Metadata-Version: 2.4
Name: openclaw-acp
Version: 0.1.1
Summary: Wrap openclaw acp into a standard stdio ACP server.
Project-URL: Homepage, https://github.com/Dr-Lv/openclaw-acp
Author: Clawdboz
License: MIT
Keywords: acp,agent-client-protocol,mcp,openclaw,stdio
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# OpenClaw ACP Stdio Wrapper

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

## 背景

`openclaw acp` 是 [OpenClaw](https://github.com/openclaw/openclaw) 的 ACP (Agent Client Protocol) 桥接进程，但它不是标准的ACP协议。本项目通过 stdio 包装层，将其转化为了标准的 ACP 消息处理能力，使其能够被 [Clawdboz](https://github.com/Dr-Lv/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，对话上下文相互隔离

## 安装

```bash
pip install openclaw-acp
```

或从源码安装：

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

## 依赖





- Python >= 3.10
- [OpenClaw CLI](https://docs.openclaw.ai/cli) (`openclaw` 命令需在 PATH 中)
- 运行中的 OpenClaw Gateway（wrapper 会自动启动，也可提前手动运行）

## 使用

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

```bash
# 基本启动
openclaw-acp

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

### 环境变量

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

### 作为 MCP/ACP 服务器配置

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

```json
{
  "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
