展开目录（11 节）
Claude Code 默认连的是 Anthropic 官方接口，国内使用有两个现实障碍：一是直连不稳定，经常卡在「Connecting」或流式输出突然中断；二是官方按美元计费，重度使用成本压不住。
把它指向兼容 Anthropic 协议的第三方网关，两个问题一起解决——网络走国内可达的地址，费用按网关的分组倍率计算。核心配置只有两个环境变量，五分钟能跑通。这篇把配置、验证、排错、省钱一次讲完。
一、先拿到 Key
登录控制台，进入「令牌」页面，点新建令牌。建的时候注意三点：
- 分组决定你能用哪些模型、按什么倍率计费。编程场景选满血线路，日常问答选福利线路，差别很大。
- 额度建议先设一个小额度试水，跑通再放开，避免配置错误时烧掉配额。
- 过期时间如果只是本地测试，可以设短期，减少泄露风险。
创建完复制以 sk- 开头的字符串，它只完整显示一次，丢了只能重建。
二、确认你的模型名
换网关之后，模型名必须用网关支持的写法，不能照抄官方文档里的名字。查法很简单：
curl https://newmao.cn/v1/models \
-H "Authorization: Bearer sk-你的令牌"返回的 data 数组里就是可用模型。记下一个你要用的，配置时填进 ANTHROPIC_MODEL。
三、方式一：环境变量（最快，适合先跑通）
macOS / Linux
export ANTHROPIC_BASE_URL="https://newmao.cn"
export ANTHROPIC_AUTH_TOKEN="sk-你的令牌"
claude关掉终端就失效，适合临时测试。
Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://newmao.cn"
$env:ANTHROPIC_AUTH_TOKEN = "sk-你的令牌"
claudeWindows 永久生效
setx ANTHROPIC_BASE_URL "https://newmao.cn"
setx ANTHROPIC_AUTH_TOKEN "sk-你的令牌"setx 写进用户环境变量，需要重开终端才生效。
两个变量缺一不可：
| 变量 | 作用 | 最常见的错 |
|---|---|---|
ANTHROPIC_BASE_URL |
把请求指向网关 | 多写了 /v1，路径变成 /v1/v1/messages |
ANTHROPIC_AUTH_TOKEN |
身份认证 | 写成 ANTHROPIC_API_KEY，Claude Code 不认这个名 |
ANTHROPIC_MODEL |
默认模型（可选） | 填了网关不支持的模型名 |
Base URL 不带 /v1，Claude Code 自己会拼成 /v1/messages。这一点和 OpenAI SDK 的习惯相反，很多人在这里踩坑。
四、方式二：写进配置文件（长期生效）
每次 export 太麻烦，写进配置文件打开就生效。
文件位置：
- macOS / Linux：
~/.claude/settings.json - Windows：
C:\Users\你的用户名\.claude\settings.json
{
"env": {
"ANTHROPIC_BASE_URL": "https://newmao.cn",
"ANTHROPIC_AUTH_TOKEN": "sk-你的令牌",
"ANTHROPIC_MODEL": "claude-sonnet-4-5"
}
}文件已存在时，只把 env 这一段合并进去，不要整个覆盖——里面可能还有你的主题、快捷键、权限设置。
项目级配置（推荐团队用）
在项目根目录建 .claude/settings.json，只对当前项目生效。这样不同项目可以用不同线路，比如生产项目用稳定线路、实验项目用低价线路。
记得把带 key 的文件加进 .gitignore：
echo ".claude/settings.local.json" >> .gitignore更稳妥的做法是 key 用环境变量传，配置文件里只放非敏感项。
五、方式三：多配置切换工具
如果你同时有多个网关或多个账号（比如一个稳定线路、一个低价线路），手改配置很烦。可以用社区工具 cc-switch 之类做一键切换，原理就是把上面的 settings.json 按配置档替换。
不用工具也能自己写个脚本：
#!/bin/bash
# 切到稳定线路
cp ~/.claude/profiles/stable.json ~/.claude/settings.json
echo "已切换到稳定线路"六、验证是否真的生效
配置完别急着重启项目，先做三步自检。
第 1 步：curl 直连网关
curl https://newmao.cn/v1/models \
-H "Authorization: Bearer sk-你的令牌" \
-H "anthropic-version: 2023-06-01"返回模型列表 = 地址和 Key 都对。这一步过不了，后面的配置再怎么改也没用。
第 2 步：进 Claude Code 看状态
启动 claude，输入 /status，会显示当前的接口地址和模型。地址不是官方域名就说明换成功了。
第 3 步：发一句测试
让它「用一句话介绍你自己」。三种结果对应三种问题：
| 现象 | 说明 |
|---|---|
| 正常返回文字 | 配置成功 |
| 一直 Connecting，最后超时 | Base URL 错了，或本地网络到网关不通 |
| 立刻 401 | Key 不对、被截断，或变量名写错 |
七、报错对照表
| 状态码 | 报错关键词 | 原因 | 处理 |
|---|---|---|---|
| 400 | context length exceeded | 对话太长，超过模型上下文 | 用 /compact 压缩，或开新会话 |
| 401 | invalid x-api-key | Key 复制不完整 / 变量名错 | 重新复制，确认 ANTHROPIC_AUTH_TOKEN |
| 403 | no permission / group not allowed | 令牌分组不含该模型 | 换分组或换模型 |
| 404 | not found | Base URL 多了 /v1 |
只留域名 |
| 413 | payload too large | 一次塞了太多文件 | 分批次读，或用 grep 先定位 |
| 429 | rate limit / too many requests | 频率或并发超限 | 等 30 秒重试；持续触发就升级分组 |
| 500 | internal error | 网关或上游异常 | 重试一次，仍失败换线路 |
| 502 / 504 | bad gateway / timeout | 网关到上游超时 | 通常是上游抖动，隔几分钟再试 |
| 529 | overloaded | 上游负载高 | 重试或换线路 |
| — | 流式中断 / 半截回复 | 网络抖动、代理超时 | 关掉本地代理；检查 HTTPS_PROXY |
一个容易被忽略的坑：本地代理
如果你开着科学上网工具，Claude Code 的请求可能被代理拦走，表现是「curl 能通、Claude Code 超时」。处理办法：把网关域名加进代理的直连规则，或者临时关掉代理测试。
# 检查当前是否有代理环境变量
env | grep -i proxy有输出的话，先 unset HTTPS_PROXY HTTP_PROXY 再试一次。
八、成本控制：四条实用建议
换网关只是省了一部分，真正烧钱的是用法。四条建议按性价比排序：
1. 用缓存，别重复读同一份文件
Claude 支持 prompt caching，同一段前缀在短时间内重复使用时按更低价格计费。做法是把固定内容（系统提示词、项目说明、常用文件）放在上下文前部，让变化的部分靠后。
2. 上下文要主动压缩
长会话会让每一轮都把历史全带上，成本随轮次线性上涨。两个习惯：
- 一个任务做完就
/clear开新会话，别在一个会话里干十件事 - 上下文快满时用
/compact，让它自己总结历史，比硬撑着强
3. 按任务挑模型
| 任务 | 建议线路 | 理由 |
|---|---|---|
| 复杂重构、架构设计 | 满血 / 高倍率 | 需要强推理，省钱反而返工 |
| 日常写函数、改 bug | 中等线路 | 性价比区间 |
| 格式转换、写注释、翻译 | 福利线路 | 任务简单，能力过剩没意义 |
4. 限制输出长度
输出 token 通常比输入贵 3-5 倍。让它「简短回答」「只给代码不要解释」，比放任它写三千字省得多。
九、进阶：把常用提示词做成命令
如果你经常让 Claude Code 做同一类事，别每次手写提示词。在项目里建 .claude/commands/，放 Markdown 文件，之后用斜杠命令调用。
# .claude/commands/review.md
请审查以下代码，重点关注：
1. 输入校验是否完整
2. 是否有 SQL 注入 / XSS 风险
3. 错误处理是否吞掉了异常
4. 是否有明显的性能问题（N+1 查询、循环内 IO）
代码：
$ARGUMENTS之后输入 /review 你的代码 即可复用。团队里把这个目录提交到仓库，所有人共享同一套提示词，输出质量会稳定很多。
十、常见问题
Q1：环境变量设了，但 Claude Code 还是连官方？
大概率是配置文件优先级更高。~/.claude/settings.json 里的 env 会覆盖 shell 变量，检查那个文件里有没有写官方地址。
Q2：能用 OpenAI 的 SDK 调吗？
可以，但那是另一套接口（/v1/chat/completions）。Claude Code 走的是 Anthropic 协议（/v1/messages），两者不能混。
Q3：为什么同样的提示词，官方和网关回答不一样？
网关只是转发，模型本身一样。差异通常来自：温度参数默认值不同、系统提示词注入、或上游版本微调。要求稳定输出的场景，把 temperature 显式固定。
Q4：图片能传吗？
支持多模态的模型可以。Claude Code 里直接把图片拖进终端，或给它文件路径。
Q5：并发高了会不会被限流？
会。每个分组有独立的并发上限，超了返回 429。需要跑批量任务时，客户端加个队列控制并发数，比硬顶更稳。
Q6：令牌泄露了怎么办？
立刻去控制台删除该令牌，重新建一个。令牌是无状态的，删掉即失效，不用改密码。
Q7：为什么有时候会返回一半就停？
三种可能：上游超时、本地网络抖动、或输出达到 max_tokens 上限。先看是不是固定长度停止（那就是 max_tokens），再排查网络。
Q8：Windows 上路径带空格报错？
配置文件路径用引号包住："C:\Users\你的名字\.claude\settings.json"。
Q9：可以在 CI/CD 里用吗？
可以，把 key 放在 CI 的 secret 里，通过环境变量注入，别写进仓库。建议单独建一个限额令牌给 CI 用，出问题好定位。
Q10：换回官方怎么操作？
删掉那两个环境变量或配置文件里的 env 段，重启终端即可。官方配置不会因为加过网关而损坏。
小结
整个配置就两步：ANTHROPIC_BASE_URL 指向网关，ANTHROPIC_AUTH_TOKEN 放令牌，Base URL 不带 /v1。
踩坑集中在四处：Base URL 多带路径、变量名写成 ANTHROPIC_API_KEY、令牌分组没权限、本地代理拦截。
跑通之后，重点转向用法——控制上下文、按任务选线路、用缓存，比换网关更能省钱。
