Codex 安装与使用教程：新手也能快速上手【2026 年 8 月最新】

Codex 安装与使用教程：新手也能快速上手【2026 年 8 月最新】

面向新手的 Codex 桌面应用安装和自定义 API 配置教程，覆盖 macOS、Windows、API Key 登录以及 APIBest config.toml 设置。

Codex 安装与使用教程：新手也能快速上手【2026 年 8 月最新】#

本文只讲两件事：如何安装 Codex 桌面应用，以及如何配置自定义 API。需要 API 中转服务的读者可以访问 https://apibest.org 获取 API Key，API 基础地址为 https://apibest.org/v1。

::: warning 第三方服务说明 APIBest 不是 OpenAI 官方服务。可用模型、价格、额度、数据处理方式和协议兼容性以 APIBest 实际说明为准。不要把生产密钥、客户数据或受保密协议约束的代码发送给未经审核的第三方服务。 :::

一、下载 Codex 桌面应用#

请从 OpenAI 官方页面下载安装包：

前往 OpenAI Codex 官方页面

在页面中选择 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、安全确认或管理员权限提示：

  1. 核对文件来自 OpenAI 官方页面。
  2. 检查发布者信息。
  3. 确认公司设备允许安装。
  4. 无法确认来源时取消安装并重新下载。

不要关闭系统安全保护来运行来源不明的文件。

3. 启动应用#

安装完成后，从 Windows 开始菜单启动 Codex。

四、首次打开时选择 API Key#

安装完成并打开 Codex 后，不要点击账号登录，按照下面步骤操作：

  1. 在登录页面不要选择“使用 ChatGPT 登录”。
  2. 点击 “使用其他方式”，英文界面显示为 Sign in another way。
  3. 选择 API Key 登录。
  4. 输入你的 API Key，先填入 sk-123456 占位。
  5. 点击继续，进入 Codex。

Codex 登录页面点击使用其他方式

Codex 输入 API Key 登录

根据 OpenAI 的认证说明，桌面应用支持使用 OpenAI Platform API Key 登录。使用官方 API Key 时，可以直接走这个登录流程。

::: tip 使用 APIBest Key 时还要配置请求地址 “使用其他方式”只负责切换到 API Key 登录。使用 APIBest 时，还必须完成下文的 model_provider、base_url 和密钥环境变量配置；仅在登录框中粘贴 Key 不会自动把请求地址切换到 https://apibest.org/v1。 :::

五、准备 APIBest API Key#

访问：

APIBest API 中转站

注册后在控制台复制 API Key。建议妥善保存。

不要把 API Key：

  • 写入 Git 仓库。
  • 放入项目 README 或公开文档。
  • 直接写进共享的 config.toml 示例。

在 APIBest 控制台复制 API Key

六、设置 API Key 环境变量#

Codex 自定义提供商可以从环境变量读取密钥。本文使用变量名：

text
APIBEST_API_KEY

macOS 当前终端会话#

bash
export APIBEST_API_KEY="你的 API Key"

Windows PowerShell 当前会话#

powershell
$env:APIBEST_API_KEY="你的 API Key"

以上命令只对当前终端会话生效。从桌面图标启动的应用不一定继承终端中的临时变量。需要长期使用时，应通过操作系统用户环境或 Codex 当前版本提供的安全配置入口保存变量，并避免把密钥写入会同步或提交的项目文件。

七、创建 Codex 用户级配置#

自定义 API 提供商应写入用户级配置文件。

macOS 配置位置：

text
~/.codex/config.toml

Windows 配置位置：

text
$HOME\.codex\config.toml

如果 .codex 目录或 config.toml 不存在，可以手动创建。

不要把提供商配置放到项目的 .codex/config.toml。Codex 不允许项目级配置覆盖 model_provider 和 model_providers 等机器级提供商设置，避免仓库偷偷修改模型请求目标。

八、写入 APIBest 配置#

在用户级 config.toml 中写入：

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"

字段含义：

配置项作用
modelAPIBest 控制台实际提供的模型 ID
model_provider选择下面定义的 apibest 提供商
base_urlAPIBest API 基础地址，保留 /v1
env_key存放密钥的环境变量名称，不是密钥值
wire_api使用 Codex 工具工作流需要的 Responses API
approval_policy遇到更高权限操作时请求用户确认
sandbox_mode默认只在当前工作区范围内写文件

::: danger 不要把 Key 写进 env_key 正确写法是 env_key = "APIBEST_API_KEY"。不要将这一行替换成真实 API Key，也不要添加包含真实密钥的 api_key 字段。 :::

gpt-5.6-sol 是本文使用的模型示例。模型 ID 必须与 APIBest 控制台当前显示的字符串一致；可用模型和账号权限可能变化。

九、让配置生效#

完成环境变量和 config.toml 后：

  1. 完全退出 Codex。
  2. 确认 API Key 环境变量已经保存到 Codex 能读取的位置。
  3. 重新打开 Codex。
  4. 新建任务，避免旧任务继续使用之前的模型状态。

macOS 或 Linux 可以在终端检查变量是否存在：

bash
test -n "$APIBEST_API_KEY" && echo "APIBEST_API_KEY 已设置"

Windows PowerShell：

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#

基础地址应为：

toml
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"。

参考资料#