ACP agents — setup

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

The sections below cover 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:

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

acpx harness support (current)

Current acpx built-in harness aliases:

• text

  Copy

  claude
• text

  Copy

  codex
• text

  Copy

  copilot
• text

  Copy

  cursor
  (Cursor CLI:
  text

  Copy

  cursor-agent acp
  )
• text

  Copy

  droid
• text

  Copy

  gemini
• text

  Copy

  iflow
• text

  Copy

  kilocode
• text

  Copy

  kimi
• text

  Copy

  kiro
• text

  Copy

  openclaw
• text

  Copy

  opencode
• text

  Copy

  pi
• text

  Copy

  qwen

When OpenClaw uses the acpx backend, prefer these values for

unless your acpx config defines custom agent aliases. If your local Cursor install still exposes ACP as , override the agent command in your acpx config instead of changing the built-in default.

Direct acpx CLI usage can also target arbitrary adapters via

, but that raw escape hatch is an acpx CLI feature (not the normal OpenClaw path).

Model control is adapter-capability dependent. Codex ACP model refs are normalized by OpenClaw before startup. Other harnesses need ACP

plus 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:

json5
Copy
{
  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",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

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

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

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

• Discord:
  text

  Copy

  channels.discord.threadBindings.spawnAcpSessions=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

Fresh installs ship the bundled

runtime plugin enabled by default, so ACP usually works without a manual plugin install step.

Start with:

text
Copy
/acp doctor

If you disabled

, denied it via / , or want to switch to a local development checkout, use the explicit plugin path:

bash
Copy
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

Local workspace install during development:

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

Then verify backend health:

text
Copy
/acp doctor

acpx command and version configuration

By default, the bundled

plugin registers the embedded ACP backend without spawning an ACP agent during Gateway startup. Run for an explicit live probe. Set only when you need the Gateway to probe the configured agent at startup.

Override the command or version in plugin config:

json
Copy
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}

• text

  Copy

  command
  accepts an absolute path, relative path (resolved from the OpenClaw workspace), or command name.
• text

  Copy

  expectedVersion: "any"
  disables strict version matching.
• Custom
  text

  Copy

  command
  paths disable plugin-local auto-install.

See Plugins.

Automatic dependency install

When you install OpenClaw globally with

, the acpx runtime dependencies (platform-specific binaries) are installed automatically via a postinstall hook. If the automatic install fails, the gateway still starts normally and reports the missing dependency through .

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:

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

What this does:

• Injects a built-in MCP server named
  text

  Copy

  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

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

:

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

What this does:

• Injects a built-in MCP server named
  text

  Copy

  openclaw-tools
  into ACPX session bootstrap.
• Exposes selected built-in OpenClaw tools. The initial server exposes
  text

  Copy

  cron
  .
• Keeps core-tool exposure explicit and default-off.

Runtime timeout configuration

The bundled

plugin defaults embedded runtime turns to a 120-second timeout. This gives slower harnesses such as Gemini CLI enough time to complete ACP startup and initialization. Override it if your host needs a different runtime limit:

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

Restart the gateway after changing this value.

Health probe agent configuration

When

or the opt-in startup probe checks the backend, the bundled plugin probes one harness agent. If is set, it defaults to the first allowed agent; otherwise it defaults to . If your deployment needs a different ACP agent for health checks, set the probe agent explicitly:

bash
Copy
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

. ACPX is the harness-level break-glass switch for ACP sessions.

text

Copy

permissionMode

Controls which operations the harness agent can perform without prompting.

text

Copy

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).

Configuration

Set via plugin config:

bash
Copy
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.