OpenCode 进阶使用手册

结论

OpenCode 的进阶使用不是堆叠 Plugin，而是建立清晰的职责边界：

配置与 Provider
  ↓
项目 instructions
  ↓
Primary Agent / Subagent
  ↓
Skill / Command
  ↓
内置工具 / MCP
  ↓
Permission 与真实验收

一、配置层级

常用位置：

全局：~/.config/opencode/opencode.json
项目：./opencode.json 或 ./opencode.jsonc
项目资源：.opencode/

OpenCode 从当前目录向工作树根查找项目配置，各层配置深度合并，项目配置覆盖全局。每次修改后退出并重启，运行中的会话不会自动重新加载。

完整加载顺序从低到高包括：组织 Remote config、全局配置、OPENCODE_CONFIG、项目配置、.opencode/ 资源、OPENCODE_CONFIG_CONTENT，以及管理员 Managed config。排障时应以 opencode debug config 的最终合并结果为准。

推荐职责：

全局配置	项目配置
通用 Provider	项目默认模型
Secret 文件引用	项目 instructions
通用 MCP	项目专用 MCP
通用 Skill	项目 Agent/Skill/Command
通用安全权限	项目额外权限

二、Provider 与 Secret

Provider 定义保留在配置，Secret 使用文件或环境变量引用：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "company/model-name",
  "provider": {
    "company": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "{file:~/.config/opencode/secrets/base_url}",
        "apiKey": "{file:~/.config/opencode/secrets/api_key}"
      },
      "models": {
        "model-name": { "name": "model-name" }
      }
    }
  }
}

不要在 headers.Authorization 和 apiKey 中重复维护两份 Secret，除非服务端明确要求两者。

验证最终合并配置时，输出可能包含脱敏 Secret 摘要；不要把完整输出贴入公开 Issue 或笔记。

三、Agent

内置常用 Agent：

Agent	模式	用途
build	primary	实现、修改、测试
plan	primary	只读分析与方案
general	subagent	通用子任务
explore	subagent	代码库搜索与探索

复杂自定义 Agent 建议使用文件：

.opencode/agents/reviewer.md

---
description: Reviews changes for correctness and security.
mode: subagent
permission:
  edit: deny
  bash: ask
---

Review the requested diff. Report findings with file and line evidence.
Do not modify files.

原则：

• Primary Agent 接用户任务并负责编排。
• Subagent 专注单一职责。
• 审查、探索类 Agent 默认禁止 edit。
• 部署 Agent 不使用宽泛 bash: allow。
• default_agent 指向非隐藏的 Primary Agent。

四、Skill 与 Command

Skill

解决“某类任务怎样做”，按需加载：

.opencode/skills/<name>/SKILL.md
~/.config/opencode/skills/<name>/SKILL.md

Command

解决“用户如何稳定启动一个固定流程”：

.opencode/commands/deploy.md

---
description: Deploy the selected environment
agent: build
---

Validate the target from `$ARGUMENTS`, show the plan, then ask before deployment.

选择规则：

情况	机制
Agent 应自动识别某类任务	Skill
用户需要 /name 固定入口	Command
所有项目任务必须遵守	AGENTS.md / instructions
需要新的运行时钩子或工具	Plugin

五、MCP

{
  "mcp": {
    "docs": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:DOCS_MCP_TOKEN}"
      }
    },
    "internal": {
      "type": "local",
      "command": ["C:\\tools\\internal-mcp.exe"],
      "enabled": true,
      "environment": {
        "API_TOKEN": "{env:INTERNAL_MCP_TOKEN}"
      }
    }
  }
}

本地 MCP 使用 environment，远程 MCP 使用 headers；Secret 用 {env:VAR} 引用。默认连接超时较短，启动慢的本地服务应显式配置合理的 timeout 和固定 cwd。

MCP 只接入高价值能力：

• Web 搜索；
• 当前框架文档；
• 代码库检索；
• 公司 DevOps；
• 浏览器自动化；
• 数据库只读查询。

六、Permission

动作只有：allow、ask、deny。

{
  "permission": {
    "edit": "allow",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "rm *": "deny"
    },
    "external_directory": {
      "*": "ask",
      "~/projects/**": "allow",
      "~/secrets/**": "deny"
    }
  }
}

规则按最后匹配项生效，因此先写宽泛规则，再写更具体规则。

权限分层建议：

操作	权限
读取、搜索、Git diff	allow
安装依赖、修改文件、创建资源	ask 或按项目 allow
删除、强推、生产部署	deny 或人工批准
Secret 目录	deny

七、Plugin

Plugin 能修改配置、工具、权限、消息和生命周期，影响范围最大。使用原则：

1. 原生能力能完成时不用 Plugin。
2. 同一类增强框架只保留一个主要实现。
3. 固定版本，避免升级后行为漂移。
4. 用 opencode --pure 或 OPENCODE_PURE=1 隔离排障。
5. 检查 Plugin 注入的 Agent、MCP 和权限，不只看配置文件。

八、日常工作流

实现功能

1. plan 明确目标、范围和验收
2. explore 查现有模式
3. build 实现
4. 运行测试和构建
5. 审查 Git diff
6. 修复问题后再提交

一次性自动任务

opencode run "实现需求，运行测试，并报告修改文件和真实结果"

会话与排障

opencode --version
opencode debug paths
opencode debug config
opencode debug info
opencode debug skill
opencode agent list
opencode mcp list
opencode session list
opencode --pure

九、配置损坏时

$env:OPENCODE_DISABLE_PROJECT_CONFIG = '1'
opencode

或指定临时配置：

$env:OPENCODE_CONFIG = 'C:\path\safe-opencode.json'
opencode

修复后清除环境变量并重启。

十、Session 与 Worktree

opencode -c
opencode -s <session-id>
opencode -c --fork
opencode -s <session-id> --fork

OpenCode 内置的是 Session 继续、分叉和父子会话。Git worktree 仍是 Git 的隔离机制；官方生态中的 worktree Plugin 不应写成 OpenCode 内置命令。Plugin/Tool 上下文中的 directory 是当前会话目录，worktree 是 Git 工作树根目录，两者不能混用。

十一、验证清单

[ ] Schema 校验通过
[ ] debug config 符合预期
[ ] Agent/Skill/Command 来源清楚
[ ] MCP 全部真实 connected
[ ] 写操作权限没有被宽泛 allow 覆盖
[ ] Secret 不在可提交文件中
[ ] 用目标模型完成最小真实任务
[ ] 修改代码后测试、构建和 diff 均已检查

参考资料

• OpenCode Config
• Agents
• Skills
• Commands
• Plugins
• MCP Servers
• Permissions