Codex 中文指南

外观

2026年国内Codex安装教程和使用教程：GPT-5.6-sol 完整指南 ​

发布于 2026年7月21日更新于 2026年7月22日作者：Codex 中文指南

2026 年在国内使用 Codex，最稳妥的思路不是反复更换安装包，而是把问题拆成三层：先让 Codex 客户端在本机正常运行，再配置可用的 API，最后验证 gpt-5.6-sol 是否支持 Codex 所需的流式响应和工具调用。

本文会从零完成整套流程。需要自定义 API 的读者可以访问 API 站点：https://apibest.org 获取 API Key，API 基础地址为 https://apibest.org/v1。

第三方服务说明

APIBest 不是 OpenAI 官方服务。模型映射、价格、额度、数据处理方式和可用性以 APIBest 实际页面为准。请先确认你的代码是否允许发送给第三方服务，不要上传生产密钥、客户数据或受保密协议约束的源码。

一、Codex 和 GPT-5.6-sol 分别是什么 ​

Codex 是面向软件开发任务的编码代理，可以读取代码、编辑文件、运行命令、执行测试并审查修改。它目前可以通过桌面应用、命令行和 IDE 扩展使用。

gpt-5.6-sol 是 GPT-5.6 系列中面向旗舰能力的模型标识。根据 OpenAI 当前模型指南：

  • gpt-5.6-sol 适合复杂、质量优先的任务。
  • gpt-5.6-terra 更偏向能力与成本的平衡。
  • gpt-5.6-luna 更适合高频、效率优先的工作负载。
  • OpenAI API 中的 gpt-5.6 别名会路由到 gpt-5.6-sol。

在 APIBest 中使用时，应填写其控制台实际提供的模型 ID。名称相同不代表本站能够确认第三方服务的底层模型映射，最终以服务商说明和实际测试为准。

二、安装前需要准备什么 ​

1. 准备 Git ​

Codex 最适合在 Git 仓库中工作，因为你可以随时查看修改内容或撤销尚未提交的变更。先检查：

bash
git --version

如果命令不存在，可以从 Git 官网 安装。

2. 准备 Node.js ​

通过 npm 安装 Codex CLI 前，需要 Node.js。建议使用当前 LTS 版本：

bash
node -v
npm -v

两条命令都能输出版本号即可。如果没有安装，请从 Node.js 官网 获取 LTS 版本，并在安装后重新打开终端。

3. Windows 应该选原生还是 WSL ​

Windows 用户可以使用原生 PowerShell，也可以使用 WSL2。如果平时的代码、Git 和开发依赖都在 Linux 环境内，建议选择 WSL2，并在 WSL2 中安装 Node.js 与 Codex。

不要在 Windows 版 Node.js 中安装 Codex，却在 WSL 项目中调用；工具链和项目放在同一个环境中，路径与权限问题会少很多。当前 Codex 的 Linux 沙箱要求也使 WSL2 比 WSL1 更适合作为开发环境。

三、安装 Codex CLI ​

1. 使用 npm 安装 ​

打开终端运行：

bash
npm install -g @openai/codex

安装完成后检查：

bash
codex --version

如果能看到版本号，说明 Codex CLI 已正常安装。

2. 更新 Codex ​

已经安装过旧版本，可以更新到当前最新版：

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

Codex 更新较快。遇到配置或协议问题时，应先记录 codex --version 的输出，再对照当前官方文档，不要直接照搬几年前的参数。

3. 解决 command not found ​

安装成功后仍提示 codex: command not found，按下面顺序检查：

  1. 完全关闭并重新打开终端。
  2. 运行 npm prefix -g，查看 npm 全局安装目录。
  3. 确认 npm 的全局可执行目录已经加入 PATH。
  4. 确认安装和运行使用的是同一套 Node.js 环境。

遇到 npm 权限错误时，建议使用 Node.js 版本管理工具重新安装用户级 Node.js，不要随意给 npm 全局目录设置过宽权限。

四、安装 Codex 桌面应用或 IDE 扩展 ​

Codex 桌面应用 ​

偏好图形界面的用户可以访问：

OpenAI Codex 官方页面

根据页面当时提供的选项下载 macOS 或 Windows 版本。安装包和系统要求可能变化，应始终从官方页面下载，不建议使用第三方重新打包的程序。

安装完成并首次打开 Codex 时：

  1. 不要点击账号登录或“使用 ChatGPT 登录”。
  2. 点击 “使用其他方式”（英文界面为 Sign in another way）。
  3. 选择 API Key 登录，输入你的 API Key，然后点击继续。
  4. 进入 Codex 后打开一个本地 Git 项目，确认项目路径、当前分支和未提交改动，再开始任务。

APIBest Key 还需要自定义提供商配置

登录页面中的 API Key 方式不会自动修改 API 请求地址。使用 APIBest 时，仍需完成下文的 model_provider = "apibest"、base_url = "https://apibest.org/v1" 和 APIBEST_API_KEY 配置。

IDE 扩展 ​

VS Code、Cursor 和 Windsurf 用户可以在扩展市场搜索 Codex，核对发布者为 OpenAI 后安装。CLI 与 IDE 扩展通常共用本机的认证状态和 ~/.codex/config.toml，所以 API 配置不需要重复写两份。

五、国内使用 Codex 的两种接入方式 ​

方式一：使用 OpenAI 支持的账号或 API ​

本地 Codex 支持使用 ChatGPT 登录，也支持使用 OpenAI Platform API Key。账号权限、套餐、地区和计费方式应以 OpenAI 当前页面为准。

使用 ChatGPT 登录时，Codex 会打开浏览器完成授权。使用 OpenAI API Key 时，调用按 API 平台规则计费，不等同于使用 ChatGPT 套餐额度。

方式二：配置 APIBest 自定义 API ​

需要 OpenAI-compatible API 时，可以使用以下信息：

  • API 站点：https://apibest.org
  • API 基础地址：https://apibest.org/v1
  • 本文示例模型：gpt-5.6-sol

接下来完成完整配置。

六、为 Codex 配置 GPT-5.6-sol ​

第 1 步：创建 API Key ​

进入 APIBest，注册并在控制台创建 API Key。不要把密钥发送到聊天记录、截图、工单或 Git 仓库。

第 2 步：设置 API Key 环境变量 ​

macOS、Linux 或 WSL：

bash
export APIBEST_API_KEY="你的 API Key"

Windows PowerShell：

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

这些命令只对当前终端有效。需要长期使用时，可以把密钥保存到个人环境变量或本机 shell 配置，但不要写入会提交到 Git 的项目文件。

第 3 步：打开用户级配置 ​

Codex 用户级配置位于：

text
~/.codex/config.toml

Windows PowerShell 中对应：

text
$HOME\.codex\config.toml

文件不存在时可以创建。自定义模型提供商是本机个人配置，必须放在用户级文件中；项目内的 .codex/config.toml 不能覆盖 model_provider 和 model_providers 等机器级提供商设置。

第 4 步：写入完整配置 ​

toml
model = "gpt-5.6-sol"
model_provider = "apibest"
model_reasoning_effort = "medium"
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 提供商
model_reasoning_effort模型推理强度，本文采用均衡的 medium 起步
approval_policy超出普通操作范围时请求用户确认
sandbox_mode默认只允许在当前工作区写入
base_urlAPIBest 基础地址，保留 /v1
env_keyCodex 读取密钥的环境变量名称
wire_api使用适合推理和工具调用的 Responses API

不要把真实密钥写进 TOML

env_key = "APIBEST_API_KEY" 填的是环境变量名称，不是 API Key。不要添加 api_key = "真实密钥"，也不要把密钥直接替换进 env_key。

第 5 步：为什么使用 Responses API ​

Codex 不只是让模型生成一段文字，它还要处理文件读取、命令执行、工具结果回传和多轮任务。OpenAI 当前 GPT-5.6 指南建议推理、工具调用和多轮工作流使用 Responses API，因此配置中使用：

toml
wire_api = "responses"

第三方 API 能返回普通聊天内容，不等于它已经完整兼容 Codex。正式使用前还要验证流式事件、工具调用和长上下文。

七、验证 GPT-5.6-sol 是否配置成功 ​

1. 检查环境变量 ​

macOS、Linux 或 WSL：

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

PowerShell：

powershell
if ($env:APIBEST_API_KEY) { "APIBEST_API_KEY 已设置" }

不要使用 echo 输出完整密钥，否则可能出现在终端日志或截图中。

2. 在测试项目中启动 ​

bash
cd /你的项目路径
codex

第一次建议使用一个小型 Git 项目，不要直接打开包含生产密钥或大量未提交改动的重要仓库。

3. 先测试只读任务 ​

输入：

阅读当前项目的 README、目录结构和主要配置文件，说明项目使用的技术栈，以及安装、测试和构建命令。不要修改文件，也不要安装依赖。

这一步可以确认 Codex 能否读取上下文和返回稳定结果，又不会立刻改动代码。

4. 再测试文件修改和命令执行 ​

只读任务成功后，可以输入：

为当前项目中最简单的工具函数补充一个边界条件测试。只修改相关测试文件，沿用现有风格，完成后运行对应测试并汇报结果。

检查 Codex 是否完成了以下闭环：

  1. 找到正确文件。
  2. 生成可审查的修改。
  3. 发起工具调用并运行测试。
  4. 正确读取工具结果。
  5. 在最终回复中说明改动和验证结果。

只有纯文本回答正常、工具调用正常、结果回传正常，才能说明自定义 API 基本适合日常 Codex 工作。

八、GPT-5.6-sol 怎么设置推理强度 ​

GPT-5.6 支持多个推理强度。对 Codex 日常开发，建议先从 medium 开始，而不是一律设到最高：

toml
model_reasoning_effort = "medium"

可以根据任务类型调整：

任务类型建议起点说明
查找文件、简单解释、小修复low更看重响应速度
常规功能开发和调试medium质量与速度较均衡
复杂重构、疑难故障、重要审查high 或 xhigh先确认更高强度确实改善结果

不要默认使用最高强度。更高推理强度通常意味着更长等待时间和更多消耗，而且很多失败其实来自目标不清、缺少验收标准或项目规则不完整。

更有效的任务写法是明确四件事：

  • 目标是什么。
  • 允许修改哪些范围。
  • 有哪些行为不能改变。
  • 用什么测试或结果验收。

九、适合 GPT-5.6-sol 的 Codex 提示词 ​

阅读项目 ​

阅读 README、AGENTS.md 和主要配置文件，说明项目结构、核心模块、启动方式和测试命令。先不要修改任何文件。

修复 Bug ​

修复用户保存资料后页面仍显示旧数据的问题。先定位根因，只修改相关模块；保持现有 API 契约，补充回归测试并运行对应测试。

开发功能 ​

为订单列表增加按状态筛选。沿用现有组件和数据请求方式，支持清空筛选并保留加载、空数据和错误状态；完成后运行相关测试和构建。

代码审查 ​

审查当前分支相对主分支的改动，优先查找功能错误、安全风险、兼容性回归和缺失测试。按严重程度列出问题，并引用文件和行号。不要修改代码。

大任务拆解 ​

先阅读相关模块并给出简短实施计划，说明会修改的文件、关键风险和验证方式。确认现有实现后直接完成范围内改动；遇到会改变公开接口的歧义时再询问我。

GPT-5.6 更善于根据上下文理解目标，但这不意味着可以省略关键约束。不要堆砌重复指令，保留真正影响结果的业务规则、权限边界和验收标准即可。

十、Codex 的权限怎么选 ​

新手建议使用：

toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

workspace-write 可以满足大多数本地代码修改，同时限制默认写入范围。Codex 请求批准时，应检查：

  • 命令是否与当前任务直接相关。
  • 是否会删除或覆盖文件。
  • 是否访问项目目录以外的位置。
  • 是否安装新软件或连接外部服务。
  • 是否可能上传源码、日志或密钥。

不要为了少点几次确认，就把所有权限长期设为完全开放。

十一、国内使用常见错误 ​

1. 401 或 403 ​

通常是 API Key 不存在、失效、没有模型权限，或者 Codex 进程没有继承环境变量。确认 env_key 与 APIBEST_API_KEY 拼写完全一致，并从设置变量的同一个终端启动 Codex。

2. 模型不存在 ​

检查 APIBest 控制台中是否确实显示 gpt-5.6-sol，不要把网页展示名称自行改写成模型 ID。不同账号可见模型可能不同。

3. 404 或地址错误 ​

正确基础地址是：

text
https://apibest.org/v1

不要写成 .../v1/v1，也不要在 base_url 后自行添加 /responses。

4. 能聊天但不能读写文件 ​

先检查 Codex 本地权限。如果权限正常，却没有工具调用或工具结果回传后中断，通常需要继续确认第三方 API 对 Responses 流式协议和工具调用的兼容情况。

5. 流式输出中断或长任务超时 ​

先换成短提示词和小项目，排除上下文过大。再检查网络稳定性、服务端限流、模型负载和网关超时。不要在不清楚是否已经计费的情况下无限重复请求。

6. 修改配置后不生效 ​

确认修改的是用户主目录下的 ~/.codex/config.toml，检查 TOML 引号和表名，然后完全退出 Codex 并新建任务。已经打开的任务可能保留旧模型状态。

完整排查步骤见 Codex 自定义 API 常见错误与排查。

十二、推荐的安全工作流 ​

  1. 在 Git 仓库根目录启动 Codex。
  2. 开始前运行 git status，了解已有改动。
  3. 先让 Codex 读取项目规则，再描述任务。
  4. 明确修改范围、不可改变的行为和验证命令。
  5. 完成后检查实际差异，不只看 Codex 的文字总结。
  6. 确认测试结果，再由你决定是否提交。

密钥和敏感文件应加入 .gitignore。即使文件没有提交，也不要主动要求 Codex 读取不属于当前任务的生产配置。

十三、总结 ​

国内安装 Codex 本身并不复杂：准备 Node.js 和 Git，执行 npm install -g @openai/codex，再用 codex --version 验证即可。真正需要仔细处理的是模型 API、环境变量、Responses 协议与本地权限。

使用 APIBest 时，访问 https://apibest.org 获取 API Key，将密钥放入 APIBEST_API_KEY 环境变量，并在 ~/.codex/config.toml 中配置 gpt-5.6-sol、https://apibest.org/v1 和 wire_api = "responses"。最后用“只读任务 -> 小型修改 -> 测试命令”的顺序验证完整工作流。

参考资料 ​

面向中文开发者的独立社区指南，非 OpenAI 官方网站。

Copyright © 2026 Codex 中文指南