Claude Code 接入自定义 API 实操

1. 场景与前置条件把 Claude Code 接入自定义 API 时最怕的不是没有教程而是几个错误同时出现base_url 少写路径、环境变量没导出、模型调用名拼错。任何一个单独存在都会让请求失败但报错往往只显示 404 或 401很难一眼定位。所以先别急着改 Claude Code 配置用一个最小的 Python 脚本把自定义 API 链跑通再把参数迁移到 Claude Code排查顺序会清晰很多。这里假设你已经拿到一个sk_live_开头的 API Key并且能在终端里执行 Python。示例在 Python 3.10 到 3.12、macOS 和 Linux 下验证Windows 的环境变量设置命令不一样但 Python 代码相同。Claude Code 本身要使用 Anthropic 兼容端点所以本教程会在环境准备里先验证 OpenAI 兼容端点确认 base_url、key、模型调用名都正确再映射到 Claude Code 需要的 Anthropic 兼容配置。这个顺序看似绕了一下实际上能少改很多配置。2. 环境准备这一节先验证千木SilvaMux的 OpenAI 兼容端点因为用 Python SDK 调用最省事且能暴露大多数参数问题。先安装依赖pip install openai装完以后把 API Key 放进环境变量而不是写死在脚本里。硬编码 key 容易经 Git 泄露切换项目时也容易误用旧 key。导出命令大致是export加上脚本里os.environ读取的那个变量名值为sk_live_开头的字符串。Windows 使用setx后需要重开终端再运行。Base URL 是这次接入最容易出错的地方。脚本里的base_url参数已经写死照抄即可。不要把它换成 api 开头的子域也不要漏掉/api/v1。调用地址与文档地址不是同一个写法后者不带 www前者带 www区别很大。确认这一段没有问题之后再进入最小可跑示例。3. 最小可跑示例创建一个smoke_test.py内容如下import os from openai import OpenAI client OpenAI( api_keyos.environ[SILVAMUX_API_KEY], base_urlhttps://www.silvamux.com/api/v1, ) response client.chat.completions.create( modelminimax-m2.5, messages[ {role: user, content: 用一句话解释什么是自定义 API 接入} ], ) print(response.choices[0].message.content)运行python smoke_test.pybase_url这一行是关键必须逐字符保持脚本里的写法不要换成 api 开头的子域也绝不能丢掉/api/v1。OpenAI SDK 会根据这个地址拼接请求路径一旦写错不管后面模型调用名和消息体多正确都看不到结果。api_key直接读环境变量里的那个值没有硬编码在文件里。model填minimax-m2.5这个值要取自模型广场的稳定 alias不要拿展示名自己加下划线或改大小写。填错时服务端通常返回model not found错误信息不会提示你大小写错了容易把人带偏。messages数组里的role也不能省。接口会校验这个字段缺了直接返 400。返回内容在choices[0].message.content。如果请求通了但这里为空再打印一次response.usage看看有没有实际消费。这一步能通过说明自定义 API 的最小链路已经建立。4. 逐步扩展最小示例只返回完整结果看不到中间生成过程。但 Claude Code 的交互依赖流式输出如果自定义 API 的流式没有正确处理会出现输出看起来卡住或末尾缺掉一块。扩展如下import os from openai import OpenAI client OpenAI( api_keyos.environ[SILVAMUX_API_KEY], base_urlhttps://www.silvamux.com/api/v1, ) stream client.chat.completions.create( modelminimax-m2.5, messages[ {role: user, content: 列出接入自定义 API 的三个检查点} ], streamTrue, ) for chunk in stream: if not chunk.choices: continue delta chunk.choices[0].delta if delta and delta.content: print(delta.content, end, flushTrue)这次代码与最小示例相比只增加了streamTrue其余初始化参数完全相同。注意循环体第一行先判断chunk.choices是否为空。原因在于自定义 API 的流式末尾可能返回一个choices为空、但带有usage的片段直接把chunk.choices[0]拿出来会抛IndexError程序就断在最后一小段。这里不用data: [DONE]作为结束判断而是让循环自然走到流结束是避免截断的关键写法。5. 排错404 或连接超时openai.NotFoundError: Error code: 404直接原因base_url写错。常见是把 www 前缀换成了 api 前缀或者漏掉/api/v1SDK 最终请求到一个不存在的位置。修法回到最小示例代码块把base_url原样复制不要手动“优化”域名。改完先重跑 smoke_test.py。401 认证失败openai.AuthenticationError: Error code: 401直接原因环境变量没导出或导出后没在同一个终端运行脚本。macOS/Linux 的 export 只对当前会话生效新开终端就读不到。Windows 使用 setx 之后没有重开终端也会读到旧环境。修法先在运行脚本的终端里执行echo确认环境变量值是sk_live_开头。如果为空就重新 export 一次再跑。model not foundopenai.BadRequestError: Error code: 400 - {error: {message: model not found, type: gateway_error, code: ERROR_CODE}}直接原因模型调用名拼写不符合平台规范。自定义 API 的调用名是平台规范后的别名拿展示名或者上游官方命名来填都可能报错。修法到模型广场详情页复制稳定 alias例如minimax-m2.5。不要自己改大小写、加连字符或下划线。429 限流openai.RateLimitError: Error code: 429直接原因请求太频繁服务端限流。不是参数错误重试前先等一会儿。修法采用指数退避第一次等 1 秒第二次等 2 秒第三次等 4 秒最大等待 30 秒。不要写死循环频繁重试那样可能持续被限。常见问题Claude Code 配置自定义 API 后为什么提示模型不支持Claude Code 默认很可能携带官方默认模型名去请求而自定义 API 的调用名另有一套规范。应该先查平台的模型列表把规范调用名填进 Claude Code 的配置或环境变量不要沿用原来的模型名。模型名不匹配会直接返回 model not found跟密钥无关。自定义 API 的 base_url 需要带 /api/v1 吗需要。/api/v1是路由前缀少了它请求会打到错误路径通常返回 404。虽然文档站地址不带这个前缀但调用地址必须保留。两个地址用途不同别混用。流式输出末尾的 usage 片段能丢掉吗不能丢。这个片段不包含正文内容但携带用量信息。客户端不能只依赖data: [DONE]当作结束应该以流结束为准。处理时可以跳过空choices但要等迭代真正结束否则本轮 token 统计会缺尾部。以上示例在千木的 OpenAI 兼容端点上验证模型调用名为 minimax-m2.5。开发者文档可查模型调用名与错误码。