概述
ACP（Agent Client Protocol）会话让 OpenClaw 通过 ACP 后端插件运行外部编码 harness（Claude Code、Cursor、Gemini CLI、Codex ACP、OpenCode 等）。每个 ACP 会话作为后台任务追踪。
支持的 Harness
| Harness ID | 后端 | 说明 |
|---|---|---|
claude | Claude Code ACP adapter | 需要 Claude Code auth |
codex | Codex ACP adapter | 原生 Codex 不可用时的显式 ACP 回退 |
cursor | Cursor CLI ACP | 需要 Cursor CLI |
gemini | Gemini CLI ACP | 需要 Gemini CLI auth |
opencode | OpenCode ACP | 需要 OpenCode CLI |
droid | Factory Droid CLI | 需要 FACTORY_API_KEY |
kiro | Kiro CLI | 依赖已安装的 CLI |
核心功能
- 会话绑定：
--bind here（绑定当前对话）或--thread auto（绑定线程） - 持久会话：
mode: "persistent"保持会话跨消息存活 - 会话恢复：
resumeSessionId恢复已有 ACP 会话 - 流式输出：
streamTo: "parent"将进度流式传回父会话 - ACP 控制命令：
/acp spawn、/acp cancel、/acp steer、/acp close、/acp status
配置/使用
安装 acpx 插件：
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true基础配置：
{
acp: {
enabled: true,
backend: "acpx",
defaultAgent: "codex",
allowedAgents: ["claude", "codex", "gemini"],
maxConcurrentSessions: 8,
},
}从 sessions_spawn 启动：
{
"task": "Open the repo and summarize failing tests",
"runtime": "acp",
"agentId": "codex",
"thread": true,
"mode": "session"
}安全边界
- ACP 会话在 host 运行时执行，不在 OpenClaw 沙箱内
- 沙箱会话不能派生 ACP 会话
- OpenClaw 仍执行 ACP 功能门控、允许 Agent 列表、会话所有权、频道绑定和 Gateway 投递策略
相关页面
- concepts/tool-acp-agents-setup — ACP agents 安装与权限配置
- concepts/tool-subagents — Sub-agents（OpenClaw 原生委托运行）
- concepts/tool-multi-agent-sandbox-tools — 多 Agent 沙箱与工具策略