OpenAI Codex 中文教程
联系我 goolvyouyou@gmail.com

Codex CLI 功能

Codex 终端客户端的功能概览

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

以交互模式运行

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

codex

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

codex "Explain this codebase to me"

会话打开后，你可以：

  • 直接在输入框中发送提示词、代码片段或截图。参见图片输入。
  • 观看 Codex 在改动前先解释自己的计划，并在过程中内联批准或拒绝步骤。
  • 在 TUI 中阅读带语法高亮的 Markdown 代码块和 diff，并用 /theme 预览和保存自己偏好的主题。
  • 使用 /clear 清空终端并开启新聊天，或按 Ctrl+L 只清屏而不开始新对话。
  • 使用 /copy 或按 Ctrl+O 复制最近一条已完成的 Codex 输出。如果当前 turn 仍在运行，它会复制最近一次完成的输出，而不是正在生成中的文本。
  • 当 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 连接到远程 app server

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

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

然后把 TUI 连接到这个端点：

codex --remote ws://127.0.0.1:4500

如果你需要从另一台机器访问，请把 app server 绑定到可达地址，并在真正远程使用前配置 WebSocket auth：

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 auth，并把连接放到 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> header 发送远程认证 token。Codex 只会在 wss:// URL 或 loopback 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 远程项目，请使用远程连接。对于托管远程控制客户端，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 <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 等常见格式。对于两张或更多图片，使用逗号分隔文件名，并配合文字说明补充上下文。

图片生成

你可以要求 Codex 直接在 CLI 中生成或编辑图片。这适合图标、banner、插图、sprite sheet 和占位图等素材。如果你希望 Codex 转换或扩展现有素材，请在提示词中附上参考图。

你可以用自然语言提出请求，也可以在提示词中包含 $imagegen 来显式调用图片生成技能。

内置图片生成使用 gpt-image-2，计入你的通用 Codex 使用限制；根据图片质量和尺寸不同，平均会以不含图片生成的类似 turn 的 3-5 倍的速度消耗套餐包含额度。详情见定价。提示词技巧和模型细节见图片生成指南。

如果要大批量生成图片，请在环境变量中设置 OPENAI_API_KEY，并要求 Codex 通过 API 生成图片，这样会按 API 价格计费。

语法高亮与主题

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 对应的精确改动集。
  • 自定义评审指令：接受你自己的表述，例如“重点关注可访问性回归”，并用同一套评审器执行。

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

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

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

提示词编辑器

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

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

模型上下文协议（MCP）

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

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

提示与快捷方式

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