1. Windows 下 OpenCode 部署為什么會(huì)卡在模型接入這一步OpenCode 是一個(gè)跑在終端里的 AI 編程助手能讀代碼、改文件、執(zhí)行命令適合習(xí)慣命令行、又想讓 AI 深度參與編碼流程的開發(fā)者。它本身不綁定任何一家模型靠opencode.json里的 provider 配置決定調(diào)用誰。問題也恰恰出在這里Windows 用戶裝完 OpenCode 后第一次打開 TUI 往往發(fā)現(xiàn)/models列表是空的或者選了模型發(fā)消息直接報(bào)連接失敗。我見過最多的場(chǎng)景是這樣的Node.js 裝好了npm install -g opencode-ai也跑通了opencode -v能打印版本號(hào)但一進(jìn)交互界面就懵了——不知道該在哪里填 Key不知道 baseURL 該寫什么更不知道騰訊云 Token Plan 的模型 ID 長(zhǎng)什么樣。官方文檔給的是通用結(jié)構(gòu)落到 Windows 的具體路徑、PowerShell 的環(huán)境變量寫法、JSON 里哪些字段必填都需要自己拼。這篇就按「環(huán)境準(zhǔn)備 → 安裝 → 配置落地 → 啟動(dòng)驗(yàn)證 → 報(bào)錯(cuò)排查」的順序走一遍重點(diǎn)放在可復(fù)制的配置片段上。同時(shí)我會(huì)把 TaoToken 的統(tǒng)一 Key 通道接進(jìn)來做對(duì)照這樣你手頭不管有沒有騰訊云的 Key都能先把 OpenCode 的調(diào)用鏈路跑通再?zèng)Q定用哪條通道。適合人群Windows 上想用 OpenCode 做日常編碼、但被 provider 配置卡住的開發(fā)者。2. TaoToken 統(tǒng)一 Key 與騰訊云 Token Plan 的前置準(zhǔn)備先說清楚兩條通道的關(guān)系避免后面配置時(shí)混淆。騰訊云 Token Plan 是騰訊云大模型服務(wù)平臺(tái)推出的套餐訂閱后拿到一個(gè)sk-開頭的 API Key通過https://api.lkeap.cloud.tencent.com/plan/v3這個(gè)兼容 OpenAI 協(xié)議的端點(diǎn)調(diào)用模型包括 DeepSeek、GLM、Kimi、MiniMax 等。它的優(yōu)勢(shì)是模型全、有套餐額度適合已經(jīng)在用騰訊云生態(tài)的團(tuán)隊(duì)。TaoToken 則是一個(gè)統(tǒng)一 Key 的接入層官網(wǎng)在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它的價(jià)值在于你只需要維護(hù)一個(gè) Key就能在 OpenCode、Cline、Claude Code 等多個(gè)客戶端之間切換不用每個(gè)工具都去配一遍不同廠商的憑據(jù)。對(duì)于同時(shí)用好幾個(gè) AI 編碼工具的人來說省掉的是反復(fù)找 Key、反復(fù)改配置的時(shí)間。前置條件清單Windows 10/11PowerShell 或 Windows Terminal 均可Node.js 18 及以上node -v確認(rèn)騰訊云賬號(hào)并已訂閱 Token Plan 套餐或一個(gè) TaoToken 的 API Key能正常訪問對(duì)應(yīng) API 端點(diǎn)的網(wǎng)絡(luò)環(huán)境獲取騰訊云 Key 的路徑登錄騰訊云大模型服務(wù)平臺(tái)進(jìn)入 Token Plan 套餐頁訂閱后在控制臺(tái)復(fù)制專屬 Key格式是sk-xxxxxxxx。TaoToken 的 Key 則在控制臺(tái)的 API Keys 頁面生成地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。兩個(gè) Key 都建議先復(fù)制到記事本后面配置要用。有一點(diǎn)要提醒不要把 Key 直接提交到 Git 倉庫。OpenCode 的全局配置放在用戶目錄下項(xiàng)目配置放在項(xiàng)目根目錄后者如果被提交Key 就泄露了。穩(wěn)妥做法是項(xiàng)目配置里用環(huán)境變量引用或者把opencode.json加進(jìn).gitignore。3. OpenCode 安裝與 opencode.json 配置落地3.1 安裝 OpenCodeWindows 上有三種裝法選一種即可。npm 安裝推薦版本最新npm install -g opencode-aiScoop 安裝scoop install opencodeChocolatey 安裝choco install opencode裝完驗(yàn)證opencode -v能打印出版本號(hào)就說明二進(jìn)制可用了。如果提示opencode 不是內(nèi)部或外部命令多半是 npm 全局 bin 目錄沒進(jìn) PATH用npm config get prefix看一下路徑手動(dòng)加進(jìn)系統(tǒng)環(huán)境變量。3.2 全局配置接騰訊云 Token Plan全局配置影響所有項(xiàng)目路徑固定在C:\Users\用戶名\.config\opencode\opencode.json如果.config\opencode目錄不存在手動(dòng)建一下。用記事本或 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 (自動(dòng)優(yōu)選), 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 } } } } } } }這里三個(gè)字段必須寫全缺一個(gè)都會(huì)導(dǎo)致模型列表為空或請(qǐng)求失敗Base URLhttps://api.lkeap.cloud.tencent.com/plan/v3API Key你的騰訊云sk-KeyModel ID比如tencent/deepseek-v4-pro-202606注意前綴tencent/是 provider 名不能省3.3 用 TaoToken 統(tǒng)一 Key 做對(duì)照配置如果你手頭是 TaoToken 的 Key或者想兩條通道都留著隨時(shí)切換可以在同一個(gè)opencode.json里再加一個(gè) provider。TaoToken 的 API 端點(diǎn)是 https://taotoken.net/api 同樣兼容 OpenAI 協(xié)議{ $schema: https://opencode.ai/config.json, model: taotoken/claude-sonnet-4-5, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken 統(tǒng)一通道, 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] } } } } } }兩個(gè) provider 可以共存切換時(shí)改頂層model字段即可比如從tencent/tc-code-latest換成taotoken/claude-sonnet-4-5。這樣你在 OpenCode 里就能按任務(wù)類型選模型寫業(yè)務(wù)代碼用騰訊云的 DeepSeek做架構(gòu)討論切到 TaoToken 上的 Claude。3.4 項(xiàng)目級(jí)配置局部覆蓋全局在項(xiàng)目根目錄建一個(gè)opencode.json只影響當(dāng)前項(xiàng)目會(huì)和全局配置合并同名字段局部?jī)?yōu)先。適合給不同項(xiàng)目配不同的 Key 或默認(rèn)模型{ $schema: https://opencode.ai/config.json, model: tencent/deepseek-v4-pro-202606, lsp: true, provider: { tencent: { npm: ai-sdk/openai-compatible, name: 騰訊云 (本項(xiàng)目專用), 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會(huì)開啟內(nèi)置的語言服務(wù)器OpenCode 能自動(dòng)檢測(cè)項(xiàng)目語言并啟動(dòng)對(duì)應(yīng)的診斷服務(wù)寫代碼時(shí)能拿到類型提示和錯(cuò)誤標(biāo)記。4. 啟動(dòng)驗(yàn)證與請(qǐng)求成功結(jié)果確認(rèn)配置寫完后進(jìn)項(xiàng)目目錄啟動(dòng)cd D:\projects\my-app opencode進(jìn)入 TUI 界面后先輸/models看模型列表。正常情況下應(yīng)該能看到騰訊云 Token Plan分組下的Auto (自動(dòng)優(yōu)選)、DeepSeek-V4-Pro、GLM-5、Kimi-K2.5等條目。如果列表是空的說明 provider 配置沒被讀到回到第 5 節(jié)排查。選中一個(gè)模型輸入一句測(cè)試創(chuàng)建一個(gè) Hello World 函數(shù)用 TypeScript 寫如果模型正常返回代碼說明調(diào)用鏈路通了。再輸/help確認(rèn)命令系統(tǒng)可用。CLI 模式也可以直接跑一次性任務(wù)適合腳本化opencode --model tencent/glm-5 分析 src/utils.js 里的性能問題想驗(yàn)證 TaoToken 通道把--model換成taotoken/claude-sonnet-4-5再跑一次能返回結(jié)果就說明兩條通道都通了。后臺(tái)服務(wù)模式供桌面應(yīng)用連接opencode serve --hostname 0.0.0.0 --port 4096Web 界面模式opencode web開啟調(diào)試日志看請(qǐng)求細(xì)節(jié)$env:OPENCODE_LOG_LEVEL debug opencode日志會(huì)打印出實(shí)際請(qǐng)求的 URL、模型 ID 和響應(yīng)狀態(tài)排查連接問題時(shí)非常有用。5. 常見報(bào)錯(cuò)排查401、local proxy failed、模型列表為空5.1 401 Unauthorized最常見的原因是 Key 寫錯(cuò)或沒生效。檢查順序先確認(rèn)opencode.json里的apiKey字段確實(shí)是完整的sk-開頭字符串沒有多余空格或換行。然后確認(rèn)你改的是正確的配置文件——全局配置在C:\Users\用戶名\.config\opencode\opencode.json項(xiàng)目配置在項(xiàng)目根目錄兩個(gè)都改了的話局部?jī)?yōu)先可能你改的全局被項(xiàng)目配置覆蓋了。如果 Key 確認(rèn)無誤還是 401用 curl 直接打一次端點(diǎn)排除 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 本身有問題去騰訊云控制臺(tái)重新生成一個(gè)。curl 成功但 OpenCode 失敗那就是配置文件路徑或 JSON 格式的問題。5.2 local proxy failed這個(gè)報(bào)錯(cuò)通常出現(xiàn)在網(wǎng)絡(luò)層。OpenCode 通過ai-sdk/openai-compatible發(fā)請(qǐng)求如果系統(tǒng)里配了 HTTP 代理但代理不可用就會(huì)報(bào) local proxy failed。檢查 PowerShell 里的代理環(huán)境變量echo $env:HTTP_PROXY echo $env:HTTPS_PROXY如果輸出了代理地址但你并不需要清掉Remove-Item Env:HTTP_PROXY Remove-Item Env:HTTPS_PROXY然后重啟 OpenCode。另外確認(rèn) baseURL 沒有拼錯(cuò)https://api.lkeap.cloud.tencent.com/plan/v3結(jié)尾不要多加斜杠也不要少寫plan。5.3 reading choices 報(bào)錯(cuò)這個(gè)錯(cuò)誤說明請(qǐng)求發(fā)出去了、也拿到了響應(yīng)但響應(yīng)結(jié)構(gòu)里沒有choices字段SDK 解析失敗。常見原因是模型 ID 寫錯(cuò)比如把deepseek-v4-pro-202606寫成了deepseek-v4-pro端點(diǎn)返回了一個(gè)錯(cuò)誤對(duì)象而不是正常的 completion 結(jié)構(gòu)。對(duì)照騰訊云控制臺(tái)的模型列表確認(rèn)models里的 key 和實(shí)際模型 ID 完全一致。另外檢查npm字段是不是ai-sdk/openai-compatible寫成別的適配器會(huì)導(dǎo)致協(xié)議不匹配。5.4 模型列表為空/models里什么都沒有按這個(gè)順序查第一確認(rèn)opencode.json是合法 JSON。用 VS Code 打開看有沒有紅色波浪線或者跑Get-Content opencode.json | ConvertFrom-Json驗(yàn)證。第二確認(rèn)provider下的models對(duì)象不是空的至少有一個(gè)模型定義。第三確認(rèn)頂層model字段引用的模型在models里存在比如tencent/tc-code-latest對(duì)應(yīng) providertencent下的tc-code-latest。第四重啟 OpenCode。配置改動(dòng)不會(huì)熱加載必須退出重進(jìn)。5.5 OAuth 相關(guān)報(bào)錯(cuò)如果你配了 GitHub MCP 這類需要 OAuth 的遠(yuǎn)程服務(wù)可能會(huì)遇到認(rèn)證失敗。OpenCode 的 MCP 認(rèn)證命令是opencode mcp auth github它會(huì)打開瀏覽器走 OAuth 流程。如果卡住檢查默認(rèn)瀏覽器是否正?；蛘呤謩?dòng)復(fù)制終端里打印的 URL 到瀏覽器打開。認(rèn)證憑據(jù)存在C:\Users\用戶名\.local\share\opencode\auth.json需要重置時(shí)刪掉對(duì)應(yīng)條目再重新認(rèn)證。5.6 配置文件位置速查類型路徑全局配置C:\Users\用戶名\.config\opencode\opencode.json項(xiàng)目配置項(xiàng)目根目錄\opencode.json全局 AgentC:\Users\用戶名\.config\opencode\agents\項(xiàng)目 Agent項(xiàng)目根目錄\.opencode\agents\認(rèn)證憑據(jù)C:\Users\用戶名\.local\share\opencode\auth.json排查時(shí)優(yōu)先確認(rèn)你改的文件和 OpenCode 實(shí)際讀取的文件是同一個(gè)這是 Windows 上最容易踩的坑。6. 把 Key 管好讓 OpenCode 長(zhǎng)期跑得穩(wěn)跑通之后日常使用還有幾個(gè)習(xí)慣值得養(yǎng)成。Key 不要硬編碼在項(xiàng)目配置里。項(xiàng)目級(jí)opencode.json如果進(jìn)了版本控制Key 就跟著泄露了。穩(wěn)妥做法是項(xiàng)目配置里只寫baseURL和模型定義apiKey用環(huán)境變量引用或者干脆把 Key 放在全局配置里項(xiàng)目配置只覆蓋模型選擇。多通道切換時(shí)頂層model字段是唯一開關(guān)。你可以在全局配置里同時(shí)保留騰訊云和 TaoToken 兩個(gè) provider日常寫代碼用tencent/deepseek-v4-pro-202606遇到需要長(zhǎng)上下文推理的任務(wù)切到taotoken/claude-sonnet-4-5改一行配置重啟即可不用重新填 Key。調(diào)試日志用完就關(guān)。$env:OPENCODE_LOG_LEVEL debug只在當(dāng)前 PowerShell 會(huì)話有效關(guān)掉窗口就恢復(fù)了不用擔(dān)心污染全局環(huán)境。最后OpenCode 的配置結(jié)構(gòu)是「全局打底、項(xiàng)目覆蓋」理解這一點(diǎn)后多項(xiàng)目多 Key 的管理就清晰了全局放公共的 provider 定義和默認(rèn)模型每個(gè)項(xiàng)目按需覆蓋model和專用 Key。這樣既不用每個(gè)項(xiàng)目重復(fù)寫一遍 provider又能保證 Key 隔離。