Codex 接入第三方模型完整指南

OpenAI Codex App、CLI 和 SDK 现可接入第三方开源模型。

这篇指南适合想把 OpenAI Codex 文档和 Codex GitHub 仓库接到自定义模型上的开发者。跟着做完，你会得到一套可运行的接入流程，能把第三方模型挂到 Codex App、CLI 或 SDK 上，并验证它是否真的在工作。

本文只基于已公开的信息做落地整理，重点放在准备环境、配置模型提供方、连通 Codex 工具链、以及最后的验证和排错。你不需要先改造整个项目，只要先把模型端和 Codex 端对接起来，就能开始试用。

Before you start

• OpenAI 账号，且能访问 Codex 相关功能。
• 一个可用的第三方模型提供方账号，支持 OpenAI 兼容 API 或 Codex 兼容接入方式。
• API key：OpenAI Codex 侧 key，以及第三方模型侧 key。
• Node.js 20+，如果你要用 CLI 或 SDK 的 JavaScript 示例。
• Git 2.40+，用于拉取示例项目或仓库。
• 至少 2 GB 可用内存，便于本地运行 CLI、日志和测试脚本。

Step 1: 获取 Codex 工具链

目标是先把 Codex 的 App、CLI 或 SDK 入口准备好，这样后续才能切换模型而不是停留在文档阶段。先确认你打算从哪个入口开始：如果偏向命令行，就装 CLI；如果偏向代码集成，就先接 SDK；如果想快速试验，就用 App。

git clone https://github.com/openai/codex.git
cd codex
# 按仓库说明安装 CLI 或 SDK 依赖

验证方式很简单：你应该能看到仓库内容、安装命令成功执行，并且本地能打开 Codex 的配置说明或帮助信息。

Step 2: 准备第三方模型端点

目标是拿到一个可调用的模型 API 地址、模型名和密钥。Codex 官方说法是可以搭配任何开源模型使用，所以关键不是“模型是不是 OpenAI 的”，而是它是否能提供稳定的推理接口。优先选择支持 OpenAI 风格请求格式的服务，这样迁移成本最低。

把这些信息记下来：base URL、model id、API key、请求限流规则，以及是否需要额外的组织 ID 或项目 ID。后面配置时，这些字段会直接映射到 Codex 的连接参数。

验证方式是发一次最小请求。你应该能拿到一个正常的文本回复，而不是 401、404 或格式错误。

Step 3: 配置 Codex 模型连接

目标是让 Codex 读到你的第三方模型配置，并把请求转发过去。不同入口的配置方式会不同，但思路一致：把模型提供方的地址、密钥和模型名写进 Codex 的配置文件或环境变量。

export OPENAI_API_KEY="your-codex-key"
export OPENAI_BASE_URL="https://your-third-party-endpoint/v1"
export OPENAI_MODEL="your-model-name"

如果你用的是支持自定义 provider 的配置文件，就把同样的信息写入对应字段。重点是确认 Codex 发出的请求不再落到默认模型上，而是命中你填的第三方端点。

验证方式是启动 Codex CLI 或 SDK 示例后查看日志。你应该能看到请求发往第三方 base URL，并且返回内容来自你选择的模型。

Step 4: 运行一次端到端任务

目标是证明接入不是“能连上”，而是“能干活”。选一个小任务最合适，比如让 Codex 生成一个函数、修改一个测试、或总结一段代码。任务越小，越容易判断模型是否真正被调用。

建议先用 CLI 跑一个单文件任务，再用 SDK 跑一个简短脚本。这样你能分别验证交互式流程和程序化流程，避免只在一个入口上成功。

验证方式是你应该看到模型返回可执行的代码、补丁或解释，并且输出结果符合你指定的第三方模型风格和能力边界。

Step 5: 固化环境变量和回退方案

目标是把临时接入变成可重复使用的配置。把 base URL、模型名和 key 放进 `.env`、CI secrets 或部署环境变量里，避免每次手动输入。与此同时，准备一个回退方案，方便第三方模型不可用时切换回默认提供方。

如果你的团队要多人协作，最好把配置写进 README 或内部运行手册，并注明哪些字段必须保密，哪些字段可以公开。这样后续换模型时，改动范围会更小。

验证方式是重启终端或重新拉起容器后，Codex 仍然能自动读到配置，不需要人工补参。

Common mistakes

• 把模型名写错。修复方法：先用第三方控制台的模型列表复制准确名称，再写入配置。
• 端点不是 OpenAI 兼容格式。修复方法：确认路径、请求体和认证头与 Codex 期望一致，必要时加一层适配代理。
• 只测了连通性，没测任务输出。修复方法：跑一次真实代码生成或修改任务，检查返回结果是否可用。

What's next

接下来可以把同一套接入方式扩展到团队工作流里，比如接入 CI、自动化代码审查，或者为不同任务路由不同模型；如果你需要更稳的方案，再继续研究 Codex 的配置层、日志层和模型回退策略。