acpx/docs/agents.md at main · openclaw/acpx

title	Agents
description	Built-in agent registry — every friendly name acpx ships with, the ACP adapter it spawns, the upstream coding agent it wraps, and per-agent notes.

acpx ships with a registry of friendly agent names. Each one resolves to a specific ACP adapter command. Unknown names fall through as raw commands, and --agent <command> is the escape hatch for anything custom (see Custom agents).

The default agent for top-level commands like acpx exec … and acpx prompt … is codex.

Built-in registry

Agent	Adapter command	Wraps
`pi`	`npx pi-acp`	Pi Coding Agent
`openclaw`	`openclaw acp`	OpenClaw ACP bridge
`codex`	`npx -y @agentclientprotocol/codex-acp`	Codex CLI
`claude`	`npx -y @agentclientprotocol/claude-agent-acp`	Claude Code
`gemini`	`gemini --acp`	Gemini CLI
`cursor`	`cursor-agent acp`	Cursor CLI
`copilot`	`copilot --acp --stdio`	GitHub Copilot CLI
`droid`	`droid exec --output-format acp`	Factory Droid
`fast-agent`	`uvx fast-agent-mcp acp`	fast-agent
`grok-build`	`grok agent stdio`	Grok Build
`iflow`	`iflow --experimental-acp`	iFlow CLI
`kilocode`	`npx -y @kilocode/cli acp`	Kilocode
`kimi`	`kimi acp`	Kimi CLI
`kiro`	`kiro-cli-chat acp`	Kiro CLI
`mux`	`mux acp` via an ACPX-owned npm range	Mux
`opencode`	`npx -y opencode-ai acp`	OpenCode
`pool`	`pool acp`	Poolside
`qoder`	`qodercli --acp`	Qoder CLI
`qwen`	`qwen --acp`	Qwen Code
`trae`	`traecli acp serve`	Trae CLI
`zeroclaw`	`zeroclaw acp`	ZeroClaw

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

Common shape

Every built-in agent supports the same command surface:

acpx <agent> [prompt_text...]                 # implicit prompt
acpx <agent> prompt [prompt_text...]          # explicit prompt
acpx <agent> exec [prompt_text...]            # one-shot, no saved session
acpx <agent> cancel [-s <name>]               # cooperative session/cancel
acpx <agent> set-mode <mode> [-s <name>]      # session/set_mode
acpx <agent> set <key> <value> [-s <name>]    # session/set_config_option
acpx <agent> status [-s <name>]
acpx <agent> sessions [list | new | ensure | close | show | history | prune]

See Prompting, Sessions, and Session control for the cross-agent semantics.

Per-agent notes

Notes that override or extend the cross-agent behavior live below.

Codex

Built-in name: codex
Default command: npx -y @agentclientprotocol/codex-acp
Upstream: agentclientprotocol/codex-acp
Runtime controls exposed by current codex-acp releases: ACP modes and session config options, including the advertised model selector.
acpx --model <id> codex … and acpx codex set model <id> apply the requested model through the advertised ACP config option. Legacy adapters that advertise models use session/set_model.

Claude

Built-in name: claude
Default command: npx -y @agentclientprotocol/claude-agent-acp
Upstream: agentclientprotocol/claude-agent-acp
The built-in package range is pinned by acpx so fresh installs pick up Claude model and ACP adapter fixes without depending on a globally installed adapter binary.
On Windows, acpx resolves the claude.exe executable from PATH before spawning so launches do not depend on shell-specific command lookup.
--system-prompt and --append-system-prompt forward through ACP _meta.systemPrompt on session/new, letting you replace or append to the Claude Code system prompt without leaving a persistent session. The value persists in session_options.system_prompt so ensure/reuse keeps the override. Other agents ignore the field.

Pi

Built-in name: pi
Default command: npx pi-acp
Upstream: mariozechner/pi

OpenClaw

Built-in name: openclaw
Default command: openclaw acp
Upstream: openclaw/openclaw

For repo-local OpenClaw checkouts, override the built-in command in ~/.acpx/config.json so acpx openclaw … spawns the ACP bridge directly without the pnpm wrapper:

{
  "agents": {
    "openclaw": {
      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node scripts/run-node.mjs acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
    }
  }
}

Cursor

Built-in name: cursor
Default command: cursor-agent acp
Upstream: Cursor CLI

If your Cursor install exposes ACP as agent acp instead of cursor-agent acp, override:

{ "agents": { "cursor": { "command": "agent acp" } } }

Gemini

Built-in name: gemini
Default command: gemini --acp
Upstream: google/gemini-cli

Copilot

Built-in name: copilot
Default command: copilot --acp --stdio
Upstream: GitHub Copilot CLI
Requires a Copilot CLI release that supports ACP stdio mode. Older copilot binaries fail before ACP startup.

Droid (Factory)

Built-in names: droid, factory-droid, factorydroid
Default command: droid exec --output-format acp
Upstream: factory.ai

fast-agent

Built-in name: fast-agent
Default command: uvx fast-agent-mcp acp
Upstream: https://fast-agent.ai/acp

acpx fast-agent starts fast-agent through its ACP entrypoint. It requires uvx on PATH.

Configure model/provider settings through fast-agent environment variables, fast-agent configuration, or an acpx agent override with additional fast-agent-mcp acp arguments.

Grok Build

Built-in name: grok-build
Default command: grok agent stdio
Upstream: xAI Grok Build

acpx grok-build uses the installed grok CLI ACP server. Install Grok Build and complete its normal authentication flow before using it through acpx. If the Grok ACP server advertises cached_token, acpx asks it to authenticate with its agent-managed cached login. If it advertises xai.api_key, acpx also accepts XAI_API_KEY for this built-in.

Qoder

Built-in name: qoder
Default command: qodercli --acp
Upstream: Qoder CLI
Reuses the Qoder CLI login state. For non-interactive runs, set QODER_PERSONAL_ACCESS_TOKEN.
acpx qoder forwards --max-turns and --allowed-tools into Qoder CLI startup flags when those session options are set, so you do not need a raw --agent override for them.

iFlow

Built-in name: iflow
Default command: iflow --experimental-acp
Upstream: iflow-ai/iflow-cli

Kilocode

Built-in name: kilocode
Default command: npx -y @kilocode/cli acp
Upstream: kilocode.ai

Kimi

Built-in name: kimi
Default command: kimi acp
Upstream: MoonshotAI/kimi-cli

Kiro

Built-in name: kiro
Default command: kiro-cli-chat acp
Upstream: kiro.dev

Mux

Built-in name: mux
Default entrypoint: mux acp via an ACPX-owned npm range
Upstream: https://mux.coder.com/integrations/acp

acpx mux starts coder/mux through its ACP stdio bridge (mux acp). mux acp auto-starts an in-process mux server, so a separate mux server is not required.

Configure at least one model provider before prompting (for example ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY); see https://mux.coder.com/config/providers. When using direct provider keys, make sure mux route priority includes direct before providers you have not authenticated. To target a remote mux server, override the command with mux acp --server-url <url> --auth-token <token> (or set MUX_SERVER_URL / MUX_SERVER_AUTH_TOKEN).

OpenCode

Built-in name: opencode
Default command: npx -y opencode-ai acp
Upstream: opencode.ai

Pool

Built-in name: pool
Default command: pool acp
Upstream: Poolside

acpx pool uses the installed pool CLI ACP server (pool acp). Install and authenticate the CLI first; pool login is the normal interactive path. Focused setup notes live in agents/Pool.md.

Qwen

Built-in name: qwen
Default command: qwen --acp
Upstream: QwenLM/qwen-code

Trae

Built-in name: trae
Default command: traecli acp serve
Upstream: docs.trae.cn

ZeroClaw

Built-in name: zeroclaw
Default command: zeroclaw acp
Upstream: zeroclaw-labs/zeroclaw
zeroclaw acp is ZeroClaw's native JSON-RPC 2.0 stdio server for ACP v1 (protocolVersion: 1, no auth methods). The channel-acp-server feature it needs ships in ZeroClaw's default build.
session/new does not carry a ZeroClaw agent alias, so the server binds the session to acp.default_agent when set, otherwise to the sole [agents.<alias>] entry. Single-agent configs work as-is; multi-agent configs must set acp.default_agent or session/new fails.
Text prompts only (no image, audio, or embedded-context capability). Session resume/close is advertised when the ZeroClaw ACP session store is available. MCP tools are opt-in per agent via [agents.<alias>].acp_enable_mcp.

Overriding a built-in

Any built-in can be replaced wholesale through config, including args for adapter sub-commands:

{
  "agents": {
    "codex": {
      "command": "/usr/local/bin/codex-acp",
      "args": ["--profile", "ci"]
    }
  }
}

CLI flags still win over config. See Config for precedence rules.

Navigation Menu

Uh oh!

Built-in registry

Common shape

Per-agent notes

Codex

Claude

Pi

OpenClaw

Cursor

Gemini

Copilot

Droid (Factory)

fast-agent

Grok Build

Qoder

iFlow

Kilocode

Kimi

Kiro

Mux

OpenCode

Pool

Qwen

Trae

ZeroClaw

Overriding a built-in

See also

Uh oh!

FilesExpand file tree

agents.md

Latest commit

History

agents.md

File metadata and controls

Built-in registry

Common shape

Per-agent notes

Codex

Claude

Pi

OpenClaw

Cursor

Gemini

Copilot

Droid (Factory)

fast-agent

Grok Build

Qoder

iFlow

Kilocode

Kimi

Kiro

Mux

OpenCode

Pool

Qwen

Trae

ZeroClaw

Overriding a built-in

See also