ACP (Agent Client Protocol) 配置完整指南

📖 什么是 ACP?

ACP (Agent Client Protocol) 是一个开放协议,用来规范 AI Agent 与代码编辑器/IDE 之间的通信方式。它类似于 Language Server Protocol (LSP),但专注于 AI 代理的集成,帮助开发者在不同编辑器中使用各种 AI 工具,而无需为每个组合构建自定义适配器。

为什么需要 ACP?

在没有 ACP 之前,每个 AI Agent 想接入某个 IDE,都需要单独开发适配器:

• Claude Code 要写一套适配器
• Cursor 要写一套适配器
• Windsurf 也要写一套适配器

这导致重复造轮子,而且一旦 Agent 更新,适配器还得跟着改。

ACP 的核心思路: 定义一套标准的通信协议,任何 Agent 只要实现了 ACP Server,任何 IDE 只要实现了 ACP Client,两者就能直接对接。

🚀 场景一: OpenClaw 中配置 ACP 调用 Claude Code 和 Codex

前置条件

• OpenClaw CLI: 已安装并配置
• Claude Code CLI (可选): 如果要调用 Claude Code
• Codex CLI (可选): 如果要调用 Codex
• Node.js: v16 或更高版本

配置步骤

第一步:安装 acpx 插件

openclaw plugins install @openclaw/acpx

第二步:配置 OpenClaw

使用命令行配置:

# 启用 acpx 插件
openclaw config set plugins.entries.acpx.enabled true

# 设置权限模式(自动批准所有操作)
openclaw config set plugins.entries.acpx.config.permissionMode approve-all

# 启用 ACP 功能
openclaw config set acp.enabled true
openclaw config set acp.dispatch.enabled true
openclaw config set acp.backend acpx

# 设置默认 Agent
openclaw config set acp.defaultAgent claude

或者直接编辑 ~/.openclaw/config.json:

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "permissionMode": "approve-all"
        }
      }
    }
  },
  "acp": {
    "enabled": true,
    "dispatch": {
      "enabled": true
    },
    "backend": "acpx",
    "defaultAgent": "claude"
  }
}

第三步:重启 Gateway

# 重启 OpenClaw Gateway 使配置生效
openclaw restart

第四步:验证配置

# 检查 ACP 状态
/acp doctor

# 启动一个持久化的 Claude 会话
/acp spawn claude --mode persistent --thread auto

使用方法

方法一:直接对话

你: "用 Claude Code 帮我重构这个函数"

OpenClaw 会自动走 ACP 路由到 Claude Code(如果你配置了 acp.defaultAgent: claude)。

方法二:手动 spawn 会话

/acp spawn claude --mode persistent --thread auto

然后在同一 thread 里继续对话,所有内容会发给 Claude Code。

方法三:用 sessions_spawn 工具

{
  "task": "帮我写个测试",
  "runtime": "acp",
  "agentId": "claude",
  "thread": true,
  "mode": "session"
}

常用 ACP 命令

关键点

⚠️ ACP 会话是非交互式的,所以 permissionMode: approve-all 是必须的,否则写文件/exec 命令会失败。

⚠️ ACP Binding 目前不支持飞书

📋 ACP 配置快速参考

OpenClaw ACP 配置

# 安装插件
openclaw plugins install @openclaw/acpx

# 配置
openclaw config set plugins.entries.acpx.enabled true
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set acp.enabled true
openclaw config set acp.dispatch.enabled true
openclaw config set acp.backend acpx
openclaw config set acp.defaultAgent claude

# 重启
openclaw restart

# 验证
/acp doctor