如何阅读本页
本页汇总了所有已文档化的 Codex CLI 命令和选项。你可以按命令名或说明来查找。每个章节都会标明该功能是稳定还是实验性，并指出哪些组合存在更高风险。
全局选项
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--add-dir |
path | 在主工作区之外，额外授予其他目录写权限。可重复传入多个路径。 |
--ask-for-approval, -a |
untrusted | on-request | never |
控制 Codex 在运行命令前何时暂停并请求人工批准。on-failure 已弃用；交互模式推荐 on-request，非交互模式推荐 never。 |
--cd, -C |
path | 在智能体开始处理请求前设置工作目录。 |
--config, -c |
key=value |
覆盖配置值。若可解析为 JSON，则按 JSON 解析；否则按字面字符串处理。 |
--dangerously-bypass-approvals-and-sandbox, --yolo |
boolean | 绕过所有审批与沙箱。只应在外部已加固的环境中使用。 |
--disable |
feature | 强制关闭某个 功能开关（等价于 -c features.<name>=false）。可重复。 |
--enable |
feature | 强制开启某个 功能开关（等价于 -c features.<name>=true）。可重复。 |
--full-auto |
boolean | 用于低摩擦本地工作的快捷方式：设置 --ask-for-approval on-request 和 --sandbox workspace-write。 |
--image, -i |
path[,path...] |
把一张或多张图片附加到初始提示词。可用逗号分隔多个路径，也可重复传 flag。 |
--model, -m |
string | 覆盖配置中的 model，例如 gpt-5.4。 |
--no-alt-screen |
boolean | 关闭 TUI 的 alternate screen mode（仅覆盖本次运行中的 tui.alternate_screen）。 |
--oss |
boolean | 使用本地开源模型提供方（等价于 -c model_provider=\"oss\"）。会检查 Ollama 是否已运行。 |
--profile, -p |
string | 从 ~/.codex/config.toml 中加载指定配置档案。 |
--sandbox, -s |
read-only | workspace-write | danger-full-access |
为模型生成的 shell 命令选择 sandbox 策略。 |
--search |
boolean | 开启实时 web search（把 web_search 从默认的 "cached" 切换为 "live"）。 |
| PROMPT | string | 可选的初始提示词。省略时只启动 TUI，而不预填消息。 |
这些选项适用于基础 codex 命令，并会传播给各个子命令，除非下文明确说明例外。运行子命令时，建议把全局选项写在子命令后面，例如 codex exec --oss ...，这样 Codex 才能按预期解析。
命令总览
| 命令 | 成熟度 | 说明 |
|---|---|---|
| codex | 稳定 | 启动终端 UI。接受上面的全局选项，以及可选提示词或图片附件。 |
| codex app | 稳定 | 在 macOS 上启动 Codex 桌面 App，并可选择直接打开某个工作区路径。 |
| codex app-server | 实验性 | 启动本地 Codex app-server，用于开发或调试。 |
| codex apply | 稳定 | 把最近一次 Codex Cloud 任务生成的 diff 应用到本地工作树。别名：codex a。 |
| codex cloud | 实验性 | 在终端里浏览或执行 Codex Cloud 任务，而不必打开 TUI。别名：codex cloud-tasks。 |
| codex completion | 稳定 | 为 Bash、Zsh、Fish 或 PowerShell 生成 shell 补全脚本。 |
| codex debug app-server send-message-v2 | 实验性 | 通过内置测试客户端向 app-server 发送单条 V2 消息，便于调试。 |
| codex exec | 稳定 | 以非交互模式运行 Codex。可输出 stdout 或 JSONL，也可恢复历史会话。别名：codex e。 |
| codex execpolicy | 实验性 | 评估 execpolicy 规则文件，查看某条命令会被允许、要求批准还是被阻止。 |
| codex features | 稳定 | 列出功能开关，并把启用 / 禁用状态持久写入 config.toml。 |
| codex fork | 稳定 | 把一个已有交互会话分叉成新线程，保留原始对话记录。 |
| codex login | 稳定 | 通过 ChatGPT OAuth、device auth 或从 stdin 读取 API key 来认证 Codex。 |
| codex logout | 稳定 | 删除已保存的认证凭据。 |
| codex mcp | 实验性 | 管理 Model Context Protocol Server（列出、添加、删除、认证）。 |
| codex mcp-server | 实验性 | 通过 stdio 把 Codex 自身作为 MCP 服务端运行，便于被其他智能体调用。 |
| codex resume | 稳定 | 按 ID 恢复某个交互会话，或恢复最近一次对话。 |
| codex sandbox | 实验性 | 在 Codex 提供的 macOS Seatbelt 或 Linux 沙箱中运行任意命令。Linux 默认使用 Landlock，可选 bubblewrap 管线。 |
命令细节
codex（交互模式）
直接运行 codex 而不带子命令时，会启动交互式终端 UI（TUI）。智能体会接受前面列出的全局选项，也支持附加图片。Web 搜索默认使用 cached 模式；使用 --search 可切换到实时浏览，使用 --full-auto 则可让 Codex 在大多数情况下无需提示就直接运行命令。
如果要把 TUI 连接到远程 app server，可使用 --remote ws://host:port 或 --remote wss://host:port，并将其指向通过 codex app-server --listen ws://IP:PORT 启动的服务端。如果服务端要求通过 WebSocket 使用 bearer token 认证，可额外传入 --remote-auth-token-env <ENV_VAR>。配置示例和认证说明，参见 Codex CLI 功能。
codex app-server
在本地启动 Codex app-server。这个命令主要用于开发和调试，未来可能会变更。
| 选项 | 类型 / 可选值 | 默认值 | 说明 |
|---|---|---|---|
--listen |
stdio:// | ws://IP:PORT |
stdio:// |
传输监听 URL。若要向远程客户端暴露 WebSocket 端点，请使用 ws://IP:PORT。 |
--ws-auth |
capability-token | signed-bearer-token |
为 app-server 的 WebSocket 客户端指定认证模式。若省略，则不会启用 WebSocket 认证；如果监听地址不是本地地址，启动时会给出警告。 | |
--ws-token-file |
absolute path | 包含共享 capability token 的文件路径。使用 --ws-auth capability-token 时必填。 |
|
--ws-shared-secret-file |
absolute path | 包含 HMAC 共享密钥的文件路径，用于校验已签名的 JWT bearer token。使用 --ws-auth signed-bearer-token 时必填。 |
|
--ws-issuer |
string | 已签名 bearer token 中预期的 iss 声明值。要求同时使用 --ws-auth signed-bearer-token。 |
|
--ws-audience |
string | 已签名 bearer token 中预期的 aud 声明值。要求同时使用 --ws-auth signed-bearer-token。 |
|
--ws-max-clock-skew-seconds |
number | 30 |
校验已签名 bearer token 的 exp 和 nbf 声明时，允许的时钟偏差秒数。要求同时使用 --ws-auth signed-bearer-token。 |
codex app-server --listen stdio:// 会继续使用默认的 JSONL-over-stdio 传输方式。--listen ws://IP:PORT 会为 app-server 客户端启用 WebSocket 传输。服务端接受 ws:// 作为监听 URL；如果客户端通过 wss:// 连接，则应在前面配置 TLS 终止或安全代理。如果你要为客户端绑定生成 schema，请额外加上 --experimental，这样受门控的字段和方法也会一并包含进去。
codex app
从终端启动 Codex Desktop（macOS），并可选择直接打开某个工作区路径。
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--download-url |
url | 高级覆盖项，用于替换安装阶段使用的 Codex desktop DMG 下载地址。 |
| PATH | path | 要在 Codex Desktop 中打开的工作区路径（codex app 仅在 macOS 上可用）。 |
codex app 会在 macOS 上安装 / 打开桌面 app，并打开给定工作区路径。这个子命令仅支持 macOS。
codex debug app-server send-message-v2
使用内置 app-server test client，通过 app-server 的 V2 thread / turn 流程发送一条消息。
| 参数 | 类型 / 可选值 | 说明 |
|---|---|---|
USER_MESSAGE |
string | 通过内置 V2 test-client 流程发送给 app-server 的消息文本。 |
这个调试流程会以 experimentalApi: true 初始化，然后启动线程、发送 turn，并流式输出 server 通知。适合在本地复现和观察 app-server 协议行为。
codex apply
把最近一次 Codex Cloud 任务生成的 diff 应用到本地仓库。你必须已经认证，而且对该任务具有访问权限。
| 参数 | 类型 / 可选值 | 说明 |
|---|---|---|
TASK_ID |
string | 要应用其 diff 的 Codex Cloud 任务 ID。 |
Codex 会打印被 patch 的文件；如果 git apply 失败（例如发生冲突），则以非零状态码退出。
codex cloud
在终端中操作 Codex Cloud 任务。默认命令会打开一个交互式选择器；codex cloud exec 可直接提交任务；codex cloud list 则可返回最近任务，便于脚本调用或快速查看。
| 参数 | 类型 / 可选值 | 说明 |
|---|---|---|
--attempts |
1-4 |
Codex Cloud 要运行的 assistant 尝试次数（best-of-N）。 |
--env |
ENV_ID |
目标 Codex Cloud environment ID（必填）。可先运行 codex cloud 查看可用值。 |
| QUERY | string | 任务提示词。若省略，Codex 会交互式提示你输入。 |
认证沿用主 CLI 使用的同一套凭据。若任务提交失败，Codex 会以非零状态码退出。
codex cloud list
列出最近的 Cloud 任务，并支持过滤和分页。
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--cursor |
string | 上一次请求返回的分页游标。 |
--env |
ENV_ID |
按 environment ID 过滤任务。 |
--json |
boolean | 输出机器可读 JSON，而不是纯文本。 |
--limit |
1-20 |
最多返回多少个任务。 |
纯文本输出会打印任务 URL 及状态信息；自动化场景请优先使用 --json。JSON 负载中包含 tasks 数组和可选的 cursor 值。每个任务会带有 id、url、title、status、updated_at、environment_id、environment_label、summary、is_review 和 attempt_total 字段。
codex completion
生成 shell completion 脚本，并把输出重定向到合适位置，例如 codex completion zsh > "${fpath[1]}/_codex"。
| 参数 | 类型 / 可选值 | 说明 |
|---|---|---|
| SHELL | bash | zsh | fish | power-shell | elvish |
要生成 completion 的 shell 类型。输出写到 stdout。 |
codex features
管理保存在 ~/.codex/config.toml 中的功能开关。enable 与 disable 子命令会把变更持久写入配置，以便对后续会话生效。若你使用 --profile 启动，Codex 会把修改写到该配置档案，而不是根配置中。
| 子命令 | 类型 / 可选值 | 说明 |
|---|---|---|
Disable subcommand |
codex features disable <feature> |
在 config.toml 中持久禁用某个功能开关。若传了 --profile，则写入对应配置档案。 |
Enable subcommand |
codex features enable <feature> |
在 config.toml 中持久启用某个功能开关。若传了 --profile，则写入对应配置档案。 |
List subcommand |
codex features list |
展示已知功能开关、成熟度阶段以及当前生效状态。 |
codex exec
对于脚本式或 CI 风格的运行，请使用 codex exec（短命令是 codex e）。它会在无需人工交互的前提下完成任务。
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--cd, -C |
path | 在执行任务前设置工作区根目录。 |
--color |
always | never | auto |
控制 stdout 中 ANSI 颜色的输出。 |
--dangerously-bypass-approvals-and-sandbox, --yolo |
boolean | 绕过审批与沙箱。风险极高，只能在隔离运行器中使用。 |
--ephemeral |
boolean | 运行时不把会话运行记录文件持久化到磁盘。 |
--full-auto |
boolean | 应用低摩擦自动化预设：workspace-write 沙箱加 on-request 审批。 |
--image, -i |
path[,path...] |
给首条消息附加图片。可重复，也支持逗号分隔多个路径。 |
--json, --experimental-json |
boolean | 输出按行分隔的 JSON 事件，而不是格式化文本。 |
--model, -m |
string | 覆盖本次运行所使用的 model。 |
--oss |
boolean | 使用本地开源提供方（要求 Ollama 正在运行）。 |
--output-last-message, -o |
path | 把 assistant 的最终消息写入文件，适合供下游脚本读取。 |
--output-schema |
path | 描述最终输出结构的 JSON Schema 文件。Codex 会按此校验工具输出。 |
--profile, -p |
string | 选择 config.toml 中定义的某个配置档案。 |
--sandbox, -s |
read-only | workspace-write | danger-full-access |
模型生成命令所使用的沙箱策略。默认取配置值。 |
--skip-git-repo-check |
boolean | 允许在 Git 仓库之外运行（适合一次性目录）。 |
-c, --config |
key=value |
为这次非交互执行内联覆盖配置（可重复）。 |
| PROMPT | string | - (read stdin) |
任务的初始提示词。传 - 表示从 stdin 读取提示词。 |
Resume subcommand |
codex exec resume [SESSION_ID] |
按 ID 恢复某个 exec 会话；或配合 --last 恢复当前工作目录下最近一次会话；加 --all 可跨目录查找。也支持额外跟一条后续提示词。 |
默认情况下，Codex 会输出格式化文本。加上 --json 后，会改为输出按行分隔的 JSON 事件（每个状态变化一条）。可选的 resume 子命令用于续跑非交互任务。使用 --last 会选取当前工作目录下最近的会话；如果要跨所有会话查找，则再加上 --all：
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--all |
boolean | 在选择最近会话时，把当前工作目录之外的会话也纳入候选。 |
--image, -i |
path[,path...] |
给后续提示词附加一张或多张图片。可重复，也支持逗号分隔路径。 |
--last |
boolean | 恢复当前工作目录下最近一次对话。 |
| PROMPT | string | - (read stdin) |
恢复后立即发送的可选后续指令。 |
SESSION_ID |
uuid | 恢复指定会话。若省略，则需配合 --last 使用。 |
codex execpolicy
在保存 execpolicy 规则文件前先做检查。codex execpolicy check 接受一个或多个 --rules flag（例如指向 ~/.codex/rules 下的文件），并输出 JSON，说明最严格的决策结果以及命中的规则。加上 --pretty 可格式化输出。execpolicy 当前仍属预览功能。
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--pretty |
boolean | 以更易读的格式打印 JSON 结果。 |
--rules, -r |
path (repeatable) |
要评估的 execpolicy 规则文件路径。可传多个，组合多份规则一起判断。 |
COMMAND... |
var-args |
要按指定策略进行检查的命令。 |
codex login
使用 ChatGPT 账号或 API key 对 CLI 进行认证。不加任何 flags 时，Codex 会打开浏览器走 ChatGPT OAuth 流程。
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--device-auth |
boolean | 使用 OAuth 设备码流程，而不是直接拉起浏览器。 |
--with-api-key |
boolean | 从 stdin 读取 API key，例如 printenv OPENAI_API_KEY | codex login --with-api-key。 |
status subcommand |
codex login status |
打印当前认证方式；若已登录则以退出码 0 返回。 |
codex login status 在凭据存在时返回 0，因此很适合在自动化脚本中做登录状态检查。
codex logout
删除已保存的 API key 与 ChatGPT 认证凭据。这个命令没有额外 flags。
codex mcp
管理保存在 ~/.codex/config.toml 中的模型上下文协议服务端配置。
| 子命令 | 类型 / 可选值 | 说明 |
|---|---|---|
add <name> |
-- <command...> | --url <value> |
使用 stdio 启动命令或 streamable HTTP URL 注册一个服务端。对 stdio 传输还支持 --env KEY=VALUE。 |
get <name> |
--json |
查看某个服务端的配置。--json 会打印原始配置项。 |
| list | --json |
列出已配置的 MCP 服务端。加 --json 可输出机器可读结果。 |
login <name> |
--scopes scope1,scope2 |
为某个 streamable HTTP 服务端发起 OAuth 登录（仅对支持 OAuth 的服务端有效）。 |
logout <name> |
删除某个 streamable HTTP 服务端的已保存 OAuth 凭据。 | |
remove <name> |
删除已保存的 MCP 服务端定义。 |
add 子命令同时支持 stdio 和 streamable HTTP 两种传输方式：
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--bearer-token-env-var |
ENV_VAR |
连接 streamable HTTP 服务端时，取这个环境变量的值作为 bearer token。 |
--env KEY=VALUE |
repeatable | 启动 stdio 服务端时附带的环境变量。 |
--url |
https://… |
注册 streamable HTTP 服务端，而不是 stdio。与 COMMAND... 互斥。 |
COMMAND... |
stdio transport |
用于启动 MCP 服务端的可执行文件及参数。需要放在 -- 之后。 |
OAuth 相关动作（login、logout）只适用于 streamable HTTP 服务端，而且服务端本身也必须支持 OAuth。
codex mcp-server
通过 stdio 把 Codex 自身作为 MCP 服务端运行，以便其他工具接入。这个命令会继承全局配置覆盖项，并在下游客户端关闭连接时退出。
codex resume
按 ID 恢复某个交互会话，或恢复最近一次对话。codex resume 会把 --last 默认限制在当前工作目录；如果你传 --all，则会跨目录查找。它支持与 codex 相同的全局选项，包括 model 和沙箱覆盖项。
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--all |
boolean | 在选择最近对话时，把当前工作目录之外的 session 一并纳入候选。 |
--last |
boolean | 跳过选择器，直接恢复当前工作目录下最近一次对话。 |
SESSION_ID |
uuid | 恢复指定会话。若省略，则需配合 --last 使用。 |
codex fork
把一个已有交互会话分叉成新线程。默认情况下，codex fork 会打开会话选择器；如果你加上 --last，则会直接分叉最近一次会话。
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--all |
boolean | 在选择器中显示当前工作目录之外的会话。 |
--last |
boolean | 跳过选择器，直接分叉最近一次对话。 |
SESSION_ID |
uuid | 分叉指定会话。若省略，则需配合 --last 使用。 |
codex sandbox
使用沙箱辅助工具，以与 Codex 内部一致的策略来运行某条命令。
macOS seatbelt
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--config, -c |
key=value |
向沙箱运行注入配置覆盖项（可重复）。 |
--full-auto |
boolean | 无需审批即可为当前工作区和 /tmp 授予写权限。 |
COMMAND... |
var-args |
在 macOS Seatbelt 中执行的 shell 命令。-- 之后的内容都会原样转发。 |
Linux Landlock
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--config, -c |
key=value |
在启动沙箱前应用配置覆盖项（可重复）。 |
--full-auto |
boolean | 在 Landlock 沙箱中为当前工作区和 /tmp 授予写权限。 |
COMMAND... |
var-args |
在 Landlock + seccomp 中执行的命令。可执行文件需放在 -- 之后。 |
选项组合与安全建议
--full-auto与--dangerously-bypass-approvals-and-sandbox不要混为一谈。前者仍然保留沙箱和审批体系，只是把它们调到更低摩擦的组合；后者则直接绕过二者。- 当你已经使用
--sandbox danger-full-access时，--add-dir额外放行目录的意义会显著下降，因为这时沙箱已经不再限制目录边界。 - 如果你既要消费机器可读事件流，又想保留最终自然语言结果，可把
--json与--output-last-message组合使用。