客户端安装与使用

Codex 有三种客户端：ChatGPT 桌面客户端、Codex CLI（终端）、VSCode / Cursor 插件。三者都读用户目录下的 .codex 文件夹，配置写一次，三个都能用。

新手用 ChatGPT 客户端。习惯终端用 CLI，想在编辑器里写代码用插件。

客户端	适合谁	安装
ChatGPT 客户端	新手，想要图形界面	官网下载
Codex CLI	习惯命令行	npm install -g @openai/codex
VSCode / Cursor 插件	想在编辑器里用	扩展市场搜 openai.chatgpt

还没写入配置的，先按 配置并开始使用 第 2 步选一种方式配好。配置写完后，按下面对应客户端打开即可。

ChatGPT 客户端

Codex App 已并入 ChatGPT 桌面客户端，提供并行任务、Git 差异查看、Worktree、内置终端、自动化任务等功能。

下载安装

• 官网下载页：https://openai.com/zh-Hans-CN/codex/
• 备用地址：https://chatgpt.com/codex

使用步骤

1. 打开客户端，点左上角把模式切到 Codex。使用 CodexZH 配置时只能在 Codex 模式下用，ChatGPT 模式需要官方账号
2. 选择项目文件夹，有历史项目时可直接从列表选
3. 运行方式选 Local，让 Codex 在本机运行
4. 发送任务，例如「Tell me about this project」「Find and fix bugs in my codebase with minimal, high-confidence changes.」

更多示例见官方 Explore 页面，完整功能说明见 Codex App 官方文档。

提示「Work browser access requires an authenticated account」

左上角的 ChatGPT / Work 入口需要验证 ChatGPT 账号，第三方 API 配置不能代替这项认证。在 Work 里发起任务或继续原来的绘画任务时会出现这个报错。

解决方法：

1. 点击左上角入口，切换到 Codex
2. 在 Codex 中新建会话，重新发送任务，不要在原来的 Work 会话里继续

Codex CLI

Codex CLI 是 OpenAI 官方的终端编程助手，依赖 Node.js 22 以上版本。

1. 检查 Node.js / npm

打开终端运行：

node -v   # 应显示 v22.x.x
npm -v    # 应显示 10.x.x

提示「找不到命令」或版本过低，先完成下一步；已经装好的直接跳到第 3 步。

2. 安装 Node.js（按你的系统选一种）

macOS（推荐 nvm）

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 重新打开终端后，安装 Node.js 22
nvm install 22
nvm use 22

Windows

# 方式一：官网下载安装包（推荐新手）
# 访问 https://nodejs.org，下载 LTS 版本（选 v22）安装即可

# 方式二：使用 nvm-windows（推荐需要多版本的用户）
# 下载 nvm-setup.exe：https://github.com/coreybutler/nvm-windows/releases
# 安装后在管理员终端运行：
nvm install 22
nvm use 22

Linux

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 重新打开终端后，安装 Node.js 22
nvm install 22
nvm use 22

装完后重新打开终端，再跑一遍第 1 步的两条命令确认版本。

3. 安装 Codex CLI

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

显示版本号即安装成功。国内网络下安装慢，可临时指定 npm 镜像：

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

4. 启动使用

配置写好后，进入任意项目目录运行：

codex

能进入对话界面并正常回复，即接入成功。

常用命令速查

npm 全局安装提示权限不足（permission denied）

• Windows：用管理员打开 PowerShell 再重试，或把 npm 全局目录配置到用户目录
• macOS / Linux：用 nvm 管理 Node.js，避免全局权限问题

VSCode / Cursor 插件

不要用 IDE 自带的 Agent

Cursor、Trae 等 IDE 自带的 Agent 聊天框不支持 CodexZH。请安装 OpenAI 官方 Codex 插件，GPT 模型针对 Codex 客户端训练，适配最好。

1. 安装官方扩展

在扩展市场搜索并安装 OpenAI 官方扩展：

• 扩展：openai.chatgpt
• 市场链接：https://marketplace.visualstudio.com/items?itemName=openai.chatgpt

认准 OpenAI 官方认证标识，避免装到仿冒扩展。

2. 重启并验证

配置写好后：

1. 重启 VSCode / Cursor，找到 Codex 插件并打开
2. 打开任意项目（插件在空窗口下会提示先打开项目），发起一次对话

Cursor 里需要点插件页面的箭头展开 Codex 面板，不要用 Cursor 自带的 Agent 聊天框。

3. 指定模型

插件读取 config.toml 里的 model 字段：

model = "gpt-5.6-terra"

保存后重启编辑器生效。可选型号和切换方法见 模型与切换。

使用注意事项

• 历史会话丢失：可能是插件更新导致的兼容问题，见 恢复聊天记录
• Windows 上遇到 Git 相关异常：等官方插件更新