第八章：高手进阶 —— Agents、Commands、Skills 与 MCP

这一章把过时的社区“偏方”清理掉，改成 2026 年仍然可靠的官方高级玩法： 自定义 agent、自定义 command、.opencode 目录扩展、MCP 接入。

1. build / plan 之外，你还能自定义 agent

OpenCode 默认内置 build 和 plan 两个 primary agent；你也可以通过配置增加自己的专用 agent。

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "专门做代码评审",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on correctness, security, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  },
  "default_agent": "build"
}

你也可以把 agent 写成 markdown 文件，放进 .opencode/agents 或 ~/.config/opencode/agents 目录中。

2. 用 commands 把重复任务模板化

当你经常让 OpenCode 做某类固定动作，例如“跑测试并解释失败原因”，最好的做法不是每次重打一遍，而是定义 command。

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite, summarize failures, and propose fixes.",
      "description": "运行测试并总结失败原因",
      "agent": "build"
    }
  }
}

这是用户需求很高的一类内容，因为它能把“Prompt 技巧”沉淀成团队资产。你不需要每次都重新描述“跑测试并总结问题”，而是可以直接用 /test 这类自定义命令。

推荐优先做的 3 个命令

• `/test`：运行测试并总结失败原因。
• `/review-changes`：读取最近提交或 diff，生成评审意见。
• `/ship-check`：发布前检查 lint、test、env 和关键路径。

命令文件版比 JSON 更好维护

---
description: Review recent changes
agent: plan
---

Recent git commits:
!`git log --oneline -10`

Review these changes and point out risks, regressions, and missing tests.

对团队来说，把命令写在 .opencode/commands/*.md 往往比塞进一个很长的 JSON 更容易维护，也更适合代码评审。

3. `.opencode` 目录是项目级定制中心

新版文档已经明确推荐使用复数目录名。最常见的结构包括：

• .opencode/agents：自定义 agent
• .opencode/commands：项目命令模板
• .opencode/skills：扩展技能来源
• .opencode/plugins：插件扩展
• .opencode/themes：主题和界面扩展

单数目录虽然还能兼容，但已经不建议作为新项目的主写法。

4. Plugins：把 OpenCode 变成团队专属工具

插件是 2026 年特别值得补充的内容。很多教程会提到 MCP，但真正能让重度用户形成粘性的，往往是插件和命令的组合。

两种加载方式

• 本地插件：放进 .opencode/plugins/ 或 ~/.config/opencode/plugins/
• npm 插件：通过 plugin 数组从 npm 加载

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-helicone-session",
    "opencode-wakatime",
    "@my-org/custom-plugin"
  ]
}

插件最常见的 4 个用途

• 通知：任务完成时发系统通知。
• 安全防护：阻止读取 `.env` 或敏感文件。
• 环境注入：在 shell 中自动注入统一环境变量。
• 自定义工具：给 OpenCode 添加你自己的 tool。

一个很实用的本地插件例子

export const EnvProtection = async () => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    },
  }
}

这类插件非常适合企业项目，因为它解决的是“安全边界”问题，而不是纯粹的功能炫技。

社区增强插件怎么看？

除了官方插件机制，社区里也有一些增强套件，比如专注于多智能体协作、任务编排、会话增强的项目。我的建议是：

• 先掌握官方插件系统，再尝试社区增强包。
• 先看它是否基于当前版本 OpenCode，避免照抄过时教程。
• 优先安装“解决具体问题”的插件，而不是一次装一堆花哨增强。

5. Skills 与 Agents：给不同任务不同人格

高级用户普遍会把“写代码”“做评审”“查文档”“排故障”拆成不同 agent，而不是永远只用默认 build。

为什么这比一个万能 Prompt 更强？

• 你可以给 review agent 更严格的权限限制。
• 你可以让 plan agent 用更便宜、偏分析的模型。
• 你可以把高频任务做成可复用的团队模板。

推荐先做的 3 个自定义 agent

• code-reviewer：只读、偏严格、关注风险和测试缺口。
• docs-writer：专门生成文档、变更说明和发布说明。
• debugger：可以跑命令，但不允许随便写文件。

权限是高级玩法的核心

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "review": {
      "mode": "subagent",
      "permission": {
        "edit": "deny",
        "bash": {
          "*": "ask",
          "git diff *": "allow",
          "git log *": "allow"
        }
      }
    }
  }
}

这类配置的价值很大，因为它能让团队放心地“开更多 agent”，而不是担心每个 agent 都有满权限。

6. MCP：连接外部系统的正式入口

对 OpenCode 来说，MCP 的价值是把“聊天”升级成“会调工具的执行环境”。例如接

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

这里需要特别记住：官方文档已经明确使用 mcp ，而不是很多旧文章里的 mcpServers。如果你在升级旧配置，优先对照当前 schema 调整。

最值得先接的 3 类 MCP

• 浏览器类：用来验页面、点按钮、复现前端问题。
• 数据库类：用来查数据、验证修复、补充上下文。
• 项目管理类：例如 Jira、飞书、内部任务系统。

7. 调试配置时别靠猜

一旦你开始混用全局配置、项目配置、`.opencode` 目录和远程默认配置，最容易踩坑的就是“我以为它读到了，实际上没有”。这时最好直接运行：

opencode debug config

这个命令能帮助你看到最终合并后的真实配置，尤其适合排查 MCP 没生效、默认模型不对、agent 没被识别等问题。

8. 高级用户还会用到什么？

• `/share`：把会话分享给团队成员复盘。
• 桌面版 / IDE 扩展：适合不想只待在纯终端里的用户。
• `opencode serve` / `opencode web`：把 OpenCode 暴露成可被其他客户端调用的服务。
• `tui.json`：主题、滚动速度、快捷键等界面级配置。
• 插件加载顺序：全局配置、项目配置、全局插件目录、项目插件目录，会影响谁覆盖谁。