Agents

acpx ships with a registry of friendly agent names. Each one resolves to a specific ACP adapter command. On Unix, unknown names fall through as raw commands, and --agent <command> supports custom launchers. On Windows, configure a named agent with structured argv instead (see Custom agents).

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

#Built-in registry

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.

#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
• Guide: 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"
    }
  }
}

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

#Other built-in agents

Setup, authentication, launch overrides, and capability notes live in the agent guides.

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

#See also

• Custom agents — --agent <command> and unknown positional names.
• Sessions — how the agent command becomes part of the session scope key.
• Authentication — ACPX_AUTH_* env vars and config auth entries for ACP authenticate handshakes.