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 Apus routes:

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

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

When Apus 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 Apus agentId path).

Model control is adapter-capability dependent. Codex ACP model refs are normalized by Apus before startup. Other harnesses need an advertised model config option with session/set_config_option, or legacy ACP models with session/set_model. Without supported ACP model control or an adapter-specific startup model flag, Apus/acpx cannot force a model selection.

GitHub Copilot CLI in native chat

GitHub Copilot CLI can serve ordinary Apus chat through the installed-agent model picker, including web chat and channels. This route uses the local copilot --acp --stdio process, not an Apus API-provider credential.

Install an ACP-capable CLI and sign in under the same OS account that runs the Gateway. Copilot CLI 1.0.86 supports model discovery and selection over ACP:

npm install -g @github/copilot
copilot --version
copilot login

Refresh the model catalog, then choose an acp-copilot/<model-id> entry. Apus uses only the models advertised by that CLI; it does not supply a static model list. Installation detection alone does not prove authentication or model access. To prevent new native Copilot turns and catalog discovery, set plugins.entries.acpx.config.nativeAgents.copilot to false. Classic /acp spawn copilot sessions and acp.allowedAgents are separate.

Copilot owns authentication and billing:

• Native GitHub authentication uses the CLI's OAuth login or its supported GitHub token routes, including an authenticated gh fallback. Environment tokens (COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN) can override a stored login.
• Copilot model usage consumes the account's plan allowance. Do not assume a model is free because its catalog entry is available; check the account's included usage and additional-usage budget.
• Explicit CLI BYOK configuration (COPILOT_PROVIDER_*, COPILOT_PROVIDERS_CONFIG, or the CLI's providers.json) can route model requests to a separately billed provider even when GitHub login is available. Configure that route deliberately. Apus does not choose it or copy an Apus API credential into the native harness.

See GitHub's CLI authentication guide and Copilot billing guide for account and plan requirements. Native chat permission and sandbox boundaries below still apply.

Installed native agents keep their own sign-in. During discovery, /models can report Checking native agent without requiring an Apus API key. If availability is unconfirmed, check the native app on the Gateway host and run /models again.

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

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

See Configuration Reference.

Repair existing bare-session histories

ACPX isolates bare session names by Apus owner. If a session reports SESSION_OWNER_MIGRATION_REQUIRED, stop the Gateway and run apus doctor --fix, then restart. Doctor uses the same service workspace as the Gateway; ACPX's default state directory is <service workspace>/state.

The repair requires one current, unambiguous canonical owner claim with matching backend identifiers. It preserves the raw history, event-log references, upstream session IDs, timestamps, options, and usage. Persistent record names move to an owner-qualified resource; existing oneshot physical IDs and histories remain intact. Ambiguous, stale, conflicting, unreadable, or live records remain in place with a diagnostic. Resolve the reported evidence problem before retrying; resetting the session does not bypass this repair.

This is an offline, crash-recoverable migration with atomic destination-file publication. Files and SQLite are not one atomic transaction. Interrupted repairs can be rerun: Doctor checks the existing destination and canonical claim before finishing the metadata update and archiving the old persistent record.

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:

apus plugins install @openclaw/acpx
apus 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:

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

Local workspace install during development:

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

Then verify backend health:

/acp doctor

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

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 Apus itself. If an adapter download or spawn fails, /acp doctor reports the failure.

Plugin tools MCP bridge

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

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

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

What this does:

• Injects a built-in MCP server named apus-plugin-tools into ACPX session bootstrap.
• Exposes plugin tools already registered by installed and enabled Apus plugins.
• Passes the active ACP session identity to plugin tool factories, so agent-scoped tools stay in that agent's namespace.
• 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 Apus 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.

Apus tools MCP bridge

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

apus config set plugins.entries.acpx.config.apusToolsMcpBridge true

What this does:

• Injects a built-in MCP server named apus-tools into ACPX session bootstrap.
• Exposes selected built-in Apus 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:

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

Runtime turns use Apus agent/run timeouts, including /acp timeout. An interactive turn can continue beyond the plugin operation limit until its turn budget expires, the harness finishes, or you cancel it. sessions_spawn does not accept per-call timeout overrides; the operator path is agents.defaults.subagents.runTimeoutSeconds. With the default hybrid reload mode, changing timeoutSeconds automatically reloads the plugin. See Config hot reload.

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

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

permissionMode

Controls which operations the harness agent can perform without prompting.

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:

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

With the default hybrid reload mode, these changes automatically reload the plugin. See Config hot reload for other reload modes.

Related

• ACP agents — overview, operator runbook, concepts
• Sub-agents
• Multi-agent routing
• ACPx plugin reference — the acpx runtime plugin's manifest and config, including the Pi session catalog