部落格 / 開發工具

Claude Code 自定義 API 與 Codex、OpenCode 介面地址配置

2026-10-17cdnping 編輯部約 5 分鐘讀完

Claude Code 自定義 API 地址靠兩個環境變數：ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN。Codex 和 OpenCode 則是在各自的配置檔案裡宣告一個“供應商”，寫上 base url 和金鑰來源。改完如果報錯，多半是地址路徑寫錯、金鑰型別不對或者網路不通，後文的排錯表可以逐項對照。

下面只寫官方文件裡有記載的配置項。這幾個工具更新快，欄位名可能變化，標了“以官方文件為準”的地方，動手前先核對當前版本的文件。

#填進去的介面地址要滿足什麼條件？

先確認你要接的服務和工具用的是同一種介面格式。

只相容 OpenAI 格式的地址填進 Claude Code 跑不通，反過來也一樣，這是 404 的常見來源。

另外兩點：

• base url 一般只寫到根路徑或 /v1，工具會自己拼後面的 /messages、/chat/completions。要不要帶 /v1，看服務方的接入說明。
• 金鑰不要寫進專案倉庫，放在 shell 配置、使用者目錄下的配置檔案或系統的金鑰管理裡。

#Claude Code 怎麼設定自定義 API 地址？

Claude Code 官方文件裡與此相關的環境變數有三個：

ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 走的是不同的請求頭。服務方要哪一種就設哪一種，不要兩個都填。

#方式一：在終端裡臨時設定

export ANTHROPIC_BASE_URL="https://your-endpoint.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxx"
claude

適合先試通不通，關掉終端就失效。

#方式二：寫進 settings.json

settings.json 支援 env 欄位，裡面的變數在每次會話啟動時生效。使用者級配置在 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-endpoint.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxx"
  }
}

專案目錄下也可以放 .claude/settings.json，但這個檔案通常會提交到倉庫，金鑰別寫在裡面。專案級的私有配置用 .claude/settings.local.json，並確認它在 .gitignore 裡。

#怎麼確認生效了

啟動後在 Claude Code 裡執行 /status，檢視當前的 API 地址和認證來源。如果顯示的還是預設地址，檢查 shell 裡是不是另有同名變數。

#Codex 怎麼配置自定義 base url？

Codex 的配置檔案是 ~/.codex/config.toml。官方文件的做法是用 model_providers 宣告一個自定義供應商，再用 model_provider 指向它。示例：

model_provider = "mygateway"

[model_providers.mygateway]
name = "My Gateway"
base_url = "https://your-endpoint.example.com/v1"
env_key = "MYGATEWAY_API_KEY"

金鑰放在環境變數裡：

export MYGATEWAY_API_KEY="sk-xxxxxxxx"
codex

幾點說明：

• env_key 填的是環境變數的名字，不是金鑰本身，Codex 啟動時去讀這個變數。
• 供應商段落裡還有 wire_api 等欄位，用來指定走哪種 OpenAI 介面。可選值和預設值在不同版本里調整過，以 Codex 官方文件為準。
• 模型名用 model = "..." 指定，填服務方支援的名稱。

#OpenCode 怎麼新增自定義 provider？

OpenCode 的全域性配置一般在 ~/.config/opencode/opencode.json，專案根目錄也可以放一份。接入相容 OpenAI 格式的服務用 provider 欄位，官方文件的寫法大致如下：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "mygateway": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Gateway",
      "options": {
        "baseURL": "https://your-endpoint.example.com/v1"
      },
      "models": {
        "your-model-id": {}
      }
    }
  }
}

金鑰可以用 opencode auth login 互動錄入，也可以在 options 裡引用環境變數。具體欄位名，以及 Anthropic 格式供應商的寫法，以 OpenCode 官方文件為準。

#接聚合閘道器時有什麼不同？以 AGI Plan 為例

用聚合閘道器的流程和上面一樣，只是地址和金鑰換成閘道器給的。以 AGI Plan 為例（AGI Plan 是 cdnping 的商業合作方）：它同時相容 OpenAI 和 Anthropic 兩種介面格式，Claude Code、Codex、OpenCode 都能接。接入分三步：郵箱驗證碼註冊、選套餐並建金鑰、改一處配置。各工具的地址和分步教程見 agiplan.dev。AGI Plan 站方說明自己不是官方授權渠道，部分模型標註為“僅境外”，具體以 模型頁 為準。使用前看清說明，並遵守各服務的條款和當地法規。

#報 401、404、超時怎麼查？

改完配置報錯，按下表從上往下查。

通用的 curl 自檢命令（Anthropic 格式，按服務方要求換成對應的請求頭）：

curl -sS -o /dev/null -w "HTTP %{http_code}  連線 %{time_connect}s  總計 %{time_total}s\n" \
  "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"your-model-id","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

返回 200 說明地址和金鑰都對，問題在工具配置；返回 401 或 404 對照上表；命令卡住不返回，就是網路問題。

#超時是服務端的問題還是本機網路的問題？

超時有兩種可能：對方服務故障，或者你這邊到對方的路不通。分開查會快很多。

第一步，看服務方是否正常。開啟 API 狀態頁，它從 Cloudflare 邊緣每 5 分鐘探測一次各家官方 API 入口，並同步部分官方狀態頁。用 AGI Plan 的可以直接看 /status/agiplan；用 Claude Code 也可以看 /down/claude-code，那裡彙總了官方狀態頁、API 探測和使用者報告。

作為參照：cdnping 在 2026 年 10 月 17 日從 Cloudflare 丹佛節點（DEN）做的邊緣探測中（統計視窗約 85 分鐘，共 242 次探測，來源 cdnping /status），api.anthropic.com 的 p50 為 73 ms，api.openai.com 為 96 ms，視窗內都沒有失敗。cdnping 從這一天才開始採集，這只是一小段視窗的機房到機房資料，不代表你本機的體驗，只能說明當時服務端在正常響應。如果狀態頁正常而你這邊超時，問題多半在本地網路。

第二步，查本機網路。開啟 IP 與環境檢測，重點看三項：

1. 出口 IP 與型別：確認終端實際走的出口在哪裡，是機房、家寬還是行動網路。
2. 大陸分流檢測：判斷當前是“大陸分流 / 全域性代理 / 國內直連”。瀏覽器走了代理而終端沒走，是常見情況。
3. 多出口檢測與 DNS 洩漏：看訪問不同服務時出口是否一致，DNS 是否走了預期的解析器。

檢測完可以生成帶水印的結果圖，並可選擇隱藏 IP 地址。發給同事或在群裡求助時，把這張圖附上，不會把自己的出口 IP 暴露出去。指紋在本地計算，不上傳。

第三步，測延遲。首頁的線上測速在瀏覽器裡測到 15 個 AI 模型 API 的“首次連線”（含 DNS 和 TLS 握手）和“往返”時間。首次連線明顯偏高而往返正常，通常是 DNS 或握手階段的問題；兩者都高，就是鏈路本身慢。延遲的成因可以參考 AI API 延遲為什麼高。

瀏覽器和終端不一定走同一條網路路徑。瀏覽器裡測得通、終端裡不通，先檢查終端有沒有設定 HTTPS_PROXY 等變數，以及分流規則是否覆蓋了介面域名，原理見分流原理。

#照著做：從配置到自檢

1. 選一個工具，先用環境變數臨時配好，跑一次上面的 curl 自檢。
2. 通了再寫進配置檔案，確認金鑰檔案不在倉庫裡。
3. 下次報錯，先看 /status 確認服務端，再開啟 /ip 查本機；求助時附上隱藏了 IP 的結果圖。