Codex 安装与国内使用教程：新手也能快速上手

Codex 安装与国内使用教程：新手也能快速上手

用简明问答介绍 Codex 桌面应用安装、API Key 登录和 APIBest 自定义 API 配置，适合第一次使用 Codex 的用户。

Codex 安装与国内使用教程：新手也能快速上手#

如果你第一次使用 Codex，只需完成两个目标：把官方桌面应用装到电脑上，再让应用连接到可用的模型 API。本文以 APIBest 为自定义 API 示例，基础地址为 https://apibest.org/v1。

::: info 本文不讲哪些内容 本文只处理桌面端安装与 API 配置，让首次使用时的每一步都更容易定位。 :::

去哪里下载桌面应用#

唯一推荐入口是 OpenAI Codex 产品页：

https://openai.com/zh-Hans-CN/codex/

官网会展示当前支持的 macOS 和 Windows 安装方式。不要从网盘或不明镜像下载“整合版”，因为安装包可能过期或被修改。

Mac 应该怎么安装#

Mac 的安装过程很直接：

  • 在“关于本机”查看系统版本和芯片。
  • 从官网下载匹配的版本。
  • 打开安装包，将应用放进“应用程序”。
  • 从 Launchpad 或 Finder 启动。

首次启动若出现安全确认，核对安装包来源后按系统流程继续。文件访问权限只给需要使用的项目目录即可。

Windows 应该怎么安装#

Windows 用户从同一官网取得安装程序，然后：

  • 双击运行安装向导。
  • 检查发布者与 SmartScreen 提示。
  • 安装完成后从开始菜单打开。

若公司电脑不允许安装，应联系管理员处理。不要为了运行 Codex 关闭杀毒软件或系统安全功能。

欢迎页面应该点哪个按钮#

准备使用 API Key 时，不要点击黑色的“使用 ChatGPT 继续”，而是点击下面的 “使用其他方式登录”。

新手在 Codex 欢迎页面选择其他登录方式

随后会出现 API 密钥输入框：

Codex API Key 输入框

第一次操作时可以用 sk-123456 看清格式，但真正连接模型必须替换为有效 Key。

如果使用 OpenAI 官方 Key，可直接按页面流程登录。如果使用 APIBest，仅填写 Key 还不够，因为应用还需要知道第三方 API 地址。

APIBest Key 在哪里复制#

访问 https://apibest.org，打开 API 密钥页面，找到目标 Key 后点击复制按钮。

APIBest API 密钥页面

把 Key 当作密码管理。不要写到项目文件、Git 仓库或公开截图中。

为什么要设置环境变量#

自定义提供商配置只记录“去哪个变量取 Key”，不会直接保存 Key。本文使用的变量名是 APIBEST_API_KEY。

macOS 当前终端：

bash
export APIBEST_API_KEY="你的 API Key"

Windows PowerShell 当前会话：

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

临时变量只在当前终端有效。如果从桌面图标启动 Codex，应通过系统用户环境或应用当前提供的安全设置方式，让桌面进程也能读取该变量。

config.toml 放在哪里#

请使用个人用户目录：

系统配置文件
macOS~/.codex/config.toml
Windows$HOME\.codex\config.toml

不要放进项目的 .codex/config.toml。模型提供商和 API 地址属于当前电脑的机器级配置，不应跟随代码仓库传播。

新手可直接核对的配置#

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 必须是控制台可用模型。
  • base_url 是 https://apibest.org/v1。
  • env_key 是变量名，不是真实密钥。
  • wire_api = "responses" 用于 Codex 的工具工作流。

保存后完全退出桌面应用，再重新打开并新建任务。

为什么配置后仍然失败#

最常见的原因不是安装问题，而是配置没有被桌面进程读取：

显示 401 或 403#

检查 Key 是否有效、是否有额度，以及 APIBEST_API_KEY 是否对应用可见。

显示 404#

确认没有把地址写成 /v1/v1，也不要手动加 /responses。

显示模型不可用#

登录 APIBest 控制台，复制准确模型 ID，不要凭展示名称猜测。

文字能返回，工具不能使用#

说明基础请求已通，但上游可能没有完整处理 Responses 流式事件或工具调用。

新手完成标准#

达到下面四点，就完成了桌面端基础配置：

  1. Codex 从官方安装包正常启动。
  2. 欢迎页选择了 API Key 登录方式。
  3. 桌面应用能读取 APIBEST_API_KEY。
  4. 用户级 config.toml 已指向 APIBest 和正确模型。

总结#

新手无需同时研究多种 Codex 入口。先装好官方桌面应用，再把 APIBest Key、用户环境变量和 config.toml 配成一条完整链路。连接异常时优先检查 Key、地址和模型，不要反复重装客户端。

参考资料#