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