跳到主要内容

本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/cli/features

Codex CLI 功能

Codex 终端客户端功能概览

Codex 支持聊天之外的工作流。使用本指南了解每种工作流能带来什么，以及何时使用它。

在交互模式下运行​

Codex 会启动为一个全屏终端 UI，它可以读取你的仓库、进行编辑，并在你们协作迭代时运行命令。当你想要一种对话式工作流，并且可以实时审查 Codex 的操作时，就使用它。

codex

你也可以在命令行中指定一个初始提示。

codex "Explain this codebase to me"

会话打开后，你可以：

  • 直接在 composer 中发送提示、代码片段或截图（参见图像输入）。
  • 查看 Codex 在进行更改前解释它的计划，并内联批准或拒绝步骤。
  • 在 TUI 中阅读带语法高亮的 markdown 代码块和 diff，然后使用 /theme 预览并保存偏好的主题。
  • 使用 /clear 清空终端并开始新的聊天，或按 Ctrl+L 仅清屏而不开始新对话。
  • 使用 /copy 或按 Ctrl+O 复制最近一次已完成的 Codex 输出。如果某一轮仍在运行，Codex 会复制最近一次已完成的输出，而不是进行中的文本。
  • 在 Codex 运行期间按 Tab，为下一轮排队后续文本、斜杠命令或 ! shell 命令。
  • 使用 Up/Down 在 composer 中浏览草稿历史；Codex 会恢复之前的草稿文本和图像占位符。
  • 按 Ctrl+R 在 composer 中搜索提示历史，然后按 Enter 接受匹配项或按 Esc 取消。
  • 完成后按 Ctrl+C 或使用 /exit 关闭交互会话。

恢复对话​

Codex 会将你的转录内容存储在本地，这样你就可以从上次中断的地方继续，而不必重复上下文。当你想用相同的仓库状态和指令重新打开早先的线程时，请使用 resume 子命令。

  • codex resume 会启动最近交互会话的选择器。高亮某次运行可查看其摘要，并按 Enter 重新打开它。
  • codex resume --all 会显示当前工作目录之外的会话，这样你可以重新打开任何本地运行。
  • codex resume --last 会跳过选择器，直接进入当前工作目录中你最近的会话（添加 --all 可忽略当前工作目录过滤器）。
  • codex resume <SESSION_ID> 用于指定某次运行。你可以从选择器、/status 或 ~/.codex/sessions/ 下的文件中复制该 ID。

非交互式自动化运行也可以恢复：

codex exec resume --last "Fix the race conditions you found"
codex exec resume 7f9f9a2e-1b3c-4c7a-9b0e-.... "Implement the plan"

每次恢复的运行都会保留原始转录、计划历史和审批记录，因此 Codex 可以利用先前的上下文，同时由你提供新指令。如果你需要在恢复前调整环境，可以使用 --cd 覆盖工作目录，或使用 --add-dir 添加额外根目录。

将 TUI 连接到远程 app server​

远程 TUI 模式允许你在一台机器上运行 Codex app server，并在另一台机器上使用 Codex 终端 UI。使用 WebSocket 监听器启动 app server：

codex app-server --listen ws://127.0.0.1:4500

然后将 TUI 连接到该端点：

codex --remote ws://127.0.0.1:4500

若要从另一台机器访问，请将 app server 绑定到可访问的接口，并在远程使用前配置 WebSocket 认证：

TOKEN_FILE="$HOME/.codex/app-server-token"
openssl rand -base64 32 > "$TOKEN_FILE"
chmod 600 "$TOKEN_FILE"
codex app-server --listen ws://0.0.0.0:4500 --ws-auth capability-token --ws-token-file "$TOKEN_FILE"

--remote 接受显式的 ws://host:port 和 wss://host:port 地址。普通 WebSocket 连接适用于 localhost 和 SSH 端口转发工作流。对于非本地客户端，请使用 WebSocket 认证，并将连接置于 TLS 之后。

Codex 支持以下 WebSocket 认证模式：

  • Capability token：使用 --ws-auth capability-token 启动服务器，并指定 --ws-token-file /absolute/path 或 --ws-token-sha256 HEX。
  • Signed bearer token：使用 --ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path 启动服务器，并可选添加 --ws-issuer、--ws-audience 和 --ws-max-clock-skew-seconds。

TUI 会在 WebSocket 握手期间将远程认证 token 作为 Authorization: Bearer 请求头发送。Codex 仅通过 wss:// URL 或回环 ws:// URL 接受远程认证 token。

export CODEX_REMOTE_TOKEN="$(cat "$TOKEN_FILE")"
codex --remote wss://remote-host:4500 --remote-auth-token-env CODEX_REMOTE_TOKEN

对于 Codex app 中的 SSH 远程项目，请参阅远程连接。对于托管的 remote-control 客户端，codex remote-control 会启动一个启用了 remote-control 支持的 app-server 进程。

模型与推理​

对于 Codex 中的大多数任务，推荐模型是 gpt-5.5。它是 OpenAI 最新的前沿模型，适用于复杂编码、计算机使用、知识工作和研究工作流，在规划、工具使用以及多步骤任务的执行完成度方面更强。对于额外追求速度的任务，ChatGPT Pro 订阅用户可在研究预览中使用 GPT-5.3-Codex-Spark 模型。

可使用 /model 命令在会话中途切换模型，或在启动 CLI 时指定模型。

codex --model gpt-5.5

进一步了解 Codex 中可用的模型。

功能标志​

Codex 包含一小组功能标志。使用 features 子命令查看可用项，并将更改持久化到你的配置中。

codex features list
codex features enable unified_exec
codex features disable shell_snapshot

codex features enable 和 codex features disable 会写入 ~/.codex/config.toml。如果你使用 --profile 启动 Codex，则 Codex 会将更改存储到该 profile 中，而不是根配置中。

Subagents​

使用 Codex subagent 工作流来并行处理更大的任务。关于设置、角色配置（config.toml 中的 [agents]）和示例，请参阅 Subagents。

只有当你明确要求时，Codex 才会生成 subagent。由于每个 subagent 都会执行自己的模型和工具工作，subagent 工作流比可比的单 agent 运行消耗更多 token。

图像输入​

附加截图或设计规范，以便 Codex 能结合你的提示读取图像细节。你可以将图像粘贴到交互式 composer 中，也可以在命令行中提供文件。

codex -i screenshot.png "Explain this error"
codex --image img1.png,img2.jpg "Summarize these diagrams"

Codex 接受常见格式，如 PNG 和 JPEG。对于两张或更多图像，请使用逗号分隔的文件名，并结合文本指令来补充上下文。

图像生成​

让 Codex 直接在 CLI 中生成或编辑图像。这非常适合图标、横幅、插图、sprite sheet 和占位图等资源。如果你希望 Codex 转换或扩展现有资源，请在提示中附加参考图像。

你可以使用自然语言提出请求，也可以通过在提示中包含 $imagegen 来显式调用图像生成 skill。

内置图像生成使用 gpt-image-2，会计入你的通用 Codex 使用限制，并且根据图像质量和尺寸，平均会比没有图像生成的类似轮次快 3-5 倍地使用包含配额。详情请参阅 Pricing。有关提示编写技巧和模型细节，请参阅图像生成指南。

对于更大批量的图像生成，请在环境变量中设置 OPENAI_API_KEY，并让 Codex 通过 API 生成图像，这样将适用 API 定价。

语法高亮与主题​

TUI 会对带围栏的 markdown 代码块和文件 diff 进行语法高亮，以便在审查和调试时更容易浏览代码。

使用 /theme 打开主题选择器、实时预览主题，并将你的选择保存到 ~/.codex/config.toml 中的 tui.theme。你也可以将自定义 .tmTheme 文件添加到 $CODEX_HOME/themes 下，并在选择器中选择它们。

运行本地代码审查​

在 CLI 中输入 /review 可打开 Codex 的审查预设。CLI 会启动一个专用 reviewer，它会读取你选择的 diff，并报告按优先级排序、可操作的发现，而不会触碰你的工作树。默认情况下它使用当前会话模型；如需覆盖，请在 config.toml 中设置 review_model。

  • 针对基线分支审查 允许你选择一个本地分支；Codex 会找到它相对于上游的 merge base，对你的工作做 diff，并在你打开 pull request 之前突出最大的风险。
  • 审查未提交的更改 会检查所有已暂存、未暂存或未跟踪的内容，以便你在提交前解决问题。
  • 审查某个提交 会列出最近的提交，并让 Codex 读取你所选 SHA 的精确变更集。
  • 自定义审查指令 接受你自己的措辞（例如，“Focus on accessibility regressions”），并使用该提示运行相同的 reviewer。

每次运行都会在对话记录中显示为独立的一轮，因此你可以随着代码演进重复运行审查并比较反馈。

Codex 内置了第一方 Web 搜索工具。对于 Codex CLI 中的本地任务，Codex 默认启用 Web 搜索，并从 Web 搜索缓存中提供结果。该缓存是由 OpenAI 维护的 Web 结果索引，因此缓存模式返回的是预先索引的结果，而不是抓取实时页面。这可以减少来自任意实时内容的提示注入暴露风险，但你仍然应该将 Web 结果视为不受信任的内容。如果你正在使用 --yolo 或其他完全访问沙箱设置，Web 搜索默认返回实时结果。要获取最新数据，可为单次运行传入 --search，或在配置基础中设置 web_search = "live"。你也可以设置 web_search = "disabled" 来关闭该工具。

每当 Codex 进行搜索时，你都会在对话记录或 codex exec --json 输出中看到 web_search 条目。

使用输入提示运行​

当你只需要一个快速答案时，可以用单条提示运行 Codex，并跳过交互式 UI。

codex "explain this codebase"

Codex 会读取工作目录、制定计划，并将响应流式返回到你的终端，然后退出。你可以将它与 --path 之类的标志配合使用，以定位特定目录，或使用 --model 预先调整行为。

Shell 自动补全​

通过为你的 shell 安装生成的补全脚本来加快日常使用：

codex completion bash
codex completion zsh
codex completion fish

在你的 shell 配置文件中运行补全脚本，以为新会话启用自动补全。例如，如果你使用 zsh，可以将以下内容添加到 ~/.zshrc 文件末尾：

# ~/.zshrc
eval "$(codex completion zsh)"

启动一个新会话，输入 codex，然后按 Tab 查看补全项。如果你看到 command not found: compdef 错误，请在 eval "$(codex completion zsh)" 这一行之前，将 autoload -Uz compinit && compinit 添加到你的 ~/.zshrc 文件中，然后重启 shell。

审批模式​

审批模式定义了 Codex 在无需停下来确认的情况下可以执行多少操作。随着你的接受程度变化，可在交互式会话中使用 /permissions 切换模式。

  • Auto（默认）允许 Codex 在工作目录内读取文件、编辑和运行命令。对于该范围之外的操作或使用网络，它仍会先询问。
  • Read-only 让 Codex 保持在咨询模式。它可以浏览文件，但在你批准计划之前不会进行更改或运行命令。
  • Full Access 授予 Codex 在你的整台机器上工作的能力，包括无需询问即可访问网络。请谨慎使用，并且仅在你信任该仓库和任务时使用。

Codex 始终会展示其操作的对话记录，因此你可以使用平常的 git 工作流来审查或回滚更改。

编写 Codex 脚本​

使用 exec 子命令自动化工作流，或将 Codex 接入你现有的脚本中。它会以非交互方式运行 Codex，并将最终计划和结果通过管道输出回 stdout。

codex exec "fix the CI failure"

将 exec 与 shell 脚本结合，可构建自定义工作流，例如自动更新变更日志、整理 issue，或在 PR 发布前执行编辑检查。

使用 Codex cloud​

codex cloud 命令让你无需离开终端即可分流和启动 Codex cloud 任务。在不带参数的情况下运行它，可以打开交互式选择器、浏览活动中或已完成的任务，并将更改应用到你的本地项目中。

你也可以直接从终端启动任务：

codex cloud exec --env ENV_ID "Summarize open bugs"

当你希望 Codex cloud 生成不止一个解决方案时，可添加 --attempts（1–4）来请求 best-of-N 运行。例如：codex cloud exec --env ENV_ID --attempts 3 "Summarize open bugs"。

环境 ID 来自你的 Codex cloud 配置——使用 codex cloud 并按 Ctrl+O 选择环境，或通过 Web 仪表板确认精确值。身份验证沿用你现有的 CLI 登录；如果提交失败，该命令会以非零状态退出，因此你可以将其接入脚本或 CI。

斜杠命令​

斜杠命令让你可以快速访问诸如 /review、/fork、/side 之类的专用工作流，或你自己可复用的提示。Codex 提供了一组精心整理的内置命令，你也可以为团队特定任务或个人快捷方式创建自定义命令。

请参阅斜杠命令指南，浏览内置命令目录、了解如何编写自定义命令，以及它们在磁盘上的存放位置。

提示编辑器​

当你在编写较长提示时，切换到完整编辑器然后再将结果发回编辑区，通常会更方便。

在提示输入框中，按 Ctrl+G 可打开由 VISUAL 环境变量定义的编辑器（如果未设置 VISUAL，则使用 EDITOR）。

Model Context Protocol (MCP)​

通过配置 Model Context Protocol 服务器，将 Codex 连接到更多工具。可在 ~/.codex/config.toml 中添加 STDIO 或流式 HTTP 服务器，或使用 codex mcp CLI 命令管理它们——Codex 会在会话开始时自动启动这些服务器，并将它们的工具与内置工具一起暴露出来。你甚至可以在需要将 Codex 用于另一个 agent 内部时，将 Codex 本身作为 MCP 服务器运行。

请参阅 Model Context Protocol，获取示例配置、支持的身份验证流程以及更详细的指南。

提示和快捷方式​

  • 在编辑区中输入 @，可对工作区根目录执行模糊文件搜索；按 Tab 或 Enter 可将高亮路径插入到你的消息中。
  • 当 Codex 正在运行时按 Enter，可将新指令注入当前这一轮；按 Tab 则可为下一轮排队后续输入。排队输入可以是普通提示、诸如 /review 之类的斜杠命令，或 ! shell 命令。Codex 会在运行时解析排队的斜杠命令。
  • 以 ! 作为行前缀可运行本地 shell 命令（例如 !ls）。Codex 会将输出视为用户提供的命令结果，并仍然应用你的审批和沙箱设置。
  • 当编辑区为空时，连按两次 Esc 可编辑你上一条用户消息。继续按 Esc 可在对话记录中进一步回退，然后按 Enter 可从该点创建分支。
  • 可通过 codex --cd 从任意目录启动 Codex，以设置工作根目录，而无需先运行 cd。当前路径会显示在 TUI 标题中。
  • 当你需要跨多个项目协调更改时，可使用 --add-dir 暴露更多可写根目录（例如 codex --cd apps/frontend --add-dir ../backend --add-dir ../shared）。
  • 启动 Codex 之前，请确保你的环境已经设置完成，这样它就不会花费 token 去探测需要激活什么。例如，预先 source 你的 Python 虚拟环境（或其他语言环境）、启动任何必需的守护进程，并导出你预计会使用的环境变量。