collective-memory-repo/shared/long-term/decisions/acp-agents-integration.md

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)

{
  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

{
  "$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 默认允许所有操作，必须显式配置：

{
  "permission": {
    "*": "ask",
    "bash": "ask",
    "edit": "ask"
  }
}

OpenClaw ACP 会话默认：permissionMode=approve-reads + nonInteractivePermissions=fail

最佳实践：

• OpenCode 侧：bash/edit 设成 ask
• OpenClaw 侧：明确哪些任务走交互，哪些只读

3) 项目规则 / 指令

{
  "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 原生支持

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
• acp - OpenClaw
• Configuration - OpenClaw
• Config | OpenCode
• Providers | OpenCode
• Permissions | OpenCode
• Rules | OpenCode
• CLI | OpenCode

---

下一步行动

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 官方文档