Codex常用命令手册，一篇搞定。

一、简介

Codex CLI 是 OpenAI 推出的编码代理工具，可以在你的终端本地运行，能够读取、修改和执行你机器上的代码。

它是开源的，使用 Rust构建，运行速度快、效率高。ChatGPT Plus、Pro、Business、Edu 和 Enterprise订阅均包含 Codex 使用权限。

二、两种核心运行模式

2.1 交互模式（Interactive TUI）

Codex 会启动一个全屏终端 UI，能够读取你的仓库、进行编辑和运行命令，让你实时审查 Codex 的操作。适用于对话式工作流程。

代码块

Plain Text

# 启动交互式 TUI

codex

# 携带初始提示启动

codex "解释这个项目的架构"

# 指定工作目录

codex -C /path/to/project

# 指定模型启动

codex -m gpt-5.5

# 附带图片启动

codex -i screenshot.png "根据这个截图实现 UI"

2.2 非交互模式（Exec）

非交互式运行 Codex，别名为 codex e。可以将结果流式输出到 stdout 或 JSONL，并支持恢复之前的会话。

代码块

Plain Text

# 基本用法

codex exec"修复所有失败的测试"

# 简写形式

codex e "运行测试并修复所有错误"

# 指定模型和沙箱

codex exec -m gpt-5.3-codex --sandbox workspace-write "审查这个仓库"

# JSON 输出（适合管道处理）

codex exec --json "生成变更日志"

# 从 stdin 读取提示

echo"重构认证模块" | codex exec -

三、全局标志（Global Flags）

CLI从 ~/.codex/config.toml 继承大多数默认值。通过命令行传递的 -c key=value 覆盖优先于配置文件。

#pbXzooJvHwHz text { white-space: pre; }#pbXzooJvHwHz .fb0 { stroke: var(--N900-FG, 0.15); }#pbXzooJvHwHz .fb0 {stroke: rgba(31,35,41, 0.15)}#pbXzooJvHwHz .fx0 { stroke-miterlimit: 10; }#pbXzooJvHwHz .fx0 {stroke-miterlimit: 10}#pbXzooJvHwHz .fa1 { fill: rgb(187, 191, 196); }#pbXzooJvHwHz .fa1 {fill: rgb(187, 191, 196)}#pbXzooJvHwHz .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#pbXzooJvHwHz .fx1 {font-style: normal}#pbXzooJvHwHz .fx2 { text-anchor: middle; }#pbXzooJvHwHz .fx2 {text-anchor: middle}#pbXzooJvHwHz .fx3 { dominant-baseline: central; }#pbXzooJvHwHz .fx3 {dominant-baseline: central}#pbXzooJvHwHz .fx4 { stroke: none; }#pbXzooJvHwHz .fx4 {stroke: none}#pbXzooJvHwHz .fc0 { fill: var(--text-caption); }#pbXzooJvHwHz .fc0 {fill: #646a73}#pbXzooJvHwHz .fa2 { fill: var(--text-link-disabled); }#pbXzooJvHwHz .fa2 {fill: rgb(187, 191, 196)}#pbXzooJvHwHz .fa3 { fill: rgb(236, 226, 254); }#pbXzooJvHwHz .fa3 {fill: rgb(236, 226, 254)}#pbXzooJvHwHz .fx5 { font: 700 16px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#pbXzooJvHwHz .fx5 {font-style: normal}#pbXzooJvHwHz .fx6 { text-anchor: start; }#pbXzooJvHwHz .fx6 {text-anchor: start}#pbXzooJvHwHz .fx7 { dominant-baseline: alphabetic; }#pbXzooJvHwHz .fx7 {dominant-baseline: alphabetic}#pbXzooJvHwHz .fc1 { fill: rgb(0, 0, 0); }#pbXzooJvHwHz .fc1 {fill: rgb(0, 0, 0)}#pbXzooJvHwHz .fx8 { font: 400 14px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#pbXzooJvHwHz .fx8 {font-style: normal}#pbXzooJvHwHz .fb1 { fill: var(--N900-FG, 0.15); }#pbXzooJvHwHz .fb1 {fill: rgba(31,35,41, 0.15)}#pbXzooJvHwHz .fa4 { fill: var(--bg-body); }#pbXzooJvHwHz .fa4 {fill: #fff}AB1234567891011标志说明--model / -m --sandbox / -s --ask-for-approval / -a -C --add-dir -c key=value--profile --search--no-git--full-auto指定使用的模型沙箱策略（见下文）审批模式（见下文）设置工作目录授予额外目录的写入权限，可重复使用覆盖配置值，支持 JSON 解析选择 config.toml 中定义的配置档案启用实时网页搜索允许在非 Git 仓库目录中运行全自动模式快捷方式

四、审批模式（Approval Modes）

控制 Codex 在运行命令前何时暂停等待人工批准。on-failure 已弃用，交互式运行推荐使用 on-request，非交互式运行推荐使用 never。

#JNkqfUsBFzSp text { white-space: pre; }#JNkqfUsBFzSp .fb0 { stroke: var(--N900-FG, 0.15); }#JNkqfUsBFzSp .fb0 {stroke: rgba(31,35,41, 0.15)}#JNkqfUsBFzSp .fx0 { stroke-miterlimit: 10; }#JNkqfUsBFzSp .fx0 {stroke-miterlimit: 10}#JNkqfUsBFzSp .fa1 { fill: rgb(187, 191, 196); }#JNkqfUsBFzSp .fa1 {fill: rgb(187, 191, 196)}#JNkqfUsBFzSp .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#JNkqfUsBFzSp .fx1 {font-style: normal}#JNkqfUsBFzSp .fx2 { text-anchor: middle; }#JNkqfUsBFzSp .fx2 {text-anchor: middle}#JNkqfUsBFzSp .fx3 { dominant-baseline: central; }#JNkqfUsBFzSp .fx3 {dominant-baseline: central}#JNkqfUsBFzSp .fx4 { stroke: none; }#JNkqfUsBFzSp .fx4 {stroke: none}#JNkqfUsBFzSp .fc0 { fill: var(--text-caption); }#JNkqfUsBFzSp .fc0 {fill: #646a73}#JNkqfUsBFzSp .fa2 { fill: var(--text-link-disabled); }#JNkqfUsBFzSp .fa2 {fill: rgb(187, 191, 196)}#JNkqfUsBFzSp .fa3 { fill: rgb(236, 226, 254); }#JNkqfUsBFzSp .fa3 {fill: rgb(236, 226, 254)}#JNkqfUsBFzSp .fx5 { font: 700 16px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#JNkqfUsBFzSp .fx5 {font-style: normal}#JNkqfUsBFzSp .fx6 { text-anchor: start; }#JNkqfUsBFzSp .fx6 {text-anchor: start}#JNkqfUsBFzSp .fx7 { dominant-baseline: alphabetic; }#JNkqfUsBFzSp .fx7 {dominant-baseline: alphabetic}#JNkqfUsBFzSp .fc1 { fill: rgb(0, 0, 0); }#JNkqfUsBFzSp .fc1 {fill: rgb(0, 0, 0)}#JNkqfUsBFzSp .fx8 { font: 400 14px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#JNkqfUsBFzSp .fx8 {font-style: normal}#JNkqfUsBFzSp .fb1 { fill: var(--N900-FG, 0.15); }#JNkqfUsBFzSp .fb1 {fill: rgba(31,35,41, 0.15)}#JNkqfUsBFzSp .fb2 { fill: rgba(204, 204, 204, 0.4); }#JNkqfUsBFzSp .fb2 {fill: rgba(204, 204, 204, 0.4)}#JNkqfUsBFzSp .fa4 { fill: var(--bg-body); }#JNkqfUsBFzSp .fa4 {fill: #fff}AB123456模式行为suggest（默认）auto-editon-requestfull-auto / neveruntrusted每一步都请求批准（读取、编辑、执行）自动编辑文件，执行命令前仍需批准仅在 Codex 主动请求时暂停完全自动，不暂停最严格模式，每步都需批准

代码块

Plain Text

# 本地开发推荐组合

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

五、沙箱模式（Sandbox Modes）

#hLOeJpUBlDRC text { white-space: pre; }#hLOeJpUBlDRC .fb0 { stroke: var(--N900-FG, 0.15); }#hLOeJpUBlDRC .fb0 {stroke: rgba(31,35,41, 0.15)}#hLOeJpUBlDRC .fx0 { stroke-miterlimit: 10; }#hLOeJpUBlDRC .fx0 {stroke-miterlimit: 10}#hLOeJpUBlDRC .fa1 { fill: rgb(187, 191, 196); }#hLOeJpUBlDRC .fa1 {fill: rgb(187, 191, 196)}#hLOeJpUBlDRC .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#hLOeJpUBlDRC .fx1 {font-style: normal}#hLOeJpUBlDRC .fx2 { text-anchor: middle; }#hLOeJpUBlDRC .fx2 {text-anchor: middle}#hLOeJpUBlDRC .fx3 { dominant-baseline: central; }#hLOeJpUBlDRC .fx3 {dominant-baseline: central}#hLOeJpUBlDRC .fx4 { stroke: none; }#hLOeJpUBlDRC .fx4 {stroke: none}#hLOeJpUBlDRC .fc0 { fill: var(--text-caption); }#hLOeJpUBlDRC .fc0 {fill: #646a73}#hLOeJpUBlDRC .fa2 { fill: var(--text-link-disabled); }#hLOeJpUBlDRC .fa2 {fill: rgb(187, 191, 196)}#hLOeJpUBlDRC .fa3 { fill: rgb(236, 226, 254); }#hLOeJpUBlDRC .fa3 {fill: rgb(236, 226, 254)}#hLOeJpUBlDRC .fx5 { font: 700 16px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#hLOeJpUBlDRC .fx5 {font-style: normal}#hLOeJpUBlDRC .fx6 { text-anchor: start; }#hLOeJpUBlDRC .fx6 {text-anchor: start}#hLOeJpUBlDRC .fx7 { dominant-baseline: alphabetic; }#hLOeJpUBlDRC .fx7 {dominant-baseline: alphabetic}#hLOeJpUBlDRC .fc1 { fill: rgb(0, 0, 0); }#hLOeJpUBlDRC .fc1 {fill: rgb(0, 0, 0)}#hLOeJpUBlDRC .fx8 { font: 400 14px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#hLOeJpUBlDRC .fx8 {font-style: normal}#hLOeJpUBlDRC .fb1 { fill: var(--N900-FG, 0.15); }#hLOeJpUBlDRC .fb1 {fill: rgba(31,35,41, 0.15)}#hLOeJpUBlDRC .fb2 { fill: rgba(204, 204, 204, 0.4); }#hLOeJpUBlDRC .fb2 {fill: rgba(204, 204, 204, 0.4)}#hLOeJpUBlDRC .fa4 { fill: var(--bg-body); }#hLOeJpUBlDRC .fa4 {fill: #fff}AB1234模式说明read-onlyworkspace-writedanger-full-access只读访问，不允许写入允许写入工作区目录完全访问（⚠️ 慎用）

danger-full-access 看似方便，但最容易造成损坏。除非在容器、临时机器或其他隔离环境中，否则不要将其设为默认。

六、斜杠命令（Slash Commands）

斜杠命令提供快速访问专门的工作流，如 /review、/fork、/side 等。Codex 附带一组精选的内置命令，你也可以创建自定义命令。

6.1 会话管理

/clear 会开始一个新的对话，而 Ctrl+L 只是清除终端显示，保留当前聊天。

6.2 模型与配置

也可以在会话中用 /model 切换模型，或使用 Alt+, / Alt+. 来实时降低或提升推理强度。

6.3 代码审查与开发

/diff 可以滚动查看 Git diff 输出，显示暂存的变更、未暂存的变更以及未跟踪的文件。

6.4 工具与输出

七、快捷键

在编辑器中输入 @ 可以打开工作区根目录的模糊文件搜索，按 Tab 或 Enter 将高亮的路径插入消息。

八、子命令大全

8.1 核心子命令

代码块

Plain Text

codex # 启动交互式 TUI

codex exec "..." # 非交互式执行

codex e "..." # exec 简写

codex login # 认证登录

codex update # 自更新

codex completion bash/zsh/fish # 生成 shell 补全脚本

8.2 云任务相关

从终端浏览或执行 Codex Cloud 任务，无需打开 TUI。别名：codex cloud-tasks。

代码块

Plain Text

8.3 高级子命令

九、配置文件（config.toml）

主配置文件位于 ~/.codex/config.toml。命令行标志和 -c key=value 覆盖优先于配置文件。

代码块

Plain Text

# ~/.codex/config.toml 示例

model = "gpt-5.3-codex"

model_reasoning_effort = "high"

approval_policy = "on-request"

sandbox_mode = "workspace-write"

web_search = "cached"

[features]

multi_agent = true

shell_tool = true

# 命名配置档案

[profiles.ci]

approval_policy = "never"

sandbox_mode = "workspace-write"

[profiles.paranoid]

approval_policy = "untrusted"

sandbox_mode = "read-only"

项目本地配置 .codex/config.toml（在项目根目录）会覆盖全局设置。当存在冲突时，项目本地设置始终优先。

十、MCP集成

通过配置 Model Context Protocol 服务器连接更多工具。在 ~/.codex/config.toml 中添加 STDIO 或流式 HTTP 服务器，或使用 codex mcp CLI 命令管理它们。会话启动时 Codex 会自动启动这些服务器。

代码块

Plain Text

# config.toml 中的 MCP 配置示例

[mcp_servers.my-db]

command = "/usr/local/bin/my-mcp-server"

env = { DB_URL = "postgres://..." }

timeout_secs = 30

在会话中用 /mcp 列出已连接的工具，用 /apps 浏览可用的连接器。

十一、AGENTS.md 项目指令

AGENTS.md 常用于初始化项目规则，可以记录项目约定。如果你在长期项目中使用 Codex，AGENTS.md 非常重要——它能减少你在每次会话中重复项目上下文的次数。

代码块

Plain Text

# 项目规则

- 使用 TypeScript strict 模式

- 测试命令：`npm test`

- 提交前运行 `npm run lint`

- 禁止修改 /config 目录下的文件

- API 端点遵循 RESTful 命名规范

十二、实用工作流示例

12.1 项目探索 → 规划 → 实施

这种工作流比简单地让 Codex 不断编辑直到全部通过要好得多。它将规划、实施、审查和验证分离开来。

代码块

Plain Text

12.2 CI/CD 自动化

代码块

Plain Text

# GitHub Actions 中自动修复 lint 错误

12.3 代码审查

内置的 /review 命令可以分析与基础分支的 diff、未提交的变更或特定提交，适合在合并或部署前使用。

代码块

Plain Text

# 审查当前变更

/review

# 审查特定提交

/review 审查上次提交与 main 分支的差异

12.4 图片输入

可以直接在 CLI 中生成或编辑图片，适用于图标、横幅、插图、精灵表和占位符等资源。如果要变换或扩展现有资源，可附加参考图片。

代码块

Plain Text

# 根据截图实现 UI

codex -i figma-export.png "实现这个 React 组件，精确匹配设计稿"

# 生成图标

codex "为这个应用生成一个扁平化风格的 logo 图标"

12.5 网页搜索

网页搜索默认使用缓存模式，使用 --search 切换到实时浏览。

代码块

Plain Text

# 启用实时搜索

codex --search "查找 React 19 的最新 API 变更"

十三、会话恢复

对话会在本地存储。可以使用 codex resume --last 或 codex resume <SESSION_ID> 恢复之前的会话，从上次中断的地方继续。

代码块

Plain Text

# 交互模式恢复

/resume # 从保存的会话列表中选择

# exec 模式恢复

codex exec resume --last # 恢复最近的会话

codex exec resume <SESSION_ID> # 恢复指定会话

codex exec resume --all # 考虑所有目录的会话

十四、远程连接

使用 --remote ws://host:port 或 --remote wss://host:port 连接到通过 codex app-server --listen 启动的 app server。当服务器需要 bearer token 认证时，添加 --remote-auth-token-env <ENV_VAR>。

代码块

Plain Text

十五、实践经验

先读后写：不要让 Codex 立即编辑。先让它读取项目、写计划、解释风险，然后再开放权限进行实施。

使用 Git 检查点：Codex 可以修改你的代码库，建议在每个任务前后创建 Git 检查点，以便在需要时轻松回滚。

检查 diff：AI 编码工具经常会做出"额外"的修改——可能重新格式化文件、更新依赖或编辑配置。实施后务必检查 diff。

长期项目必备 AGENTS.md：长期项目需要 AGENTS.md 或项目级规则，否则每次都要重复测试命令、目录约定和提交习惯。

善用配置档案：针对不同场景（CI、开发、审查）创建不同的 profile，用 --profile 快速切换。