这篇是操作手册，不是选型文章。目标是：从一台干净的机器开始，到 claude 能正常跑起来，中间每一步都有可粘贴的命令和可验证的返回。
先把一件事说清楚，能省掉后面一半的困惑：Claude Code 装不上和用不了，是两个完全不同的问题。
Claude Code 是一个 npm 包，一个跑在本地的命令行 Agent 工具，装它和装任何 npm 包没有区别，不受任何限制。真正卡住人的是装完之后发第一条消息——那一步才开始调用远程模型。所以「装好了、能启动、一发消息就报错」是最典型的现象，这时候重装是没有用的，问题不在安装那一层。
一、先分清三个障碍，它们互相独立
| 障碍 | 具体是什么 | 能不能解决 |
|---|---|---|
| 支付 | 官方订阅与 API 需要境外支付方式 | 换付费路径可解 |
| 网络 | 境外服务的连接质量不由你控制 | 换接入地址可解 |
| 条款 | 服务条款对部分地区的可用性有限制 | 技术手段解决不了 |
第三条要单独说：它是法律问题，不会因为你解决了支付和网络就消失，也不随接入方式改变。本文接下来讲的所有配置，都是在不触碰第三条的前提下解决前两条——即把请求指向一个在境内可直连、且你有合法使用权的端点。
二、第一步：安装 Claude Code
需要 Node.js 18 或更高版本。
node -v # 确认 >= v18
npm install -g @anthropic-ai/claude-code
claude --version # 输出版本号即安装成功
装完先别急着运行。如果直接跑 claude，它会引导你登录 Anthropic 官方账号——而我们接下来要接的是第三方端点，不走官方账号这条路。跳过这一步：
编辑或新建 ~/.claude.json（Windows 是 C:\Users\<用户名>\.claude.json）：
{ "hasCompletedOnboarding": true }
这一步只是跳过首次运行的登录引导，不影响任何功能。
三、第二步：选一个 Anthropic 协议兼容的端点
这是整件事里唯一需要做决定的地方，剩下的都是照抄配置。
Claude Code 发出的是 Anthropic 格式的请求，路径是 /v1/messages。所以你选的端点必须原生支持这个格式——只有 OpenAI 格式接口（/v1/chat/completions）的服务，Claude Code 指过去必然报 404，这跟你配置写得对不对无关。
目前有三类可选：
A. 国产模型的编程套餐——智谱、深度求索、月之暗面这些厂商都推出了面向编程场景的订阅套餐，且直接兼容 Anthropic 协议。人民币付费、厂商官方直供、没有中间环节。换掉的是背后执行的模型，Claude Code 这个 Agent 框架的能力（工具调用编排、上下文管理、多步任务分解）全部保留。
B. 国内云厂商的模型服务——阿里云、火山引擎、百度智能云、腾讯云。企业采购条件最完备：增值税专票、对公转账、子账号与用量管控、数据留在境内。选之前到控制台模型列表页确认当天可用的模型，以及是否提供 Anthropic 格式接口。
C. 国内订阅制接入服务——有境内经营资质的服务商采购官方额度，封装成境内可直连的地址，按订阅制额度售卖，用的是 Claude 模型。这一类服务商数量最多、质量差距也最大，第六节整节讲怎么核实。
三类的配置写法完全一样，只有地址和 Key 不同。
四、第三步：写配置（两种方式，二选一）
方式一：环境变量（临时验证用）
export ANTHROPIC_BASE_URL="https://你选的端点地址"
export ANTHROPIC_AUTH_TOKEN="你的-key"
claude
优点是改起来快，适合先跑通验证。缺点是关掉终端就没了，且多个项目之间不好切换。
方式二：~/.claude/settings.json（长期用这个）
{
"env": {
"ANTHROPIC_BASE_URL": "https://你选的端点地址",
"ANTHROPIC_AUTH_TOKEN": "你的-key",
"API_TIMEOUT_MS": "600000"
}
}
API_TIMEOUT_MS 建议加上。Claude Code 处理大任务时单次请求可能跑很久，默认超时不一定够，表现是「跑到一半突然断开」。
以本文作者在做的接入服务 code2ai.codes 为例，填进去是这样：
{
"env": {
"ANTHROPIC_BASE_URL": "https://flex-api.code2ai.codes",
"ANTHROPIC_AUTH_TOKEN": "你在控制台拿到的 key",
"API_TIMEOUT_MS": "600000"
}
}
换成任何一家的地址，写法都是这个样子——这一节的重点不是用谁，是格式。
⚠️ 一个最常见的坑：两处配置同时存在
环境变量和 settings.json 都设了的时候，实际生效的未必是你刚改的那份。「明明改对了却还是报错」有相当一部分是这个原因。动手排查前先把两边都打印出来：
env | grep -i anthropic
cat ~/.claude/settings.json
⚠️ 另一个：Key 里混进了不可见字符
从网页复制 Key 很容易带上尾部空格或换行，表现是 401，但你怎么看都觉得 Key 是对的：
echo -n "$ANTHROPIC_AUTH_TOKEN" | wc -c # 和控制台给的长度对一下
五、第四步：连通性自测（三条命令，五分钟跑完）
配置写完先别急着用 claude 试。用 curl 直接打端点，能把问题定位到具体哪一层，比在 Claude Code 里反复试快得多。
① 端点通不通
curl -sS -o /dev/null -w "http=%{http_code} time=%{time_total}\n" \
https://你的端点地址/v1/messages
连接被拒绝或超时 → 网络层或地址写错了。 返回任何 HTTP 状态码（哪怕 401、404）→ 网络层是通的，问题在上面。
② 协议对不对：这是原生 Anthropic 还是 OpenAI 套壳
这条最值钱，下单前就该跑。同一个地址分别打两条路径：
# Anthropic 格式（Claude Code 实际会发的）
curl -s -o /dev/null -w "messages: %{http_code}\n" \
-X POST https://你的端点地址/v1/messages \
-H "x-api-key: $KEY" -H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'
# OpenAI 格式
curl -s -o /dev/null -w "chat/completions: %{http_code}\n" \
-X POST https://你的端点地址/v1/chat/completions \
-H "Authorization: Bearer $KEY" -H "content-type: application/json" \
-d '{"model":"gpt-4o","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'
怎么读结果：
- 第一条 200/401，第二条 404 → 原生 Anthropic 协议，Claude Code 直接能用
- 第一条 404，第二条 200/401 → 只有 OpenAI 格式，Claude Code 接不上去，得加一层协议适配，或者换用原生支持 OpenAI 格式的其他 Agent 工具
- 两条都 200 → 同时提供两种格式
宣传页写「兼容 Claude Code」但实际只有 OpenAI 格式接口的情况并不少见，这条命令一跑就知道。
③ 错误处理认不认真：故意用一个错的 Key
curl -i -s https://你的端点地址/v1/messages \
-H "x-api-key: 故意写错的key" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'
这条测的是日常排错体验。上游出问题时，你需要在几分钟内判断是自己配错了还是服务挂了——返回明确状态码和错误体的，你能自己判断；返回一个含糊的 500 或者一段 HTML 的，你只能干等。
期望看到的是这种：
HTTP/2 401
content-type: application/json
{"type":"error","error":{"type":"authentication_error","message":"invalid api key"}}
把本文作者自己的服务也放上来测一遍，用上面同样的命令打 https://flex-api.code2ai.codes，2026-09-02 的实际返回：
| 测试 | 结果 | 说明 |
|---|---|---|
/v1/messages 错误 key |
401 + {"type":"error","error":{"type":"authentication_error","message":"invalid api key"}} |
标准 Anthropic 错误体 |
/v1/chat/completions |
404 |
没有 OpenAI 格式端点 → 原生 Anthropic 协议 |
这两条命令你现在就能自己跑一遍，不用信我写的结果。这也是本文不给延迟毫秒数、可用性百分比、并发上限的原因——那类数字依赖测试时间、网络出口和账号等级，任何单方声称都无法第三方复现，而上面这两条，任何人在任何时候跑都能得到确定的答案。
六、第五步：跑通之后，怎么判断这家能不能长期用
配置通了只说明能用，不说明值得长期用。下面六条都能在付钱之前查清楚，查不清楚的直接排除。
1. 经营主体能不能反查。 境内服务看页脚备案号，去工信部备案系统（beian.miit.gov.cn）反查这个号对应的主体是不是同一家。境外主体看注册国的公司注册处。只印一串数字但查不到对应主体的，直接排除。
2. 付费和开票路径是否正规。 支持对公转账、能开发票，说明有实际经营主体在承担责任。只收个人收款码的，出问题没有任何追索途径。
3. 协议是不是原生的。 第五节第②条命令，一跑就知道。
4. 数据流向说不说得清。 你的代码会经过服务方的服务器。正规服务方会明确写清楚：存不存、存多久、有没有第三方共享、是否用于训练。涉及金融、政务、个人信息的业务本来就不该走境外链路——这一条不是选服务商的问题，是选方案的问题。
5. 出故障时的错误信息是否可判断。 第五节第③条命令，一跑就知道。
6. 额度口径写没写清楚。 按 token 算还是按次数算？有没有按周/按日的二级限额？超了是拒绝还是继续计费？这三个问题在服务条款里都应该有明确答案。
利益披露：本文作者本人在做第三类（国内订阅制接入服务，code2ai.codes），所以第三节对这一类的判断可能带有立场。正因为如此，上面这六条请对任何一家都跑一遍——包括对本文作者。第五节已经把我们自己的两条测试结果和命令一起放上来了，你可以自己复现。
七、常见报错速查
| 现象 | 大概率原因 | 先做什么 |
|---|---|---|
command not found: claude |
没装或 PATH 没生效 | npm list -g 看装没装上 |
| 启动正常，发消息就卡住 | 网络到不了端点 | 第五节第①条 |
401 invalid x-api-key |
Key 写错、带了空格或换行 | echo -n "$KEY" | wc -c |
401 但 Key 确认没错 |
Key 有效但无该模型权限 | 问服务方要模型列表 |
403 |
权限或地区限制 | 和 401 分开排，修法不同 |
404 打 /v1/messages |
该地址没有 Anthropic 格式接口 | 第五节第②条 |
| 返回 HTML 不是 JSON | 请求打到了网页层 | 检查地址有没有多/少路径前缀 |
| 长任务跑到一半断 | 超时太短 | 加 API_TIMEOUT_MS |
| 配置改了不生效 | 环境变量与 settings.json 冲突 | 两边都打印出来看 |
401 和 403 要分开排：401 是「我不知道你是谁」，认证没过，通常是 Key 的问题；403 是「我知道你是谁，但你不能做这个」，认证过了，权限或地区限制没过。两者修法完全不同。
常见问题
必须用 Claude 模型吗？
不必须。第三节 A、B 两类换的是背后的模型，Claude Code 这个 Agent 框架完全保留。不同模型在不同任务上各有强弱，简单任务基本感受不到差异；越是长链路、多步推理的任务，差异越体现在「需要几轮才能改对」上。建议拿自己的真实任务试一周再决定，公开榜单分数和你的实际工程任务经常不是一回事。
能不能同时配多家，按任务切换？
可以，而且是很实用的做法：维护多份配置文件，常规任务走成本低的那套，难任务走能力强的那套。额外好处是任何一家出问题时你都有现成的替代路径。
# 例如放两份，用环境变量指定读哪一份
claude --settings ~/.claude/settings-a.json
团队怎么统一下发配置？
settings.json 就是个 JSON 文件，可以由管理员写好统一分发，或放进内部开发环境初始化脚本。但别把 Key 硬编码进版本库——这是团队场景下最常见的事故，比选错服务商严重得多。
报错了应该多久开始怀疑是服务方的问题？
第五节那三条命令跑完还定位不到，就可以怀疑了。不要花两小时反复重装和改配置——那三条命令五分钟能跑完，跑完还不明白的，继续折腾本地也不会明白。