openclaw-acp 0.1.0

Wrap openclaw acp into a standard stdio ACP server.

OpenClaw ACP Stdio Wrapper

将 openclaw acp 包装为标准 stdio ACP 服务器的桥接工具。

背景

openclaw acp 是 OpenClaw 的 ACP (Agent Client Protocol) 桥接进程，但它不是标准的ACP协议。本项目通过 stdio 包装层，将其转化为了标准的 ACP 消息处理能力，使其能够被 Clawdboz 等 ACP 客户端正常调用。

功能

• Gateway 管理：自动检测并启动 openclaw gateway（端口 18789）
• ACP 桥接：启动并管理 openclaw acp 子进程
• 协议翻译：自动转换 initialize 请求的 protocolVersion
• Agent Fallback：当 openclaw acp 不支持某些方法（如 session/prompt、tools/call）时，直接调用 openclaw agent CLI 获取真实回复
• 流式通知：为 session/prompt 提供标准的 ACP 流式响应（thinking → agent_message_chunk → stopReason）
• 自动建 Session：每次启动自动分配全新 session，对话上下文相互隔离

安装

pip install openclaw-acp

或从源码安装：

git clone https://github.com/Dr-Lv/openclaw-acp
cd openclaw-acp
pip install -e .

依赖

• Python >= 3.10
• OpenClaw CLI (openclaw 命令需在 PATH 中)
• 运行中的 OpenClaw Gateway（wrapper 会自动启动，也可提前手动运行）

使用

安装后会暴露 openclaw-acp 命令：

# 基本启动
openclaw-acp

# 指定 openclaw 二进制路径
openclaw-acp --openclaw-bin /opt/homebrew/bin/openclaw

环境变量

变量	说明	默认值
OPENCLAW_SESSION_ID	强制使用指定 session ID（留空则每次启动自动新建）	自动生成 UUID

作为 MCP/ACP 服务器配置

在支持 stdio ACP 的客户端（如 Cursor、Claude Desktop）中配置：

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw-acp"
    }
  }
}

工作原理

┌─────────────┐     Content-Length/NDJSON      ┌──────────────────────┐     NDJSON      ┌─────────────┐
│   ACP 客户端 │  ────────────────────────────> │ openclaw-acp-wrapper │ ──────────────> │ openclaw acp│
│  (Clawdboz) │                              │                      │               │             │
│             │  <──────────────────────────── │   - 协议翻译         │ <─────────────│   bridge    │
│             │     NDJSON (session/update)    │   - Agent fallback   │               │             │
└─────────────┘                                │   - 流式通知         │               └─────────────┘
                                               └──────────────────────┘
                                                        │
                                                        │ 启动/管理
                                                        ▼
                                               ┌──────────────────────┐
                                               │   openclaw gateway   │
                                               │    (127.0.0.1:18789) │
                                               └──────────────────────┘

协议说明

Wrapper 的输入支持两种格式：

• Content-Length 分帧（标准 MCP/ACP）
• 换行分隔 JSON（newline-delimited JSON）

输出统一使用 换行分隔 JSON，与 clawdboz 等客户端兼容。

License

MIT