先使用 Plan 理解问题与修改方案，再使用 Build 实现和验证。旧教程中的“模式”，当前通过 OpenCode 的**主代理（primary agents）**配置。本页保留原有 URL，方便继续使用收藏的链接。
以下行为已于 2026 年 10 月 2 日对照官方代理文档核对。OpenCode Tutorial 是独立教程站。
Plan 与 Build 应该怎么选？
| 任务 | 建议起点 | 期望结果 |
|---|---|---|
| 理解陌生仓库 | Plan | 相关文件与当前行为的说明 |
| 比较实现方案 | Plan | 方案、取舍与受影响的文件 |
| 实现已确认的修改 | Build | 代码差异与验证结果 |
| 调查失败测试 | 先 Plan，再 Build | 原因、针对性修复与通过的测试 |
| 审查完成的修改 | Plan | 对代码差异的发现与疑问 |
Build 是默认主代理，可以使用全部工具。Plan 的权限更受限：官方默认设置会在文件编辑和 bash 命令执行前询问。项目或全局权限可以覆盖这些默认值，行为不一致时应检查配置。
不能把 Plan 理解为无条件保证不执行命令、不修改文件。如果需要明确禁止某类操作，请设置对应限制。
如何切换 Plan 与 Build
在终端界面按 Tab 循环切换主代理，并确认界面显示的代理名称。自定义键盘设置可能使用不同的 switch_agent 快捷键，参阅快捷键配置。
切换代理不会自动执行之前的方案。审阅方案后，应向 Build 发出明确的实现请求。
一个实际工作流程
假设设置页面刷新后丢失已保存的偏好。先在 Plan 中提出具体请求：
追踪设置页面保存偏好的流程。找出保存的值为何可能在刷新后丢失，
列出相关文件并提出修复方案，暂时不要实现。
检查诊断是否解释了实际现象。有效方案应指出状态存在哪里、启动时如何读取，以及哪个测试可以复现问题。与其列一长串通用原则，不如回答这些具体问题。
切换至 Build 后提出实现请求：
实现刚才的持久化修复，修改范围限定在设置流程。
运行现有的相关测试，并解释最终的代码差异。
接受结果前，复现原始问题、检查差异，并确认测试覆盖了这次失败。不能只依据代理宣称“已完成”来判断修复成功。
为 Plan 配置更严格的权限
希望 Plan 明确禁止编辑和 shell 命令时，把以下字段合并到已有 opencode.json：
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"plan": {
"permission": {
"edit": "deny",
"bash": "deny"
}
}
}
}
这是主动覆盖默认设置，也会阻止 Plan 通过 shell 查看信息和运行测试。如果希望逐次决定，可以把相应权限设为 "ask"。权限指南介绍了完整配置方式。
迁移旧的 mode 配置
本站旧示例使用过顶层 mode 和 .opencode/modes/。当前指南使用：
- 在
opencode.json中通过agent配置代理。 - 在
.opencode/agents/中存放项目 Markdown 代理定义。 - 在
~/.config/opencode/agents/中存放全局 Markdown 代理定义。 - 通过
switch_agent配置切换快捷键。
先备份旧配置，再按原来的用途迁移，不要把旧字段直接复制到新文件。代理指南介绍主代理与自定义代理；使用新版本时应对照官方文档核对。
常见问题
Plan 会写文件吗？
默认编辑权限会先询问。如果要禁止编辑，将 agent.plan.permission.edit 设为 "deny"，同时检查项目配置是否覆盖了全局设置。
为什么 Build 仍会询问权限？
工具可用性和权限设置是两个因素。项目策略或自定义配置可以要求特定操作先经过确认，即使当前使用的是 Build。
哪个模式能解决 LSP 问题？
切换到 Build 不会自动启用语言服务器。请按照 OpenCode LSP 配置与故障排查检查配置及服务器的运行条件。
尚未安装应用时，从安装指南开始。