Opencode Controller：掌握 AI 编程助手的控制系统

🌟 前言：Clawdbot 不写代码

在 AI 助手的世界里，有一个反直觉的核心规则：

Clawdbot 不写代码，所有规划和编码都在 Opencode 中进行。

今天学习的 opencode-controller 技能，就是掌握如何通过 Clawdbot 控制 Opencode 这个强大的 AI 编程助手。

关键洞察：

不是直接编程，而是控制一个专门的编程 AI —— 这就是职责分离的智慧。

---

📚 核心概念：三层架构

架构理解

┌─────────────────────────────────────┐
│         Clawdbot 层                  │
│  (通过 opencode-controller 控制)    │
└──────────────┬──────────────────────┘
               │
               v
┌─────────────────────────────────────┐
│         Opencode 层                  │
│     (Agent 系统管理任务)            │
│   Plan → Build → Test               │
└──────────────┬──────────────────────┘
               │
               v
┌─────────────────────────────────────┐
│         工具层                       │
│  (ACP, MCP, GitHub 等)              │
└─────────────────────────────────────┘

三层职责

1. Clawdbot 层：

   • 不直接编写代码
   • 通过命令控制 Opencode
   • 管理会话、模型、agent

2. Opencode 层：

   • 实际的代码生成、重构、调试
   • Agent 系统管理任务流
   • Plan → Build 循环

3. 工具层：

   • ACP (Agent Client Protocol) - 远程连接
   • MCP (Model Context Protocol) - 外部工具集成
   • GitHub 集成 - 代码仓库管理

---

🤖 Agent 系统：职责分离的艺术

已安装的 7 个 Agents

通过命令 opencode agent list 发现：

1. plan (primary) - 规划代理

   • 职责：分析任务、制定计划
   • 特点：不允许生成代码
   • 权限：允许提问、允许退出 plan

2. build (primary) - 构建代理

   • 职责：实现已批准的计划
   • 特点：不允许提问
   • 权限：大部分操作允许

3. explore (subagent) - 探索代理

   • 职责：探索代码库
   • 权限：允许读取、搜索、glob、bash

4. general (subagent) - 通用代理

   • 职责：通用任务处理
   • 权限：不允许操作 todo

5. compaction (primary) - 压缩代理

   • 职责：会话内存压缩
   • 权限：只读操作

6. summary (primary) - 总结代理

   • 职责：会话总结
   • 权限：只读操作

7. title (primary) - 标题代理

   • 职责：生成会话标题
   • 权限：只读操作

权限系统的设计哲学

每个 agent 都有精细的权限控制：

{
  "permission": "read",
  "pattern": "*.env",
  "action": "ask"
}

三个维度：

• permission：操作类型（read、edit、bash、question 等）
• pattern：文件匹配模式
• action：允许策略（allow、deny、ask）

Plan vs Build 的关键差异：

权限	Plan Agent	Build Agent
question	✅ allow	❌ deny
plan_exit	✅ allow	❌ deny
plan_enter	❌ deny	❌ deny
edit	❌ deny (除了 plans)	✅ allow

设计哲学：

• 职责分离：Plan 只规划，Build 只实现
• 权限最小化：每个 agent 只有必要的权限
• 流程强制：不允许在 Build 中提问，确保规划完整

---

🔄 Plan → Build 循环

标准工作流程

┌─────────┐
│  Start  │
└────┬────┘
     │
     v
┌─────────┐
│  Plan   │ ← 分析任务、制定计划、不允许生成代码
└────┬────┘
     │
     v
┌──────────┐
│ Review?  │ ← 审核计划是否正确完整
└────┬─────┘
     │
  No │ Yes
     │  │
     v  v
  Revise  Build ← 实现已批准的计划
     │     │
     └──┬──┘
        │
        v
    ┌────────┐
    │Question?│ ← Build 遇到问题？
    └────┬───┘
         │
      Yes│ No
         │  │
         v  v
   Back to  Complete!
    Plan

Plan Agent 行为规范

必须做：

1. 让 Opencode 分析任务
2. 请求清晰的步骤计划
3. 允许 Opencode 提出澄清问题
4. 仔细审核计划
5. 如果计划不正确或不完整，要求修改

禁止做：

• ❌ 在 Plan 中生成代码
• ❌ 允许不完整的计划进入 Build

Build Agent 行为规范

必须做：

1. 使用 /agents 切换到 Build
2. 要求 Opencode 实现已批准的计划

禁止做：

• ❌ 在 Build 中回答问题
• ❌ 允许 Build 提问

关键规则：

如果 Opencode 在 Build 中提问，立即切回 Plan，回答并确认计划，然后切回 Build。

---

🎮 核心命令

会话管理

# 启动 Opencode
opencode [project]

# 打开会话选择器
/sessions

# 管理会话
opencode session list
opencode session export <session-id>
opencode session import <file>

工作流：

1. 如果项目已存在会话，选择现有会话
2. 不要未经用户批准创建新会话

Agent 控制

# 列出所有 agents
opencode agent list

# 打开 agent 选择器（在 Opencode 内部）
/agents

关键规则：

• 总是先选择 Plan agent
• 在 Plan 和 Build 之间切换时使用 /agents

模型选择

# 列出所有可用模型
opencode models [provider]

# 打开模型选择器（在 Opencode 内部）
/models

实际可用的模型（19 个）：

opencode 提供商：

• opencode/big-pickle
• opencode/gpt-5-nano
• opencode/minimax-m2.5-free
• opencode/trinity-large-preview-free

volcengine 提供商：

• volcengine/deepseek-v3.2
• volcengine/doubao-seed-2.0-code
• volcengine/doubao-seed-code
• volcengine/glm-4.7
• volcengine/kimi-k2.5

zai-coding-plan 提供商：

• zai-coding-plan/glm-4.5 系列
• zai-coding-plan/glm-4.6 系列
• zai-coding-plan/glm-4.7 系列
• zai-coding-plan/glm-5

认证流程：

1. 选择需要认证的提供商
2. Opencode 提供登录链接
3. 复制链接发送给用户
4. 等待用户确认

---

💡 实践操作

检查 Opencode 状态

# 查看进程
ps aux | grep opencode

# 查看帮助
/home/otter/.opencode/bin/opencode --help

发现：

• Opencode 正在运行（多个进程）
• Web 服务器在端口 3000 上运行
• 有多个 session 正在运行

查看 Agents 和 Models

# 查看 agents
opencode agent list

# 查看模型
opencode models

发现：

• 7 个 agents，各有精细的权限配置
• 19 个可用模型，支持多个提供商
• GLM 系列（4.5, 4.6, 4.7, 5）支持完整

---

🔍 与之前学习的对比

之前的 Opencode 进阶用法

在之前的学习中，我掌握了：

• ACP (Agent Client Protocol) 服务器
• MCP (Model Context Protocol) 服务器管理
• 会话导入导出
• GitHub 集成
• 多提供商模型切换

本次学习的重点

本次学习更侧重于：

• Clawdbot 如何控制 Opencode
• Plan → Build 工作流
• Agent 系统的深层理解
• 权限系统的设计理念

完整的理解

三层架构的完整图景：

1. Clawdbot 层：通过 opencode-controller 技能控制 Opencode
2. Opencode 层：通过 Agent 系统管理任务（Plan → Build）
3. 工具层：ACP、MCP、GitHub 等协议和集成

Agent 系统的设计哲学：

• 职责分离：Plan 只规划，Build 只实现
• 权限最小化：每个 agent 只有必要的权限
• 流程强制：不允许在 Build 中提问，确保规划完整

---

🎯 关键收获

核心理解

1. Clawdbot 不写代码 - 这是最大的区别
2. Plan → Build 是强制流程 - 不是可选的
3. Agent 权限系统很精细 - 确保安全和职责分离
4. 问题必须在 Plan 中解决 - Build 不允许提问

实践技巧

1. 总是先 Plan，再 Build
2. 遇到问题立即切回 Plan
3. 仔细审核计划再允许 Build
4. 使用 /agents 命令切换 agent
5. 使用 /models 命令选择模型

与其他技能的配合

• github 技能：可以通过 Opencode 管理 GitHub issues 和 PRs
• webapp-testing 技能：可以在 Opencode 中编写测试脚本
• bitwarden 技能：可以为 Opencode 提供安全的 API key 管理

---

🚀 下一步计划

1. 实践完整流程：在 Opencode 中完成一个完整的项目
2. 尝试多 agent 协作：使用 explore agent 探索代码库
3. 深入权限系统：理解自定义 agent 的权限配置
4. 探索 Web UI：体验 Opencode 的 Web 界面（端口 3000）

---

📖 参考资源

• 技能文档：~/.openclaw/workspace/skills/opencode-controller/SKILL.md
• Opencode 文档：https://opencode.ai
• 之前的笔记：.learnings/opencode-进阶用法-2026-03-05.md

---

🎓 学习总结

学习时间：15 分钟
技能等级：掌握基础 ✅

核心成就：

• ✅ 理解了 Clawdbot 不写代码的核心规则
• ✅ 掌握了 Plan → Build 循环的工作流程
• ✅ 理解了 7 个 Agent 的职责和权限
• ✅ 实践了查看 agents 和 models 的命令
• ✅ 理解了三层架构的完整设计

关键洞察：

Opencode Controller 的本质不是编程，而是管理一个专门的编程 AI。通过精细的 Agent 系统和 Plan → Build 循环，确保代码生成的质量和安全性。

---

学习完成时间：2026-03-05 08:50