1. 為什么我建議你從 opencode.json 開始折騰opencode 這個(gè)終端里的 AI 編碼工具最近在開發(fā)者圈子里討論度不低。它跟很多同類工具最大的區(qū)別在于配置是顯式的、可版本化的所有 Agent 行為都落在opencode.json這一個(gè)文件里。你可以把它理解成「給 AI 編碼助手寫一份崗位說(shuō)明書」——provider 決定它去哪家模型服務(wù)商拿能力model 決定用哪個(gè)具體模型agent 段落則定義每個(gè)智能體的性格和職責(zé)邊界。但第一次配置的人往往會(huì)卡在同一個(gè)地方provider 的 endpoint 和 Key 到底怎么填。官方文檔里列了一堆服務(wù)商每家字段名還不完全一樣填錯(cuò)一個(gè)字母就是 401。更麻煩的是如果你同時(shí)用 Claude、GLM、Gemini 幾個(gè)模型就得維護(hù)多套 Key切換一次改一次配置時(shí)間全耗在復(fù)制粘貼上。這篇要解決的問(wèn)題很具體把 opencode 的 provider endpoint 統(tǒng)一指向 TaoToken 的兼容通道用一把 Key 打通opencode.json里的模型配置再配合 skill-creator 定義可復(fù)用技能最后跑通一個(gè)多 Agent 協(xié)作任務(wù)。適合誰(shuí)適合已經(jīng)裝好 opencode、想認(rèn)真用起來(lái)而不是隨便試試的開發(fā)者也適合被多服務(wù)商 Key 管理折磨過(guò)、想收斂配置的人。我試過(guò)把 plan 和 build 兩個(gè) Agent 分開配置不同模型一個(gè)負(fù)責(zé)出方案、一個(gè)負(fù)責(zé)改代碼上下文互不污染效果比單 Agent 硬扛好不少。下面從零開始一步步把配置寫出來(lái)。2. 前置準(zhǔn)備TaoToken 通道與 opencode 安裝檢查在動(dòng)opencode.json之前先把兩件事確認(rèn)掉opencode 本體裝好了TaoToken 的 Key 拿到了。opencode 的安裝按官方文檔走就行下載鏈接在 opencode.ai 的 download 頁(yè)面各平臺(tái)都有對(duì)應(yīng)包。裝完之后在終端敲opencode --version能打印版本號(hào)就說(shuō)明 PATH 沒問(wèn)題。如果你還想用 oh my opencode 這套增強(qiáng)配置裝完后用cat ~/.config/opencode/oh-my-opencode.json檢查一下文件存在且內(nèi)容正常就代表安裝完成。這個(gè)檢查動(dòng)作別省后面 Agent 配置出問(wèn)題時(shí)第一步就是回來(lái)確認(rèn)這個(gè)文件還在不在。接著是 TaoToken 這邊。打開 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注冊(cè)后進(jìn)控制臺(tái)在 API Keys 頁(yè)面創(chuàng)建一個(gè)新 Key。這里有個(gè)細(xì)節(jié)Key 只在創(chuàng)建時(shí)完整顯示一次記得當(dāng)場(chǎng)復(fù)制到密碼管理器或者本地環(huán)境變量文件里別關(guān)掉頁(yè)面再回來(lái)找。創(chuàng)建完 Key 之后你還需要確認(rèn)要用的模型 ID比如 Claude 系列、GLM 系列模型列表在文檔頁(yè)能查到記下準(zhǔn)確的模型標(biāo)識(shí)后面填model字段要用。TaoToken 的 API 基地址是https://taotoken.net/api這個(gè)地址在配置里會(huì)作為 provider 的baseURL出現(xiàn)。注意它跟官網(wǎng)首頁(yè)不是一回事別把帶 UTM 參數(shù)的推廣鏈接填進(jìn)配置文件那樣請(qǐng)求會(huì)失敗。配置里只寫純 API 地址。環(huán)境變量這塊建議單獨(dú)處理。把 Key 寫進(jìn) shell 的配置文件里比如~/.zshrc或~/.bashrc加一行export TAOTOKEN_API_KEY你的Key然后source一下。這樣做的好處是opencode.json里可以用變量引用Key 不會(huì)明文躺在項(xiàng)目倉(cāng)庫(kù)里被誤提交。如果你團(tuán)隊(duì)多人協(xié)作這一點(diǎn)尤其重要。到這里前置就齊了opencode 能跑、Key 在手、模型 ID 記下、API 地址明確。接下來(lái)進(jìn)配置文件。3. 可復(fù)制配置opencode.json 的 provider 與 model 字段怎么寫opencode.json的位置分全局和項(xiàng)目級(jí)兩種。全局配置在~/.config/opencode/opencode.json對(duì)所有項(xiàng)目生效項(xiàng)目級(jí)配置放在項(xiàng)目根目錄優(yōu)先級(jí)更高。我建議先寫全局的把 provider 和默認(rèn)模型定下來(lái)項(xiàng)目里需要特殊模型時(shí)再覆蓋。先看 provider 段落。核心是把自定義 provider 的baseURL指向 TaoToken 的 API 地址apiKey用環(huán)境變量引用。下面這段可以直接復(fù)制把模型 ID 換成你實(shí)際要用的{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} }, models: { claude-sonnet-4-20250514: { name: Claude Sonnet 4 }, glm-4.6: { name: GLM-4.6 } } } }, model: taotoken/claude-sonnet-4-20250514 }幾個(gè)字段逐個(gè)說(shuō)清楚。npm指定用哪個(gè) SDK 適配器OpenAI 兼容協(xié)議的服務(wù)商統(tǒng)一用ai-sdk/openai-compatibleTaoToken 的通道走這個(gè)沒問(wèn)題。baseURL就是前面說(shuō)的 API 地址結(jié)尾不要多加斜杠。apiKey里的{env:TAOTOKEN_API_KEY}是 opencode 的變量語(yǔ)法運(yùn)行時(shí)從環(huán)境變量讀取這樣配置文件可以放心提交。models里列出你要用的模型鍵名必須是服務(wù)商側(cè)準(zhǔn)確的模型 ID顯示名可以自己起。最外層的model是默認(rèn)模型格式是provider名/模型ID。然后是 agent 段落。opencode 內(nèi)置了 plan 和 build 兩種模式plan 先出方案再拆任務(wù)build 直接寫改代碼。你可以給它們分別指定模型和溫度{ agent: { plan: { model: taotoken/claude-sonnet-4-20250514, temperature: 0.1, description: 負(fù)責(zé)需求分析與任務(wù)拆解只出方案不改代碼 }, build: { model: taotoken/glm-4.6, temperature: 0.3, description: 負(fù)責(zé)按方案落地代碼專注實(shí)現(xiàn) }, creative: { temperature: 0.8, description: 負(fù)責(zé)文案與創(chuàng)意類任務(wù)允許發(fā)散 } } }temperature的取值邏輯值得展開。數(shù)值越小輸出越確定、越專一適合 plan 這種需要嚴(yán)謹(jǐn)拆解的場(chǎng)景數(shù)值越大發(fā)散性和創(chuàng)造性越強(qiáng)適合創(chuàng)意類任務(wù)。plan 給 0.1、build 給 0.3、creative 給 0.8是我實(shí)測(cè)下來(lái)比較穩(wěn)的一組值。description不是裝飾它會(huì)影響 Agent 的行為傾向?qū)懬宄氊?zé)邊界能減少跑偏。多 Agent 協(xié)作的價(jià)值在這里體現(xiàn)出來(lái)每個(gè) Agent 工作時(shí)上下文是獨(dú)立的。plan 拆完任務(wù)build 接手時(shí)不會(huì)背著 plan 階段那一大堆分析過(guò)程專注度更高。任務(wù)復(fù)雜時(shí)這種上下文隔離比單 Agent 一路扛到底效果好得多。配置好之后在對(duì)話里用agent名就能指定某個(gè) Agent 干活。最后補(bǔ)一個(gè) skill-creator 的安裝。最常用的方式是從 GitHub 直接裝npx skills add https://github.com/anthropics/skills --skill skill-creator如果這條命令失敗別死磕直接把 skill-creator 目錄復(fù)制到~/.config/opencode/skills/下面效果一樣。裝完在 skills 目錄里能看到 skill-creator 文件夾就說(shuō)明就位了。技能定義好之后Agent 在遇到匹配任務(wù)時(shí)會(huì)自動(dòng)調(diào)用可復(fù)用性比每次手寫提示詞強(qiáng)。4. 驗(yàn)證請(qǐng)求跑通第一個(gè) Agent 任務(wù)并確認(rèn)返回配置寫完不等于通了得實(shí)際發(fā)一次請(qǐng)求驗(yàn)證。分兩步先驗(yàn)證 provider 通道再驗(yàn)證 Agent 調(diào)用。第一步在終端里直接測(cè) API 通道。用 curl 發(fā)一個(gè)最小請(qǐng)求確認(rèn) Key 和地址都對(duì)curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回復(fù)兩個(gè)字通了}] }返回體里choices[0].message.content有內(nèi)容就說(shuō)明通道沒問(wèn)題。如果這里就報(bào)錯(cuò)先別往下走回到第 5 節(jié)對(duì)照排查。第二步進(jìn) opencode 驗(yàn)證 Agent。在項(xiàng)目目錄下啟動(dòng) opencode先看它有沒有正確加載配置。輸入一個(gè)簡(jiǎn)單任務(wù)比如讓它讀一下當(dāng)前目錄的文件結(jié)構(gòu)并給出說(shuō)明。觀察兩點(diǎn)一是請(qǐng)求有沒有正常發(fā)出二是返回內(nèi)容是不是來(lái)自你配置的模型。如果 opencode 界面里顯示了模型名確認(rèn)是taotoken/前綴的那個(gè)說(shuō)明 provider 映射生效了。第三步驗(yàn)證多 Agent 切換。在對(duì)話里用plan讓它拆一個(gè)任務(wù)比如「把這個(gè)項(xiàng)目的 README 補(bǔ)全先出方案」。plan Agent 應(yīng)該只給方案不動(dòng)文件。然后build接手讓它按方案改。兩次調(diào)用的上下文是隔離的build 不會(huì)帶著 plan 的完整推理過(guò)程這就是前面說(shuō)的上下文獨(dú)立優(yōu)勢(shì)。第四步驗(yàn)證 skill-creator。讓它創(chuàng)建一個(gè)簡(jiǎn)單技能比如「生成 commit message」的技能觀察它是否按 skill 的結(jié)構(gòu)輸出。技能文件落到 skills 目錄后下次遇到相關(guān)任務(wù)時(shí) Agent 會(huì)自動(dòng)匹配。整個(gè)驗(yàn)證過(guò)程里成功結(jié)果的標(biāo)志很明確curl 返回正常 JSON、opencode 里模型名正確、Agent 按指定響應(yīng)、技能文件生成到位。四步都過(guò)配置就算跑通了。5. 常見報(bào)錯(cuò)排查401、local proxy failed 與 reading choices配置階段最容易撞的幾類錯(cuò)誤我按出現(xiàn)頻率排一下對(duì)照著看。401 Unauthorized。這是最高頻的。原因通常有三個(gè)Key 沒讀到、Key 寫錯(cuò)、Key 失效。先確認(rèn)環(huán)境變量在當(dāng)前 shell 里真的存在echo $TAOTOKEN_API_KEY看有沒有輸出。如果為空說(shuō)明source沒生效或者寫錯(cuò)了文件。如果變量有值但還報(bào) 401檢查opencode.json里apiKey的變量語(yǔ)法是不是{env:TAOTOKEN_API_KEY}花括號(hào)和冒號(hào)都不能少。還有一種情況是 Key 復(fù)制時(shí)帶了首尾空格肉眼看不出來(lái)重新復(fù)制一次。local proxy failed 或連接類錯(cuò)誤。這類報(bào)錯(cuò)說(shuō)明請(qǐng)求根本沒到達(dá)服務(wù)端。先確認(rèn)baseURL寫的是https://taotoken.net/api沒有多余路徑、沒有結(jié)尾斜杠、沒有把官網(wǎng)推廣鏈接填進(jìn)去。再確認(rèn)本機(jī)網(wǎng)絡(luò)能正常訪問(wèn)這個(gè)地址用 curl 測(cè)一下根路徑。如果 curl 通但 opencode 不通檢查 opencode 版本是否過(guò)舊老版本對(duì)自定義 provider 的支持有差異升級(jí)到最新版再試。reading choices 相關(guān)報(bào)錯(cuò)。這個(gè)錯(cuò)誤的本質(zhì)是返回體結(jié)構(gòu)跟預(yù)期不符代碼去讀choices字段時(shí)讀不到。常見原因是模型 ID 填錯(cuò)了——服務(wù)端不認(rèn)識(shí)這個(gè)模型返回的是錯(cuò)誤對(duì)象而不是標(biāo)準(zhǔn)補(bǔ)全結(jié)構(gòu)?；厝ズ藢?duì)models里的鍵名跟服務(wù)商文檔里的模型 ID 是否完全一致大小寫、連字符都要對(duì)上。另一個(gè)原因是npm適配器選錯(cuò)了OpenAI 兼容通道必須用ai-sdk/openai-compatible用錯(cuò)適配器解析邏輯就不一樣。OAuth 相關(guān)報(bào)錯(cuò)。如果你之前配過(guò)其他需要 OAuth 登錄的服務(wù)商殘留的認(rèn)證狀態(tài)可能干擾。檢查~/.config/opencode/下有沒有舊的認(rèn)證緩存文件清理掉再重啟。自定義 provider 走的是 API Key 認(rèn)證不需要 OAuth 流程兩者混在一起容易出問(wèn)題。Agent 不響應(yīng)指定。先確認(rèn) agent 名拼寫跟配置里一致plan對(duì)應(yīng)配置里的plan鍵。再確認(rèn)配置文件的層級(jí)沒寫錯(cuò)agent是頂層字段不要嵌到provider里面去。改完配置記得重啟 opencode配置是啟動(dòng)時(shí)加載的。排查的通用思路是分層先 curl 測(cè)通道再測(cè) opencode 加載最后測(cè) Agent 行為。哪一層斷了就修哪一層別一上來(lái)就改配置容易越改越亂。6. 把配置沉淀下來(lái)后續(xù)接入與長(zhǎng)期使用建議配置跑通之后建議做兩件事讓這套東西長(zhǎng)期可用。第一件把opencode.json納入版本管理。因?yàn)?Key 走的是環(huán)境變量引用配置文件本身不含敏感信息可以放心提交到倉(cāng)庫(kù)。團(tuán)隊(duì)里其他人拉下來(lái)只需要自己配一下TAOTOKEN_API_KEY環(huán)境變量就能用同一套 Agent 定義。這比每個(gè)人各自維護(hù)一份配置要省心得多Agent 的description和temperature也能統(tǒng)一團(tuán)隊(duì)輸出風(fēng)格更一致。第二件把常用技能沉淀到 skills 目錄。skill-creator 裝好之后遇到重復(fù)性任務(wù)就讓它生成技能文件比如代碼審查清單、commit 規(guī)范、文檔模板。技能積累多了Agent 的自動(dòng)化程度會(huì)明顯提升。技能文件同樣可以進(jìn)版本庫(kù)跟配置一起管理。如果你后續(xù)要長(zhǎng)期跑編碼任務(wù)或者搭多 Agent 工作流可以關(guān)注 Coding Plan 這類方案把調(diào)用額度規(guī)劃好避免高峰期臨時(shí)抓瞎。模型能力驗(yàn)證階段直接用模型對(duì)話頁(yè)面測(cè)一下不同模型的返回質(zhì)量確認(rèn)哪個(gè)模型適合你的任務(wù)類型再寫進(jìn)opencode.json的models列表。接入文檔在 https://taotoken.net/api 對(duì)應(yīng)的文檔頁(yè)能查到字段說(shuō)明和模型列表都在那里。Key 管理在控制臺(tái)的 API Keys 頁(yè)面建議定期輪換。這套配置的核心思路就一句話endpoint 和 Key 收斂到一處Agent 定義顯式化技能可復(fù)用。把這三件事做好opencode 才算真正用起來(lái)了。