环境变量：运行时行为的底层调谐

从定义开始

在 Claude Code 中，环境变量是控制程序行为、调试模式、API 提供商以及实验性功能的“底层电位器”。相比于用户配置文件（settings.json），环境变量拥有更高的优先级，常用于 CI/CD 环境、企业策略锁定、或开发者对模型能力的强制性干预。

环境变量的定义并没有一个单一的清单，而是散落在系统的各个角落。Claude Code 在运行时会频繁通过 isEnvTruthy（一个处理 "true", "1", "yes" 等真值的工具函数）来动态决定代码执行路径。

实现细节

主要的变量集中在身份认证、资源限制和环境适配三个领域：

认证与服务配置：
- ANTHROPIC_API_KEY：最核心的变量。在 src/utils/auth.ts 中，系统会检查此变量，并赋予其比配置文件中密钥更高的优先级。
- CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX：布尔值开关。控制 src/utils/model/providers.ts 决定走哪种云服务。
- ANTHROPIC_BASE_URL：覆盖默认的 API 端点。
运行时行为与实验性功能：
- USER_TYPE：如果设置为 ant，会开启大量 Anthropic 内部调试工具和尚未公开的 Beta 特性。很多 UI 组件（如 src/ink/components/App.tsx）都会根据此变量决定是否显示某些状态。
- DISABLE_PROMPT_CACHING：在 src/services/api/claude.ts 中通过此变量强制关闭 Prompt 缓存（Prompt Caching），以排查上下文管理问题。
- CLAUDE_CODE_MAX_CONTEXT_TOKENS：在 src/utils/context.ts 中作为硬性上限（Override），手动约束模型一次性能“吃掉”多少 Token。
- CLAUDE_CODE_SIMPLE：开启“极简模式”。此变量会影响 src/utils/envUtils.ts 中的 UI 逻辑，移除复杂的交互，适合在管道（Pipeline）中使用。
调试与日志：
- DEBUG / DEBUG_SDK：常规的调试日志开关。
- CLAUDE_CODE_DEBUG_LOG_LEVEL：精细控制日志级别（INFO, WARN, ERROR, DEBUG）。
- CLAUDE_CODE_DIAGNOSTICS_FILE：指定诊断日志（Diagnostics）的输出文件路径。

踩坑指南

优先级法则：在代码实现中（如 src/utils/model/model.ts），逻辑通常是 process.env.VARIABLE || settings.value。这意味着环境变量具有“强制覆盖权”。
Ant-Only 陷阱：源码中存在大量 process.env.USER_TYPE === 'ant' 的判断。如果你试图复现某些高级功能（如 AutoDream、MagicDocs 的部分逻辑）但发现未生效，很可能是因为系统判定你不是“内部用户”。
路径控制：CLAUDE_CONFIG_DIR 决定了 .claude 文件夹的根位置，这会影响到所有 Settings、History、Memory 的存储路径。

源码锚点

claude-code-opensource/src/utils/envUtils.ts: 核心环境变量解析工具。

📄 src/utils/envUtils.ts — 核心环境变量解析工具。L7-12 of 184

typescript

export const getClaudeConfigHomeDir = memoize(
  (): string => {
    return (
      process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude')
    ).normalize('NFC')
  },

claude-code-opensource/src/utils/auth.ts: 处理 API Key 的加载与覆盖。

📄 src/utils/auth.ts — 处理 API Key 的加载与覆盖。L80-96 of 2003

typescript

/** Default TTL for API key helper cache in milliseconds (5 minutes) */
const DEFAULT_API_KEY_HELPER_TTL = 5 * 60 * 1000

/**
 * CCR and Claude Desktop spawn the CLI with OAuth and should never fall back
 * to the user's ~/.claude/settings.json API-key config (apiKeyHelper,
 * env.ANTHROPIC_API_KEY, env.ANTHROPIC_AUTH_TOKEN). Those settings exist for
 * the user's terminal CLI, not managed sessions. Without this guard, a user
 * who runs `claude` in their terminal with an API key sees every CCD session
 * also use that key — and fail if it's stale/wrong-org.
 */
function isManagedOAuthContext(): boolean {
  return (
    isEnvTruthy(process.env.CLAUDE_CODE_REMOTE) ||
    process.env.CLAUDE_CODE_ENTRYPOINT === 'claude-desktop'
  )
}

claude-code-opensource/src/utils/context.ts: 环境变量对上下文窗口的限制。

📄 src/utils/context.ts — 环境变量对上下文窗口的限制。L9-33 of 222

typescript

export const MODEL_CONTEXT_WINDOW_DEFAULT = 200_000

// Maximum output tokens for compact operations
export const COMPACT_MAX_OUTPUT_TOKENS = 20_000

// Default max output tokens
const MAX_OUTPUT_TOKENS_DEFAULT = 32_000
const MAX_OUTPUT_TOKENS_UPPER_LIMIT = 64_000

// Capped default for slot-reservation optimization. BQ p99 output = 4,911
// tokens, so 32k/64k defaults over-reserve 8-16× slot capacity. With the cap
// enabled, <1% of requests hit the limit; those get one clean retry at 64k
// (see query.ts max_output_tokens_escalate). Cap is applied in
// claude.ts:getMaxOutputTokensForModel to avoid the growthbook→betas→context
// import cycle.
export const CAPPED_DEFAULT_MAX_TOKENS = 8_000
export const ESCALATED_MAX_TOKENS = 64_000

/**
 * Check if 1M context is disabled via environment variable.
 * Used by C4E admins to disable 1M context for HIPAA compliance.
 */
export function is1mContextDisabled(): boolean {
  return isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_1M_CONTEXT)
}

环境变量：运行时行为的底层调谐 ​

从定义开始 ​

实现细节 ​

踩坑指南 ​

相关主题 ​

源码锚点 ​

环境变量：运行时行为的底层调谐

从定义开始

实现细节

踩坑指南

相关主题

源码锚点