Claude Code 深度学习手册

主题

环境变量参考 ​

Claude Code 官方支持的环境变量清单：鉴权、模型、超时、渲染、遥测等。

是什么 ​

环境变量是 Claude Code 在交互式与非交互式（-p/SDK）会话中读取的运行期开关，用于覆盖鉴权方式、API 端点、模型选择、超时与重试、终端渲染、遥测与隐私等行为。

本页仅收录官方文档明确列出的变量。许多变量是布尔开关（设为 1 生效），部分带数值默认（如超时毫秒数），其余默认为未设置（None）。

怎么工作 ​

  • 鉴权优先级：ANTHROPIC_API_KEY 设置后在非交互模式（-p）下始终覆盖订阅；交互模式下首次需确认一次；unset ANTHROPIC_API_KEY 可恢复订阅。
  • CLAUDE_CODE_OAUTH_TOKEN 优先于 keychain 中存储的凭据；可用 claude setup-token 生成。
  • ANTHROPIC_BASE_URL 可把请求路由到代理/网关；指向非第一方主机时默认禁用 MCP tool search，需 ENABLE_TOOL_SEARCH=true 才启用。
  • 聚合开关 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 等价于同时设置 DISABLE_AUTOUPDATER、DISABLE_FEEDBACK_COMMAND、DISABLE_ERROR_REPORTING、DISABLE_TELEMETRY。
  • 遥测需先设 CLAUDE_CODE_ENABLE_TELEMETRY=1 才能配置 OTel 导出器；DISABLE_TELEMETRY 与标准信号 DO_NOT_TRACK 会关闭遥测。
  • CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 是按 CLAUDE_CODE_AUTO_COMPACT_WINDOW 容量的百分比应用的；后者默认取模型上下文窗口（标准 200K / 扩展 1M）。

怎么配置 / 用法 ​

bash
# 鉴权与端点
ANTHROPIC_API_KEY=...            # X-Api-Key，覆盖订阅
ANTHROPIC_AUTH_TOKEN=...          # Authorization: Bearer <值>
CLAUDE_CODE_OAUTH_TOKEN=...       # Claude.ai OAuth，优先于 keychain
ANTHROPIC_BASE_URL=...            # 路由到代理/网关
ANTHROPIC_CUSTOM_HEADERS=...      # 'Name: Value' 多行

# 模型与 token
ANTHROPIC_MODEL=...               # 主模型
ANTHROPIC_DEFAULT_HAIKU_MODEL=... # 后台/Haiku 类
CLAUDE_CODE_EFFORT_LEVEL=auto     # low|medium|high|xhigh|max|auto
CLAUDE_CODE_MAX_OUTPUT_TOKENS=... # 输出 token 上限
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50# 触发自动压缩的容量百分比(默认~95)

# 超时与重试
API_TIMEOUT_MS=600000             # API 请求超时(默认10分钟)
BASH_DEFAULT_TIMEOUT_MS=120000    # bash 默认超时
BASH_MAX_TIMEOUT_MS=600000        # bash 最大超时
CLAUDE_CODE_MAX_RETRIES=10        # 失败重试次数

# 终端渲染
CLAUDE_CODE_NO_FLICKER=1          # 启用全屏渲染(research preview)
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 # 用经典主屏渲染
CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1   # 禁用自动终端标题

# 遥测与隐私
CLAUDE_CODE_ENABLE_TELEMETRY=1
DISABLE_TELEMETRY=1
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

什么时候用 ​

  • 通过企业代理/LLM 网关或第三方平台（Bedrock / Vertex / Foundry / AWS）路由请求时配置端点与鉴权变量。
  • 在 CI、SDK 或自动化环境中用 CLAUDE_CODE_OAUTH_TOKEN 等做无浏览器鉴权。
  • 慢网络或代理下请求超时时调大 API_TIMEOUT_MS、BASH_*_TIMEOUT_MS。
  • 需要静默网络/合规时用 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 及各 DISABLE_*。
  • 终端渲染异常（残影、闪烁、滚动空白）时用对应 CLAUDE_CODE_* 渲染开关排查。

限制 / 坑 ​

  • ANTHROPIC_SMALL_FAST_MODEL 在本页标注为 [DEPRECATED]（已弃用的 Haiku 类后台模型名）。
  • API_TIMEOUT_MS 最大 2147483647，超过该值会使底层计时器溢出导致请求立即失败。
  • CLAUDE_CODE_MAX_CONTEXT_TOKENS 仅在同时设置 DISABLE_COMPACT 时才生效。
  • CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 高于默认阈值的取值无效；其百分比按 CLAUDE_CODE_AUTO_COMPACT_WINDOW 容量计算。
  • 本页未收录 MCP_TIMEOUT、MCP_TOOL_TIMEOUT、MAX_MCP_OUTPUT_TOKENS、USE_BUILTIN_RIPGREP、FORCE_COLOR 等变量（它们记录在各自功能页）。

硬事实速查（37 条） ​

  • ANTHROPIC_API_KEY：作为 X-Api-Key 头发送；设置后覆盖订阅，-p 模式下始终使用，交互模式首次需确认
  • ANTHROPIC_AUTH_TOKEN：作为 Authorization 头的自定义值，会被加上 Bearer 前缀
  • ANTHROPIC_CUSTOM_HEADERS：向请求添加自定义头，Name: Value 格式，多个头用换行分隔
  • ANTHROPIC_BASE_URL：覆盖 API 端点以经代理/网关路由；非第一方主机默认禁用 MCP tool search
  • CLAUDE_CODE_OAUTH_TOKEN：Claude.ai OAuth 访问令牌，SDK/自动化环境的 /login 替代，优先于 keychain 凭据
  • ANTHROPIC_WORKSPACE_ID：用于 workload identity federation 的 workspace ID
  • CLAUDE_CODE_CERT_STORE：TLS 的 CA 证书来源列表，默认 bundled,system（bundled 为内置 Mozilla CA，system 为系统信任库）
  • ANTHROPIC_BEDROCK_BASE_URL：覆盖 Bedrock 端点 URL，用于自定义端点或经 LLM 网关路由
  • ANTHROPIC_BEDROCK_SERVICE_TIER：Bedrock 服务层（default/flex/priority），作为 X-Amzn-Bedrock-Service-Tier 头发送
  • AWS_BEARER_TOKEN_BEDROCK：用于鉴权的 Bedrock API key
  • ANTHROPIC_VERTEX_BASE_URL：覆盖 Vertex AI 端点 URL，用于自定义端点或经 LLM 网关路由
  • ANTHROPIC_VERTEX_PROJECT_ID：Vertex AI 请求的 GCP 项目 ID（会被 GCLOUD_PROJECT 等覆盖）
  • ANTHROPIC_BETAS：逗号分隔的额外 anthropic-beta 头值列表，可在原生支持前提前 opt-in 某 API beta
  • ANTHROPIC_MODEL：要使用的模型设置名称（见 Model Configuration）
  • ANTHROPIC_SMALL_FAST_MODEL：[DEPRECATED] 后台任务的 Haiku 类模型名称
  • ANTHROPIC_DEFAULT_HAIKU_MODEL / SONNET / OPUS：分别设定 Haiku/Sonnet/Opus 各档默认模型
  • CLAUDE_CODE_EFFORT_LEVEL：设置受支持模型的 effort 级别（low/medium/high/xhigh/max 或 auto），优先于 /effort 与 effortLevel 设置
  • CLAUDE_CODE_MAX_OUTPUT_TOKENS：多数请求的最大输出 token 数；默认与上限随模型不同，调高会减少自动压缩前的可用上下文
  • CLAUDE_CODE_MAX_CONTEXT_TOKENS：覆盖 Claude Code 对当前模型假定的上下文窗口大小，仅当同时设置 DISABLE_COMPACT 时生效
  • CLAUDE_CODE_AUTO_COMPACT_WINDOW：用于自动压缩计算的上下文容量（token），默认取模型上下文窗口（标准 200K / 扩展 1M）
  • CLAUDE_AUTOCOMPACT_PCT_OVERRIDE：触发自动压缩的容量百分比（1-100），默认约 95%；低值如 50 提前压缩，超过默认阈值无效
  • BASH_MAX_OUTPUT_LENGTH：bash 输出超过该字符数后整段存文件，Claude 收到路径加简短预览
  • API_TIMEOUT_MS：API 请求超时（毫秒），默认 600000（10 分钟），最大 2147483647
  • BASH_DEFAULT_TIMEOUT_MS：长时 bash 命令的默认超时，默认 120000（2 分钟）
  • BASH_MAX_TIMEOUT_MS：模型可设置的 bash 命令最大超时，默认 600000（10 分钟）
  • CLAUDE_CODE_MAX_RETRIES：失败 API 请求的重试次数，默认 10
  • CLAUDE_CODE_GLOB_TIMEOUT_SECONDS：Glob 工具文件发现的超时（秒），多数平台默认 20、WSL 默认 60
  • CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS：刷新待处理 OpenTelemetry span 的超时（毫秒），默认 5000
  • CLAUDE_CODE_NO_FLICKER：设为 1 启用全屏渲染（减少闪烁、长会话内存平稳），等价于 tui 设置
  • CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN：设为 1 禁用全屏渲染、改用经典主屏渲染，优先于 CLAUDE_CODE_NO_FLICKER
  • CLAUDE_CODE_DISABLE_TERMINAL_TITLE：设为 1 禁用基于对话上下文的自动终端标题更新
  • CLAUDE_CODE_HIDE_CWD：设为 1 在启动 logo 中隐藏工作目录，适合录屏/演示
  • CLAUDE_CODE_ENABLE_TELEMETRY：设为 1 启用 OpenTelemetry 指标与日志采集，是配置 OTel 导出器的前提
  • DISABLE_TELEMETRY：禁用遥测；同时会关闭反馈调查（除非用 OTEL 反馈开关 opt back in）
  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC：等价于同时设置 DISABLE_AUTOUPDATER、DISABLE_FEEDBACK_COMMAND、DISABLE_ERROR_REPORTING、DISABLE_TELEMETRY
  • ENABLE_TOOL_SEARCH：当 ANTHROPIC_BASE_URL 指向非第一方主机且代理转发 tool_reference 块时设为 true
  • CLAUDECODE：在 Claude Code 派生的子进程（Bash/PowerShell、tmux、hook、status line、stdio MCP 子进程）中被设为 1，用于检测脚本是否运行在其子进程内

官方出处：https://code.claude.com/docs/en/env-vars