Claude Code 環境變量完全指南：解決 AWS Bedrock 兼容性報錯只需 1 個設置

永久生效 ✓ 團隊可共享

<！– 標籤 –> 推薦用於正式配置

<！– 優先級說明 –> 配置優先級（從高到低）

<！– 優先級箭頭 –> Shell 環境變量

&gt；

settings.json

&gt；

Claude Code 默認值

Shell 環境變量始終覆蓋 settings.json 中的同名配置

<！– 底部品牌 –> API易 apiyi.com — 通過 settings.json 配置 API Key 和 Base URL 即可使用

Claude Code 環境變量重點解讀：解決 AWS Bedrock 兼容性問題

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 詳解

這是本文的核心主角。當你通過 AWS Bedrock、Google Vertex AI、LiteLLM 等第三方網關使用 Claude Code 時，Claude Code 會自動在請求頭中添加 Anthropic 的實驗性 Beta 標識，例如：

anthropic-beta: prompt-caching-scope-2026-01-05，advanced-tool-use-2025-11-20

這些 Beta 標識是 Anthropic 直連 API 的特性，AWS Bedrock 等第三方平臺無法識別，於是返回錯誤：

Error: Unexpected value（s） for the anthropic-beta header

解決方法：

# 方式一：Shell 命令
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# 方式二：settings.json
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

設置爲 1 後，Claude Code 將不再發送這些實驗性 Beta 頭部，從而兼容所有第三方平臺。

已知問題與臨時解決方案

根據 GitHub Issues 記錄，部分 Claude Code 版本（2.1.18 之後）存在該環境變量不完全生效的問題——即使設置了 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1，某些新增的 Beta 頭部（如 advanced-tool-use-2025-11-20）仍然會被髮送。

如果你仍然遇到問題，可以嘗試以下額外措施：

• 降級 Claude Code 版本: 回退到 2.1.68 等已知穩定版本
• 使用 LiteLLM 網關: LiteLLM 提供了 anthropic_beta_headers_config.json 配置文件，可以精細控制哪些 Beta 頭部被轉發
• 同時設置 DISABLE_PROMPT_CACHING: 禁用 Prompt 緩存可以避免 prompt-caching-scope 相關的 Beta 頭部

# 全面兼容設置
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_PROMPT_CACHING=1

Claude Code 環境變量完整分類速查

第一類：認證與 API 配置

這是最基礎也是最常用的環境變量類別，控制 Claude Code 如何連接到 API 服務：

🎯 第三方平臺用戶注意: 使用 API易 apiyi.com 等第三方 API 平臺時，需要同時設置 ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL。Claude Code 會優先使用環境變量中的 API Key，即使你已登錄 Anthropic 訂閱賬號。

第二類：模型選擇與配置

控制 Claude Code 使用哪個模型以及模型的行爲參數：

第三類：平臺兼容與網關配置

這類變量專門解決 Claude Code 與不同雲平臺和 LLM 網關的兼容性問題：

第四類：功能開關

通過 DISABLE_ 或 CLAUDE_CODE_DISABLE_ 前綴的變量關閉特定功能：

第五類：上下文與性能管理

控制 Claude Code 如何管理上下文窗口和資源使用：

🎯 性能優化建議: 如果你在長對話中發現 Claude Code 頻繁壓縮上下文，可以將 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 設爲更低的值（如 50），讓壓縮提前觸發，減少信息丟失。通過 API易 apiyi.com 調用時同樣支持這些環境變量配置。

<！– 標題 –> Claude Code 60+ 環境變量分類總覽 按使用頻率排序 · 橙色高亮爲本文重點

<！– 第一行：3 個卡片 –> <！– 1. 平臺兼容（高亮） –> 平臺兼容 9 個 DISABLE_EXPERIMENTAL_BETAS CLAUDE_CODE_USE_BEDROCK SKIP_BEDROCK_AUTH CLAUDE_CODE_USE_FOUNDRY SKIP_VERTEX_AUTH + 4 more… 解決 anthropic-beta 報錯

<！– 2. 認證配置 –> 認證與 API 6 個 ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_CUSTOM_HEADERS ANTHROPIC_BASE_URL CLIENT_CERT / CLIENT_KEY API Key 優先於 /login 訂閱

<！– 3. 模型選擇 –> 模型選擇 7 個 ANTHROPIC_MODEL DEFAULT_OPUS_MODEL DEFAULT_SONNET_MODEL DEFAULT_HAIKU_MODEL EFFORT_LEVEL / MAX_OUTPUT 支持 low/medium/high/max

<！– 第二行：3 個卡片 –> <！– 4. 功能開關 –> 功能開關 12 個 DISABLE_PROMPT_CACHING DISABLE_TELEMETRY DISABLE_AUTO_MEMORY DISABLE_1M_CONTEXT DISABLE_FAST_MODE + 7 more （CRON/GIT/…） NONESSENTIAL_TRAFFIC 一鍵禁用

<！– 5. 上下文管理 –> 上下文與性能 6 個 AUTOCOMPACT_PCT_OVERRIDE AUTO_COMPACT_WINDOW FILE_READ_MAX_OUTPUT CLAUDE_CODE_TMPDIR CLAUDE_CODE_SHELL 壓縮默認 95%，可調低至 50%

<！– 6. 其他 –> 其他設置 20+ ENABLE_TELEMETRY （OTel） EXPERIMENTAL_AGENT_TEAMS ENABLE_PROMPT_SUGGESTION IDE_SKIP_AUTO_INSTALL SHELL_PREFIX + 15 more… SDK/團隊/監控/插件等

<！– 底部統計 –> Claude Code 官方文檔共收錄 60+ 個環境變量 | 完整列表: code.claude.com/docs/en/env-vars

Claude Code 環境變量快速上手

極簡示例：配置 Claude Code 連接第三方 API 平臺

# 在終端中設置環境變量後啓動 Claude Code
export ANTHROPIC_API_KEY="sk-your-api-key"
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-api-key"，
    "ANTHROPIC_BASE_URL": "https://vip.apiyi.com/v1"，
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"，
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000"，
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80"，
    "DISABLE_TELEMETRY": "1"
  }，
  "permissions": {
    "allow": ["Read"， "Glob"， "Grep"]，
    "deny": []
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1"，
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"，
    "DISABLE_PROMPT_CACHING": "1"，
    "ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION": "us-east-1"
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1"，
    "ANTHROPIC_FOUNDRY_BASE_URL": "https://my-resource.services.ai.azure.com/anthropic"，
    "ANTHROPIC_FOUNDRY_API_KEY": "your-foundry-key"，
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

建議: 如果你不想折騰 AWS Bedrock 或 Azure 的複雜配置，可以通過 API易 apiyi.com 直接使用 Claude 全系列模型。只需設置 API Key 和 Base URL 兩個變量，無需處理雲平臺認證和兼容性問題。

常見問題

總結

Claude Code 環境變量的核心要點：

1. 解決 AWS Bedrock 報錯: 設置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 禁用實驗性 Beta 頭部，一行配置解決「Unexpected value（s） for the anthropic-beta header」錯誤
2. 60+ 環境變量分 6 大類: 認證配置、模型選擇、平臺兼容、功能開關、上下文管理、其他設置
3. 兩種配置方式: Shell export（臨時）和 settings.json（永久），推薦永久配置寫入 settings.json
4. 第三方平臺簡化方案: 通過 API易 apiyi.com 等統一 API 平臺，只需設置 ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL 兩個變量，無需處理複雜的雲平臺認證和 Beta 頭部兼容性

推薦通過 API易 apiyi.com 快速體驗 Claude Code 接入，平臺提供免費額度和統一接口，避免 AWS Bedrock/Vertex AI 配置中的各種兼容性坑。

📚 參考資料

1. Claude Code 官方文檔 – 環境變量: 完整的環境變量列表和說明

   • 鏈接: code.claude.com/docs/en/env-vars
   • 說明: 所有 60+ 環境變量的官方權威參考

2. Claude Code 官方文檔 – 設置: 配置作用域和 settings.json 規範

   • 鏈接: code.claude.com/docs/en/settings
   • 說明: 理解 Managed/User/Project/Local 四級配置體系

3. Claude Code 官方文檔 – Amazon Bedrock: AWS Bedrock 集成指南

   • 鏈接: code.claude.com/docs/en/amazon-bedrock
   • 說明: Bedrock 專用配置和常見問題解決

4. GitHub Issue #22893 – DISABLE_EXPERIMENTAL_BETAS 不完全生效: 社區 Bug 報告

   • 鏈接: github.com/anthropics/claude-code/issues/22893
   • 說明: 瞭解該環境變量的已知侷限和臨時解決方案

5. LiteLLM – Claude Code Beta Headers 管理: 網關層面的 Beta 頭部過濾方案

   • 鏈接: docs.litellm.ai/docs/tutorials/claude_code_beta_headers
   • 說明: 使用 LiteLLM 網關時的精細化 Beta 頭部控制

作者: APIYI 技術團隊
技術交流: 歡迎在評論區討論 Claude Code 配置經驗，更多使用教程可訪問 API易 docs.apiyi.com 文檔中心