GPT-5.5 Codex 国内使用教程：Windows / macOS / Linux 配置

GPT-5.5 Codex 国内使用教程：Windows / macOS / Linux 配置方法

本文按 API Key 方式配置 Codex，适合国内环境下使用 GPT-5.5 Codex。

1. Codex 是什么

Codex 是 OpenAI 的 AI 编程智能体。它不是简单的代码补全工具，而是可以进入项目目录，读取文件、理解上下文、修改代码、运行命令、执行测试，并根据运行结果继续调整。

例如你可以在项目目录里直接让它做这些事：

text 复制代码

先不要修改任何文件。请阅读当前项目结构，说明技术栈、启动方式、测试方式和核心模块。

也可以让它修复问题：

text 复制代码

运行测试并定位失败原因。请先说明问题，再修改代码，最后重新运行相关测试。

或者开发功能：

text 复制代码

为用户模块增加邮箱验证码登录。保持现有代码风格，补充必要测试，并总结修改了哪些文件。

GPT-5.5 Codex 更适合处理复杂项目里的长上下文任务，比如跨文件分析、重构、自动补测试、排查报错、整理文档等。

2. 国内使用前要准备什么

国内环境使用 Codex，除了安装 CLI，还要准备一个可用的 API 访问入口。本文使用 API Key 方式配置，整体流程如下：

安装 Node.js。
安装 Codex CLI。
创建 Codex token。
配置 auth.json。
配置 config.toml。
进入项目目录运行 codex。

文中的接口地址使用下面这个页面作为示例：

示例 API 控制台：https://codex.tokenshop.pro/
截图版配置流程：https://my.feishu.cn/wiki/OWqFw4Bmni2xVRk5farccvdwnAf?from=from_copylink

本文下面会分别写 Windows、macOS、Linux 的配置方式。

3. 环境要求

环境	说明
Node.js	使用 22 或以上版本
npm	安装 Node.js 后自带
Git	方便查看 Codex 修改了哪些文件
Codex CLI	通过 npm 安装
API token	用于 Codex 请求模型

检查 Node.js 和 npm：

bash 复制代码

node -v
npm -v

如果没有安装 Node.js，先去 Node.js 官网安装 LTS 版本，再继续后面的步骤。

4. 准备 API Token

下面以一个 API 控制台页面为例：
https://codex.tokenshop.pro/

按页面流程完成登录后，创建一个用于 Codex 的 token。后面会把这个 token 写入 auth.json。如果你使用的是其他兼容服务，流程也是类似的：创建 token、查看接口地址、填入 Codex 配置。

如果是第一次配置，可以对照截图版教程操作：
https://my.feishu.cn/wiki/OWqFw4Bmni2xVRk5farccvdwnAf?from=from_copylink

注意：token 不要公开，不要提交到 Git 仓库，也不要放到博客截图里。下面示例统一用 sk-xxx 作为占位符。

5. Windows 配置方法

5.1 安装 Codex CLI

打开 PowerShell，先检查 Node.js：

powershell 复制代码

node -v
npm -v

安装 Codex：

powershell 复制代码

npm install -g @openai/codex

如果 npm 下载比较慢，可以换成国内镜像：

powershell 复制代码

npm install -g @openai/codex --registry=https://registry.npmmirror.com

检查是否安装成功：

powershell 复制代码

codex --version

5.2 创建 `.codex` 目录

进入当前用户目录：

text 复制代码

C:\Users\你的用户名\

创建目录：

text 复制代码

.codex

最终路径类似：

text 复制代码

C:\Users\你的用户名\.codex

5.3 创建 `auth.json`

在 .codex 目录里创建文件：

text 复制代码

auth.json

写入下面内容：

json 复制代码

{
  "OPENAI_API_KEY": "sk-xxx"
}

把 sk-xxx 替换成你在 API 控制台创建的 token。示例页面如下：
https://codex.tokenshop.pro/

5.4 创建 `config.toml`

继续在 .codex 目录里创建：

text 复制代码

config.toml

写入：

toml 复制代码

model_provider = "codex_api"
model = "gpt-5.5"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.codex_api]
name = "Codex API"
# 示例地址，实际以你的 API 控制台为准
base_url = "https://codex.tokenshop.pro/v1"
wire_api = "responses"

这里的 base_url 是示例地址；如果你的控制台显示了其他接口地址，以实际页面为准。

5.5 启动 Codex

关闭 PowerShell，重新打开，然后进入你的项目：

powershell 复制代码

cd D:\your-project
codex

进入 Codex 后先输入：

text 复制代码

/status

确认当前模型、provider 和 API 配置是否生效。

6. macOS 配置方法

6.1 安装 Codex CLI

检查 Node.js：

bash 复制代码

node -v
npm -v

安装 Codex：

bash 复制代码

npm install -g @openai/codex

如果提示权限不足：

bash 复制代码

sudo npm install -g @openai/codex

国内 npm 下载慢时：

bash 复制代码

npm install -g @openai/codex --registry=https://registry.npmmirror.com

6.2 创建配置目录

bash 复制代码

mkdir -p ~/.codex

6.3 写入 `auth.json`

bash 复制代码

vi ~/.codex/auth.json

内容如下：

json 复制代码

{
  "OPENAI_API_KEY": "sk-xxx"
}

sk-xxx 替换为你创建的 token。

6.4 写入 `config.toml`

bash 复制代码

vi ~/.codex/config.toml

内容如下：

toml 复制代码

model_provider = "codex_api"
model = "gpt-5.5"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.codex_api]
name = "Codex API"
# 示例地址，实际以你的 API 控制台为准
base_url = "https://codex.tokenshop.pro/v1"
wire_api = "responses"

保存后进入项目目录：

bash 复制代码

cd ~/your-project
codex

7. Linux 配置方法

7.1 安装 Node.js

Ubuntu / Debian 可以使用：

bash 复制代码

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

检查版本：

bash 复制代码

node -v
npm -v

7.2 安装 Codex CLI

bash 复制代码

npm install -g @openai/codex

如果权限不足：

bash 复制代码

sudo npm install -g @openai/codex

如果下载慢：

bash 复制代码

npm install -g @openai/codex --registry=https://registry.npmmirror.com

7.3 创建配置文件

bash 复制代码

mkdir -p ~/.codex
vi ~/.codex/auth.json

写入：

json 复制代码

{
  "OPENAI_API_KEY": "sk-xxx"
}

继续创建配置：

bash 复制代码

vi ~/.codex/config.toml

写入：

toml 复制代码

model_provider = "codex_api"
model = "gpt-5.5"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.codex_api]
name = "Codex API"
# 示例地址，实际以你的 API 控制台为准
base_url = "https://codex.tokenshop.pro/v1"
wire_api = "responses"

启动：

bash 复制代码

cd ~/your-project
codex

8. 配置参数说明

上面的 config.toml 里有几个关键参数：

参数	作用
`model_provider`	指向下面定义的 API provider
`model`	默认使用的模型
`model_reasoning_effort`	推理强度，复杂任务可用 `high`
`disable_response_storage`	关闭响应存储
`preferred_auth_method`	使用 API Key 方式
`base_url`	API 请求地址
`wire_api`	Codex 请求接口类型，使用 `responses`

其中最容易写错的是 base_url 和模型名。下面只是示例地址：

toml 复制代码

# 示例地址，实际以你的 API 控制台为准
base_url = "https://codex.tokenshop.pro/v1"

实际使用时，按你自己的 API 控制台展示的接口地址填写。

9. 第一次启动后怎么测试

配置完成后，不要一上来就让 Codex 大规模修改项目。先确认它能正常读取项目、调用模型、返回结果。

9.1 查看状态

text 复制代码

/status

看一下当前 model、provider、auth、sandbox 等信息是否正常。

9.2 查看模型

text 复制代码

/model

如果 gpt-5.5 不可用，先确认当前 token 是否支持这个模型，或者临时切换到页面显示的可用模型。

9.3 只读分析项目

text 复制代码

先不要修改任何文件。请阅读当前项目，说明技术栈、目录结构、启动方式、测试方式和核心模块。

如果它能准确说出项目结构，说明基础配置已经通了。

9.4 做一个小修改

text 复制代码

请找出当前项目里最适合补充测试的一个函数，先说明理由，不要直接修改。

确认方案没问题后再继续：

text 复制代码

按刚才的方案补充测试，修改后运行相关测试，并总结改动文件。

10. 常用命令

命令	作用
`/status`	查看当前 Codex 状态
`/model`	查看或切换模型
`/approvals`	调整命令审批方式
`/init`	初始化项目指令文件
`/diff`	查看当前改动
`/clear`	清空上下文
`/help`	查看帮助

11. 常见问题

11.1 `codex` 命令不存在

通常是 npm 全局路径没有加入环境变量。先检查：

bash 复制代码

npm bin -g

然后把输出路径加入 PATH。也可以重新安装：

bash 复制代码

npm install -g @openai/codex --registry=https://registry.npmmirror.com

11.2 npm 安装很慢

使用国内 npm 镜像：

bash 复制代码

npm install -g @openai/codex --registry=https://registry.npmmirror.com

npm 镜像只影响安装速度，不影响模型请求。模型请求是否正常，主要看 config.toml 里的 base_url、token 和模型名。

11.3 API Key 无效

检查：

auth.json 文件名是否正确。
OPENAI_API_KEY 是否拼写正确。
token 是否完整，没有多余空格或换行。
token 是否仍然有效。

11.4 `model not found`

可能原因：

当前 token 暂不支持 gpt-5.5。
控制台显示的模型名和本地配置不一致。
Codex CLI 版本较旧。

处理方式：

bash 复制代码

npm install -g @openai/codex@latest --registry=https://registry.npmmirror.com

然后进入 Codex 输入：

text 复制代码

/model

按实际可用模型切换。

11.5 配置文件不生效

检查：

Windows 文件名不要变成 config.toml.txt。
.codex 目录是否放在当前用户目录下。
修改配置后是否重新打开终端。
auth.json 和 config.toml 是否都在同一个 .codex 目录中。

11.6 能启动但请求失败

重点检查这段：

toml 复制代码

[model_providers.codex_api]
name = "Codex API"
# 示例地址，实际以你的 API 控制台为准
base_url = "https://codex.tokenshop.pro/v1"
wire_api = "responses"

base_url 要包含正确路径。上面的地址只作为示例，wire_api 保持为 responses。

12. 使用时的几个习惯

12.1 先让 Codex 读项目

第一次进入项目时，先让它分析，不要直接修改：

text 复制代码

先阅读当前项目，不要修改文件。请说明项目结构、运行方式和测试方式。

12.2 修改前先要方案

text 复制代码

请先说明你准备修改哪些文件、为什么这样改，不要直接动代码。

确认方向后再执行：

text 复制代码

按这个方案修改，并运行相关测试。

12.3 保持 Git 可查看 diff

Codex 会直接修改文件，项目最好先初始化 Git：

bash 复制代码

git init

修改后查看：

bash 复制代码

git diff

12.4 不要公开 token

auth.json 里是真实 token。写教程、截图、录屏时，把它替换成 sk-xxx。

13. 总结

国内使用 GPT-5.5 Codex，可以按下面流程走：

安装 Node.js 和 Codex CLI。
打开 API 控制台创建 token，本文示例地址为 https://codex.tokenshop.pro/。
在用户目录创建 .codex/auth.json。
在用户目录创建 .codex/config.toml。
写入 API 控制台提供的 base_url，并设置 wire_api = "responses"。
进入项目目录运行 codex。
使用 /status 和 /model 验证配置。

截图版步骤放在这里：
https://my.feishu.cn/wiki/OWqFw4Bmni2xVRk5farccvdwnAf?from=from_copylink

把这套配置跑通后，就可以让 Codex 参与项目分析、功能开发、Bug 修复和测试补充了。

GPT-5.5 Codex 国内使用教程：Windows / macOS / Linux 配置