## 概述 本教程面向零基础用户，带你用一个全新的视角完成 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`。在终端执行： ```bash # 全局安装（原生方式，最干净） 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`，把 `/bin` 加进 `~/.zshrc` 或 `~/.bashrc` | | `EACCES` 权限错误 | 系统目录写入被拒 | 改用 `nvm` 管理 Node，或 `npm config set prefix ~/.npm-global` 后重装 | | 公司网络拉包超时 | 走内网代理 | `npm config set proxy` / `set https-proxy` 后重试 | > 配置核心理念：从这一步起，所有"配什么、配在哪"的决策都遵循 **"更具体的作用域覆盖更通用的作用域"** 这一条铁律。记住它，后面三层配置就不会乱。 ## 第二步：环境变量三件套——认证与路由 这是本教程的核心。Claude Code 的"三件套"指三个最关键的环境变量，它们决定了**用什么身份、连哪个服务器、跑哪个模型**： 1. **`ANTHROPIC_API_KEY`** —— 认证身份。官方 API 直接用 Anthropic 下发的 Key。 2. **`ANTHROPIC_BASE_URL`** —— 请求路由。指向官方 `https://api.anthropic.com`，或自建/第三方兼容网关地址。 3. **`ANTHROPIC_MODEL`** —— 主模型路由。决定这一会话默认用 Opus、Sonnet 还是 Haiku。 最小可用配置（临时测试，写进当前终端会话）： ```bash 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 ` 形式发送，往往与 `ANTHROPIC_BASE_URL` 成对出现）。 > ⚠️ **安全红线**：永远在 **Shell 层级**（环境变量 / `settings.json` 的 `env` 块 / 系统密钥库）管理 Key，**绝不要**把它写进会被提交到版本库的项目文件，更不要粘贴到来源不明的第三方配置模板里。 ## 第三步：模型路由深度配置 "三件套"之外，还有一组与模型成本/速度强相关的变量，建议在首次配置时一并了解： ```bash # 主模型（决定主力推理质量） 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 网关地址放"项目本地"隔离敏感信息： ```json // ~/.claude/settings.json（用户级默认） { "env": { "ANTHROPIC_MODEL": "claude-sonnet-4-6", "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5" }, "model": "sonnet" } ``` ```json // <项目>/.claude/settings.local.json（本地隔离，绝不提交） { "env": { "ANTHROPIC_API_KEY": "sk-ant-xxxxxxxx", "ANTHROPIC_BASE_URL": "https://your-gateway.example.com" } } ``` 也可运行 `claude` 后用 `/config` 打开可视化设置界面，用 `/permissions` 查看权限层，所见即所得。 ## 第五步：首个真实项目实战——配置驱动的 Bug 修复 下面用一个完整闭环验证你的"三件套"是否真正生效。目标是让 Claude 在**低成本模型**下完成一个真实调试任务。 ```bash # 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`，并改正文件。接着升级模型做更严谨的回归： ```bash # 4. 切回 Sonnet 主力模型，要求补边界值测试 ANTHROPIC_MODEL="claude-sonnet-4-6" claude -p "为修复后的 temp.js 增加边界用例 32F/212F 的测试并运行 node 验证" ``` **验证要点**：两次调用分别命中不同模型，证明你的 `ANTHROPIC_MODEL` 路由确实在起作用；整个过程没有弹任何模型选择菜单，全靠环境变量驱动——这就是"配到位"的体感。 ## 配置与请求路由全景图 ```mermaid 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
身份认证] D --> D2[ANTHROPIC_BASE_URL
路由到网关] D --> D3[ANTHROPIC_MODEL
主模型] D3 --> E[/model 别名: opus sonnet haiku/] E --> F[实际请求
主模型推理 + 小模型后台杂活] 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`。 ## 延伸阅读 - 官方 settings 分层文档：`code.claude.com/docs/en/settings` - 官方环境变量参考：`code.claude.com/docs/en/env-vars` - 官方模型配置与别名：`code.claude.com/docs/en/model-config` - `claude doctor` 自检命令与 `llms.txt` 文档索引 ## 训练营适用性评估 - **适用类型**：开发者入门营、企业内训"第一天"课程、科研团队批量接入营 - **教学时长**：约 **60–90 分钟**（含动手跑通首个项目） - **编排建议**：作为入门营的"配置基石"课，排在"安装/登录"之后、"CLAUDE.md 与权限围栏"之前；后续可直接衔接"三层配置进阶"与"多代理编排" ## 参考来源 1. [Claude Code settings — 官方文档](https://code.claude.com/docs/en/settings) — settings.json 三层分层配置（用户/项目/本地）权威说明 2. [Environment variables — 官方文档](https://code.claude.com/docs/en/env-vars) — ANTHROPIC_API_KEY / BASE_URL / MODEL 等环境变量完整参考 3. [Model configuration — 官方文档](https://code.claude.com/docs/en/model-config) — 模型别名（opus/sonnet/haiku）与路由配置 4. [Claude Code settings.json: Complete config guide (2026) — eesel.ai](https://www.eesel.ai/blog/settings-json-claude-code) — 2026 年 settings.json 配置实战指南 5. [How to Configure Claude Code Settings (2026) — thecaio.ai](https://www.thecaio.ai/blog/claude-code-settings-guide) — 三层配置体系与团队协作实践 > [!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 等场景全覆盖。