Unified Management of 10+ Coding Agents on Messaging Platforms via OpenClaw ACP

Why a unified protocol is needed

When using AI coding tools, developers often face three problems: Codex works only in VS Code, prompting agents in Discord requires re‑explaining project context each time, and each agent has its own integration protocol, making onboarding costly. The root cause is the lack of a standard communication layer between coding agents and editors/platforms.

Agent Client Protocol (ACP)

ACP is a JSON‑RPC 2.0‑based protocol that standardizes the interaction between a client (editor or platform such as OpenClaw) and an AI coding agent (e.g., Codex, Claude Code, Gemini CLI). It is analogous to the Language Server Protocol: where LSP standardizes language server integration, ACP standardizes agent‑client communication.

Core benefits :

Decoupling : agents and editors can evolve independently.

Ecosystem interoperability : any ACP‑compatible agent works in any ACP‑compatible client.

Innovation freedom : developers can mix and match the best tools.

Protocol features :

Based on the JSON‑RPC 2.0 specification.

Supports local stdio and remote http/websocket transports (the latter is under development).

Default user‑readable format is Markdown.

Reuses the JSON representation from MCP (Model Context Protocol).

Client‑Agent architecture

The architecture follows a client‑agent model. The client is typically an editor or platform (e.g., OpenClaw); the agent is a coding agent such as Codex or Claude Code.

Methods offered by the client

fs/*

: file system operations (read/write). terminal/*: terminal management (create, output, terminate). request_permission: permission requests.

Methods offered by the agent

initialize

: establish a connection. session/new: create a new session. session/prompt: send a user message. session/load: restore an existing session. session/set_mode: switch operation mode.

Agent notifications

session/update

: progress updates. session/cancel: cancel an operation.

Prompt‑turn flow

Client → Agent: session/prompt (send user message).

Agent → Client: session/update (progress notification).

Agent → Client: optional file or permission request.

Client → Agent: permission approval or denial.

Agent → Client: session/prompt response with stopReason.

OpenClaw acpx plugin

The acpx plugin implements the ACP protocol for OpenClaw. It is written in TypeScript and the GitHub repository has over 992 stars.

Supported agents

codex – codex‑acp – uses the Codex CLI.

claude – claude‑agent‑acp – uses Claude Code.

gemini – native support – uses Gemini CLI.

cursor – native support – uses Cursor CLI.

copilot – native support – uses GitHub Copilot CLI.

pi – pi‑acp – uses Pi coding agent.

openclaw – native support – uses OpenClaw ACP bridge.

droid – native support – uses factory droid.

kimi – native support – uses Kimi CLI.

opencode – invoked via npx – uses opencode.

qwen – native support – uses Qwen code.

Session management

Session keys follow the pattern:

ACP session: agent:<agentId>:acp:<uuid> Sub‑agent session: agent:<agentId>:subagent:<uuid> Thread binding allows a client thread to be bound to a specific ACP session so that subsequent messages on that thread are automatically routed to the bound session. Bindings are removed when the thread is unfocused, closed, archived, idle‑timed‑out, or reaches its maximum lifetime.

Supported channels

Discord – thread/channel.

Telegram – topics (group/super‑group forums or direct messages).

Permission control

Two configuration keys govern permission handling.

permissionMode (runtime approval) approve-all: automatically approve all file writes and shell commands. approve-reads: automatically approve reads only; writes and executions require prompts. deny-all: deny all permission prompts.

nonInteractivePermissions (non‑interactive mode) fail (default): abort the session with AcpRuntimeError. deny: silently deny the permission and continue (graceful degradation).

Prompt queue

Each ACP session maintains an independent prompt queue.

The active acpx process owns the queue.

Other callers submit prompts via local IPC.

Unix systems use a Unix socket at ~/.acpx/queues/<hash>.sock; Windows uses a named pipe.

The queue owner uses an idle TTL (default 300 s).

Getting started

Installation

# Install the plugin
openclaw plugins install acpx
# Enable the plugin
openclaw config set plugins.entries.acpx.enabled true
# Verify backend health
/acp doctor

Core configuration

{
  "acp": {
    "enabled": true,
    "dispatch": { "enabled": true },
    "backend": "acpx",
    "defaultAgent": "codex",
    "allowedAgents": ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    "maxConcurrentSessions": 8,
    "stream": {
      "coalesceIdleMs": 300,
      "maxChunkChars": 1200
    },
    "runtime": {
      "ttlMinutes": 120
    }
  }
}

Discord thread‑binding configuration

{
  "session": {
    "threadBindings": {
      "enabled": true,
      "idleHours": 24,
      "maxAgeHours": 0
    }
  },
  "channels": {
    "discord": {
      "threadBindings": {
        "enabled": true,
        "spawnAcpSessions": true
      }
    }
  }
}

Common /acp commands

/acp spawn

– create an ACP session (e.g., /acp spawn codex --mode persistent --thread auto). /acp cancel – cancel the current turn (e.g., /acp cancel agent:codex:acp:…). /acp steer – send a steering instruction (e.g., /acp steer prioritize failing tests). /acp close – close a session. /acp status – display runtime status. /acp set-mode – set runtime mode (e.g., /acp set-mode plan). /acp set – generic configuration write (e.g., /acp set model openai/gpt-5.2). /acp cwd – set working directory. /acp permissions – set approval strategy (e.g., /acp permissions strict). /acp timeout – set timeout (e.g., /acp timeout 120). /acp model – override model (e.g., /acp model anthropic/claude-opus-4-5). /acp sessions – list recent sessions. /acp doctor – health check of the backend.

ACP vs. sub‑agent

OpenClaw offers two runtimes: ACP (external tool execution) and sub‑agent (native OpenClaw sandbox). Choose based on needs:

Use ACP when you need external tools such as Codex, Claude Code, or Gemini CLI.

Use sub‑agent when you require OpenClaw’s native sandbox or delegated execution.

Practical use cases

Case 1 – PR code review

# Review a PR in a dedicated session
acpx --cwd ~/repos/shop --approve-all codex -s pr-842 \
  'review PR #842 for regressions and propose a minimal fix'
# Continue reviewing the same PR
acpx --cwd ~/repos/shop codex -s pr-842 \
  'now draft commit message and rollout checklist'

Case 2 – Parallel workflows

# Create named sessions
acpx codex sessions new --name backend
acpx codex sessions new --name docs
# Run tasks in parallel
acpx codex -s backend 'fix checkout timeout'
acpx codex -s docs 'document payment retry behavior'

Case 3 – Permission strategy selection

# Full approval (automation)
acpx --approve-all codex 'apply this patch and run tests'
# Read‑only approval (investigation, default)
acpx --approve-reads codex 'inspect repo structure and suggest plan'
# Full denial (security)
acpx --deny-all codex 'explain what you can do without tool access'

Case 4 – Prompt from stdin or file

# From stdin
echo 'triage failing tests' | acpx codex
# From a file
acpx codex --file prompt.md
# Stdin with extra args
acpx codex --file - 'also check lint warnings'

Case 5 – JSON automation

# Filter tool calls with jq
acpx --format json codex exec 'review changed files' \
  | jq -r 'select(.type=="tool_call") | [.status, .title] | @tsv'

Troubleshooting

Symptom: "ACP runtime backend is not configured" – Cause: missing or disabled backend plugin – Fix: install and enable the plugin, then run /acp doctor.

Symptom: "ACP is disabled by policy" – Cause: global ACP disabled – Fix: set acp.enabled=true in the config.

Symptom: "ACP agent "…" is not allowed" – Cause: agent not in acp.allowedAgents – Fix: add the agent to the allowed list.

Symptom: "Unable to resolve session target" – Cause: incorrect session key – Fix: run /acp sessions to obtain the correct key.

Symptom: "Thread bindings are unavailable" – Cause: adapter does not support thread bindings – Fix: use --thread off or switch channel.

Symptom: "Sandboxed sessions cannot spawn ACP" – Cause: sandbox restrictions – Fix: use runtime="subagent" or run from a non‑sandboxed session.

Symptom: "ACP session fails early" – Cause: permission blocked – Fix: set permissionMode=approve-all.

Smoke test for operators

Verify the deployed gateway version.

Confirm the deployment includes ACP support.

Run a temporary session with sessions_spawn using runtime "acp", agentId "codex", mode "run" and task "reply with exactly LIVE‑acp‑spawn‑ok".

Check that the agent reports accepted=yes and returns a valid child session key.

Conclusion

OpenClaw ACP agents, via the acpx plugin, expose the ACP protocol to messaging platforms, enabling direct control of more than ten coding agents (Codex, Claude Code, Gemini CLI, etc.) from Discord or Telegram. Core features include cross‑platform session persistence through thread binding, flexible permission modes, and ordered concurrent prompt handling. Choose ACP when external tool execution is required, sub‑agent when sandbox isolation is needed, and thread binding when collaborative, cross‑device workflows are desired.