跳转至

ACP 智能体快速入门

这是否开箱即用？

是的，安装官方 ACP 运行时插件后即可：

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

源码检出（source checkouts）在 pnpm install 之后可以使用本地的 extensions/acpx 工作区插件。运行 /acp doctor 进行就绪检查。

只有当 ACP 真正可用时，OpenClaw 才会让智能体了解 ACP 的生成（spawning）能力：ACP 必须已启用，调度（dispatch）不能被禁用，当前会话不能被沙箱阻止，并且必须已加载且运行健康的运行时后端。如果任一条件不满足，ACP 技能和 sessions_spawn 的 ACP 指引将保持隐藏，以避免智能体推荐不可用的后端。

ACP 策略变更无需重启 Gateway 即可生效。启用状态、调度、默认智能体以及允许的智能体决定新的准入；后端与回退设置决定后续轮次。已准入的轮次保留其会话所有权。ACPX 健康检查会从当前允许的智能体中选择，除非其插件配置显式设置了 probeAgent。

ACPX 会话状态默认存放在 OpenClaw 状态目录（OPENCLAW_STATE_DIR，通常为 ~/.openclaw）下的 acpx/。工作目录和已安装包目录在会话重置时不需要可写。显式设置 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、model_provider、model_reasoning_effort、sandbox_mode 以及安全的 model_providers.<name> 字段）；认证、通知和 hooks 仅保留在宿主配置中。
  • 其他目标 harness 适配器可在首次使用时按需通过 npx 获取。
  • 该 harness 的供应商认证必须已存在于宿主上。
  • 如果宿主没有 npm 或网络访问权限，首次运行的适配器获取将会失败，直到缓存被预热或以其他方式安装适配器。
运行时先决条件

ACP 会启动一个真实的外部 harness 进程。OpenClaw 负责路由、后台任务状态、投递、绑定和策略；harness 负责其提供商登录、模型目录、文件系统行为以及原生工具。

在归咎于 OpenClaw 之前，请确认：

  • /acp doctor 报告已启用且健康的后端。
  • 当设置了 acp.allowedAgents 允许列表时，目标 id 被该列表允许。
  • harness 命令能够在 Gateway 主机上启动。
  • 该 harness 存在提供商认证（claude、codex、gemini、opencode、droid 等）。
  • 所选模型在该 harness 中存在——模型 id 不能跨 harness 移植。
  • 请求的 cwd 存在且可访问，或者省略 cwd 让后端使用其默认值。
  • 权限模式与工作相匹配。非交互式会话无法点击原生权限提示，因此写/执行密集型的编码运行通常需要能够无头运行的 ACPX 权限配置文件。

默认情况下，OpenClaw 插件工具和内置 OpenClaw 工具不会暴露给 ACP harness。仅当 harness 需要直接调用这些工具时，才启用 ACP 智能体 - 设置 中的显式 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/运行时认证。
cursor Cursor CLI ACP（cursor-agent acp） 如果本地安装暴露了不同的 ACP 入口点，请覆盖 acpx 命令。
droid Factory Droid CLI 需要在 harness 环境中具有 Factory/Droid 认证或 FACTORY_API_KEY。
fast-agent fast-agent-mcp ACP 适配器 按需通过 uvx 获取。
gemini Gemini CLI ACP 适配器 需要 Gemini CLI 认证或 API 密钥设置。
iflow iFlow CLI 适配器可用性和模型控制取决于已安装的 CLI。
kilocode Kilo Code CLI 适配器可用性和模型控制取决于已安装的 CLI。
kimi Kimi/Moonshot CLI 需要在宿主上具有 Kimi/Moonshot 认证。
kiro Kiro CLI 适配器可用性和模型控制取决于已安装的 CLI。
Harness ID 典型后端 备注
mux Mux CLI ACP 适配器 通过 npx 按需获取。
opencode OpenCode ACP 适配器 需要 OpenCode CLI/提供商身份验证。
openclaw 通过 openclaw acp 的 OpenClaw Gateway 桥接 允许支持 ACP 的框架向 OpenClaw Gateway 会话回传消息。
qoder Qoder CLI 适配器可用性和模型控制取决于已安装的 CLI。
qwen Qwen Code / Qwen CLI 需要在主机上配置 Qwen 兼容的身份验证。
trae Trae CLI ACP 适配器 适配器可用性和模型控制取决于已安装的 CLI。

pi（pi-acp）也已注册到 acpx 后端，但它与上述其他工具不同，不属于同一意义上的编码框架。

可以在 acpx 本身中配置自定义 acpx 代理别名，但 OpenClaw 策略在调度前仍会检查 acp.allowedAgents 以及任何 agents.entries.*.runtime.acp.agent 映射。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw