通过 ACP runtime 委托 acpx-enabled harness(Claude Code / Codex 等)的标准协议。触发词:调用 Claude Code、通过 acp 调用、通过 acpx 调用、delegation to claude/codex、Coordinator 调用 Executor。
---
name: acp-harness-delegation
description: 通过 ACP runtime 委托 acpx-enabled harness(Claude Code / Codex 等)的标准协议。触发词:调用 Claude Code、通过 acp 调用、通过 acpx 调用、delegation to claude/codex、Coordinator 调用 Executor。
---
# Acpx Harness Delegation
通过 ACP runtime 委托 acpx-enabled harness(Claude Code / Codex 等)的标准协议。
## 触发条件(满足其一)
- "调用 Claude Code"
- "通过 acp 调用"
- "通过 acpx 调用"
- "delegation to claude"
- "delegation to codex"
- "Coordinator 调用 Executor"
- "spawn acpx harness"
- "用 acp 调用外部 agent"
- "通过 ACP 委托 harness"
---
## 核心调用方式
### ✅ 标准 sessions_spawn(结果自动推回父 channel)
```javascript
sessions_spawn({
runtime: "acp",
agentId: "claude", // 或 codex / pi / opencode / gemini / kimi
mode: "session", // 关键:持久 session,不是 run
thread: true, // 关键:结果通过 parent channel 推送回来
label: "executor", // 固定 label,复用 session
task: "任务描述"
})
```
**效果**:结果直接出现在 Coordinator 的聊天里,不需要跨 session 查。
### ❌ 错误方式(不要用)
```javascript
// 错误1:mode="run" 是 fire-and-forget,无法获取返回结果
sessions_spawn({ runtime: "acp", agentId: "claude", mode: "run", task: "..." })
// 错误2:sessions_send 跨 session 访问会被 visibility 限制
sessions_send({ sessionKey: "agent:claude:acp:...", message: "..." })
// → 报错:forbidden / Session visibility restricted
// 错误3:visibility=all 有安全风险,不推荐
// → CVE-2026-27004 相关风险
```
---
## 调用前必须满足的 3 个前提
### 1️⃣ 认证:ANTHROPIC_API_KEY 必须存在
acpx 调用 Claude adapter 时,runtime 会广告 `authMethods`,如果找不到凭据则报错 `RUNTIME: Authentication required`。
**检查方式:**
```bash
echo $ANTHROPIC_API_KEY
```
**配置方式(二选一):**
**方式 A:环境变量(推荐用于测试)**
```bash
export ANTHROPIC_API_KEY=sk-...
# 然后调用
```
**方式 B:acpx 配置文件(推荐用于生产)**
在 `~/.acpx/config.json` 添加:
```json
{
"authCredentials": {
"ANTHROPIC_API_KEY": "sk-你的key"
}
}
```
> 注意:`authPolicy: "skip"` 只能跳过认证检查,不能替代凭据。如果 Claude adapter 要求 API key 而找不到,会直接失败。
### 2️⃣ acpx 全局权限配置
`~/.acpx/config.json` 必须包含:
```json
{
"defaultPermissions": "approve-all",
"nonInteractivePermissions": "deny",
"authPolicy": "skip"
}
```
这个配置让 acpx 在自动化环境下自动批准所有操作,不弹确认框。
### 3️⃣ Session 可用性验证(可选但推荐)
如果之前调用过同一个 label,可能需要先验证 session 是否健康:
```bash
acpx sessions list
```
如果看到某个 session 显示 `needs reconnect`,先修复:
```bash
acpx sessions ensure <session-name>
# 或重建
acpx sessions new claude
```
---
## 完整调用流程(推荐写入你的 Coordinator Agent prompt)
```
当需要调用 Claude Code 执行任务时:
1. 前置检查:确认 ANTHROPIC_API_KEY 环境变量存在
(如果不存在,回复:"请先配置 ANTHROPIC_API_KEY 环境变量")
2. 调用 spawn:
sessions_spawn(
runtime="acp",
agentId="claude",
mode="session",
thread=true,
label="executor",
task="具体任务描述"
)
3. 等待结果:结果会通过 thread 自动推送回当前 channel
不要使用 sessions_send 去跨 session 查结果
4. 如果结果未返回,检查:
- acpx sessions list → 是否有 needs reconnect
- echo $ANTHROPIC_API_KEY → API key 是否有效
```
---
## 已知问题记录
### 🔍 `unknown option '--cwd'` 排查
**已验证:** OpenClaw acpx runtime.ts(2026.3.13)构造命令时 `--cwd` 是放在 agent 之前的,顺序正确:
```
acpx --format json --json-strict --cwd /path claude prompt --session ...
```
**如果仍看到这个错误:** 说明调用方不是 OpenClaw runtime,而是外部脚本直接调用 `acpx claude --cwd /path`。检查那个脚本,把 `--cwd` 移到 `claude` 之前:
```
✅ acpx --cwd /path claude "prompt"
❌ acpx claude --cwd /path "prompt"
```
---
## 错误处理对照表
| 错误信息 | 根因 | 解决方法 |
|---------|------|---------|
| `unknown option '--cwd'` | OpenClaw acpx runtime bug,参数构造顺序错误 | 等待 OpenClaw 修复;当前可在 agent config 里 workaround |
| `agent needs reconnect` | acpx session 记录在但进程断了 | `acpx sessions ensure <name>` 或 `sessions new` |
| `RUNTIME: Resource not found` | session id 失效 | 不要复用旧 id,用新的 spawn |
| `RUNTIME: Authentication required` | 找不到 API key | 配 `ANTHROPIC_API_KEY` 环境变量或 `authCredentials` |
| `forbidden / Session visibility restricted` | `sessions_send` 跨 session 被限制 | 改用 `thread=true` 模式,结果自动推回 |
---
## Session 复用说明
使用固定 `label` 的好处:
- 第一次调用:创建 session
- 后续调用:自动 reconnect 到已有 session,保留上下文
- Session 有 30 天归档清理 + 500 条上限
不需要手动管理 session 生命周期,只要 label 固定,acpx 会自动处理。
---
## 关键澄清
- **`--dangerously-skip-permissions` 是 Claude Code CLI 的参数,不是 acpx 的参数**
- **acpx 的正确权限控制是 `defaultPermissions` 配置项**(见上方配置)
- **`mode:"session" + thread:true` 是唯一可靠的结果返回方式**
- **不要用 `visibility=all`**,有安全风险
---
## 相关文件
- Skill 配置:`~/.openclaw/skills/acp-harness-delegation/SKILL.md`
- Harness 列表:`~/.openclaw/skills/acp-harness-delegation/references/harness-list.md`
- acpx 全局配置:`~/.acpx/config.json`
- Claude API Key 配置:`~/.acpx/config.json` 的 `authCredentials` 字段
don't have the plugin yet? install it then click "run inline in claude" again.