Codex¶
Codex 是 OpenAI 官方推出的运行在终端里的代理式（agentic）编程工具。它可以理解您的代码库、编辑文件、运行命令，并帮助您更高效地编写代码。
通过将 Codex 指向 vLLM 服务器，您可以使用自己的模型作为后端，而不是使用 OpenAI API。这适用于以下场景：
- 运行完全本地/私有的代码辅助
- 使用具有工具调用（tool calling）能力的开源模型
- 使用自定义模型进行测试和开发
工作原理¶
vLLM 实现了 OpenAI-Responses API，这也是 Codex 用来与 OpenAI 服务器通信的同一种 API。通过将 Codex 配置为指向您的 vLLM 服务器，Codex 会将其请求发送给 vLLM 而不是 OpenAI。随后，vLLM 会翻译这些请求以适配您的本地模型，并按 Codex 预期的格式返回响应。
这意味着任何由 vLLM 提供服务且具备适当工具调用支持的模型，都可以在 Codex 中作为 OpenAI 模型的掉换替代品。
要求¶
Codex 需要具有强大工具调用能力的模型。该模型必须支持 OpenAI-Responses 工具调用 API。有关为您的模型启用工具调用的详细信息，请参阅 工具调用 (Tool Calling)。
安装¶
首先，按照 官方安装指南 安装 Codex。
启动 vLLM 服务器¶
使用具有工具调用功能的模型启动 vLLM - 这是一个使用 Qwen/Qwen3-27B 的示例
vllm serve Qwen/Qwen3.6-27B --port 8000 --tensor-parallel-size 8 --max-model-len 262144 --reasoning-parser qwen3 --enable-auto-tool-choice --tool-call-parser qwen3_coder
对于其他模型，您需要使用 --enable-auto-tool-choice 和正确的 --tool-call-parser 来显式启用工具调用。请参考 工具调用文档 以获取适用于您模型的正确标识。
配置 Codex¶
Codex 通过位于 ~/.codex/config.toml 的 TOML 文件进行配置。创建或编辑此文件以将 Codex 指向您的 vLLM 服务器
model = "my-model"
model_provider = "vllm"
[model_providers.vllm]
name = "vLLM"
env_key = "VLLM_API_KEY"
base_url = "https://:8000/v1"
wire_api = "responses"
配置字段
| 字段 | 描述 |
|---|---|
model | 要使用的模型名称。必须与您传递给 vLLM 的 --served-model-name 匹配。 |
model_provider | 设置为 "vllm" 以使用您的本地 vLLM 服务器。 |
[model_providers.vllm] | vLLM 提供程序的配置部分。 |
名称 | 您的 vLLM 提供程序的显示名称。 |
env_key | Codex 将读取 API 密钥的环境变量名称。由于 vLLM 默认不需要身份验证，因此这可以是任何值。 |
base_url | 您的 vLLM 服务器的 OpenAI 兼容 API 端点 URL（默认为 https://:8000/v1）。 |
wire_api | 要使用的 API 风格。对于 OpenAI Responses API，请设置为 "responses" |
警告
使用 responses API 时，请确保您的 vLLM 版本支持 OpenAI Responses API。
测试设置¶
配置好 Codex 后，在您的项目目录中启动它
尝试简单的提示词以验证连接，例如要求它解释项目中的一个文件。如果模型能正确响应，则说明您的设置已生效。您现在可以将 Codex 与您由 vLLM 提供服务的模型一起用于编程任务了。
故障排除¶
连接被拒绝 (Connection refused)：确保 vLLM 正在运行且可以通过指定的 URL 访问。检查端口是否匹配，以及 base_url 是否包含 /v1 路径后缀。
工具调用无效 (Tool calls not working)：验证您的模型是否支持工具调用，以及您是否使用了正确的 --tool-call-parser 标识启用了它。请参阅 工具调用。
找不到模型 (Model not found)：确保 ~/.codex/config.toml 中的 model 字段与您传递给 vLLM 的 --served-model-name 一致。