CLI 参数怎么用

Codex CLI 的参数不要按“完整列表”学习。更实用的方式是先判断你要启动哪类任务，再决定使用哪些参数覆盖默认配置。

官方 CLI 会继续演进，完整命令和 flag 以 codex --help、子命令 --help 和官方 CLI Features 为准。本页只保留稳定用法和风险边界。

记住一个原则：长期默认值写进 config.toml，项目规则写进 .codex/，本次临时变化才用 CLI 参数。

CLI Features

查看 Codex CLI 的 TUI、slash commands、remote app server、MCP、exec 等官方能力说明。

Configuration Reference

查看参数背后的配置 key、类型、默认值和可用范围。

Agent Security

理解 approval、sandbox、network access 和 agent 执行边界。

CLI 参数的三类用途

flowchart TB
    Start["codex 命令"] --> Entry["选择任务入口"]
    Start --> Boundary["设置执行边界"]
    Start --> Override["覆盖本次配置"]

    Entry --> TUI["interactive TUI"]
    Entry --> Exec["codex exec"]
    Entry --> Cloud["cloud / apply / resume"]

    Boundary --> Sandbox["sandbox"]
    Boundary --> Approval["approval"]
    Boundary --> Workspace["working directory / extra dirs"]

    Override --> Model["model / profile"]
    Override --> Feature["feature flags"]
    Override --> Config["-c key=value"]

读参数时先问：

我是在打开交互式 TUI，还是跑一次自动化任务。
这次是否允许改文件、联网、执行命令。
这次变化应该临时生效，还是应该写进配置文件。

如果这三个问题没想清楚，参数越多越容易误用。

最常用入口

打开交互式 TUI：

codex

带一个初始任务进入 TUI：

codex "检查这个 PR 的风险点"

在指定目录启动：

codex --cd /path/to/repo

非交互执行一次任务：

codex exec "运行测试并总结失败原因"

把 stdin 作为任务输入：

cat prompt.md | codex exec -

这些入口的差别不是“命令长短”，而是交互模型不同：TUI 适合边看边改，exec 适合脚本化、CI、批处理。

权限参数优先看 sandbox 和 approval

Codex 会读文件、改文件、调用工具。启动前最重要的是权限边界。

常见组合：

codex --sandbox read-only --ask-for-approval on-request
codex --sandbox workspace-write --ask-for-approval on-request
codex exec --sandbox workspace-write --ask-for-approval never "运行只读审计"

使用建议：

只想让它分析项目，用 read-only。
允许它改当前 workspace，用 workspace-write。
需要访问 workspace 外目录时，明确传入额外目录，而不是放开全部权限。
自动化运行如果使用 never，必须确保外层 runner 已经隔离。
不要把危险组合写成团队默认值。

--dangerously-bypass-approvals-and-sandbox / --yolo 只适合外部已经隔离、可回滚、低价值环境。它不是“更省事”的日常模式。

临时配置用 `-c`

-c / --config 用于覆盖本次 invocation 的配置。它适合临时实验，不适合替代正式配置。

codex -c model_reasoning_effort='"high"'
codex -c sandbox_mode='"read-only"'
codex -c 'features.codex_hooks=true'

注意：

值按 TOML 解析；字符串通常要加引号。
Nested key 可以用点号。
同一个参数可以重复传入。
如果某个覆盖值每次都要写，应回到 config.toml 或 profile。

这也是排查配置问题的好方法：先用 -c 验证单次行为，再决定是否固化。

Profile 适合常用工作模式

如果你经常切换模式，不要每次手写一长串参数。用 profile。

[profiles.review]
sandbox_mode = "read-only"
approval_policy = "on-request"

[profiles.implementation]
sandbox_mode = "workspace-write"
approval_policy = "on-request"

启动：

codex --profile review
codex --profile implementation

Profile 最适合表达“我现在要进入哪种工作状态”。它比临时 flag 更稳定，也比复制命令更少出错。

`exec` 用于自动化，不等于放弃审查

codex exec 常用于批处理、脚本和 CI 风格任务。

codex exec "检查 docs 中有没有失效链接"

适合场景：

对一批文件做一致性检查。
在 CI 或脚本里生成结构化结果。
从 stdin 读取长 prompt。
让 Codex 完成一次明确、可验证的任务。

不适合场景：

需求还在讨论。
需要频繁人工决策。
需要对生产环境做不可逆操作。
任务边界不清楚但权限很大。

自动化入口更要明确 sandbox、approval、工作目录和输出格式。

Remote 和 app-server 要先处理认证边界

Codex CLI 支持把 TUI 连接到 remote app-server。这类能力适合本地开发、远程工作区和特殊集成，但默认不应暴露给不受信任网络。

使用时重点检查：

endpoint 是否只在可信网络可达。
token 是否通过安全渠道传递。
ws:// 是否仅用于 localhost 或受控环境。
app-server 是否有清晰的启动和关闭方式。

如果不确定认证和网络边界，不要为了方便直接暴露 remote endpoint。

MCP 和插件类命令先看用途

Codex CLI 也包含 MCP、features、completion、cloud、apply、resume 等命令。学习顺序建议：

先掌握 codex 和 codex exec。
再掌握 sandbox、approval、profile、-c。
然后配置 MCP servers。
最后处理 cloud、remote、app-server、plugin marketplace 这类扩展能力。

这样学不会被命令数量带偏。CLI 的核心价值始终是：在正确边界内把 Codex 接入真实工程任务。

日常命令模板

只读审计：

codex --sandbox read-only --ask-for-approval on-request

普通本地实现：

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

单次高推理任务：

codex -c model_reasoning_effort='"high"' "审查这次重构的风险"

脚本化检查：

codex exec --sandbox read-only --ask-for-approval never "列出 docs 中需要人工复核的页面"

这些模板不要原样当成永久标准。最终应该根据你的项目风险、团队规范和运行环境沉淀成 profiles。

不建议写死的内容

教程和团队文档里不建议长期写死这些清单：

完整 CLI flag 表。
完整子命令表。
模型列表和价格。
实验 feature flag 列表。
remote / app-server 的内部协议细节。

它们更新频率高，写死后很快变成误导。更稳的写法是说明“怎么查、怎么选、怎么控制风险”。

团队文档怎么写

团队内部写 Codex CLI 教程时，不要把页面变成命令速查表。命令速查表会随版本变化，很快失效；更稳定的写法是把“入口选择、权限边界、验证动作、回滚方式”写清楚。新人真正需要知道的是：什么时候进入 TUI，什么时候用 exec，什么时候必须只读，什么时候要停下来让负责人确认。

商业项目里还要把 CLI 参数和团队默认 profile 对齐。文档可以给出推荐模式，但最终应落到 config.toml、项目规则和 CI 检查里。这样每个人启动 Codex 时看到的是一致边界，而不是从聊天记录里复制一串临时参数。

CLI 参数怎么用

CLI Features

Configuration Reference

Agent Security

本页目录