Claude Code API Key 配置教程：环境变量、配置文件与安全（2026）

Claude Code 的 API Key 不只是一个字符串，它决定了请求以谁的身份计费、能调用哪些模型、泄露后影响多大。多数 401 并不是 Key 本身失效，而是变量名、请求头或配置层级出了问题。

本文按“鉴权链路、创建 Key、环境变量与配置文件、多套配置、轮换、防泄露、CI 与团队、401 排查”的顺序，给出一套可以直接照做的配置方法。具体的变量名和配置项以当前 Claude Code 版本及网关文档为准。

说明：Claude、Anthropic 是其权利人的商标，本文仅作技术说明，与相关厂商无隶属关系；接口、权限和价格以各平台官方文档及站内页面为准。

一、先理解 Claude Code 的鉴权链路

Claude Code 启动后，会把请求发往 ANTHROPIC_BASE_URL，并带上认证信息。认证信息通常来自两个变量之一：

ANTHROPIC_AUTH_TOKEN：以 Authorization: Bearer 发送，常见于网关接入。
ANTHROPIC_API_KEY：以 x-api-key 发送，贴近 Anthropic 原生方式。

网关收到请求后，用 Key 找到对应账号，再检查余额、额度、模型权限和有效期。任何一环不通过，都可能表现为 401、403 或 429。所以排查时不要只盯着 Key 字符串。

另一个常见误解是把 Key 和模型绑定。Key 是身份，模型是请求参数；同一把 Key 通常可以调用多个模型，具体取决于账号权限和网关策略。

二、创建 Key：五步做完

打开中商起航 AI 网关或你使用的平台，注册并登录控制台。
进入「API 密钥」页面，点击新建。名称写清环境和用途，例如 claude-code-work-mac。
设置额度上限和过期时间。测试 Key 先设低额度，确认真实消耗后再调整。
如果平台支持模型白名单或项目范围，只勾选 Claude Code 需要的模型。
复制完整 Key，立即存入密码管理器或密钥管理服务。多数控制台只显示一次完整值。

Key 常以 sk- 开头，但前缀不能证明真伪，也不能说明权限。复制时注意首尾空格和换行，这是 401 的高频原因。

创建后先用一条最小 curl 验证，再分发给团队成员。验证方法见后文“401 排查”一节。

三、环境变量与配置文件：怎么选

方式	适合场景	优点	注意
Shell 环境变量	个人开发机、临时切换	不落盘到项目，切换方便	新开终端或 IDE 可能读不到
用户级 settings.json	个人长期使用	一次配置，全局生效	Key 明文存储
项目级 settings.local.json	单项目覆盖	不影响其他项目，可加入 gitignore	换机器要重新配置
apiKeyHelper 或密钥管理	团队、共享机器、合规场景	Key 不直接出现在配置文件	需要额外脚本和权限管理
CI 密钥变量	自动化流水线	与代码分离，可审计	注意日志脱敏和分支权限

环境变量适合“我现在就要试一下”；settings.json 适合“这台机器长期这么用”；密钥管理适合“Key 不能以明文出现在磁盘上”。三者可以叠加，但要知道谁覆盖谁。Claude Code 的配置优先级大体是企业管理配置、命令行参数、本地项目、项目、用户依次覆盖，版本之间可能微调，以官方文档为准。

一个容易踩的坑：在 ~/.zshrc 里 export 了变量，但从 Dock 或 IDE 启动的 Claude Code 读不到。图形界面程序继承的是登录环境，不一定加载你的 shell 配置。遇到这种情况，改 settings.json 或在启动脚本里显式注入。

四、多套配置：个人、项目、团队怎么隔离

建议至少分三套 Key：个人日常、项目专用、自动化。它们的额度、权限和轮换周期不同，混用会让用量和故障都难以定位。

如果不想维护多个配置文件，可以用 shell 函数按场景注入：

# ~/.zshrc
claude_work() {
  ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com" \
  ANTHROPIC_AUTH_TOKEN="$ZSQH_WORK_KEY" \
  claude "$@"
}

claude_test() {
  ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com" \
  ANTHROPIC_AUTH_TOKEN="$ZSQH_TEST_KEY" \
  claude "$@"
}

真实 Key 放在 ~/.zshrc.local 或密钥管理工具里，主配置文件只引用变量。这样切换环境只改函数名，不用改项目代码。

项目级隔离用 .claude/settings.local.json，并确认它已加入 .gitignore。团队共享的 .claude/settings.json 只放 Base URL、模型名、权限等非敏感项，不要放 Key。

五、Key 轮换：什么时候换、怎么换

轮换的目的不是形式主义，而是缩短泄露后的有效窗口。建议在以下时机轮换：员工离职或转岗、设备丢失、怀疑泄露、供应商要求，以及固定周期。周期可以按团队合规要求设定，例如每 90 天。

在控制台创建新 Key，命名带日期，例如 claude-code-prod-2026-10。
先把新 Key 写入密钥管理工具或环境变量，暂时不要删除旧 Key。
用 curl 和 Claude Code 各验证一次，确认模型、额度、权限正常。
观察旧 Key 的用量日志，确认没有遗漏的脚本或成员仍在使用。
停用旧 Key，再观察一到两天错误率。
记录轮换时间、负责人和影响范围，方便下次交接。

不要在生产请求高峰期做轮换。双 Key 并行一段时间，比“删了再建”安全得多。

六、防泄露：从开发机到代码仓库

Key 泄露的常见路径不是黑客攻击，而是自己提交、截图、录屏、发群聊或写进日志。可以按这几条做：

.gitignore 覆盖 .env、.env.*、.claude/settings.local.json、*.pem 等文件。
提交前用 secret scanning 或 pre-commit hook 检查 sk- 等模式。
不在代码里写默认 Key，不用 echo $ANTHROPIC_AUTH_TOKEN 调试。
日志里对 Authorization、x-api-key 等请求头做脱敏。
共享屏幕和截图前关闭终端历史或清屏。
开发机设置文件权限，例如 chmod 600 ~/.claude/settings.json。
使用带过期时间和额度上限的 Key，降低单次泄露的损失。

如果确认泄露，顺序是：先停用或删除 Key，再创建新 Key，然后排查用量日志和代码仓库历史。只改密码或只删文件都不够，因为旧 Key 可能已经被复制到别处。

七、CI 与团队使用

CI 环境的原则是“Key 不进入代码、不进入镜像、不进入日志”。具体做法：

用平台提供的 Secret 或环境变量功能注入，不要在 YAML 里明文写。
限制 Secret 只在受保护分支或受信工作流中可用。
日志输出前确认不会打印请求头；多数 HTTP 库默认不打印，但自定义日志可能打印。
自动化任务使用单独的 Key，额度单独设置，便于定位异常。
团队成员一人一 Key，离职当天停用，不要用共用 Key 省事。
定期导出用量，按成员、项目、模型三个维度核对。

如果平台支持短期凭证或 OIDC，优先使用，减少长期 Key 的存放。是否支持取决于平台能力，接入前先看文档。

八、401 排查：按这个顺序查

401 表示认证失败，不代表 Key 一定错了。按下面顺序排查，通常几分钟能定位：

确认请求发往哪个 Base URL，执行 echo $ANTHROPIC_BASE_URL。空值或指向旧地址都会失败。
确认 Key 没有首尾空格、换行或多余引号，重新从控制台复制一次。
确认变量名正确：是 ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY，两者不要同时设置。
确认请求头与网关要求一致：Bearer 还是 x-api-key。
确认 Key 未过期、未被停用，账户有余额。
确认模型名在网关目录中存在；有些平台对无权限模型返回 401 或 403。
如果经过代理，检查代理是否剥离或改写 Authorization 头。
用最小 curl 复现，排除 Claude Code 版本或配置层级的干扰。

常见错误对照：

错误	常见原因	处理
401 Unauthorized	Key 错误、变量名错、请求头不对	重新复制；只保留一个认证变量
403 Forbidden	Key 无模型权限或 IP 限制	检查白名单和模型权限
404 Not Found	Base URL 或路径不对	根地址与 `/v1` 逐次验证
429 Too Many Requests	并发或额度超限	降并发；检查 Key 限额
insufficient quota	余额不足	充值或更换 Key

如果 curl 正常、Claude Code 仍报 401，重点查启动环境：IDE 内置终端、Docker、systemd、launchd 可能没有继承你的 shell 变量。把配置写进 settings.json 或启动脚本，通常能解决。

常见问题

Claude Code 的 Key 和 Claude 网页会员是同一个吗？

不是。网页会员是聊天产品订阅，API Key 是接口身份凭证。Claude Code 走的是 API 调用，不能用网页会员代替 Key。

一把 Key 可以同时给 Claude Code 和 Cursor 用吗？

技术上通常可以，只要工具都支持同一个网关协议和模型名。但建议按工具分开 Key，便于分别限额、排查和停用。

Key 放在 settings.json 里安全吗？

个人电脑可以接受，因为文件只在本机。共享机器、代码仓库和 CI 里不要放明文 Key，应改用环境变量、apiKeyHelper 或密钥管理服务。

轮换 Key 需要停服吗？

不需要。先创建新 Key 并验证，再切换配置，最后停用旧 Key，让两把 Key 并行一段时间，可以避免请求中断。

为什么昨天还能用，今天突然 401？

常见原因包括 Key 到期、余额不足、额度用完、Key 被管理员停用、网关调整了鉴权方式，或者启动环境没有加载最新变量。按 401 排查顺序逐项确认即可。

下一步

如果你还没有 Key，可以从注册入口创建一把低额度测试 Key，按本文顺序配置和验证。模型、额度和计费方式见模型价格，价格会随模型版本和上游政策调整，以页面实时信息为准。