Codex CLI 常用命令与参数速查

Codex CLI 包含三类操作：

1. 在 Shell 中执行的 CLI 命令和参数；
2. 进入交互界面后输入的斜杠命令；
3. 用于脚本和 CI 的非交互命令。

不同版本可能增加或调整命令，最可靠的入口始终是：

codex --help
codex <subcommand> --help

1. 启动 Codex

在当前目录启动：

codex

指定工作目录：

codex --cd ~/code/my-project

简写：

codex -C ~/code/my-project

直接附带初始任务：

codex "分析这个项目的认证流程，先不要修改代码"

2. 选择模型

单次运行指定模型：

codex --model <model-name>

简写：

codex -m <model-name>

交互界面中使用：

/model

模型目录更新较快，教程不应长期写死唯一推荐模型。应引导用户使用 /model 查看账户当前可用选项。

3. 指定推理等级

在交互界面使用：

/reasoning

适用原则：

• 小型格式或文案修改：较低推理；
• 普通功能开发：中等推理；
• 架构、复杂调试、安全审查：高推理；
• 不要把所有任务都设置为最高等级，速度和消耗会明显增加。

持久化配置可写入 config.toml：

model_reasoning_effort = "high"

4. 查看状态

交互界面：

/status

通常用于查看：

• 当前任务或会话信息；
• 上下文使用情况；
• 模型；
• 速率限制；
• 当前目录或项目状态。

在开始长任务前执行一次 /status，可以避免在错误目录或错误配置下工作。

5. 权限设置

交互界面：

/permissions

CLI 参数：

codex --ask-for-approval on-request

可用策略以当前版本帮助为准，官方参考中常见值包括：

• untrusted：更谨慎地批准命令；
• on-request：需要越界时请求批准；
• never：不弹出批准请求，但仍受沙箱限制。

注意：approval_policy = "never" 不等于无限权限。沙箱仍然决定命令技术上可以访问什么。

6. 额外允许写入目录

默认情况下，Codex主要围绕当前工作区操作。需要额外目录时：

codex --add-dir ../shared-library

多个目录可重复传入：

codex --add-dir ../shared-a --add-dir ../shared-b

优先把相关仓库放入明确的 worktree 或 monorepo，不要为方便而开放整个 Home 目录。

7. 临时覆盖配置

使用 -c 或 --config：

codex -c model_reasoning_effort="high"

同时覆盖多个值：

codex \
  -c approval_policy="on-request" \
  -c sandbox_mode="workspace-write"

命令行覆盖优先级高于项目和用户配置，适合一次性实验。

8. 使用配置 Profile

启动指定 Profile：

codex --profile deep-review

简写：

codex -p deep-review

对应文件位于：

~/.codex/deep-review.config.toml

示例：

model_reasoning_effort = "xhigh"
approval_policy = "on-request"
sandbox_mode = "read-only"

Profile 适合建立：

• fast-edit：快速小改动；
• deep-review：只读、高推理审查；
• ci：非交互自动化；
• offline：禁用网络。

9. 图片输入

启动时附加图片：

codex --image error.png "根据截图定位页面错误"

简写：

codex -i design.png "按现有项目组件实现这个页面"

多个图片：

codex -i desktop.png,mobile.png "实现响应式页面"

图片只提供视觉信息。还需说明框架、路由、组件规范、交互状态和响应式要求。

10. Web 搜索

需要当前版本、外部文档或最新行为时，可使用：

codex --search

或在配置中设置搜索模式。Web 内容应视为不可信输入，特别是允许实时访问外部页面时，要防止提示注入和恶意命令诱导。

11. 恢复会话

Codex CLI 支持恢复之前的任务：

codex resume

先查看帮助：

codex resume --help

恢复会话适合继续同一个问题；如果需求已经变化或工作区状态不同，创建新会话更清晰。

12. 初始化项目规则

交互界面：

/init

它会为当前项目生成 AGENTS.md 脚手架。生成后必须人工编辑，不要把自动生成内容直接视为最终规范。

建议至少包含：

## Build and test
- Install: `pnpm install`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
- Test: `pnpm test`

## Constraints
- Do not add production dependencies without approval.
- Do not modify generated files.

13. Plan 模式

/plan

用于复杂、多步骤或有歧义的任务。Plan 阶段应要求 Codex先阅读代码、识别风险和提出里程碑，而不是直接修改。

14. 代码审查

/review

常见范围：

• 与基础分支比较；
• 审查未提交改动；
• 审查某个提交；
• 自定义关注点。

自定义示例：

/review 重点检查空值、并发、权限绕过和向后兼容性

审查模式通常只报告问题，不修改工作树。

15. MCP 状态

/mcp

用于查看当前连接的 MCP Server 和可用工具。配置 MCP 后，先用 /mcp 确认连接状态，再让 Codex调用外部工具。

16. 压缩上下文

长任务中可使用：

/compact

它用于压缩当前任务上下文。压缩前应让 Codex形成阶段总结，避免关键约束只存在于很早的对话里。

建议提示：

在压缩前总结：当前目标、已修改文件、未完成任务、关键约束和下一步验证命令。

17. 临时侧边对话

/side

适合询问一个不应打断主任务的临时问题，例如解释某个库或比较两种实现方式。

18. Git worktree 任务

/worktree

可在新的 Git worktree 中运行任务，减少并行修改互相污染。大型项目、多个代理或多 Issue 并行时非常有用。

19. 云端任务

/cloud

选择环境：

/cloud-environment

云端任务需要事先配置对应仓库和环境。不要假设本机 .env、依赖缓存和系统工具会自动存在于云端。

20. 非交互模式

运行一次任务并退出：

codex exec "检查当前改动是否存在明显回归"

非交互模式适合：

• CI；
• 批处理；
• 自动生成报告；
• 固定格式代码审查。

查看所有参数：

codex exec --help

脚本中应明确输出格式、失败条件和权限，避免依赖交互确认。

21. 高风险参数

官方提供跳过批准和沙箱的高风险参数，常见别名包括 --yolo。它会让命令失去 Codex 自身的隔离保护。

只应在已经由容器、虚拟机、临时机器或严格 CI Runner 提供外层隔离时考虑，并且不得挂载真实凭据和重要目录。

普通本地开发不应把它作为“减少弹窗”的默认方案。

22. 推荐日常组合

小范围开发：

codex -C ~/code/app

只读深度审查：

codex --profile deep-review

附图实现页面：

codex -i target.png "使用现有组件实现页面，先分析再修改"

自动审查：

codex exec --profile deep-review "Review the current branch against main"

官方参考

• https://learn.chatgpt.com/docs/developer-commands?surface=cli
• https://learn.chatgpt.com/docs/reference/slash-commands
• https://learn.chatgpt.com/docs/codex/cli
• https://learn.chatgpt.com/docs/config-file/config-basic

资料核对日期：2026-07-14。命令和成熟度会随 Codex 版本变化，页面应提示读者同时查看本机 --help。