主导航

推荐
API 控制台

Codex CLI 功能

Codex 终端客户端功能概览

Codex 支持超越聊天范畴的工作流。使用本指南了解每种工作流的作用及其适用场景。

交互模式下运行

Codex 会启动一个全屏终端界面 (TUI)，能够读取您的代码库、进行编辑并在您共同迭代时运行命令。当您需要通过对话式工作流实时查看 Codex 的操作时，请使用此模式。

codex

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

codex "Explain this codebase to me"

会话开启后，您可以：

  • 将提示词、代码片段或截图（参见图像输入）直接发送到编辑器中。
  • 在 Codex 做出更改前观察其计划，并内联批准或拒绝操作步骤。
  • 在 TUI 中阅读带有语法高亮的 Markdown 代码块和差异对比（diff），并使用 /theme 预览和保存您偏好的主题。
  • 使用 /clear 清除终端并开始新对话，或按 Ctrl+L 清除屏幕而不开启新对话。
  • 使用 /copy 或按 Ctrl+O 复制 Codex 最近完成的输出。如果某轮操作仍在进行中，Codex 将复制最近一次完成的输出，而不是正在进行的文本。
  • 在 Codex 运行时按 Tab 键，可为下一轮排队后续文本、斜杠命令或 ! Shell 命令。
  • 使用 Up/Down 键在编辑器中导航草稿历史记录；Codex 会恢复之前的草稿文本和图像占位符。
  • 按 Ctrl+R 在编辑器中搜索提示词历史，按 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 连接到远程应用服务器

远程 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 和 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 握手期间将远程身份验证令牌作为 Authorization: Bearer <token> 头发送。Codex 仅接受通过 wss:// URL 或回环 ws:// URL 传输的远程身份验证令牌。

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 会在启用远程控制支持的情况下启动应用服务器进程。

模型与推理

对于 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> 和 codex features disable <feature> 会写入 ~/.codex/config.toml。如果您使用 --profile 启动 Codex，更改将存储在该配置文件中，而不是根配置中。

子 Agent

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

Codex 仅在您明确要求时才会生成子代理。由于每个子代理都会执行自己的模型和工具工作，因此子代理工作流比类似的单代理运行消耗更多的 Token。

图像输入

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

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

Codex 接受 PNG 和 JPEG 等常见格式。对于两个或多个图像，请使用逗号分隔文件名，并将其与文字说明结合以增加上下文。

图像生成

要求 Codex 直接在 CLI 中生成或编辑图像。这对于图标、横幅、插图、精灵表（sprite sheets）和占位符素材非常有效。如果您希望 Codex 转换或扩展现有素材，请在提示词中附上参考图像。

您可以用自然语言提问，也可以通过在提示词中包含 $imagegen 来显式调用图像生成技能。

内置图像生成功能使用 gpt-image-2，会计入您的通用 Codex 使用限制，且根据图像质量和大小，其消耗速度平均比没有图像生成的同类任务快 3-5 倍。有关详情，请参阅定价。有关提示技巧和模型详细信息，请参阅图像生成指南。

如需批量生成更多图像，请在环境变量中设置 OPENAI_API_KEY，并要求 Codex 通过 API 生成图像，这样将适用 API 定价。

语法高亮与主题

TUI 会对 Markdown 代码块和文件差异进行语法高亮显示，以便在审查和调试时更容易查阅代码。

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

运行本地代码审查

在 CLI 中输入 /review 以打开 Codex 的审查预设。CLI 会启动一个专用审查器，它会读取您选择的差异并报告优先级高、可操作的发现，而无需触碰您的工作树。默认情况下它使用当前会话模型；在 config.toml 中设置 review_model 可覆盖此设置。

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

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

网络搜索

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 即可根据您的舒适度切换模式。

  • 自动（默认）：允许 Codex 在工作目录内读取文件、编辑和运行命令。但在触及范围之外或使用网络前仍会询问。
  • 只读：使 Codex 保持咨询模式。它可以浏览文件，但在您批准计划前不会进行任何更改或运行命令。
  • 完全访问：授予 Codex 在您的机器上工作的能力，包括网络访问，且无需询问。请谨慎使用，仅在您信任该代码库和任务时使用。

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

脚本化 Codex

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

codex exec "fix the CI failure"

将 exec 与 Shell 脚本结合使用可构建自定义工作流，例如自动更新更新日志、分类问题或在 PR 发布前强制执行编辑检查。

使用 Codex Cloud

codex cloud 命令允许您无需离开终端即可分类和启动 Codex Cloud 任务。不带参数运行该命令可打开交互式选择器，浏览活动或已完成的任务，并将更改应用于本地项目。

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

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

添加 --attempts (1–4) 以请求多次运行，当您希望 Codex Cloud 生成多个解决方案时。例如：codex cloud exec --env ENV_ID --attempts 3 "总结已开启的 Bug"。

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

斜杠命令

斜杠命令可让您快速访问专门的工作流，如 /review、/fork、/side 或您自己的可重用提示词。Codex 附带一组精选的内置命令，您也可以为团队特定任务或个人快捷方式创建自定义命令。

请参阅斜杠命令指南以浏览内置命令目录，学习如何创作自定义命令，并了解它们存储在磁盘的位置。

提示词编辑器

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

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

模型上下文协议 (MCP)

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

请参阅模型上下文协议了解示例配置、支持的身份验证流程以及更详细的指南。

提示与快捷键

  • 在编辑器中键入 @ 可打开工作区根目录的模糊文件搜索；按 Tab 或 Enter 将高亮显示的文件路径填入您的消息中。
  • Codex 运行时按 Enter 可将新指令注入当前轮次，或按 Tab 为下一轮次排队后续输入。排队的输入可以是普通提示词、/review 等斜杠命令或 ! Shell 命令。Codex 会在运行时解析排队的斜杠命令。
  • 在行首加 ! 可运行本地 Shell 命令（例如 !ls）。Codex 将输出视为用户提供的命令结果，并仍会应用您的批准和沙箱设置。
  • 在编辑器为空时连按两次 Esc 以编辑上一条用户消息。继续按 Esc 可在对话记录中进一步回溯，然后按 Enter 从该点开始分叉。
  • 使用 codex --cd <path> 从任何目录启动 Codex，无需先运行 cd 即可设置工作根目录。当前路径会显示在 TUI 标题中。
  • 当您需要协调多个项目时，使用 --add-dir 公开更多可写根目录（例如 codex --cd apps/frontend --add-dir ../backend --add-dir ../shared）。
  • 确保在启动 Codex 之前环境已设置好，这样它就不会消耗 Token 来探测该激活什么。例如，提前 source 您的 Python 虚拟环境（或其他语言环境），启动所需的守护进程，并导出您预计会用到的环境变量。
© . This website operates independently and is not affiliated with or endorsed by OpenAI, Inc. All brand names, logos, and trademarks are the property of their respective owners.