Skip to content

Codex 客户端接入 CodexZH(App / CLI / 插件) ​

Codex 有三种客户端:Codex App、Codex CLI、VSCode / Cursor 插件,都读同一份配置(用户目录下的 .codex 文件夹)。按 快速使用 在控制台选 Codex 导入一次,三个都能用。

在 CodexZH 控制台 CC Switch 一键导入界面选择 Codex 客户端

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

Codex App ​

Codex App 已并入 ChatGPT 桌面客户端(macOS / Windows)。下载安装、切到 Codex 模式和发第一条消息,按 快速使用 操作即可。

接通后主界面如下(左侧为项目、插件、自动化与设置入口,底部可查看 codexzh 连接状态、权限和模型档位):

Codex App 主界面与常用入口

常用设置入口 ​

Codex CLI ​

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

1. 检查 Node.js / npm ​

打开终端运行:

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

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

2. 安装 Node.js(按你的系统选一种) ​

bash
# 安装 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
powershell
# 方式一:官网下载安装包(推荐新手)
# 访问 https://nodejs.org,下载 LTS 版本(选 v22)安装即可

# 方式二:使用 nvm-windows(推荐需要多版本的用户)
# 下载 nvm-setup.exe:https://github.com/coreybutler/nvm-windows/releases
# 安装后在管理员终端运行:
nvm install 22
nvm use 22
bash
# 安装 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 ​

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

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

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

4. 启动使用 ​

配置写好后,进入任意项目目录运行:

bash
codex

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

常用命令速查 ​

Codex CLI 斜杠命令、快捷键、标志参数与工作流完整速查表

文字版 Codex CLI 常用命令与参数速查(支持复制与搜索)

高频斜杠命令(Slash Commands)

命令说明
/clear清空当前会话并开始新对话
/compact压缩当前上下文摘要,节省 token
/copy / /diff复制最近一次完整输出 / 查看当前代码改动 diff
/status / /exit查看当前线程状态、模式和模型信息 / 退出 CLI(同 /quit)
/model / /fast切换当前模型与推理档位 / 切换 Fast 模式
/permissions / /personality调整审批与自动执行权限 / 切换代理交互风格
/agent / /mcp / /apps切换 agent 或 subagent 线程 / 列出当前可用 MCP 工具 / 浏览 connectors
/mention / /init / /logout附加文件或目录到当前对话 / 生成 AGENTS.md 脚手架 / 退出登录清除本地认证

常用 CLI 启动命令与全局标志

命令 / 参数说明
codex启动交互式 Codex CLI
codex exec "<task>"非交互式执行单次任务,适合脚本与 CI(可搭配 --json、--ephemeral)
-m, --model <model>临时指定本次运行模型(覆盖 config.toml)
-c key=value / -p, --profile单次覆盖配置项(支持 JSON 值)/ 加载指定 profile
-C, --cd <path> / --add-dir指定工作目录后启动 / 额外授予可写目录
-a, --ask-for-approval审批策略:untrusted | on-request | never
-s, --sandbox沙盒模式:read-only | workspace-write | danger-full-access
--full-auto / -i, --image开启低摩擦本地自动模式 / 给初始提示附加图片

常用快捷键与输入前缀:Ctrl + C 中断当前运行、Ctrl + D 退出、Ctrl + L 清屏、Tab 补全文件或命令;/ 打开斜杠命令、@文件或目录 引用上下文、! 直接执行 shell 命令。

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 官方认证标识,避免装到仿冒扩展。

在 VSCode 或 Cursor 扩展市场搜索 openai.chatgpt 找到 OpenAI 官方 Codex 扩展核对 OpenAI 官方认证标识并点击安装 Codex IDE 插件重启 VSCode 或 Cursor 后打开右侧 Codex 插件面板开始对话

2. 重启并验证 ​

配置写好后:

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

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

3. 指定模型 ​

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

toml
model = "gpt-5.6-terra"

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

使用注意事项 ​

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