1. 为什么新手第一次跑 OpenCode 总会卡在配置上OpenCode 是一个 100% 开源的 AI 编程助手跑在终端里带 TUI 界面支持 MCP 扩展能读代码、改代码、跑命令。它适合谁适合那些不想被某个闭源编辑器绑死、又希望把模型调用统一收口到自己一套 Key 上的开发者。你可以把它理解成“终端里的编程搭子”你在项目目录敲opencode它就在当前仓库里帮你分析、补全、重构。但真正劝退新手的往往不是 OpenCode 本身而是配置。OpenCode 支持 75 模型提供商配置文件又分全局、项目级、环境变量好几层Provider、MCP、Agent、LSP 各有一套写法。很多人装完之后卡在三个地方一是不知道 Key 该往哪填二是settings.json和config.toml傻傻分不清三是 MCP 加进去了但工具调不动。这篇就聚焦“上手配置”这一件事。我会给你可复制的配置骨架、TaoToken 统一 Key/API 通道的接入片段以及启动验证和报错排查动作。目标很明确让你从装完到能对话、能调 MCP一次跑通。先记住一个核心思路——把模型访问收敛到一个统一的 API 通道上后面换模型、加工具都只改一处。2. TaoToken 前置把统一 Key/API 通道准备好在动 OpenCode 配置之前先把“钥匙”准备好。TaoToken 在这里扮演的角色是给你一个统一的 API 通道你只需要一套 Key就能在 OpenCode 里对接多种模型不用为每个 Provider 单独折腾认证。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个地址不加 UTM 参数。你需要提前拿到两样东西一个是 API Key一个是确认好的 API Base URL。Key 的创建入口在控制台的 API Keys 页面地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。进去之后新建一个 Key复制出来先存到本地临时文件里别直接贴在聊天窗口。注意Key 属于敏感凭证建议用环境变量或独立文件引用不要硬编码进会提交到 Git 的配置文件里。如果你只是想先验证模型能不能通可以先用模型对话页面快速试一句地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。确认通道没问题再回到 OpenCode 里做正式配置。这一步的意义在于把“通道是否可用”和“OpenCode 配置是否正确”两个变量拆开排障时不会互相干扰。3. 可复制配置settings.json 与 config.toml 骨架OpenCode 的配置以 JSON/JSONC 为主核心文件通常叫opencode.json放在项目根目录或全局配置目录。很多同学会问settings.json和config.toml在哪——这里要说清楚OpenCode 主配置走 JSONconfig.toml更多出现在别的工具里别混用。下面给你一份可直接改的骨架。先看全局配置路径一般是~/.config/opencode/opencode.json{ $schema: https://opencode.ai/config.json, theme: tokyonight, model: taotoken/your-model-name, small_model: taotoken/your-small-model, autoupdate: true, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} }, models: { your-model-name: { name: 主力模型 }, your-small-model: { name: 轻量模型 } } } } }这里的关键点有三个。第一npm字段用ai-sdk/openai-compatible因为 TaoToken 提供的是 OpenAI 兼容接口这样 OpenCode 才能正确发请求。第二baseURL填https://taotoken.net/api不要多加路径后缀。第三apiKey用{env:TAOTOKEN_API_KEY}引用环境变量避免明文。再看项目级配置放在项目根目录的opencode.json用来覆盖全局设置{ $schema: https://opencode.ai/config.json, model: taotoken/your-model-name, instructions: [AGENTS.md, CONTRIBUTING.md], permission: { edit: allow, bash: ask }, mcp: { context7: { type: remote, url: https://mcp.context7.com/mcp, enabled: true } } }环境变量在 shell 里设置Linux/macOS 写进~/.zshrc或~/.bashrcexport TAOTOKEN_API_KEY你的KeyWindows PowerShell 里则是$env:TAOTOKEN_API_KEY 你的Key配置层级要记牢项目级覆盖全局级环境变量OPENCODE_CONFIG_CONTENT又能运行时覆盖。排障时如果发现改了没生效先确认是不是被更高优先级的配置盖掉了。4. 启动验证与成功结果配置写完进入你的项目目录直接启动cd /path/to/your/project opencode第一次进 TUI先做三件事验证。第一敲/models看列表里能不能看到你配置的taotoken/your-model-name。能看到说明 Provider 注册成功。第二随便问一句“介绍一下这个仓库的结构”如果模型正常返回说明 Key 和通道都通了。第三敲/init让它扫描项目生成AGENTS.md这一步能验证文件读写权限。成功的结果长这样TUI 顶部显示当前模型名你输入问题后能看到流式输出/models列表里有你的 TaoToken 模型条目/init之后项目根目录多出一个AGENTS.md。如果这三步都过说明统一 Key/API 通道接入完成。再验证一下 MCP。在对话里输入类似“用 context7 查一下 Cloudflare Worker 的缓存配置”如果工具被正确调用并返回文档内容说明 MCP 也通了。MCP 的认证命令是opencode mcp auth server-name远程服务需要 OAuth 时用它。提示验证阶段建议先用 Plan 模式Tab 切换只读不改确认模型理解正确后再切 Build 模式动手。5. 本篇常见错排查配置跑不通八成是下面几个原因。我按出现频率排一下。第一个baseURL写错。有人会写成https://taotoken.net/api/v1或者漏掉协议头。正确写法就是https://taotoken.net/api多一段少一段都会 404。改完记得重启 OpenCode配置不会热加载。第二个Key 没被读到。表现是请求返回 401。先确认环境变量在当前 shell 里echo $TAOTOKEN_API_KEY有值再确认配置文件里写的是{env:TAOTOKEN_API_KEY}而不是别的名字。如果你在 GUI 里启动 OpenCode环境变量可能没继承这时改用{file:~/.secrets/taotoken-key}从文件读。第三个模型名对不上。model字段里的名字必须和provider.taotoken.models里定义的键一致否则/models里看不到。建议先只配一个模型跑通再加第二个。第四个MCP 工具调不动。远程 MCP 需要认证的先跑opencode mcp auth本地 MCP 检查command数组能不能在终端里手动执行成功。另外 MCP 加太多会撑大上下文用tools字段按需禁用。第五个/undo不工作。这个功能依赖 Git项目不是 Git 仓库时用不了。先git init再试。如果以上都排查完还是不通回到模型对话页面单独测一次通道确认是通道问题还是 OpenCode 配置问题。通道没问题就逐层检查配置优先级。6. 接下来怎么走按场景选入口跑通基础配置之后你的下一步取决于你要做什么。如果你是要长期写代码、跑 Agent 任务建议直接上 Coding Plan把额度和模型规划好入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它适合那种每天都要和 AI 结对、需要稳定调用的场景。如果你还在验证模型效果、对比不同模型的表现用模型对话页面最直接https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。换模型、试 prompt 都在这里做不用反复改 OpenCode 配置。如果你在接入过程中遇到报错或者想查更细的参数说明去看接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Key 的管理和新建仍在 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。最后给一个我自己的习惯把opencode.json和AGENTS.md一起提交到 Git团队里每个人拉下来就能用同一套模型和规则省得每人配一遍。配置这东西一次配好后面就是纯写代码了。
