本页内容
本页内容
代理协调
ACP 代理快速入门
这开箱即用吗？
是的，安装官方 ACP 运行时插件后即可：
源签出可以在 pnpm install 之后使用本地 extensions/acpx 工作区插件。运行 /acp doctor 进行准备情况检查。
OpenClaw 仅在 ACP 为 真正可用的 时向代理传授有关 ACP 生成的知识：必须启用 ACP，不得禁用调度，当前会话不得被沙箱阻止，并且运行时后端必须已加载且运行正常。如果任何条件失败，ACP 技能和 sessions_spawn ACP 指导将保持隐藏状态，因此代理不会建议后端不可用。
ACP 策略更改无需重新启动网关即可应用。启用、调度、默认代理和允许的代理管理新的准入；后端和后备设置控制后续回合。承认的回合保留其会话所有权。 ACPX 运行状况检查从当前允许的代理中进行选择，除非其插件配置设置了显式 probeAgent。
ACPX 会话状态默认为 OpenClaw 状态目录内的 acpx/（OPENCLAW_STATE_DIR，通常为 ~/.openclaw）。会话重置时，工作目录和已安装的包目录不需要是可写的。显式 plugins.entries.acpx.config.stateDir 仍会覆盖此位置。以前的 <workspace>/state 默认值中的会话会在 ACPX 启动时自动迁移，或者在新的默认值为空时由 openclaw doctor --fix 自动迁移。仅当您想保留旧位置时才设置 stateDir。如果迁移失败，ACPX 会发出警告并继续使用该进程的旧位置；警告指定要设置的覆盖。
首次运行的陷阱
- 如果设置了
plugins.allow，它就是一个受限的插件清单，并且 必须 包含acpx，否则已安装的 ACP 后端会被故意阻止（/acp doctor会报告缺失的允许列表项）。 - Codex ACP 适配器自带
acpx插件，并在可能时本地启动。 - Codex ACP 与隔离的
CODEX_HOME一起运行。 OpenClaw 从主机 Codex 配置复制可信项目信任条目以及安全 model/provider 路由配置（model、model_provider、model_reasoning_effort、sandbox_mode和安全model_providers.<name>字段）；身份验证、通知和挂钩仅保留在主机配置上。 - 其他目标 harness 适配器可能会在首次使用时通过
npx按需获取。 - 该 harness 的厂商认证必须已在宿主上存在。
- 如果宿主没有 npm 或网络访问权限，首次运行时的适配器获取将会失败，直到缓存被预热或以其他方式安装该适配器。
运行时先决条件
ACP 会启动一个真实的外部 harness 进程。OpenClaw 负责路由、 后台任务状态、投递、绑定和策略；harness 负责其提供方登录、模型目录、文件系统行为和原生工具。
在归咎于 OpenClaw 之前，请验证：
/acp doctor报告后端已启用且健康。- 当设置了 allowlist 时，目标 id 需要被
acp.allowedAgents允许。 - harness 命令可以在 Gateway 主机上启动。
- 该 harness 已存在供应商认证（
claude、codex、gemini、opencode、droid等）。 - 为该 harness 选择的模型存在 - 模型 id 不能跨 harness 通用。
- 请求的
cwd存在且可访问，或者省略cwd让 backend 使用其默认值。 - 权限模式与工作匹配。非交互式会话无法单击本机权限提示，因此 write/exec-heavy 编码运行通常需要可以无头进行的 ACPX 权限配置文件。
默认情况下，OpenClaw 插件工具和内置的 OpenClaw 工具不会暴露给 ACP harness。只有在 harness 需要直接调用这些工具时，才在 ACP agents - setup 中启用显式的 MCP 桥接。
支持的 harness 目标
使用 acpx 后端时，可将这些 id 作为 /acp spawn <id> 或 sessions_spawn({ runtime: "acp", agentId: "<id>" }) 的目标：
| harness ID | 常见后端 | 笔记 |
|---|---|---|
claude |
Claude Code ACP 适配器 | 需要主机上已完成 Claude Code 身份验证。 |
codex |
Codex ACP 适配器 | 仅在原生 /codex 不可用或请求 ACP 时，才会显式回退到 ACP。 |
copilot |
GitHub Copilot ACP 适配器 | 需要 Copilot CLI/runtime 身份验证。 |
cursor |
光标 CLI ACP （cursor-agent acp） |
如果本地安装暴露了不同的 ACP 入口点，请覆盖 acpx 命令。 |
droid |
工厂机器人 CLI | 需要 Factory/Droid 身份验证，或在 harness 环境中提供 FACTORY_API_KEY。 |
fast-agent |
fast-agent-mcp ACP 适配器 | 通过 uvx 按需获取。 |
gemini |
Gemini CLI ACP 适配器 | 需要 Gemini CLI 身份验证或 API key 配置。 |
grok-build |
Grok 构建 CLI （grok agent stdio） |
需要在主机上安装并验证 Grok Build。 |
iflow |
iFlow CLI | 适配器可用性和模型控制取决于已安装的 CLI。 |
kilocode |
公斤代码 CLI | 适配器可用性和模型控制取决于已安装的 CLI。 |
kimi |
Kimi/Moonshot CLI | 需要主机上已完成 Kimi/Moonshot 身份验证。 |
kiro |
基罗 CLI | 适配器可用性和模型控制取决于已安装的 CLI。 |
mux |
Mux CLI ACP 适配器 | 通过 npx 按需获取。 |
opencode |
OpenCode ACP 适配器 | 需要 OpenCode CLI/provider 身份验证。 |
openclaw |
OpenClaw 网关桥接 openclaw acp |
让 ACP-aware harness与 OpenClaw 网关会话进行对话。 |
pool |
Poolside 代理 （pool acp） |
需要在网关主机上安装并验证 Poolside CLI。 |
qoder |
订购 CLI | 适配器可用性和模型控制取决于已安装的 CLI。 |
qwen |
Qwen 代码 / Qwen CLI | 需要主机上的 Qwen- 兼容身份验证。 |
trae |
Trae CLI ACP 适配器 | 适配器可用性和模型控制取决于已安装的 CLI。 |
pi（pi-acp）也在 acpx 后端中注册，但它并不像上面这些那样属于编码 harness。
grok-build 是启动 Grok 内部版本 CLI 的 ACPX 代理目标，而不是 xAI 模型 ID xai/grok-build-0.1。将 grok-build 传递为 agentId 为 ACP；仅在 OpenClaw 模型字段中使用 xAI 模型 ID。
自定义 acpx agent 别名可以在 acpx 本身中配置，但在分发前，OpenClaw 策略仍会检查 acp.allowedAgents 以及任何 agents.entries.*.runtime.acp.agent 映射。