首页 / Claude Code 入门教程 / 环境变量

← 上一篇 下一篇 →
Claude Code 入门教程

环境变量

本教程共 34 篇 · 第 16 篇 · 更新于 2026-07-26 · 约 7 分钟阅读

Claude CodeClaude Code 入门教程环境变量API Key代理env-vars

16. 环境变量

本节目标：搞懂 Claude Code 读哪些环境变量、怎么配、跟设置文件什么关系。重点掌握 API Key、代理、模型、超时、配置目录这几类，学完能搞定网络受限环境和自动化脚本场景。

环境变量和设置文件什么关系

同一个行为，往往既能用环境变量配，也能用 settings.json 配。比如选模型，既能让 ANTHROPIC_MODEL=opus，也能在设置里写 "model": "opus"。

那它俩谁说了算？环境变量优先。

打个比方：设置文件像你家长期装的门铃，环境变量像你临时贴的告示—告示贴了就按告示来，没贴才看门铃。ANTHROPIC_MODEL 会覆盖 model 设置，CLAUDE_CODE_AUTO_CONNECT_IDE 会覆盖 autoConnectIde 设置。

但也有反过来的特例：--model 标志和 /model 命令会覆盖 ANTHROPIC_MODEL，CLAUDE_CODE_EFFORT_LEVEL 会覆盖 /effort。具体每个变量的优先级，在官方 env-vars 文档的变量表里有说明。

Note

Claude Code 在启动时读环境变量，改了要下次启动才生效。

两种配置方式

方式一：在 shell 里设

临时用一次，直接在启动 claude 前设：

# macOS / Linux / WSL
export API_TIMEOUT_MS="1200000"
claude
# Windows PowerShell
$env:API_TIMEOUT_MS = "1200000"
claude
# Windows CMD
set API_TIMEOUT_MS=1200000
claude

想每次都生效，macOS/Linux 加到 ~/.bashrc 或 ~/.zshrc；PowerShell 跑 [Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "1200000", "User") 后开新终端；CMD 跑 setx API_TIMEOUT_MS "1200000" 后开新终端。

方式二：在设置文件里设

在 settings.json 的 env 键下写，Claude Code 启动时直接读，不管你怎么启动 claude 都生效：

{
  "env": {
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

放哪个文件决定影响谁：

文件影响谁
~/.claude/settings.json你自己，所有项目
.claude/settings.json这个项目的所有人（提交 git）
.claude/settings.local.json你自己，仅这个项目
Managed 设置组织里所有人（管理员部署）
Tip

shell 里设的变量会被设置文件 env 块里的同名变量覆盖—Claude Code 启动时把 env 条目写进进程环境，替换从 shell 继承的值。所以想长期固定，写设置文件更稳；想临时覆盖一次，用 shell。

认证类：API Key 和令牌

最常用的一组，决定 Claude Code 拿什么凭证去请求。

变量作用
ANTHROPIC_API_KEYAPI 密钥，作为 X-Api-Key 头发送。设了就用它，替代你的订阅登录
ANTHROPIC_AUTH_TOKEN自定义 Authorization 头的值（自动加 Bearer 前缀）
ANTHROPIC_BASE_URL覆盖 API 端点，走代理或网关时用

ANTHROPIC_API_KEY 有个细节要注意：设了它，即使你已经登录订阅，也会用这个密钥。非交互模式（-p）下有了就用；交互模式下会先问你一次是否用密钥覆盖订阅。想换回订阅，跑 unset ANTHROPIC_API_KEY。

代理和网络

国内用户最关心的一块。Claude Code 需要连通 claude.ai 和 Anthropic API 端点，网络不通时得走代理。

HTTP/HTTPS 代理

最直接的方式，设标准的代理环境变量：

export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
claude

这俩是通用的网络代理变量，Claude Code 的网络请求会走你指定的代理服务器。

自定义 API 端点

如果你用的是 API 中转服务（社区/第三方方案，非官方推荐），用 ANTHROPIC_BASE_URL 把请求转到别的端点：

export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
claude
Warning

ANTHROPIC_BASE_URL 改的是请求发到哪儿，不是哪个模型回答。指向非官方主机时，MCP 工具搜索默认会关掉，Remote Control 也会被禁用。涉及第三方模型或 API 中转，属社区/第三方方案，非官方推荐，配置时注意甄别。

超时类：别让命令卡死

跑长任务时，超时配置能避免卡死。

变量作用默认值
API_TIMEOUT_MSAPI 请求超时（毫秒）600000（10 分钟）
BASH_DEFAULT_TIMEOUT_MSbash 命令默认超时120000（2 分钟）
BASH_MAX_TIMEOUT_MS模型能给 bash 设的最大超时600000（10 分钟）
API_FORCE_IDLE_TIMEOUT流式响应空闲超时（无字节到达时中止）5 分钟

网络慢或走代理时，把 API_TIMEOUT_MS 调大点：

{
  "env": {
    "API_TIMEOUT_MS": "1200000"
  }
}

这表示 20 分钟。最大值 2147483647，超过会溢出导致请求立即失败。

Tip

如果你跑的命令本身就很慢（比如全套测试、大构建），把 BASH_DEFAULT_TIMEOUT_MS 也调大，不然 2 分钟到了 Claude 会以为命令卡了。

模型和推理类

跟模型选择、思考强度相关的几个：

变量作用
ANTHROPIC_MODEL用哪个模型（别名或名称）
CLAUDE_CODE_EFFORT_LEVEL推理强度：low/medium/high/xhigh/max/auto
MAX_THINKING_TOKENS思考 token 预算，设 0 关掉思考（Fable 5 除外）
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING设 1 关掉自适应推理（仅 Opus 4.6/Sonnet 4.6 有效，新一代模型不行）
CLAUDE_CODE_SUBAGENT_MODEL子代理用什么模型

CLAUDE_CODE_EFFORT_LEVEL 优先级最高，压过 /effort 命令和 effortLevel 设置。MAX_THINKING_TOKENS=0 能在 Anthropic API 上彻底关掉思考省钱（Fable 5 关不掉）。

模型相关的细节看第 15 章。

配置目录和会话

变量作用
CLAUDE_CONFIG_DIR覆盖配置目录（默认 ~/.claude），所有设置、凭证、会话历史、插件都存这下面
CLAUDE_CODE_SKIP_PROMPT_HISTORY设 1 不写会话记录到磁盘，这样的会话不会出现在 --resume/--continue 里
DISABLE_AUTO_COMPACT设 1 关掉上下文快满时的自动压缩（手动 /compact 还能用）

CLAUDE_CONFIG_DIR 挺有用—想在同一台机器上跑两套账号/配置，给它们各配一个目录：

alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'
alias claude-personal='CLAUDE_CONFIG_DIR=~/.claude-personal claude'

这样工作配置和个人配置完全隔离。

功能开关类

一组 DISABLE_* / ENABLE_* 变量，用来开关功能：

变量作用
DISABLE_AUTOUPDATER设 1 关自动更新（手动 claude update 还能用）
DISABLE_AUTO_COMPACT设 1 关自动压缩
CLAUDE_CODE_DISABLE_AUTO_MEMORY设 1 关自动内存
CLAUDE_CODE_ENABLE_TELEMETRY设 1 开 OpenTelemetry 数据收集
CLAUDE_CODE_NO_FLICKER设 1 开全屏渲染，减少闪烁
CLAUDE_CODE_AUTO_CONNECT_IDEfalse 关 IDE 自动连接，true 强制连
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB设 1 从子进程里删掉 API 凭证，防注入窃密

最后那个 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 值得留意—开了之后，Bash 工具、钩子、MCP 子进程都拿不到你的 API Key，能降低提示注入攻击偷密钥的风险。

一个实际配置示例

把上面几类攒一起，一个国内开发者常见的配置长这样：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com",
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "CLAUDE_CODE_EFFORT_LEVEL": "high",
    "CLAUDE_CODE_SUBPROCESS_ENV_SCRUB": "1"
  }
}

含义：走自定义网关、超时放宽到 20 分钟、bash 命令超时 5 分钟、推理强度 high、子进程不暴露凭证。

小结

  • 优先级：环境变量 > 设置字段（少数例外如 --model 覆盖 ANTHROPIC_MODEL）
  • 两种配法：shell 里临时设、settings.json 的 env 块里长期设（后者覆盖前者）
  • 认证：ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL
  • 代理：HTTPS_PROXY/HTTP_PROXY 走代理，ANTHROPIC_BASE_URL 换端点
  • 超时：API_TIMEOUT_MS、BASH_DEFAULT_TIMEOUT_MS 按需调大
  • 隔离：CLAUDE_CONFIG_DIR 给不同账号/场景配不同目录
  • 安全：CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 防子进程泄密

完整的变量列表在官方 env-vars 文档，我这儿挑的是最常用的。下一章讲权限和模式—Claude Code 能干什么、不能干什么，怎么管。

上一篇
模型配置
下一篇
权限与模式