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

| 客户端 | 适合谁 | 安装 |
|---|---|---|
| Codex App | 想要图形界面,新手首选 | 官网下载 |
| Codex CLI | 习惯命令行 | npm install -g @openai/codex |
| VSCode / Cursor 插件 | 想在编辑器里用 | 扩展市场搜 openai.chatgpt |
Codex App
Codex App 已并入 ChatGPT 桌面客户端(macOS / Windows)。下载安装、切到 Codex 模式和发第一条消息,按 快速使用 操作即可。
接通后主界面如下(左侧为项目、插件、自动化与设置入口,底部可查看 codexzh 连接状态、权限和模型档位):

常用设置入口
- 换模型:修改
config.toml的model字段(或直接在 CC-Switch 里改),彻底退出重开生效,见 模型与切换 - MCP / 自动化 / 归档对话:
设置 → MCP servers、左侧自动化标签页、设置内 恢复聊天记录 - 保留官方账号登录:见 官方账号 + 平台 API
- 完整功能:官方 Codex App 文档 · Explore 示例
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 22powershell
# 方式一:官网下载安装包(推荐新手)
# 访问 https://nodejs.org,下载 LTS 版本(选 v22)安装即可
# 方式二:使用 nvm-windows(推荐需要多版本的用户)
# 下载 nvm-setup.exe:https://github.com/coreybutler/nvm-windows/releases
# 安装后在管理员终端运行:
nvm install 22
nvm use 22bash
# 安装 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.com4. 启动使用
配置写好后,进入任意项目目录运行:
bash
codex能进入对话界面并正常回复,即接入成功。
常用命令速查

文字版 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.chatgpt - 市场链接:https://marketplace.visualstudio.com/items?itemName=openai.chatgpt
认准 OpenAI 官方认证标识,避免装到仿冒扩展。



2. 重启并验证
配置写好后:
- 重启 VSCode / Cursor,找到 Codex 插件并打开
- 打开任意项目(插件在空窗口下会提示先打开项目),发起一次对话
Cursor 里需要点插件页面的箭头展开 Codex 面板,不要用 Cursor 自带的 Agent 聊天框。
3. 指定模型
插件读取 config.toml 里的 model 字段:
toml
model = "gpt-5.6-terra"保存后重启编辑器生效。可选型号和切换方法见 模型与切换。
使用注意事项
- 历史会话丢失:可能是插件更新导致的兼容问题,见 恢复聊天记录
- Windows 上遇到 Git 相关异常:等官方插件更新