05 · 接入 DeepSeek 等第三方模型
通过兼容网关或第三方服务配置模型的基本原理、环境变量、验证方法和风险边界，别把兼容接口当成官方能力。
Claude Code 默认连的是 Anthropic 自家的模型，但它并没有把这扇门关死——留了一个「接第三方模型」的口子，很多用户用它来做成本优化或本地化。这篇讲清楚这条路子能怎么走、不能怎么走。
为什么会有第三方接入需求
最常见的三个动机是：① 想降低 token 成本（官方 Opus 比多数国产模型贵一个量级）；② 数据合规——不想走境外 API；③ 团队已经为某个国产模型买了大量 token 额度，想复用。明确你的动机，后面的判断才有依据。
基本原理：兼容接口这层
flowchart LR A[Claude Code] --> B[兼容网关 第三方] B --> C[真实模型 第三方] C -->|响应| B B -->|翻译回 Anthropic 协议| A style A fill:#5eead4,color:#050a0f style B fill:#a78bfa,color:#050a0f style C fill:#0f1a24,color:#e6f1f5
第三方接入不是 Claude Code 直接和模型通信——中间经过一个「兼容网关」。原理是：第三方服务商实现 Anthropic 协议的兼容接口，Claude Code 发起请求时，目标 URL 指向这个网关，网关收到请求后翻译给它后端的真实模型，响应回来再翻译回去。对 Claude Code 来说，它全程以为自己在跟 Anthropic 说话。
这种「伪 Anthropic 协议」的兼容方案，让接入成本极低——理论上任何一个愿意实现兼容接口的服务商，都能被 Claude Code 接上。但这里有个隐藏前提：兼容要「真兼容」，不少号称兼容的服务商实际只支持了基础对话，工具调用、流式响应、模型名规范都可能和官方有差异。
实际配置：环境变量这一层
Claude Code 接第三方主要靠环境变量。核心的几个：
- `ANTHROPIC_BASE_URL`：兼容接口的地址（取代默认的 Anthropic 端点）
- `ANTHROPIC_AUTH_TOKEN`：第三方服务的 API Key
- 模型名相关的变量：不同服务商的字段名可能略有差异，常见的有 `ANTHROPIC_MODEL` 或通过 settings.json 里的 model 字段
通用骨架（具体字段名以你用的服务商文档为准）：
bashexport ANTHROPIC_BASE_URL=https://你的服务商兼容接口地址/v1
export ANTHROPIC_AUTH_TOKEN=你的_api_key
把这两行加到 shell 配置文件（macOS/Linux 是 `~/.zshrc` 或 `~/.bashrc`，Windows 是 PowerShell profile），重启终端生效。Key 千万不要写进代码仓库或聊天里发出去——它是账户的钱包钥匙。
验证三步：别只信它能回话
能接通 ≠ 能干活。验证要分三步走，由粗到细：
flowchart LR A[配置完成] --> B[1. 看模型名] B -->|是第三方| C[2. 测试工具调用] B -->|是 Claude| X[环境变量没生效] C -->|工具能用| D[3. 真实任务] C -->|不会用工具| Y[接口工具不全] D -->|能用| E[对接成功] D -->|不行| Z[找其他模型] style A fill:#5eead4,color:#050a0f style E fill:#5eead4,color:#050a0f style X fill:#22d3ee,color:#050a0f style Y fill:#22d3ee,color:#050a0f style Z fill:#22d3ee,color:#050a0f
① 看一眼连接：启动 Claude Code，让它「自我介绍」（比如「你的模型是谁？」），看它回的是不是第三方服务商提供的模型名。如果还是默认的 claude-* 系列，说明环境变量没生效或被忽略。
② 真一刀测试：让它做一件 Claude Code 必须用工具的任务——读某个文件、改一段代码、跑一条命令。如果它能做，说明工具调用这条链路也通了；如果它只会回话但拒绝动手（比如回我无法访问文件），那说明兼容接口对工具协议支持不全。
③ 端到端验证：拿一个你日常真实的小任务（比如「帮这个文件加一行注释」），看完成度、质量、速度是不是符合预期。这一步是把「能跑」和「能用」区别开的关键。
风险边界：兼容 ≠ 等同
这是最容易踩坑的地方。第三方模型即使是同一个名字，和官方 Claude 模型的差别可能很大：
- **工具调用能力**：Claude 模型强在它对工具调用的精确控制、错误处理、长链路规划。第三方模型即便「兼容」了协议，工具调用上往往明显掉链子，尤其是多步骤任务。
- **上下文长度**：不同服务商宣称的上下文长度，实际可用的往往差很多，Claude Code 长任务里如果需要带大量文件，超出有效长度会静默截断或开始胡编。
- **推理能力差异**：Claude 模型在复杂推理、代码理解上有口碑优势，第三方模型通常弱一档。这意味着同一段提示词，第三方模型可能理解得浅、改得糙。
- **响应速度与稳定性**：第三方服务商可能偶发波动，API 限流、模型下架都更常见。
决策对照：要不要接
三个问题快速判断：① 你是不是已经买了 Claude 订阅？如果是，接第三方等于重复付费，不划算。② 你做的任务是简单日常活，还是复杂长链路？后者对模型能力要求高，第三方更容易掉链。③ 你能不能接受偶尔需要切回官方模型的折腾？如果不能，就别接。
经验法则：日常代码问答、改注释、看 bug 这类活，第三方问题不大；大型重构、疑难调试、跨模块推理，官方 Claude 不可替代。
调试手册：常见报错怎么办
① 401 / 鉴权失败：99% 是 Key 没设对——检查 `ANTHROPIC_AUTH_TOKEN` 的名字对不对、有没有拼错、Key 有没有过期、账号有没有欠费。
② 404 / 找不到端点：`ANTHROPIC_BASE_URL` 配置错了——检查地址格式（常见漏 `/v1` 后缀）、服务商域名有没有拼错、HTTPS 而不是 HTTP。
③ 400 / 请求格式错误：兼容接口实现不完整——服务商没全实现 Anthropic 协议。换个服务商或换回官方。
④ 模型名无效：服务商升级改了模型名，但 Claude Code 的环境变量没更新。去服务商文档查最新模型名。
⑤ 能回话但拒绝用工具：兼容接口没实现工具调用协议。这条是「能接但不能用」的典型场景，建议换服务商。
一页速览
接第三方能省成本或做本地化，但代价是模型能力的部分缩水。把它当作「日常糙活的省钱工具」而不是「主力生产工具」会更合适。配置走环境变量，验证分三步（连接 / 工具调用 / 端到端），撞墙时优先排查 Key、URL、模型名这三类高频问题。
动手试一下：比起看十遍，不如立刻打开 Codex 跑一个小任务验证你理解的概念。比如这一篇讲的概念，你可以找一个一分钟能完成的小需求，让它跑一遍，看实际行为是不是和你理解的一致。
五分钟练习：① 找一个一分钟能完成的代码任务 ② 用这一篇的方法描述给 Codex ③ 看它执行时有没有触发你刚学的那个机制 ④ 验证结果是否符合预期。这一轮做下来，你对这一篇的理解会深 3 倍。
延伸阅读：学完这一篇，你可以看本组里的下一篇，把相邻的概念连起来读；也可以跳到更后面的组学 MCP、子代理、Skills 这些更深的能力。知识是网状的，多跳几篇会理解更深。
一页速览：如果只能记三件事，① {一}。② {二}。③ {三}。其他细节以后需要再翻这一篇查。