Codex 常用操作手册

Codex 是 OpenAI 推出的 AI 编程智能体（Agent），能够读取项目文件、理解代码结构、修改代码、运行命令，并完成实际的开发任务。它不是简单的“代码问答工具”，而是一个能真正“动手”的执行型搭档。

一、安装与登录

1. 前置准备

• Node.js ≥ 22（硬性要求）
• ChatGPT Plus/Pro/Team/Business/Edu 订阅（免费账号无法使用 CLI）
• Git（建议安装）

2. 安装方式

方式一：CLI（终端）

macOS / Linux：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

或通过 npm：

npm install -g @openai/codex

或通过 Homebrew（macOS）：

brew install --cask codex

Windows（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Windows 用户注意：Windows 支持仍处于实验性阶段，建议在 WSL2 中运行以获得最佳体验。

方式二：桌面 App

前往官网下载 macOS 或 Windows 版本，安装后用 ChatGPT 账号登录即可。

方式三：IDE 插件

在 VS Code / Cursor / Windsurf 的插件市场中搜索“Codex”，选择 OpenAI 官方版本安装。

3. 验证安装

codex --version

4. 首次登录

运行 codex 后，选择 Sign in with ChatGPT 登录账号。

二、三种入口的选择

入口	适合场景	特点
桌面 App	项目级工作、长任务、处理本地文件	可视化界面，零门槛上手
CLI	终端党、脚本与 CI	最纯粹的 Codex 体验
IDE 插件	日常编码开发	贴近编辑器工作流

新手建议：日常写代码用 IDE 扩展，想体验最完整的 Codex 用 CLI。

三、CLI 常用操作

1. 启动与进入

进入项目目录后启动：

cd /path/to/your/project
codex

启动后进入全屏 TUI（终端交互界面），底部输入框可输入指令。

2. 自然语言对话

直接在输入框用中文描述任务即可，例如：

• “帮我解释这个项目是干什么的”
• “给这个仓库加一个 .gitignore，忽略 node_modules 和 dist 目录”
• “修复订单导出空白页”

3. 常用快捷键

快捷键	作用
Enter	发送消息
↑	翻找历史输入
Ctrl+D	退出 Codex
Ctrl+K	清屏
Ctrl+O	选择 Codex Cloud 环境

4. 特殊输入前缀

前缀	作用
@文件名	触发文件模糊搜索，精准指定文件
!命令	直接执行 Shell 命令

5. 快捷操作流程验证

# 1. 建空目录并启动
mkdir codex-demo && cd codex-demo
codex

# 2. 查看状态
/status

# 3. 试跑命令
!echo hello

# 4. 查看改动
/diff

# 5. 退出
/exit

四、斜杠命令速查（会话内使用）

斜杠命令是 Codex 会话中的“控制指令”——不是说给模型听让它干活，而是直接命令 Codex 程序本身。

CLI 常用斜杠命令

命令	作用
/status	查看当前会话配置（模型、审批策略、上下文等）
/model [模型名]	切换模型
/diff	查看 Git 视角的所有改动
/compact	将对话压缩成摘要，释放 Token
/clear	清空对话重新开始
/init	在当前目录生成 AGENTS.md 脚手架
/review	触发代码审查
/permissions	调整权限策略
/mcp	管理 MCP 连接
/new	开启新对话线程
/list	列出所有线程
/exit	退出交互会话

CLI 斜杠命令共计 40 多条，以上为最常用部分。

桌面 App / IDE 斜杠命令

桌面 App 和 IDE 插件支持的斜杠命令较少（分别约 6 条和 8 条），以界面实际显示为准。

五、权限与安全

Codex 提供三级权限模式：

模式	说明
默认权限	AI 可读取和编辑工作区文件，需要额外权限时会询问
自动审查	AI 自动审查操作（新手推荐）
完全访问	AI 可自由操作，不会弹出确认框

Codex 有沙盒机制，危险操作会先询问确认。建议从低风险任务开始，逐步建立信任。

六、常见任务示例

1. 分析项目结构

“先不要改文件，帮我解释这个项目怎么运行。”

2. 修复 Bug

“这个命令报错如下，请定位原因并做最小修复。”

3. 补充测试

“参考现有测试风格，为这个函数补 3 个边界用例。”

4. 代码审查

“只看当前 diff，找可能导致 bug 的问题。”

5. 文件操作

“帮我分析这个文件夹的空间占用情况，找出所有超过 500MB 的大文件。”

七、进阶配置

1. AGENTS.md

在项目根目录创建 AGENTS.md，写入项目约定和规则，Codex 每次开工前都会读取。

2. config.toml

配置文件位于 ~/.codex/config.toml，可自定义模型、网关、权限等。

3. 切换模型

CLI 中使用 /model 命令切换，例如选择 gpt-5-codex + high 推理强度。

八、参考资源

• 官方文档：https://developers.openai.com/codex/[reference:61]
• 官方 CLI 仓库：https://github.com/openai/codex
• CodexGuide 中文教程：https://codexguide.ai/
• Awesome Codex Guide：https://github.com/geekjourneyx/awesome-codex-guide