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