Codex 安装与使用教程：新手也能快速上手【2026 年 8 月最新】
本文只讲两件事：如何安装 Codex 桌面应用，以及如何配置自定义 API。需要 API 中转服务的读者可以访问 https://apibest.org 获取 API Key，API 基础地址为 https://apibest.org/v1。
第三方服务说明
APIBest 不是 OpenAI 官方服务。可用模型、价格、额度、数据处理方式和协议兼容性以 APIBest 实际说明为准。不要把生产密钥、客户数据或受保密协议约束的代码发送给未经审核的第三方服务。
一、下载 Codex 桌面应用
请从 OpenAI 官方页面下载安装包：
在页面中选择 macOS 或 Windows 版本。官方安装方式和系统要求可能随版本变化，因此本文不提供固定的 .dmg、.exe 或其他安装文件直链。
下载时注意：
- 浏览器地址应属于
openai.com官方域名。 - 不要使用论坛附件、网盘重新打包版或所谓破解版。
- 下载后核对文件来源和发布者。
- 公司电脑安装软件前应确认设备管理策略。
二、macOS 安装步骤
1. 检查 Mac 信息
打开“苹果菜单 -> 关于本机”，查看 macOS 版本和芯片信息。如果官方页面提供不同架构版本，应选择与当前 Mac 匹配的安装包。
2. 安装应用
打开下载完成的安装包，根据界面提示将 Codex 放入“应用程序”目录。
安装完成后，可以从以下位置启动：
- Launchpad
- Finder 的“应用程序”目录
- Spotlight 搜索
3. 处理首次打开提示
macOS 可能显示应用来源确认或文件夹访问请求。确认安装包来自 OpenAI 官方页面后，再按照系统正常流程继续。
只授权实际需要使用的项目目录，不要为了安装而关闭 Gatekeeper，也不要默认开放整个磁盘。
三、Windows 安装步骤
1. 下载安装程序
在 OpenAI Codex 官方页面选择 Windows 版本，等待安装程序下载完成。
2. 完成安装
双击安装程序，按照安装向导继续。如果 Windows 显示 SmartScreen、安全确认或管理员权限提示：
- 核对文件来自 OpenAI 官方页面。
- 检查发布者信息。
- 确认公司设备允许安装。
- 无法确认来源时取消安装并重新下载。
不要关闭系统安全保护来运行来源不明的文件。
3. 启动应用
安装完成后，从 Windows 开始菜单启动 Codex。
四、首次打开时选择 API Key
安装完成并打开 Codex 后，不要点击账号登录，按照下面步骤操作：
- 在登录页面不要选择“使用 ChatGPT 登录”。
- 点击 “使用其他方式”，英文界面显示为 Sign in another way。
- 选择 API Key 登录。
- 输入你的 API Key，先填入
sk-123456占位。 - 点击继续，进入 Codex。
根据 OpenAI 的认证说明，桌面应用支持使用 OpenAI Platform API Key 登录。使用官方 API Key 时，可以直接走这个登录流程。
使用 APIBest Key 时还要配置请求地址
“使用其他方式”只负责切换到 API Key 登录。使用 APIBest 时，还必须完成下文的 model_provider、base_url 和密钥环境变量配置；仅在登录框中粘贴 Key 不会自动把请求地址切换到 https://apibest.org/v1。
五、准备 APIBest API Key
访问：
注册后在控制台复制 API Key。建议妥善保存。
不要把 API Key：
- 写入 Git 仓库。
- 放入项目 README 或公开文档。
- 直接写进共享的
config.toml示例。
六、设置 API Key 环境变量
Codex 自定义提供商可以从环境变量读取密钥。本文使用变量名：
APIBEST_API_KEYmacOS 当前终端会话
export APIBEST_API_KEY="你的 API Key"Windows PowerShell 当前会话
$env:APIBEST_API_KEY="你的 API Key"以上命令只对当前终端会话生效。从桌面图标启动的应用不一定继承终端中的临时变量。需要长期使用时，应通过操作系统用户环境或 Codex 当前版本提供的安全配置入口保存变量，并避免把密钥写入会同步或提交的项目文件。
七、创建 Codex 用户级配置
自定义 API 提供商应写入用户级配置文件。
macOS 配置位置：
~/.codex/config.tomlWindows 配置位置：
$HOME\.codex\config.toml如果 .codex 目录或 config.toml 不存在，可以手动创建。
不要把提供商配置放到项目的 .codex/config.toml。Codex 不允许项目级配置覆盖 model_provider 和 model_providers 等机器级提供商设置，避免仓库偷偷修改模型请求目标。
八、写入 APIBest 配置
在用户级 config.toml 中写入：
model = "gpt-5.6-sol"
model_provider = "apibest"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[model_providers.apibest]
name = "APIBest"
base_url = "https://apibest.org/v1"
env_key = "APIBEST_API_KEY"
wire_api = "responses"字段含义：
| 配置项 | 作用 |
|---|---|
model | APIBest 控制台实际提供的模型 ID |
model_provider | 选择下面定义的 apibest 提供商 |
base_url | APIBest API 基础地址，保留 /v1 |
env_key | 存放密钥的环境变量名称，不是密钥值 |
wire_api | 使用 Codex 工具工作流需要的 Responses API |
approval_policy | 遇到更高权限操作时请求用户确认 |
sandbox_mode | 默认只在当前工作区范围内写文件 |
不要把 Key 写进 env_key
正确写法是 env_key = "APIBEST_API_KEY"。不要将这一行替换成真实 API Key，也不要添加包含真实密钥的 api_key 字段。
gpt-5.6-sol 是本文使用的模型示例。模型 ID 必须与 APIBest 控制台当前显示的字符串一致；可用模型和账号权限可能变化。
九、让配置生效
完成环境变量和 config.toml 后：
- 完全退出 Codex。
- 确认 API Key 环境变量已经保存到 Codex 能读取的位置。
- 重新打开 Codex。
- 新建任务，避免旧任务继续使用之前的模型状态。
macOS 或 Linux 可以在终端检查变量是否存在：
test -n "$APIBEST_API_KEY" && echo "APIBEST_API_KEY 已设置"Windows PowerShell：
if ($env:APIBEST_API_KEY) { "APIBEST_API_KEY 已设置" }不要直接输出完整 API Key，以免密钥出现在终端日志或截图中。
十、自定义 API 常见错误
1. 返回 401 或 403
通常是 API Key 没有设置、已经失效、没有模型权限，或者 Codex 进程没有继承环境变量。确认 env_key 与 APIBEST_API_KEY 拼写完全一致。
2. 提示模型不存在
检查 APIBest 控制台中的实际模型 ID。不要根据网页展示名称自行拼写模型字符串。
3. 返回 404
基础地址应为：
base_url = "https://apibest.org/v1"不要写成 .../v1/v1，也不要在 base_url 后自行添加 /responses。
4. 能返回文字但不能使用工具
普通聊天成功不代表第三方 API 已完整兼容 Codex。还需要确认 Responses 流式事件、工具调用和工具结果回传是否正常。
5. 修改配置后没有生效
确认修改的是用户目录下的 ~/.codex/config.toml，检查 TOML 引号和表名，然后完全退出 Codex 并重新打开。
更多排查方法见 Codex 自定义 API 常见错误与排查。
总结
安装 Codex 桌面应用时，应始终从 OpenAI Codex 官方页面 获取当前版本。首次打开后，点击“使用其他方式”，选择 API Key 登录。
配置自定义 API 时，访问 https://apibest.org 获取 API Key，把密钥保存到 APIBEST_API_KEY 环境变量，并在用户级 ~/.codex/config.toml 中设置 model_provider = "apibest"、base_url = "https://apibest.org/v1" 和 wire_api = "responses"。