Codex 和 Claude Code 这两个终端 AI 编程工具现在几乎是很多开发者工作流里离不开的东西了。但有个现实问题官方订阅要么有地域限制要么配额不够用要么公司账号权限管控严格于是大家纷纷转向兼容 API——把 DeepSeek、智谱、本地模型这类第三方服务接到 Codex 和 Claude Code 上跑。这个方向本身没问题问题出在配置方式上。我见过太多人图省事把sk-开头的 Key 直接写死在配置文件里然后又把配置文件提交到了 git 仓库或者截图发群里问为什么报 401。这篇就把两件事讲透怎么把 Codex 和 Claude Code 正确接入各类兼容 API以及怎么全程保证 Key 不泄露。无论你是第一次配环境还是已经被各种报错折磨了一下午按这篇的思路走一遍基本能解决 80% 的问题。1. 为什么兼容 API 会成为刚需以及 90% 的 Key 泄露都发生在哪里1.1 订阅、配额与端点限制的夹缝先说动机。Codex 和 Claude Code 官方都要求订阅或按量付费但很多团队的实际情况是不想给每个人开订阅、海外支付流程麻烦、或者公司安全制度要求数据不能出域。于是兼容 API就成了最自然的替代方案——这些工具本身设计上就允许开发者覆盖默认的 API 端点和模型供应商只要你理解它们的配置机制。以 Codex 为例它底层的模型调用本质上就是一个 HTTP 客户端。你告诉它去哪个 URL、带什么 Key、用什么协议格式它就能用第三方模型跑起来。Claude Code 也一样通过ANTHROPIC_BASE_URL这个环境变量替换掉官方端点指向任意兼容 Anthropic 协议的服务即可。灵活是真灵活坑也真坑——配置项暴露面越大Key 泄露的风险就越高。1.2 Key 泄露的真实渠道不是黑客而是你自己的习惯大多数 Key 泄露和黑客攻击没半点关系。根据我在项目群里观察到的案例泄露基本发生在这几个环节把api_key sk-xxx直接写进config.toml然后整个目录被 git 跟踪为了调试在终端里执行export OPENAI_API_KEYsk-xxx随后 Key 留在 shell history 文件中配置界面截图发到群里求助截图里的 Key 是完整可见的把.env文件放在项目目录里但.gitignore没写好提交时被一起推上去。你可能觉得这些都属于低级错误但实际情况是这些恰恰是顺手操作里最容易发生的。后面每个配置环节我都会重点标注这步会触发哪些泄露风险以及对应的规避方式。2. 配置前必须搞明白Codex 和 Claude Code 各自读取配置的机制很多人配置失败不是因为 Key 有问题而是没搞清楚这两个工具到底从哪里读配置。它们都支持配置文件 环境变量的双通道但优先级和写法完全不同。2.1 Codex CLI 的配置链config.toml 与环境变量Codex CLI 的主配置文件在~/.codex/config.toml。官方支持的配置方式有两种用codex login走 OAuth 流程登录凭证写入~/.codex/auth.json用环境变量直接提供 API Key同时在config.toml里声明自定义 provider。重点说 provider 的写法。下面是一个典型的自定义供应商配置model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat关键点在于env_key这个字段。它表示从环境变量DEEPSEEK_API_KEY读取 Key 值配置文件里只存变量名不存 Key 本身。这是 Codex 官方推荐的做法也是不泄露 Key 的基础前提。同理用 OpenAI 官方 Key 时设置OPENAI_API_KEY环境变量即可Codex CLI 会自动使用。2.2 Claude Code 的配置链settings.json 与 ANTHROPIC 系列环境变量Claude Code 的配置读取路径更环境变量导向。它认这几个变量环境变量作用ANTHROPIC_API_KEYAnthropic 官方 Key登录时使用ANTHROPIC_AUTH_TOKEN非交互式认证 Token优先级高于上面的 KeyANTHROPIC_BASE_URL覆盖默认 API 端点接第三方服务时的核心开关ANTHROPIC_MODEL覆盖默认模型名ANTHROPIC_SMALL_FAST_MODEL设置后台轻量任务如标题生成使用的模型除了 shell 环境变量Claude Code 也会读~/.claude/settings.json里面可以配置env字段来注入环境变量{ env: { ANTHROPIC_BASE_URL: https://your-gateway.example.com, ANTHROPIC_AUTH_TOKEN: your-token } }注意写在这个文件的 Token 是明文落盘的。如果必须用 settings.json记得把文件权限收紧到 600并且绝对不要把这个文件纳入任何 git 仓库。更稳妥的做法是放到 shell profile 里 export或者用 direnv 做目录级注入。2.3 哪些配置项会明文落盘哪些不会对上表做个总结你就知道该把 Key 放哪了Codex 的config.toml通过env_key引用环境变量时文件里不出现 Key安全Codex 的auth.jsonOAuth 登录产物默认权限 600相对安全但别手动往里塞明文 KeyClaude Code 的settings.jsonenv字段里的 Key 是明文默认权限也可能偏松需要自己收紧Shell profile、.env文件属于环境变量注入只要.gitignore写对是最推荐的载体直接写进config.toml的api_key字段绝对不要这么做这相当于把 Key 贴在门口。3. 不泄露 Key 的三道防线环境变量、权限、gitignore安全问题单独开一章因为这是标题里最核心的诉求。我自己趟过的坑加上帮别人排查时看到的错误总结下来需要做三件事。3.1 环境变量的正确打开方式direnv 与 .env 本地化在 shell 里直接export是最简单的方式但会有两个问题一是 Key 进入 shell history二是一旦换终端、换项目就要重新导出。我的做法是配合 direnv 做目录级环境变量注入。在项目或者专门放配置的目录下建一个.envrc文件export DEEPSEEK_API_KEYsk-xxxxxxxx export ANTHROPIC_BASE_URLhttps://your-gateway.example.com export ANTHROPIC_AUTH_TOKENyour-token然后运行direnv allow。这样只有cd进这个目录时变量才会生效退出目录自动清空。.envrc本身要加入 gitignore。相比全局 export这种方式把暴露面控制在了最小范围。如果你不想装 direnv也可以用.env文件配合 shell 脚本手动加载set -a source .env set a但无论如何不要把.env提交到仓库。3.2 文件权限与 shell 历史的清理我见过不少开发者配置完一切正常结果过了几天发现 Key 被刷爆一查才知道是配置文件权限太宽被同机房的其他人顺手读了。这里有三步必须做对~/.codex/config.toml、~/.claude/settings.json这类含敏感信息的文件执行chmod 600对~/.codex/auth.json同样检查权限确认不是644如果已经执行过export OPENAI_API_KEYsk-xxx之类的命令用history -d 行号或history -c清理当前会话记录再检查~/.bash_history或~/.zsh_history把含 Key 的行删掉。这一步看着琐碎但确实能堵住绝大多数日常泄露风险。3.3 网关、子 Key 与额度上限最后一层保险就算上面全做了Key 还是可能从其他渠道泄露——电脑被植入后门、社交工程、或者你哪次不小心贴到了公共频道。所以理想的配置习惯是不要直接把主账号的 Key 配到工具里。更稳的做法是在中间加一层网关或直接使用子 Key。简单说OpenAI、DeepSeek、智谱等平台通常支持创建多个 API Key按项目分配一个独立 Key更进一步的方案是部署开源 API 网关相当于一个本地/自建的中转服务把各家供应商的 Key 集中管理在网关上Codex 和 Claude Code 只面向网关配置一个专属 Key在供应商后台给 Key 设置消费上限和 IP 白名单。这样即使某一个 Key 泄露损失也完全可控。网关方案后面的章节会展开讲。4. Codex 接入 DeepSeek 的完整步骤与 401 的排查链路4.1 config.toml 的最小可运行配置下面是我验证过可以跑的 Codex DeepSeek 最小配置。假设你已经在 DeepSeek 开放平台申请好了 Key。第一步设置环境变量export DEEPSEEK_API_KEYsk-your-deepseek-key第二步编辑~/.codex/config.tomlmodel deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat注意wire_api我写的是chat而不是responses。这是很多初次配置的人最容易踩的坑。Codex 官方默认走 OpenAI 的 Responses 协议但 DeepSeek 目前对外提供的是 Chat Completions 兼容接口。如果你不显式把wire_api改成chatCodex 会按照 Responses 的格式去请求 DeepSeek结果往往是请求发出去就直接报错或者收到无法解析的响应。第三步运行测试cd ~/your-project codex 你好请回复 OK如果这一步顺利过说明基础链路已经通了。接下来才是真正的战斗。4.2 401 报错逐项排查从 key 格式到 wire_api 不匹配先说最常见的报错。如果你看到unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****这个sk-svcac前缀有个明显特征——它是 Anthropic 控制台生成的 Key不是 DeepSeek 的。出现这个报错说明 Codex 拿到的 Key 根本不是 DeepSeek 平台的而是别的平台的。常见原因有几个环境变量名写错了比如配置里env_key DEEPSEEK_API_KEY但 shell 里 export 的是OPENAI_API_KEY多个环境变量冲突Codex 同时读到了OPENAI_API_KEY和DEEPSEEK_API_KEY而默认的OPENAI_API_KEY优先级被错误地处理了把 Anthropic 平台的 Key 复制到了 DeepSeek 的配置里。排查链路应该是这样的按顺序走运行echo $DEEPSEEK_API_KEY先确认 shell 里这个变量存在且不是空字符串检查env | grep -i api_key看看当前 shell 环境里有没有多个*_API_KEY变量同时存在确认 Key 前缀sk-开头的 Key 在不同平台含义完全不同直接在对应平台后台查看 Key 的归属用 curl 直接请求 DeepSeek 端点绕过 Codex 的配置层定位问题在Key 本身还是Codex 的请求格式curl https://api.deepseek.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d {model:deepseek-chat,messages:[{role:user,content:ping}]}如果 curl 返回正常的 JSON 响应说明 Key 和端点都没问题问题在 Codex 一侧的配置如果 curl 也返回 401那就去平台后台检查 Key 状态、余额、是否被禁用。4.3 400 上下文超限与模型名不可用的处理接入第三方模型后还常见两类 400 报错。一类是api error: 400 this models maximum context length is 1048576 tokens. However, your request ...这个报错字面意思是模型最大上下文是 1M tokens但你这次的请求超了。刚看到这个数字你会觉得离谱——谁会一次发 100 万 token 进去但实际上大部分情况是 Codex 把项目代码、历史会话、工具定义全部打包进了请求里。比如你在一个依赖很多的 monorepo 项目根目录直接运行 codex它扫描文件的时候会把一堆无关文件塞进上下文。处理方式在codex对话里用/compact压缩历史会话避免在过大的项目根目录直接启动用codex --exclude排除无关目录或进入子目录再运行在config.toml里显式设置model_max_tokens来主动限制请求长度。另一类是我在热搜词里看到的the gpt-5.6-sol model is not supported when using codex with a ...这种报错的本质是模型名写错了。你在config.toml里写的model字段必须同时满足两个条件一是你选的第三方平台确实提供了这个模型二是 Codex 对这个模型的支持逻辑存在。如果你顺手填了一个平台根本不存在的模型名Codex 会在请求阶段直接拒绝。解决办法就是去第三方平台的模型列表页确认准确的模型名然后写进配置。顺带提醒某些第三方供应商会提供模型别名服务让一个名字映射到多个模型这类别名在 Codex 里很容易触发不支持报错尽量写原始模型名。5. Claude Code 接入兼容 API从官端点迁移到三方端点的实操5.1 ANTHROPIC_BASE_URL 替换后的最小改动Claude Code 默认走 Anthropic 官方端点https://api.anthropic.com。要接第三方兼容服务核心动作就一个换掉ANTHROPIC_BASE_URL。比如你接了智谱开放平台提供的 Anthropic 兼容端点那么目录级.envrc里写export ANTHROPIC_BASE_URLhttps://open.bigmodel.cn/api/anthropic export ANTHROPIC_AUTH_TOKENyour-zhipu-api-key export ANTHROPIC_MODELglm-4.5然后重新打开终端进入项目目录运行claude。如果配置无误Claude Code 的界面会正常启动对话时请求会被转发到兼容端点。这个过程里有一件事容易忽略ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN同时存在时Claude Code 会优先用AUTH_TOKEN。所以如果你之前为官方账号配过ANTHROPIC_API_KEY现在接第三方服务只设置ANTHROPIC_AUTH_TOKEN还不够最好把旧的ANTHROPIC_API_KEY也一并清掉避免混淆。5.2 organization has disabled claude subscription access 怎么处理热搜词里有这样一条your organization has disabled claude subscription access for claude code这个报错的意思是你的账号或所在组织在 Anthropic 侧关闭了 Claude Code 的订阅访问权限。常见于企业订阅、组织管理员统一管控的场景。单靠改环境变量解决不了根本问题因为这是账号权限层面的限制。处理路径分两种如果你确实需要官方订阅服务联系组织管理员开启 Claude Code 的访问权限如果你只是想继续用 Claude Code 这个终端工具那正好——把ANTHROPIC_BASE_URL指向第三方兼容端点即可。请求不再打到 Anthropic 官方这个订阅限制自然不会触发。这也是很多团队去官方化的动力来源工具形态不变、使用习惯不变只是后端供应商换掉。5.3 一次真实的协议兼容坑位messages 与 responses 的区别Claude Code 原生走的是 Anthropic Messages API路径是/v1/messages请求体格式是anthropic-version头部加 messages 数组。而 OpenAI 兼容接口比如 DeepSeek、智谱的 OpenAI 端点走的是/v1/chat/completions请求体完全不同。所以如果你把ANTHROPIC_BASE_URL指到一个只提供 OpenAI 兼容接口的服务大概率会报协议错误。这就是为什么现在很多第三方平台会专门提供Anthropic 兼容端点——智谱开放平台的/api/anthropic路径就是这么来的。那如果你想接一个只提供 OpenAI 兼容端点的服务怎么办两条路换一个有 Anthropic 兼容层的供应商在本地跑一个协议转换代理把 Anthropic 的 Messages 请求转成 OpenAI 的 Chat Completions 格式再把响应转回去。协议转换层的配置也不算复杂社区里有现成方案。核心就是把ANTHROPIC_BASE_URL指向http://localhost:本地端口由这个本地服务完成协议转换。后面讲本地模型接入时还会再提到。6. 本地模型的接入LM Studio / Ollama 与协议转换层6.1 Codex 直连本地 OpenAI 兼容端点本地模型场景这两年很火最常见的诉求是不想把代码发给云端我想用本地模型跑 Codex。LM Studio 启动后会在本地开一个 OpenAI 兼容端点默认是http://localhost:1234/v1。Codex 接入它的配置非常简单model local-model-name model_provider lmstudio [model_providers.lmstudio] name LM Studio base_url http://localhost:1234/v1 env_key LMSTUDIO_API_KEY wire_api chat注意LM Studio 默认不校验 Key但请求头里必须带一个非空的 Authorization 值。所以你还需要export LMSTUDIO_API_KEYsk-local-dev这里有个很多人会忽略的点wire_api还是得写chat。因为 LM Studio 提供的是 Chat Completions 兼容接口不是 Responses 接口。用responses的话Codex 会往/v1/responses发请求绝大多数本地推理引擎都没有实现这个路径。Ollama 同理它的默认端点是http://localhost:11434/v1同样支持 OpenAI 兼容协议Codex 的配置方式几乎一模一样只需要换掉base_url。我在实际操作中发现本地模型接入最大的瓶颈不是配置而是模型能力和上下文长度。比如我对接 32B 模型跑 Codex小任务没问题一旦让它修改一个大型多文件项目本地推理速度会明显拖慢上下文窗口也容易被塞满。如果你是为了隐私完全本地化那这是必经之路如果只是图省钱反而建议先用云端便宜模型。6.2 Claude Code 接本地模型需要解决的协议问题Claude Code 接本地模型的难度比 Codex 高一个数量级。核心原因我在前面说过Claude Code 只认 Anthropic 的/v1/messages协议而 LM Studio、Ollama 默认只提供 OpenAI 兼容端点。直接改ANTHROPIC_BASE_URL指向 LM Studio 是不够的请求会因协议不匹配而失败。你需要一个翻译层。社区里的常见做法是跑一个本地代理进程这个进程对外暴露 Anthropic 兼容端点对内把请求转发给 LM Studio 或 Ollama。配置链路长这样启动本地代理监听http://localhost:8080在代理配置里把上游指向 LM Studio 的http://localhost:1234/v1Claude Code 设置ANTHROPIC_BASE_URLhttp://localhost:8080ANTHROPIC_AUTH_TOKEN随便填一个非空值启动claude验证对话是否正常。这层代理大多数时候是稳定的但我在切换模型时会碰到一个问题不同模型对工具调用function calling的支持程度不一致。Claude Code 重度依赖工具调用如果本地模型不支持或者支持得不好你会发现它在对话里频繁想调用工具但调用失败。遇到这种情况多半不是配置问题而是模型能力天花板只能换一个工具调用能力更好的模型。7. 高频报错对照表与可复现的排查路径把热搜词里出现的报错和应对方式整理成一张表方便你快速定位。这里面的报错我在不同项目里基本都遇到过。报错信息根因处理建议unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****Key 无效/过期或 Key 类型与端点不匹配去对应平台后台确认 Key 状态用 curl 单独验证端点cc switch local proxy failed while handling codex endpoint /responses本地代理无法处理/responses路径检查代理进程、端口和版本确认 Codex 用的是wire_api chatllm-deepseek: no api key for provider route deepseek-official第三方客户端的 provider 路由没有配置 Key在对应工具的供应商配置里补上 DeepSeek 的 apiKey 或环境变量引用your organization has disabled claude subscription access for claude code组织侧关闭了官方订阅访问联系管理员或改用第三方端点绕过官方订阅链路api error: 400 this models maximum context length is 1048576 tokens单次请求超长常见于项目文件被集体打包进上下文/compact压缩历史进入子目录运行限制model_max_tokensthe gpt-5.6-sol model is not supported配置了平台不存在的模型名去供应商模型列表确认准确的模型 IDpublic key retrieval is not allowedSSH 服务端或代理配置限制公开密钥获取检查 SSH config 与代理改用 HTTPS 认证方式Anthropic API key expired官方订阅过期更新ANTHROPIC_API_KEY或改用ANTHROPIC_AUTH_TOKEN7.1 一个完整排查链路示例从报错到修复为了避免给了结论但不知道过程这里展开一个实际排查链路。假设你遇到的就是第一个报错unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****排查步骤先判断槽位。sk-svcac前缀强烈指向 Anthropic 平台生成的 Key。如果这个 Key 是你从 Anthropic 控制台复制的那就不该用在一个 DeepSeek 端点的配置里。检查 Codex 的config.toml看model_provider指向的 provider 里base_url是不是 DeepSeekenv_key是不是DEEPSEEK_API_KEY。回到终端执行echo $DEEPSEEK_API_KEY | cut -c1-10看看实际注入的 Key 前缀是什么。如果显示sk-svcac说明环境变量里存的是 Anthropic 的 Key。去 DeepSeek 开放平台重新生成 Key复制到.envrc或 shell profile 里重新加载环境变量。再用 curl 验证一次 DeepSeek 端点确认返回正常 JSON。重新启动 Codex这次如果还报 401就要考虑是不是 Codex 缓存了旧的配置。退出终端、重开一个新会话再试。整个链路走下来绝大多数 401 都是Key 和端点不匹配或者环境变量没加载导致的真正平台侧 Key 失效的情况反而是少数。7.2 本地代理失败的场景还原再看cc switch local proxy failed while handling codex endpoint /responses这条。这个报错常见于 Claude Code 通过某种桥接方式切换到 Codex 后端中间夹了一个本地代理服务。报错信息里的/responses是个关键线索——它说明代理收到了针对 Codex或 OpenAI 兼容协议的/responses请求但处理失败。按我的经验优先查三件事代理进程是不是活着端口能不能通curl http://localhost:你配置的端口/代理版本是不是过旧不支持 Responses 协议。如果代理只实现了 Chat Completions 协议那么任何发往/responses的请求都会失败代理和目标上游比如 DeepSeek的协议映射是否正确尤其检查它出站时是否把/responses正确转换成了/chat/completions。如果是代理不支持 Responses 协议解决办法有两个升级代理版本或者把 Codex 的wire_api改成chat让请求走/chat/completions绕开/responses。后者是更轻量的方案大部分兼容场景下都能直接解掉。8. 进阶玩法统一网关集中管理多供应商 Key8.1 网关模式的架构与收益当你同时使用 DeepSeek、智谱、本地模型甚至还要给团队多人分配额度时每个工具单独配置 Key 的方式就撑不住了。这时候值得引入API 网关模式。架构上非常简单中间架一个网关服务自建或者用开源方案各家供应商的真实 Key 只保存在网关里网关对外暴露一个统一的 OpenAI 或 Anthropic 兼容端点Codex 和 Claude Code 只配置网关地址 网关签发的 Key。收益很明显客户端层面完全不接触供应商真实 Key即使某台机器被入侵泄露的也只是网关的子 Key可以按项目、按人分配不同 Key在网关侧做额度限制、审计日志、禁用操作切换供应商时不用动客户端配置只改网关的路由规则。我在团队里就是这么用的。每个成员拿到的是一个独立的子 Key后台能看到每个 Key 的调用量和费用分布。之前那种谁的 Key 超了说不清的情况基本消失。8.2 个人项目中的落地建议如果你只是个人使用网关方案听起来有点重但实际上轻量自建也花不了多少时间。一个简单的网关只要做到转发 鉴权 限额三件事就够了。我的建议是如果你只在本机用、只接一家供应商不需要网关做好环境变量和权限就已经及格如果你要接两三家供应商并且会在不同项目里切换上目录级环境变量管理配合 direnv 就够了如果你有共享开发机、或者要帮同事配置建议上网关把真实 Key 收回到自己手里其他人只拿到一个子 Key。有一点实践经验供参考网关地址一定要选在你信任的、有访问控制的环境里部署。如果只是为了省钱把网关部署在一台没有防火墙的机器上那相当于把钥匙放在门口反而比直接配供应商 Key 更不安全。最后说几句实在的配置兼容 API 这件事技术难度真不高核心就是把Key 放哪里这个问题想清楚。我见过太多人配置本身是成功的但 Key 在半路就漏了。从实践角度看最值得养成的三个习惯第一所有 Key 一律走环境变量绝不写进配置文件第二给配置目录层层收紧权限第三能用子 Key 就不用主 Key能用网关就不用裸 Key。做到这三点你基本就告别Key 泄露这个烦恼了。另外一个小技巧每次配置完用curl单独验证一次端点再启动工具能帮你把配置问题和Key 问题快速分隔开排查效率能提升一大截。