Codex CLI 参考

本页汇总了所有已文档化的 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	覆盖配置值。若可解析为 TOML，则按 TOML 解析；否则按字面字符串处理。
`--dangerously-bypass-approvals-and-sandbox`, `--yolo`	boolean	绕过所有审批与沙箱。只应在外部已加固的环境中使用。
`--dangerously-bypass-hook-trust`	boolean	本次调用运行已启用的 hooks 时，不要求存在已持久化的 hook 信任记录。仅适用于已经在 Codex 外部审核 hook 来源的自动化环境。
`--disable`	feature	强制关闭某个功能开关（等价于 -c features.=false）。可重复。
`--enable`	feature	强制开启某个功能开关（等价于 -c features.=true）。可重复。
`--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_HOME/profile-name.config.toml。
`--remote`	ws://host:port \| wss://host:port \| unix:// \| unix://PATH	通过 WebSocket 或 Unix socket 把交互式 TUI 连接到远程 app-server 端点。支持 codex、codex resume 和 codex fork；其他子命令会拒绝 remote mode。
`--remote-auth-token-env`	ENV_VAR	从这个环境变量读取 bearer token，并在通过 --remote 连接时发送。要求同时使用 --remote；token 只会通过 wss:// URL 或 local-only ws:// URL 发送。
`--sandbox`, `-s`	read-only \| workspace-write \| danger-full-access	为模型生成的 shell 命令选择沙箱策略。
`--search`	boolean	开启实时 web search（把 web_search 从默认的 "cached" 切换为 "live"）。
`--strict-config`	boolean	当 config.toml 中包含当前 Codex 版本不认识的字段时直接报错。codex、exec、review、resume、fork、app-server、mcp-server 和 exec-server 等运行时命令支持该选项。
`PROMPT`	string	可选的初始提示词。省略时只启动 TUI，而不预填消息。

这些选项适用于基础 codex 命令，并会传播给各个子命令，除非下文明确说明例外。运行子命令时，建议把全局选项写在子命令后面，例如 codex exec --oss ...，这样 Codex 才能按预期解析。

命令总览

命令	成熟度	说明
`codex`	稳定	启动终端 UI。接受上面的全局选项，以及可选提示词或图片附件。
`codex app`	稳定	在 macOS 或 Windows 上启动 Codex 桌面 App。macOS 可打开工作区路径；Windows 会打印要打开的路径。
`codex app-server`	实验性	通过 stdio、WebSocket 或 Unix socket 启动本地 Codex app-server，用于开发或调试。
`codex apply`	稳定	把最近一次 Codex 云端任务生成的 diff 应用到本地工作树。别名：`codex a`。
`codex archive`	稳定	按 session ID 或 session 名称归档已保存的交互会话。
`codex cloud`	实验性	在终端里浏览或执行 Codex 云端任务，而不必打开 TUI。别名：`codex cloud-tasks`。
`codex completion`	稳定	为 Bash、Zsh、Fish 或 PowerShell 生成 shell 补全脚本。
`codex doctor`	稳定	为本地安装、配置、认证、运行时、Git、终端、app-server 和线程清单问题生成诊断报告。
`codex debug app-server send-message-v2`	实验性	通过内置测试客户端向 app-server 发送单条 V2 消息，便于调试。
`codex debug models`	实验性	打印 Codex 看到的原始 model catalog，也可只查看当前二进制内置的 catalog。
`codex exec`	稳定	以非交互模式运行 Codex。可输出 stdout 或 JSONL，也可恢复历史会话。别名：`codex e`。
`codex execpolicy`	实验性	评估 execpolicy 规则文件，查看某条命令会被允许、要求批准还是被阻止。
`codex features`	稳定	列出功能开关，并把启用 / 禁用状态持久写入当前活动配置文件。
`codex fork`	稳定	把一个已有交互会话分叉成新线程，保留原始对话记录。
`codex login`	稳定	通过 ChatGPT OAuth、设备码认证，或从 stdin 读取 API key / access token 来认证 Codex。
`codex logout`	稳定	删除已保存的认证凭据。
`codex mcp`	实验性	管理 Model Context Protocol Server（列出、添加、删除、认证）。
`codex plugin marketplace`	实验性	从 Git 或本地来源添加、列出、升级或移除插件市场。
`codex plugin`	实验性	从已配置的 marketplace 来源安装、列出或移除插件。
`codex mcp-server`	实验性	通过 stdio 把 Codex 自身作为 MCP server 运行，便于被其他智能体调用。
`codex remote-control`	实验性	确保本地 app-server daemon 正在运行，并启用了 remote-control 支持。
`codex resume`	稳定	按 ID 恢复某个交互会话，或恢复最近一次对话。
`codex sandbox`	实验性	在 Codex 提供的 macOS、Linux 或 Windows 沙箱中运行任意命令。
`codex update`	稳定	在已安装版本支持 self-update 时，检查并应用 Codex CLI 更新。
`codex unarchive`	稳定	按 session ID 或 session 名称恢复已归档的交互会话。

命令细节

codex（交互模式）

直接运行 codex 而不带子命令时，会启动交互式终端 UI（TUI）。智能体会接受前面列出的全局选项，也支持附加图片。Web 搜索默认使用 cached 模式；使用 --search 可切换到实时浏览。若要进行低摩擦本地工作，请使用 --sandbox workspace-write --ask-for-approval on-request。

如果要把 TUI 连接到远程 app server，可使用 --remote ws://host:port、 --remote wss://host:port、 --remote unix:// 或 --remote unix://PATH，并将其指向通过 codex app-server --listen ... 启动的服务端。如果服务端要求通过 WebSocket 使用 bearer token 认证，可额外传入 --remote-auth-token-env <ENV_VAR>。

codex app-server

在本地启动 Codex app-server。这个命令主要用于开发和调试，未来可能会变更。

选项	类型 / 可选值	默认值	说明
`--stdio`	boolean	false	使用 stdio 传输。等价于 --listen stdio://，并且与 --listen 互斥。
`--listen`	stdio:// \| ws://IP:PORT \| unix:// \| unix://PATH \| off	stdio://	传输监听 URL。用 stdio:// 表示 JSONL，ws://IP:PORT 表示 TCP WebSocket 端点，unix:// 表示默认 Unix socket，unix://PATH 表示自定义 Unix socket，off 表示禁用本地传输。
`--ws-auth`	capability-token \| signed-bearer-token		为 app-server 的 WebSocket 客户端指定认证模式。若省略，则不会启用 WebSocket 认证；如果监听地址不是本地地址，启动时会给出警告。
`--ws-token-file`	absolute path		包含共享 capability token 的文件路径。使用 --ws-auth capability-token 时传入，除非你改用 --ws-token-sha256。
`--ws-token-sha256`	hexadecimal SHA-256 digest		capability-token 认证所期望的 SHA-256 摘要。当客户端 token 来自其他来源时，可用它代替 --ws-token-file。
`--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。
`--analytics-default-enabled`	boolean	false	为第一方 app-server 客户端默认启用 analytics，除非用户在配置中选择退出。

codex app-server --listen stdio:// 会继续使用默认的 JSONL-over-stdio 传输方式， codex app-server --stdio 是这个传输方式的别名。 --listen ws://IP:PORT 会为 app-server 客户端启用 WebSocket 传输。服务端接受 ws:// 作为监听 URL；如果客户端通过 wss:// 连接，则应在前面配置 TLS 终止或安全代理。使用 --listen unix:// 可在 Codex 默认 Unix socket 上接受 WebSocket 握手；使用 --listen unix:///absolute/path.sock 可指定 socket 路径。如果你要为客户端绑定生成 schema，请额外加上 --experimental，这样受门控的字段和方法也会一并包含进去。

codex remote-control

确保 app-server daemon 正在运行，并启用了 remote-control 支持。托管 remote-control 客户端和 SSH 远程工作流会使用这个命令；如果你正在构建本地协议客户端，它不能替代 codex app-server --listen。

codex app

从终端启动 Codex Desktop（macOS 或 Windows）。在 macOS 上，Codex 可以直接打开指定工作区路径；在 Windows 上，Codex 会打印要打开的路径。

选项	类型 / 可选值	说明
`--download-url`	url	高级覆盖项，用于替换安装阶段使用的 Codex desktop installer 下载地址。
`PATH`	path	Codex Desktop 的工作区路径。在 macOS 上，Codex 会打开该路径；在 Windows 上，Codex 会打印该路径。

codex app 会打开已安装的 Codex Desktop app；如果缺少 app，则启动安装器。在 macOS 上，Codex 会打开给定工作区路径；在 Windows 上，安装后会打印要打开的路径。

codex debug app-server send-message-v2

使用内置 app-server 测试客户端，通过 app-server 的 V2 线程 / turn 流程发送一条消息。

参数	类型 / 可选值	说明
`USER_MESSAGE`	string	通过内置 V2 测试客户端流程发送给 app-server 的消息文本。

这个调试流程会以 experimentalApi: true 初始化，然后启动线程、发送 turn，并流式输出服务端通知。适合在本地复现和观察 app-server 协议行为。

codex debug models

以 JSON 形式打印 Codex 看到的原始 model catalog。

选项	类型 / 可选值	默认值	说明
`--bundled`	boolean	false	跳过刷新，只打印当前 Codex 二进制内置的 model catalog。

当你只想检查当前二进制打包的 catalog，而不从远程 models endpoint 刷新时，请使用 --bundled。

codex apply

把最近一次 Codex 云端任务生成的 diff 应用到本地仓库。你必须已经认证，而且对该任务具有访问权限。

参数	类型 / 可选值	说明
`TASK_ID`	string	要应用其 diff 的 Codex 云端任务 ID。

Codex 会打印被打补丁的文件；如果 git apply 失败（例如发生冲突），则以非零状态码退出。

codex archive 与 codex unarchive

按 session ID 或 session 名称归档或恢复已保存的交互会话。当你想清理 session 选择器、但不删除 transcript 时，可以使用这两个命令。session ID 的优先级高于 session 名称。

codex archive <SESSION>
codex unarchive <SESSION>

参数 / 选项	类型 / 可选值	说明
`SESSION`	session ID \| session name	要归档或恢复的已保存 session。session ID 的优先级高于 session 名称。
`--remote`	ws://host:port \| wss://host:port \| unix:// \| unix://PATH	在改变归档状态前，先连接到远程 app-server 端点。
`--remote-auth-token-env`	ENV_VAR	当 --remote 要求认证时，从这个环境变量读取 bearer token。

codex cloud

在终端中操作 Codex 云端任务。默认命令会打开一个交互式选择器； codex cloud exec 可直接提交任务； codex cloud list 则可返回最近任务，便于脚本调用或快速查看。

参数	类型 / 可选值	说明
`--attempts`	1-4	Codex 云端要运行的 assistant 尝试次数（best-of-N）。
`--env`	ENV_ID	目标 Codex 云端环境 ID（必填）。可先运行 codex cloud 查看可用值。
`QUERY`	string	任务提示词。若省略，Codex 会交互式提示你输入。

认证沿用主 CLI 使用的同一套凭据。若任务提交失败，Codex 会以非零状态码退出。

codex cloud list

列出最近的云端任务，并支持过滤和分页。

选项	类型 / 可选值	说明
`--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 doctor

生成经过脱敏的本地诊断报告，用于排查安装、配置、认证、运行时、Git、终端、app-server 和线程清单问题。

选项	类型 / 可选值	默认值	说明
`--json`	boolean	false	输出经过脱敏的机器可读支持报告。
`--summary`	boolean	false	只显示按组排列的检查行和最终数量摘要。
`--all`	boolean	false	在可读报告中展开较长列表。
`--no-color`	boolean	false	在可读输出中禁用 ANSI 颜色。
`--ascii`	boolean	false	在可读输出中使用 ASCII 状态标签和分隔符。

codex features

管理保存在 $CODEX_HOME/config.toml 中的功能开关。enable 与 disable 子命令会把变更持久写入配置，以便对后续会话生效。

子命令	类型 / 可选值	说明
Disable subcommand	`codex features disable`	在 $CODEX_HOME/config.toml 中持久禁用某个功能开关。
Enable subcommand	`codex features enable`	在 $CODEX_HOME/config.toml 中持久启用某个功能开关。
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	已弃用的兼容 flag。请优先使用 --sandbox workspace-write；使用该 flag 时 Codex 会打印警告。
`--ignore-user-config`	boolean	不加载 $CODEX_HOME/config.toml。认证仍会使用 CODEX_HOME。
`--ignore-rules`	boolean	本次运行不加载用户或项目 execpolicy .rules 文件。
`--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	在用户基础配置之上叠加 $CODEX_HOME/profile-name.config.toml。
`--sandbox`, `-s`	read-only \| workspace-write \| danger-full-access	模型生成命令所使用的沙箱策略。默认取配置值。
`--dangerously-bypass-hook-trust`	boolean	本次调用运行已启用的 hooks 时，不要求存在已持久化的 hook 信任记录。仅适用于已经在 Codex 外部审核 hook 来源的自动化环境。
`--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	要按指定策略进行检查的命令。

使用 ChatGPT 账号、API key 或 access token 对 CLI 进行认证。不加任何 flag 时，Codex 会打开浏览器走 ChatGPT OAuth 流程。

选项	类型 / 可选值	说明
`--device-auth`	boolean	使用 OAuth 设备码流程，而不是直接拉起浏览器。
`--with-api-key`	boolean	从 stdin 读取 API key，例如 `printenv OPENAI_API_KEY \| codex login --with-api-key`。
`--with-access-token`	boolean	从 stdin 读取 access token，例如 `printenv CODEX_ACCESS_TOKEN \| codex login --with-access-token`。
status subcommand	`codex login status`	打印当前认证方式；若已登录则以退出码 0 返回。

codex login status 在凭据存在时返回 0，因此很适合在自动化脚本中做登录状态检查。

codex logout

删除已保存的 API key 与 ChatGPT 认证凭据。这个命令没有额外 flag。

codex mcp

管理保存在 ~/.codex/config.toml 中的模型上下文协议服务端配置。

子命令	类型 / 可选值	说明
`add`	-- <command...> \| --url	使用 stdio 启动命令或 streamable HTTP URL 注册一个服务端。对 stdio 传输还支持 --env KEY=VALUE。
`get`	--json	查看某个服务端的配置。--json 会打印原始配置项。
`list`	--json	列出已配置的 MCP server。加 --json 可输出机器可读结果。
`login`	--scopes scope1,scope2	为某个 streamable HTTP 服务端发起 OAuth 登录（仅对支持 OAuth 的服务端有效）。
`logout`		删除某个 streamable HTTP 服务端的已保存 OAuth 凭据。
`remove`		删除已保存的 MCP server 定义。

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 server 的可执行文件及参数。需要放在 -- 之后。

OAuth 相关动作（login、logout）只适用于 streamable HTTP 服务端，而且服务端本身也必须支持 OAuth。

codex plugin marketplace

管理 Codex 可浏览和安装的插件市场来源。

子命令	类型 / 可选值	说明
`add`	[--ref REF] [--sparse PATH] [--json]	从 GitHub 简写、Git URL、SSH URL 或本地 marketplace 根目录安装插件市场。--sparse 只支持 Git 来源，并且可重复传入。
`list`	[--json]	显示 Codex 当前会考虑的插件市场，以及每个 marketplace 的根路径。
`upgrade`	[marketplace-name] [--json]	刷新一个已配置的 Git 插件市场；如果省略名称，则刷新所有已配置的 Git 插件市场。
`remove`	[--json]	移除一个已配置的插件市场。

codex plugin marketplace add 接受 owner/repo 或 owner/repo@ref 这类 GitHub 简写、HTTP 或 HTTPS Git URL、SSH Git URL，以及本地 marketplace 根目录。使用 --ref 可以固定 Git ref；对 Git-backed marketplace 仓库，可以重复传入 --sparse PATH 来使用 sparse checkout。

codex plugin marketplace list 会打印当前作用域内的 marketplace 名称和根路径，包括隐式发现的默认 marketplace 和已配置的 marketplace 快照。

codex plugin

从已配置的 marketplace 安装、列出和移除插件。

子命令	类型 / 可选值	说明
`add`	<plugin[@marketplace]> [--marketplace, -m NAME] [--json]	从已配置的 marketplace 安装插件。如果插件参数没有写 @marketplace，可用 --marketplace 或 -m 指定 marketplace。
`list`	[--marketplace, -m NAME] [--available --json] [--json]	列出已安装插件。使用 --json 时，输出包含 installed 和 available 数组；--available 会包含尚未安装的 marketplace 插件，并且要求同时使用 --json。
`remove`	<plugin[@marketplace]> [--marketplace, -m NAME] [--json]	从本地配置和缓存中移除已安装插件。使用 --json 可获得便于自动化处理的输出。
`marketplace`		管理已配置的 marketplace 来源。参见上面的 codex plugin marketplace。

codex plugin add --json 会打印 pluginId、 name、 marketplaceName、 version、 installedPath 和 authPolicy。 codex plugin list --json 会打印 installed 和 available 数组；条目包含 pluginId、 name、 marketplaceName、 version、 installed、 enabled、 source、 installPolicy、 authPolicy，可用时还会包含 marketplaceSource，其中记录已配置 marketplace 的来源类型和值。 codex plugin remove --json 会打印 pluginId、 name 和 marketplaceName。

codex mcp-server

通过 stdio 把 Codex 自身作为 MCP server 运行，以便其他工具接入。这个命令会继承全局配置覆盖项，并在下游客户端关闭连接时退出。

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

选项	类型 / 可选值	说明
`--permissions-profile`, `-P`	NAME	从当前激活配置栈中应用一个命名权限配置档案。
`--cd`, `-C`	DIR	用于配置档案解析和命令执行的工作目录。需要配合 --permissions-profile 使用。
`--include-managed-config`	boolean	解析显式权限配置档案时包含托管 requirements。需要配合 --permissions-profile 使用。
`--allow-unix-socket`	path	允许沙箱内命令绑定或连接位于该路径下的 Unix socket。可重复允许多个路径。
`--log-denials`	boolean	命令运行期间用 log stream 捕获 macOS sandbox deny 记录，并在退出后打印。
`--config`, `-c`	key=value	向沙箱运行注入配置覆盖项（可重复）。
`COMMAND...`	var-args	在 macOS Seatbelt 中执行的 shell 命令。-- 之后的内容都会原样转发。

Linux Landlock

选项	类型 / 可选值	说明
`--permissions-profile`, `-P`	NAME	从当前激活配置栈中应用一个命名权限配置档案。
`--cd`, `-C`	DIR	用于配置档案解析和命令执行的工作目录。需要配合 --permissions-profile 使用。
`--include-managed-config`	boolean	解析显式权限配置档案时包含托管 requirements。需要配合 --permissions-profile 使用。
`--config`, `-c`	key=value	在启动沙箱前应用配置覆盖项（可重复）。
`COMMAND...`	var-args	在 Landlock + seccomp 中执行的命令。可执行文件需放在 -- 之后。

Windows

选项	类型 / 可选值	说明
`--permissions-profile`, `-P`	NAME	从当前激活配置栈中应用一个命名权限配置档案。
`--cd`, `-C`	DIR	用于配置档案解析和命令执行的工作目录。需要配合 --permissions-profile 使用。
`--include-managed-config`	boolean	解析显式权限配置档案时包含托管 requirements。需要配合 --permissions-profile 使用。
`--config`, `-c`	key=value	在启动沙箱前应用配置覆盖项（可重复）。
`COMMAND...`	var-args	在原生 Windows sandbox 中执行的命令。可执行文件需放在 -- 之后。

codex update

当已安装版本支持 self-update 时，检查并应用 Codex CLI 更新。Debug build 会打印提示，说明应安装 release build。

选项组合与安全建议

对于可以保持在工作区内的无人值守本地工作，请使用 --sandbox workspace-write；除非已经处在专用 sandbox VM 中，否则避免使用 --dangerously-bypass-approvals-and-sandbox。
如果需要给 Codex 更多目录的写权限，优先使用 --add-dir，而不是直接切到 --sandbox danger-full-access。
在 CI 中把 --json 与 --output-last-message 组合使用，可以同时捕获机器可读进度和最终自然语言摘要。