Claude Code 环境变量

环境变量是控制 Claude Code 行为的重要方式，无需编辑配置文件即可灵活调整各项设置。本章详细介绍 Claude Code 支持的所有环境变量、它们的用途、配置方式以及常见使用场景。

环境变量概述

Claude Code 使用环境变量来控制行为，这些变量可以通过以下方式设置：

  • 直接在 shell 中 export
  • 在 ~/.claude/settings.json 的 env 字段中配置
  • 在项目级 .claude/settings.json 中配置
  • 通过 IDE 插件的设置界面配置

环境变量优先级从高到低：命令行 > 项目级 settings.json > 用户级 settings.json > shell 环境变量。在 settings.json 中配置的变量会自动传递给 Claude 进程。

认证相关变量

变量名 说明 值
ANTHROPIC_API_KEY Claude API 密钥（从 claude.ai 获取） API 密钥字符串
ANTHROPIC_BASE_URL API 请求的目标地址（用于代理或自定义端点） URL 地址
ANTHROPIC_AUTH_TOKEN 认证令牌（用于 VS Code 插件等场景） 令牌字符串

配置示例

实例

# 在 shell 中设置
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"

实例

// 在 settings.json 中配置
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxx",
    "ANTHROPIC_BASE_URL": "https://custom-proxy.com/v1"
  }
}

模型配置变量

变量名 说明 值
ANTHROPIC_MODEL 默认使用的模型 claude-opus-4-5、claude-sonnet-4-5、claude-haiku-3-5 等
ANTHROPIC_SMALL_FAST_MODEL 快速响应模式使用的模型（用于简单任务） 模型名称
CLAUDE_CODE_SUBAGENT_MODEL 统一设置所有子代理使用的模型 模型名称
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 使用 Bedrock 或 Vertex 的 Anthropic Messages 格式时禁用实验性功能 1

使用场景

子代理默认继承主对话的模型。通过 CLAUDE_CODE_SUBAGENT_MODEL 可以统一设置，将简单任务交给 Haiku，将复杂分析交给 Sonnet，从而优化成本：

实例

# 主对话用 Opus 做复杂推理，子代理统一用 Sonnet
export ANTHROPIC_MODEL="claude-opus-4-5"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5"

工具与命令变量

变量名 说明 值
CLAUDE_CODE_DISABLE_SLASH_COMMANDS 禁用所有斜杠命令 1
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS 禁用内置的 Git 相关系统提示词（优先级高于 settings.json 中的 includeGitInstructions） 1
CLAUDE_CODE_USE_POWERSHELL_TOOL 在 Windows 上启用 PowerShell 工具（需要配合 defaultShell: "powershell" 设置） 1
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL 跳过自动安装 IDE 扩展（替代 autoInstallIdeExtension 设置） 1
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 禁用后台任务功能 1

权限与安全变量

变量名 说明 值
CLAUDE_CODE_PERMISSION_MODE 设置默认权限模式（详见子代理章节） default、acceptEdits、dontAsk、bypassPermissions、plan
CLAUDE_CODE_ALLOWED_TOOLS 允许 Claude 使用的工具白名单（逗号分隔） 工具列表
CLAUDE_CODE_DISALLOWED_TOOLS 禁止 Claude 使用的工具黑名单 工具列表

权限模式详解

  • default：正常权限提示，每次操作前询问
  • acceptEdits：自动接受文件编辑，无需确认
  • dontAsk：自动拒绝未授权操作，不中断执行
  • bypassPermissions：跳过所有权限检查（仅限完全可信环境）
  • plan：只读规划模式，不执行写操作

实例

# 在 CI 环境中使用只读模式
export CLAUDE_CODE_PERMISSION_MODE="plan"
export CLAUDE_CODE_ALLOWED_TOOLS="Read,Grep,Glob,Bash(gh *)"

日志与调试变量

变量名 说明 值
CLAUDE_CODE_DEBUG 启用调试输出 1
CLAUDE_CODE_ENABLE_TELEMETRY 启用遥测数据收集 1
OTEL_METRICS_EXPORTER OpenTelemetry 指标导出器 otlp 等

会话与历史变量

变量名 说明 值
CLAUDE_CODE_DISABLE_HISTORY 禁用对话历史保存 1
CLAUDE_CODE_SESSION_TIMEOUT 会话超时时间（秒） 数字
CLAUDE_CODE_MAX_SESSIONS 最大保存的会话数量 数字

MCP 相关变量

当 Claude Code 执行 MCP 工具时，会设置以下环境变量：

变量名 说明 值
CLAUDE_CODE_MCP_SERVER_NAME MCP 服务器名称 字符串
CLAUDE_CODE_MCP_TOOL_NAME 正在调用的 MCP 工具名称 字符串
CLAUDE_CODE_MCP_TOOL_ARGS 传递给 MCP 工具的参数 JSON 字符串

工作流相关变量

变量名 说明 值
CLAUDE_CODE_WORKTREE_CLEANUP_PERIOD_DAYS 孤立 worktree 的自动清理周期 天数
CLAUDE_CODE_DISABLE_WORKTREE_AUTO_CLEANUP 禁用 worktree 自动清理 1

GitHub Actions 专用变量

变量名 说明 值
ANTHROPIC_VERTEX_PROJECT_ID Vertex AI 项目 ID（使用 Vertex 时由认证步骤设置） GCP 项目 ID
CLOUD_ML_REGION Vertex AI 区域 区域代码（如 us-east5）

settings.json 配置方式

所有环境变量都可以在 settings.json 中配置，这种方式更加声明式和可移植：

实例

{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-5",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-3-5",
    "CLAUDE_CODE_PERMISSION_MODE": "plan",
    "CLAUDE_CODE_ALLOWED_TOOLS": "Read,Grep,Glob,Bash",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

VS Code 插件配置

在 VS Code 中使用 Claude Code 插件时，可以通过 environmentVariables 设置：

实例

{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": "https://custom-proxy.com/api"
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": "your-token-here"
    },
    {
      "name": "ANTHROPIC_MODEL",
      "value": "claude-sonnet-4-5"
    }
  ]
}

常见使用场景

场景一：使用代理或自定义 API 端点

实例

# 通过企业内部代理访问 Claude API
export ANTHROPIC_BASE_URL="https://proxy.company.com/anthropic/v1"
export ANTHROPIC_API_KEY="your-api-key"

场景二：优化成本配置

实例

# 主对话用 Sonnet，子代理统一用 Haiku
export ANTHROPIC_MODEL="claude-sonnet-4-5"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-haiku-3-5"

场景三：CI/CD 环境安全配置

实例

# CI 环境中使用只读模式
export CLAUDE_CODE_PERMISSION_MODE="plan"
export CLAUDE_CODE_DISABLE_HISTORY="1"
export CLAUDE_CODE_ALLOWED_TOOLS="Read,Grep,Glob,Bash(gh *)"

场景四：Windows PowerShell 环境

实例

# Windows 上启用 PowerShell
$env:CLAUDE_CODE_USE_POWERSHELL_TOOL = "1"
# 在 settings.json 中设置 defaultShell

优先级与覆盖

环境变量的优先级（从高到低）：

  1. 命令行 export 设置
  2. 项目级 .claude/settings.json
  3. 用户级 ~/.claude/settings.json
  4. Claude Code 默认值

在 settings.json 中配置的变量会覆盖同名的 shell 环境变量。这是因为 settings.json 在 Claude Code 进程启动时被显式读取，优先级更高。

查看当前配置

使用 /config 命令可以查看当前的完整配置：

/config

这会显示所有当前生效的设置，包括环境变量和 settings.json 中的配置。

最佳实践

1、敏感信息处理

  • API 密钥等敏感信息不要硬编码在 settings.json 中
  • 使用环境变量或 shell 配置文件（~/.bashrc、~/.zshrc）
  • 确保包含敏感信息的文件不在 git 版本控制中

2、按环境配置

  • 本地开发：使用更宽松的权限模式
  • CI/CD：使用只读模式 plan
  • 生产调试：启用 CLAUDE_CODE_DEBUG

3、集中管理

  • 通用配置放在 ~/.claude/settings.json
  • 项目特有配置放在项目目录的 .claude/settings.json
  • 敏感配置通过 shell 环境变量或 CI Secrets 提供

常见问题

Q：环境变量和 settings.json 哪个优先？

在 settings.json 中配置的变量优先级更高，会覆盖同名的 shell 环境变量。

Q：如何让 Claude Code 使用不同的 API 端点？

设置 ANTHROPIC_BASE_URL 环境变量指向你的代理或自定义端点。

Q：子代理如何控制使用的模型？

可以通过 CLAUDE_CODE_SUBAGENT_MODEL 统一设置所有子代理的模型，也可以在每个子代理的 frontmatter 中单独指定。

Q：在 Windows 上如何启用 PowerShell？

设置环境变量 CLAUDE_CODE_USE_POWERSHELL_TOOL=1，同时在 settings.json 中设置 defaultShell: "powershell"。

Q：如何禁用所有斜杠命令？

设置 CLAUDE_CODE_DISABLE_SLASH_COMMANDS=1 环境变量。