1. 为什么要在终端里折腾 OpenCode 这套双模式如果你平时写代码的场景是 SSH 到远程机器、在 tmux 里开好几个 pane、或者干脆懒得离开命令行那 OpenCode 这类终端 AI 助手会比 IDE 插件顺手得多。它是一款跑在 Terminal 里的 AI 编程工具核心卖点是 Plan 与 Build 双模式Plan 阶段只读代码、只出方案不碰你的文件Build 阶段才真正生成 diff 并落盘。这个分离机制解决了一个很常见的痛点——大多数 AI 编程工具一上来就改代码逻辑跑偏了你还得手动回滚。OpenCode 适合谁适合已经习惯命令行、手里有多个模型 API、想把「需求分析 → 方案确认 → 代码落地」串成一条流水线的人。它不绑定模型供应商只要对方兼容 OpenAI 格式的接口就能接。这篇就围绕 Plan/Build 双模式、Slash 命令体系以及怎么用统一的 Key/API 通道把它接起来给出一份可以直接抄的配置骨架并演示一次模式切换加命令调用的完整验证。我试过把同一套配置在本地 WSL 和远程开发机上各跑一遍下面按「先接通道、再配骨架、最后验证」的顺序来。2. TaoToken 前置统一 Key 与 API 通道怎么准备OpenCode 本身不提供模型它需要一个兼容 OpenAI 格式的推理端点。TaoToken 在这里扮演的就是统一通道的角色一个 Key、一个 API Base后面无论你切 GLM、DeepSeek 还是别的模型都改配置里的模型名就行不用每个供应商单独维护一套鉴权。先把地址记清楚官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Basehttps://taotoken.net/api 这个不加 UTM配置里直接填操作路径是进官网 → 登录 → 打开控制台 → 在 API Keys 页面创建一个新 Key。创建时建议按用途命名比如opencode-dev方便以后区分是哪个工具在用。Key 只在创建时完整显示一次复制后先存到本地环境变量里别直接写进会提交到 git 的配置文件。# 写入 shell 配置避免 Key 出现在代码仓库里 echo export TAOTOKEN_API_KEYsk-你的Key ~/.bashrc source ~/.bashrc # 验证变量已生效 echo $TAOTOKEN_API_KEY | head -c 8这里有个细节OpenCode 读配置时既支持直接写 Key也支持读环境变量。生产习惯上我更推荐环境变量配置文件里只留变量名。控制台里还能看到用量统计方便你判断是不是某个 Agent 把上下文撑爆了。3. 可复制配置settings.json 与 config.toml 骨架OpenCode 的配置分两层一层是全局的模型与通道定义一层是项目级的模式与命令行为。不同版本对文件名有差异常见的是~/.opencode/config.json或config.toml项目根目录下则是.opencode/目录。下面给一份能直接用的骨架重点看apiBase和apiKey两处怎么指向 TaoToken。{ models: [ { name: glm-4.7, provider: openai-compatible, apiBase: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, contextWindow: 128000 }, { name: deepseek-v3, provider: openai-compatible, apiBase: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, contextWindow: 64000 } ], defaultModel: glm-4.7, modes: { plan: { readOnly: true, autoApply: false }, build: { readOnly: false, autoApply: true } } }如果你用的是 TOML 版本等价写法是这样default_model glm-4.7 [[models]] name glm-4.7 provider openai-compatible api_base https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} context_window 128000 [modes.plan] read_only true auto_apply false [modes.build] read_only false auto_apply true关键参数对照一下方便你按自己项目调参数作用建议值apiBase推理端点地址https://taotoken.net/apiapiKey鉴权 Key用环境变量引用contextWindow上下文上限按模型实际能力填modes.plan.readOnlyPlan 是否只读truemodes.build.autoApplyBuild 是否自动落盘先 false 观察注意autoApply第一次配的时候建议设成 false让 Build 阶段先输出 diff 给你看确认没问题再改成 true。直接自动写文件遇到大重构容易一次改乱好几个文件。项目级配置放在.opencode/config.json可以覆盖全局的默认模型。比如某个仓库专门做前端就把它默认指到上下文更长的模型上。4. 验证请求一次模式切换与 Slash 命令调用配置写完先别急着上复杂任务用一个小需求把「Plan → 切换 → Build」这条链路跑通。启动 OpenCode 后默认进 Plan 模式此时它只读不写。第一步在 Plan 模式下描述需求并把相关文件加进上下文/add src/utils/*.js 请分析这些工具函数的依赖关系给出一个把日期格式化逻辑抽成独立模块的实施计划先不要改代码。Plan 模式会输出一份自然语言方案列出要动哪些文件、新增哪些函数。如果它理解偏了继续对话修正直到方案你认可为止。第二步确认方案后切换模式。两种方式都行按Tab键或者直接输入斜杠命令/build第三步Build 模式基于刚才的 Plan 执行生成 diff。如果autoApply是 false它会先把改动展示出来已生成 3 处变更 - src/utils/date.js 新增 formatDate / parseDate - src/utils/index.js 移除旧实现并 re-export - src/utils/date.test.js 新增用例 确认应用(y/n)输入y落盘。到这里一次完整的双模式工作流就跑通了。几个高频 Slash 命令建议一起记住命令功能什么时候用/init初始化项目配置新仓库首次接入/add添加文件到上下文需要 AI 读特定代码/compact压缩上下文历史Token 快满或话题跑偏/undo撤销上一步改错文件或 Plan 方向错/review代码审查提交前自查/add支持通配符但别一上来就/add .大项目会瞬间把上下文撑满。配合/compact定期压缩是控制成本的关键。5. 本篇常见错排查报 401 或鉴权失败先确认环境变量在当前 shell 里真的生效了echo $TAOTOKEN_API_KEY看有没有值。如果配置文件里写的是${TAOTOKEN_API_KEY}但 OpenCode 没做变量展开就换成直接读环境变量的写法或者临时把 Key 填进去测一次排除是变量问题还是 Key 本身问题。Plan 模式却改了文件检查modes.plan.readOnly是不是被项目级配置覆盖成了 false。项目级.opencode/config.json优先级高于全局两个地方都看一眼。上下文溢出 Context Full立刻执行/compact再用/drop移除无关文件。根因通常是/add加太猛遵守最小权限原则只加和当前任务相关的文件。Build 生成的代码有幻觉多半是 Plan 阶段太粗。执行/undo回退回到 Plan 模式要求它「列出具体函数名和变更逻辑」确认无误再切 Build。Windows 下路径解析出错OpenCode 对 Unix 环境支持最好Windows 建议在 WSL2 里跑直接 PowerShell 可能遇到\和/的兼容问题导致上下文读取失败。切换模式没反应确认当前焦点在 OpenCode 的输入框里Tab键有时会被终端本身截获。这种情况直接用/build命令更稳。6. 把通道和模式固定下来配置这件事一次调顺后面就省心。我的习惯是把模型定义和模式行为都收进全局配置项目级只覆盖默认模型这样换仓库不用重配一遍。Key 走环境变量apiBase统一指向 https://taotoken.net/api 以后想换模型只改defaultModel一行。如果你主要做长期编码或者要接 Agent 流水线可以看下 Coding Plan 这类按周期计费的方式比按次调用更适合高频场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content需要新建或管理 Key 的时候走这里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想先在网页里验证模型通不通用模型对话页试一句最快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后留一个我踩过的坑autoApply别急着开 true先让 Build 出 diff 观察几次确认模型对你这个代码库的理解稳定了再放开自动落盘。
