OpenClaude 的 /provider：Ollama、OpenAI 相容端點與設定檔放哪裡

/Provider 是什麼：設定寫在哪一層

先把結論講白：/provider 不是一套新軟體，它只是「在這個終端機工具裡，告訴模型要用哪一家後端」的一條指令。很多人誤以為要換模型，就得把工具、資料夾、甚至整個程式重新裝一遍，其實不用。openclaude 的用法很單純：進到你要改的那個專案，執行 openclaude，用 /provider 挑好後端、存成一組設定，然後下任務，終端機就會一邊跑、一邊把工具用了什麼、改了哪些內容印給你看。

同一條工作流程上還掛著 /diff（這次改了什麼）、/rewind（把對話或變更往回捲）、/cost（這次花多少），用起來和 Claude Code 那套斜線指令幾乎一樣。差別只有一件事：模型從哪裡來，可以自己換；存設定的資料夾也刻意分開，不跟官方版共用。官方產品頁 openclaude.gitlawb.com 跟 GitHub 專案 Gitlawb/openclaude 把這條路徑寫得很直白：進專案、啟動工具、選後端、開始改程式。

這類開源工具的熱度其實很好查：GitHub API 在 2026 年 9 月 6 日的快照約有 32,752 顆星、9,066 次 fork；npm 套件 @gitlawb/openclaude 當時最新版是 0.30.0。這些數字只說明用的人不少，真正決定模型用哪一家的，是一組設定（叫 profile）加上你家目錄下的 ~/.openclaude，而不是專案資料夾裡隨便放的檔案，更不是官方 Claude Code 的 ~/.claude。

在開始之前，執行環境要先對。Node 版本以 README 的 >=22 為準（安裝文件曾寫 Node 20，兩份對不上，這裡以 README 跟套件標示為準）; 缺 ripgrep 要另外裝 rg，再用 openclaude –version 確認程式有正常起來。這些準備工作和挑模型是同一套流程，別把「選模型」想成另一條產品線。安裝細節見 官方安裝文件。

設定寫進 ~/.openclaude，不讀 ~/.claude

這裡是新手最容易踩的坑。openclaude 的設定資料夾是 ~/.openclaude，不讀官方 Claude Code 的 ~/.claude。很多人從 Claude Code 轉過來，第一個直覺就是把 ~/.claude 整個資料夾拷過去，結果連舊的認證、錯誤的產品界線一起帶進來。遷移時只要複製你自己為 openclaude 寫的設定跟技能，不要整包複製官方憑證。

/provider 挑好後端、存成 profile，寫進的就是這層使用者設定，而不是把金鑰散在每個專案裡。專案資料夾負責讓工具讀程式、跑指令、產出修改；家目錄下的 ~/.openclaude 負責記住「你要用哪一組後端設定」。要排查就用 /doctor，它檢查的是這層設定跟執行環境，不是 git 狀態本身。

Provider profile 怎麼組成：舊環境變數與限流備援

openclaude 把「終端機那套工作流程」和「背後那顆模型」拆成兩件事，這點對台灣團隊很友善：你已經會 Claude Code 的斜線指令，這裡要改的只是模型從哪裡來，不用把整套工作流程重學。被寫進設定的，是一份可以切換的 provider profile，內容是後端名稱、端點網址、金鑰來源、模型識別字，以及限流時要改讀哪一組備援設定。官方文件說可以接四十個以上的後端，涵蓋 OpenAI、Gemini、Grok、Ollama、LM Studio、OpenRouter、GitHub Models，還有自訂的 OpenAI 相容端點（來源：openclaude.gitlawb.com 與 GitHub 專案說明，對照 2026 年 9 月文件）。

環境變數仍叫 CLAUDE_CODE_USE_OPENAI：舊專案名稱的陷阱

有一個很容易讓人心慌的細節：切捷徑用的環境變數仍叫 CLAUDE_CODE_USE_OPENAI=1，名字沿用舊專案，不是打錯字，也不是要你去裝另一套官方工具。看到 CLAUDE_ 這個字首，有人會跑去設 Anthropic 的金鑰檔、複製 ~/.claude，或把程式裝錯成別的 Claude 相關工具。這裡請認明：npm 包名是 @gitlawb/openclaude，2026 年 8 月 31 日前後最新版是 0.30.0。

設定方式要看作業系統。macOS 和 Linux 在 bash 或 zsh 用 export：export CLAUDE_CODE_USE_OPENAI=1，再 export OPENAI_BASE_URL=http://localhost:11434/v1，模型名另外寫進 /provider 存下的 profile。Windows 要用 PowerShell 語法，別把 Unix 的 export 直接貼過去再怪程式壞掉。對等寫法是 $env:CLAUDE_CODE_USE_OPENAI="1" 跟 $env:OPENAI_BASE_URL="http://localhost:11434/v1"。要提醒的是：這些變數只屬於「目前這個終端機視窗」，關掉就沒了；想長期用，要寫進該帳號的 shell 設定，而不是以為 /provider 會幫你把環境變數全部記起來。

限流時用 fallback chain 換下一組 profile

哪一家的模型都會碰到限流、額度用完、伺服器維護。openclaude 在產品層提供一種「備援鏈」provider fallback chain：遇到限流時，自動改讀下一組已經存好的設定，而不是讓「提示→模型→工具→修改」這整條流程直接卡在一個錯誤碼上。備援鏈裡每一節都必須是完整設定，包括後端名稱、端點、金鑰來源跟模型字串。

常見排法是：平常走雲端 OpenAI 相容閘道，碰到限流改用 OpenRouter 或 GitHub Models，再不行就切到本機 Ollama 或 LM Studio。重點是每一節的協定要協調一致，不能混搭。Ollama 那節要走原生聊天介面、給足 OPENCLAUDE_OLLAMA_NUM_CTX；LM Studio 那節要用它實際上監聽的埠；自訂端點那節的 OPENAI_BASE_URL 必須在限流當下仍連得上。換設定之後，依然是同一條工作流程，變的只是模型從哪來、帳單算在哪。

本機 Ollama 與 OpenAI 相容端點：BASE_URL、埠號與模型名

對想跑在自家電腦、不外送資料的人來說，本機 Ollama 是最直接的路。openclaude 對 Ollama 的寫法不是「隨便丟一個相容網址就結束」，而是明確走原生聊天介面。預設內容窗口長度是 32768（這是文件給的預設值）。遇到長文件、整份程式碼摘要或一次送多個檔案時，窗口不夠會被截斷或直接被後端拒絕。調整的鍵就是 OPENCLAUDE_OLLAMA_NUM_CTX，把它設成你這顆模型實際扛得住的長度。

設本機很簡單，就兩個數字對好：基底網址寫 OPENAI_BASE_URL=http://localhost:11434/v1，埠號 11434 是 Ollama 常見的本機監聽埠，路徑末端的 /v1 是相容介面的慣例，不是雲端網域。模型名必須跟你在本機列表裡看到的標籤一致，不要抄遠端廠商的別名。缺一項，看起來就會像「沒接上」，跟模型準不準無關。

自訂相容端點只記三欄：位址、模型、金鑰

走 OpenAI 相容協定的自訂端點，要對齊的其實只有三欄。少一欄，程式可能還是能啟動，只是請求已經跑到你以為的界線之外。這三欄必須一起出現，不能只改其中一個、還沿用舊金鑰。

第一欄是位址（BASE_URL），也就是請求真正打到哪台主機，本機可設 OPENAI_BASE_URL=http://localhost:11434/v1。路徑末端的 /v1 不是裝飾，很多相容實作把聊天功能掛在這個前綴，少寫一段會打到錯的路由。第二欄是模型名稱，必須是那台主機當下真的在服務的名字，不能從別家的型錄直接複製。第三欄是金鑰放哪，openclaude 的設定資料夾預設在 ~/.openclaude，官方 README 寫明不讀 ~/.claude，也不該把 Claude Code 的憑證整包複製過來。

企業雲與合作閘道不得混進同一張表

Amazon Bedrock、Google Vertex、Azure OpenAI 這三條是企業合約跟既有雲帳號路線，不是「再填一個 OpenAI 相容網址」就能混過去。Bedrock 走的是 AWS 區域、IAM 角色跟模型存取權；Vertex 走的是雲端專案、位置跟服務帳戶；Azure 走的是資源名稱、部署名稱跟金鑰或目錄驗證。主機、簽驗方式、帳單主體、資料駐留條款都不同，沒辦法共用同一組 OPENAI_BASE_URL。把企業雲硬塞進自訂相容欄，最常見的後果是請求看起來成功、帳單卻出現在另一個雲帳號，或日誌跟提示內容進了合約沒寫的端點。請替 Bedrock、Vertex、Azure 各自建 profile，名稱寫清楚雲跟專案，切換只用 /provider，不要靠改一個環境變數蓋掉全部。

OpenRouter 跟 Gitlawb Opengateway 則屬於合作或贊助商閘道，和本機 Ollama、和企業雲都不是同一台主機。閘道的便利是一張鑰匙後面掛很多模型別名，代價是你得接受請求先打到閘道營運商的主機、再由對方轉發。本機路徑的主機是 localhost，公開閘道是 HTTPS 遠端；這兩種位址若出現在同一行歷史紀錄裡，請當設定污染、整段重填。官方文件也列有 Gemini 後端，但我們不示範任何 Gemini 金鑰，需要這條後端的讀者請自行閱讀官方 providers 文件。專案 LICENSE 寫底層衍生程式仍屬 Anthropic 著作權，本專案沒有 Anthropic 授權散布其專有原始碼，使用者與貢獻者應自行評估法律立場。

台灣團隊落地順序：先本機試讀 repo，再接雲端金鑰

台灣客戶把需求講得很白：不要綁一家雲、程式不要出國、已經會 Claude Code 斜線指令。這三句話就決定了落地順序。「程式不要出國」講的是推論請求跟工作區內容的邊界，不是把筆電網路線拔掉。本機 Ollama 把推論留在 localhost；雲端金鑰則是把提示送出去，而提示裡往往已經夾著剛讀進來的原始碼。「不要綁一家雲」要求後端必須能切，切的是一組設定，不是換個環境變數就完事。

我們給台灣團隊的順序是寫死的：先用本機 Ollama 讓工具讀自己的專案，確認 ~/.openclaude 裡的設定能切換之後，再把既有雲端金鑰接進另一組設定。試讀專案必須發生在本機設定。跑起來後先做三件小事：讓工具列出資料夾結構、讀專案自己的說明檔、對單一檔案提出修改草稿並要人工核准敏感動作。目的是確認工具讀到的是自己的工作區，而不是誤連到合作雲。雲端設定一啟用，模型推論請求就會離開本機；工具還是在本機跑，可是讀進提示的原始碼會跟著請求出去，這才是「程式不要出國」要守的線。

對替代方案有限公司來說，結論很窄：本機先跑通、雲端金鑰再接、閘道跟地端分開寫。我們不把這個專案當公司正式產線預設。專案 LICENSE 寫底層衍生程式仍屬 Anthropic 著作權，本專案沒有 Anthropic 授權散布其專有原始碼，使用者與貢獻者應自行評估法律立場，公司文章只轉述這段、不做能不能商用的結論。這是獨立社群專案，跟 Anthropic 無關、未被背書；Claude 跟 Claude Code 是商標。斜線指令可以留、模型可以換，資料邊界必須自己守。落地前先把檔案系統紀律訂成內部規範：新專案只用 ~/.openclaude，禁止備份腳本把 ~/.claude 整包鏡像，技能用版本庫管理、不從舊隱藏資料夾撿，金鑰用各後端自己的環境變數或核准過的密鑰機制、不依賴舊的登入檔。

常見問題 FAQ

Q：我可以直接把 ~/.claude 複製到 ~/.openclaude 嗎？
不行。openclaude 不讀 ~/.claude，整包複製只會把錯誤的認證、舊的登入狀態一起帶進新的工作流程。只複製你自己為 openclaude 寫的設定跟技能。

Q：環境變數我照著設好了，為什麼存完 profile 還是跑不起來？
先確認兩件事：Node 版本是否達到 README 的 >=22，以及 OPENAI_BASE_URL 是否真的指到你核准的主機。再跑 /doctor 看它回報的設定根目錄跟環境變數。不要把「指令有回應」當成設定已生效。

Q：本機 Ollama 的 context 要設多少？
官方預設是 32768，可用 OPENCLAUDE_OLLAMA_NUM_CTX 調整。把它設成你這顆模型實際扛得住的長度，並確認 Ollama 這個程式本身也用相同的窗口啟動，兩邊不一致時，一端以為能塞進整份文件、另一端已經在裡頭截斷。

有任何問題或需要協助，歡迎聯絡我們：[email protected]