OpenClaw with Codex: Complete Coding Agent Setup Guide (2026)

What Is ACP and Why Does It Matter?

The Agent Client Protocol (ACP) is how OpenClaw communicates with external coding harnesses. Think of it as a universal adapter: OpenClaw speaks to you through Telegram, Discord, or WhatsApp, and speaks to coding agents through ACP. The coding agent does the actual work — reading files, writing code, running tests — while OpenClaw handles the conversation, context, and delivery.

Before ACP existed, people used the built-in coding-agent skill, which spawned Codex or Claude Code as background processes via PTY sessions. That still works and is useful for quick one-off tasks. But ACP adds critical capabilities:

Here's the key distinction between the two approaches: The Coding-Agent Skill (PTY) has low setup complexity — just install the CLI. However, it offers no session persistence (dies with process), no thread binding, no resume capability, and requires manual management for parallel agents. It's best for quick one-shot tasks. ACP Sessions have medium setup complexity (needs ACP config) but offer full session persistence that survives restarts, thread binding for Discord and Telegram, session resume via resumeSessionId, built-in multi-agent orchestration, and are best for ongoing projects and team workflows.

For most developers, you'll want both: the skill for quick "fix this one file" tasks and ACP for anything that takes more than a few minutes.

• Persistent sessions that survive restarts and can be resumed days later
• Thread binding so a Discord thread or Telegram topic becomes a dedicated workspace for one coding agent
• Multi-agent orchestration where different agents work on different parts of a codebase simultaneously
• Session handoff — start on your laptop, continue on your phone via Telegram
• Structured streaming with progress updates delivered back to your chat

Supported Coding Agents

OpenClaw works with every major coding CLI through ACP. Codex (CLI: codex, default model: gpt-5.2-codex, requires PTY) is best for full-auto coding and PR reviews. Claude Code (CLI: claude, default model: claude-sonnet-4, no PTY needed with --print mode) excels at complex reasoning and large refactors. Gemini CLI (CLI: gemini, default model: gemini-2.5-pro, requires PTY) shines for long-context analysis and documentation. OpenCode (CLI: opencode, configurable model, requires PTY) offers multi-model flexibility. Pi (CLI: pi, configurable model, requires PTY) is ideal for lightweight tasks and fast iteration.

Each has different strengths. Codex excels at autonomous coding with its --full-auto sandbox mode. Claude Code handles complex multi-file refactors better than anything else. Gemini CLI shines when you need to analyze an entire repository's worth of context. You can configure all of them and switch between agents per task.

Prerequisites

Before setting up coding agents, you need:

• A running OpenClaw instance — either self-hosted on a VPS or via DoneClaw's managed service
• Node.js 20+ installed on your server
• API keys for the models you want to use: OpenAI API key (for Codex), Anthropic API key (for Claude Code), Google AI API key (for Gemini CLI)
• Git installed and configured (Codex requires a git repository)
• At least 2GB RAM free on your server (4GB recommended for parallel agents)

Step 1: Install the Coding Agent CLIs

SSH into your OpenClaw server and install the agents you want to use.

First, install the Codex CLI:

Next, install Claude Code:

Then install acpx — the ACP bridge that connects OpenClaw to the coding agents:

Optionally, install additional agents:

npm install -g @openai/codex

# Verify installation
codex --version

# Configure your API key
export OPENAI_API_KEY="sk-your-key-here"

# Or add to ~/.codex/config.toml for persistence
mkdir -p ~/.codex
cat > ~/.codex/config.toml << 'EOF'
model = "gpt-5.2-codex"
approval_mode = "full-auto"

[providers.openai]
api_key_env = "OPENAI_API_KEY"
EOF

npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

# Set up authentication
claude setup-token
# Follow the prompts to enter your Anthropic API key

npm install -g @openclaw/acpx

# Verify
acpx --version

# Test the connection with a simple session
acpx codex 'echo hello world'

# Gemini CLI
npm install -g @google/gemini-cli

# OpenCode
npm install -g @mariozechner/opencode

# Pi coding agent
npm install -g @mariozechner/pi-coding-agent

Step 2: Configure ACP in OpenClaw

Now tell OpenClaw about your coding agents. Edit your openclaw.json configuration to enable ACP globally, define your coding agents, and set up the allowed agents list:

After editing, restart the gateway with openclaw gateway restart.

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "codex",
    "dispatch": {
      "enabled": true
    },
    "allowedAgents": ["codex", "claude", "gemini"]
  },
  "agents": {
    "list": [
      {
        "id": "codex",
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "codex",
            "backend": "acpx",
            "mode": "persistent",
            "cwd": "/workspace/projects"
          }
        }
      },
      {
        "id": "claude",
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "claude",
            "backend": "acpx",
            "mode": "persistent"
          }
        }
      },
      {
        "id": "gemini",
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "gemini",
            "backend": "acpx",
            "mode": "persistent"
          }
        }
      }
    ]
  }
}

Step 3: Enable Thread Bindings (Optional but Recommended)

Thread bindings let you dedicate a Discord thread or Telegram topic to a specific coding agent. This is the killer feature — every message in that thread goes straight to the agent, and all responses come back there.

For Telegram, enable thread bindings in your channel config:

For Discord, enable thread bindings and configure your guild and channel settings:

You can also set up permanent channel bindings for a dedicated coding channel that always routes to Codex:

{
  "channels": {
    "telegram": {
      "threadBindings": {
        "spawnAcpSessions": true
      }
    }
  }
}

{
  "channels": {
    "discord": {
      "threadBindings": {
        "spawnAcpSessions": true
      },
      "guilds": {
        "YOUR_GUILD_ID": {
          "channels": {
            "YOUR_CHANNEL_ID": {
              "requireMention": false
            }
          }
        }
      }
    }
  }
}

{
  "bindings": [
    {
      "type": "acp",
      "agentId": "codex",
      "match": {
        "channel": "discord",
        "accountId": "default",
        "peer": { "kind": "channel", "id": "YOUR_CHANNEL_ID" }
      },
      "acp": {
        "label": "codex-main",
        "cwd": "/workspace/my-project"
      }
    }
  ]
}

Step 4: Your First Coding Task

Let's test everything. Send a message to your OpenClaw agent: "Start a Codex session and create a simple Express.js API with health check and user CRUD endpoints."

Behind the scenes, OpenClaw recognizes this as a coding task, spawns an ACP session with the codex agent, creates a thread (if enabled) for the conversation, sends the task to Codex via acpx, and streams progress updates back to your chat.

You can also be explicit with the /acp spawn command, or use the sessions_spawn tool directly from your agent configuration:

{
  "task": "Create an Express.js API with health check and user CRUD endpoints",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

Real-World Coding Workflows

Workflow 1: Automated PR Reviews — Set up a cron job that reviews new PRs every hour. The schedule runs an agent turn that checks for open PRs and spawns a Codex agent to review each one:

Workflow 2: Bug Fix Pipeline — When someone reports a bug in your Telegram group, handle it with a single message: "Fix bug #234: users can't reset their password when they have 2FA enabled. Check the auth module, write a fix, add tests, and open a PR." OpenClaw will spawn a Codex session, have it read the issue, explore the codebase, write the fix, run existing tests, commit and push to a new branch, open a PR via gh pr create, and report back with the PR link.

Workflow 3: Parallel Issue Resolution with Git Worktrees — For tackling multiple issues simultaneously, tell OpenClaw: "Fix issues #78 and #99 in parallel. Use git worktrees so they don't conflict. Create separate PRs for each." The agent creates isolated worktrees and launches separate Codex instances in each.

Workflow 4: Code Review from Your Phone — You're on the train and a PR comes in. From Telegram: "Review PR #130 on myrepo. Focus on security issues and performance." OpenClaw clones the repo to a temp directory, checks out the PR, and has Codex review it — all from your phone. The review lands in your chat within minutes.

{
  "schedule": { "kind": "cron", "expr": "0 * * * *", "tz": "America/New_York" },
  "payload": {
    "kind": "agentTurn",
    "message": "Check for new open PRs on github.com/myorg/myrepo. For each unreviewed PR, spawn a Codex agent to review it. Post the review as a PR comment.",
    "timeoutSeconds": 600
  },
  "sessionTarget": "isolated",
  "delivery": { "mode": "announce" }
}

# What happens behind the scenes:
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# Codex instance 1 (background + PTY)
codex --yolo 'Fix issue #78: <description>. Commit and push.'
# Codex instance 2 (background + PTY)
codex --yolo 'Fix issue #99: <description>. Commit and push.'

Using the Coding-Agent Skill (Quick Tasks)

For simple, one-off coding tasks where you don't need persistent sessions, the built-in coding-agent skill is faster to use. It spawns agents as background processes.

Codex Quick Tasks — use one-shot execution for new projects, full-auto mode for existing ones, or YOLO mode for maximum speed (no sandbox, no approvals):

Claude Code Quick Tasks — Claude Code uses --print mode (no PTY needed). Important: Don't use --dangerously-skip-permissions with PTY for Claude Code — it can exit after the confirmation dialog. Always use --permission-mode bypassPermissions --print instead.

Key differences between Codex and Claude Code execution: Codex requires PTY and a git repo, uses --full-auto for sandboxed mode, --yolo for fastest mode, and exec --full-auto for best auto mode. Claude Code doesn't need PTY (use --print) or a git repo, uses --permission-mode bypassPermissions for sandboxed mode, --print with bypass for fastest mode.

# One-shot execution (needs a git repo)
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init
codex exec "Build a dark mode toggle component"

# Full-auto mode in an existing project
codex exec --full-auto 'Add error handling to all API calls'

# YOLO mode (no sandbox, no approvals — fastest but riskiest)
codex --yolo 'Refactor the auth module to use JWT'

# Foreground execution
cd ~/project && claude --permission-mode bypassPermissions --print 'Your task'

# Background execution
claude --permission-mode bypassPermissions --print 'Refactor the database layer' &

Advanced Configuration

Model Selection Per Agent — Override the default model for specific agents by creating multiple agent configurations with different IDs. Then target specific agents in your messages: "Use claude-deep for this complex refactor" or "Quick fix with codex-fast."

Resume Sessions — One of ACP's most powerful features. Pick up where you left off by passing a resumeSessionId. This replays the conversation history so the agent has full context. Perfect for long refactors that span multiple days, handing off from laptop to phone, or resuming after a server restart.

Stream Progress to Parent Session — Get real-time updates in your chat by setting streamTo to parent. This sends progress summaries back to your chat as the agent works, so you can monitor long-running tasks without polling.

{
  "agents": {
    "list": [
      {
        "id": "codex-fast",
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "codex",
            "backend": "acpx",
            "mode": "persistent"
          }
        }
      },
      {
        "id": "claude-deep",
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "claude",
            "backend": "acpx",
            "mode": "persistent"
          }
        }
      }
    ]
  }
}

{
  "task": "Continue fixing the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

{
  "task": "Refactor the entire auth module",
  "runtime": "acp",
  "agentId": "codex",
  "streamTo": "parent"
}

Cost Management for Coding Agents

Coding agents can burn through API credits fast. Here's how to keep costs under control.

Token usage varies by task type: A simple bug fix uses 5K-15K tokens ($0.02-$0.06 with GPT-5.2, $0.02-$0.05 with Claude Sonnet). Feature implementation uses 20K-80K tokens ($0.08-$0.32 / $0.06-$0.24). PR reviews use 10K-40K tokens ($0.04-$0.16 / $0.03-$0.12). Large refactors use 50K-200K tokens ($0.20-$0.80 / $0.15-$0.60). Full codebase analysis uses 100K-500K tokens ($0.40-$2.00 / $0.30-$1.50).

• Use the right agent for the job: Codex for straightforward implementations, Claude Code for complex reasoning. Don't use Opus-level models for simple fixes.
• Set timeouts to prevent runaway sessions: {"task": "...", "runtime": "acp", "runTimeoutSeconds": 300}
• Use one-shot mode for quick tasks: mode "run" instead of "session" when you don't need persistence.
• Batch related changes: Instead of five separate "fix this file" tasks, send one "fix all linting issues in src/auth/" task.
• Use free models for simple tasks: Route simple code reviews to Gemini Flash or local models via Ollama.

Troubleshooting Common Issues

"Codex refuses to run — not a git repository" — Codex requires a trusted git directory. For new projects, run cd /your/project && git init. For scratch work, create a temp directory with git init first.

"Claude Code exits immediately with --dangerously-skip-permissions" — Don't use PTY mode with --dangerously-skip-permissions. Use claude --permission-mode bypassPermissions --print 'your task' instead.

"ACP session not found" or "Agent not responding" — Check that acpx is installed (acpx --version), verify ACP is enabled in config, check the agent is in the allowed list, restart the gateway, and test acpx directly.

"Thread binding not working" — Ensure thread bindings are enabled for your channel. For Telegram, thread bindings only work in forum-enabled groups (supergroups with topics) and DM topics.

"Agent modifies wrong files" or "Works in wrong directory" — Always set cwd explicitly in your ACP session config. Without cwd, the agent uses its default working directory, which might not be your project folder.

"Session timeout — agent killed mid-task" — Increase the timeout for complex tasks by setting runTimeoutSeconds to a higher value (e.g., 1800 for large refactors). The default timeout may be too short for complex work.

# For new projects
cd /your/project && git init

# For scratch work
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "your prompt"

claude --permission-mode bypassPermissions --print 'your task'

Security Considerations

Running coding agents on your server means giving AI write access to your codebase. Take these precautions:

• Never run coding agents in OpenClaw's own directory — the agent could modify its own configuration. Always use a separate project directory.
• Use --full-auto over --yolo — Full-auto mode sandboxes file operations within the workspace. YOLO mode has no restrictions.
• Set explicit cwd paths — Don't let agents wander into sensitive directories.
• Review PR diffs before merging — Coding agents are good but not infallible. Always review what they produce.
• Use git worktrees for isolation — When running multiple agents, worktrees prevent them from stepping on each other's changes.
• Limit API key scopes — Use project-specific API keys where possible, not your admin keys.

DoneClaw: Coding Agents Without the Setup

If the configuration above looks like a lot of work, DoneClaw includes pre-configured coding agent support out of the box. Your managed instance comes with everything ready to go. Just message your DoneClaw agent: "Start a Codex session for my project" and it works. No SSH, no config files, no dependency management.

• Codex and Claude Code pre-installed and configured
• ACP enabled with sensible defaults
• Thread bindings ready for Telegram and Discord
• Sandboxed execution environment so coding agents can't break your instance
• Automatic updates when new coding agent versions drop

Conclusion

The combination of OpenClaw's persistent agent framework with dedicated coding CLIs like Codex and Claude Code is one of the most powerful developer productivity setups available in 2026. Once you experience delegating coding tasks from your phone and getting back working PRs, you'll wonder how you ever coded any other way. Now that you have coding agents running through OpenClaw, explore related guides on building custom DoneClaw skills, setting up cron jobs and heartbeats for automated coding tasks, building API integrations that trigger coding workflows, and choosing the right model for each coding task.

Frequently asked questions