ShiBin's Wiki

Appearance

Published at:

附录 C：环境变量完整参考 ​

本附录汇总 Claude Code 支持的所有环境变量，按功能分类整理。环境变量可以在 shell 配置文件（~/.zshrc）、settings.json 的 env 字段、settings.local.json 的 env 字段、或 VSCode 扩展设置中定义。优先级详见 第 13 章：配置体系深度解析。

C.1 API 认证 ​

变量说明示例必选
ANTHROPIC_AUTH_TOKENAPI 认证令牌（推荐使用）sk-xxxxxxxxxxxxxxxx✓
ANTHROPIC_API_KEYAPI 密钥（旧称，与 AUTH_TOKEN 等效）sk-xxxxxxxxxxxxxxxx—
ANTHROPIC_BASE_URL自定义 API 端点地址https://api.deepseek.com/anthropic—

注意：ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 功能完全相同，设置其中一个即可。推荐使用 ANTHROPIC_AUTH_TOKEN（新命名规范）。如果两者同时设置，ANTHROPIC_AUTH_TOKEN 优先。

C.2 模型映射 ​

这些变量将 Claude Code 的三个模型档位（Haiku / Sonnet / Opus）映射到实际模型 ID——是使用第三方模型服务商（如 DeepSeek、OpenAI 兼容端点）的核心配置。

变量说明示例
ANTHROPIC_DEFAULT_HAIKU_MODELHaiku 档位映射的实际模型deepseek-v4-flash
ANTHROPIC_DEFAULT_SONNET_MODELSonnet 档位映射的实际模型deepseek-v4-flash[1M]
ANTHROPIC_DEFAULT_OPUS_MODELOpus 档位映射的实际模型deepseek-v4-pro[1m]
ANTHROPIC_DEFAULT_SONNET_MODEL_NAMESonnet 档位的 UI 显示名称deepseek-v4-flash
ANTHROPIC_MODEL覆盖默认模型选择（所有档位）deepseek-v4-flash

模型后缀说明：[1M]、[1m] 等后缀用于指定上下文窗口大小——DeepSeek V4 系列通过后缀来区分不同上下文容量的模型变体。DEFAULT_SONNET_MODEL_NAME 是去掉后缀的简洁名称，用于 UI 显示和日志输出。

C.3 性能与控制 ​

变量说明默认值推荐值
API_TIMEOUT_MSAPI 请求超时时间（毫秒）取决于 SDK3000000（DeepSeek 用户）
CLAUDE_CODE_MAX_OUTPUT_TOKENS单次响应的最大输出 token 数—32768
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC禁用非必要网络流量（更新检查等）01（第三方 API 用户）
CLAUDE_CODE_DISABLE_TELEMETRY禁用遥测数据上报01（隐私敏感用户）
NO_COLOR禁用 CLI 彩色输出01（CI/CD 环境）
DISABLE_AUTOUPDATER禁用自动更新检查0—

详细说明：

  • API_TIMEOUT_MS：DeepSeek 等第三方服务在使用高 Effort + 长上下文时响应可能需 10–30 分钟。设置 3000000（50 分钟）避免误中断。Anthropic 官方 API 通常不需要调整此值。
  • CLAUDE_CODE_MAX_OUTPUT_TOKENS：限制单次响应的最大长度。对于批量代码生成、长文档编写等场景，可适当调高。注意：值越大，单次响应的延迟和成本越高。
  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC：设为 1 后，Claude Code 不会发送更新检查、使用统计等非必要网络请求。使用第三方 API 端点时建议开启——这些流量对非 Anthropic 端点没有意义。
  • CLAUDE_CODE_DISABLE_TELEMETRY：设为 1 后阻止所有遥测数据上报。与 DISABLE_NONESSENTIAL_TRAFFIC 的区别：后者禁用所有非必要流量（包括更新检查），前者仅禁用遥测。
  • NO_COLOR：在日志文件记录、CI/CD 流水线、或不支持 ANSI 颜色的终端中使用。设为 1 后所有输出为纯文本。
  • DISABLE_AUTOUPDATER：阻止 Claude Code 在启动时检查新版本。在企业代理环境或锁定版本的场景中使用。

C.4 目录与路径 ​

变量说明示例
CLAUDE_CODE_WORKING_DIRECTORY强制指定工作目录（覆盖当前目录）/path/to/project
CLAUDE_CODE_PROJECT_DIR项目根目录路径/path/to/project

这两个变量在以下场景中有用：

  • 在非项目目录中启动 Claude Code 但希望它工作在指定项目下
  • 编写包装脚本时精确控制 Claude Code 的工作上下文
  • VSCode 多根工作区中指定 Claude Code 的主项目

C.5 网络与代理 ​

变量说明示例
HTTP_PROXYHTTP 代理地址http://proxy.company.com:8080
HTTPS_PROXYHTTPS 代理地址http://proxy.company.com:8080
NO_PROXY不走代理的地址列表localhost,127.0.0.1,.internal.com
NODE_EXTRA_CA_CERTS额外的 CA 证书文件路径/path/to/company-ca.pem

企业网络环境中，Claude Code（基于 Node.js）会遵循这些标准代理环境变量。如果公司使用自签名证书进行 TLS 检查，需要将公司 CA 证书路径设置到 NODE_EXTRA_CA_CERTS 中。

C.6 环境变量优先级 ​

当同一个变量在多个位置定义时，按以下优先级生效：

1. Shell 环境变量（export 方式）或 ~/.claude/.env 文件    ← 最高优先级
2. .claude/settings.local.json 的 env 字段
3. .claude/settings.json 的 env 字段
4. ~/.claude/settings.json 的 env 字段                    ← 最低优先级

⚠️ 排查技巧：很多"配置改了但不生效"的问题根因是 shell 中残留了 export 的变量。排查第一步：执行 env | grep ANTHROPIC 检查当前 shell 环境。

C.7 建议的配置方式 ​

按安全性从高到低排列：

优先级方式适用场景安全性
1.claude/settings.local.json 的 env 字段项目级密钥、本地数据库 URL★★★★★
2~/.claude/.env 文件全局密钥（所有项目共享）★★★★☆
3~/.claude/settings.json 的 env 字段全局非敏感配置★★★☆☆
4Shell 配置文件（~/.zshrc 等）开发环境统一管理★★☆☆☆
5VSCode claudeCode.environmentVSCode 扩展专属★★★★☆

核心原则：密钥不进 Git，不进 shell 全局环境。最佳实践是把所有敏感变量放在 .claude/settings.local.json 中，搭配 .gitignore 确保该文件不会被提交。

C.8 模型服务商配置片段 ​

Anthropic 官方 ​

使用 Anthropic 官方 API 是最简配置，通常只需要 API 密钥：

方法一：settings.local.json

json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-xxxxxxxxxxxxxxxx"
  }
}

方法二：Shell 环境变量

bash
export ANTHROPIC_AUTH_TOKEN="sk-ant-xxxxxxxxxxxxxxxx"

不需要设置 ANTHROPIC_BASE_URL（使用默认的 https://api.anthropic.com），也不需要设置模型映射变量（使用内置的模型 ID 映射）。

DeepSeek ​

DeepSeek 是社区中最流行的替代模型服务商，通过 Anthropic 兼容 API 提供服务。核心配置包括端点重定向和模型映射：

完整配置（settings.local.json）：

json
{
  "model": "haiku",
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的-deepseek-api-key",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-flash[1M]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "deepseek-v4-flash",
    "ANTHROPIC_MODEL": "deepseek-v4-flash",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_DISABLE_TELEMETRY": "1"
  }
}

关键说明：

  • model 设为 "haiku" → 由 ANTHROPIC_DEFAULT_HAIKU_MODEL 映射到 deepseek-v4-flash（日常使用）
  • 需要复杂推理时通过 /model 命令切换到 opus → 由 ANTHROPIC_DEFAULT_OPUS_MODEL 映射到 Pro
  • [1M] / [1m] 后缀指定 DeepSeek V4 的 1M token 上下文窗口变体
  • API_TIMEOUT_MS 设为 50 分钟以适应 DeepSeek 高 Effort 模式下的长响应
  • 禁用遥测和非必要流量——这些数据对 DeepSeek 端点没有意义
  • 建议同时设置 autoCompactTokenLimit 为 500000 以充分利用 1M 上下文：
json
{
  "autoCompactTokenLimit": 500000
}

OpenAI 兼容端点 ​

任何兼容 OpenAI Chat Completions API 的端点都可以通过适配器使用。以下以通用 OpenAI 兼容端点为示例：

json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的-api-key",
    "ANTHROPIC_BASE_URL": "https://your-openai-compatible-endpoint.com/v1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-4o-mini",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-4o",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-4o",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "GPT-4o",
    "ANTHROPIC_MODEL": "gpt-4o-mini"
  }
}

注意：OpenAI 兼容端点的支持程度取决于具体实现。并非所有功能（如 extended thinking、prompt caching）都能在第三方端点上正常工作。建议在正式使用前用简单任务验证基础功能。

多模型切换 ​

如果需要在多个模型服务商之间切换（如日常用 DeepSeek 省钱，关键任务用 Anthropic 官方保质量），有两种策略：

策略一：准备多份 local 配置，通过注释切换

json
{
  "env": {
    // ===== DeepSeek（日常使用）=====
    "ANTHROPIC_AUTH_TOKEN": "sk-你的-deepseek-api-key",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-flash[1M]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "deepseek-v4-flash",

    // ===== Anthropic 官方（需要时取消注释并注释掉上面 DeepSeek 部分）=====
    // "ANTHROPIC_AUTH_TOKEN": "sk-ant-xxxxxxxxxxxxxxxx",
    // "ANTHROPIC_BASE_URL": "",
    // "ANTHROPIC_DEFAULT_HAIKU_MODEL": "",
    // ...
  }
}

策略二：使用 cc-switch 等第三方工具

通过 cc-switch 管理多套配置 profiles，一键在模型服务商间切换，避免手动编辑 JSON 文件。

企业代理环境 ​

在需要 HTTP 代理和自定义 CA 证书的企业网络中使用 Claude Code：

json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxx",
    "HTTP_PROXY": "http://proxy.company.com:8080",
    "HTTPS_PROXY": "http://proxy.company.com:8080",
    "NO_PROXY": "localhost,127.0.0.1,.internal.company.com",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/company-ca.pem"
  }
}

或者在 shell 配置中设置：

bash
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.company.com"
export NODE_EXTRA_CA_CERTS="/etc/ssl/certs/company-ca.pem"

C.9 快速排错清单 ​

当 Claude Code 无法连接或行为异常时，按以下顺序排查环境变量：

  1. 检查 shell 环境：env | grep -iE 'anthropic|claude' — 查看是否有意外的全局覆盖
  2. 检查 API 端点可达性：
    bash
    curl -v https://api.deepseek.com/anthropic/v1/messages \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}]}'
  3. 检查模型映射：确认 ANTHROPIC_MODEL 和各 DEFAULT_*_MODEL 变量没有互相冲突
  4. 检查超时设置：如果看到超时错误，确认 API_TIMEOUT_MS 是否足够大
  5. 检查代理设置：企业网络中，确认 HTTP_PROXY / HTTPS_PROXY / NODE_EXTRA_CA_CERTS 是否正确
  6. 最小化测试：将配置精简到只有 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL 两个变量，验证基础连通性后再逐步添加其他变量

更多配置调试技巧见 第 13 章 13.7 节。

Copyright © 2017-2026 Shi Bin