控制 Claude Code 行为的环境变量完整参考。可在 shell 中设置，也可在 settings.json 的 env 键下配置以持久化或团队共享。
核心机制
环境变量优先级高于 settings.json 中的同名设置。设置在 settings.json 的 env 键下可以跨会话持久化，也可以通过 managed settings 推送给整个团队。
认证相关
| 变量 | 说明 |
|---|
ANTHROPIC_API_KEY | API key，设置后优先于订阅认证（交互模式需确认一次） |
ANTHROPIC_BASE_URL | 覆盖 API 端点，用于代理或 LLM gateway |
ANTHROPIC_MODEL | 指定默认模型 |
CLAUDE_CODE_OAUTH_TOKEN | OAuth access token，用于 SDK 和自动化环境 |
CLAUDE_CODE_OAUTH_REFRESH_TOKEN | OAuth refresh token，配合 CLAUDE_CODE_OAUTH_SCOPES 使用 |
Agent 行为控制
| 变量 | 说明 |
|---|
CLAUDE_CODE_MAX_TURNS | 限制 agentic turns 上限 |
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY | 并行工具/子 Agent 最大数量（默认 10） |
CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS | 后台子 Agent 停滞超时（默认 10 分钟） |
CLAUDE_CODE_EFFORT_LEVEL | 设置推理深度（low/medium/high/xhigh/max/auto） |
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE | 触发自动压缩的上下文占用百分比（1-100，默认约 95%） |
CLAUDE_CODE_AUTO_COMPACT_WINDOW | 自动压缩计算用的上下文窗口大小（token 数） |
CLAUDE_CODE_FORK_SUBAGENT | 设为 1 启用 forked subagents（继承完整对话上下文） |
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS | 设为 1 启用实验性 Agent Teams |
功能开关
| 变量 | 说明 |
|---|
CLAUDE_CODE_DISABLE_AUTO_MEMORY | 设为 1 禁用 auto memory |
CLAUDE_CODE_DISABLE_CLAUDE_MDS | 设为 1 禁止加载任何 CLAUDE.md |
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS | 设为 1 禁用所有后台任务功能 |
CLAUDE_CODE_DISABLE_CRON | 设为 1 禁用定时任务 |
CLAUDE_CODE_DISABLE_THINKING | 设为 1 强制禁用 extended thinking |
CLAUDE_CODE_DISABLE_FAST_MODE | 设为 1 禁用 fast mode |
CLAUDE_CODE_DISABLE_AGENT_VIEW | 设为 1 关闭后台 Agent 和 Agent 视图 |
CLAUDE_CODE_DISABLE_1M_CONTEXT | 设为 1 禁用 1M 上下文窗口支持 |
DISABLE_AUTO_COMPACT | 禁用自动压缩 |
Bash 工具行为
| 变量 | 说明 |
|---|
BASH_DEFAULT_TIMEOUT_MS | Bash 命令默认超时（默认 2 分钟） |
BASH_MAX_TIMEOUT_MS | Bash 命令最大超时（默认 10 分钟） |
BASH_MAX_OUTPUT_LENGTH | Bash 输出最大字符数（默认 30000，上限 150000） |
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR | 每次 Bash 命令后恢复到项目目录 |
CLAUDECODE | Claude Code 生成的 shell 环境中设为 1，可用于检测脚本是否在 Claude Code 内运行 |
云平台配置
| 变量 | 说明 |
|---|
CLAUDE_CODE_USE_BEDROCK | 设为 1 使用 Amazon Bedrock |
ANTHROPIC_BEDROCK_BASE_URL | 覆盖 Bedrock 端点 |
ANTHROPIC_BEDROCK_SERVICE_TIER | Bedrock 服务层级（default/flex/priority） |
CLAUDE_CODE_USE_VERTEX | 设为 1 使用 Google Vertex AI |
ANTHROPIC_VERTEX_PROJECT_ID | GCP 项目 ID |
ANTHROPIC_FOUNDRY_API_KEY | Microsoft Foundry API key |
调试与监控
| 变量 | 说明 |
|---|
CLAUDE_CODE_ENABLE_TELEMETRY | 设为 1 启用 OpenTelemetry 数据收集 |
CLAUDE_CODE_DEBUG_LOGS_DIR | 覆盖 debug 日志文件路径 |
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | 等效于同时设置 DISABLE_AUTOUPDATER、DISABLE_FEEDBACK_COMMAND、DISABLE_ERROR_REPORTING、DISABLE_TELEMETRY |
API_TIMEOUT_MS | API 请求超时（默认 10 分钟，最大约 24 天） |
CLAUDE_CODE_MAX_RETRIES | API 请求失败重试次数（默认 10） |
与其他概念的关联
实践要点
ANTHROPIC_API_KEY 存在时会覆盖订阅认证，CI 中要注意清理旧 keyCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 适合企业合规环境，一键禁用所有非必要流量CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 可提前触发压缩，避免上下文接近上限时的质量下降CLAUDECODE=1 可在 hook 脚本中检测当前是否在 Claude Code 环境内（注意：hooks 中不设置此变量）