9999e3c668
- shared/long-term/lessons: OpenClaw exec 批准授权系统完整配置经验 - daily/2026-03-16: CLI安装、exec配置、待办记录 - daily/2026-03-15: 之前未提交的日志 - shared/long-term/decisions/acp-agents-integration.md - agents/openclaw-main: claude-switch/mcp 相关记录
221 lines
5.7 KiB
Markdown
221 lines
5.7 KiB
Markdown
# ACP Agents Integration - OpenClaw ↔ OpenCode
|
||
|
||
**Created:** 2026-03-16
|
||
**Topic:** OpenClaw 通过 ACP 协议调用 OpenCode 的配置架构与最佳实践
|
||
|
||
---
|
||
|
||
## 核心概念
|
||
|
||
### 两层配置分离
|
||
|
||
1. **OpenClaw 层**：决定何时、如何调用外部编码代理
|
||
2. **OpenCode 层**：拿到任务后按什么模型、权限、规则执行
|
||
|
||
**关键原则**：OpenClaw 把 OpenCode 当作 ACP 外部 harness，通过 `@openclaw/acpx` 插件调用，而非手搓 PTY 自动化。
|
||
|
||
---
|
||
|
||
## OpenClaw 侧配置
|
||
|
||
### 入口命令区分
|
||
|
||
| 命令 | 用途 |
|
||
|------|------|
|
||
| `openclaw acp` | 让 **IDE/外部 ACP client** 接入 OpenClaw Gateway（服务端桥接） |
|
||
| `ACP Agents` 配置 | 让 **OpenClaw 主动调用外部代理**（如 OpenCode） |
|
||
|
||
**不要混淆**：要让 OpenClaw 调 OpenCode，配的是 `ACP Agents`，不是 `openclaw acp`。
|
||
|
||
### 最小配置路径
|
||
|
||
1. 安装并启用 `@openclaw/acpx` 插件
|
||
2. 设置 `acp.enabled = true`
|
||
3. 设置 `acp.backend = "acpx"`
|
||
4. 把 `opencode` 加入 `acp.allowedAgents`
|
||
5. 可选：设 `acp.defaultAgent = "opencode"`
|
||
6. 用 `/acp doctor` 检查后端状态
|
||
|
||
### 推荐配置 (`~/.openclaw/openclaw.json`)
|
||
|
||
```json5
|
||
{
|
||
acp: {
|
||
enabled: true,
|
||
dispatch: { enabled: true },
|
||
backend: "acpx",
|
||
defaultAgent: "opencode",
|
||
allowedAgents: ["opencode", "gemini", "codex"],
|
||
maxConcurrentSessions: 4,
|
||
runtime: {
|
||
ttlMinutes: 180
|
||
},
|
||
stream: {
|
||
coalesceIdleMs: 300,
|
||
maxChunkChars: 1200
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### acpx 内建 harness alias
|
||
|
||
`pi / claude / codex / opencode / gemini`
|
||
|
||
---
|
||
|
||
## OpenCode 侧配置
|
||
|
||
### 配置层级（merge，非 replace）
|
||
|
||
优先级从低到高：
|
||
|
||
1. Remote config (`.well-known/opencode`)
|
||
2. 全局 config (`~/.config/opencode/opencode.json`)
|
||
3. 自定义 config (`OPENCODE_CONFIG`)
|
||
4. 项目 config (`<repo>/opencode.json`)
|
||
5. `.opencode/` 目录 (agents/commands/plugins/skills/tools)
|
||
6. 运行时内联 (`OPENCODE_CONFIG_CONTENT`)
|
||
|
||
**建议只用两层**：
|
||
- 全局：provider / 默认模型 / 默认权限
|
||
- 项目：instructions / 项目模型 / 项目规则
|
||
|
||
### 关键配置项
|
||
|
||
#### 1) 模型与 provider
|
||
|
||
```jsonc
|
||
{
|
||
"$schema": "https://opencode.ai/config.json",
|
||
"model": "openrouter/anthropic/claude-sonnet-4",
|
||
"provider": {
|
||
"openrouter": {
|
||
"options": {
|
||
"apiKey": "{env:OPENROUTER_API_KEY}"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
支持 75+ provider，可自定义 `baseURL`、`apiKey`、`headers`。
|
||
|
||
#### 2) 权限 (permission)
|
||
|
||
**OpenCode 默认允许所有操作**，必须显式配置：
|
||
|
||
```json
|
||
{
|
||
"permission": {
|
||
"*": "ask",
|
||
"bash": "ask",
|
||
"edit": "ask"
|
||
}
|
||
}
|
||
```
|
||
|
||
**OpenClaw ACP 会话默认**：`permissionMode=approve-reads` + `nonInteractivePermissions=fail`
|
||
|
||
**最佳实践**：
|
||
- OpenCode 侧：`bash/edit` 设成 `ask`
|
||
- OpenClaw 侧：明确哪些任务走交互，哪些只读
|
||
|
||
#### 3) 项目规则 / 指令
|
||
|
||
```jsonc
|
||
{
|
||
"instructions": [
|
||
"AGENTS.md",
|
||
"docs/coding-standards.md",
|
||
"docs/testing-guidelines.md"
|
||
]
|
||
}
|
||
```
|
||
|
||
推荐组合：
|
||
- 项目根放 `AGENTS.md`
|
||
- `opencode.json` 里用 `instructions` 引入更细规则
|
||
|
||
#### 4) Server / Serve / Attach
|
||
|
||
- `opencode serve`：启动 headless HTTP 服务
|
||
- `opencode run --attach http://...`：附着到已有服务，避免冷启动
|
||
|
||
**两种方案**：
|
||
- A（简单）：acpx 每次直接调用本机 `opencode`
|
||
- B（更稳）：常驻 `opencode serve`，执行时复用后台实例
|
||
|
||
节点多时推荐 B。
|
||
|
||
#### 5) ACP 原生支持
|
||
|
||
```bash
|
||
opencode acp # stdin/stdout nd-JSON 通信
|
||
```
|
||
|
||
但 OpenClaw 官方集成路径仍是：**OpenClaw ACP Agents → acpx backend → agentId=opencode**
|
||
|
||
---
|
||
|
||
## 推荐落地架构
|
||
|
||
### 职责划分
|
||
|
||
| 组件 | 职责 |
|
||
|------|------|
|
||
| **OpenClaw** | 会话编排、任务分发、ACP session 生命周期管理、多通道接收任务 |
|
||
| **OpenCode** | 读仓库、按 `AGENTS.md`/`instructions` 写代码、用选定 provider+model 执行 |
|
||
| **acpx / ACP backend** | 桥接 OpenClaw ACP runtime 与 OpenCode harness |
|
||
|
||
### 分阶段实施
|
||
|
||
**第一阶段**
|
||
- 跑通 OpenClaw `ACP Agents`
|
||
- 只允许 `opencode` + `gemini`
|
||
- OpenCode 用项目内 `AGENTS.md` + `opencode.json`
|
||
- 权限全设 `ask`
|
||
|
||
**第二阶段**
|
||
- 常驻 `opencode serve` 减少冷启动
|
||
- 细分不同 repo 的项目配置
|
||
- 考虑 Gemini 分析器 + OpenCode 执行器分工
|
||
|
||
---
|
||
|
||
## 常见坑
|
||
|
||
| 坑 | 说明 |
|
||
|----|------|
|
||
| 1. 混淆 `openclaw acp` 与 ACP Agents | `openclaw acp` 是让外部 client 接入 OpenClaw，不是让 OpenClaw 调外部代理 |
|
||
| 2. OpenCode 默认权限太松 | 不配 `permission` 会默认允许所有操作 |
|
||
| 3. OpenClaw ACP 非交互权限失败 | 默认 `approve-reads` + `nonInteractivePermissions=fail`，写文件/执行命令可能直接失败 |
|
||
| 4. 改太多配置层不知谁生效 | OpenCode 配置是 merge + precedence，建议只用全局 + 项目两层 |
|
||
|
||
---
|
||
|
||
## 参考文档
|
||
|
||
- [ACP Agents - OpenClaw](https://docs.openclaw.ai/tools/acp-agents)
|
||
- [acp - OpenClaw](https://docs.openclaw.ai/cli/acp)
|
||
- [Configuration - OpenClaw](https://docs.openclaw.ai/gateway/configuration)
|
||
- [Config | OpenCode](https://opencode.ai/docs/config/)
|
||
- [Providers | OpenCode](https://opencode.ai/docs/providers/)
|
||
- [Permissions | OpenCode](https://opencode.ai/docs/permissions/)
|
||
- [Rules | OpenCode](https://opencode.ai/docs/rules)
|
||
- [CLI | OpenCode](https://opencode.ai/docs/cli/)
|
||
|
||
---
|
||
|
||
## 下一步行动
|
||
|
||
1. 在 `~/.openclaw/openclaw.json` 中添加 ACP Agents 配置
|
||
2. 运行 `openclaw plugins install @openclaw/acpx`
|
||
3. 运行 `/acp doctor` 检查后端状态
|
||
4. 在 `~/.config/opencode/opencode.jsonc` 中配置全局权限和模型
|
||
5. 在目标项目中创建 `AGENTS.md` 和 `opencode.json`
|
||
|
||
---
|
||
|
||
**Source:** 2026-03-16 讨论总结，基于 OpenClaw 和 OpenCode 官方文档
|