Claude Code 環境變量
本文說明 Claude Code 的每一個環境變量：各自的作用、應該設定在哪裡，以及如何通過 claudeCode.environmentVariables 傳遞到 VS Code 面板。
Claude Code 幾乎完全依靠環境變量來配置。身份驗證、API 端點、模型、重試與超時行為，以及針對代理和閘道的每一個相容性開關，都是環境變量——不是命令行參數，也不是配置嚮導裡的欄位。如果你的 Claude Code 配置沒有按預期工作，本頁就是檢查清單：哪個變量、哪個文件、哪條優先順序規則。
claudeCode.environmentVariables 是什麼
claudeCode.environmentVariables 是 VS Code 設定項，用於把環境變量交給 Claude Code 插件面板。它是一個普通的 { "name": ..., "value": ... } 陣列，儲存在 VS Code 的用戶 settings.json 中：
1 "claudeCode.environmentVariables": [2 { "name": "ANTHROPIC_BASE_URL", "value": "https://www.codebyai.net/api/agent" },3 { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-proj-xxxx" }4 ]
在修改這個陣列之前，有四個特性值得先了解，因為它們都會讓人出乎意料：
| 特性 | 後果 |
|---|---|
| 它是對象陣列，不是對映 | "KEY": "value" 會被靜默忽略——面板啟動時沒有任何變量 |
| 它的作用域是整臺機器 | 該電腦上的每個 VS Code 窗口都會受影響，而不只是當前文件夾 |
| 它與其他無關變量共用同一個陣列 | 代理設定或 NODE_EXTRA_CA_CERTS 就在同一個陣列裡——一旦覆蓋，它們就沒了 |
| 它只在啟動智能體時讀取一次 | 修改後不起作用，直到運行開發人員: 重新加載窗口（或重啓 VS Code） |
為什麼 shell 裡的 export 到不了插件面板
claude CLI 會繼承啟動它的程序的環境，所以在 ~/.zshrc 裡 export ANTHROPIC_BASE_URL=... 是有效的。插件則不是：它從 VS Code 窗口程序派生自己的智能體程序，因此面板看到的是 VS Code 啟動時所在的桌面/登錄環境——而不是你輸入 export 的那個 shell。
這正是最常見的 Claude Code 配置錯誤的成因：終端裡能用，插件面板卻一直在跟默認端點通訊。要麼從那個終端裡啟動 VS Code（這樣它會繼承這些變量——但此後每個窗口都會被路由過去），要麼設定 claudeCode.environmentVariables，這是插件自己的變通入口。
檢查面板實際看到的內容
以下命令會打印插件將要注入的變量名，並把看起來像憑據的值遮蔽掉：
1 # macOS2 S="$HOME/Library/Application Support/Code/User/settings.json"3 # Linux: S="$HOME/.config/Code/User/settings.json"4 # Windows: S="$APPDATA/Code/User/settings.json"5 6 jq -r '.["claudeCode.environmentVariables"] // [] | .[] | "\(.name)"' "$S"
沒有任何輸出，說明面板繼承了 VS Code 程序的環境——變量必須來自其他地方。
變量可以設定的三個位置
| 位置 | 適用於 | 是否持久 |
|---|---|---|
Shell export（~/.zshrc、~/.bashrc、Windows 環境變量） | 從 shell 啟動的 claude CLI | 是，按 shell 會話 |
settings.json 中的 env 塊（~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json） | CLI、VS Code 插件和 Agent SDK | 是，按設定作用域 |
claudeCode.environmentVariables | 僅 VS Code 插件面板 | 是，整臺機器 |
settings.json 的幾個作用域值得區分：
| 文件 | 作用域 |
|---|---|
~/.claude/settings.json | 你本人，在所有項目中 |
.claude/settings.json | 項目中的所有人（請提交到倉庫） |
.claude/settings.local.json | 只有你，僅限此項目（已被 git 忽略） |
| 託管配置 | 組織中的所有人 |
1 {2 "env": {3 "ANTHROPIC_BASE_URL": "https://www.codebyai.net/api/agent",4 "API_TIMEOUT_MS": "600000"5 }6 }
優先順序規則
- 環境變量優先於對應的
settings.json欄位（例如ANTHROPIC_MODEL優先於model）。 - 命令行上的
--model和會話內的/model優先於ANTHROPIC_MODEL。 - 在互動模式下，
ANTHROPIC_API_KEY優先於互動式訂閱登錄；在-p（print）模式下則始終使用 API 金鑰。 - 變量在程序啟動時讀取。會話進行中不會有任何重新加載：請重啓
claude，或在 VS Code 中運行開發人員: 重新加載窗口。
讓 Claude Code 指向 Code By AI
Code By AI 提供 Anthropic 相容的端點，因此涉及的變量只有端點和與之配套的 token。請選擇與你的 Claude Code 啟動方式相匹配的位置。
終端 / CLI
1 # ~/.zshrc or ~/.bashrc2 export ANTHROPIC_BASE_URL="https://www.codebyai.net/api/agent"3 export ANTHROPIC_AUTH_TOKEN="sk-proj-xxxx"4 export API_TIMEOUT_MS=6000005 export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
VS Code 插件
1 "claudeCode.environmentVariables": [2 { "name": "ANTHROPIC_BASE_URL", "value": "https://www.codebyai.net/api/agent" },3 { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-proj-xxxx" },4 { "name": "API_TIMEOUT_MS", "value": "600000" },5 { "name": "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "value": "1" }6 ],
重新加載窗口，然後確認面板頂部顯示的是閘道端點。包含 Windows 命令行等價寫法的逐步說明見 Claude Code 配置。
ANTHROPIC_AUTH_TOKEN 會以 Authorization: Bearer <value> 發送，這正是 Code By AI 閘道所期望的形式。ANTHROPIC_API_KEY 則以 X-Api-Key 發送——兩者只用其一，絕不要同時設定，否則可能讓錯誤的那個生效。
變量參考
身份驗證
| 變量 | 用途 |
|---|---|
ANTHROPIC_API_KEY | 以 X-Api-Key 請求頭髮送的 API 金鑰。在 -p 模式下始終使用 |
ANTHROPIC_AUTH_TOKEN | 自定義 Authorization 請求頭的值，前綴為 Bearer |
CLAUDE_CODE_OAUTH_TOKEN | 用於 Claude.ai 身份驗證的 OAuth 訪問令牌，適用於 SDK 和自動化環境 |
CLAUDE_CODE_OAUTH_REFRESH_TOKEN | 由 claude auth login 在無需瀏覽器的情況下交換的刷新令牌 |
CLAUDE_CODE_OAUTH_SCOPES | 刷新令牌簽發時使用的、以空格分隔的作用域 |
端點與提供商路由
| 變量 | 用途 |
|---|---|
ANTHROPIC_BASE_URL | 覆蓋 API 端點（代理或閘道）。使用非第一方主機時，除非 ENABLE_TOOL_SEARCH=true，否則會禁用 MCP 工具搜尋 |
CLAUDE_CODE_USE_BEDROCK / _VERTEX / _FOUNDRY | 經 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 路由 |
ANTHROPIC_BEDROCK_BASE_URL / ANTHROPIC_VERTEX_BASE_URL / ANTHROPIC_FOUNDRY_BASE_URL | 按提供商覆蓋端點 |
HTTP_PROXY / HTTPS_PROXY / NO_PROXY | 網絡連接的出站代理 |
CLAUDE_CODE_SKIP_BEDROCK_AUTH 及同類變量 | 當 LLM 閘道自行對請求籤名時，跳過提供商的身份驗證 |
模型選擇
| 變量 | 用途 |
|---|---|
ANTHROPIC_MODEL | 要使用的模型。會被 --model 和 /model 覆蓋 |
ANTHROPIC_DEFAULT_SONNET_MODEL / _HAIKU_ / _OPUS_ | 固定某一檔位的默認模型 ID |
ANTHROPIC_CUSTOM_MODEL_OPTION / _NAME / _DESCRIPTION | 在 /model 選擇器中新增自定義條目 |
CLAUDE_CODE_SUBAGENT_MODEL | 子智能體使用的模型 |
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY | 設為 1，即可從閘道的 /v1/models 填充 /model 列表 |
MAX_THINKING_TOKENS | 插件思考預算；0 會在 Anthropic API 上禁用思考 |
CLAUDE_CODE_MAX_OUTPUT_TOKENS | 每次請求的最大輸出 token 數 |
超時與重試
| 變量 | 默認值 | 用途 |
|---|---|---|
API_TIMEOUT_MS | 600000 | API 請求的超時時間，單位為毫秒 |
BASH_DEFAULT_TIMEOUT_MS | 120000 | 長時間運行的 Bash 命令的默認超時 |
BASH_MAX_TIMEOUT_MS | 600000 | 模型可以為 Bash 設定的最大超時 |
CLAUDE_CODE_MAX_RETRIES | 10 | 失敗的 API 請求的重試次數 |
代理與閘道相容性
這些變量決定第三方端點究竟能不能用：
| 變量 | 用途 |
|---|---|
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | 1 用一個開關關掉自動更新程序、反饋命令、錯誤上報和遙測 |
CLAUDE_CODE_ATTRIBUTION_HEADER | 0 會從系統提示中移除署名塊，從而提升閘道後面的提示快取命中率 |
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS | 1 會去掉代理可能拒絕的 anthropic-beta 請求頭 |
CLAUDE_CODE_DISABLE_THINKING | 完全省略 thinking 參數 |
ENABLE_TOOL_SEARCH | true / false / auto：在自定義 ANTHROPIC_BASE_URL 上控制 MCP 工具的延遲載入 |
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK | 避免流式傳輸中途失敗後以非流式方式重新運行工具呼叫 |
DISABLE_PROMPT_CACHING | 關閉提示快取（僅用於調試——它會提高成本） |
診斷與路徑
| 變量 | 用途 |
|---|---|
DEBUG | 設為 1（或 true、yes、on）可啟用調試模式，等同於 --debug |
CLAUDE_CODE_DEBUG_LOG_LEVEL | 最低日誌級別：verbose、debug、info、warn、error |
CLAUDE_CONFIG_DIR | 覆蓋配置目錄，默認是 ~/.claude |
CLAUDE_CODE_SIMPLE | 1 表示以最小系統提示運行，且只保留 Bash 和文件工具 |
故障排查
變量似乎被忽略了。 先檢查設定位置。shell export 對 VS Code 插件面板不可見，claudeCode.environmentVariables 對 CLI 不可見。然後檢查重啓這一步：環境變量只在程序啟動時讀取一次。
切換端點後出現 401 或 invalid api key。 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 通過不同的請求頭髮送。同一作用域裡殘留的 ANTHROPIC_API_KEY 會在 -p 模式下勝出——如果你用 token 進行身份驗證，請把它移除。
經過代理後每個請求都失敗。 新增 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1；有些代理會拒絕 Claude Code 默認發送的 beta 請求頭。
長時間生成時請求超時。 與其重試，不如調高 API_TIMEOUT_MS（默認是十分鐘）——這個超時已經很寬鬆，但一個大 diff 仍可能超過它。
在閘道上 /model 選擇器是空的。 設定 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，讓選擇器由閘道的 /v1/models 填充，或者用 ANTHROPIC_MODEL 顯式指定模型。
閘道後面的提示快取命中率偏低。 設定 CLAUDE_CODE_ATTRIBUTION_HEADER=0：署名塊在會話之間會發生變化，使已快取的前綴失效。
常見問題
Claude Code 從哪裡讀取環境變量？
從它啟動時所在的程序環境讀取，並與適用的 settings.json 文件中的 env 塊合併。當兩者定義同一行為時，環境變量優先。VS Code 插件面板是獨立的程序樹，需要改用 claudeCode.environmentVariables。
修改變量後需要重啓嗎？
需要。Claude Code 在啟動時讀取配置。CLI 需重啓 claude，插件則需在 VS Code 中運行開發人員: 重新加載窗口。
ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 哪個優先？
在 -p 模式下是 ANTHROPIC_API_KEY，它還會覆蓋互動式訂閱登錄。如果你經一個使用 bearer token 進行身份驗證的閘道路由，請取消設置 ANTHROPIC_API_KEY，以消除這種歧義。
不改變量也能換用其他模型嗎？
可以——啟動時的 --model 和會話內的 /model 都會覆蓋 ANTHROPIC_MODEL。變量設定默認值，命令行參數覆蓋變量。
Claude Code、Codex 和 Gemini 在 Code By AI 上都通過同一個端點和同一把金鑰工作，價格僅為官方 API 的 1/6。檢視價格對比或充值並獲取金鑰。