企业官网建设流程全解析

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_KEY=sk-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 的配置读取路径更"环境变量导向"。它认这几个变量：

除了 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.json：OAuth 登录产物，默认权限 600，相对安全，但别手动往里塞明文 Key；
• Claude Code 的settings.json：env字段里的 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_KEY="sk-xxxxxxxx" export ANTHROPIC_BASE_URL="https://your-gateway.example.com" export ANTHROPIC_AUTH_TOKEN="your-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_KEY=sk-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_KEY="sk-your-deepseek-key"

第二步，编辑~/.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" wire_api = "chat"

注意wire_api我写的是"chat"而不是"responses"。这是很多初次配置的人最容易踩的坑。Codex 官方默认走 OpenAI 的 Responses 协议，但 DeepSeek 目前对外提供的是 Chat Completions 兼容接口。如果你不显式把wire_api改成"chat"，Codex 会按照 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 的配置里。

排查链路应该是这样的，按顺序走：

1. 运行echo $DEEPSEEK_API_KEY，先确认 shell 里这个变量存在且不是空字符串；
2. 检查env | grep -i api_key，看看当前 shell 环境里有没有多个*_API_KEY变量同时存在；
3. 确认 Key 前缀，sk-开头的 Key 在不同平台含义完全不同，直接在对应平台后台查看 Key 的归属；
4. 用 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 model's 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_URL="https://open.bigmodel.cn/api/anthropic" export ANTHROPIC_AUTH_TOKEN="your-zhipu-api-key" export ANTHROPIC_MODEL="glm-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_KEY="sk-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。配置链路长这样：

1. 启动本地代理，监听http://localhost:8080；
2. 在代理配置里把上游指向 LM Studio 的http://localhost:1234/v1；
3. Claude Code 设置ANTHROPIC_BASE_URL=http://localhost:8080，ANTHROPIC_AUTH_TOKEN随便填一个非空值；
4. 启动claude，验证对话是否正常。

这层代理大多数时候是稳定的，但我在切换模型时会碰到一个问题：不同模型对工具调用（function calling）的支持程度不一致。Claude Code 重度依赖工具调用，如果本地模型不支持或者支持得不好，你会发现它在对话里频繁"想调用工具但调用失败"。遇到这种情况，多半不是配置问题，而是模型能力天花板，只能换一个工具调用能力更好的模型。

7. 高频报错对照表与可复现的排查路径

把热搜词里出现的报错和应对方式整理成一张表，方便你快速定位。这里面的报错我在不同项目里基本都遇到过。

7.1 一个完整排查链路示例：从报错到修复

为了避免"给了结论但不知道过程"，这里展开一个实际排查链路。假设你遇到的就是第一个报错：

unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****

排查步骤：

1. 先判断槽位。sk-svcac前缀强烈指向 Anthropic 平台生成的 Key。如果这个 Key 是你从 Anthropic 控制台复制的，那就不该用在一个 DeepSeek 端点的配置里。
2. 检查 Codex 的config.toml，看model_provider指向的 provider 里base_url是不是 DeepSeek，env_key是不是DEEPSEEK_API_KEY。
3. 回到终端执行echo $DEEPSEEK_API_KEY | cut -c1-10，看看实际注入的 Key 前缀是什么。如果显示sk-svcac，说明环境变量里存的是 Anthropic 的 Key。
4. 去 DeepSeek 开放平台重新生成 Key，复制到.envrc或 shell profile 里，重新加载环境变量。
5. 再用 curl 验证一次 DeepSeek 端点，确认返回正常 JSON。
6. 重新启动 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. 进阶玩法：统一网关集中管理多供应商 Key

8.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 问题"快速分隔开，排查效率能提升一大截。