Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

附录 B：环境变量参考

本附录列出 Claude Code v2.1.88 中用户可配置的关键环境变量。按功能域分组，仅列出影响用户可见行为的变量，省略内部遥测和平台检测类变量。

上下文压缩

变量效果默认值
CLAUDE_CODE_AUTO_COMPACT_WINDOW覆盖上下文窗口大小（token）模型默认值
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE以百分比覆盖自动压缩阈值（0-100）计算值
DISABLE_AUTO_COMPACT完全禁用自动压缩false

Effort 与推理

变量效果有效值
CLAUDE_CODE_EFFORT_LEVEL覆盖 effort 级别low、medium、high、max、auto、unset
CLAUDE_CODE_DISABLE_FAST_MODE禁用 Fast Mode 加速输出true/false
DISABLE_INTERLEAVED_THINKING禁用扩展思考true/false
MAX_THINKING_TOKENS覆盖思考 token 上限模型默认值

工具与输出限制

变量效果默认值
BASH_MAX_OUTPUT_LENGTHBash 命令最大输出字符数8,000
CLAUDE_CODE_GLOB_TIMEOUT_SECONDSGlob 搜索超时（秒）默认值

权限与安全

变量效果注意
CLAUDE_CODE_DUMP_AUTO_MODE导出 YOLO 分类器请求/响应仅调试用
CLAUDE_CODE_DISABLE_COMMAND_INJECTION_CHECK禁用 Bash 命令注入检测降低安全性

API 与认证

变量效果安全等级
ANTHROPIC_API_KEYAnthropic API 认证密钥凭证
ANTHROPIC_BASE_URL自定义 API 端点（代理支持）可重定向
ANTHROPIC_MODEL覆盖默认模型安全
CLAUDE_CODE_USE_BEDROCK通过 AWS Bedrock 路由推理安全
CLAUDE_CODE_USE_VERTEX通过 Google Vertex AI 路由推理安全
CLAUDE_CODE_EXTRA_BODY向 API 请求追加额外字段高级用途
ANTHROPIC_CUSTOM_HEADERS自定义 HTTP 请求头安全

模型选择

变量效果示例
ANTHROPIC_DEFAULT_HAIKU_MODEL自定义 Haiku 模型 ID模型字符串
ANTHROPIC_DEFAULT_SONNET_MODEL自定义 Sonnet 模型 ID模型字符串
ANTHROPIC_DEFAULT_OPUS_MODEL自定义 Opus 模型 ID模型字符串
ANTHROPIC_SMALL_FAST_MODEL快速推理模型（如用于摘要）模型字符串
CLAUDE_CODE_SUBAGENT_MODEL子 Agent 使用的模型模型字符串

提示词缓存

变量效果默认值
CLAUDE_CODE_ENABLE_PROMPT_CACHING启用提示词缓存true
DISABLE_PROMPT_CACHING完全禁用提示词缓存false

会话与调试

变量效果用途
CLAUDE_CODE_DEBUG_LOG_LEVEL日志详细程度silent/error/warn/info/verbose
CLAUDE_CODE_PROFILE_STARTUP启用启动性能剖析调试
CLAUDE_CODE_PROFILE_QUERY启用查询管线剖析调试
CLAUDE_CODE_JSONL_TRANSCRIPT将会话记录写为 JSONL文件路径
CLAUDE_CODE_TMPDIR覆盖临时目录路径

输出与格式

变量效果默认值
CLAUDE_CODE_SIMPLE最小系统提示词模式false
CLAUDE_CODE_DISABLE_TERMINAL_TITLE禁用设置终端标题false
CLAUDE_CODE_NO_FLICKER减少全屏模式闪烁false

MCP（Model Context Protocol）

变量效果默认值
MCP_TIMEOUTMCP 服务器连接超时（ms）10,000
MCP_TOOL_TIMEOUTMCP 工具调用超时（ms）30,000
MAX_MCP_OUTPUT_TOKENSMCP 工具输出 token 上限默认值

网络与代理

变量效果注意
HTTP_PROXY / HTTPS_PROXYHTTP/HTTPS 代理可重定向
NO_PROXY绕过代理的主机列表安全
NODE_EXTRA_CA_CERTS额外 CA 证书影响 TLS 信任

路径与配置

变量效果默认值
CLAUDE_CONFIG_DIR覆盖 Claude 配置目录~/.claude

版本演化：v2.1.91 新增变量

变量效果说明
CLAUDE_CODE_AGENT_COST_STEER子代理成本引导控制多代理场景下的资源消耗
CLAUDE_CODE_RESUME_THRESHOLD_MINUTES会话恢复时间阈值控制会话恢复的时间窗口
CLAUDE_CODE_RESUME_TOKEN_THRESHOLD会话恢复 Token 阈值控制会话恢复的 Token 预算
CLAUDE_CODE_USE_ANTHROPIC_AWSAWS 认证路径启用 Anthropic AWS 基础设施认证
CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH跳过 AWS 认证AWS 不可用时的回退路径
CLAUDE_CODE_DISABLE_CLAUDE_API_SKILL禁用 Claude API 技能企业合规场景控制
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE插件市场容错市场获取失败时保留缓存版本
CLAUDE_CODE_REMOTE_SETTINGS_PATH远程设置路径覆盖企业部署自定义设置 URL

v2.1.91 移除的变量

变量原效果移除原因
CLAUDE_CODE_DISABLE_COMMAND_INJECTION_CHECK禁用命令注入检查Tree-sitter 基础设施整体移除
CLAUDE_CODE_DISABLE_MOUSE_CLICKS禁用鼠标点击功能废弃
CLAUDE_CODE_MCP_INSTR_DELTAMCP 指令增量功能重构

配置优先级体系

环境变量只是 Claude Code 配置系统的一个切面。完整的配置体系由 6 层来源构成，按优先级从低到高合并（merge）——后者覆盖前者。理解这个优先级链对诊断"为什么我的设置没有生效"至关重要。

六层优先级模型

配置来源定义在 restored-src/src/utils/settings/constants.ts:7-22，合并逻辑实现在 restored-src/src/utils/settings/settings.ts:644-796 的 loadSettingsFromDisk() 函数中：

优先级来源标识文件路径 / 来源说明
0 (最低)pluginSettings插件提供的基础设置只包含白名单字段（如 agent），作为所有文件来源的底层
1userSettings~/.claude/settings.json用户全局设置，跨所有项目生效
2projectSettings$PROJECT/.claude/settings.json项目共享设置，提交到版本控制
3localSettings$PROJECT/.claude/settings.local.json项目本地设置，自动加入 .gitignore
4flagSettings--settings CLI 参数 + SDK 内联设置命令行或 SDK 传入的临时覆盖
5 (最高)policySettings企业托管策略（多来源竞争）企业管理员强制策略，见下文

合并语义

合并使用 lodash 的 mergeWith 进行深度合并（deep merge），自定义合并器定义在 restored-src/src/utils/settings/settings.ts:538-547：

  • 对象：递归合并，后来源的字段覆盖前来源
  • 数组：合并并去重（mergeArrays），而非替换——这意味着多层来源的 permissions.allow 规则会累加
  • undefined 值：在 updateSettingsForSource 中被解释为"删除该键"（restored-src/src/utils/settings/settings.ts:482-486）

这个数组合并语义特别重要：如果用户在 userSettings 中允许了一个工具，又在 projectSettings 中允许了另一个工具，最终的 permissions.allow 列表包含两者。这使得多层权限配置可以叠加而非互相覆盖。

策略设置（policySettings）的四层竞争

策略设置（policySettings）本身有一个内部优先级链，采用"第一个有内容的来源胜出"（first source wins）策略，实现在 restored-src/src/utils/settings/settings.ts:322-345：

子优先级来源说明
1 (最高)远程托管设置（Remote Managed Settings）从 API 同步的企业策略缓存
2MDM 原生策略（HKLM / macOS plist）通过 plutil 或 reg query 读取的系统级策略
3文件策略（managed-settings.json + managed-settings.d/*.json）Drop-in 目录支持，按字母序合并
4 (最低)HKCU 用户策略（仅 Windows）用户级注册表设置

注意策略设置与其他来源的合并行为不同：策略内部的四个子来源是竞争关系（第一个胜出），而策略整体与其他来源是叠加关系（深度合并到配置链顶部）。

覆盖链流程图

flowchart TD
    P["pluginSettings<br/>插件基础设置"] -->|mergeWith| U["userSettings<br/>~/.claude/settings.json"]
    U -->|mergeWith| Proj["projectSettings<br/>.claude/settings.json"]
    Proj -->|mergeWith| L["localSettings<br/>.claude/settings.local.json"]
    L -->|mergeWith| F["flagSettings<br/>--settings CLI / SDK 内联"]
    F -->|mergeWith| Pol["policySettings<br/>企业托管策略"]
    Pol --> Final["最终生效配置<br/>getInitialSettings()"]

    subgraph PolicyInternal["policySettings 内部竞争（第一个胜出）"]
        direction TB
        R["远程托管<br/>Remote API"] -.->|空?| MDM["MDM 原生<br/>plist / HKLM"]
        MDM -.->|空?| MF["文件策略<br/>managed-settings.json"]
        MF -.->|空?| HK["HKCU<br/>Windows 用户级"]
    end

    Pol --- PolicyInternal

    style Final fill:#e8f4f8,stroke:#2196F3,stroke-width:2px
    style PolicyInternal fill:#fff3e0,stroke:#FF9800

图 B-1：配置优先级覆盖链

缓存与失效

配置加载有两层缓存机制（restored-src/src/utils/settings/settingsCache.ts）：

  1. 文件级缓存：parseSettingsFile() 缓存每个文件的解析结果，避免重复 JSON 解析
  2. 会话级缓存：getSettingsWithErrors() 缓存合并后的最终结果，整个会话复用

缓存通过 resetSettingsCache() 统一失效——当用户通过 /config 命令或 updateSettingsForSource() 修改设置时触发。设置文件变更检测由 restored-src/src/utils/settings/changeDetector.ts 负责，通过文件系统监听（watch）驱动 React 组件的重新渲染。

诊断建议

当某个设置"不生效"时，按以下顺序排查：

  1. 确认来源：用 /config 命令查看当前生效的配置和来源标注
  2. 检查优先级：高优先级来源是否覆盖了你的设置？policySettings 是最强的覆盖者
  3. 检查数组合并：权限规则是累加的——如果 deny 规则出现在高优先级来源中，低优先级的 allow 无法覆盖
  4. 检查缓存：在同一会话中修改 .json 文件后，配置可能仍在缓存中——重启会话或使用 /config 触发刷新