最近总有人拿着同一类报错来找我unexpected status 401 unauthorized: incorrect api key provided。一看就是 Codex 或者 Claude Code 想接第三方兼容 API结果 Key 没配对或者压根不知道 Key 该往哪放。Codex 默认连 OpenAIClaude Code 默认连 Anthropic但很多人实际想接的是 DeepSeek、智谱、通义这类兼容接口甚至本地模型服务。这篇文章就把两个 CLI 接入兼容 API 的完整配置流程讲清楚重点解决一个核心矛盾怎么在灵活换 API 的同时不把 Key 搞丢、搞错、搞泄露。适合刚接触终端 AI 工具的新手也适合在团队里负责统一配置的开发者参考。1. 为什么 Codex 和 Claude Code 需要“换接口”而不是“换工具”1.1 官方工具默认连接的是自家服务Codex CLI 出自 OpenAI设计时默认把请求发到 OpenAI 的接口。Claude Code 出自 Anthropic默认把请求发到 Anthropic 的接口。这两个工具在官方模型上表现确实不错但不代表它们只能连自家服务。很多模型服务商都提供了协议兼容的 HTTP 接口有的完全兼容 OpenAI 的 Chat Completions / Responses 协议有的兼容 Anthropic Messages 协议。CLI 本身不认识“这是哪家公司”它只认环境变量里给的地址和凭证。这就是“接入兼容 API”的本质。你不需要改 Codex 或 Claude Code 的源码也不用换一个第三方封装工具只要把请求的 base URL 指到目标服务商的地址把 Key 配成目标服务商的 KeyCLI 就会乖乖把请求发过去。就像同一辆配送车默认只知道去 A 仓库取货你把导航地址改成 B 仓库它就能从 B 仓库取到货。车不关心仓库是谁家的只看地址是否正确、钥匙能不能开门。1.2 兼容 API 的核心base URL、模型名、Key 三者匹配很多人配置失败不是不会写环境变量而是没搞懂这三者必须同时匹配。base URL 决定了请求发到哪Key 决定了服务商认不认你模型名决定了对方拿什么模型来响应。换一家服务商这三个值基本都要换一遍。举个例子Codex 默认用 OpenAI 官方接口时base URL 是https://api.openai.com/v1模型名可能是gpt-5或gpt-5-codex。如果你想接 DeepSeekbase URL 要改成https://api.deepseek.com/v1Key 换成 DeepSeek 的 Key模型名改成deepseek-chat或服务商文档里列出的型号。三者只要有一个不匹配就会报 401 或 400而且报错信息往往长得一模一样容易让人误以为是工具坏了。Claude Code 同理。官方默认走 Anthropic 的 APIbase URL 是https://api.anthropic.comKey 是 Anthropic 平台的 Key。接到兼容服务时需要设置ANTHROPIC_BASE_URL指向服务商提供的 Anthropic 兼容地址同时把ANTHROPIC_AUTH_TOKEN或ANTHROPIC_API_KEY换成对应服务的凭证。注意不同服务商支持的协议版本不一样有的只支持 OpenAI 协议那就得配合能做协议转换的本地服务或者用服务商明确说明支持 Anthropic 协议的端点别硬套。2. 动手前的准备环境变量、API Key 和配置文件2.1 三个必须搞懂的概念配置之前先花一分钟把三个概念对齐避免后面反复踩坑。API Key 是服务商发你的身份凭证通常是一串以sk-开头的字符串。它的作用是让服务端确认“你是谁”“你有没有额度”。Key 一旦泄露别人就能用你的余额调用模型账单可能一夜之间飙高。所以任何教程里让你把 Key 写进配置文件并提交到代码仓库的行为都是错误的。Base URL 是接口地址的前缀。HTTP 客户端会把这个地址和具体的路径拼在一起组成完整的请求地址。比如 base URL 是https://api.deepseek.com/v1Codex 请求时会拼出https://api.deepseek.com/v1/responses。如果服务商文档写的是https://api.deepseek.com不带/v1你需要确认该服务是否要求带版本前缀不同服务差别很大。模型名是请求体里的model字段。它必须和服务商平台上实际存在的模型 ID 完全一致多一个字符、少一个字符都会报model not found或model is not supported。有些服务商提供别名比如deepseek-chat可能动态指向最新版对话模型配置前先去服务商文档确认当前推荐填什么。2.2 为什么 Key 不能写死在配置文件里最常见的低级错误是把 Key 直接写进~/.codex/config.toml或~/.claude/settings.json然后整个目录被同步到网盘或者项目仓库被 push 到远端。Key 一旦进了 Git 历史就算后来删掉也能从提交记录里翻出来。正确的思路是配置文件只放模型名、温度、输出风格等非敏感参数Key 一律通过环境变量注入。CLI 工具在读取配置时都会优先看环境变量。Codex 支持在[model_providers.xxx]里指定env_key意思是“这个提供商的 Key 从哪个环境变量读”。Claude Code 也支持通过ANTHROPIC_AUTH_TOKEN等环境变量传入凭据。用这种方式配置文件即使被同步、被截图、被分享里面也没有任何秘密真正做到了“配置公开、Key 私有”。2.3 本地目录和权限的干净方案开始之前我建议在项目根目录建一个.env文件用来集中存放环境变量。.env的格式很简单DEEPSEEK_API_KEYsk-你的key OPENAI_API_KEYsk-你的key ANTHROPIC_AUTH_TOKEN你的token然后立刻执行两步操作。第一步在.gitignore里加入.env确保它不会被提交第二步执行chmod 600 .env把文件权限改成只有当前用户可读写。这样别人即使能登录你的机器也需要更高权限才能看到 Key。同时检查一下 Codex 和 Claude Code 的配置文件权限。~/.codex/config.toml、~/.claude/settings.json这些文件如果存了敏感信息也建议chmod 600。目录权限可以保留默认但文件权限收紧没坏处。3. Codex 接入兼容 API以 DeepSeek 和智谱为例3.1 安装 Codex 并定位配置文件Codex 官方提供了多种安装方式最简单的是通过 npm 安装npm install -g openai/codex安装完成后运行codex --version确认版本。首次运行codex会在用户目录生成配置文件Linux/macOS 通常是~/.codex/config.tomlWindows 在%USERPROFILE%\.codex\config.toml。如果之前已经用过官方配置先打开现有文件看一眼cat ~/.codex/config.toml你会看到类似这样的内容model gpt-5-codex这时候不要急着改先备份一份后面接第三方服务时大概率要改model和model_provider两处。3.2 配置 DeepSeek一个可以直接抄的模板DeepSeek 提供了 OpenAI 兼容接口所以 Codex 可以直接接。打开~/.codex/config.toml把内容改成下面这样model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY解释一下每个字段model_provider是给当前会话指定用哪一套提供商配置名字要和下面[model_providers.deepseek]里的 key 对应。base_url是 DeepSeek 文档要求的接口前缀一定带/v1。env_key告诉 Codex去环境变量里找DEEPSEEK_API_KEY这个变量当作 Key而不是从配置文件读取。保存文件后在终端导出 Keyexport DEEPSEEK_API_KEYsk-xxx codex这时 Codex 会把请求发到 DeepSeek模型名填deepseek-chat。如果 DeepSeek 平台更新了模型列表可以把model改成文档里的其他型号比如deepseek-reasoner。只要env_key对应的环境变量里有值Codex 就不会要求你登录 OpenAI 账号。3.3 接入智谱 GLM 的配置示例智谱的 OpenAI 兼容地址和 DeepSeek 不一样base URL 是https://open.bigmodel.cn/api/paas/v4。配置文件可以写成model glm-4.5 model_provider zhipu [model_providers.zhipu] name Zhipu base_url https://open.bigmodel.cn/api/paas/v4 env_key ZHIPU_API_KEY然后执行export ZHIPU_API_KEYsk-xxx codex注意智谱的模型名要按你在智谱开放平台上开通的模型 ID 来填不同时间段平台主推的型号可能不同。如果你在平台看到的是glm-4.5或glm-4.5-air直接抄导航里的模型字符串就行。3.4 从 .env 文件加载 Key避免每次手敲每次打开终端都手动export很烦也容易把 Key 留在 shell 历史里。我的做法是在项目根目录放一个启动脚本比如run-codex.sh#!/usr/bin/env bash set -a source .env set a exec codex $先执行chmod x run-codex.sh以后每次启动就运行./run-codex.sh。脚本里的set -a表示后面 source 进来的变量都自动导出到环境变量exec codex $直接替换当前进程启动 Codex。这样 Key 只存在于.env文件里不会出现在命令历史中。如果你不想用脚本也可以在 shell 配置文件比如~/.bashrc或~/.zshrc里加一行source ~/.env但这样所有终端会话都会加载这些变量安全性不如按项目加载来得干净。按项目加载最大的好处是不同项目可以用不同的 Key 和不同的模型服务互不污染。4. Claude Code 接入兼容 APIANTHROPIC_BASE_URL 实操记录4.1 用环境变量切换接口地址Claude Code 原本默认走 Anthropic 官方 API读取的是ANTHROPIC_API_KEY。接入兼容服务时最核心的环境变量是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。假设你有一个兼容 Anthropic 协议的服务端点地址是https://api.example.com/anthropic可以在终端这样设置export ANTHROPIC_BASE_URLhttps://api.example.com/anthropic export ANTHROPIC_AUTH_TOKENyour-token claudeANTHROPIC_AUTH_TOKEN会作为 Bearer token 跟随请求发送兼容服务一般认这个字段。如果你同时设置了ANTHROPIC_API_KEY两个变量同时存在时可能造成混淆建议只保留ANTHROPIC_AUTH_TOKEN一种。进入 Claude Code 后直接问一个问题如果返回正常说明接口已经通了。需要注意不是所有兼容服务都实现了 Anthropic Messages 协议。如果你的目标服务商只提供 OpenAI 兼容端点Claude Code 可能没法直接接。这种场景需要查一下服务商文档看他们是否提供 Anthropic 兼容入口或者用本地能跑模型服务的工具做一次协议转换但那就是另一套方案了。4.2 模型名与上下文长度的坑Claude Code 接入兼容 API 后最常见的两个报错都和模型参数有关。第一个是400 this models maximum context length is 1048576 tokens。这个报错的意思是你请求的模型上下文窗口确实很大比如 1M tokens但当前会话里的内容已经超过了模型能接受的实际长度。原因通常是 Claude Code 扫描了项目目录把大量文件内容都塞进了上下文或者你在会话里贴了超长文本。解决办法是新开会话减少/add的文件数量或者在设置里限制 Claude Code 读取目录的范围别让它递归扫描整个仓库。第二个是model is not supported或the xxx model is not supported when using codex with a ...。这表示你填的模型名在当前服务端不存在或者该模型不允许通过 API 调用。处理方式是去服务商文档确认正确的模型 ID然后通过环境变量重新指定模型名。比如某些兼容服务要求设置ANTHROPIC_MODEL不同版本名称不一样别想当然地填claude-opus-4之类的官方名。4.3 官方订阅限制提示怎么处理有些人在配置兼容 API 时会遇到这样的提示your organization has disabled claude subscription access for claude code。这个报错其实是官方订阅层面的限制说明你的终端环境还在尝试使用 Anthropic 官方登录态或者组织管理员在后台关闭了 Claude Code 的订阅访问。处理思路分两步。第一步检查ANTHROPIC_BASE_URL是否真的生效了运行printenv ANTHROPIC_BASE_URL看输出如果没有输出说明变量没加载重新设置后再启动。第二步如果环境变量已经设置但还报这个错可能是~/.claude目录下残留了官方登录凭证。备份好这个目录后临时移走它再重新启动 Claude Code让程序走环境变量配置的接口。问题解决后再把备份里的非敏感配置放回来。这个报错通常和兼容 API 本身无关问题出在“程序还在走官方认证路径”。5. 常见报错速查与排查思路5.1 401 UnauthorizedKey 不对还是变量没加载看热词就知道unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****是出现频率最高的报错。它表示服务器收到了请求但认为 Key 无效。具体原因可能是复制 Key 时多复制了空格、换行或者漏了最后几位。Key 本身是 A 服务商的但你请求的 base URL 是 B 服务商的服务商验票自然失败。环境变量没加载CLI 读取到了一个空字符串或旧值。服务商后台把 Key 禁用了或账户余额耗尽。排查步骤很直接。先用printenv确认变量printenv DEEPSEEK_API_KEY printenv ANTHROPIC_AUTH_TOKEN如果变量为空说明.env没有 source 成功。然后再用 curl 直接测试目标接口比如curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer $DEEPSEEK_API_KEY如果 curl 返回 200 和模型列表说明 Key 没问题问题出在 CLI 配置。如果 curl 也返回 401那就是 Key 本身有问题直接去服务商后台重新生成一个新的。5.2 400 context length exceeded上下文超长这类报错的完整信息往往是api error: 400 this models maximum context length is 1048576 tokens. however...。看到这个不要慌你的 Key 和模型都是好的只是输入内容超过了模型窗口。说直白点就是“这次请求带的材料太多桌子放不下了”。处理办法可以参考第 4.2 节新开会话、减少文件加载、手动清理上下文。Codex 里可以用/compact之类命令压缩上下文Claude Code 也可以新开会话。如果这个问题反复出现就检查是不是设置了自动读取整个项目目录的规则把它改成只读取必要文件。5.3 model not supported 和 organization disabled热词里还有两条很有意思一条是the gpt-5.6-sol model is not supported when using codex with a...另一条是this organization has been disabled。第一条说明你填的模型名在服务端不存在或者当前接口不允许调用该模型。不要看到gpt-开头就觉得是官方模型兼容服务里同样可能返回这个错。你需要去服务商文档找到它实际支持的模型 ID。第二条说明账号本身被运营商停用大概率是欠费、违规或触发风控跟配置无关去服务商后台处理就好。5.4 环境变量没生效变量明明设了却没用一个非常隐蔽的问题是你在当前终端里刚 export 了变量然后又用sudo codex启动sudo 会切换用户环境变量自然丢了。另一个常见问题是修改.env后没有重新 source只改了文件内容当前 shell 里拿到的还是旧值。启动前先执行printenv OPENAI_BASE_URL确认无误。Claude Code 和 Codex 都支持调试模式比如claude --debug或codex --debug启动时会把请求的 URL 打印出来。看到打印出的地址和你预期不一致立刻停下来检查环境变量优先级。有些系统级的 shell 配置可能会覆盖你的临时变量。6. 不泄露 Key 的落地细节从本地到团队协作6.1 .gitignore 和文件权限挡住第一层风险不管你是个人项目还是团队仓库.gitignore里至少要有这些内容.env *.env !*.env.example.env是真实密钥文件.env.example是模板里面的变量值用your-key占位。每次改动后跑一下git check-ignore .env如果输出.env说明 Git 已经忽略它了。如果输出为空说明忽略规则没生效检查.gitignore是否放在仓库根目录。文件权限层面执行chmod 600 .env ~/.codex/config.toml ~/.claude/settings.json这样其他系统用户无法读取这些文件。如果之前不小心把 Key 提交到了 Git不要只删文件正确的做法是立即去服务商后台作废旧 Key生成新的替换然后再用git filter-repo之类的工具清理历史。记住历史里的 Key 永远算泄露。6.2 用系统密钥管理器或统一 .env 管理对绝大多数个人开发者来说一个权限为 600 的~/.env文件已经足够安全。每次打开终端需要加载时在 shell 配置里加一行source ~/.env即可。但要注意这样会把所有 Key 加载到全局环境每次启动任何程序都会继承这些变量安全性中等偏上。如果你更讲究一点可以用操作系统的钥匙串。macOS 上可以用security add-generic-password把 Key 存进钥匙串调用时再读出来Linux 可以用pass管理。但我的观点是不要为了“看起来很安全”搞出太复杂的流程否则你很快就会嫌麻烦绕回到硬编码的老路。先用.env 权限 600 养成习惯再逐步升级到密钥管理工具。6.3 日志脱敏和命令历史清理很多人在调试时把完整请求头贴到群里里面有Authorization: Bearer sk-xxx。这就是白送 Key。请记住三点第一不要直接在终端手敲export DEEPSEEK_API_KEYsk-xxx然后再跑命令因为命令历史会记录完整的 Key。如果已经敲过立刻执行history -d 行号删掉或者直接用unset清掉当前变量再离开。第二任何包含请求头的调试日志粘贴前先把 Key 替换成sk-***。第三如果你用 CI 系统不要在 CI 日志里打印环境变量设置里把日志脱敏打开。6.4 团队协作时怎么分发配置团队场景下最忌讳的是把真实 Key 写进共享文档、群公告或者钉钉笔记。推荐做法是仓库里放.env.example只写变量名不写值。真实 Key 通过内部密钥管理平台比如 Vault、1Password Teams按成员分发。CI 流水线的 Key 配置在 CI 系统的 Secrets 里不要写进.yml配置文件。每个成员本地维护自己的.env由.gitignore保证不提交。这样即使某个成员离职只需要吊销他持有的 Key不影响其他人。如果之前大家共用一个 Key离职时就必须全员换 Key非常被动。最后再分享一个我常用的调试技巧拿到任何新服务商先别直接配 CLI。用 curl 把目标接口的models列表拉出来确认 Key 有效再复制一个模型 ID 填到配置里。请求通了再进 Codex 或 Claude Code 做验证。这样能把“配置问题”和“服务商问题”快速分开省下的时间足够多喝两杯水。