English
主导航

推荐
API 仪表板

Codex CLI 功能

Codex 终端客户端功能概述

Codex 支持聊天之外的多种工作流。请阅读本指南，了解各项功能的作用及适用场景。

在交互模式下运行

Codex 会启动一个全屏终端 UI，它可以读取您的代码仓库、进行编辑，并在您与其共同迭代时运行命令。当您希望拥有一个可以实时查看 Codex 操作的对话式工作流时，请使用此模式。

codex

您也可以在命令行上指定初始提示词。

codex "Explain this codebase to me"

会话打开后，您可以：

  • 将提示词、代码片段或屏幕截图（参见 图像输入）直接发送到输入框。
  • 观察 Codex 在进行更改前解释其计划，并内联批准或拒绝相关步骤。
  • 在 TUI 中阅读带有语法高亮的 Markdown 代码块和差异比较，然后使用 /theme 来预览并保存您偏好的主题。
  • 使用 /clear 清除终端并开始新的聊天，或按下 Ctrl+L 清除屏幕而不开始新的对话。
  • 使用 /copy or press Ctrl+O 复制 Codex 最近完成的输出。如果某个回合仍在运行，Codex 将复制最近一次已完成的输出，而不是进行中的文本。
  • 在 Codex 运行期间按下 Tab 可将后续文本、斜杠命令或 ! Shell 命令排队等待下一回合执行。
  • 使用 Up/Down；Codex 会恢复之前的草稿文本和图片占位符。
  • 在 Codex 运行期间按下 Ctrl+R 在输入框中浏览草稿历史记录，在输入框中搜索提示词历史记录，然后按下 Enter 接受匹配项，或按下 Esc to cancel.
  • 在 Codex 运行期间按下 Ctrl+C or use /exit 在完成后关闭交互式会话。

恢复对话

Codex 会在本地存储您的记录，以便您可以接着之前的进度继续，而无需重复提供上下文。当您希望以相同的代码仓库状态和指令重新打开之前的线程时，请使用 resume 子命令。

  • codex resume 会启动一个近期交互会话的选择器。高亮显示某次运行以查看其摘要，然后按下 Enter to reopen it.
  • codex resume --all 会显示当前工作目录之外的会话，因此您可以重新打开任何本地运行记录。
  • codex resume --last 会跳过选择器，直接进入当前工作目录中您最近的会话（添加 --all 以忽略当前工作目录筛选器)。
  • codex resume <SESSION_ID> 针对特定的运行。你可以从选择器中复制 ID， /status，或以下文件： ~/.codex/sessions/.

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

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 连接到远程应用服务器

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

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

然后将 TUI 连接到该端点：

codex --remote ws://127.0.0.1:4500

若要从另一台机器访问，请将应用服务器绑定到可访问的接口，并在远程使用前配置 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 and wss://host:port 地址。普通的 WebSocket 连接适用于 localhost 和 SSH 端口转发工作流。对于非本地客户端，请使用 WebSocket 认证并将连接置于 TLS 之后。

Codex 支持以下 WebSocket 认证模式：

  • 能力令牌：使用以下命令启动服务器 --ws-auth capability-token and either --ws-token-file /absolute/path or --ws-token-sha256 HEX.
  • 签名不记名令牌：使用以下命令启动服务器 --ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path，加上可选的 --ws-issuer, --ws-audience，且 --ws-max-clock-skew-seconds.

TUI 会在 WebSocket 握手期间将远程身份验证令牌作为 Authorization: Bearer <token> 请求头发送。Codex 仅接受通过 wss:// URL 或环回地址传输的远程身份验证令牌 ws:// URLs.

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

对于 Codex 应用中的 SSH 远程项目，请使用 远程连接。对于托管的远程控制客户端， codex 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 <feature> and codex features disable <feature> 写入 ~/.codex/config.toml。如果你使用以下方式启动 Codex： --profile profile-name, Codex writes to $CODEX_HOME/profile-name.config.toml instead.

子智能体

使用 Codex 子代理工作流并行处理大型任务。有关设置、角色配置（[agents] in config.toml）及示例，请参见 子智能体.

Codex 仅在您明确要求时才会生成子代理。由于每个子代理会独立执行模型和工具调用，子代理工作流消耗的 token 比同类的单代理运行更多。

图像输入

附加屏幕截图或设计规范，以便 Codex 在处理您的提示时能读取图像细节。您可以将图像粘贴到交互式编辑器中，或在命令行中提供文件。

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

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

图像生成

让 Codex 在 CLI 中直接生成或编辑图像。这非常适用于图标、横幅、插图、精灵图和占位图等资源。如果您希望 Codex 转换或扩展现有资产，请在提示中附上一张参考图像。

您可以使用自然语言提问，或者通过包含以下内容来显式调用图像生成技能： $imagegen in your prompt.

内置图像生成使用 gpt-image-2,会计入你的常规 Codex 使用额度,并且根据图像质量和尺寸,平均比不含图像生成的类似轮次快 3-5 倍地消耗包含额度。详情请参阅 定价。有关提示技巧和模型详情,请参阅 图像生成指南.

对于大批量的图像生成，请在您的环境变量中设置 OPENAI_API_KEY 并要求 Codex 通过 API 生成图像，以便适用 API 定价。

语法高亮与主题

TUI 会对带有标记的 Markdown 代码块和文件差异进行语法高亮，以便在代码审查和调试时更易于浏览。

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

运行本地代码审查

类型 /review 在 CLI 中运行以打开 Codex 的审查预设。CLI 会启动一个专用的审查器，读取您选定的差异并报告按优先级排序的、可操作的发现，且不会触及您的工作区。默认情况下，它使用当前会话的模型；请设置 review_model in config.toml to override.

  • 对照基础分支进行审查 允许您选择一个本地分支；Codex 会找到其上游的合并基点，对您的工作进行差异比对，并在您发起 Pull Request 前突出显示最大的风险。
  • 审查未提交的更改 会检查所有已暂存、未暂存或未跟踪的内容，以便您在提交前解决问题。
  • 审查提交 会列出最近的提交，并让 Codex 读取您所选 SHA 的确切变更集。
  • 自定义审查指令 接受您的自定义措辞（例如，“重点关注可访问性回归问题”），并使用该提示运行相同的审查器。

每次运行都会作为独立的一轮出现在记录中，因此您可以在代码演进时重新运行审查并比较反馈。

网络搜索

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

每当 Codex 查找内容时，您会在记录中看到 web_search 条目，或者在 codex exec --json 输出中看到它们。

使用输入提示运行

当您只需要快速获取答案时，请使用单个提示运行 Codex，并跳过交互式 UI。

codex "explain this codebase"

Codex 将读取工作目录，制定计划，并在退出前将响应流式传输回您的终端。您可以结合 --path 等标志指定目标目录，或使用 --model 预先调整其行为。

Shell 自动补全

通过安装为您的 Shell 生成的自动补全脚本来加快日常使用：

codex completion bash
codex completion zsh
codex completion fish

在您的 Shell 配置文件中运行自动补全脚本，以便为新会话设置自动补全。例如，如果您使用 zsh，你可以将以下内容添加到你的 ~/.zshrc file:

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

启动一个新会话，输入 codex的末尾，然后按 Tab 以查看自动补全内容。如果出现 command not found: compdef 错误，请在 autoload -Uz compinit && compinit to your ~/.zshrc 行之前将其添加到您的 eval "$(codex completion zsh)" 文件中，然后重启您的 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 脚本结合以构建自定义工作流，例如自动更新变更日志、整理议题，或在 PR 发布前执行编辑审查。

使用 Codex 云

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

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

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

添加 --attempts (1–4) 以请求 best-of-N 运行，当你希望 Codex 云端生成多个解决方案时。例如， codex cloud exec --env ENV_ID --attempts 3 "Summarize open bugs".

环境 ID 来自你的 Codex 云端配置——使用 codex cloud and press Ctrl+O 来选择环境，或使用 Web 控制台确认确切的值。身份验证沿用了你现有的 CLI 登录状态，如果提交失败，命令将以非零状态退出，因此你可以将其接入脚本或 CI。

斜杠命令

斜杠命令让你能快速访问专门的工作流，例如 /review, /fork, /side，或者使用你自己的可复用提示。Codex 附带了一组精选的内置提示，你也可以为特定团队的任务或个人快捷操作创建自定义提示。

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

提示词编辑器

在起草较长的提示词时，切换到完整的编辑器然后将结果发送回编辑器可能会更容易。

在提示词输入框中，按 Ctrl+G 以打开由 VISUAL 环境变量定义的编辑器（如果未设置 EDITOR if VISUAL )未被设置）。

模型上下文协议 (MCP)

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

查看 模型上下文协议 以获取示例配置、支持的身份验证流程以及更详细的指南。

技巧与快捷方式

  • 类型 @ 在编辑器中打开工作区根目录的模糊文件搜索；按下 Tab or Enter 以将高亮显示的路径插入到你的消息中。
  • 在 Codex 运行期间按下 Enter 在 Codex 运行期间以向当前回合注入新指令，或按下 Tab 来为下一回合排队输入。排队的输入可以是常规提示，斜杠命令例如 /review, or a ! shell 命令。Codex 在运行时会解析排队的斜杠命令。
  • 在行首添加 ! 来运行本地 shell 命令（例如， !ls）。Codex 会将输出视为用户提供的命令结果，并仍会应用你的批准和沙箱设置。
  • 轻触 Esc 两次可以在编辑器为空时编辑你之前的用户消息。继续按 Esc 可在对话记录中进一步向前回溯，然后按 Enter 从该点分叉。
  • 使用以下命令从任意目录启动 Codex： codex --cd <path> 以设置工作根目录，而无需先运行 cd 。活动路径显示在 TUI 标题栏中。
  • 使用以下命令暴露更多可写根目录： --add-dir （例如， codex --cd apps/frontend --add-dir ../backend --add-dir ../shared)，当您需要协调多个项目的更改时。
  • 在启动 Codex 之前，请确保您的环境已配置妥当，以免它消耗 token 来探测需要激活哪些内容。例如，提前加载您的 Python 虚拟环境（或其他语言环境），启动所有必需的守护进程，并导出您期望使用的环境变量。