Codex下载、安装、配置保姆级教程（2026最新版）
本文从零讲清楚 Codex 的下载、安装、登录、API 配置和第一次使用。没有可用的 ChatGPT 账号，或者希望通过自定义 API 使用 Codex，可以访问 API 站点：https://apibest.org 获取 API Key；对应的 API 基础地址是 https://apibest.org/v1。下文会给出可以直接参考的完整配置。
使用第三方 API 前请确认数据要求
APIBest 不是 OpenAI 官方服务。模型、价格、可用性、数据处理方式和协议兼容性以 APIBest 的实际说明为准。公司源码、客户数据或其他敏感内容是否允许发送给第三方服务，应先经过所在组织的安全审查。
一、先弄清楚 Codex 的三个版本
Codex 不是只有一种安装方式。2026 年常见的使用入口有三个：
| 使用方式 | 适合人群 | 是否需要命令行 |
|---|---|---|
| 桌面应用 | 希望使用图形界面、管理多个项目和任务 | 不需要 |
| Codex CLI | 经常在终端工作，希望直接操作本地仓库 | 需要 |
| IDE 扩展 | 主要使用 VS Code、Cursor 或 Windsurf | 少量 |
三种方式并不冲突。CLI 与 IDE 扩展可以共用本机的登录状态和 ~/.codex/config.toml，所以很多开发者会同时安装。本文以最通用的 CLI 为主，同时给出桌面应用和 IDE 扩展的安装方法。
二、安装前的准备工作
1. 准备一个代码编辑器和 Git
建议提前安装：
- Git，用于版本管理和查看 Codex 的修改。
- VS Code、Cursor、Windsurf 或你常用的其他编辑器。
- Node.js 当前的 LTS 版本，用于通过 npm 安装 Codex CLI。
打开终端，检查 Node.js 和 npm：
node -v
npm -v只要两条命令都能输出版本号，就可以继续。如果提示找不到命令，请先从 Node.js 官网 安装当前 LTS 版本，然后重新打开终端。
2. Windows 用户注意终端环境
Windows 可以使用 PowerShell，也可以在 WSL 中使用 Codex CLI。如果你的项目、Node.js 和 Git 都在 WSL 里，就应在同一个 WSL 环境内安装 Codex；不要把 Windows 路径、Windows 版 Node.js 和 WSL 工具链混在一次任务中。
三、下载并安装 Codex 桌面应用
想直接使用图形界面，可以访问 OpenAI 官方 Codex 页面：
根据页面提示选择 macOS 或 Windows 版本。下载入口和系统要求会随版本更新，因此建议始终从官方页面获取当前安装包，不要使用网盘中来源不明或长期未更新的安装文件。
macOS 安装步骤
- 下载适合当前 Mac 的安装包。
- 打开安装包，将应用拖入“应用程序”目录。
- 从 Launchpad 或“应用程序”目录启动。
- 第一次打开时，确认应用来源后按 macOS 提示完成授权。
Windows 安装步骤
- 从官方页面下载 Windows 安装程序。
- 双击安装程序，按向导完成安装。
- 从开始菜单启动应用。
- 如果系统显示安全确认，先核对发布者和下载来源。
公司电脑可能限制安装软件。这种情况应联系设备管理员，不建议关闭系统安全保护或绕过组织策略。
四、安装 Codex CLI
1. 使用 npm 安装
在 macOS、Linux、PowerShell 或 WSL 的终端中运行：
npm install -g @openai/codex安装完成后检查版本：
codex --version看到版本号就说明 CLI 已经安装成功。进入一个 Git 项目后运行：
cd /你的项目路径
codex第一次启动时，Codex 会引导你选择登录方式并确认项目权限。
2. 更新到最新版
已经安装过旧版时，执行：
npm install -g @openai/codex@latest
codex --version排查问题时最好同时记录 Codex 版本。网上教程中的配置字段可能已经变更，应优先参考当前版本的官方文档。
3. 常见安装报错
如果出现 codex: command not found：
- 关闭并重新打开终端。
- 运行
npm prefix -g，确认 npm 的全局目录已经加入PATH。 - 确认安装 Codex 和运行 Codex 使用的是同一个 Node.js 环境。
如果出现权限错误，不要直接使用来源不明的提权命令。优先通过 Node.js 版本管理工具安装用户级 Node.js，再重新执行 npm 安装。
五、安装 Codex IDE 扩展
以 VS Code 为例：
- 打开扩展市场。
- 搜索
Codex。 - 核对发布者为 OpenAI 后再安装。
- 打开一个本地项目，在 Codex 面板中按提示登录。
Cursor、Windsurf 等兼容 VS Code 扩展的编辑器也可以使用相应入口。安装后建议先让 Codex 解释当前文件或读取项目结构，再尝试修改代码。
六、选择登录或 API 接入方式
本地 Codex 通常有两类接入方式：
方式 A：使用 OpenAI 账号
启动 Codex 后选择使用 ChatGPT 登录，浏览器会打开登录页面。完成登录后回到应用或终端即可。
本地 Codex 也支持 OpenAI Platform API Key，按界面提示输入即可。使用 API Key 会按 API 平台规则计费，不等同于使用 ChatGPT 套餐内的额度。
方式 B：使用 APIBest 自定义 API
如果你需要 OpenAI-compatible 自定义 API，可以使用：
- API 站点：https://apibest.org
- API 基础地址：
https://apibest.org/v1
下面是完整配置步骤。
七、配置 APIBest API
1. 创建 API Key
进入 APIBest，注册并在控制台创建 API Key。密钥通常只会完整显示一次，请妥善保存，不要发送给他人，也不要写进 Git 仓库。
2. 设置环境变量
macOS、Linux 或 WSL，在当前终端运行：
export APIBEST_API_KEY="你的 API Key"Windows PowerShell：
$env:APIBEST_API_KEY="你的 API Key"上面的命令只对当前终端会话生效。需要长期使用时，可以通过系统的用户环境变量或个人 shell 配置保存，但不要把密钥放入会提交到 Git 的文件。
3. 找到 Codex 配置文件
Codex 的用户级配置文件是：
~/.codex/config.tomlWindows PowerShell 对应当前用户主目录下的：
$HOME\.codex\config.toml目录或文件不存在时可以手动创建。自定义 API 提供商属于个人机器配置，应写在用户级文件中，不要写到项目的 .codex/config.toml。
4. 写入完整配置
打开 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 | API 请求基础地址，保留末尾的 /v1 |
env_key | 保存密钥的环境变量名称，不是密钥本身 |
wire_api | 使用 Codex 所需的 Responses API 协议 |
approval_policy | 遇到需要确认的操作时向用户请求批准 |
sandbox_mode | 默认只允许在当前工作区范围内写文件 |
model 必须与 APIBest 控制台实际提供的模型 ID 一致。本文使用 gpt-5.6-sol 作为示例；可用模型、名称和兼容性可能变化，请以控制台当时显示的信息为准。
不要这样填写密钥
不要把 env_key 写成真实 API Key，也不要在 config.toml 中加入 api_key = "真实密钥"。正确做法是让 env_key 指向环境变量 APIBEST_API_KEY。
5. 验证环境变量和配置
macOS、Linux 或 WSL：
test -n "$APIBEST_API_KEY" && echo "APIBEST_API_KEY 已设置"PowerShell：
if ($env:APIBEST_API_KEY) { "APIBEST_API_KEY 已设置" }然后进入一个用于测试的 Git 项目并启动：
codex第一次先发送一个只读任务：
阅读当前项目的 README 和目录结构，告诉我如何安装依赖、运行测试和启动项目。不要修改文件，也不要安装依赖。
如果 Codex 能稳定返回结果，再测试一次小范围文件修改和本地命令。普通聊天成功并不能证明第三方 API 已完整支持流式输出、工具调用和长上下文。
八、第一次使用时怎么设置权限
Codex 可以读取文件、修改代码和运行命令，因此权限不应一开始就全部放开。推荐保持：
approval_policy = "on-request"
sandbox_mode = "workspace-write"这套设置适合大多数本地项目：Codex 可以在当前工作区工作，涉及更大权限时会请求确认。批准前重点检查命令、目标路径和网络地址，尤其是删除文件、安装软件、访问项目外目录和上传数据等操作。
打开项目后还应先确认：
- 当前目录确实是目标 Git 仓库。
- 未提交改动已经备份或清楚记录。
.env、私钥和生产配置没有被加入 Git。- 项目的测试、构建命令可以在本机正常运行。
九、API 配置常见问题
1. 提示 401 或 API Key 无效
检查 APIBEST_API_KEY 是否存在、是否多了空格、是否已经失效。修改环境变量后需要在同一个终端启动 Codex；从桌面图标启动的应用不一定继承终端中的临时环境变量。
2. 提示模型不存在
model 不是随便填写的显示名称，必须使用 APIBest 控制台实际提供的模型 ID。更换模型后建议新建 Codex 任务，避免旧任务保留之前的模型状态。
3. 请求地址出现重复的 /v1
base_url 应写为：
base_url = "https://apibest.org/v1"不要自行追加 /responses，Codex 会根据协议生成具体请求路径。
4. 能回答问题，但不能修改文件
先区分是本地权限问题，还是 API 工具调用兼容问题。检查 Codex 是否获得工作区写权限，再确认第三方 API 是否完整支持 Responses 流式协议、工具调用和工具结果回传。
5. 修改配置后没有生效
确认修改的是用户主目录下的 ~/.codex/config.toml，TOML 表名和引号没有写错，然后完全退出并重新启动 Codex。CLI 与 IDE 扩展通常共用登录和配置，但已经打开的任务可能保留旧状态。
更多错误定位方法可查看 Codex 自定义 API 常见错误与排查。
十、推荐的日常使用流程
- 在 Git 仓库根目录启动 Codex。
- 先让 Codex 阅读
README.md、AGENTS.md和主要配置文件。 - 明确说明目标、允许修改的范围和验收命令。
- 让 Codex 完成后运行对应测试或构建。
- 使用 Git 差异或应用内审查界面检查每一处改动。
- 确认无误后再由你决定是否提交代码。
一个比较稳妥的任务写法是：
修复登录表单在请求超时后一直显示加载状态的问题。只修改相关组件和测试，沿用现有代码风格；完成后运行对应测试，并总结修改内容和测试结果。
目标、范围和验证方式越清楚，Codex 越不容易做出超出预期的改动。
十一、卸载与清理
通过 npm 安装的 CLI 可以这样卸载：
npm uninstall -g @openai/codex用户配置和登录缓存通常仍保留在 ~/.codex/。其中可能包含认证信息，不要上传或分享。只有在确认不再需要历史配置和凭据后，才应手动处理该目录。
桌面应用可按 macOS 或 Windows 的常规卸载流程移除。IDE 扩展则从编辑器的扩展管理页面卸载。
十二、总结
如果你偏好图形界面，安装 Codex 桌面应用即可；如果主要在终端开发，使用 npm install -g @openai/codex 安装 CLI；如果长期在编辑器内工作，再安装官方 IDE 扩展。
需要配置自定义 API 时，核心只有三步：在 https://apibest.org 获取 API Key，将密钥保存到 APIBEST_API_KEY 环境变量，再在 ~/.codex/config.toml 中把 base_url 设置为 https://apibest.org/v1。配置后先用小型只读任务验证连接、流式输出和工具调用，再用于正式项目。