环境变量三件套配置首跑

首页 › tutorials › 环境变量三件套配置首跑

概述

本教程面向零基础用户，带你用一个全新的视角完成 Claude Code 的"配置"环节——环境变量三件套（API Key、Base URL、模型路由）。学完后你将掌握：原生安装与版本验证、用环境变量完成认证与模型路由、把配置持久化到 settings.json 的三层体系、并跑通一个真实的首个项目。本文刻意避开已被反复讲过的"装好即用"流程，专注那些决定后续每一次会话成本、速度与稳定性的底层配置逻辑。适用人群：刚拿到 Claude Code、想要一次配到位而非反复踩坑的开发者、运维和科研人员。

前置条件

一台可联网的 macOS / Linux / WSL2 机器，终端可用
Node.js ≥ 18（Claude Code 运行基座），可用 node -v 确认；没有则用官方安装包或 nvm install --lts
一个可用的 Anthropic API Key（或兼容网关的 Token）
基础命令行操作能力（会 cd、ls、编辑文本即可）

第一步：原生安装与版本核验

Claude Code 的官方分发渠道是 npm 包 @anthropic-ai/claude-code。在终端执行：

# 全局安装（原生方式，最干净）
npm install -g @anthropic-ai/claude-code

# 核验安装结果
claude --version
claude doctor     # 自检：Node 版本、网络、认证、配置文件路径

预期结果：claude --version 打印出版本号；claude doctor 输出一张健康检查表，标绿表示 OK，标红处会给出修复建议（如 Node 版本过低、认证缺失）。

常见问题与解决方案：

现象	原因	解决
`command not found: claude`	npm 全局 `bin` 不在 `PATH`	执行 `npm config get prefix`，把 `<prefix>/bin` 加进 `~/.zshrc` 或 `~/.bashrc`
`EACCES` 权限错误	系统目录写入被拒	改用 `nvm` 管理 Node，或 `npm config set prefix ~/.npm-global` 后重装
公司网络拉包超时	走内网代理	`npm config set proxy` / `set https-proxy` 后重试

配置核心理念：从这一步起，所有"配什么、配在哪"的决策都遵循 "更具体的作用域覆盖更通用的作用域" 这一条铁律。记住它，后面三层配置就不会乱。

第二步：环境变量三件套——认证与路由

这是本教程的核心。Claude Code 的"三件套"指三个最关键的环境变量，它们决定了用什么身份、连哪个服务器、跑哪个模型：

ANTHROPIC_API_KEY —— 认证身份。官方 API 直接用 Anthropic 下发的 Key。
ANTHROPIC_BASE_URL —— 请求路由。指向官方 https://api.anthropic.com，或自建/第三方兼容网关地址。
ANTHROPIC_MODEL —— 主模型路由。决定这一会话默认用 Opus、Sonnet 还是 Haiku。

最小可用配置（临时测试，写进当前终端会话）：

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"
export ANTHROPIC_MODEL="claude-sonnet-4-6"
claude

进入交互界面后，输入"你好，确认你当前使用的模型"，Claude 会回报模型名——这便是路由生效的最快验证。

认证方式选择：当你使用官方 API 时用 ANTHROPIC_API_KEY；若走需要 Bearer 头的自建网关，改用 ANTHROPIC_AUTH_TOKEN（它会以 Authorization: Bearer <token> 形式发送，往往与 ANTHROPIC_BASE_URL 成对出现）。

⚠️ 安全红线：永远在 Shell 层级（环境变量 / settings.json 的 env 块 / 系统密钥库）管理 Key，绝不要把它写进会被提交到版本库的项目文件，更不要粘贴到来源不明的第三方配置模板里。

第三步：模型路由深度配置

"三件套"之外，还有一组与模型成本/速度强相关的变量，建议在首次配置时一并了解：

# 主模型（决定主力推理质量）
export ANTHROPIC_MODEL="claude-sonnet-4-6"

# 后台小模型（文件标题生成、会话摘要等轻任务，默认走 Haiku，省钱提速）
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5"

# 别名级覆盖（当你用 /model opus 切换时，实际映射到哪个具体版本）
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-8"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"

模型别名机制：Claude Code 在 model 设置里接受三种写法——别名（opus / sonnet / haiku / opusplan）、短名、或 Anthropic API 的完整模型名。交互中用 /model sonnet 即可热切换，无需重启。

成本控制技巧：把 ANTHROPIC_SMALL_FAST_MODEL 固定为 Haiku，可让 90% 的后台杂活走低价通道；只在需要深度推理时 /model opus 临时升级。

第四步：把"三件套"持久化进三层配置

环境变量直接 export 只对当前终端有效。要让配置长期生效，并纳入团队协作，需写入 settings.json 的三层体系：

作用域	路径	用途	是否提交 Git
用户级（全局）	`~/.claude/settings.json`	对你所有项目生效的默认值	不提交（在 home）
项目级（共享）	`<项目>/.claude/settings.json`	团队共享的路由/权限约定	✅ 提交
项目级（本地）	`<项目>/.claude/settings.local.json`	个人覆盖、私有 Key 路径	❌ 加入 `.gitignore`

优先级：项目本地 > 项目共享 > 用户级（越具体越优先）。

推荐做法——把模型路由放"用户级"作默认，把 API 网关地址放"项目本地"隔离敏感信息：

// ~/.claude/settings.json（用户级默认）
{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5"
  },
  "model": "sonnet"
}

// <项目>/.claude/settings.local.json（本地隔离，绝不提交）
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxxxxx",
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com"
  }
}

也可运行 claude 后用 /config 打开可视化设置界面，用 /permissions 查看权限层，所见即所得。

第五步：首个真实项目实战——配置驱动的 Bug 修复

下面用一个完整闭环验证你的"三件套"是否真正生效。目标是让 Claude 在低成本模型下完成一个真实调试任务。

# 1. 准备一个最小项目
mkdir cc-first && cd cc-first
git init

# 2. 写一个带 bug 的文件（温度转换：F 转 C 公式写反了）
cat > temp.js <<'EOF'
function fToC(f) { return f * 9/5 + 32; }   // 故意写错：应为 (f-32)*5/9
console.log("100F =", fToC(100), "C");
EOF

# 3. 让 Haiku 小模型先做廉价诊断（强制小模型）
ANTHROPIC_MODEL="claude-haiku-4-5" claude -p "找出 temp.js 里的 bug 并修复，用一句话说明原因"

预期结果：Claude 在头/headless -p 模式下直接返回修复方案——指出公式应为 (f - 32) * 5 / 9，并改正文件。接着升级模型做更严谨的回归：

# 4. 切回 Sonnet 主力模型，要求补边界值测试
ANTHROPIC_MODEL="claude-sonnet-4-6" claude -p "为修复后的 temp.js 增加边界用例 32F/212F 的测试并运行 node 验证"

验证要点：两次调用分别命中不同模型，证明你的 ANTHROPIC_MODEL 路由确实在起作用；整个过程没有弹任何模型选择菜单，全靠环境变量驱动——这就是"配到位"的体感。

配置与请求路由全景图

flowchart TD
    A[claude 启动] --> B{读取 settings.json}
    B --> B1[用户级 ~/.claude]
    B --> B2[项目级 .claude]
    B --> B3[项目本地 .local]
    B1 & B2 & B3 --> C[合并: 本地>共享>用户]
    C --> D{env 三件套}
    D --> D1[ANTHROPIC_API_KEY/AUTH_TOKEN<br/>身份认证]
    D --> D2[ANTHROPIC_BASE_URL<br/>路由到网关]
    D --> D3[ANTHROPIC_MODEL<br/>主模型]
    D3 --> E[/model 别名: opus sonnet haiku/]
    E --> F[实际请求<br/>主模型推理 + 小模型后台杂活]
    D1 -.授权.-> F
    D2 -.寻址.-> F

常见问题速查

改了 ~/.claude/settings.json 不生效？ 检查项目级 .local.json 是否覆盖了同名键；记住"本地优先"。
/model 切了又跳回？ 说明 settings.json 里 model 或 env.ANTHROPIC_MODEL 被锁死，删除该项改用交互切换。
走自建网关报 401？ 官方用 API_KEY，Bearer 网关用 AUTH_TOKEN，二者别混用，且确认 BASE_URL 末尾无多余 /。
想关掉自动更新与遥测？ 设置 DISABLE_AUTOUPDATER=1、DISABLE_TELEMETRY=1。

训练营适用性评估

适用类型：开发者入门营、企业内训"第一天"课程、科研团队批量接入营
教学时长：约 60–90 分钟（含动手跑通首个项目）
编排建议：作为入门营的"配置基石"课，排在"安装/登录"之后、"CLAUDE.md 与权限围栏"之前；后续可直接衔接"三层配置进阶"与"多代理编排"

参考来源

Claude Code settings — 官方文档 — settings.json 三层分层配置（用户/项目/本地）权威说明
Environment variables — 官方文档 — ANTHROPIC_API_KEY / BASE_URL / MODEL 等环境变量完整参考
Model configuration — 官方文档 — 模型别名（opus/sonnet/haiku）与路由配置
Claude Code settings.json: Complete config guide (2026) — eesel.ai — 2026 年 settings.json 配置实战指南
How to Configure Claude Code Settings (2026) — thecaio.ai — 三层配置体系与团队协作实践

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

51学通信知识星球海报-扫码加入

概述