企业官网建设流程全解析

最近总有人拿着同一类报错来找我：unexpected status 401 unauthorized: incorrect api key provided。一看就是 Codex 或者 Claude Code 想接第三方兼容 API，结果 Key 没配对，或者压根不知道 Key 该往哪放。Codex 默认连 OpenAI，Claude 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 配成目标服务商的 Key，CLI 就会乖乖把请求发过去。就像同一辆配送车，默认只知道去 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。如果你想接 DeepSeek，base URL 要改成https://api.deepseek.com/v1，Key 换成 DeepSeek 的 Key，模型名改成deepseek-chat或服务商文档里列出的型号。三者只要有一个不匹配，就会报 401 或 400，而且报错信息往往长得一模一样，容易让人误以为是工具坏了。

Claude Code 同理。官方默认走 Anthropic 的 API，base URL 是https://api.anthropic.com，Key 是 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/v1，Codex 请求时会拼出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_KEY=sk-你的key OPENAI_API_KEY=sk-你的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.toml，Windows 在%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，而不是从配置文件读取。

保存文件后，在终端导出 Key：

export DEEPSEEK_API_KEY="sk-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_KEY="sk-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 接入兼容 API：ANTHROPIC_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_URL="https://api.example.com/anthropic" export ANTHROPIC_AUTH_TOKEN="your-token" claude

ANTHROPIC_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 model's 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 Unauthorized：Key 不对还是变量没加载？

看热词就知道，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 model's 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_KEY=sk-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 做验证。这样能把“配置问题”和“服务商问题”快速分开，省下的时间足够多喝两杯水。