Skip to content

Codex CLI 终端客户端的选项和标志参考,包含所有命令和全局标志的详细说明。

Codex 终端客户端的选项和标志

本页面收录了所有文档化的 Codex CLI 命令和标志。你可以使用交互式表格按键名或描述进行搜索。每个章节都会标明该选项是稳定版还是实验版,并标注有风险的组合。

CLI 的大部分默认值继承自 ~/.codex/config.toml。你在命令行传递的任何 -c key=value 覆盖值都会在该次调用中优先。更多信息请参见配置基础

类型 / 值详情
--add-dirpath授予额外的目录写入权限,与主工作区并列。可重复使用以添加多个路径。
--ask-for-approval, -auntrusted | on-request | never控制 Codex 在运行命令前何时暂停等待人工审批。on-failure 已弃用;交互式运行时优先使用 on-request,非交互式运行时优先使用 never
--cd, -Cpath在智能体开始处理请求之前设置其工作目录。
--config, -ckey=value覆盖配置值。值会尽可能解析为 JSON;否则使用字面字符串。
--dangerously-bypass-approvals-and-sandbox, --yoloboolean不经审批或沙箱直接运行所有命令。仅在外部加固的环境中使用。
--disablefeature强制禁用某个功能标志(等价于 -c features.<name>=false)。可重复使用。
--enablefeature强制启用某个功能标志(等价于 -c features.<name>=true)。可重复使用。
--image, -ipath[,path…]将一个或多个图片文件附加到初始提示。使用逗号分隔多个路径,或重复使用标志。
--model, -mstring覆盖配置中设置的模型(例如 gpt-5.4)。
--no-alt-screenboolean禁用 TUI 的交替屏幕模式(覆盖本次运行的 tui.alternate_screen)。
--ossboolean使用本地开源模型提供商(等价于 -c model_provider="oss")。会验证 Ollama 是否正在运行。
--profile, -pstring~/.codex/config.toml 中加载的配置文件名。
--remotews://host:port | wss://host:port将交互式 TUI 连接到远程 app-server WebSocket 端点。支持 codexcodex resumecodex fork;其他子命令不支持远程模式。
--remote-auth-token-envENV_VAR从此环境变量读取 bearer token,并在使用 --remote 连接时发送。需要 --remote;token 仅通过 wss:// URL 或主机为 localhost、127.0.0.1 或 ::1 的 ws:// URL 发送。
--sandbox, -sread-only | workspace-write | danger-full-access为模型生成的 shell 命令选择沙箱策略。
--searchboolean启用实时网络搜索(将 web_search 设为 "live" 而非默认的 "cached")。
PROMPTstring可选的文本指令,用于启动会话。省略则启动 TUI 而不预填消息。

这些选项适用于基础 codex 命令,并会传递到每个子命令,除非下文另有说明。运行子命令时,请将全局标志放在其后(例如 codex exec --oss ...),以便 Codex 正确应用它们。

成熟度列使用功能成熟度标签,如实验版(Experimental)、测试版(Beta)和稳定版(Stable)。有关如何理解这些标签,请参见功能成熟度

成熟度详情
codex稳定版启动终端 UI。接受上述全局标志,外加可选的提示或图片附件。
codex app稳定版在 macOS 或 Windows 上启动 Codex 桌面应用。在 macOS 上,Codex 可以打开工作区路径;在 Windows 上,Codex 会打印要打开的路径。
codex app-server实验版通过 stdio、WebSocket 或 Unix socket 启动 Codex 应用服务器,用于本地开发或调试。
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实验版通过内置测试客户端发送单条 V2 消息来调试 app-server。
codex debug models实验版打印 Codex 看到的原始模型目录,包括仅检查内置目录的选项。
codex exec稳定版非交互式运行 Codex。别名:codex e。将结果流式输出到 stdout 或 JSONL,并可选择恢复之前的会话。
codex execpolicy实验版评估 execpolicy 规则文件,查看命令是允许、提示还是被阻止。
codex features稳定版列出功能标志并在 config.toml 中持久启用或禁用。
codex fork稳定版将之前的交互式会话分叉到新线程,保留原始对话记录。
codex login稳定版使用 ChatGPT OAuth、设备认证、API 密钥或通过 stdin 传入的访问令牌认证 Codex。
codex logout稳定版移除存储的认证凭据。
codex mcp实验版管理 Model Context Protocol 服务器(列出、添加、移除、认证)。
codex mcp-server实验版将 Codex 本身作为 MCP 服务器通过 stdio 运行。适用于另一个智能体消费 Codex 的场景。
codex plugin marketplace实验版从 Git 或本地源添加、升级或移除插件市场。
codex remote-control实验版确保本地 app-server 守护进程正在运行并启用了远程控制支持。
codex resume稳定版按 ID 继续之前的交互式会话,或恢复最近的对话。
codex sandbox实验版在 Codex 提供的 macOS、Linux 或 Windows 沙箱内运行任意命令。
codex update稳定版检查并应用 Codex CLI 更新(当已安装版本支持自更新时)。

不带子命令运行 codex 会启动交互式终端 UI(TUI)。智能体接受上述全局标志以及图片附件。网络搜索默认为缓存模式;使用 --search 切换到实时浏览。对于低摩擦的本地工作,使用 --sandbox workspace-write --ask-for-approval on-request

使用 --remote ws://host:port--remote wss://host:port 将 TUI 连接到通过 codex app-server --listen ws://IP:PORT 启动的应用服务器。当服务器需要 bearer token 进行 WebSocket 认证时,添加 --remote-auth-token-env <ENV_VAR>

在本地启动 Codex 应用服务器。这主要用于开发和调试,可能随时变更。

类型 / 值详情
--analytics-default-enabledboolean为第一方 app-server 客户端默认启用分析,除非用户在配置中主动关闭。
--listenstdio:// | ws://IP:PORT | unix:// | unix://PATH | off传输监听器 URL。使用 stdio:// 进行 JSONL 通信,ws://IP:PORT 作为 TCP WebSocket 端点,unix:// 使用默认 Unix socket,unix://PATH 使用自定义 Unix socket,或 off 禁用本地传输。
--ws-audiencestring签名 bearer token 的期望 aud 声明。需要 --ws-auth signed-bearer-token
--ws-authcapability-token | signed-bearer-tokenapp-server WebSocket 客户端的认证模式。如果省略,WebSocket 认证将被禁用;非本地监听器会在启动时发出警告。
--ws-issuerstring签名 bearer token 的期望 iss 声明。需要 --ws-auth signed-bearer-token
--ws-max-clock-skew-secondsnumber验证签名 bearer token 的 expnbf 声明时的时钟偏差容限。需要 --ws-auth signed-bearer-token
--ws-shared-secret-fileabsolute path包含用于验证签名 JWT bearer token 的 HMAC 共享密钥的文件。配合 --ws-auth signed-bearer-token 必须提供。
--ws-token-fileabsolute path包含共享 capability token 的文件。配合 --ws-auth capability-token 必须提供。

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 以包含受限字段和方法。

确保 app-server 守护进程正在运行并启用了远程控制支持。托管的远程控制客户端和 SSH 远程工作流使用此命令;它不是 codex app-server --listen 的替代品(后者用于构建本地协议客户端)。

从终端启动 Codex Desktop(macOS 或 Windows)。在 macOS 上,Codex 可以打开特定的工作区路径;在 Windows 上,Codex 会打印要打开的路径。

类型 / 值详情
--download-urlurl高级覆盖:用于安装的 Codex 桌面安装程序 URL。
PATHpathCodex Desktop 的工作区路径。在 macOS 上,Codex 会打开此路径;在 Windows 上,Codex 会打印该路径。

codex app 会打开已安装的 Codex Desktop 应用,如果应用缺失则启动安装程序。在 macOS 上,Codex 会打开提供的工作区路径;在 Windows 上,它会在安装后打印要打开的路径。

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

类型 / 值详情
USER_MESSAGEstring通过内置 V2 测试客户端流程发送到 app-server 的消息文本。

此调试流程以 experimentalApi: true 初始化,启动线程,发送轮次,并流式传输服务器通知。用它来在本地复现和检查 app-server 协议行为。

以 JSON 格式打印 Codex 看到的原始模型目录。

类型 / 值详情
--bundledboolean跳过刷新,仅打印当前 Codex 二进制文件附带的模型目录。

当你想仅检查当前二进制文件附带的目录而不从远程模型端点刷新时,使用 --bundled

将 Codex Cloud 任务的最新 diff 应用到你的本地仓库。你必须已认证并有权限访问该任务。

类型 / 值详情
TASK_IDstring要应用其 diff 的 Codex Cloud 任务标识符。

Codex 会打印被修补的文件,如果 git apply 失败(例如由于冲突),则返回非零退出码。

从终端与 Codex Cloud 任务交互。默认命令打开交互式选择器;codex cloud exec 直接提交任务,codex cloud list 返回最近的任务用于脚本或快速检查。

类型 / 值详情
--attempts1-4Codex Cloud 应运行的助手尝试次数(best-of-N)。
--envENV_ID目标 Codex Cloud 环境标识符(必需)。使用 codex cloud 列出选项。
QUERYstring任务提示。如果省略,Codex 会交互式地提示输入详细信息。

认证使用与主 CLI 相同的凭据。如果任务提交失败,Codex 返回非零退出码。

列出最近的云任务,支持可选的过滤和分页。

类型 / 值详情
--cursorstring上一次请求返回的分页游标。
--envENV_ID按环境标识符过滤任务。
--jsonboolean输出机器可读的 JSON 而非纯文本。
--limit1-20返回的最大任务数。

纯文本输出打印任务 URL 后跟状态详情。使用 --json 用于自动化。JSON 负载包含一个 tasks 数组和一个可选的 cursor 值。每个任务包含 idurltitlestatusupdated_atenvironment_idenvironment_labelsummaryis_reviewattempt_total

生成 shell 补全脚本并将输出重定向到适当的位置,例如 codex completion zsh > "${fpath[1]}/_codex"

类型 / 值详情
SHELLbash | zsh | fish | power-shell | elvish要生成补全的目标 shell。输出打印到 stdout。

管理存储在 ~/.codex/config.toml 中的功能标志。enabledisable 命令会持久保存更改,使其在未来的会话中生效。当你使用 --profile 启动时,Codex 会写入该配置文件而非根配置。

类型 / 值详情
Disable 子命令codex features disable <feature>在 config.toml 中持久禁用某个功能标志。提供 --profile 时遵循活动配置文件。
Enable 子命令codex features enable <feature>在 config.toml 中持久启用某个功能标志。提供 --profile 时遵循活动配置文件。
List 子命令codex features list显示已知的功能标志、其成熟度阶段和有效状态。

使用 codex exec(或简写 codex e)用于脚本或 CI 风格的运行,这些运行应在没有人工交互的情况下完成。

类型 / 值详情
--cd, -Cpath在执行任务之前设置工作区根目录。
--coloralways | never | auto控制 stdout 中的 ANSI 颜色。
--dangerously-bypass-approvals-and-sandbox, --yoloboolean绕过审批提示和沙箱。危险——仅在隔离的运行器内使用。
--ephemeralboolean不将会话 rollout 文件持久保存到磁盘。
--full-autoboolean已弃用的兼容性标志。优先使用 --sandbox workspace-write;使用此标志时 Codex 会打印警告。
--ignore-rulesboolean本次运行不加载用户或项目的 execpolicy .rules 文件。
--ignore-user-configboolean不加载 $CODEX_HOME/config.toml。认证仍使用 CODEX_HOME
--image, -ipath[,path…]将图片附加到第一条消息。可重复使用;支持逗号分隔的列表。
--json, --experimental-jsonboolean打印以换行分隔的 JSON 事件,而非格式化文本。
--model, -mstring覆盖本次运行的已配置模型。
--ossboolean使用本地开源提供商(需要正在运行的 Ollama 实例)。
--output-last-message, -opath将助手的最终消息写入文件。适用于下游脚本。
--output-schemapath描述期望最终响应结构的 JSON Schema 文件。Codex 会据此验证工具输出。
--profile, -pstring选择 config.toml 中定义的配置文件名。
--sandbox, -sread-only | workspace-write | danger-full-access模型生成命令的沙箱策略。默认使用配置中的值。
--skip-git-repo-checkboolean允许在 Git 仓库外运行(适用于一次性目录)。
-c, --configkey=value非交互式运行的内联配置覆盖(可重复使用)。
PROMPTstring | -(读取 stdin)任务的初始指令。使用 - 从 stdin 管道传入提示。
Resume 子命令codex exec resume [SESSION_ID]按 ID 恢复 exec 会话,或添加 --last 从当前工作目录继续最近的会话。添加 --all 以考虑所有目录中的会话。接受可选的后续提示。

Codex 默认写入格式化输出。添加 --json 以接收以换行分隔的 JSON 事件(每个状态变更一个事件)。可选的 resume 子命令允许你继续非交互式任务。使用 --last 选择当前工作目录中最近的会话,或添加 --all 跨所有会话搜索:

类型 / 值详情
--allboolean在选择最近会话时包含当前工作目录之外的会话。
--image, -ipath[,path…]将一个或多个图片附加到后续提示。使用逗号分隔多个路径,或重复使用标志。
--lastboolean从当前工作目录恢复最近的对话。
PROMPTstring | -(读取 stdin)可选的后续指令,在恢复后立即发送。
SESSION_IDuuid恢复指定的会话。省略并使用 --last 来继续最近的会话。

在保存之前检查 execpolicy 规则文件。codex execpolicy check 接受一个或多个 --rules 标志(例如 ~/.codex/rules 下的文件),并输出 JSON,显示最严格的决策和任何匹配的规则。添加 --pretty 格式化输出。execpolicy 命令目前处于预览阶段。

类型 / 值详情
--prettyboolean美化输出的 JSON 结果。
--rules, -rpath(可重复)要评估的 execpolicy 规则文件路径。提供多个标志以组合跨文件的规则。
COMMAND...var-args要针对指定策略检查的命令。

使用 ChatGPT 账户、API 密钥或访问令牌认证 CLI。不带任何标志时,Codex 会打开浏览器进行 ChatGPT OAuth 流程。

类型 / 值详情
--device-authboolean使用 OAuth 设备码流程,而非启动浏览器窗口。
--with-access-tokenboolean从 stdin 读取访问令牌(例如 printenv CODEX_ACCESS_TOKEN | codex login --with-access-token)。
--with-api-keyboolean从 stdin 读取 API 密钥(例如 printenv OPENAI_API_KEY | codex login --with-api-key)。
status 子命令codex login status打印活动认证模式,登录成功时返回退出码 0。

codex login status 在存在凭据时返回退出码 0,这在自动化脚本中很有用。

移除 API 密钥和 ChatGPT 认证的已保存凭据。此命令没有标志。

管理存储在 ~/.codex/config.toml 中的 Model Context Protocol 服务器条目。

类型 / 值详情
add <name>-- <command...> | --url <value>使用 stdio 启动器命令或 streamable HTTP URL 注册服务器。支持 --env KEY=VALUE 用于 stdio 传输。
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-varENV_VAR环境变量,其值在连接到 streamable HTTP 服务器时作为 bearer token 发送。
--env KEY=VALUE可重复启动 stdio 服务器时应用的环境变量赋值。
--urlhttps://…注册 streamable HTTP 服务器而非 stdio。与 COMMAND... 互斥。
COMMAND...stdio 传输启动 MCP 服务器的可执行文件及参数。在 -- 之后提供。

OAuth 操作(loginlogout)仅适用于 streamable HTTP 服务器(且仅当服务器支持 OAuth 时)。

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

类型 / 值详情
add <source>[--ref REF] [--sparse PATH]从 GitHub 简写、Git URL、SSH URL 或本地市场根目录安装插件市场。--sparse 仅支持 Git 源,可重复使用。
remove <marketplace-name>移除已配置的插件市场。
upgrade [marketplace-name]刷新一个已配置的 Git 市场,或在不提供名称时刷新所有已配置的 Git 市场。

codex plugin marketplace add 接受 GitHub 简写,如 owner/repoowner/repo@ref、HTTP 或 HTTPS Git URL、SSH Git URL 以及本地市场根目录。使用 --ref 固定 Git 引用,重复 --sparse PATH 对 Git 支持的市场仓库使用稀疏检出。

将 Codex 作为 MCP 服务器通过 stdio 运行,以便其他工具可以连接。此命令继承全局配置覆盖,并在下游客户端关闭连接时退出。

按 ID 继续交互式会话,或恢复最近的对话。codex resume--last 范围限定为当前工作目录,除非你传入 --all。它接受与 codex 相同的全局标志,包括模型和沙箱覆盖。

类型 / 值详情
--allboolean在选择最近会话时包含当前工作目录之外的会话。
--lastboolean跳过选择器,从当前工作目录恢复最近的对话。
SESSION_IDuuid恢复指定的会话。省略并使用 --last 来继续最近的会话。

将之前的交互式会话分叉到新线程。默认情况下,codex fork 打开会话选择器;添加 --last 以直接分叉最近的会话。

类型 / 值详情
--allboolean在选择器中显示当前工作目录之外的会话。
--lastboolean跳过选择器,自动分叉最近的对话。
SESSION_IDuuid分叉指定的会话。省略并使用 --last 来分叉最近的会话。

使用沙箱助手在与 Codex 内部相同的策略下运行命令。

macOS Seatbelt

类型 / 值详情
--allow-unix-socketpath允许沙箱命令绑定或连接到以此路径为根的 Unix socket。可重复使用以允许多个路径。
--cd, -CDIR用于配置文件解析和命令执行的工作目录。需要 --permissions-profile
--config, -ckey=value将配置覆盖传递到沙箱运行中(可重复使用)。
--include-managed-configboolean在解析显式权限配置文件时包含托管要求。需要 --permissions-profile
--log-denialsboolean在命令运行时使用 log stream 捕获 macOS 沙箱拒绝记录,并在退出后打印。
--permissions-profileNAME从活动配置栈应用命名权限配置文件。
COMMAND...var-args在 macOS Seatbelt 下执行的 shell 命令。-- 之后的所有内容都会被转发。

Linux Landlock

类型 / 值详情
--cd, -CDIR用于配置文件解析和命令执行的工作目录。需要 --permissions-profile
--config, -ckey=value在启动沙箱之前应用的配置覆盖(可重复使用)。
--include-managed-configboolean在解析显式权限配置文件时包含托管要求。需要 --permissions-profile
--permissions-profileNAME从活动配置栈应用命名权限配置文件。
COMMAND...var-args在 Landlock + seccomp 下执行的命令。在 -- 之后提供可执行文件。

Windows

类型 / 值详情
--cd, -CDIR用于配置文件解析和命令执行的工作目录。需要 --permissions-profile
--config, -ckey=value在启动沙箱之前应用的配置覆盖(可重复使用)。
--include-managed-configboolean在解析显式权限配置文件时包含托管要求。需要 --permissions-profile
--permissions-profileNAME从活动配置栈应用命名权限配置文件。
COMMAND...var-args在原生 Windows 沙箱下执行的命令。在 -- 之后提供可执行文件。

检查并应用 Codex CLI 更新(当已安装版本支持自更新时)。调试构建版本会打印消息,提示你安装发布版本。

  • 使用 --sandbox workspace-write 进行可以保持在工作区范围内的无人值守本地工作,除非你处于专用的沙箱虚拟机中,否则避免使用 --dangerously-bypass-approvals-and-sandbox
  • 当你需要授予 Codex 对更多目录的写入权限时,优先使用 --add-dir 而非强制使用 --sandbox danger-full-access
  • 在 CI 中将 --json--output-last-message 配合使用,以捕获机器可读的进度和最终的自然语言摘要。
  • Codex CLI 概述:安装、升级和快速提示。
  • 配置基础:持久化模型和提供商等默认值。
  • 高级配置:配置文件、提供商、沙箱调优和集成。
  • AGENTS.md:Codex 智能体能力和最佳实践的概念概述。
-
0:000:00