DEV Community

Hex
Hex

Posted on • Originally published at openclawplaybook.ai

OpenClaw ACP Agents: Turn Any Chat Thread into a Coding Workspace

#ai #agents #automation #productivity

Imagine this: you're in your Slack DM with your AI agent. You type "Build me a REST endpoint for this feature" and instead of getting a vague reply, a full Claude Code session spins up right there in the thread — reading your codebase, writing files, running tests. When it's done, it reports back. You never left Slack.

That's not a hypothetical. That's ACP in OpenClaw, and it's one of the most powerful things the platform does.

What ACP Actually Is

ACP stands for Agent Client Protocol. It's the bridge that lets OpenClaw spawn and control external coding harnesses — the AI tools you already know and use — from inside any chat interface.

Where OpenClaw's native sub-agents handle delegation within OpenClaw itself, ACP reaches outside to tools like:

  • Claude Code — Anthropic's terminal coding agent
  • Codex — OpenAI's CLI coding agent
  • Gemini CLI — Google's terminal AI
  • Cursor, Copilot, Kiro, OpenCode, Pi, Qwen — and more

The key distinction: ACP = external harness runtime. Sub-agents = OpenClaw-native delegation. They're complementary, not competing.

ACP is powered by the acpx plugin. Once it's installed and configured, you can spawn coding sessions from any chat channel OpenClaw is connected to — Slack, Discord, Telegram, iMessage, wherever.

Quick Start: Your First ACP Session

Before anything else, install the plugin:

openclaw plugins install acpx
Enter fullscreen mode Exit fullscreen mode

Then enable it in your OpenClaw config. The minimum required config looks like this:

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "claude",
    "allowedAgents": ["claude", "codex", "gemini"]
  }
}
Enter fullscreen mode Exit fullscreen mode

The built-in harness aliases cover most tools you'd want: claude, codex, copilot, cursor, droid, gemini, iflow, kilocode, kimi, kiro, openclaw, opencode, pi, qwen. Use those aliases in allowedAgents.

Now spawn a session. There are two ways:

Via the /acp command:

/acp spawn --agent codex "Refactor the auth module to use JWT"
Enter fullscreen mode Exit fullscreen mode

Via natural language (OpenClaw routes it automatically):

Run this in Codex: refactor the auth module to use JWT
Start Claude Code and fix the failing tests in /src/api
Enter fullscreen mode Exit fullscreen mode

OpenClaw understands both. If you've set a defaultAgent, you don't even need to specify which harness — just say "run this" and it picks your default.

There are two session modes:

  • run — one-shot. Task runs, finishes, done. Great for isolated jobs.
  • session — persistent. The coding agent stays alive across messages. Requires thread binding (next section).

For quick one-off tasks, run mode is all you need. For ongoing feature work where context matters, you want a persistent session.

Thread-Bound Sessions: Persistent Coding in Chat

This is where ACP gets genuinely interesting. You can bind a persistent coding session to a specific chat thread — so every message in that thread goes directly to the agent, and it replies back in the same thread.

To spawn a thread-bound session:

/acp spawn --agent claude --thread auto "Start working on the payment integration"
Enter fullscreen mode Exit fullscreen mode

The --thread flag accepts three values:

  • auto — creates a new thread and binds the session to it
  • here — binds to the current thread you're in
  • off — no thread binding (default)

You can also use --bind here to pin an ACP session to your current conversation without spawning a new thread. This is useful in DMs — the whole conversation becomes the coding workspace.

For Discord specifically, thread binding requires two config flags:

{
  "session": {
    "threadBindings": {
      "enabled": true
    }
  },
  "channels": {
    "discord": {
      "threadBindings": {
        "spawnAcpSessions": true
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Once bound, the session stays alive. You can come back hours later, send a follow-up message in that thread, and Claude Code (or whichever agent) picks right up where it left off — with full context.

Configuration Deep Dive

Here's a more complete config showing everything you can tune:

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "claude",
    "allowedAgents": ["claude", "codex", "gemini", "opencode"],
    "permissionMode": "approve-reads",
    "nonInteractivePermissions": "deny",
    "timeout": 600
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "runtime": {
          "acp": {
            "permissionMode": "approve-all",
            "timeout": 900,
            "cwd": "/Users/rahul/development/my-project"
          }
        }
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Breaking it down:

  • permissionMode — controls what the coding agent can do without asking. Options: approve-all (ask for everything), approve-reads (auto-allow reads, ask for writes), deny-all (block everything)
  • nonInteractivePermissions — what happens when the agent needs approval but there's no human around. fail stops the task; deny silently blocks the action and continues
  • timeout — max seconds before a session is killed automatically
  • cwd — working directory for the coding agent
  • Per-agent defaults via agents.list[].runtime.acp.* let you set different configs per OpenClaw agent identity

Runtime options can also be passed inline at spawn time:

/acp spawn --agent codex --model gpt-4o --timeout 300 --cwd /my-project "Fix the broken tests"
Enter fullscreen mode Exit fullscreen mode

ACP vs Sub-Agents: When to Use Which

This comes up constantly, so let's be direct about it.

Use ACP when:

  • You need a full coding environment — file reads, writes, terminal commands, test runs
  • You want a specific external tool (Claude Code's capabilities vs Codex's vs Gemini's are genuinely different)
  • The task is long-running and benefits from a persistent, thread-bound workspace
  • You're doing real software development work

Use sub-agents when:

  • You need OpenClaw-native delegation — spawning parallel tasks, orchestrating workflows
  • The work doesn't require a full coding harness (research, writing, API calls)
  • You need tight integration with OpenClaw's own tools (message sending, canvas, browser)
  • Latency matters — sub-agents start faster than full ACP sessions

They can work together too. A sub-agent can spawn an ACP session. OpenClaw's multi-agent orchestration supports this natively — one agent coordinates, another codes.

Permission Management for Non-Interactive Sessions

When you're using ACP in automated contexts — cron jobs, heartbeats, unattended workflows — permission management becomes critical. A coding agent that blocks waiting for approval in the middle of the night is useless.

The nonInteractivePermissions setting handles exactly this:

{
  "acp": {
    "permissionMode": "approve-reads",
    "nonInteractivePermissions": "deny"
  }
}
Enter fullscreen mode Exit fullscreen mode

With deny, any action that would normally require approval is silently blocked. The agent continues with what it can do. With fail, the entire session stops at the first blocked action.

For unattended automation, deny is usually the right choice — it keeps things moving without giving the agent unchecked write access. For sensitive codebases, consider approve-all with fail so nothing sneaks through.

Pro Tips

Resume a Previous Session

ACP sessions have IDs. If a session ended before completing its work, you can resume it:

/acp spawn --agent claude --resume <session-id> "Continue where you left off"
Enter fullscreen mode Exit fullscreen mode

Or via sessions_spawn in the API with resumeSessionId. The agent reloads its conversation history and picks up from the last state.

Stream Progress to the Parent Session

By default, ACP sessions run independently. But if you want live progress in your main chat, use streamTo: "parent" in the spawn config. Updates stream back as the agent works — useful for long builds where you want visibility without waiting.

Steer a Running Session

Changed your mind mid-task? The /acp steer command sends a new instruction to an active session without stopping it:

/acp steer <session-id> "Actually, use PostgreSQL instead of SQLite"
Enter fullscreen mode Exit fullscreen mode

Check What's Running 

/acp sessions    # List all active ACP sessions
/acp status <id> # Status of a specific session
/acp cancel <id> # Stop a session
Enter fullscreen mode Exit fullscreen mode

Diagnose Setup Issues

If something isn't working, run:

/acp doctor
Enter fullscreen mode Exit fullscreen mode

It checks your acpx plugin installation, config validity, available harnesses, and connectivity. Start here before digging into logs.

Full /acp Command Reference

The complete command family: spawn, cancel, steer, close, status, model, permissions, timeout, cwd, sessions, doctor, install. Each has its own flags — use /acp <command> --help for details.

The Bigger Picture

ACP isn't just a convenience feature. It's a fundamental shift in how you interact with coding tools.

Instead of switching between chat and terminal, between your agent and your IDE, between coordination and execution — ACP collapses those contexts. Your Slack DM, your Discord server, your Telegram chat: any of them can become a full coding workspace, with a persistent AI coder that knows the project, remembers the context, and keeps working even when you're not watching.

For teams using OpenClaw across channels, this means your whole organization's communication surface becomes a development platform. Someone reports a bug in Slack? Spawn Claude Code in a thread, fix it, report back — without anyone leaving the conversation.

That's the version of AI-assisted development that actually saves time.

Originally published at openclawplaybook.ai. Get The OpenClaw Playbook — $9.99

Top comments (0)