OpenCode Plan / Build 模式配 TaoToken：settings.json 骨架与报错排查

1. 为什么要在 OpenCode 里区分 Plan 和 BuildOpenCode 的 Plan / Build 双模式本质是权限隔离不是「简易版 / 完整版」的区别。Plan 模式只读规划能读全部代码、搜索、分析架构、输出实施计划只允许写.opencode/plans/*.md计划文档禁止 write/edit/patch 改源码也禁止执行 bash。Build 模式是完整权限代理读写编辑新建文件、打补丁、跑 shell、跑测试、装依赖直接改项目源码。这个设计对本地开发者很友好复杂重构先让 AI 出方案你审阅确认后再切 Build 落地避免 AI 乱改业务代码。但问题也出在这里——两个模式的工具权限不同接入统一 Key/API 通道时如果settings.json没配对就会出现「Plan 能聊不能写计划」「Build 鉴权失败」「切了模式不生效」这类问题。我试过把 OpenCode 接到 TaoToken 的统一通道上Plan 和 Build 共用一套 Key配置骨架其实不复杂坑主要在字段层级和模式覆盖上。下面按「前置准备 → 配置骨架 → 验证 → 排障」的顺序走一遍你可以直接抄。2. TaoToken 前置拿 Key、认通道、选对入口TaoToken 在这里的角色是统一 Key/API 通道你不需要为 Plan 和 Build 分别维护两套凭证一个 Key 走同一个 base URL模型和模式由 OpenCode 侧决定。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM配置里就写它。先做三件事第一在控制台创建 API Key。入口走 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建后立刻复制页面刷新后不再完整显示。Key 形如sk-开头的一串字符后面配置里用环境变量引用不要硬编码进仓库。第二确认你要用的模型名。OpenCode 的 Plan 和 Build 可以指向同一个模型也可以分开。建议先用同一个模型跑通链路再按需拆分。模型对话页可以用来快速验证 Key 是否可用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第三如果你打算长期用 OpenCode 做编码和 Agent 任务Coding Plan 比按量更省心入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 字段含义以文档为准。注意Key 只放环境变量settings.json里用${TAOTOKEN_API_KEY}这种引用形式。OpenCode 读取配置时会做变量展开写死明文一旦提交就是事故。3. settings.json 骨架Plan / Build 共用通道OpenCode 的配置文件按优先级分全局和项目级。全局一般在~/.config/opencode/settings.json项目级在项目根目录.opencode/settings.json。项目级覆盖全局模式相关的覆盖写在项目级更稳。下面是一份可直接复制的骨架核心是把 provider 指向 TaoToken 的 API 基址然后给 Plan 和 Build 分别声明模型与权限{ provider: { taotoken: { type: openai-compatible, baseURL: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, models: { default: { name: your-model-name, contextWindow: 128000 } } } }, model: taotoken/default, modes: { plan: { model: taotoken/default, tools: { write: false, edit: false, patch: false, bash: false }, allowedWritePaths: [.opencode/plans/**] }, build: { model: taotoken/default, tools: { write: true, edit: true, patch: true, bash: true } } } }几个字段说明一下。type用openai-compatible因为 TaoToken 提供的是兼容 OpenAI 协议的接口OpenCode 走这个类型最省事。baseURL结尾不要带/v1OpenCode 会自己拼路径多写一层会 404。apiKey用环境变量引用。modes.plan.allowedWritePaths是 Plan 模式唯一放行的写入目录对应.opencode/plans/*.md别把它删了否则 Plan 连计划文档都存不下来。环境变量在 shell 里导出export TAOTOKEN_API_KEYsk-你的Key想持久化就写进~/.zshrc或~/.bashrc然后source一下。Windows 用系统环境变量面板或者 PowerShell 里$env:TAOTOKEN_API_KEYsk-...。提示如果你在项目级和全局都写了provider项目级会整体覆盖同名 provider不是深合并。要么只写一处要么两处字段保持完整。4. 验证请求Plan 出计划、Build 改代码配置写完先别急着上复杂任务用最小用例验证两种模式都能通。第一步启动 OpenCode确认它读到了配置。在项目根目录执行opencode进入交互界面后先看模型标识是不是taotoken/default。如果显示的是别的模型说明model字段没生效回去检查 JSON 有没有语法错误——OpenCode 对 JSON 容错很低多一个逗号就整段忽略。第二步切到 Plan 模式。快捷键Tab循环切换或者直接输入斜杠命令/plan 重构用户登录模块列出所有改动文件说明风险点预期结果是AI 读取相关文件、分析依赖、输出一份 markdown 计划落到.opencode/plans/下。你可以打开那个文件确认内容。如果 AI 试图改源码说明tools.write没关掉Plan 的权限隔离没生效。第三步审阅计划。方案不对就继续对话修正Plan 模式下改计划文档是允许的。确认无误后切 Build/build 执行刚才这份计划预期结果是AI 按计划改源码、跑命令、可能装依赖。这一步如果报鉴权失败问题在 Key 或 baseURL不在模式配置。第四步跑测试验证结果。Build 完成后执行项目自带的测试命令比如npm test或pytest确认改动没破坏功能。整个链路跑通后你会看到 Plan 产出的是.opencode/plans/*.mdBuild 产出的是真实源码变更。两者共用同一个 Key但工具权限完全不同。5. 常见报错排查鉴权失败与模式不生效5.1 鉴权失败401 / 403报错长这样401 Unauthorized或invalid api key。按顺序查先确认环境变量真的导出了。echo $TAOTOKEN_API_KEY看有没有值为空说明 shell 没加载。再确认settings.json里写的是${TAOTOKEN_API_KEY}而不是别的变量名大小写要一致。然后查 baseURL。必须是https://taotoken.net/api结尾不带/v1不带斜杠。写成https://taotoken.net/api/v1会拼成/api/v1/chat/completions之外的路径直接 404 或 401。最后确认 Key 本身有效。去模型对话页发一条消息如果那边也失败就是 Key 的问题重新在控制台创建一个。如果那边正常、OpenCode 失败就是配置引用的问题。5.2 模式不生效切了 Plan 还能写代码现象是/plan之后 AI 依然改源码。原因通常是modes字段没被识别。检查两点一是modes的层级。它必须在顶层和provider、model平级不能塞进provider里面。二是模式名拼写必须是plan和build小写。写成Plan或Planning都不会匹配。还有一种情况项目级配置覆盖了全局但项目级只写了provider没写modes导致模式配置丢失。解决办法是把modes也补进项目级或者干脆只维护一份配置。5.3 Plan 存不下计划文档报错类似permission denied writing .opencode/plans/xxx.md。这是allowedWritePaths没配或路径写错。确认值是[.opencode/plans/**]双星号表示递归匹配。另外确认.opencode/plans/目录存在不存在就手动建一个mkdir -p .opencode/plans5.4 切换后模型没变如果你给 Plan 和 Build 配了不同模型切换后没生效检查modes.plan.model和modes.build.model是否都写了完整标识taotoken/模型名。只写模型名不写 provider 前缀OpenCode 可能回退到默认模型。注意改完settings.json要重启 OpenCode 会话热重载不一定覆盖所有字段。这是最容易忽略的一步。6. 把两种模式用顺手的几个习惯Plan 文档会持久保存在.opencode/plans/这其实是白送的项目开发文档。复杂改动前先/plan把方案和风险点留档过几周回头看改动思路一目了然。小改动比如改配置、修单函数 bug直接 Build 就行不用走 Plan省一轮交互。如果你长期用 OpenCode 跑编码和 Agent 任务建议把 Coding Plan 配上入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 比按量调用更可控。Key 的管理统一在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入字段有疑问就翻文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后提醒一句Plan 和 Build 共用一套 Key 没问题但别把 Build 的完整权限当成默认工作流。先 Plan 后 Build让 AI 的方案先过你的眼这才是这套双模式真正值钱的地方。