ACP Agents Setup: acpx Harness, MCP Bridge, Permissions

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

This page documents acpx harness configuration, MCP bridge plugin setup, and permission settings.

Consult this page only when configuring the ACP/acpx route. For native Codex app-server runtime configuration, refer to Codex harness. For OpenAI API keys or Codex OAuth model-provider settings, see OpenAI.

Codex offers two OpenClaw routes:

Choose the native route unless ACP/acpx behavior is explicitly required.

acpx harness support (current)

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

The built-in droid adapter is also what factory-droid and factorydroid map to.

When the acpx backend is in use by OpenClaw, stick with these agentId values unless custom agent aliases are defined in your acpx config. If your local Cursor installation still presents ACP as agent acp, modify the cursor agent command within your acpx config rather than altering the built-in default.

Direct acpx CLI usage can reach arbitrary adapters through --agent <command>, though that low-level option is an acpx CLI capability, not the standard OpenClaw agentId flow.

Model control depends on what the adapter supports. OpenClaw normalizes Codex ACP model refs before startup. Other harnesses require ACP models together with session/set_model support; when a harness offers neither that ACP capability nor its own startup model flag, OpenClaw/acpx cannot enforce a model choice.

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",
    ],
    stream: {
      deliveryMode: "live",
    },
  },
}

Thread binding configuration is shared across all supported channel adapters:

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
      spawnSessions: true,
    },
  },
}

If thread-bound ACP spawning fails, start by checking the adapter feature flag:

• Discord: session.threadBindings.spawnSessions=true

Binds tied to the current conversation do not depend on creating child threads. What they need is an active conversation context plus a channel adapter that provides ACP conversation bindings.

The Configuration Reference has more details.

Plugin setup for acpx backend

For packaged installs, the official @openclaw/acpx runtime plugin is what provides ACP support. Get it installed and enabled before you try using ACP harness sessions:

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

If you are working from a source checkout, the local workspace plugin works too, after you run pnpm install.

Begin with:

/acp doctor

When acpx has been disabled, blocked through plugins.allow / plugins.deny, or you prefer to return to the packaged plugin, point to the explicit package path:

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

For development, install the local workspace plugin like this:

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

After that, confirm the backend is healthy:

/acp doctor

acpx runtime startup probe

The acpx plugin carries the ACP runtime inside itself, so there is no separate acpx binary or version to manage. On Gateway startup it registers the embedded backend by default and holds off until a startup probe succeeds before the gateway sends the ready signal. Only set OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 or OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 for scripts or environments that deliberately leave the startup probe off. To trigger a probe manually, run /acp doctor.

To keep a path or flag value as a single argv token, override an individual ACP agent command with structured arguments:

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

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

See Plugins.

Automatic adapter download

On first use, acpx fetches ACP adapters automatically (the Claude and Codex ACP bridges are examples) through npx. There is no need to install adapter packages by hand, and OpenClaw itself has no separate postinstall step. If an adapter download or spawn goes wrong, /acp doctor reports the failure.

Plugin tools MCP bridge

Out of the box, ACPX sessions do not make OpenClaw plugin-registered tools visible to the ACP harness.

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

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

Here is what it does:

• Adds a built-in MCP server named openclaw-plugin-tools to the ACPX session bootstrap.
• Surfaces plugin tools that installed and enabled OpenClaw plugins have already registered.
• Hands the active ACP session identity to plugin tool factories, keeping agent-scoped tools inside that agent's namespace.
• Stays explicit and off unless you enable it.

Trust and security considerations:

• The ACP harness tool surface grows when this is on.
• ACP agents can only reach plugin tools that are already active in the gateway.
• Treat this as the same trust boundary as letting those plugins run inside OpenClaw itself.
• Review your installed plugins before switching it on.

Custom mcpServers behave exactly as they did before. The built-in plugin-tools bridge is an extra opt-in convenience, not a substitute for generic MCP server configuration.

OpenClaw tools MCP bridge

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

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

Here is what it does:

• Adds a built-in MCP server named openclaw-tools to the ACPX session bootstrap.
• Exposes chosen built-in OpenClaw tools. The initial server exposes cron.
• Keeps core-tool exposure explicit and off by default.

Runtime operation timeout configuration

The acpx plugin grants embedded runtime startup and control operations 120 seconds by default. That gives slower harnesses like Gemini CLI enough time to finish ACP startup and initialization. If your host needs a different operation limit, override it:

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

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

Health probe agent configuration

When /acp doctor or the startup probe checks the backend, the bundled acpx plugin probes a single harness agent. With acp.allowedAgents set, it falls back to the first allowed agent; otherwise it falls back to codex. To use 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, meaning there is no TTY to approve or deny file-write and shell-exec permission prompts. The acpx plugin offers two config keys that dictate how permissions are handled:

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

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

permissionMode

Determines which operations the harness agent can perform without prompting.

nonInteractivePermissions

Controls the behavior when a permission prompt would appear but no interactive TTY exists, which is always true for ACP sessions.

Configuration

Configured through plugin settings:

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

After modifying these values, restart the gateway.

Warning

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

To restrict permissions, set nonInteractivePermissions to deny so sessions degrade gracefully rather than crash.

Related

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