Claude Code 支援第三方推理端點：從零開始的完整設定與四項驗證

這篇要解決的問題

Claude Code 可以把推理請求導向第三方閘道，但這項設定預設不會出現在選單裡，而且網路上多數教學停在「填好欄位、看到版本號就算完成」。

實際上「版本號印出來」只證明用戶端裝在你的電腦上，它沒有證明端點連得上、憑證有效、模型會回話。這三件事一件都沒被驗證過。

這篇從完全沒設定過的狀態開始，把整個流程走完：怎麼判斷自己該用哪一支腳本、腳本會問什麼、桌面版圖形介面在哪裡、系統裡實際被寫入什麼、以及最後怎麼確認它真的通了。全文的數據都是在下列環境實測的：

最後一列不是寫錯，後面會回頭說明它的意義。

步驟一：先確認你屬於哪一種情況

打開終端機，輸入這一行：

claude --version

依輸出決定接下來走哪條路：

這一步常被跳過。很多人直接抓一支「全量安裝」的腳本就執行，結果在已經裝好的環境上把相依套件重裝一遍。

configure 這一支帶有硬性檢查：它做的第一件事就是在 PATH 裡尋找 claude，找不到就直接拋出錯誤結束，不會繼續往下執行。所以選錯這一邊不會弄壞任何東西，它只是拒絕動作。反方向則不成立——拿 setup 去動一個已經設定完成的環境是有代價的。

步驟二：執行腳本

已經有 Claude Code，只要寫設定：

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/xujfcn/crazyrouter-claude-code/main/configure.sh | bash

Windows PowerShell

irm https://raw.githubusercontent.com/xujfcn/crazyrouter-claude-code/main/windows/configure.ps1 | iex

完全沒有 Claude Code 的話，同一個儲存庫的同一個目錄裡還有一支完整安裝腳本，把上面命令裡的 configure 換成 setup 即是（setup.sh / windows/setup.ps1），它會先安裝 Git、Node.js、Claude Code，再寫設定。反過來不要換。

不論用哪一支，執行前請先把網址貼到瀏覽器裡把內容看過一遍。這跟腳本由誰撰寫無關，任何 | bash、| iex 形式的命令都應該這樣處理。以下關於腳本行為的敘述，都是這樣讀原始碼得到的。

補充一點 setup 在 Windows 上的實作，因為它決定了舊機器能不能跑通：優先使用 winget，沒有 winget 就回退到直接下載（Node.js 使用固定版本的 LTS 安裝檔，Git 從官方 release 取得），並且針對 PowerShell 5.1 明確啟用 TLS 1.2 與 1.3。舊環境能不能成功，差別就在這些回退分支上。

步驟三：腳本只會問三件事

三個互動式提問，除第一項以外都有預設值，按 Enter 即可接受：

兩個讀原始碼才會知道的細節：

第一，Token 有格式預檢，檢查前綴是否為 sk-、cr- 或 rk-。不符合時只印出一行警告，不會攔截執行。看到警告不必急著重來，先看後面有沒有真正的錯誤訊息。

第二，腳本輸出是英文的，即使你看的是中文說明文件。看到一整螢幕英文屬於正常狀況。

這裡有一項實測結果值得記下來。我用非互動方式跑過一次完整命令：腳本成功下載並執行，印出 [OK] Claude Code detected: 2.1.283，走到 Token 輸入環節；因為執行在非互動的子行程裡，讀取 Token 時拋錯結束，退出碼 1。事後逐一核對六個環境變數，一個都沒有被改動。

這說明腳本採「全部問完才寫入」的設計，中途中斷不會留下半套設定。對需要反覆重試的人來說，這一點很重要：失敗之後直接重跑就好，不需要先手動清理。

無人值守部署

如果是在伺服器上不想互動，先用環境變數把 Token 餵進去：

export CRAZYROUTER_TOKEN="你的金鑰"
curl -fsSL https://raw.githubusercontent.com/xujfcn/crazyrouter-claude-code/main/configure.sh | bash

（裸機伺服器連 Claude Code 都還沒有的話，同樣把 configure 換成 setup。）

這一支額外處理了一個容易踩到的狀況：curl | bash 通常執行在非登入 shell 裡，看不到 npm 的全域路徑。腳本會主動到 /usr/local/bin、~/.local/bin、~/.npm-global/bin 這幾個目錄尋找 claude；即使最後仍然定位不到，它也會把設定寫完並印出診斷資訊，不會留下半途而廢的狀態。

步驟四：改用桌面版圖形介面

如果你不想用命令列，桌面版有一個完整的設定面板。但它預設不會出現在設定選單裡，必須先開啟開發者模式。

依官方說明文件的路徑：

Help → Troubleshooting → Enable Developer Mode

確認之後應用程式會自動重新啟動一次，左上角的選單裡才會多出 Developer 這一項：

展開它，點 Configure third-party inference：

進去之後選左側的 Connection。以下是設定完成後的樣子：

（說明：本文撰寫環境的開發者模式原本就處於開啟狀態，無法驗證「未開啟時是否確實看不到」，這一段僅依官方選單路徑陳述，不是實際重現的結果。）

這個面板有四個欄位需要說明。

Credential kind 設為 Static API key 的語意是鎖定憑證來源：選定之後只使用這一個來源，不再回退到登入狀態或環境變數。對排查很有幫助，因為它排除了「以為走自建閘道、其實回落到預設端點」的不確定性。反過來說，如果設定完成後請求仍然流向舊位址，這一欄應該列為第一個檢查項目。

Gateway base URL 填閘道位址。注意這裡跟環境變數的規則一致，後面會詳細說明。

Gateway auth scheme 可選 bearer 或 x-api-key，決定憑證放在哪一個 HTTP 標頭裡送出。本文實測的閘道對兩種標頭都回傳 200 並取得回應，但這並非通則。多數閘道只接受其中一種，選錯時的錯誤訊息與「憑證無效」幾乎無法區分，應以服務方文件為準。

這個面板不會幫你整理網址格式。 結尾多餘的斜線、多打的一段 /v1、從分享連結複製過來時尾巴帶著的 ?utm_source=...，全部會照你輸入的樣子送出去。命令列腳本會自動去掉結尾斜線，圖形介面不會。

還有一個容易吃虧的細節：按鈕位置不直覺。Test connection 在右上角，Apply Changes 在右下角。而且測試在尚未套用的值上就能通過，所以「測試成功後直接關掉視窗」是一種什麼都沒存到的操作方式。順序是先測試、再套用。

面板左側另外還有 Sandbox & workspace 與 Egress 兩個分區，代表應用程式對工具流量實施沙箱隔離。如果所有欄位都正確、Test connection 卻不通，閘道網域可能不在允許出網的清單裡。

（說明：此項在本文實測環境未重現，當前設定可直接連通，列出僅供排查參考。）

步驟五：確認系統裡實際被寫入什麼

不論你走命令列還是圖形介面，最終落地的是六個使用者層級的環境變數，分屬兩套協定約定：

之所以寫成兩套，是因為 Claude Code 本身讀取 Anthropic 那一組，而許多 OpenAI 相容的開發工具讀取後一組。一組憑證同時滿足兩邊。

這裡是最容易出錯的一點

兩個位址的路徑約定不對稱。

ANTHROPIC_BASE_URL 只填根網域，用戶端會自行組出 /v1/messages。如果你手動補上 /v1，實際請求會變成 /v1/v1/messages，這個寫法是錯的。閘道嚴格按路徑路由時，你會收到一個 404，而錯誤訊息不會告訴你原因；但也有閘道寬鬆到照樣回 200，我實測手上這個就是這樣。後者反而更難發現，因為畫面上完全沒有異常。

OPENAI_BASE_URL 則必須自己帶上 /v1。

會踩到這個坑的人，通常反而是做事比較整齊的人：兩個欄位指向同一台伺服器，看起來理應長得一樣，於是統一格式。這個直覺在多數情況下是對的，只是這個案例剛好是不對稱的。沒有任何檢查工具會提醒你，因為兩個值在語法上都沒有問題。

症狀是「Claude Code 通了、其他工具卻連不上」，或者剛好相反。多半會看到 404，不過實際回什麼錯誤要看那個閘道怎麼處理。

落盤位置

在 Windows 上，這些值以 User scope 寫入使用者環境變數。在 macOS 與 Linux 上，寫入家目錄下的 env 檔案，再由 shell 啟動檔案載入。

有一個實作細節值得一提：啟動檔案是依真正的登入 shell 來選擇的，不是依檔案存不存在。一台用 zsh 登入的機器上可能也有 ~/.bashrc，改到那裡是不會生效的。動手之前先 echo $SHELL。

專案層級的替代方案

如果不想動系統環境變數，可以在專案根目錄建立 .claude/settings.json，在 env 區塊中指定：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.crazyrouter.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的金鑰",
    "ANTHROPIC_MODEL": "claude-opus-4-8"
  }
}

作用範圍限於該專案，很適合多個專案走不同閘道的情況。但這個檔案同樣是明文，而且比環境變數更容易被誤提交進版本控制系統，走這條路務必同步調整 .gitignore。

三種設定方式的取捨：

步驟六：四項驗證

這是整篇最關鍵的一節。設定完成之後，請依序確認下列四項。

第一項，用戶端是否安裝。

claude --version

證明的範圍：PATH 裡存在這個執行檔。就只有這樣。本文實測環境回報 2.1.283。

第二項，執行環境是否具備。

node --version

證明的範圍：Node.js 在。實測回報 v24.21.0。

第三項，設定是否確實寫入。 注意這裡要做的是「讀回來看」，不是「我剛剛有輸入」。

Windows PowerShell

'ANTHROPIC_BASE_URL','ANTHROPIC_AUTH_TOKEN','ANTHROPIC_MODEL','CLAUDE_MODEL','OPENAI_API_KEY','OPENAI_BASE_URL' |
  ForEach-Object { "{0,-22} {1}" -f $_, [Environment]::GetEnvironmentVariable($_,'User') }

macOS / Linux

env | grep -E 'ANTHROPIC|OPENAI'

看的重點就是前面說的 /v1 不對稱：ANTHROPIC_BASE_URL 結尾不該有 /v1，OPENAI_BASE_URL 結尾該有。

第四項，端到端是否連通。 這一項是關鍵。

curl -s https://api.crazyrouter.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "reply with: pong"}]
  }'

max_tokens 設 16 是刻意的：回應內容是什麼並不重要，重要的是回應存在。成功回傳同時確立三件事——端點可達、憑證被接受、模型有回話。

為什麼前三項在關鍵處派不上用場

前三項檢查的全部是你自己這台機器的狀態，沒有任何一項碰到閘道。

因此下列失效情形對前三項完全不可見：

• 憑證過期
• 額度耗盡
• 模型代號不被閘道辨識
• 代理軟體或 VPN 把網域分流到別處
• 閘道網域不在允許出網清單裡

以上全部會通過第一到第三項、沒有任何警告，然後停在第四項。

也就是說，前三項全過、第四項失敗，不是罕見狀況，而是這類問題最常見的樣子。如果你只有時間做一項，做第四項。

常見錯誤與處理

設定完成後在原本的終端機視窗驗證，顯示找不到命令。

環境變數只對新建立的行程生效。在舊視窗裡驗證必然失敗，這是預期結果，不是設定錯誤。請把視窗完整關掉再開新的；在 Windows 上，開新分頁是不夠的。這一條每次都會產生一批誤判，如果你在寫團隊文件，建議直接寫進去。

端點回報「未提供憑證」，但憑證明明設好了。

這是本文實測遇到的狀況。在子行程裡 $env:ANTHROPIC_AUTH_TOKEN 讀出來是空的，端點於是回報沒有收到憑證，表現跟金鑰失效幾乎一致。

從伺服器的角度看這兩種情況是無法區分的：一個沒帶憑證的請求送達了，伺服器無從判斷你是沒有憑證、還是憑證在中途弄丟了。所以錯誤訊息雖然準確，卻把人指向錯誤的假設。

在 PowerShell 裡比較可靠的做法是明確從使用者範圍讀取，不要依賴 $env:：

[Environment]::GetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN','User')

請求回 404，但網址看起來沒問題。

檢查 /v1 是否重複。這是前面那個不對稱問題最常見的表現。

端點位址帶了查詢參數。

很多人的位址是從某個分享連結複製來的，尾巴掛著 ?utm_source=xxx 之類的東西。在瀏覽器裡無所謂，填進 API 端點輕則被忽略，重則驗證不過。端點位址必須是乾淨的。

Git 安裝失敗，是不是要整個重來。

不必。本文實測環境沒有安裝 Git，claude 命令運作正常，第四項端到端請求也通過。這說明 Git 不是 Claude Code 的執行相依項目。完整安裝腳本會一併安裝 Git，是為了後續開發流程所需，並非執行前提。看到 Git 安裝失敗不要推翻整個部署流程，繼續往下驗證。

桌面版 Test connection 不通，但欄位都對。

到左側 Sandbox & workspace 與 Egress 兩欄，看允許出網的清單裡有沒有你的閘道網域。（本文實測環境未重現，僅作為排查方向。）

憑證管理

最後這一段不是技術問題，但比技術問題更容易出事。

憑證不是存放在受管控的金鑰保管服務裡，而是以明文形式存在於你的使用者環境變數或家目錄檔案中。任何能讀取該使用者工作階段的行程都能取得它。

三項最低要求：

• 不要隨程式碼提交進版本控制系統
• 不要出現在螢幕截圖與教學文件中
• 人員異動或機器汰換時，確實撤銷舊金鑰

這三件在個人使用情境下屬於良好習慣，在團隊情境下應該寫進資訊安全規範。就我自己的經驗，最容易疏忽的是第二項——除錯的時候金鑰經常就明文躺在螢幕上，而當下完全不會意識到。

小結

整個流程其實不長：判斷自己屬於哪種情況、執行對應的腳本或填好圖形介面、然後做四項驗證。

真正需要記住的是三件事。第一，兩個 Base URL 的 /v1 規則不一樣，把它們統一成同一種寫法是錯的，而且不一定會報錯——有的閘道回你一個沒有解釋的 404，有的照樣回 200，讓你完全看不出來。第二，設定完成後必須開新的終端機視窗，在舊視窗裡驗證失敗是預期結果。第三，前三項驗證只檢查本機狀態，真正會出問題的地方全部落在第四項。

把「用戶端已安裝」當成「設定已生效」，是這件事上最常見的判斷失誤。版本號能印出來，只證明檔案在磁碟上。