Claude Code 环境变量完全指南：解决 AWS Bedrock 兼容性报错只需 1 个设置

作者注：详解 Claude Code 全部 60+ 环境变量的作用和配置方法，重点解决 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 解决第三方平台 anthropic-beta header 报错

在使用 Claude Code 连接 AWS Bedrock、Google Vertex AI 或其他第三方 LLM 网关时，你很可能遇到过这个报错："Unexpected value(s) for the anthropic-beta header"。这个问题的根源是 Claude Code 默认会发送 Anthropic API 特有的实验性 Beta 头部，而 AWS Bedrock 等第三方平台并不认识这些头部。

解决方案只需一行设置：CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。

但 Claude Code 的环境变量远不止这一个——官方文档列出了 60+ 个环境变量，覆盖认证配置、模型选择、性能调优、功能开关等各个方面。本文将系统梳理这些环境变量，帮你快速定位和解决 Claude Code 的各类配置问题。

核心价值: 读完本文，你将掌握 Claude Code 环境变量的完整体系，能够快速解决 AWS Bedrock/Vertex AI 兼容性问题，并学会通过环境变量优化 Claude Code 的使用体验和成本。

Claude Code 环境变量核心要点

Claude Code 的 60+ 个环境变量可以分为 6 大类。以下是你最需要关注的核心变量：

Claude Code 环境变量的两种设置方式

方式一：Shell 环境变量（临时生效）

在终端中设置后启动 Claude Code，仅当前会话有效：

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export ANTHROPIC_API_KEY="your-api-key"
claude

方式二：settings.json 配置（永久生效）

在 ~/.claude/settings.json 中配置 env 字段，每次启动自动加载：

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "ANTHROPIC_API_KEY": "your-api-key"
  }
}

🎯 推荐方式: 对于需要长期生效的设置（如 API Key、平台兼容性修复），建议使用 settings.json 方式，避免每次手动 export。如果你的 API Key 来自 API易 apiyi.com 等第三方平台，同样在这里配置即可。

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 环境变量快速上手

极简示例：配置 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 文档中心