在 OpenClaw 中接入 Claude Code（ACP 方式）

本文记录了在 Windows 环境下，通过 OpenClaw + acpx 调用 Claude Code 的完整配置过程。

---

环境说明

• OS：Windows Server / Windows 10+
• Node.js：v22.21.0（通过 nvm 管理）
• OpenClaw：已运行
• Claude Code：通过 Anthropic API Key 调用

---

一、安装 acpx 插件

acpx 是 OpenClaw 的 ACP（Agent Client Protocol）后端插件，用于桥接外部 AI 编程助手。

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

---

二、配置 ACP 基础参数

在 openclaw.json 中设置 ACP 相关参数：

openclaw config set acp.enabled true
openclaw config set acp.backend acpx
openclaw config set acp.defaultAgent claude
openclaw config set acp.allowedAgents "[\"claude\",\"codex\"]"

配置 acpx 插件的路径和权限：

openclaw config set plugins.entries.acpx.config.command "C:\nvm4w\nodejs\acpx.cmd"
openclaw config set plugins.entries.acpx.config.expectedVersion any
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions deny

⚠️ 注意：plugins.entries.acpx.config 只允许这几个字段，不能添加其他字段，否则会报 invalid config 错误。

---

三、安装 Claude Code

npm install -g @anthropic-ai/claude-code
claude --version  # 验证安装：2.1.138 (Claude Code)

---

四、安装 claude-agent-acp 适配器

acpx 内置的 claude harness 依赖 @zed-industries/claude-agent-acp，但该包已改名。需安装新包：

npm install -g @agentclientprotocol/claude-agent-acp

验证安装路径：

where.exe claude-agent-acp
# C:\nvm4w\nodejs\claude-agent-acp
# C:\nvm4w\nodejs\claude-agent-acp.cmd

---

五、配置 API Key 和 agent 入口

由于 claude-agent-acp 是 ESM 模块，需要通过 .mjs wrapper 注入 API Key 并调用：

创建 C:\Users\{用户名}\.acpx\claude-acp.mjs：

// Claude ACP wrapper
process.env.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY || 'sk-ant-api03-xxxxxxxxxxxxxx'
await import('file:///C:/nvm4w/nodejs/node_modules/@agentclientprotocol/claude-agent-acp/dist/index.js')

创建 C:\Users\{用户名}\.acpx\config.json：

{
  "agents": {
    "claude": {
      "command": "node C:/Users/{用户名}/.acpx/claude-acp.mjs"
    }
  }
}

⚠️ 注意：config.json 必须用 UTF-8 无 BOM 编码保存，否则 acpx 解析 JSON 会失败。建议用 Python 写入：

import json
with open(r'C:\Users\xxx\.acpx\config.json', 'w', encoding='utf-8') as f:
    json.dump(cfg, f, indent=2)

---

六、验证 acpx 能调通 Claude

$env:ANTHROPIC_API_KEY = "sk-ant-api03-xxxxxxxxxxxxxx"
acpx claude sessions new        # 创建 session
acpx claude "1+1等于多少，只回答数字" --approve-all
# 输出：2

---

七、重启 OpenClaw gateway

openclaw gateway restart

验证是否正常：

发送消息 /acp doctor，期望看到：

healthy: yes
runtimeDoctor: ok (acpx command available ...)

---

八、通过 OpenClaw 调用 Claude Code

配置完成后，直接和 OpenClaw 对话即可让它调用 Claude Code：

用户： 让 Claude Code 计算 1+2

OpenClaw： Claude Code 回答：3 ✅

底层调用链：

OpenClaw → sessions_spawn(runtime=acp, agentId=claude)
         → acpx → claude-acp.mjs
         → claude-agent-acp (ACP 协议)
         → Anthropic API
         → 返回结果

---

常见问题

问题	原因	解决方案
acpx exited with code 1	claude harness 找不到可执行文件	配置 ~/.acpx/config.json 指向正确路径
spawn EINVAL	Windows 不支持直接 spawn .cmd 文件	改用 .mjs wrapper 通过 node 调用
ERR_REQUIRE_ASYNC_MODULE	ESM 模块不能用 require()	改用 .mjs 文件 + await import()
invalid config: must NOT have additional properties	openclaw.json 的 acpx config 不支持 agents 字段	agent 配置放在 ~/.acpx/config.json
Authentication required	API Key 未注入	在 .mjs wrapper 里硬编码或通过环境变量传入
JSON 解析失败	PowerShell 写文件带 BOM	改用 Python 写 UTF-8 无 BOM 文件

---

总结

整个配置的核心思路：

1. OpenClaw 通过 acpx 插件支持 ACP 协议
2. acpx 需要知道如何启动 claude agent（通过 ~/.acpx/config.json）
3. claude-agent-acp 是 ACP 协议适配器，连接 Claude Code 的 API
4. 因为是 ESM 模块，需要 .mjs wrapper 来正确加载并注入 API Key

配置完成后，可以让 OpenClaw 自动调用 Claude Code 完成代码分析、重构、文件操作等复杂任务。