OpenClaw ACP (Agent Client Protocol) 完整指南

什么是 ACP

ACP (Agent Client Protocol) 是 OpenClaw 的外部编码 Agent 集成协议。通过 ACP，OpenClaw 可以驱动外部编码工具（如 Claude Code、Codex、Pi 等），将它们作为「手臂」执行实际编码任务，而 OpenClaw 自身负责调度、对话管理和消息路由。

核心思路：OpenClaw 是大脑（规划、对话），外部编码 Agent 是手（写代码）。

架构概览


用户消息 → OpenClaw Gateway → ACP Runtime (acpx 插件) → 外部编码 Agent (Claude Code / Codex / Pi...)
                  ↑                                                    |
                  └────────────── 输出回传 ←──────────────────────────┘

关键组件

组件	说明
ACP Runtime	OpenClaw 内置的 ACP 会话管理器
acpx 插件	`@openclaw/acpx`，ACP 后端实现，负责与外部 Agent 通信
acpx CLI	命令行工具 (v0.1.15)，管理外部 Agent 会话
Harness Adapter	适配器，将不同编码工具统一为 ACP 协议

ACP vs Sub-agent

维度	ACP Session	Sub-agent
运行时	外部 Agent (Claude Code, Codex...)	OpenClaw 原生
会话键	`agent::acp:`	`agent::subagent:`
沙箱	❌ 在宿主机运行	✅ 支持
管理命令	`/acp ...`	`/subagents ...`
适用场景	需要专业编码工具能力	OpenClaw 原生委派

支持的编码 Agent

Agent	agentId	适配器命令	特点
Codex	`codex`	`npx @zed-industries/codex-acp`	OpenAI 出品，需要 git repo
Claude Code	`claude`	`npx -y @zed-industries/claude-agent-acp`	Anthropic 出品
Pi	`pi`	`npx pi-acp`	Mario Zechner 出品
OpenCode	`opencode`	`npx -y opencode-ai acp`	开源
Gemini CLI	`gemini`	`gemini`	Google 出品
Kimi	`kimi`	`kimi acp`	Moonshot 出品

使用方式

1. 自然语言触发（推荐）

在聊天中直接说：

"用 Codex 做这个"
"在 thread 里启动一个 Claude Code session"
"用 Gemini CLI 处理这个任务"

OpenClaw 会自动识别意图，路由到 ACP runtime。

2. `/acp` 命令


/acp spawn codex --mode persistent --thread auto --cwd /path/to/repo
/acp status
/acp cancel
/acp steer "优先修复 failing tests"
/acp close
/acp model anthropic/claude-opus-4-5
/acp doctor

3. sessions_spawn API


{
  "task": "修复登录页 bug",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session",
  "cwd": "/path/to/project"
}

4. 直接 acpx CLI（备用）


# 持久会话
acpx codex sessions new --name my-session
acpx codex -s my-session --cwd /repo --format quiet "你的任务"

# 一次性
acpx codex exec --cwd /repo "你的任务"

Thread 绑定（重要功能）

ACP 会话可以绑定到聊天线程（Discord thread / Telegram topic），实现持续对话：

线程中的后续消息自动路由到绑定的 ACP session
Agent 输出回传到同一线程
空闲超时或手动关闭时解绑

配置


{
  "channels": {
    "discord": {
      "threadBindings": { "spawnAcpSessions": true }
    },
    "telegram": {
      "threadBindings": { "spawnAcpSessions": true }
    }
  },
  "session": {
    "threadBindings": {
      "enabled": true,
      "idleHours": 24
    }
  }
}

配置参考

完整 ACP 配置


{
  "acp": {
    "enabled": true,
    "dispatch": { "enabled": true },
    "backend": "acpx",
    "defaultAgent": "codex",
    "allowedAgents": ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    "maxConcurrentSessions": 8,
    "stream": {
      "coalesceIdleMs": 300,
      "maxChunkChars": 1200
    },
    "runtime": {
      "ttlMinutes": 120
    }
  }
}

持久绑定（高级）

将特定频道/话题永久绑定到某个 Agent：


{
  "bindings": [
    {
      "type": "acp",
      "agentId": "codex",
      "match": {
        "channel": "discord",
        "peer": { "kind": "channel", "id": "频道ID" }
      },
      "acp": { "label": "codex-main", "cwd": "/workspace/repo" }
    }
  ]
}

权限配置

permissionMode	行为
`approve-all`	自动批准所有操作
`approve-reads`	仅自动批准读操作（默认）
`deny-all`	拒绝所有操作

nonInteractivePermissions	行为
`fail`	遇到权限提示时报错中止（默认）
`deny`	静默拒绝，优雅降级


openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions deny

IDE 集成

Zed 编辑器


{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"]
    }
  }
}

远程 Gateway：


{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp", "--url", "wss://gateway:18789", "--token", "<token>"]
    }
  }
}

通用流程

1. Gateway 运行中（本地或远程）

2. 配置 Gateway 目标

3. IDE 通过 stdio 运行 openclaw acp

安装与调试


# 安装 acpx 插件
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

# 健康检查
/acp doctor

# 查看版本
./extensions/acpx/node_modules/.bin/acpx --version

# 重新安装（版本不匹配时）
cd extensions/acpx && npm install --omit=dev --no-save acpx@<version>

常见问题

症状	原因	解决
`ACP runtime backend is not configured`	插件未安装/未启用	安装 acpx + `/acp doctor`
`Permission prompt unavailable`	权限模式过严	设 `permissionMode=approve-all`
Session 卡住	进程僵死	`ps aux \	grep acpx` 杀掉
沙箱 session 无法 spawn ACP	ACP 在宿主机运行	用 `runtime="subagent"`
Thread 绑定失败	频道未开启 `spawnAcpSessions`	检查配置

设计理念

1. OpenClaw 是编排层：不替代编码工具，而是让它们协作

2. 协议标准化：ACP 是开放协议 (agentclientprotocol.com)，任何工具都可以接入

3. 会话持久化：Thread 绑定让 Agent 拥有「上下文连续性」

4. 权限分层：非交互模式下的权限策略可配置

5. 双路径设计：ACP runtime（集成）+ acpx CLI（备用），确保可用性

生成时间：2026-04-14

数据来源：OpenClaw docs, acpx 插件源码, 实际配置