如何阅读本页
本页汇总了所有已文档化的 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）。可重复。 |
--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 或 Windows 上启动 Codex 桌面 App。macOS 可打开工作区路径；Windows 会打印要打开的路径。 |
| codex app-server | 实验性 | 通过 stdio、WebSocket 或 Unix socket 启动本地 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 debug models | 实验性 | 打印 Codex 看到的原始 model catalog，也可只查看当前二进制内置的 catalog。 |
| codex exec | 稳定 | 以非交互模式运行 Codex。可输出 stdout 或 JSONL，也可恢复历史会话。别名：codex e。 |
| codex execpolicy | 实验性 | 评估 execpolicy 规则文件，查看某条命令会被允许、要求批准还是被阻止。 |
| codex features | 稳定 | 列出功能开关，并把启用 / 禁用状态持久写入 config.toml。 |
| 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 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（交互模式）
直接运行 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，并将其指向通过 codex app-server --listen ws://IP:PORT 启动的服务端。如果服务端要求通过 WebSocket 使用 bearer token 认证，可额外传入 --remote-auth-token-env <ENV_VAR>。
codex app-server
在本地启动 Codex app-server。这个命令主要用于开发和调试，未来可能会变更。
| 选项 | 类型 / 可选值 | 默认值 | 说明 |
|---|---|---|---|
--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-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 传输方式。--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 Cloud 任务生成的 diff 应用到本地仓库。你必须已经认证，而且对该任务具有访问权限。
| 参数 | 类型 / 可选值 | 说明 |
|---|---|---|
TASK_ID |
string | 要应用其 diff 的 Codex Cloud 任务 ID。 |
Codex 会打印被打补丁的文件；如果 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 | 已弃用的兼容 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 | 选择 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 或 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 <name> |
-- <command...> | --url <value> |
使用 stdio 启动命令或 streamable HTTP URL 注册一个服务端。对 stdio 传输还支持 --env KEY=VALUE。 |
get <name> |
--json |
查看某个服务端的配置。--json 会打印原始配置项。 |
| list | --json |
列出已配置的 MCP server。加 --json 可输出机器可读结果。 |
login <name> |
--scopes scope1,scope2 |
为某个 streamable HTTP 服务端发起 OAuth 登录（仅对支持 OAuth 的服务端有效）。 |
logout <name> |
删除某个 streamable HTTP 服务端的已保存 OAuth 凭据。 | |
remove <name> |
删除已保存的 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 <source> |
[--ref REF] [--sparse PATH] |
从 GitHub 简写、Git URL、SSH URL 或本地 marketplace 根目录安装插件市场。--sparse 只支持 Git 来源，并且可重复传入。 |
upgrade [marketplace-name] |
刷新一个已配置的 Git 插件市场；如果省略名称，则刷新所有已配置的 Git 插件市场。 | |
remove <marketplace-name> |
移除一个已配置的插件市场。 |
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 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 |
NAME | 从当前激活配置栈中应用一个命名 permissions profile。 |
--cd, -C |
DIR | 用于 profile 解析和命令执行的工作目录。需要配合 --permissions-profile 使用。 |
--include-managed-config |
boolean | 解析显式 permissions profile 时包含托管 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 |
NAME | 从当前激活配置栈中应用一个命名 permissions profile。 |
--cd, -C |
DIR | 用于 profile 解析和命令执行的工作目录。需要配合 --permissions-profile 使用。 |
--include-managed-config |
boolean | 解析显式 permissions profile 时包含托管 requirements。需要配合 --permissions-profile 使用。 |
--config, -c |
key=value |
在启动沙箱前应用配置覆盖项（可重复）。 |
COMMAND... |
var-args |
在 Landlock + seccomp 中执行的命令。可执行文件需放在 -- 之后。 |
Windows
| 选项 | 类型 / 可选值 | 说明 |
|---|---|---|
--permissions-profile |
NAME | 从当前激活配置栈中应用一个命名 permissions profile。 |
--cd, -C |
DIR | 用于 profile 解析和命令执行的工作目录。需要配合 --permissions-profile 使用。 |
--include-managed-config |
boolean | 解析显式 permissions profile 时包含托管 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组合使用，可以同时捕获机器可读进度和最终自然语言摘要。