3 步搞定 OpenAI Codex 国内使用环境：镜像网站 + 配置文件 + 使用指南（2026年9月最新）

发布于 2026年9月2日更新于 2026年9月2日作者：Codex 中文指南

如果你想在国内网络环境中使用 OpenAI Codex，最容易出错的地方通常不是安装命令，而是 API 地址、Key 的读取方式和配置文件位置。本文把完整流程压缩成三个可复现的步骤：在 APIBest 创建 Key、写入 Codex 配置、重启终端并完成一次只读测试。

本文适用于 Windows、macOS、Linux 和 WSL。APIBest 是独立的第三方兼容 API 服务，不是 OpenAI 官方服务；模型列表、价格、额度、可用区域和数据处理规则请以 APIBest 官网当前说明为准。

先看三步流程

步骤	要完成的事情	验收信号
1	访问 APIBest，创建并保存 API Key	Key 已保存到密码管理器，未写入仓库
2	安装 Codex 并写入 `auth.json`、`config.toml`	`codex --version` 有版本号，配置路径正确
3	进入项目目录启动 Codex，发送只读任务	能读取项目并返回结果，不出现 401、404

1. Codex 能做什么

Codex 是面向软件项目的 AI 编程助手。获得明确的目录权限后，它可以读取文件、理解目录结构、提出或应用代码修改，并在批准后运行测试和构建命令。它与只粘贴代码的聊天窗口不同：上下文、修改和验证可以在同一个项目中连续完成。

常见任务包括：

根据自然语言生成一个函数、接口或页面组件；
搜索项目中的调用关系，解释错误原因；
在限定范围内修复 Bug、补测试和更新文档；
运行已有的 lint、测试或构建命令，并根据输出继续排查。

第一次使用时建议从只读任务开始，不要直接把生产密钥或客户数据放进项目。

2. 开始前的准备

2.1 通用依赖

依赖	建议	用途
Windows / macOS / Linux	使用仍受支持的 64 位版本	运行桌面版或 CLI
Node.js	22 或更高版本	安装 Codex CLI
npm	随 Node.js 安装的较新版本	全局安装 CLI
终端	PowerShell、Git Bash、Terminal 或 WSL	执行安装和启动命令
APIBest 账号	在 APIBest 注册	创建自定义 API Key

检查 Node.js 和 npm：

bash

node --version
npm --version

2.2 安全边界

API Key 只应出现在环境变量或用户目录中的密钥文件，不要提交到 Git、截图、公开 issue 或聊天群。配置第三方 API 前，先确认项目代码已经脱敏，并阅读 APIBest 当前的数据保留和隐私说明。

3. 第一步：在 APIBest 创建 API Key

打开 https://apibest.org，按照页面提示注册或登录，在控制台创建一个专门给 Codex 使用的 Key。不同设备使用不同 Key，后续停用和轮换更容易。

创建时记录以下信息：

API Key 的完整值（只保存到密码管理器）；
APIBest 控制台显示的精确模型 ID；
当前套餐的额度、限流和有效期；
服务商文档中关于 Responses API、流式输出和工具调用的说明。

不要根据宣传页猜模型名称。下面的 gpt-5.6-sol 仅是配置示例，如果 APIBest 控制台显示的 ID 不同，应以控制台为准。

4. 第二步：安装 Codex 并写入配置

4.1 安装 CLI

在 Windows PowerShell、macOS Terminal、Linux shell 或 WSL 中执行：

bash

npm install -g @openai/codex
codex --version

如果只想临时运行，也可以使用：

bash

npx @openai/codex

Windows 用户使用 WSL 时，应在同一个 WSL 终端和项目路径中安装、启动，避免 Windows 与 Linux 的全局 npm 路径混用。

4.2 创建 `.codex` 目录

系统	配置目录
macOS / Linux / WSL	`~/.codex`
Windows PowerShell	`$HOME\\.codex`

macOS、Linux 或 WSL：

bash

mkdir -p ~/.codex

Windows PowerShell：

powershell

New-Item -ItemType Directory -Force "$HOME\\.codex"

4.3 设置 API Key

推荐先用环境变量，避免把真实 Key 写进配置文件。

macOS、Linux 或 WSL 当前终端：

bash

export APIBEST_API_KEY="你的 APIBest Key"

Windows PowerShell 当前会话：

powershell

$env:APIBEST_API_KEY="你的 APIBest Key"

如果需要长期保存环境变量，请使用系统自己的环境变量管理功能，并确认新终端能够读取它。不要把包含真实值的命令提交到仓库。

4.4 写入 `auth.json`（可选）

部分 Codex 版本会从用户目录读取 auth.json。如果你的版本要求该文件，可以创建下面的结构，并把占位符替换为真实 Key：

json

{
  "OPENAI_API_KEY": "你的 APIBest Key"
}

文件权限应限制为当前用户可读。若版本支持 env_key，优先使用环境变量，不必在磁盘保存明文 Key。

4.5 写入 `config.toml`

编辑 ~/.codex/config.toml（Windows 为 $HOME\\.codex\\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"

字段说明：

字段	作用	注意事项
`model`	要调用的模型 ID	使用 APIBest 控制台当前显示的精确值
`model_provider`	选择下方提供商	必须与 `apibest` 小节一致
`base_url`	API 基础地址	使用 `https://apibest.org/v1`，不要重复拼接 `/v1`
`env_key`	Key 对应的环境变量名	必须与 `APIBEST_API_KEY` 完全一致
`wire_api`	请求协议	按服务商文档确认 `responses` 是否可用
`approval_policy`	命令审批策略	新手建议保留 `on-request`
`sandbox_mode`	文件和命令的沙箱范围	项目任务可先使用 `workspace-write`

保存后检查 TOML 是否有重复的 [model_providers.apibest] 小节、错误引号或全角标点。配置文件中的 Key 变量名不是 Key 本身。

5. 第三步：终端启动与首次验证

5.1 重启终端

关闭并重新打开终端，让新的环境变量和配置生效。然后进入一个临时或脱敏项目目录：

bash

cd /你的项目路径
codex

启动后，先发送只读提示：

text

请读取当前目录结构并说明项目使用的技术栈、启动命令和主要入口。
只进行读取，不要修改文件、安装依赖或执行网络请求。

如果能得到项目概览，说明基础认证、地址和模型路由至少已经连通。接着可以测试一个小范围任务：

text

请只修改 src/example.ts 中的一个函数，为它补充单元测试。
完成后运行项目已有的测试命令，并列出修改的文件。

5.2 选择合适的入口

入口	更适合的工作
桌面应用	新手、跨文件任务、需要直观看到项目状态
CLI	终端、Git、批量修改、测试与构建
IDE 插件	解释当前文件、局部重构、处理编辑器报错

三种入口可以组合使用，但应保持同一套 APIBest 配置和项目权限边界。

6. Windows、macOS 与 Linux 差异

Windows

可使用 PowerShell 或 Git Bash；
配置文件位于 $HOME\\.codex，不是项目目录下的 .codex；
如果 codex 找不到，检查 npm 全局目录是否加入 PATH；
WSL 项目应在 WSL 内安装并启动 CLI。

macOS

可通过官方桌面安装包或 npm CLI 使用；
配置目录为 ~/.codex；
首次打开桌面应用时，按系统提示授予项目目录访问权限；
export 设置的变量只对当前终端有效，长期使用请配置系统环境变量。

Linux

先用发行版包管理器或 Node.js 官方方式准备 Node.js 22+；
权限不足时修复 npm 全局目录，尽量不要长期用 sudo npm install -g；
配置目录同样为 ~/.codex，启动前确认当前用户可以读取它。

7. 常见问题与排查顺序

现象	优先检查	处理办法
`npm: command not found`	Node.js 是否安装、PATH 是否刷新	重装 Node.js 或重开终端
`codex: command not found`	npm 全局 bin 是否在 PATH	用 `npm prefix -g` 查看路径，或暂用 `npx`
401 / 403	Key 是否有效、环境变量名是否一致	重新生成 APIBest Key，确认 `APIBEST_API_KEY` 可读
404	`base_url` 是否准确	使用 `https://apibest.org/v1`，不要写成 `/v1/v1`
模型不存在	模型 ID 或账号权限	复制 APIBest 控制台当前 ID，重启 Codex
能聊天但工具调用失败	Responses API、流式和工具调用兼容性	查阅 APIBest 文档，先用只读项目验证
响应慢或 429	额度、并发和限流	查看控制台用量，降低并发并按提示重试
读取不到项目	启动目录或访问权限错误	在目标目录运行 `codex`，重新授权目录

排错时可以运行 /status 查看当前会话信息，运行 /model 检查模型选择，运行 /diff 查看改动。不要把 Authorization Header、完整 Key 或客户代码粘贴到公开求助帖。

8. 常用命令速查

命令	用途
`codex`	在当前项目目录启动交互式 CLI
`codex --version`	查看 CLI 版本
`/status`	查看会话配置和用量提示
`/model`	切换模型或推理级别
`/approvals`	调整命令审批策略
`/diff`	查看当前 Git 差异
`/clear`	清除当前会话上下文
`/help`	查看内置帮助

9. 发布前检查清单

[ ] APIBest Key 已创建并安全保存，没有出现在仓库或截图中。
[ ] base_url 为 https://apibest.org/v1，没有重复路径。
[ ] model 使用 APIBest 控制台当前存在的模型 ID。
[ ] env_key 与 APIBEST_API_KEY 完全一致。
[ ] 已重启终端，并在脱敏项目中完成只读测试。
[ ] 已验证至少一次小范围修改、测试或构建。
[ ] 已阅读 APIBest 当前的价格、额度、限流和数据处理说明。

总结

把 Codex 接入 APIBest 可以记成三步：在 APIBest 创建 Key，安装 CLI 并写好 config.toml，重启终端后从只读任务开始验证。遇到问题时先按状态码检查认证、地址和模型，再判断是否属于 Responses API 或工具调用兼容性问题。

更多配置字段可参考使用 APIBest 为 Codex 配置自定义 API，需要完整排错表时查看Codex 自定义 API 常见错误与排查。

3 步搞定 OpenAI Codex 国内使用环境：镜像网站 + 配置文件 + 使用指南（2026年9月最新） ​

先看三步流程 ​

1. Codex 能做什么 ​

2. 开始前的准备 ​

2.1 通用依赖 ​

2.2 安全边界 ​

3. 第一步：在 APIBest 创建 API Key ​

4. 第二步：安装 Codex 并写入配置 ​

4.1 安装 CLI ​

4.2 创建 .codex 目录 ​

4.3 设置 API Key ​

4.4 写入 auth.json（可选） ​

4.5 写入 config.toml ​

5. 第三步：终端启动与首次验证 ​

5.1 重启终端 ​

5.2 选择合适的入口 ​

6. Windows、macOS 与 Linux 差异 ​

Windows ​

macOS ​

Linux ​

7. 常见问题与排查顺序 ​

8. 常用命令速查 ​

9. 发布前检查清单 ​

总结 ​

3 步搞定 OpenAI Codex 国内使用环境：镜像网站 + 配置文件 + 使用指南（2026年9月最新）

先看三步流程

1. Codex 能做什么

2. 开始前的准备

2.1 通用依赖

2.2 安全边界

3. 第一步：在 APIBest 创建 API Key

4. 第二步：安装 Codex 并写入配置

4.1 安装 CLI

4.2 创建 `.codex` 目录

4.3 设置 API Key

4.4 写入 `auth.json`（可选）

4.5 写入 `config.toml`

5. 第三步：终端启动与首次验证

5.1 重启终端

5.2 选择合适的入口

6. Windows、macOS 与 Linux 差异

Windows

macOS

Linux

7. 常见问题与排查顺序

8. 常用命令速查

9. 发布前检查清单

总结