2. 环境准备

2.1 安装 Codex CLI

Codex CLI 基于 Node.js 运行，推荐使用 npm 全局安装。安装前请确认本机已具备较新的 Node.js 环境（建议 Node 18 及以上）：

确认无误后执行：

安装完成后验证版本：

如果能正常打印出版本号，说明安装成功。如果你是 Homebrew 用户，也可以执行：

Windows 用户同样可以使用 npm 安装。若在 PowerShell 中遇到执行策略限制，可先运行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，或在安装后直接通过 npx @openai/codex 调用。

2.2 认识配置文件

Codex 的配置保存在以下位置（Linux / macOS）：

Windows 默认在：

如果文件不存在，直接创建即可。配置文件使用 TOML 格式，整体分为两大块：

• 顶层默认值：model、model_provider，决定 Codex 启动后默认使用哪个模型。
• 服务商定义区：[model_providers.xxx]，描述每个模型供应方的连接信息。

另外，Codex 还支持项目级配置与实验性功能开关，但在“接入自定义 API”这个主题下，我们只需要掌握上面的核心字段就足够了。

顺带说明：Codex 在启动时会按顺序查找配置，项目目录下的 .codex/config.toml 优先级高于用户主目录的全局配置。日常个人使用直接改 ~/.codex/config.toml 即可；团队项目若要强制指定某个模型，可以放在项目级配置中。

3. 配置文件结构解析

先看一份最小可用的 OpenAI 官方配置：

逐项说明：

其中最关键、也最容易搞错的是 wire_api：

• chat：兼容标准 OpenAI Chat Completions 接口，路径为 /v1/chat/completions。第三方模型、本地推理框架大多使用这个协议。
• responses：OpenAI 较新的 Responses API，功能更完整，能更好地支持 Codex 的 agent 能力（如工具调用、多轮状态管理）。目前只有 OpenAI 官方模型使用它最稳妥。

关键点：第三方服务几乎都选 wire_api = "chat"，只有 OpenAI 官方全家桶才用 responses。如果你把第三方模型误配成 responses，大概率会出现 404 或“接口不存在”的报错。

这里再强调一条容易被忽略的规则：base_url 的结尾是否带 /v1、是否多一个 /，都会影响最终请求地址。Codex 最终请求的完整 URL 大致是：

所以对 Chat Completions 服务来说，base_url 应以 /v1 收尾；如果服务商文档给的是 https://api.example.com/v1/chat/completions，配置时只截取前面的 https://api.example.com/v1。

4. 场景一：接入第三方云端 API

以 DeepSeek 为例，它的接口完全兼容 OpenAI Chat Completions。接入前需要先在 DeepSeek 开放平台创建 API Key，然后在 config.toml 中新增一个服务商：

然后在终端设置环境变量：

启动 Codex 后，它就会用 deepseek-chat 模型并通过 DeepSeek 的接口完成对话。验证是否生效，可以启动后输入：

这条命令会显示当前模型、服务商、Token 使用量等信息，方便快速确认配置是否命中。

同样的套路适用于其他兼容服务商：

接入步骤可以归纳为三板斧：

1. 到对应平台开通服务，创建 API Key。
2. 把服务商的 base_url 填入配置，wire_api 设为 chat。
3. 设置 env_key 对应的环境变量，并把想要使用的模型名写到顶层 model 字段。

注意：每家服务商的“模型名”并不通用。qwen-coder-plus 只有通义千问认识，glm-4-plus 只有智谱认识。填错模型名时，服务端通常会返回类似 “Model Not Exist” 或 400 错误。

5. 场景二：接入本地模型

本地模型适合对数据敏感或离线开发的场景，常见方案有 Ollama、LM Studio、vLLM。三者的共同点都是：在本机或内网服务器上启动一个 OpenAI 兼容的 HTTP 服务，然后让 Codex 指向 localhost。

接入本地模型时还有一点和云端不同：本地服务通常不需要真实 API Key。但 Codex 会校验 env_key 对应的环境变量是否存在，所以我们需要给一个占位值。

5.1 接入 Ollama

Ollama 是一个轻量的本地模型运行工具，安装后默认监听 http://localhost:11434，并提供了 OpenAI 兼容接口。接入前先启动 Ollama 并拉取模型：

拉取完成后可以先手动验证模型能不能跑：

然后添加配置：

注意：Ollama 本地服务不需要真实密钥，但 Codex 会校验 env_key 对应的环境变量是否存在，所以随便给个占位值即可：

小技巧：7B 模型对日常补全已经可用，但 Codex 的 agent 工作流会频繁调用工具、读取多文件上下文，显存允许的情况下建议优先使用 qwen2.5-coder:14b 或更大的模型，任务成功率会明显提升。

5.2 接入 LM Studio

LM Studio 是带图形界面的本地模型工具，适合喜欢可视化操作的用户。在 LM Studio 中下载模型后，进入 Local Server 页面点击 Start Server，默认 OpenAI 兼容地址是 http://localhost:1234/v1。配置方式与 Ollama 完全一致：

同样设置占位环境变量：

LM Studio 中加载的模型名会显示在 Server 页面上，model 字段要与之保持一致。如果加载的是 GGUF 量化模型，模型名可能带 -GGUF 之类的后缀，留意页面上显示的准确名称。

5.3 接入 vLLM

vLLM 是高吞吐量的推理引擎，通常部署在带 GPU 的 Linux 服务器上，适合生产环境或多人共用场景。启动时默认在 http://localhost:8000/v1 提供 OpenAI 兼容接口：

这里 --served-model-name 负责对外暴露的模型名，配置里的 model 要写这个对外名称，而不是 Hugging Face 仓库路径：

再设置占位环境变量即可：

如果 vLLM 部署在另一台内网机器上，把 localhost 换成对应的内网 IP 即可。多用户共用时建议统一维护这套配置，让每个人都通过同一入口访问。

6. 多服务商共存与模型切换

一个配置文件中可以同时定义多个服务商，方便快速切换。例如：

这份配置同时登记了 DeepSeek、Ollama 和 OpenAI 三家，顶层默认走 DeepSeek。真正使用时，我们不必每次都改配置文件，在 Codex 的交互式会话（TUI）中，输入以下命令即可动态切换模型：

如果切换的模型属于另一个服务商，可以加上服务商前缀来避免歧义。切回本地模型同理：

模型标识的完整格式可以理解为：

• 不带前缀时，Codex 默认在当前 model_provider 下查找模型。
• 带上 ollama/、deepseek/ 这类前缀时，则会到对应服务商中查找，跨服务商切换立刻生效。

实用建议：日常联网开发用云端模型，处理敏感代码或断网环境时用 /model ollama/... 一键切回本地，既省成本又兼顾隐私。

7. 环境变量与密钥安全

强烈建议不要把 API Key 直接写进 config.toml，而是通过环境变量注入。这样配置文件里只有变量名，没有真实密钥，即使把配置分享给同事或提交到 Git，也不会直接泄露凭证。

常用做法是把密钥写进 shell 配置文件：

修改后刷新配置：

如果你使用 fish，写入 ~/.config/fish/config.fish 后执行 source ~/.config/fish/config.fish 即可。

Windows 用户则可以通过系统环境变量设置，或使用 PowerShell 的 setx 永久写入：

设置完成后需要重开终端，新的环境变量才会注入到当前进程。

这样既能避免密钥随配置文件泄露（比如误提交到 Git），也方便在不同机器间复用同一份 config.toml：配置只管“结构”，密钥由每台机器各自持有。

提示：env_key 的值只是环境变量名，Codex 会根据这个名字去进程环境中查找真正的密钥。所以 env_key = "DEEPSEEK_API_KEY" 和 export DEEPSEEK_API_KEY=... 两处的变量名必须严格一致，包括大小写。

再补充两条安全习惯：

• 如果团队使用 Git 管理 dotfiles，确保 ~/.zshrc 不要被公开仓库收录，或把密钥单独放到 .env 文件并加入 .gitignore。
• 在公司服务器上运行时，不要用 echo 直接把密钥打到日志里；排查问题优先用 echo $VAR_NAME 只确认变量是否存在、是否为空。

8. 常见问题与排查

下面覆盖从“连不上”到“答得差”的常见问题，建议按顺序排查。

8.1 报错含义：API key not found

如果看到类似 no API key found for provider 的提示，说明 env_key 指定的环境变量没有设置。检查当前 shell：

为空的话，补齐环境变量并重启 Codex。需要留意的是：环境变量是在进程启动时读取的，修改 ~/.zshrc 后没有 source、或者没有重开终端，新变量不会生效。

8.2 返回 404 或接口不兼容

先确认 base_url 是否以 /v1 结尾，并用 curl 手动验证连通性：

能返回模型列表，说明接口可用。如果服务端只兼容 Chat Completions，记得把 wire_api 改为 chat。

排查顺序建议：

1. 检查 base_url 是不是多了或少了 /v1。
2. 确认 wire_api 与目标服务匹配（第三方用 chat）。
3. 用上面的 curl 命令独立验证，排除 Codex 配置之外的网络问题。

8.3 返回 401 或 403

401/403 通常是鉴权失败，而不是接口找不到。可能原因：

• 环境变量名与 env_key 不一致（例如配置里是 DEEPSEEK_API_KEY，实际 export 的是 DEEPSEEK_KEY）。
• API Key 本身失效、被禁用或额度用尽。
• 认证头格式问题，这通常由服务商兼容性导致，优先确认模型确实支持 OpenAI 规范。

可以先复现一下带鉴权的请求：

如果这里也返回 401，说明问题在密钥本身；如果这里正常而 Codex 报错，再回头检查 env_key 拼写。

8.4 本地模型连接失败

本地服务走 HTTP，确认服务已启动且监听地址正确：

同时留意防火墙、容器端口映射等因素，必要时把 localhost 换成实际 IP。

另一个常见坑是“本地服务启动了，但进程的监听地址不是你以为的那个”。可以确认：

如果服务跑在 Docker 里，记得用 -p 做端口映射，例如：

8.5 模型输出质量差或不支持工具调用

Codex 依赖模型具备一定的**工具调用（function calling）**能力。部分开源小模型对工具调用支持不完整，可能导致编辑、执行命令等环节异常。建议优先选择专门针对编码和 Agent 场景优化的模型，例如 qwen2.5-coder、deepseek-chat 等。

如果模型经常“答非所问”或无法正确调用工具，可以依次尝试：

• 更换为支持 function calling 的模型，并确认推理框架开启了工具调用能力。
• 检查上下文长度设置，过小的上下文会被截断，导致模型“失忆”。
• 减少单次任务复杂度，把大任务拆成小步骤。

8.6 请求超时或连接被重置

遇到超时，可以看看是否走了系统代理。很多国内开发者会开启 HTTP 代理访问海外服务，但接入本地 Ollama、LM Studio 时，这个代理反而会拦截 localhost 请求。一般需要把 localhost、127.0.0.1 加入代理例外列表：

如果目标是内网服务器，也建议把对应 IP 或域名加入 NO_PROXY。

9. 接入流程总览

为了更直观地梳理整个过程，可以把“从零到一接入自定义模型”抽象成下面的流程：

无论走云端还是本地，核心判断都在“服务端是否提供 OpenAI 兼容接口”，剩下的只是把地址、密钥和协议三个参数填对。

10. 总结

Codex CLI 自定义 API 的核心就在 config.toml 的 [model_providers] 段落：只要服务端提供 OpenAI 兼容接口，配置好 base_url、env_key 和 wire_api 就能接入。

回顾一下关键步骤：

1. 安装 Codex CLI，并用 codex --version 验证。
2. 在 ~/.codex/config.toml 中定义服务商。
3. 用 model 和 model_provider 指定默认模型。
4. 通过环境变量注入 API Key，避免明文泄露。
5. 启动后可用 /model 随时切换模型。
6. 遇到问题优先用 curl 验证接口连通性，再检查 wire_api 与代理配置。

掌握这套配置方法后，无论是云端性价比模型还是内网私有模型，都能灵活挂载到 Codex 上，打造真正属于自己的 AI 编程工作流。