feat(memory): add exec approval config lessons, daily notes, ACP decisions

- 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 相关记录
2026-03-16 20:08:47 +08:00
parent de2b6e968c
commit 9999e3c668
7 changed files with 1077 additions and 0 deletions
--- a/shared/long-term/decisions/acp-agents-integration.md
+++ b/shared/long-term/decisions/acp-agents-integration.md
@@ -0,0 +1,220 @@
+# 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 官方文档