Acp Harness

Name: Acp Harness
Rating: 3.5 (1 reviews)
Author: lichao2014

By lichao2014 👁 41 views ▲ 0 votes

openclaw harness runtime plugin using ACP

GitHub

Install

npm install
npm

Configuration Example

{
  "harnesses": {
    "my-agent": {
      "agent": "my-agent",
      "command": "my-agent --acp",
      "bundleMcp": true,
      "autoModel": false,
      "allowedTools": ["shell"],
      "maxTurns": 30
    }
  }
}

README

# ACP Agent Harness

ACP Agent Harness 是一个 OpenClaw runtime plugin，用于让 OpenClaw 会话通过
ACP（Agent Client Protocol）接入外部 agent。插件会注册一个或多个 OpenClaw
`AgentHarness` runtime，按配置启动对应的 ACP 命令，把 ACP 事件流转回 OpenClaw，
并把最终消息镜像写入 OpenClaw 会话 transcript。

本项目面向 OpenClaw 插件集成场景，可作为 OpenClaw extension 加载，用于把外部
ACP-compatible agent 接入 OpenClaw 会话运行链路。

## 功能

- 通过插件配置中的 `harnesses` 注册多个 OpenClaw agent harness。
- 通过 ACP stdio 命令启动外部 agent。
- 按 OpenClaw 会话 id 和 harness id 复用持久 ACP 会话。
- 支持 side question，并为 side question 使用短生命周期 ACP 会话。
- 将 assistant 文本、reasoning 文本、工具调用、工具结果、生命周期事件和错误事件回传给 OpenClaw。
- 将 user、assistant、tool-result 消息以幂等方式镜像写入 OpenClaw transcript。
- 可选地把 OpenClaw MCP loopback server 暴露给 ACP agent。
- 提供 gateway 鉴权的 probe 路由，用于检测 ACP 命令是否可启动，以及 agent 暴露了哪些模型。

```mermaid
flowchart LR
  A["OpenClaw 会话"] --> B["acp-harness AgentHarness"]
  B --> C["ACP core loader"]
  C --> D["acpx runtime"]
  D --> E["外部 ACP agent 命令"]
  E --> D
  D --> F["OpenClaw 事件"]
  D --> G["Transcript 镜像写入"]
```

## 环境要求

- 支持 plugin 的 OpenClaw。
- 与宿主 OpenClaw 进程兼容的 Node.js runtime。
- 一个可执行的 ACP-compatible agent 命令，可以位于 `PATH` 中，也可以使用绝对路径。

本包声明 `openclaw` 为 peer dependency，并依赖 `@agentclientprotocol/sdk`。

## 配置

插件通过 `harnesses` 对象配置。对象 key 就是该 harness 的 OpenClaw runtime id。
OpenClaw 发起请求时，需要使用同一个 runtime id 才能选中对应 harness。

```json
{
  "harnesses": {
    "my-agent": {
      "agent": "my-agent",
      "command": "my-agent --acp",
      "bundleMcp": true,
      "autoModel": false,
      "allowedTools": ["shell"],
      "maxTurns": 30
    }
  }
}
```

### 字段说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `harnesses` | object | 否 | harness id 到 harness 配置的映射。未配置时不会注册任何 harness。 |
| `agent` | string | 是 | ACP agent 的逻辑名称。同一个 agent 名称不能在不同 harness 中配置不同 command。 |
| `command` | string | 是 | 启动 ACP agent 的命令行。 |
| `env` | object | 否 | 传给 agent 进程的额外字符串环境变量。空值会被忽略；不要把敏感凭据提交到仓库。 |
| `bundleMcp` | boolean | 否 | 为 `true` 时，在本次运行没有禁用工具的前提下，把 OpenClaw MCP loopback server 暴露给 ACP agent。默认 `false`。 |
| `autoModel` | boolean | 否 | 为 `true` 时，插件不会向 ACP agent 传递 OpenClaw model id。默认 `false`。 |
| `allowedTools` | string array | 否 | 作为 ACP session option 转发给 agent 的工具 allow-list，是否生效取决于 agent 支持情况。 |
| `maxTurns` | integer | 否 | 作为 ACP session option 转发给 agent 的正整数最大 turn 数，是否生效取决于 agent 支持情况。 |

如果没有开启 `autoModel`，普通 run 需要 OpenClaw 提供 model id。当 `agent` 为
`codex` 时，插件会把 OpenClaw thinking level 映射到 Codex 风格的 runtime model
后缀。

## 运行机制

插件启动时，`src/plugin.ts` 会解析插件配置，注册 probe 路由，并为每个配置项注册一个
OpenClaw `AgentHarness`。较重的 ACP core 不会在插件注册阶段立即加载，而是在 probe、
run、side question 或 reset 真正需要时通过 lazy load 加载。

普通 run 使用持久 ACP 会话。ACP session key 由 OpenClaw session id 和 harness id
组合得到，因此同一个 OpenClaw 会话在同一个 harness 下可以跨 turn 继续对话。

Side question 使用 one-shot ACP 会话，并且不会接收打包的 OpenClaw MCP server。

runtime 状态目录：

```text
~/.openclaw/acp-harness
```

## Probe API

插件注册了一个需要 gateway 鉴权的 HTTP 路由：

```text
POST /plugins/acp-harness/v1/agents/probe
```

请求示例：

```json
{
  "harnessId": "my-agent",
  "agent": "my-agent",
  "command": "my-agent --acp",
  "cwd": "F:\\code\\project",
  "autoModel": true,
  "timeoutMs": 15000
}
```

响应示例：

```json
{
  "ok": true,
  "available": true,
  "harnessId": "my-agent",
  "agent": "my-agent",
  "currentModelId": "example-model",
  "models": [
    { "id": "example-model", "name": "example-model" }
  ]
}
```

OpenClaw 侧的配置 UI 或诊断工具可以使用这个路由来验证 command 能否启动、ACP session
能否初始化，以及 agent 是否上报可用模型。

## 开发

在宿主工作区安装依赖，然后让 OpenClaw 从 `index.ts` 加载 extension。

```bash
npm install
npm run build
```

当前 `npm run build` 是 no-op，只会输出确认信息。插件入口文件：

```text
index.ts
```

OpenClaw extension 元数据文件：

```text
openclaw.plugin.json
```

## 排障

- OpenClaw 中看不到 ACP runtime：检查是否配置了 `harnesses`，并确认每个配置项都有 `agent` 和 `command`。
- run 提示 runtime 不支持：请求的 runtime id 必须与 harness id 一致，例如示例配置中的 `my-agent`。
- probe 立即失败：确认 OpenClaw 进程能找到该命令，并按 agent 文档准备所需运行环境。
- run 提示缺少 model id：在 OpenClaw 中选择或提供模型，或者把 `autoModel` 设置为 `true`。
- ACP agent 中没有工具：确认 `bundleMcp` 为 `true`，本次 run 没有禁用工具，并确认宿主 OpenClaw MCP loopback 能正常启动。

## License

本仓库当前未提供独立的 `LICENSE` 文件。对外发布前请补充明确的许可证信息。

tools