1. Windows 下 OpenCode 部署为什么会卡在模型接入这一步OpenCode 是一个跑在终端里的 AI 编程助手能读代码、改文件、执行命令适合习惯命令行、又想让 AI 深度参与编码流程的开发者。它本身不绑定任何一家模型靠opencode.json里的 provider 配置决定调用谁。问题也恰恰出在这里Windows 用户装完 OpenCode 后第一次打开 TUI 往往发现/models列表是空的或者选了模型发消息直接报连接失败。我见过最多的场景是这样的Node.js 装好了npm install -g opencode-ai也跑通了opencode -v能打印版本号但一进交互界面就懵了——不知道该在哪里填 Key不知道 baseURL 该写什么更不知道腾讯云 Token Plan 的模型 ID 长什么样。官方文档给的是通用结构落到 Windows 的具体路径、PowerShell 的环境变量写法、JSON 里哪些字段必填都需要自己拼。这篇就按「环境准备 → 安装 → 配置落地 → 启动验证 → 报错排查」的顺序走一遍重点放在可复制的配置片段上。同时我会把 TaoToken 的统一 Key 通道接进来做对照这样你手头不管有没有腾讯云的 Key都能先把 OpenCode 的调用链路跑通再决定用哪条通道。适合人群Windows 上想用 OpenCode 做日常编码、但被 provider 配置卡住的开发者。2. TaoToken 统一 Key 与腾讯云 Token Plan 的前置准备先说清楚两条通道的关系避免后面配置时混淆。腾讯云 Token Plan 是腾讯云大模型服务平台推出的套餐订阅后拿到一个sk-开头的 API Key通过https://api.lkeap.cloud.tencent.com/plan/v3这个兼容 OpenAI 协议的端点调用模型包括 DeepSeek、GLM、Kimi、MiniMax 等。它的优势是模型全、有套餐额度适合已经在用腾讯云生态的团队。TaoToken 则是一个统一 Key 的接入层官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它的价值在于你只需要维护一个 Key就能在 OpenCode、Cline、Claude Code 等多个客户端之间切换不用每个工具都去配一遍不同厂商的凭据。对于同时用好几个 AI 编码工具的人来说省掉的是反复找 Key、反复改配置的时间。前置条件清单Windows 10/11PowerShell 或 Windows Terminal 均可Node.js 18 及以上node -v确认腾讯云账号并已订阅 Token Plan 套餐或一个 TaoToken 的 API Key能正常访问对应 API 端点的网络环境获取腾讯云 Key 的路径登录腾讯云大模型服务平台进入 Token Plan 套餐页订阅后在控制台复制专属 Key格式是sk-xxxxxxxx。TaoToken 的 Key 则在控制台的 API Keys 页面生成地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。两个 Key 都建议先复制到记事本后面配置要用。有一点要提醒不要把 Key 直接提交到 Git 仓库。OpenCode 的全局配置放在用户目录下项目配置放在项目根目录后者如果被提交Key 就泄露了。稳妥做法是项目配置里用环境变量引用或者把opencode.json加进.gitignore。3. OpenCode 安装与 opencode.json 配置落地3.1 安装 OpenCodeWindows 上有三种装法选一种即可。npm 安装推荐版本最新npm install -g opencode-aiScoop 安装scoop install opencodeChocolatey 安装choco install opencode装完验证opencode -v能打印出版本号就说明二进制可用了。如果提示opencode 不是内部或外部命令多半是 npm 全局 bin 目录没进 PATH用npm config get prefix看一下路径手动加进系统环境变量。3.2 全局配置接腾讯云 Token Plan全局配置影响所有项目路径固定在C:\Users\用户名\.config\opencode\opencode.json如果.config\opencode目录不存在手动建一下。用记事本或 VS Code 打开opencode.json写入下面这段把$your_api_key换成你的腾讯云 Key{ $schema: https://opencode.ai/config.json, model: tencent/tc-code-latest, provider: { tencent: { npm: ai-sdk/openai-compatible, name: 腾讯云 Token Plan, options: { baseURL: https://api.lkeap.cloud.tencent.com/plan/v3, apiKey: $your_api_key }, models: { tc-code-latest: { name: Auto (自动优选), modalities: { input: [text], output: [text] }, options: { thinking: { type: enabled } } }, deepseek-v4-pro-202606: { name: DeepSeek-V4-Pro, modalities: { input: [text], output: [text] }, options: { thinking: { type: enabled } } }, glm-5: { name: GLM-5, modalities: { input: [text], output: [text] }, options: { thinking: { type: enabled } } }, kimi-k2.5: { name: Kimi-K2.5, modalities: { input: [text], output: [text] }, options: { thinking: { type: enabled } } } } } } }这里三个字段必须写全缺一个都会导致模型列表为空或请求失败Base URLhttps://api.lkeap.cloud.tencent.com/plan/v3API Key你的腾讯云sk-KeyModel ID比如tencent/deepseek-v4-pro-202606注意前缀tencent/是 provider 名不能省3.3 用 TaoToken 统一 Key 做对照配置如果你手头是 TaoToken 的 Key或者想两条通道都留着随时切换可以在同一个opencode.json里再加一个 provider。TaoToken 的 API 端点是 https://taotoken.net/api 同样兼容 OpenAI 协议{ $schema: https://opencode.ai/config.json, model: taotoken/claude-sonnet-4-5, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken 统一通道, options: { baseURL: https://taotoken.net/api, apiKey: $your_taotoken_key }, models: { claude-sonnet-4-5: { name: Claude Sonnet 4.5, modalities: { input: [text], output: [text] } }, gpt-5: { name: GPT-5, modalities: { input: [text], output: [text] } } } } } }两个 provider 可以共存切换时改顶层model字段即可比如从tencent/tc-code-latest换成taotoken/claude-sonnet-4-5。这样你在 OpenCode 里就能按任务类型选模型写业务代码用腾讯云的 DeepSeek做架构讨论切到 TaoToken 上的 Claude。3.4 项目级配置局部覆盖全局在项目根目录建一个opencode.json只影响当前项目会和全局配置合并同名字段局部优先。适合给不同项目配不同的 Key 或默认模型{ $schema: https://opencode.ai/config.json, model: tencent/deepseek-v4-pro-202606, lsp: true, provider: { tencent: { npm: ai-sdk/openai-compatible, name: 腾讯云 (本项目专用), options: { baseURL: https://api.lkeap.cloud.tencent.com/plan/v3, apiKey: $your_project_api_key }, models: { deepseek-v4-pro-202606: { name: DeepSeek-V4-Pro, modalities: { input: [text], output: [text] }, options: { thinking: { type: enabled } } } } } } }lsp: true会开启内置的语言服务器OpenCode 能自动检测项目语言并启动对应的诊断服务写代码时能拿到类型提示和错误标记。4. 启动验证与请求成功结果确认配置写完后进项目目录启动cd D:\projects\my-app opencode进入 TUI 界面后先输/models看模型列表。正常情况下应该能看到腾讯云 Token Plan分组下的Auto (自动优选)、DeepSeek-V4-Pro、GLM-5、Kimi-K2.5等条目。如果列表是空的说明 provider 配置没被读到回到第 5 节排查。选中一个模型输入一句测试创建一个 Hello World 函数用 TypeScript 写如果模型正常返回代码说明调用链路通了。再输/help确认命令系统可用。CLI 模式也可以直接跑一次性任务适合脚本化opencode --model tencent/glm-5 分析 src/utils.js 里的性能问题想验证 TaoToken 通道把--model换成taotoken/claude-sonnet-4-5再跑一次能返回结果就说明两条通道都通了。后台服务模式供桌面应用连接opencode serve --hostname 0.0.0.0 --port 4096Web 界面模式opencode web开启调试日志看请求细节$env:OPENCODE_LOG_LEVEL debug opencode日志会打印出实际请求的 URL、模型 ID 和响应状态排查连接问题时非常有用。5. 常见报错排查401、local proxy failed、模型列表为空5.1 401 Unauthorized最常见的原因是 Key 写错或没生效。检查顺序先确认opencode.json里的apiKey字段确实是完整的sk-开头字符串没有多余空格或换行。然后确认你改的是正确的配置文件——全局配置在C:\Users\用户名\.config\opencode\opencode.json项目配置在项目根目录两个都改了的话局部优先可能你改的全局被项目配置覆盖了。如果 Key 确认无误还是 401用 curl 直接打一次端点排除 OpenCode 本身的问题curl -X POST https://api.lkeap.cloud.tencent.com/plan/v3/chat/completions -H Authorization: Bearer $your_api_key -H Content-Type: application/json -d {model:deepseek-v4-pro-202606,messages:[{role:user,content:hi}]}curl 也返回 401说明 Key 本身有问题去腾讯云控制台重新生成一个。curl 成功但 OpenCode 失败那就是配置文件路径或 JSON 格式的问题。5.2 local proxy failed这个报错通常出现在网络层。OpenCode 通过ai-sdk/openai-compatible发请求如果系统里配了 HTTP 代理但代理不可用就会报 local proxy failed。检查 PowerShell 里的代理环境变量echo $env:HTTP_PROXY echo $env:HTTPS_PROXY如果输出了代理地址但你并不需要清掉Remove-Item Env:HTTP_PROXY Remove-Item Env:HTTPS_PROXY然后重启 OpenCode。另外确认 baseURL 没有拼错https://api.lkeap.cloud.tencent.com/plan/v3结尾不要多加斜杠也不要少写plan。5.3 reading choices 报错这个错误说明请求发出去了、也拿到了响应但响应结构里没有choices字段SDK 解析失败。常见原因是模型 ID 写错比如把deepseek-v4-pro-202606写成了deepseek-v4-pro端点返回了一个错误对象而不是正常的 completion 结构。对照腾讯云控制台的模型列表确认models里的 key 和实际模型 ID 完全一致。另外检查npm字段是不是ai-sdk/openai-compatible写成别的适配器会导致协议不匹配。5.4 模型列表为空/models里什么都没有按这个顺序查第一确认opencode.json是合法 JSON。用 VS Code 打开看有没有红色波浪线或者跑Get-Content opencode.json | ConvertFrom-Json验证。第二确认provider下的models对象不是空的至少有一个模型定义。第三确认顶层model字段引用的模型在models里存在比如tencent/tc-code-latest对应 providertencent下的tc-code-latest。第四重启 OpenCode。配置改动不会热加载必须退出重进。5.5 OAuth 相关报错如果你配了 GitHub MCP 这类需要 OAuth 的远程服务可能会遇到认证失败。OpenCode 的 MCP 认证命令是opencode mcp auth github它会打开浏览器走 OAuth 流程。如果卡住检查默认浏览器是否正常或者手动复制终端里打印的 URL 到浏览器打开。认证凭据存在C:\Users\用户名\.local\share\opencode\auth.json需要重置时删掉对应条目再重新认证。5.6 配置文件位置速查类型路径全局配置C:\Users\用户名\.config\opencode\opencode.json项目配置项目根目录\opencode.json全局 AgentC:\Users\用户名\.config\opencode\agents\项目 Agent项目根目录\.opencode\agents\认证凭据C:\Users\用户名\.local\share\opencode\auth.json排查时优先确认你改的文件和 OpenCode 实际读取的文件是同一个这是 Windows 上最容易踩的坑。6. 把 Key 管好让 OpenCode 长期跑得稳跑通之后日常使用还有几个习惯值得养成。Key 不要硬编码在项目配置里。项目级opencode.json如果进了版本控制Key 就跟着泄露了。稳妥做法是项目配置里只写baseURL和模型定义apiKey用环境变量引用或者干脆把 Key 放在全局配置里项目配置只覆盖模型选择。多通道切换时顶层model字段是唯一开关。你可以在全局配置里同时保留腾讯云和 TaoToken 两个 provider日常写代码用tencent/deepseek-v4-pro-202606遇到需要长上下文推理的任务切到taotoken/claude-sonnet-4-5改一行配置重启即可不用重新填 Key。调试日志用完就关。$env:OPENCODE_LOG_LEVEL debug只在当前 PowerShell 会话有效关掉窗口就恢复了不用担心污染全局环境。最后OpenCode 的配置结构是「全局打底、项目覆盖」理解这一点后多项目多 Key 的管理就清晰了全局放公共的 provider 定义和默认模型每个项目按需覆盖model和专用 Key。这样既不用每个项目重复写一遍 provider又能保证 Key 隔离。