Codex 常用命令 | XPoet's Blog

Codex 是 OpenAI 官方推出的 AI 编程助手，支持在终端、IDE、桌面应用和 Web 中使用。本文主要介绍 Codex CLI，也就是在终端里运行的版本。

它可以读取代码库、修改文件、执行命令、查看 Git Diff、做代码审查，也可以接入 MCP、Skills、Cloud Tasks 等能力。

用好下面这些命令，日常开发、排查 Bug、重构模块、写测试、生成文档都会顺手很多。

安装与登录

如果还没安装 Codex，可以先安装 CLI。官方支持安装脚本、npm 和 Homebrew 等方式。

命令	作用
`brew install --cask codex`	使用 Homebrew 安装 Codex，适合 macOS 用户
`npm install -g @openai/codex`	使用 npm 全局安装 Codex
`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`	macOS / Linux 官方安装脚本
`codex login`	登录 Codex，默认会打开浏览器进行 ChatGPT OAuth 登录
`codex login status`	查看当前是否已登录，适合脚本中判断登录状态
`codex logout`	退出登录，清除本地保存的认证信息

如果你是 ChatGPT Plus、Pro、Business、Edu 或 Enterprise 用户，可以直接用 ChatGPT 账号登录 Codex。官方也支持 API Key 登录。

启动命令

这些是最常用的 Codex CLI 启动命令。官方文档中，codex 是交互式终端 UI；也可以直接在命令后面传入初始 Prompt，或者通过 --cd 指定工作目录。

命令	作用
`codex`	启动 Codex CLI，进入当前目录的交互式对话
`codex "解释一下这个项目结构"`	启动 Codex，并直接发送一条初始指令
`codex --cd ~/projects/my-app`	打开指定目录，无需先手动 `cd`
`codex -C ~/projects/my-app`	`--cd` 的简写形式
`codex --model gpt-5.5`	指定本次会话使用的模型
`codex -m gpt-5.5`	`--model` 的简写形式
`codex --image screenshot.png "分析这个报错"`	启动时附带图片，让 Codex 结合截图分析问题
`codex -i screenshot.png "解释这个页面问题"`	`--image` 的简写形式
`codex --search "帮我查一下这个依赖的最新用法"`	开启实时 Web 搜索
`codex --profile work`	使用指定配置 Profile 启动
`codex --add-dir ../backend`	在当前工作目录外，额外授权一个可访问目录
`codex --sandbox read-only`	只读模式，适合先让 Codex 分析项目，不希望它改文件
`codex --sandbox workspace-write`	允许 Codex 修改工作区内文件，日常开发推荐
`codex --sandbox danger-full-access`	完全访问模式，权限很高，新手慎用
`codex --dangerously-bypass-approvals-and-sandbox`	跳过审批和沙箱限制，风险很高，只建议在隔离环境中使用
`codex --yolo`	上面危险模式的别名，慎用

日常开发推荐用这个组合：

1	codex --cd ~/projects/my-app --sandbox workspace-write --ask-for-approval on-request

这样 Codex 可以在项目内正常修改和执行命令，但遇到越界操作时仍然需要你确认。

会话恢复

Codex 的恢复会话不是 --resume，而是 codex resume 子命令。官方文档说明，codex resume 可以恢复指定会话，也可以恢复当前目录最近一次会话。

命令	作用
`codex resume`	打开会话选择器，选择之前的会话继续
`codex resume --last`	恢复当前目录下最近一次会话
`codex resume --all`	显示所有目录中的历史会话
`codex resume --last --all`	恢复所有目录范围内最近一次会话
`codex resume <SESSION_ID>`	按会话 ID 恢复指定会话
`codex fork`	分叉一个历史会话，保留原会话不变，另开一条新线

这个命令很适合长任务，比如你昨天让 Codex 分析了一个复杂 Bug，今天想继续：

1	codex resume --last

非交互命令

除了进入终端对话，Codex 还支持非交互模式，也就是让它执行一次任务后直接输出结果。官方推荐使用 codex exec，简写是 codex e。它适合脚本、CI、批量检查、自动生成文档等场景。

命令	作用
`codex exec "修复 CI 报错"`	非交互执行一次任务
`codex e "检查这个项目潜在问题"`	`codex exec` 的简写形式
`codex exec --cd ~/projects/my-app "生成 README"`	在指定目录中执行任务
`codex exec --json "分析当前变更"`	以 JSONL 形式输出事件，适合脚本处理
`codex exec -o result.md "总结这个项目"`	将最终回答写入文件
`codex exec --skip-git-repo-check "分析这个目录"`	允许在非 Git 仓库目录中执行
`codex exec resume --last "继续完成刚才的重构"`	恢复最近一次非交互任务并继续执行
`cat prompt.md \| codex exec -`	从标准输入读取 Prompt

例如，想让 Codex 自动检查当前项目并输出报告：

1	codex exec -o codex-report.md "检查当前项目的代码质量、潜在 Bug 和可优化点，输出 Markdown 报告"

桌面应用与云任务

Codex 不只有 CLI，也可以打开桌面应用，或者和 Codex Cloud 任务联动。官方命令列表中包括 codex app、codex cloud、codex apply 等命令。

命令	作用
`codex app`	打开 Codex 桌面应用
`codex app ~/projects/my-app`	在桌面应用中打开指定工作区
`codex cloud`	在终端中查看或操作 Codex Cloud 任务
`codex cloud list`	列出最近的 Cloud Tasks
`codex cloud exec --env ENV_ID "修复登录问题"`	在指定云环境中发起一个 Codex Cloud 任务
`codex apply <TASK_ID>`	将 Codex Cloud 任务生成的最新 diff 应用到本地工作区

如果你只是本地开发，用 codex 和 codex exec 就够了。

如果你想把长任务丢到云端跑，再把结果拉回本地，就可以了解 codex cloud 和 codex apply。

配置与诊断命令

这些命令主要用于排查 Codex 环境、更新 CLI、配置自动补全、管理功能开关。官方命令行参考中列出了这些子命令。

命令	作用
`codex doctor`	生成本地诊断报告，检查安装、配置、认证、Git、终端等问题
`codex doctor --summary`	只显示诊断摘要
`codex doctor --json`	输出机器可读的诊断结果
`codex update`	检查并更新 Codex CLI
`codex completion zsh`	生成 zsh 自动补全脚本
`codex completion bash`	生成 bash 自动补全脚本
`codex debug models`	查看当前 Codex 能看到的模型目录
`codex features list`	查看可用 Feature Flags
`codex features enable <feature>`	启用某个功能开关
`codex features disable <feature>`	禁用某个功能开关

如果 Codex 突然不能登录、不能执行命令、配置不生效，优先跑：

1	codex doctor

MCP 命令

Codex 支持 MCP，也就是 Model Context Protocol，可以接入外部工具和数据源。官方文档中，codex mcp 用来管理 MCP Server 配置，配置会写入 ~/.codex/config.toml。

命令	作用
`codex mcp list`	查看已配置的 MCP Server
`codex mcp list --json`	以 JSON 格式输出 MCP 配置
`codex mcp get <name>`	查看某个 MCP Server 配置
`codex mcp add <name> -- <command...>`	添加 stdio 类型 MCP Server
`codex mcp add <name> --url <url>`	添加 HTTP 类型 MCP Server
`codex mcp remove <name>`	删除某个 MCP Server
`codex mcp login <name>`	对支持 OAuth 的 MCP Server 进行登录
`codex mcp logout <name>`	退出某个 MCP Server 的 OAuth 登录
`codex mcp-server`	将 Codex 自身作为 MCP Server 暴露给其他工具

例如：

1	codex mcp list

进入 Codex 会话后，也可以输入：

/mcp

查看当前会话可用的 MCP 工具。

内置斜杠命令

这些命令在 Codex CLI 对话中输入，以 / 开头。官方文档说明，输入 / 可以打开命令弹窗，并通过斜杠命令切换模型、调整权限、压缩上下文、查看 diff 等。

会话管理

命令	作用
`/clear`	清空当前终端显示，并开始一个新聊天
`/new`	在不退出 CLI 的情况下开始新对话
`/resume`	从保存的会话列表中恢复历史会话
`/fork`	分叉当前会话，保留原会话不变，另开一个新线程
`/side`	开启一个临时侧边对话，不打断主任务
`/btw`	`/side` 的别名，适合“顺便问一句”
`/copy`	复制 Codex 最近一次完成的输出
`/exit`	退出 Codex CLI
`/quit`	与 `/exit` 相同，退出 CLI

/side 或 /btw 很适合这种场景：Codex 正在改一个复杂 Bug，你突然想问“这个函数原理是什么”，但又不想污染主线任务上下文。

上下文与文件管理

命令	作用
`/mention`	将指定文件或目录加入当前上下文
`/compact`	压缩当前对话历史，释放上下文空间
`/status`	查看当前模型、权限策略、可写目录和 Token 使用情况
`/statusline`	配置底部状态栏显示内容
`/title`	配置终端窗口或标签标题
`/raw`	切换原始滚动模式，方便复制长输出

/compact 非常常用。聊了很多轮、上下文变长之后，先执行：

/compact

再继续让 Codex 做后面的工作，会稳很多。

模型、速度与权限

命令	作用
`/model`	切换当前会话使用的模型
`/fast on`	开启快速模式，如果当前模型支持
`/fast off`	关闭快速模式
`/fast status`	查看快速模式状态
`/personality`	切换 Codex 的沟通风格
`/permissions`	调整 Codex 可以自动执行哪些操作
`/approve`	当自动审查拒绝某个操作后，手动批准重试一次
`/experimental`	开启或关闭实验性功能

/permissions 是新手最应该熟悉的命令。你可以随时把 Codex 从自动改代码切到只读分析，也可以在确认安全后放宽权限。

规划与目标

命令	作用
`/plan`	进入规划模式，让 Codex 先给方案，不急着改代码
`/plan <任务描述>`	直接基于某个目标生成执行方案
`/goal <目标>`	设置一个持续目标，让 Codex 围绕这个目标推进
`/goal`	查看当前目标
`/goal pause`	暂停当前目标
`/goal resume`	恢复当前目标
`/goal clear`	清除当前目标

遇到大改动时，先用：

1	/plan 重构用户权限模块，要求不影响现有接口，并补充必要测试

等方案确认后，再让 Codex 执行。

项目与代码质量

命令	作用
`/init`	在当前目录生成 `AGENTS.md` 项目规则文件
`/diff`	查看 Git Diff，包括未跟踪文件
`/review`	审查当前工作区变更
`/skills`	浏览和使用 Skills
`/hooks`	查看生命周期 Hooks 配置
`/mcp`	查看当前可用 MCP 工具
`/mcp verbose`	查看更详细的 MCP 诊断信息

常见工作流：

/init
/plan 修复登录后跳转异常
/diff
/review

也就是先生成项目规则，再规划，再改代码，最后看 diff 和做审查。

后台任务与终端

命令	作用
`/ps`	查看后台终端任务及最近输出
`/stop`	停止当前会话中的后台终端任务
`/theme`	切换代码高亮主题
`/keymap`	配置 TUI 快捷键
`/vim`	开启或关闭 Vim 输入模式

如果 Codex 启动了测试、构建、开发服务等长命令，可以用：

/ps

查看后台输出。

如果发现跑偏了，可以用：

/stop

直接停止后台任务。

权限模式

Codex 的权限控制比普通聊天工具更重要，因为它真的可以改文件、跑命令。官方文档把权限模式分成 Auto、Read-only、Full Access 等模式。

模式	作用	适合场景
Auto	默认模式，可以读取、修改工作目录内文件，并在必要时请求确认	日常开发
Read-only	只读模式，只分析不改代码	接手新项目、代码审查、风险评估
Full Access	完全访问模式，权限很高，包括更大范围文件和网络访问	只建议在可信项目和隔离环境中使用

推荐新手这样用：

1	codex --sandbox read-only

先让 Codex 分析项目。

确认它理解正确后，再切到：

1	codex --sandbox workspace-write --ask-for-approval on-request

不建议一上来就用：

1	codex --yolo

这个模式太猛，适合临时实验环境，不适合重要项目。

AGENTS.md 项目规则

Claude Code 常见的是 CLAUDE.md，Codex 对应的是 AGENTS.md。

官方文档说明，Codex 在开始工作前会读取 AGENTS.md，你可以把项目结构、启动命令、代码规范、测试命令、提交规范等长期规则写进去。

文件	作用
`~/.codex/AGENTS.md`	全局规则，所有项目默认生效
`AGENTS.md`	当前项目规则
`AGENTS.override.md`	当前目录下的覆盖规则，优先级更高
`services/payments/AGENTS.override.md`	子目录专项规则，适合多团队或多模块项目

最简单的初始化方式：

/init

生成后建议手动补充这些内容：

# AGENTS.md

## Project Overview

这是一个 Vue 3 + TypeScript + Vite 项目。

## Commands

- 安装依赖：pnpm install
- 本地开发：pnpm dev
- 构建项目：pnpm build
- 代码检查：pnpm lint
- 类型检查：pnpm typecheck

## Code Style

- 使用 TypeScript
- 使用 Vue 3 Composition API
- 缩进 2 个空格
- 字符串使用单引号
- 文件名使用 kebab-case
- 修改代码后必须运行 lint 和 build

## Rules

- 不要擅自删除文件
- 不要引入不必要的新依赖
- 大改动前先给计划
- 修改公共组件时必须考虑兼容性

这个文件非常重要。Codex 能不能稳定干活，很大程度取决于 AGENTS.md 写得够不够清楚。

Skills 技能

Codex 也支持 Skills。官方文档说明，Codex 可以通过 /skills 或 $ 显式调用技能，也可以根据 Skill 描述自动判断是否使用某个技能。

命令 / 写法	作用
`/skills`	查看和选择可用 Skills
`$skill-name`	在 Prompt 中显式调用某个 Skill
`$skill-creator`	使用内置创建器创建 Skill
`$imagegen`	调用图像生成相关能力，适合生成图标、插图、占位图等

示例：

1	使用 $skill-creator 帮我创建一个 Vue 组件重构 Skill

或者：

1	使用 $imagegen 生成一组后台系统空状态插图

常用快捷键

Codex CLI 也有不少高频快捷键。官方功能文档列出了清屏、复制输出、排队输入、搜索历史、编辑上一条消息等操作。

快捷键 / 写法	作用
`Ctrl + L`	清屏，但不开始新对话
`Ctrl + O`	复制最近一次完成的 Codex 输出
`Ctrl + R`	搜索 Prompt 历史
`Ctrl + C`	关闭当前交互式会话
`Ctrl + G`	打开外部编辑器编写长 Prompt
`Tab`	在 Codex 运行时排队下一条输入或斜杠命令
`Up / Down`	在输入框中切换历史草稿
`Esc` 两次	编辑上一条用户消息，并从该位置分叉继续
`@`	打开文件模糊搜索，把文件加入 Prompt
`!ls`	在 Codex 中执行本地 Shell 命令，并把输出作为上下文

最实用的是这几个：

1	@src/main.ts

快速引用文件。

1	!pnpm test

直接执行本地命令。

Ctrl + L

清屏但保留上下文，适合长对话时保持终端干净。

常用工作流

1. 接手新项目

1	codex --cd ~/projects/my-app --sandbox read-only

然后输入：

1	请先阅读项目结构，告诉我这个项目的技术栈、启动命令、核心模块和潜在风险，不要修改任何文件

2. 初始化项目规则

/init

然后让 Codex 根据项目补充：

1	请根据当前项目结构完善 AGENTS.md，重点补充启动命令、构建命令、代码规范和禁止事项

3. 修复 Bug

1	/plan 修复登录成功后偶发无法跳转的问题，要求先分析原因，再给最小修改方案

确认方案后：

1	按方案修复，并补充必要的边界处理

最后：

1 2	/diff /review

4. 长对话续命

/compact

然后继续：

1	基于刚才的总结，继续完成剩余重构

或者退出后下次恢复：

1	codex resume --last

5. 自动生成报告

1	codex exec -o report.md "检查当前项目的代码质量、架构问题、潜在 Bug，并输出 Markdown 报告"

6. 在 CI 或脚本中使用

1	codex exec --json -o codex-summary.md "检查当前 diff 是否存在明显风险，并给出修改建议"

小结

Codex 常用命令可以按这几类记：

类别	常用命令
启动	`codex`、`codex --cd`、`codex --model`
登录	`codex login`、`codex login status`、`codex logout`
恢复	`codex resume`、`codex resume --last`、`codex fork`
自动化	`codex exec`、`codex e`、`codex exec resume`
项目规则	`/init`、`AGENTS.md`
上下文	`/mention`、`/compact`、`/status`
改代码	`/plan`、`/diff`、`/review`
权限	`/permissions`、`--sandbox`、`--ask-for-approval`
扩展能力	`/skills`、`/mcp`、`codex mcp`
诊断	`codex doctor`、`codex update`

新手最推荐先记住这组：

1	codex --cd <项目路径> --sandbox workspace-write --ask-for-approval on-request

进入后常用：

/init
/plan
/diff
/review
/compact
/status

掌握这些，Codex 就不只是一个“问答工具”，而是可以真正参与开发流程的 AI 编程助手。