查询 CLI 参数
本篇是 Codex CLI 的命令与参数参考。它把官方 reference 页面里的交互式配置表改成普通 Markdown 表格，便于在 GitHub 上直接阅
本篇是 Codex CLI 的命令与参数参考。它把官方 reference 页面里的交互式配置表改成普通 Markdown 表格，便于在 GitHub 上直接阅读。
How to read this reference
这页覆盖所有已记录的 Codex CLI commands 和 flags。每节会说明选项是 stable 还是 experimental，并标出需要谨慎使用的组合。
CLI 大多数默认值来自：
~/.codex/config.toml命令行里的 -c key=value 会覆盖配置文件里的值，并且只对本次 invocation（调用）生效。
配置优先级见：
https://developers.openai.com/codex/config-basic#configuration-precedence
Global flags
这些选项适用于基础 codex 命令，也会传播到各个 subcommands，除非具体 subcommand 单独说明。
运行 subcommand 时，把 global flags 放在 subcommand 后面，例如：
codex exec --oss ...这样 Codex 才会按预期应用它们。
| Flag | Type | Default | Description |
|---|---|---|---|
PROMPT | string | - | 可选文字指令，用于启动 session。省略则打开没有预填消息的 TUI。 |
--image, -i | path[,path...] | - | 给 initial prompt 附加一张或多张图片。多路径可用逗号分隔，也可重复使用 flag。 |
--model, -m | string | - | 覆盖配置里的模型，例如 gpt-5.4。 |
--oss | boolean | false | 使用本地 open source model provider，等同 -c model_provider="oss"，并验证 Ollama 正在运行。 |
--profile, -p | string | - | 从 ~/.codex/config.toml 加载指定 configuration profile。 |
--sandbox, -s | read-only / workspace-write / danger-full-access | - | 选择 model-generated shell commands（模型生成的 shell 命令）的 sandbox policy。 |
--ask-for-approval, -a | untrusted / on-request / never | - | 控制 Codex 什么时候暂停并要求人工 approval。on-failure 已 deprecated；interactive runs 优先用 on-request，non-interactive runs 优先用 never。 |
--dangerously-bypass-approvals-and-sandbox, --yolo | boolean | false | 不经 approvals、不进 sandbox，直接运行每个命令。只应在外部加固环境中使用。 |
--cd, -C | path | - | Agent 开始处理请求前，设置 working directory。 |
--search | boolean | false | 启用 live web search，把 web_search 设为 "live"，而不是默认 "cached"。 |
--add-dir | path | - | 在主 workspace 之外，额外授予目录 write access。多目录可重复使用。 |
--no-alt-screen | boolean | false | 关闭 TUI alternate screen mode，并覆盖本次运行的 tui.alternate_screen。 |
--remote | ws://host:port / wss://host:port | - | 把 interactive TUI 连接到 remote app-server WebSocket endpoint。支持 codex、codex resume、codex fork；其他 subcommands 会拒绝 remote mode。 |
--remote-auth-token-env | ENV_VAR | - | 从该环境变量读取 bearer token，并在 --remote 连接时发送。要求同时使用 --remote。Tokens 只会通过 wss://，或 host 是 localhost、127.0.0.1、::1 的 ws:// 发送。 |
--enable | feature | - | 强制启用 feature flag，转成 -c features.<name>=true。可重复。 |
--disable | feature | - | 强制禁用 feature flag，转成 -c features.<name>=false。可重复。 |
--config, -c | key=value | - | 覆盖配置值。值能解析为 JSON 时按 JSON 解析，否则按 literal string 使用。 |
Command overview
Maturity（成熟度）使用 Experimental、Beta、Stable 等标签。解释见：
https://developers.openai.com/codex/feature-maturity
| Command | Maturity | Description |
|---|---|---|
codex | Stable | 打开 terminal UI。接受 global flags，以及可选 prompt 或 image attachments。 |
codex app-server | Experimental | 启动 Codex app server，用于本地开发或调试。 |
codex app | Stable | 在 macOS 或 Windows 上打开 Codex desktop app。macOS 可打开 workspace path；Windows 会打印要打开的路径。 |
codex debug app-server send-message-v2 | Experimental | 通过内置 test client 向 app-server 发送一条 V2 message，用于调试。 |
codex debug models | Experimental | 打印 Codex 看到的 raw model catalog，也可只查看 bundled catalog。 |
codex apply | Stable | 把 Codex Cloud task 生成的最新 diff 应用到本地 working tree。Alias: codex a。 |
codex cloud | Experimental | 从 terminal 浏览或执行 Codex Cloud tasks，不打开 TUI。Alias: codex cloud-tasks。 |
codex completion | Stable | 为 Bash、Zsh、Fish 或 PowerShell 生成 shell completion scripts。 |
codex features | Stable | 列出 feature flags，并在 config.toml 中持久启用或禁用。 |
codex exec | Stable | 非交互运行 Codex。Alias: codex e。可把结果输出到 stdout 或 JSONL，也可以 resume 旧 session。 |
codex execpolicy | Experimental | 评估 execpolicy rule files，判断命令会被 allow、prompt 还是 block。 |
codex login | Stable | 用 ChatGPT OAuth、device auth 或 stdin 传入 API key 认证 Codex。 |
codex logout | Stable | 删除已保存的 authentication credentials。 |
codex mcp | Experimental | 管理 Model Context Protocol servers，包括 list、add、remove、authenticate。 |
codex plugin marketplace | Experimental | 从 Git 或本地 sources 添加、升级、删除 plugin marketplaces。 |
codex mcp-server | Experimental | 通过 stdio 把 Codex 自身作为 MCP server 运行，供其他 Agent 消费。 |
codex resume | Stable | 按 ID 继续 previous interactive session，或恢复最近 conversation。 |
codex fork | Stable | 把 previous interactive session fork 成新 thread，并保留原始 transcript。 |
codex sandbox | Experimental | 在 Codex 提供的 macOS、Linux 或 Windows sandboxes 中运行任意命令。 |
codex update | Stable | 当安装版本支持 self-update 时，检查并应用 Codex CLI 更新。 |
Command details
codex interactive
不带 subcommand 运行 codex 会打开 interactive terminal UI (TUI)。Agent 接受 global flags 和 image attachments。
Web search 默认是 cached mode。使用 --search 可切到 live browsing。
低摩擦本地工作推荐：
codex --sandbox workspace-write --ask-for-approval on-request远程 TUI 连接：
codex --remote ws://host:port
codex --remote wss://host:port如果 app server 要求 WebSocket bearer token，加：
--remote-auth-token-env <ENV_VAR>远程示例和认证说明见：
https://developers.openai.com/codex/cli/features#connect-the-tui-to-a-remote-app-server
codex app-server
本地启动 Codex app server。主要用于 development 和 debugging，未来可能变化。
| Option | Type | Default | Description |
|---|---|---|---|
--listen | stdio:// / ws://IP:PORT | stdio:// | Transport listener URL。使用 ws://IP:PORT 暴露 WebSocket endpoint。 |
--ws-auth | capability-token / signed-bearer-token | - | app-server WebSocket clients 的 authentication mode。省略时关闭 WebSocket auth；non-local listeners 会在启动时警告。 |
--ws-token-file | absolute path | - | 包含 shared capability token 的文件。使用 --ws-auth capability-token 时必需。 |
--ws-shared-secret-file | absolute path | - | 包含 HMAC shared secret 的文件，用于验证 signed JWT bearer tokens。使用 --ws-auth signed-bearer-token 时必需。 |
--ws-issuer | string | - | signed bearer tokens 期望的 iss claim。要求 --ws-auth signed-bearer-token。 |
--ws-audience | string | - | signed bearer tokens 期望的 aud claim。要求 --ws-auth signed-bearer-token。 |
--ws-max-clock-skew-seconds | number | 30 | 验证 signed bearer token 的 exp 和 nbf claims 时允许的 clock skew。要求 --ws-auth signed-bearer-token。 |
codex app-server --listen stdio:// 保持默认 JSONL-over-stdio 行为。
--listen ws://IP:PORT 会启用 app-server clients 的 WebSocket transport。Server 接受 ws:// listen URLs；当 clients 使用 wss:// 连接时，请使用 TLS termination 或 secure proxy。
如果为 client bindings 生成 schemas，加 --experimental 可包含 gated fields 和 methods。
codex app
从 terminal 启动 Codex Desktop。支持 macOS 和 Windows。
| Option | Type | Default | Description |
|---|---|---|---|
PATH | path | . | Codex Desktop workspace path。macOS 会打开该路径；Windows 会打印该路径。 |
--download-url | url | - | 高级选项：覆盖安装时使用的 Codex desktop installer URL。 |
如果 Codex Desktop 已安装，codex app 会打开它；如果缺失，会启动 installer。macOS 会打开提供的 workspace path；Windows 会在安装后打印要打开的 path。
codex debug app-server send-message-v2
通过内置 app-server test client 发送一条 message，走 app-server 的 V2 thread / turn flow。
| Option | Type | Description |
|---|---|---|
USER_MESSAGE | string | 通过内置 V2 test-client flow 发送到 app-server 的 message text。 |
这个 debug flow 会以 experimentalApi: true 初始化，启动 thread，发送 turn，并 stream server notifications。用于本地复现和检查 app-server protocol behavior。
codex debug models
以 JSON 打印 Codex 看到的 raw model catalog。
| Option | Type | Default | Description |
|---|---|---|---|
--bundled | boolean | false | 跳过 refresh，只打印当前 Codex binary 内置的 model catalog。 |
codex apply
把 Codex cloud task 的最新 diff 应用到本地 repository。你必须已认证，并且有权限访问该 task。
| Option | Type | Description |
|---|---|---|
TASK_ID | string | 要应用 diff 的 Codex Cloud task identifier。 |
Codex 会打印 patched files。如果 git apply 失败，例如发生 conflicts，会以 non-zero 退出。
codex cloud
从 terminal 与 Codex cloud tasks 交互。默认命令打开 interactive picker；codex cloud exec 直接提交任务；codex cloud list 返回 recent tasks，适合 scripting 或快速检查。
codex cloud exec：
| Option | Type | Default | Description |
|---|---|---|---|
QUERY | string | - | Task prompt。省略时 Codex 会交互式询问细节。 |
--env | ENV_ID | - | 目标 Codex Cloud environment identifier。必填。用 codex cloud 查看可选项。 |
--attempts | 1-4 | 1 | 请求 Codex Cloud 运行多少个 assistant attempts，也就是 best-of-N。 |
Authentication 复用主 CLI credentials。任务提交失败时，Codex non-zero 退出。
codex cloud list：
| Option | Type | Default | Description |
|---|---|---|---|
--env | ENV_ID | - | 按 environment identifier 过滤 tasks。 |
--limit | 1-20 | 20 | 最多返回多少 tasks。 |
--cursor | string | - | 上一次 request 返回的 pagination cursor。 |
--json | boolean | false | 输出 machine-readable JSON，而不是 plain text。 |
Plain-text 输出包含 task URL 和 status details。--json 适合自动化。JSON payload 包含 tasks array 和可选 cursor。每个 task 包括 id、url、title、status、updated_at、environment_id、environment_label、summary、is_review、attempt_total。
codex completion
生成 shell completion scripts，例如：
codex completion zsh > "${fpath[1]}/_codex"| Option | Type | Default | Description |
|---|---|---|---|
SHELL | bash / zsh / fish / power-shell / elvish | bash | 要生成 completions 的 shell。输出打印到 stdout。 |
codex features
管理保存在 ~/.codex/config.toml 中的 feature flags。enable 和 disable 会持久化变更，应用到未来 sessions。使用 --profile 启动时，Codex 写入该 profile，而不是 root configuration。
| Subcommand | Type | Description |
|---|---|---|
| List subcommand | codex features list | 显示已知 feature flags、maturity stage 和 effective state。 |
| Enable subcommand | codex features enable <feature> | 在 config.toml 中持久启用 feature flag。提供 --profile 时遵守 active profile。 |
| Disable subcommand | codex features disable <feature> | 在 config.toml 中持久禁用 feature flag。提供 --profile 时遵守 active profile。 |
codex exec
codex exec，短写 codex e，用于 scripted 或 CI-style runs，不需要人工交互即可完成。
| Option | Type | Default | Description |
|---|---|---|---|
PROMPT | string / - (read stdin) | - | 任务初始 instruction。使用 - 可从 stdin 读取 prompt。 |
--image, -i | path[,path...] | - | 给第一条消息附加 images。可重复，支持逗号分隔列表。 |
--model, -m | string | - | 覆盖本次运行的 configured model。 |
--oss | boolean | false | 使用本地 open source provider，需要 Ollama 正在运行。 |
--sandbox, -s | read-only / workspace-write / danger-full-access | 配置值 | model-generated commands 的 sandbox policy。 |
--profile, -p | string | - | 选择 config.toml 中定义的 configuration profile。 |
--full-auto | boolean | false | deprecated compatibility flag。优先使用 --sandbox workspace-write；使用时 Codex 会打印 warning。 |
--dangerously-bypass-approvals-and-sandbox, --yolo | boolean | false | 绕过 approval prompts 和 sandboxing。危险，只应在 isolated runner 中使用。 |
--cd, -C | path | - | 执行任务前设置 workspace root。 |
--skip-git-repo-check | boolean | false | 允许在 Git repository 外运行，适合一次性目录。 |
--ephemeral | boolean | false | 运行时不把 session rollout files 持久化到磁盘。 |
--ignore-user-config | boolean | false | 不加载 $CODEX_HOME/config.toml。Authentication 仍使用 CODEX_HOME。 |
--ignore-rules | boolean | false | 本次运行不加载 user 或 project execpolicy .rules files。 |
--output-schema | path | - | 描述 expected final response shape 的 JSON Schema 文件。Codex 会按它验证 tool output。 |
--color | always / never / auto | auto | 控制 stdout 中 ANSI color。 |
--json, --experimental-json | boolean | false | 输出 newline-delimited JSON events，而不是 formatted text。 |
--output-last-message, -o | path | - | 把 assistant final message 写入文件，适合 downstream scripting。 |
| Resume subcommand | codex exec resume [SESSION_ID] | - | 按 ID 恢复 exec session；加 --last 继续当前 working directory 最近 session；加 --all 搜索任意目录 session。可接受可选 follow-up prompt。 |
-c, --config | key=value | - | 非交互运行的 inline configuration override。可重复。 |
默认输出为 formatted text。加 --json 会收到 newline-delimited JSON events，每个 state change 一行。
resume subcommand 可继续非交互任务。使用 --last 选择当前 working directory 最近 session；使用 --all 跨所有 sessions 搜索。
codex exec resume 选项：
| Option | Type | Default | Description |
|---|---|---|---|
SESSION_ID | uuid | - | 恢复指定 session。省略并用 --last 可继续最近 session。 |
--last | boolean | false | 恢复当前 working directory 最近 conversation。 |
--all | boolean | false | 选择最近 session 时包含当前 working directory 之外的 sessions。 |
--image, -i | path[,path...] | - | 给 follow-up prompt 附加一张或多张图片。多路径用逗号分隔，也可重复 flag。 |
PROMPT | string / - (read stdin) | - | 恢复后立刻发送的可选 follow-up instruction。 |
codex execpolicy
保存 execpolicy rules 前，可以用 codex execpolicy check 检查。
它接受一个或多个 --rules flags，例如 ~/.codex/rules 下的文件，并输出 JSON，说明 strictest decision 和命中的 rules。加 --pretty 可格式化输出。
这个命令当前处于 preview。
| Option | Type | Default | Description |
|---|---|---|---|
--rules, -r | path (repeatable) | - | 要评估的 execpolicy rule file。多个 flags 可合并多个文件的 rules。 |
--pretty | boolean | false | pretty-print JSON result。 |
COMMAND... | var-args | - | 要根据指定 policies 检查的 command。 |
codex login
用 ChatGPT account 或 API key 认证 CLI。不带 flags 时，Codex 会打开 browser 执行 ChatGPT OAuth flow。
| Option | Type | Description |
|---|---|---|
--with-api-key | boolean | 从 stdin 读取 API key，例如 printenv OPENAI_API_KEY | codex login --with-api-key。 |
--device-auth | boolean | 使用 OAuth device code flow，而不是启动浏览器窗口。 |
| status subcommand | codex login status | 打印当前 authentication mode；登录状态存在时 exit code 为 0。 |
codex login status 在 automation scripts 中很有用。
codex logout
删除 API key 和 ChatGPT authentication 的 saved credentials。没有 flags。
codex mcp
管理保存在 ~/.codex/config.toml 中的 Model Context Protocol server entries。
| Command | Type | Description |
|---|---|---|
list | --json | 列出已配置 MCP servers。加 --json 输出 machine-readable 内容。 |
get <name> | --json | 显示指定 server configuration。--json 会打印 raw config entry。 |
add <name> | -- <command...> / --url <value> | 用 stdio launcher command 或 streamable HTTP URL 注册 server。stdio transports 支持 --env KEY=VALUE。 |
remove <name> | - | 删除保存的 MCP server definition。 |
login <name> | --scopes scope1,scope2 | 为 streamable HTTP server 启动 OAuth login。仅支持 OAuth 的 servers 可用。 |
logout <name> | - | 删除 streamable HTTP server 保存的 OAuth credentials。 |
add subcommand 同时支持 stdio 和 streamable HTTP transports：
| Option | Type | Description |
|---|---|---|
COMMAND... | stdio transport | 启动 MCP server 的 executable 和 arguments。放在 -- 后。 |
--env KEY=VALUE | repeatable | 启动 stdio server 时应用的 environment variable assignments。 |
--url | https://... | 注册 streamable HTTP server，而不是 stdio。与 COMMAND... 互斥。 |
--bearer-token-env-var | ENV_VAR | 连接 streamable HTTP server 时，发送该环境变量中的值作为 bearer token。 |
OAuth actions（login、logout）只适用于 streamable HTTP servers，并且 server 必须支持 OAuth。
codex plugin marketplace
管理 Codex 可浏览和安装的 plugin marketplace sources。
| Command | Type | Description |
|---|---|---|
add <source> | [--ref REF] [--sparse PATH] | 从 GitHub shorthand、Git URL、SSH URL 或 local marketplace root directory 安装 plugin marketplace。--sparse 只支持 Git sources，可重复。 |
upgrade [marketplace-name] | - | 刷新一个已配置 Git marketplace；不传 name 时刷新所有已配置 Git marketplaces。 |
remove <marketplace-name> | - | 删除已配置 plugin marketplace。 |
codex plugin marketplace add 接受：
- GitHub shorthand，例如
owner/repo或owner/repo@ref。 - HTTP / HTTPS Git URLs。
- SSH Git URLs。
- local marketplace root directories。
用 --ref 固定 Git ref。对 Git-backed marketplace repositories，可重复 --sparse PATH 进行 sparse checkout。
codex mcp-server
通过 stdio 把 Codex 作为 MCP server 运行，供其他工具连接。该命令继承 global configuration overrides，并在 downstream client 关闭连接时退出。
codex resume
按 ID 继续 interactive session，或恢复最近 conversation。codex resume --last 默认只查当前 working directory；传 --all 可查所有目录。它接受与 codex 相同的 global flags，包括 model 和 sandbox overrides。
| Option | Type | Default | Description |
|---|---|---|---|
SESSION_ID | uuid | - | 恢复指定 session。省略并用 --last 可继续最近 session。 |
--last | boolean | false | 跳过 picker，恢复当前 working directory 最近 conversation。 |
--all | boolean | false | 选择最近 session 时包含当前 working directory 之外的 sessions。 |
codex fork
把 previous interactive session fork 成 new thread。默认打开 session picker；加 --last 可 fork 最近 session。
| Option | Type | Default | Description |
|---|---|---|---|
SESSION_ID | uuid | - | Fork 指定 session。省略并用 --last 可 fork 最近 session。 |
--last | boolean | false | 跳过 picker，自动 fork 最近 conversation。 |
--all | boolean | false | 在 picker 中显示当前 working directory 之外的 sessions。 |
codex sandbox
Sandbox helper 可以用和 Codex 内部一致的 policies 运行命令。
macOS seatbelt
| Option | Type | Default | Description |
|---|---|---|---|
--permissions-profile | NAME | - | 应用 active configuration stack 中的 named permissions profile。 |
--cd, -C | DIR | - | 用于 profile resolution 和 command execution 的 working directory。要求 --permissions-profile。 |
--include-managed-config | boolean | false | 解析 explicit permissions profile 时包含 managed requirements。要求 --permissions-profile。 |
--allow-unix-socket | path | - | 允许 sandboxed command bind 或 connect rooted at this path 的 Unix sockets。可重复。 |
--log-denials | boolean | false | 命令运行时用 log stream 捕获 macOS sandbox denials，并在退出后打印。 |
--config, -c | key=value | - | 给 sandboxed run 传入 configuration overrides。可重复。 |
COMMAND... | var-args | - | 在 macOS Seatbelt 下执行的 shell command。-- 后的内容会被转发。 |
Linux Landlock
| Option | Type | Default | Description |
|---|---|---|---|
--permissions-profile | NAME | - | 应用 active configuration stack 中的 named permissions profile。 |
--cd, -C | DIR | - | 用于 profile resolution 和 command execution 的 working directory。要求 --permissions-profile。 |
--include-managed-config | boolean | false | 解析 explicit permissions profile 时包含 managed requirements。要求 --permissions-profile。 |
--config, -c | key=value | - | 启动 sandbox 前应用的 configuration overrides。可重复。 |
COMMAND... | var-args | - | 在 Landlock + seccomp 下执行的 command。executable 放在 -- 后。 |
Windows
| Option | Type | Default | Description |
|---|---|---|---|
--permissions-profile | NAME | - | 应用 active configuration stack 中的 named permissions profile。 |
--cd, -C | DIR | - | 用于 profile resolution 和 command execution 的 working directory。要求 --permissions-profile。 |
--include-managed-config | boolean | false | 解析 explicit permissions profile 时包含 managed requirements。要求 --permissions-profile。 |
--config, -c | key=value | - | 启动 sandbox 前应用的 configuration overrides。可重复。 |
COMMAND... | var-args | - | 在 native Windows sandbox 下执行的 command。executable 放在 -- 后。 |
codex update
当安装版本支持 self-update 时，检查并应用 Codex CLI 更新。Debug builds 会打印消息，提示你安装 release build。
Flag combinations and safety tips
- 对 unattended local work，如果工作范围可以留在 workspace 内，使用
--sandbox workspace-write。 - 除非你在 dedicated sandbox VM 中运行，否则避免
--dangerously-bypass-approvals-and-sandbox。 - 需要给 Codex 更多目录 write access 时，优先用
--add-dir，不要直接使用--sandbox danger-full-access。 - 在 CI 中把
--json与--output-last-message搭配使用，既能捕获 machine-readable progress，也能保存最终自然语言总结。
Related resources
- Codex CLI overview： https://developers.openai.com/codex/cli
- Config basics： https://developers.openai.com/codex/config-basic
- Advanced Config： https://developers.openai.com/codex/config-advanced
- AGENTS.md： https://developers.openai.com/codex/guides/agents-md