OpenAI Codex 中文文档（4.14更新）
联系我 ↗
官方文档 ↗

Codex CLI 功能

Codex 终端客户端的功能概览

Codex 支持的不止是聊天式工作流。使用本指南了解每项能力能解锁什么，以及它适合在什么场景中使用。

以交互模式运行

Codex 会以全屏终端 UI 启动。你可以与它一起迭代，它能读取仓库、修改代码并运行命令。只要你希望在对话式工作流中实时审视 Codex 的动作，就适合使用这种方式。

codex

你也可以在命令行中直接指定一条初始提示词。

codex "Explain this codebase to me"

会话打开后，你可以：

  • 直接在输入框中发送提示词、代码片段或截图。参见图片输入。
  • 观看 Codex 在改动前先解释自己的计划，并在过程中内联批准或拒绝步骤。
  • 在 TUI 中阅读带语法高亮的 Markdown 代码块和 diff，并用 /theme 预览和保存自己偏好的主题。
  • 使用 /clear 清空终端并开启新聊天，或按 Ctrl+L 只清屏而不开始新对话。
  • 使用 /copy 复制最近一条已完成的 Codex 输出。如果当前回合仍在运行，它会复制最近一次完成的输出，而不是正在生成中的文本。
  • 用 Up/Down 浏览输入框中的草稿历史；Codex 会恢复之前的草稿文本和图片占位。
  • 完成后按 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。当代码、凭据或执行环境位于远程主机，但你仍希望保留本地交互式 TUI 体验时，这种方式尤其有用。

先在负责持有工作区并执行命令的机器上启动 app server：

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

然后从运行 TUI 的机器上连接过去：

codex --remote ws://127.0.0.1:4500

如果你需要从另一台机器访问，可以把 app server 绑定到可达地址，例如：

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

--remote 只接受显式的 ws://host:port 或 wss://host:port 地址。对于明文 WebSocket，优先使用本地主机地址或 SSH 端口转发；如果监听器暴露到了本机之外，请先完成认证配置，并把带认证的非本地连接放到 TLS 后面。

Codex 为远程 TUI 连接支持以下 WebSocket 认证模式：

  • No WebSocket auth（无 WebSocket 认证）：最适合仅监听本地主机地址，或通过 SSH 端口转发访问的场景。Codex 可以在无认证的情况下启动非本地监听器，但会记录警告，并在启动横幅中提醒你在真正远程使用前配置认证。
  • Capability token：在 app-server 主机上把共享 token 保存到文件中，使用 --ws-auth capability-token --ws-token-file /abs/path/to/token 启动服务；然后在 TUI 主机上把同一个 token 放进环境变量，再通过 --remote-auth-token-env <ENV_VAR> 传入。
  • Signed bearer token（已签名 bearer token）：在 app-server 主机上把 HMAC 共享密钥保存到文件中，使用 --ws-auth signed-bearer-token --ws-shared-secret-file /abs/path/to/secret 启动服务；然后让 TUI 通过 --remote-auth-token-env <ENV_VAR> 发送一个已签名的 JWT bearer token。共享密钥至少需要 32 字节。签名 token 使用 HS256，并且必须包含 exp；如果 token 声明或服务端选项中提供了 nbf、iss、aud，Codex 也会一并校验。

如果你要在 app-server 主机上创建 capability token，可以生成一个只有当前用户可读的随机 token 文件：

TOKEN_FILE="$HOME/.codex/codex-app-server-token"
install -d -m 700 "$(dirname "$TOKEN_FILE")"
openssl rand -base64 32 > "$TOKEN_FILE"
chmod 600 "$TOKEN_FILE"

请像对待密码一样保护这个 token 文件；一旦泄露，就应立即重新生成。

然后用这个 token 文件启动 app server。例如，把 capability token 放在 TLS 代理之后使用：

# Remote host
TOKEN_FILE="$HOME/.codex/codex-app-server-token"
codex app-server \
  --listen ws://0.0.0.0:4500 \
  --ws-auth capability-token \
  --ws-token-file "$TOKEN_FILE"

# TUI host
export CODEX_REMOTE_AUTH_TOKEN="$(ssh devbox 'cat ~/.codex/codex-app-server-token')"
codex --remote wss://codex-devbox.example.com:4500 \
  --remote-auth-token-env CODEX_REMOTE_AUTH_TOKEN

TUI 会在 WebSocket 握手期间以 Authorization: Bearer <token> 的形式发送远程认证 token。Codex 只会在 wss:// URL，或 host 为 localhost、127.0.0.1、::1 的 ws:// URL 上发送这些 token；因此，只要客户端需要在网络上传递认证 token，就应把非本地远程监听器放到 TLS 之后。

模型与推理

对于 Codex 中的大多数任务，推荐模型是 gpt-5.4。它把 gpt-5.3-codex 行业领先的编码能力带到了 OpenAI 的旗舰前沿模型中，结合了前沿级编码表现、更强的推理能力、原生计算机使用能力，以及更广泛的专业工作流支持。对于追求额外速度的任务，ChatGPT Pro 订阅者还可以使用研究预览版 GPT-5.3-Codex-Spark。

你可以在会话中通过 /model 切换模型，也可以在启动 CLI 时直接指定模型。

codex --model gpt-5.4

了解 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，它会把更改写进该配置档案，而不是根配置。

子智能体

使用 Codex 的子智能体工作流可以把更大的任务并行拆分。关于设置、角色配置（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 等常见格式。对于两张或更多图片，使用逗号分隔文件名，并配合文字说明补充上下文。

语法高亮与主题

TUI 会对带围栏的 Markdown 代码块和文件 diff 做语法高亮，让代码在评审和调试时更容易浏览。

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

运行本地代码评审

在 CLI 中输入 /review，即可打开 Codex 的评审预设。CLI 会启动一个专用评审智能体，读取你选择的 diff，并在不改动工作树的前提下，输出带优先级、可执行的问题列表。默认情况下它使用当前会话模型；如果要覆盖，可在 config.toml 中设置 review_model。

  • 对比某个基线分支进行评审：让你选择一个本地分支。Codex 会找到它与上游分支的 merge base，读取 diff，并在你打开 pull request 前指出最大的风险。
  • 评审未提交改动：检查所有已暂存、未暂存和未跟踪的变更，帮助你在提交前发现问题。
  • 评审某个提交：列出最近的提交，让 Codex 读取你选定 SHA 对应的精确改动集。
  • 自定义评审指令：接受你自己的表述，例如“重点关注可访问性回归”，并用同一套评审器执行。

每次运行都会作为对话记录中独立的一轮出现，因此你可以随着代码演进反复运行评审，并比较反馈差异。

Web 搜索

Codex 自带第一方 Web 搜索工具。对于 Codex CLI 中的本地任务，默认会启用 Web 搜索，并优先从 Web 搜索缓存提供结果。这个缓存是 OpenAI 维护的网页结果索引，因此 cached 模式返回的是预索引结果，而不是实时抓取页面。这能降低来自任意实时内容的提示词注入风险，但你仍应把 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 补全

安装补全脚本，可以加快日常使用：

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，然后重启 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，或在 pull request 发出前执行编辑性检查。

使用 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，或你自己定义的可复用提示词。Codex 自带一组精选内建命令，你也可以为团队任务或个人快捷方式创建自定义命令。

参见斜杠命令文档，了解内建命令目录、如何编写自定义命令，以及这些命令在磁盘上的存放位置。

提示词编辑器

如果你在编写一条较长的提示词，切到完整编辑器往往会更方便，编辑完成后再把结果送回输入框。

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

模型上下文协议（MCP）

通过配置 Model Context Protocol 服务端，把 Codex 连接到更多工具。你可以在 ~/.codex/config.toml 中添加 STDIO 或流式 HTTP 服务端，也可以使用 codex mcp CLI 命令来管理它们。Codex 会在会话启动时自动拉起这些服务端，并把它们的工具与内建工具一起暴露出来。必要时，你甚至可以把 Codex 本身作为一个 MCP 服务端，提供给其他智能体使用。

示例配置、支持的认证流以及更完整的说明，参见 MCP。

提示与快捷方式

  • 在输入框中键入 @，可以对工作区根目录执行模糊文件搜索；按 Tab 或 Enter 即可把高亮路径插入消息。
  • 当 Codex 正在运行时，按 Enter 会把新指令注入当前回合；按 Tab 则会把后续提示词排队到下一回合执行。
  • 在一行前加上 ! 可以直接运行本地 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 去探测需要激活什么。例如，先激活 Python 虚拟环境或其他语言环境、启动必需的守护进程，并提前导出你希望使用的环境变量。

来源：https://developers.openai.com/codex/cli/features