說句實(shí)話2025年還在糾結(jié)“該選哪個(gè)AI編程助手”的人多半已經(jīng)被各種名字繞暈了。今天我只聊一個(gè)opencode。它是一款跑在終端里的開源AI編程Agent能讀你整個(gè)項(xiàng)目、自己改代碼、執(zhí)行命令、跑測(cè)試甚至幫你點(diǎn)瀏覽器找前端Bug而且模型自由到離譜——想接哪家接哪家。這篇文章沒有什么“官方文檔翻譯”全是我自己從裝到用、從踩坑到順手的一套實(shí)踐記錄。適合剛聽說opencode想嘗鮮的人也適合已經(jīng)在用但被各種報(bào)錯(cuò)和配置折磨的人。1. 先搞明白o(hù)pencode到底是什么為什么值得折騰1.1 終端AI Agent和傳統(tǒng)AI補(bǔ)全插件是兩碼事很多人一聽“AI編程工具”第一反應(yīng)是那些在編輯器里彈補(bǔ)全建議的插件比如Copilot、Continue這類。opencode跟它們是兩個(gè)物種。補(bǔ)全插件是“你寫一句它接一句”本質(zhì)是個(gè)高級(jí)輸入法而opencode是一個(gè)能獨(dú)立干活的Agent——你給它一個(gè)任務(wù)它會(huì)自己讀代碼、拆步驟、改文件、跑命令、看結(jié)果然后決定下一步干什么。我在實(shí)際項(xiàng)目里最喜歡的一個(gè)場(chǎng)景是這樣的我對(duì)它說“這個(gè)模塊的接口超時(shí)問題幫我查一下”它不會(huì)只回你一段分析文字而是真的去追蹤調(diào)用鏈、找到超時(shí)配置、把代碼改了再跑一遍測(cè)試給你看。整個(gè)過程像給一個(gè)思路清楚的新同事派活不是給輸入法敲提示。它跟“問答型AI”也不一樣。你問“這段代碼什么意思”它回答你問“這個(gè)Bug怎么修”它不一定直接給你答案而是自己動(dòng)手查日志、改代碼、驗(yàn)證結(jié)果。這就是Agent和Chatbot的本質(zhì)區(qū)別一個(gè)只會(huì)說一個(gè)會(huì)做。1.2 和Claude Code、Codex CLI用起來有什么不一樣現(xiàn)在市面上能“自己干活”的終端Agent其實(shí)已經(jīng)有好幾個(gè)最出名的就是Claude Code、OpenAI Codex CLI以及開源陣營(yíng)的opencode、Aider、Gemini CLI。我用下來的感受是opencode有幾個(gè)點(diǎn)讓它特別值得放進(jìn)工具箱模型不受綁。Claude Code基本綁定Anthropic的模型Codex CLI天生偏向OpenAI系。opencode是模型無(wú)關(guān)的Claude、GPT、Gemini、DeepSeek、通義Qwen、本地Ollama全都行而且可以在一個(gè)會(huì)話里來回?fù)Q。這一點(diǎn)對(duì)我來說是決定性的。原生就支持多Agent協(xié)作。你可以讓一個(gè)Agent負(fù)責(zé)規(guī)劃另一個(gè)Agent負(fù)責(zé)執(zhí)行還能自己定義專門的小Agent處理特定任務(wù)比如“專門寫測(cè)試的Agent”“專門做Code Review的Agent”。配置是透明的純文本。項(xiàng)目規(guī)則、模型供應(yīng)商、Skills技能、MCP服務(wù)全部通過配置文件管理看得見、摸得著、能進(jìn)Git不會(huì)像某些商業(yè)工具把配置鎖死在云端賬號(hào)里。開源社區(qū)活躍。你遇到的問題大概率已經(jīng)有人提了Issue或?qū)懥瞬寮钠饋硪卜奖恪Ｎ也⒉皇钦fopencode能完全替代Claude Code或Codex。商業(yè)工具在特定模型上的調(diào)優(yōu)和出品方生態(tài)確實(shí)有優(yōu)勢(shì)。但如果你和我一樣平時(shí)要接不同客戶的項(xiàng)目、用不同家的模型、還要控制成本那opencode這種“開放底座”的價(jià)值就體現(xiàn)出來了。2. 安裝與初始化把opencode跑起來2.1 四個(gè)安裝姿勢(shì)與我的推薦opencode的安裝方式有好幾種我按常見程度排一下官方安裝腳本macOS/Linux/WSL推薦curl -fsSL https://opencode.ai/install | bash裝完以后腳本會(huì)提示你把安裝目錄加到PATH里一般是~/.opencode/bin或者/usr/local/bin具體看輸出。通過Bun安裝如果你已經(jīng)在用Bunbun install -g opencode-aiBun裝的版本更新比較積極適合喜歡追新的人。通過HomebrewmacOS用戶友好brew install sst/tap/opencodeGo install開發(fā)者習(xí)慣go install github.com/sst/opencode/cmd/opencodelatest我的建議很簡(jiǎn)單新手直接用官方腳本最穩(wěn)。因?yàn)楣俜侥_本會(huì)處理好PATH和依賴少踩很多“命令找不到”的坑。裝完之后在終端敲一下opencode --version能輸出版本號(hào)就算成了。提示如果你在Windows上建議優(yōu)先用WSL而不是純PowerShell。不是不能用PowerShell而是后續(xù)很多Skills、MCP工具的生態(tài)在Linux環(huán)境下更順。當(dāng)然后面我也會(huì)講純Windows下怎么處理。2.2 模型接入一個(gè)config.json走天下安裝只是第一步真正的關(guān)鍵是把模型接進(jìn)來。opencode的思路是“Provider Model”兩層結(jié)構(gòu)先定義模型供應(yīng)商Provider再?gòu)墓?yīng)商里選模型Model。最省事的辦法是把API Key設(shè)成環(huán)境變量opencode會(huì)自動(dòng)識(shí)別主流供應(yīng)商的Keyexport ANTHROPIC_API_KEYsk-ant-... export OPENAI_API_KEYsk-... export OPENROUTER_API_KEYsk-or-...設(shè)置好之后直接運(yùn)行opencode然后在界面里輸入/models就能看到對(duì)應(yīng)供應(yīng)商的模型列表回車即可切換。如果你用的是OpenAI兼容接口的第三方服務(wù)就需要自己寫配置文件了。全局配置文件默認(rèn)在~/.config/opencode/opencode.jsonWindows是%USERPROFILE%\.config\opencode\opencode.json參考配置長(zhǎng)這樣{ $schema: https://opencode.ai/config.json, provider: { myprovider: { npm: ai-sdk/openai-compatible, name: My Provider, options: { baseURL: https://api.example.com/v1, apiKey: env:MY_API_KEY }, models: { my-fast-model: { name: My Fast Model }, my-powerful-model: { name: My Powerful Model } } } } }這里有幾個(gè)重點(diǎn)baseURL填供應(yīng)商的接口地址注意一般后面要帶/v1很多人的報(bào)錯(cuò)就是漏了這個(gè)。apiKey可以直接填明文但我強(qiáng)烈建議寫成env:變量名讓Key從環(huán)境變量讀取免得配置文件不小心提交到Git倉(cāng)庫(kù)。npm字段是opencode用來跟模型服務(wù)通信的SDK包ai-sdk/openai-compatible是通用OpenAI兼容協(xié)議適用于絕大多數(shù)第三方服務(wù)如果接的是Anthropic兼容服務(wù)就換成ai-sdk/anthropic。配置完以后重啟opencode再/models就能看到自定義的模型了。2.3 Windows用戶最常見的第一個(gè)坑無(wú)法識(shí)別“opencode”這個(gè)報(bào)錯(cuò)我在熱搜詞里看到了太經(jīng)典了opencode : 無(wú)法將“opencode”項(xiàng)識(shí)別為 cmdlet、函數(shù)、腳本文件或可運(yùn)行程序的名稱不用慌本質(zhì)上就是系統(tǒng)找不到opencode這個(gè)命令也就是PATH沒配上。按這個(gè)順序排查確認(rèn)安裝是否成功。重新開一個(gè)PowerShell執(zhí)行Get-Command opencode如果這個(gè)命令返回路徑說明已經(jīng)裝好只是當(dāng)前這個(gè)終端窗口沒刷新直接重開終端就好。如果報(bào)錯(cuò)找不到進(jìn)入下一步。找到opencode安裝位置。官方腳本一般裝在%USERPROFILE%\.opencode\bin下Bun全局裝在%USERPROFILE%\.bun\bin下。打開資源管理器確認(rèn)一下這個(gè)目錄里有沒有opencode.exe。手動(dòng)把目錄加進(jìn)PATH[Environment]::SetEnvironmentVariable(Path, $env:Path ;$env:USERPROFILE\.opencode\bin, User)加完以后重開終端。如果你是用Bun裝的記得確認(rèn)Bun的bin目錄在PATH里opencode是它的軟鏈Bun目錄不在PATH同樣找不到。說句實(shí)在話這個(gè)坑跟opencode本身沒關(guān)系是所有命令行工具在Windows上的通病。我見過不少朋友卡在這一步就放棄了其實(shí)靜下心來花五分鐘排查PATH就過去了。3. 日常使用邏輯從問一句到干一個(gè)活3.1 會(huì)話、Agent和最常見的斜杠命令跑起來之后你會(huì)看到一個(gè)終端交互界面類似一個(gè)特殊設(shè)計(jì)的聊天窗口。剛接觸時(shí)別急著讓它干活先把這幾個(gè)基礎(chǔ)概念理清會(huì)話Session一次完整的對(duì)話上下文。同一會(huì)話里Agent會(huì)記住之前聊了什么。用/new開啟新會(huì)話。Agent不同角色的執(zhí)行單位。內(nèi)置至少有build默認(rèn)負(fù)責(zé)具體開發(fā)和修改和plan先出方案不動(dòng)代碼。你可以在Agent間切換。斜杠命令Slash Command在輸入框里以/開頭的指令。日常最常用的是/models切換模型、/agents切換Agent、/new新開對(duì)話、/help查看所有命令。我的習(xí)慣是先/models選好模型然后直接自然語(yǔ)言描述任務(wù)。開頭不用太客氣不用寫“請(qǐng)幫我”直接說“這個(gè)倉(cāng)庫(kù)里那個(gè)登錄超時(shí)的Bug查一下原因”它的理解能力完全跟得上。3.2 Agent和Plan兩種模式怎么配合這里我重點(diǎn)說下內(nèi)置的兩種模式是怎么分工的因?yàn)楹芏嗳瞬粫?huì)用Plan就把活直接丟給了默認(rèn)Agent導(dǎo)致改完不滿意又來回返工。Plan模式只讀代碼、只做分析、只給方案不會(huì)動(dòng)任何文件。適合接到任務(wù)時(shí)先用它摸清底細(xì)。Build模式真正的干活模式讀代碼、改代碼、跑命令、驗(yàn)證結(jié)果全自動(dòng)。我現(xiàn)在的標(biāo)準(zhǔn)流程是接一個(gè)新任務(wù)先切到Plan讓它給我一份“這個(gè)需求要怎么改、涉及哪些文件、有什么風(fēng)險(xiǎn)”的方案我看完覺得靠譜再切到Build說一句“按剛剛的方案執(zhí)行”。這樣既避免了Agent自作主張?jiān)礁脑狡沧屛覍?duì)它的操作有掌控感。注意Plan模式不是不能改文件而是它被設(shè)計(jì)成“不該改文件”。如果你發(fā)現(xiàn)Plan模式也在頻繁改東西檢查一下是不是自定義Agent配置里權(quán)限給得太寬了。3.3 讓opencode記住項(xiàng)目規(guī)則AGENTS.md與記憶機(jī)制這是很多人忽略、但價(jià)值極高的功能。你會(huì)遇到這類情況一個(gè)項(xiàng)目里約定縮進(jìn)必須4空格、前端組件必須用TypeScript、提交信息必須按Conventional Commits格式寫……這些東西你每次都要在對(duì)話里重復(fù)或者它根本不知道。opencode支持通過AGENTS.md文件來注入項(xiàng)目規(guī)則類似Claude Code的CLAUDE.md。在項(xiàng)目根目錄創(chuàng)建AGENTS.md里面寫上項(xiàng)目的技術(shù)棧、目錄結(jié)構(gòu)、代碼風(fēng)格和約束opencode在每次會(huì)話啟動(dòng)時(shí)都會(huì)自動(dòng)讀到它。我的項(xiàng)目根目錄的AGENTS.md一般長(zhǎng)這樣# 項(xiàng)目規(guī)則 - 這個(gè)項(xiàng)目是前后端分離的Java Spring Boot Vue應(yīng)用 - 后端代碼在backend/目錄前端在frontend/目錄 - 新增接口必須寫單元測(cè)試 - 數(shù)據(jù)庫(kù)變更必須提供遷移腳本 - 不要修改generated/目錄下的任何文件這樣每次新開會(huì)話它會(huì)自動(dòng)“知道”這些約定不用我一遍遍重復(fù)。如果你有跨項(xiàng)目的通用偏好比如“代碼注釋用中文”“提交信息按Conventional Commits”可以放在全局配置目錄下的AGENTS.md里所有項(xiàng)目通用。關(guān)于大家經(jīng)常問的“memory記憶”問題opencode目前沒有一個(gè)統(tǒng)一的“記憶數(shù)據(jù)庫(kù)”但實(shí)踐上可以通過三層結(jié)構(gòu)實(shí)現(xiàn)類似效果全局AGENTS.md存?zhèn)€人偏好項(xiàng)目AGENTS.md存項(xiàng)目約定對(duì)話會(huì)話存短期上下文。把該沉淀的規(guī)則寫進(jìn)文件它就是長(zhǎng)期記憶只寫在對(duì)話里關(guān)掉窗口就沒了。4. 干活場(chǎng)景拆解接手老項(xiàng)目、配Maven、測(cè)前端Bug4.1 接手已有項(xiàng)目先讀文檔、理清結(jié)構(gòu)再動(dòng)手搜熱詞里有個(gè)“opencode接手開發(fā)項(xiàng)目”這實(shí)際上是我日常用得最多的場(chǎng)景。剛拿到一個(gè)陌生倉(cāng)庫(kù)人肉讀代碼很累但我不會(huì)一上來就讓Agent改東西而是按這個(gè)順序來第一步讓它先讀項(xiàng)目說明和結(jié)構(gòu)先看一下項(xiàng)目根目錄的README和整體目錄結(jié)構(gòu)告訴我這個(gè)項(xiàng)目是干什么的、用了什么技術(shù)棧、有哪些模塊。第二步讓它梳理關(guān)鍵流程找到用戶登錄的完整代碼鏈路從Controller到Service到DAO把所有相關(guān)文件和調(diào)用關(guān)系列出來。第三步確認(rèn)理解無(wú)誤后再給修改任務(wù)。這樣接手老項(xiàng)目的效率比人肉翻代碼高好幾倍而且因?yàn)橄茸x了AGENTS.md和結(jié)構(gòu)它的回答會(huì)非?！岸小薄Ｈ绻愕睦享?xiàng)目是Java Maven工程這里有個(gè)關(guān)鍵詞“opencode mvn配置”我給一點(diǎn)實(shí)操建議在AGENTS.md里明確告訴它“這是一個(gè)Maven多模塊項(xiàng)目構(gòu)建命令是mvn -pl xxx -am test不要執(zhí)行全量mvn install”避免它上來就給你全倉(cāng)構(gòu)建跑十分鐘還不一定過。4.2 玩轉(zhuǎn)Skillsoh-my-claudecode、superpowers這類社區(qū)增強(qiáng)從哪下手Skills是opencode里一個(gè)非常強(qiáng)大的擴(kuò)展機(jī)制本質(zhì)上就是在.opencode/skills/目錄下放一堆帶說明的技能包讓Agent在某些場(chǎng)景下自動(dòng)調(diào)用對(duì)應(yīng)技能或者通過/技能名手動(dòng)觸發(fā)。社區(qū)里流傳比較廣的幾個(gè)思路來自oh-my-claudecode和superpowers。它們最初是給Claude Code做的技能合集比如“自動(dòng)生成git提交信息”“做代碼審查”“寫技術(shù)方案文檔”之類因?yàn)閛pencode支持Agent Skills標(biāo)準(zhǔn)很多人把這些技能直接搬過來或者做了適配。你完全可以在項(xiàng)目中建.opencode/skills目錄把需要的技能放進(jìn)去。舉個(gè)例子一個(gè)經(jīng)典的“git-commit”技能目錄結(jié)構(gòu)就是.opencode/skills/git-commit/ └── SKILL.mdSKILL.md的內(nèi)容包含技能的描述、適用場(chǎng)景和具體指令A(yù)gent讀到后就知道“當(dāng)用戶說提交代碼時(shí)我應(yīng)該執(zhí)行什么流程比如先看git status、再diff、再生成符合規(guī)范的提交信息”。我的建議是先別貪多裝一個(gè)最貼合你工作流的技能跑通全流程理解技能包是“怎么被加載、怎么寫描述”的再逐步加。一下子裝幾十個(gè)技能反而會(huì)讓Agent在調(diào)用時(shí)猶豫不決。4.3 Playwright接進(jìn)來讓Agent自己點(diǎn)頁(yè)面找Bug“opencode playwright怎么測(cè)試前端Bug”也是很多人搜的點(diǎn)。場(chǎng)景是你遇到一個(gè)前端Bug說要打開頁(yè)面、點(diǎn)幾次按鈕、看控制臺(tái)報(bào)錯(cuò)才能定位?，F(xiàn)在這些事情可以讓opencode通過Playwright MCP自己干。實(shí)現(xiàn)方式是在配置里加一個(gè)MCP服務(wù)指向Playwright{ mcp: { playwright: { type: local, command: [npx, -y, playwright/mcplatest] } } }配置好以后你就可以給Agent下這種任務(wù)用Playwright打開本地前端的登錄頁(yè)面輸入測(cè)試賬號(hào)登錄 復(fù)現(xiàn)用戶反饋的“登錄成功后頁(yè)面白屏”問題 打開瀏覽器控制臺(tái)把報(bào)錯(cuò)信息截圖給我。它會(huì)真的去啟動(dòng)瀏覽器、執(zhí)行操作、收集信息然后把結(jié)果反饋回來。這一步對(duì)調(diào)試“用戶那邊復(fù)現(xiàn)不了、本地偶發(fā)”的前端問題特別有效。注意首次使用需要安裝瀏覽器內(nèi)核npx playwright install chromium提前裝好可以少踩一次坑。5. 編輯器與桌面端不想敲命令的人怎么用5.1 VSCode和JetBrains IDEA插件怎么配雖然opencode主陣地是終端TUI但它在編輯器里的體驗(yàn)也挺好。搜熱詞里出現(xiàn)的“vscode opencode插件”“idea opencode插件”其實(shí)就是把TUI或者會(huì)話面板嵌入編輯器側(cè)邊欄讓你不用來回切換窗口。以VSCode為例直接在擴(kuò)展市場(chǎng)搜opencode安裝社區(qū)插件后前提還是本地已經(jīng)裝好opencode CLI插件本質(zhì)上是調(diào)本機(jī)的opencode命令。裝完以后側(cè)邊欄會(huì)出現(xiàn)opencode面板你可以在里面開新會(huì)話、看當(dāng)前改動(dòng)不用離開編輯器。JetBrains IDEA也是在插件市場(chǎng)搜opencode安裝后通常會(huì)在底部或側(cè)邊欄出現(xiàn)一個(gè)工具窗口。我的使用習(xí)慣是寫代碼的時(shí)候開著插件面板遇到需要大范圍改動(dòng)的任務(wù)還是切到獨(dú)立終端用TUI因?yàn)門UI的全屏交互在復(fù)雜任務(wù)下更專注。編輯器插件適合“輕量問答 小范圍改動(dòng)”終端TUI適合“重活”。5.2 opencode桌面版和TUI怎么選“opencode桌面版”也是被問得很多的。桌面版本質(zhì)上就是給不想碰終端的人包了一層圖形界面把TUI里的會(huì)話、模型切換、Agent切換都做成了窗口按鈕。如果你在圖形化界面里操作更舒服或者團(tuán)隊(duì)里有不太熟命令行的同事桌面版是很好的選擇。但我個(gè)人的看法是一旦你要用高級(jí)功能最終還是繞不開TUI和配置文件。桌面版能做的是90%的日常操作但像自定義Provider、寫AGENTS.md、調(diào)整Skill這些仍然需要碰文件。所以我的建議是入門可以用桌面版但抽空把TUI的基本操作練熟上限高很多。6. 模型選型免費(fèi)模型、本地模型和付費(fèi)API怎么組合6.1 主力模型、快速模型、本地模型的分工模型選型是決定opencode好用程度的關(guān)鍵。我的原則是三個(gè)檔位主力模型處理復(fù)雜任務(wù)、架構(gòu)設(shè)計(jì)、跨文件修改。我用過Claude、GPT系列也用過Gemini各家各有勝負(fù)關(guān)鍵看你的實(shí)際任務(wù)類型和預(yù)算?？焖?輕量模型處理簡(jiǎn)單問答、代碼格式化、生成提交信息。選便宜的、延遲低的小模型就行成本能壓到很低。本地模型隱私敏感、離線環(huán)境或者純粹想省錢。通過Ollama跑Qwen系列、Llama系列都可以。opencode對(duì)本地模型的支持很友好。你只要讓Ollama跑起來然后在配置里加一個(gè)本地Provider{ provider: { ollama: { npm: ai-sdk/openai-compatible, name: Ollama, options: { baseURL: http://localhost:11434/v1, apiKey: ollama }, models: { qwen3:14b: { name: Qwen3 14B } } } } }本地模型的好處是數(shù)據(jù)不出機(jī)器、沒有調(diào)用費(fèi)用但能力上限和速度受你機(jī)器的顯卡和內(nèi)存限制。我實(shí)測(cè)下來14B左右的中小模型做代碼解釋、簡(jiǎn)單重構(gòu)是夠用的做復(fù)雜的跨文件架構(gòu)調(diào)整還是會(huì)露怯。6.2 免費(fèi)模型和廉價(jià)網(wǎng)關(guān)的真相搜熱詞里“opencode免費(fèi)模型”熱度很高也有“hy3-free下線了嗎”這種問題。我必須說點(diǎn)實(shí)話免費(fèi)的、共享的、公共的模型網(wǎng)關(guān)我建議只拿來做體驗(yàn)和測(cè)試千萬(wàn)別當(dāng)核心生產(chǎn)力依賴。原因很簡(jiǎn)單免費(fèi)服務(wù)說沒就沒模型能力不穩(wěn)定而且你或者隊(duì)友的代碼可能經(jīng)過完全不可控的服務(wù)鏈路。我不是說所有免費(fèi)服務(wù)都不可信而是這個(gè)風(fēng)險(xiǎn)需要你心里有數(shù)。相對(duì)靠譜的“便宜”路子有這么幾條各家云廠商對(duì)新用戶的免費(fèi)額度比如某些大模型API的免費(fèi)試用包。OpenRouter這類聚合服務(wù)上的免費(fèi)模型檔位適合體驗(yàn)各種模型。本地Ollama一次性投入硬件長(zhǎng)期零邊際成本。如果你確實(shí)需要“既要模型能力好、又要便宜”我建議選一個(gè)正規(guī)云廠商的低價(jià)模型檔位把主力任務(wù)和便宜任務(wù)分開而不是把希望押在一個(gè)隨時(shí)可能下線的免費(fèi)網(wǎng)關(guān)上。6.3 第三方配置管理工具的作用關(guān)于“opencode go需要配合ccswitch等工具”這個(gè)說法我理解是這樣的當(dāng)你的模型供應(yīng)商變多Key分散在好幾個(gè)地方手動(dòng)切環(huán)境變量會(huì)非常繁瑣。這時(shí)候ccswitch這類配置管理工具能幫上忙——它們可以集中管理多家供應(yīng)商的API Key在多個(gè)配置組之間一鍵切換省去每次手工改環(huán)境變量的麻煩。不過在引入任何第三方工具之前我的建議是先把opencode原生的Provider配置吃透。大多數(shù)“多供應(yīng)商切換”的需求通過配置文件里的多個(gè)Provider都能解決不一定需要額外工具。先原生、后第三方工具能少裝就少裝。7. 常見報(bào)錯(cuò)排查實(shí)錄與避坑清單7.1 unexpected server error 到底是誰(shuí)的鍋搜熱詞里有一條很具體c:\windows\system32opencode error: unexpected server error. check server logs這個(gè)報(bào)錯(cuò)看著嚇人但它基本可以翻譯成一句話opencode向模型服務(wù)發(fā)請(qǐng)求結(jié)果對(duì)方?jīng)]按預(yù)期返回。通常不是opencode本身的Bug排查順序如下確認(rèn)API Key是否有效。很多供應(yīng)商的Key有過期時(shí)間或者是臨時(shí)Key失效了就會(huì)報(bào)這種錯(cuò)。去供應(yīng)商控制臺(tái)生成一個(gè)新Key試試。確認(rèn)baseURL是否正確。這是自定義Provider最常見的問題比如漏了/v1或者填了網(wǎng)頁(yè)地址而不是API地址。確認(rèn)網(wǎng)絡(luò)是否通。有時(shí)候模型服務(wù)控制臺(tái)明明是好的但某個(gè)特定網(wǎng)絡(luò)環(huán)境下就是連不上。打開debug日志看細(xì)節(jié)。用debug模式啟動(dòng)opencode通常在日志里能看到具體的HTTP狀態(tài)碼或錯(cuò)誤信息比猜靠譜得多。提示看到unexpected server error不要急著重裝opencode99%的情況是上游模型服務(wù)的問題先查Key、查baseURL、查日志。7.2 hy3-free這類模型忽好忽壞怎么辦這個(gè)問題我前面已經(jīng)說了觀點(diǎn)免費(fèi)共享模型服務(wù)不穩(wěn)定是常態(tài)下線也沒人能攔得住。你搜“hy3-free下線了嗎”說明你已經(jīng)意識(shí)到風(fēng)險(xiǎn)了。我的處理方式很樸素用一個(gè)核心穩(wěn)定供應(yīng)商打底免費(fèi)服務(wù)只當(dāng)臨時(shí)替補(bǔ)。在opencode里配置多個(gè)Provider主力供應(yīng)商出問題就/models切到備用工作不中斷。7.3 技能裝不上、插件連不上多半是這三個(gè)原因社區(qū)里不少人問“Skills為什么加載不出來”“插件面板連不上TUI”。根據(jù)我踩過的坑大多是以下三種情況目錄放錯(cuò)了。SKILL.md必須放在.opencode/skills/技能名/下面而不是隨便丟在項(xiàng)目里。而且安裝技能后要重啟會(huì)話才生效。插件和CLI版本對(duì)不上。VSCode/IDEA插件會(huì)跟隨opencode CLI的版本變化老插件配合新版CLI很可能連不上。把雙向都升到最新版再試。終端必須在項(xiàng)目目錄啟動(dòng)。插件面板本質(zhì)上是代理了終端的opencode進(jìn)程如果你在錯(cuò)誤目錄啟動(dòng)它讀不到項(xiàng)目里的AGENTS.md和Skills。確認(rèn)opencode是在項(xiàng)目根目錄運(yùn)行時(shí)再用插件連接。8. 我現(xiàn)在的workflow與給你的一點(diǎn)建議最后分享一套我現(xiàn)在用得最順的流程算是把這幾年折騰出來的經(jīng)驗(yàn)濃縮一下。接到一個(gè)項(xiàng)目任務(wù)時(shí)先用Plan模式讓它出方案明確改動(dòng)清單方案確認(rèn)后切Build模式執(zhí)行執(zhí)行過程中如果遇到不確定的設(shè)計(jì)問題我會(huì)問清楚再繼續(xù)而不是讓它無(wú)限發(fā)揮。項(xiàng)目根目錄的AGENTS.md保持更新每踩一次坑就往里加一條規(guī)則。模型選擇上主力任務(wù)用能力強(qiáng)的付費(fèi)模型簡(jiǎn)單任務(wù)用便宜小模型涉及敏感代碼時(shí)切到本地模型。前端排查凡是涉及交互的直接讓Playwright MCP去復(fù)現(xiàn)。關(guān)于opencode我最大的體會(huì)是它真正的價(jià)值不在于“多了一個(gè)AI工具”而在于把AI Agent的能力真正下沉到了每一個(gè)開發(fā)者手里而且不綁定某一家模型不綁定某個(gè)編輯器不綁定某個(gè)商業(yè)生態(tài)。配置是一次性的但省下來的時(shí)間每天都在累積。你先把這條路跑通讓它穩(wěn)定地在你的項(xiàng)目里干活然后再慢慢擴(kuò)展Skills和MCP那時(shí)候你會(huì)發(fā)現(xiàn)自己已經(jīng)在用一套很不一樣的方式寫代碼了。