錯誤碼對照表
| 錯誤碼 | 代表什麼 | 先檢查 |
|---|---|---|
| 401 | Key 不對、被停用或已刪除 | ANTHROPIC_AUTH_TOKEN 有沒有完整貼上，控制台裡這把 Key 還在不在 |
| 403 | 餘額不夠，或這把 Key 不能用這個模型 | 控制台概覽 的餘額；換一個模型試試 |
| 404 | 模型名打錯，或網址路徑不對 | 模型名照 模型頁 複製；base URL 不要加 /v1 |
| 429 | 請求太快 | 等幾秒到一分鐘再試，不要同時開太多個 Claude Code |
| 5xx | 上游模型暫時出錯 | 過一會兒重試；持續很久就換個模型或聯絡客服 |
| 連不上 / timeout | 網路或代理擋住了 | 公司 VPN、Proxy、防火牆設定 |
依序排查：五分鐘找出問題
- 確認變數真的有讀到：在同一個終端機執行
echo $ANTHROPIC_BASE_URL，應該顯示https://api.macloudai.com，後面沒有/v1、沒有多餘的斜線或空白。 - 確認 Key：到控制台 API Key 看這把 Key 還在不在；不確定就建一把新的重新貼上。
- 確認餘額：控制台概覽 的餘額是否大於零。
- 確認模型名：從 模型頁 直接複製，不要憑記憶打。
- 用下面的 curl 指令繞過 Claude Code 直接測 API，看是 API 的問題還是 Claude Code 設定的問題。
- 看 用量：有記錄代表請求有到我們這邊，問題在回應或模型；完全沒記錄代表請求根本沒送到。
curl https://api.macloudai.com/v1/messages \
-H "x-api-key: sk-..." \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "hk-5-5", "max_tokens": 64, "messages": [{"role": "user", "content": "你好"}]}'curl.exe https://api.macloudai.com/v1/messages `
-H "x-api-key: sk-..." `
-H "anthropic-version: 2023-06-01" `
-H "content-type: application/json" `
-d '{\"model\": \"hk-5-5\", \"max_tokens\": 64, \"messages\": [{\"role\": \"user\", \"content\": \"hi\"}]}'curl 有正常回應，代表 Key、餘額、模型名都沒問題，剩下的就是 Claude Code 這邊的設定。注意 curl 裡的完整路徑是 https://api.macloudai.com/v1/messages，那是 Anthropic SDK 自己會接上去的路徑；你在 ANTHROPIC_BASE_URL 只填 https://api.macloudai.com。
為什麼 base URL 多了 /v1 就會壞？
Claude Code 和 Anthropic SDK 會自動在 base URL 後面接 /v1/messages。如果你填的是 https://api.macloudai.com/v1，實際送出的網址就變成 /v1/v1/messages，伺服器找不到這個路徑，回 404。
容易混淆的原因是 Cursor、LobeChat、OpenAI SDK 這類 OpenAI 格式的工具，網址要加 /v1。記法很簡單：Claude Code 和 Anthropic SDK 不加，OpenAI 格式的工具加。
從別的網頁或聊天紀錄複製網址時，常會多帶一個結尾斜線或看不見的空白。最保險是直接在終端機手打 https://api.macloudai.com。
環境變數沒生效的常見原因
- 改了
~/.zshrc但沒開新視窗，或沒執行source ~/.zshrc。 - macOS 用 zsh，卻把設定寫進
~/.bash_profile，結果根本沒被讀到。 - Windows 用
setx設定後，沒把 PowerShell、Windows Terminal 或 VS Code 整個關掉重開；VS Code 內建終端機要整個 VS Code 重開才會讀到新變數。 - 同時在
settings.json和 shell 裡設了不同的值，結果用的不是你以為的那個。只留一種。 settings.json格式錯誤（多了逗號、少了引號），整份設定都沒被讀。可以把內容貼到任何 JSON 檢查工具看一下。- 把專案層級的
.claude/settings.json和使用者層級的~/.claude/settings.json搞混，專案裡的設定蓋過了你的使用者設定。
和 Anthropic 官方帳號登入的衝突
如果你之前用 claude 登入過 Anthropic 官方帳號（Claude Pro 或官方 Console），Claude Code 可能優先使用那組登入資訊，而不是你設的環境變數。症狀是：用量頁沒有記錄、或者跳出要你登入官方帳號的畫面、或出現官方帳號的額度提示。
處理方式：在 Claude Code 裡執行 /logout 登出官方帳號，關掉後重新開，確認環境變數或 settings.json 都設好了再執行 claude。如果你兩邊都想用，可以把 MaCloud AI 的設定寫在 shell 裡的一個函式或別名，需要時才帶上，避免互相干擾。
登出位置：在 Claude Code 對話框直接輸入 /logout 按 Enter。登出後重開 claude，如果它又問要不要登入，代表環境變數還是沒讀到，回到上一段檢查。
公司網路、VPN、Proxy 擋住了怎麼辦？
在新竹科學園區或香港的公司裡常遇到：家裡能用，到公司就 timeout 或憑證錯誤。這通常是公司防火牆或 Proxy 擋了外部網址。
- 先用手機熱點測一次，能通就確定是公司網路的問題。
- 公司有指定 Proxy 時，設定
HTTPS_PROXY（例如export HTTPS_PROXY=http://proxy.公司.內部:8080，實際網址問 IT），Claude Code 會走這個代理。 - 如果公司會解開 HTTPS 檢查流量，可能需要把公司的根憑證設給 Node.js（
NODE_EXTRA_CA_CERTS指到憑證檔）。這部分請和 IT 確認。 - 個人 VPN 切換節點時連線會短暫中斷，看到零星的連線錯誤可以先重試。
429 和 5xx 一直出現怎麼辦？
429 代表短時間內請求太多。常見原因是同時開了好幾個 Claude Code 視窗跑任務，或者寫了腳本並行呼叫。等一下再試通常就好；長期解法是減少同時進行的任務數。
5xx 是上游模型那邊暫時出問題，不是你的設定錯。等幾分鐘重試；如果某個模型一直不穩，可以先把 ANTHROPIC_MODEL 換成 模型頁 上的另一個 Claude 模型繼續工作。持續很久都不行，就帶著發生時間和錯誤訊息聯絡客服。
最後的檢查清單
ANTHROPIC_BASE_URL=https://api.macloudai.com，沒有/v1、沒有結尾斜線。ANTHROPIC_AUTH_TOKEN是完整的sk-...，前後沒有空白或引號。ANTHROPIC_MODEL從模型頁複製。- 控制台裡 Key 還在、餘額大於零。
- 已經
/logout官方帳號，或確定沒登入過。 - 改完設定有開新的終端機視窗。
- curl 測試能通。
設定步驟本身可以回頭看 Claude Code 中轉怎麼設定，各種工具的接法在 接入文件。
