openclaw-openclaw/docs/tools/acp-agents-setup.md

summary, read_when, title

summary	read_when	title
Setting up ACP agents: acpx harness config, plugin setup, permissions	Installing or configuring the acpx harness for Claude Code / Codex / Gemini CLI Enabling the plugin-tools or OpenClaw-tools MCP bridge Configuring ACP permission modes	ACP agents — setup

For the overview, operator runbook, and concepts, see ACP agents.

This page covers acpx harness config, plugin setup for the MCP bridges, and permission configuration.

Use this page only when you are setting up the ACP/acpx route. For native Codex app-server runtime config, use Codex harness. For OpenAI API keys or Codex OAuth model-provider config, use OpenAI.

Codex has two OpenClaw routes:

Route	Config/command	Setup page
Native Codex app-server	/codex ..., openai/gpt-* agent refs	Codex harness
Explicit Codex ACP adapter	/acp spawn codex, runtime: "acp", agentId: "codex"	This page

Prefer the native route unless you explicitly need ACP/acpx behavior.

acpx harness support (current)

Built-in acpx harness aliases (from the pinned acpx dependency):

Alias	Wraps
claude	Claude Code
codex	Codex CLI
copilot	GitHub Copilot CLI
cursor	Cursor CLI (cursor-agent acp)
droid	Factory Droid
fast-agent	fast-agent
gemini	Gemini CLI
iflow	iFlow CLI
kilocode	Kilocode
kimi	Kimi CLI
kiro	Kiro CLI
mux	Mux
opencode	OpenCode
openclaw	OpenClaw ACP bridge (native openclaw acp)
pi	Pi Coding Agent
qoder	Qoder CLI
qwen	Qwen Code
trae	Trae CLI

factory-droid and factorydroid also resolve to the built-in droid adapter.

When OpenClaw uses the acpx backend, prefer these values for agentId unless your acpx config defines custom agent aliases. If your local Cursor install still exposes ACP as agent acp, override the cursor agent command in your acpx config instead of changing the built-in default.

Direct acpx CLI usage can also target arbitrary adapters via --agent <command>, but that raw escape hatch is an acpx CLI feature (not the normal OpenClaw agentId path).

Model control is adapter-capability dependent. Codex ACP model refs are normalized by OpenClaw before startup. Other harnesses need ACP models plus session/set_model support; if a harness exposes neither that ACP capability nor its own startup model flag, OpenClaw/acpx cannot force a model selection.

Required config

Core ACP baseline:

{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      // Defaults are coalesceIdleMs: 350, maxChunkChars: 1800; shown explicitly here.
      coalesceIdleMs: 350,
      maxChunkChars: 1800,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

Thread binding config is channel-adapter specific. Example for Discord:

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        // Default is already true; shown explicitly here.
        spawnSessions: true,
      },
    },
  },
}

If thread-bound ACP spawn does not work, verify the adapter feature flag first:

• Discord: channels.discord.threadBindings.spawnSessions=true

Current-conversation binds do not require child-thread creation. They require an active conversation context and a channel adapter that exposes ACP conversation bindings.

See Configuration Reference.

Plugin setup for acpx backend

Packaged installs use the official @openclaw/acpx runtime plugin for ACP. Install and enable it before using ACP harness sessions:

openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true

Source checkouts can also use the local workspace plugin after pnpm install.

Start with:

/acp doctor

If you disabled acpx, denied it via plugins.allow / plugins.deny, or want to switch back to the packaged plugin, use the explicit package path:

openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true

Local workspace install during development:

openclaw plugins install ./path/to/local/acpx-plugin

Then verify backend health:

/acp doctor

acpx runtime startup probe

The acpx plugin embeds the ACP runtime directly (no separate acpx binary or version to configure). By default it registers the embedded backend during Gateway startup and waits for a startup probe before the gateway ready signal. Set OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 or OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 only for scripts or environments that intentionally keep the startup probe disabled. Run /acp doctor for an explicit on-demand probe.

Override an individual ACP agent command with structured arguments when a path or flag value should remain one argv token:

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "agents": {
            "claude": {
              "command": "node",
              "args": ["/path/to/custom adapter.mjs", "--verbose"]
            }
          }
        }
      }
    }
  }
}

• agents.<id>.command is the executable or existing command string for that ACP agent.
• agents.<id>.args is optional. Each array item is shell-quoted before OpenClaw passes it through the current acpx command-string registry.

See Plugins.

Automatic adapter download

acpx auto-downloads ACP adapters (for example the Claude and Codex ACP bridges) via npx on first use. You do not need to install adapter packages manually, and there is no separate postinstall step for OpenClaw itself. If an adapter download or spawn fails, /acp doctor reports the failure.

Plugin tools MCP bridge

By default, ACPX sessions do not expose OpenClaw plugin-registered tools to the ACP harness.

If you want ACP agents such as Codex or Claude Code to call installed OpenClaw plugin tools such as memory recall/store, enable the dedicated bridge:

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

What this does:

• Injects a built-in MCP server named openclaw-plugin-tools into ACPX session bootstrap.
• Exposes plugin tools already registered by installed and enabled OpenClaw plugins.
• Keeps the feature explicit and default-off.

Security and trust notes:

• This expands the ACP harness tool surface.
• ACP agents get access only to plugin tools already active in the gateway.
• Treat this as the same trust boundary as letting those plugins execute in OpenClaw itself.
• Review installed plugins before enabling it.

Custom mcpServers still work as before. The built-in plugin-tools bridge is an additional opt-in convenience, not a replacement for generic MCP server config.

OpenClaw tools MCP bridge

By default, ACPX sessions also do not expose built-in OpenClaw tools through MCP. Enable the separate core-tools bridge when an ACP agent needs selected built-in tools such as cron:

openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true

What this does:

• Injects a built-in MCP server named openclaw-tools into ACPX session bootstrap.
• Exposes selected built-in OpenClaw tools. The initial server exposes cron.
• Keeps core-tool exposure explicit and default-off.

Runtime operation timeout configuration

The acpx plugin gives embedded runtime startup and control operations 120 seconds by default. This gives slower harnesses such as Gemini CLI enough time to complete ACP startup and initialization. Override it if your host needs a different operation limit:

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

Runtime turns use OpenClaw agent/run timeouts, including /acp timeout. sessions_spawn does not accept per-call timeout overrides; the operator path is agents.defaults.subagents.runTimeoutSeconds. Restart the gateway after changing timeoutSeconds.

Health probe agent configuration

When /acp doctor or the startup probe checks the backend, the bundled acpx plugin probes one harness agent. If acp.allowedAgents is set, it defaults to the first allowed agent; otherwise it defaults to codex. If your deployment needs a different ACP agent for health checks, set the probe agent explicitly:

openclaw config set plugins.entries.acpx.config.probeAgent claude

Restart the gateway after changing this value.

Permission configuration

ACP sessions run non-interactively — there is no TTY to approve or deny file-write and shell-exec permission prompts. The acpx plugin provides two config keys that control how permissions are handled:

These ACPX harness permissions are separate from OpenClaw exec approvals and separate from CLI-backend vendor bypass flags such as Claude CLI --permission-mode bypassPermissions. ACPX approve-all is the harness-level break-glass switch for ACP sessions.

For the broader comparison between OpenClaw tools.exec.mode, Codex Guardian approvals, and ACPX harness permissions, see Permission modes.

permissionMode

Controls which operations the harness agent can perform without prompting.

Value	Behavior
approve-all	Auto-approve all file writes and shell commands.
approve-reads	Auto-approve reads only; writes and exec require prompts.
deny-all	Deny all permission prompts.

nonInteractivePermissions

Controls what happens when a permission prompt would be shown but no interactive TTY is available (which is always the case for ACP sessions).

Value	Behavior
fail	Abort the session with PermissionPromptUnavailableError. (default)
deny	Silently deny the permission and continue (graceful degradation).

Configuration

Set via plugin config:

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Restart the gateway after changing these values.

OpenClaw defaults to `permissionMode=approve-reads` and `nonInteractivePermissions=fail`. In non-interactive ACP sessions, any write or exec that triggers a permission prompt can fail with `PermissionPromptUnavailableError: Permission prompt unavailable in non-interactive mode`.

If you need to restrict permissions, set nonInteractivePermissions to deny so sessions degrade gracefully instead of crashing.

Related

• ACP agents — overview, operator runbook, concepts
• Sub-agents
• Multi-agent routing