掌握 CLI 功能

Codex CLI 不只支持聊天。它还支持恢复会话、远程 TUI、子 Agent、图片输入、图片生成、本地 review、web search、非交互脚本和 c

Codex CLI 不只支持聊天。它还支持恢复会话、远程 TUI、子 Agent、图片输入、图片生成、本地 review、web search、非交互脚本和 cloud tasks。

本篇按功能解释：每个能力解决什么问题，什么时候该用。

Running in interactive mode

直接运行：

codex

Codex 会进入 full-screen terminal UI（全屏终端界面）。在这个界面里，它可以读取 repository、修改文件，并运行命令。适合你希望和 Codex 对话式迭代，并实时 review 它动作的场景。

你也可以从命令行带上 initial prompt（初始提示词）：

codex "Explain this codebase to me"

session 打开后，你可以：

在 composer（输入区）里直接发送 prompts、code snippets（代码片段）或 screenshots（截图）。截图见 image inputs。
在 Codex 修改前查看它的 plan，并 inline approve 或 reject steps。
在 TUI 中阅读带 syntax highlighting（语法高亮）的 Markdown code blocks 和 diffs，然后用 /theme 预览并保存喜欢的主题。
用 /clear 清空 terminal 并开始 fresh chat；或按 Ctrl+L 只清屏，不开始新 conversation。
用 /copy 或 Ctrl+O 复制最新完成的 Codex 输出。如果某一轮仍在运行，Codex 会复制最近已完成的输出，而不是进行中的文本。
Codex 正在运行时按 Tab，把 follow-up text、slash commands 或 ! shell commands 排队到下一轮。
在 composer 里用 Up / Down 浏览 draft history，Codex 会恢复之前的草稿文本和已附加图片。
按 Ctrl+R 从 composer 搜索 prompt history，再按 Enter 接受匹配，或按 Esc 取消。
完成后按 Ctrl+C，或使用 /exit 关闭 interactive session。

Resuming conversations

Codex 会把 transcripts（对话记录）保存在本地，所以你可以从上次中断的位置继续，而不用重复上下文。

当你希望用同一个 repository state（仓库状态）和 instructions 重新打开 earlier thread（旧线程）时，使用 resume subcommand：

codex resume

常用方式：

codex resume：打开 recent interactive sessions 的 picker。选中一个 run 可以看到 summary，按 Enter 重新打开。
codex resume --all：显示当前 working directory 外的 sessions，可以恢复任意本地 run。
codex resume --last：跳过 picker，直接回到当前 working directory 的最近 session。加 --all 可以忽略当前目录过滤。
codex resume <SESSION_ID>：恢复指定 run。Session ID 可以从 picker、/status 或 ~/.codex/sessions/ 下的文件中复制。

Non-interactive automation runs 也可以恢复：

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

每个 resumed run 都会保留原始 transcript、plan history 和 approvals。Codex 可以使用之前上下文，同时你补充新的 instructions。

如果恢复前需要调整环境，可以用 --cd 覆盖 working directory，或用 --add-dir 添加额外 roots。

Connect the TUI to a remote app server

Remote TUI mode 允许你在一台机器上运行 Codex app server，在另一台机器上使用 Codex terminal UI。

这个模式适合 code、credentials 或 execution environment 在远端主机上，但你想使用本地 interactive TUI 体验的场景。

先在拥有 workspace 并负责运行命令的机器上启动 app server：

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

再在运行 TUI 的机器上连接：

codex --remote ws://127.0.0.1:4500

如果要从另一台机器访问，把 app server 绑定到可访问 interface，例如：

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

--remote 只接受显式 ws://host:port 和 wss://host:port 地址。普通 WebSocket 连接建议优先使用 localhost 地址或 SSH port forwarding。

如果把 listener 暴露到 localhost 之外，真实远程使用前必须配置 authentication，并把 authenticated non-local connections 放在 TLS 后面。

Codex 支持三种 remote TUI WebSocket authentication 模式：

No WebSocket auth：适合 localhost listeners 或 SSH port-forwarded connections。Codex 可以在没有 auth 的情况下启动 non-local listeners，但会记录 warning，并在 startup banner 中提醒你真实远程使用前配置 auth。
Capability token：在 app-server host 上把 shared token 存入文件，用 --ws-auth capability-token --ws-token-file /abs/path/to/token 启动 server。TUI host 上把同一个 token 放进 environment variable，并传入 --remote-auth-token-env <ENV_VAR>。
Signed bearer token：在 app-server host 上把 HMAC shared secret 存入文件，用 --ws-auth signed-bearer-token --ws-shared-secret-file /abs/path/to/secret 启动 server。TUI 通过 --remote-auth-token-env <ENV_VAR> 发送 signed JWT bearer token。shared secret 至少 32 bytes。Signed tokens 使用 HS256，必须包含 exp；如果存在 nbf、iss、aud claims 或 server options，Codex 也会验证它们。

在 app-server host 上创建 capability 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 file 当密码处理。如果泄露，立即重新生成。

使用 capability token 并放在 TLS proxy 后面的完整示例：

# 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 handshake（握手）时把 remote auth token 作为 Authorization: Bearer <token> 发送。

Codex 只会在 wss:// URL，或 host 为 localhost、127.0.0.1、::1 的 ws:// URL 上发送这些 tokens。因此，如果 client 需要通过网络认证 non-local remote listener，必须把它放在 TLS 后面。

Models and reasoning

多数 Codex 任务优先使用 gpt-5.5，前提是它在你的账号中可用。它是 OpenAI 最新 frontier model，适合复杂 coding、computer use、knowledge work 和 research workflows，并且在 planning、tool use、多步骤任务 follow-through 方面更强。

如果 gpt-5.5 还不可用，继续使用 gpt-5.4。

如果你需要极快任务，ChatGPT Pro 用户可以使用 research preview 阶段的 GPT-5.3-Codex-Spark。

在 session 中用 /model 切换模型，或启动 CLI 时指定：

codex --model gpt-5.5

模型说明见：

https://developers.openai.com/codex/models

功能开关

Codex 包含少量 feature flags。使用 features subcommand 查看可用功能，并把变更持久化到配置中：

codex features list
codex features enable unified_exec
codex features disable shell_snapshot

codex features enable <feature> 和 codex features disable <feature> 会写入 ~/.codex/config.toml。

如果启动 Codex 时使用 --profile，Codex 会把变更写入该 profile，而不是 root configuration。

Subagents

Codex subagent workflows 用于并行化更大的任务。配置、role configuration（config.toml 中的 [agents]）和示例见：

https://developers.openai.com/codex/subagents

Codex 只会在你明确要求时 spawn subagents。

因为每个 subagent 都会进行自己的 model 和 tool work，subagent workflows 会比类似的 single-agent runs 消耗更多 tokens。

Image inputs

你可以附加 screenshots 或 design specs，让 Codex 在 prompt 旁边读取图片细节。

在 interactive composer 中可以粘贴图片；命令行里也可以提供文件：

codex -i screenshot.png "Explain this error"

codex --image img1.png,img2.jpg "Summarize these diagrams"

Codex 接受 PNG、JPEG 等常见格式。两张或更多图片用 comma-separated filenames（逗号分隔文件名），也可以把图片和文字说明组合起来补充 context。

图片生成

你可以让 Codex 在 CLI 中直接生成或编辑图片。

适合生成 icons、banners、illustrations、sprite sheets 和可直接使用的真实 UI assets。

如果你希望 Codex transform 或 extend 现有素材，把 reference image 随 prompt 附上。

你可以用自然语言提出需求，也可以在 prompt 中加入 $imagegen 显式调用 image generation skill。

内置图片生成使用 gpt-image-2，计入 general Codex usage limits，并且平均比不生成图片的类似轮次更快消耗 included limits，约 3-5x，具体取决于 image quality 和 size。

用量说明：

https://developers.openai.com/codex/pricing#image-generation-usage-limits

Prompting 技巧和模型细节：

https://developers.openai.com/api/docs/guides/image-generation

如果要大批量生成图片，在 environment variables 中设置 OPENAI_API_KEY，然后让 Codex 通过 API 生成图片，这样按 API pricing 计费。

Syntax highlighting and themes

TUI 会对 fenced markdown code blocks 和 file diffs 做 syntax highlighting，方便 review 和 debug 时快速扫代码。

使用 /theme 打开 theme picker，可以实时预览主题，并把选择保存到 ~/.codex/config.toml 的 tui.theme。

你也可以把自定义 .tmTheme 文件放在 $CODEX_HOME/themes 下，然后在 picker 中选择。

Running local code review

在 CLI 中输入 /review 可以打开 Codex 的 review presets。

CLI 会启动 dedicated reviewer，读取你选择的 diff，并报告 prioritized、actionable findings。它不会修改你的 working tree。

默认使用当前 session model；如果要覆盖，在 config.toml 中设置 review_model。

可选 review 类型：

Review against a base branch：选择一个本地 branch；Codex 找到它与 upstream 的 merge base，diff 你的工作，并在打开 PR 前指出最大风险。
Review uncommitted changes：检查 staged、not staged 和 untracked 的所有内容，方便 commit 前修问题。
Review a commit：列出 recent commits，让 Codex 读取你选择 SHA 的精确 change set。
Custom review instructions：接受自定义说明，例如 Focus on accessibility regressions，并用同一个 reviewer 执行。

每次 review 会作为独立 turn 出现在 transcript 中，所以你可以随着代码变化重复运行 review，并比较反馈。

Web search

Codex 内置 first-party web search tool。

对于 Codex CLI 中的 local tasks，Codex 默认启用 web search，并从 web search cache 返回结果。cache 是 OpenAI 维护的 web results index，所以 cached mode 返回的是预索引结果，不是实时抓取页面。

这会减少 arbitrary live content 带来的 prompt injection 暴露面，但你仍然应该把 web results 当作 untrusted 内容。

如果你使用 --yolo 或其他 full access sandbox setting，web search 默认使用 live results：

https://developers.openai.com/codex/agent-approvals-security

如果要获取最新数据，可以给单次运行加 --search，或在 Config basics 里设置：

web_search = "live"

也可以关闭：

web_search = "disabled"

配置基础：

https://developers.openai.com/codex/config-basic

当 Codex 查询网页时，你会在 transcript 或 codex exec --json 输出中看到 web_search items。

Running with an input prompt

如果只需要快速回答，可以给 Codex 一个单次 prompt，不进入 interactive UI：

codex "explain this codebase"

Codex 会读取 working directory，拟定 plan，并把 response stream 回 terminal 后退出。

你可以搭配 --path 指定目录，或搭配 --model 预先调好行为。

Shell completions

安装 shell completion scripts 可以提升日常使用速度：

codex completion bash
codex completion zsh
codex completion fish

把 completion script 放进 shell configuration file。

例如使用 zsh 时，把下面内容加到 ~/.zshrc 末尾：

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

开启新 session，输入 codex 后按 Tab，就能看到 completions。

如果遇到 command not found: compdef，在 ~/.zshrc 里把下面这行加到 eval "$(codex completion zsh)" 前面，然后重启 shell：

autoload -Uz compinit && compinit

Approval modes

Approval modes 决定 Codex 在不停止确认的情况下能做多少事。Interactive session 中可以用 /permissions 切换。

Auto（默认）：允许 Codex 在 working directory 内读取文件、编辑和运行命令。触碰范围之外内容或使用 network 前仍会询问。
Read-only：让 Codex 保持 consultative mode（咨询模式）。它可以浏览文件，但不会修改或运行命令，除非你批准 plan。
Full Access：允许 Codex 跨你的机器工作，包括 network access，且不询问。只在你信任 repository 和 task 时谨慎使用。

Codex 始终展示 actions transcript，你可以用常规 git workflow review 或 rollback changes。

Scripting Codex

用 exec subcommand 可以把 Codex 接进脚本或已有自动化流程。它以 non-interactive（非交互）方式运行，把最终 plan 和 results 输出到 stdout。

codex exec "fix the CI failure"

你可以把 exec 和 shell scripting 组合，用于自动更新 changelog、整理 issues，或在 PR 前执行 editorial checks。

Working with Codex cloud

codex cloud 命令让你不离开 terminal，也能 triage 和启动 Codex cloud tasks：

https://developers.openai.com/codex/cloud

不带参数运行时，它会打开 interactive picker，让你浏览 active 或 finished tasks，并把 changes 应用到本地项目。

也可以直接从 terminal 启动任务：

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

添加 --attempts 可以请求 best-of-N runs，取值 1-4。例如：

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

Environment IDs 来自 Codex cloud configuration。用 codex cloud 并按 Ctrl+O 选择 environment，或在 web dashboard 确认准确值。

Authentication 复用现有 CLI login。如果提交失败，该命令会以 non-zero 退出，适合接进 scripts 或 CI。

斜杠命令

Slash commands 提供 /review、/fork、/side 等 specialized workflows，也可以承载你自己的 reusable prompts。

Codex 自带一组 built-ins，你也可以创建团队专属或个人 shortcut。

Slash commands 指南：

https://developers.openai.com/codex/guides/slash-commands

Prompt editor

写长 prompt 时，切到 full editor 更方便。

在 prompt input 中按 Ctrl+G，Codex 会打开 VISUAL environment variable 指定的 editor；如果没有设置 VISUAL，则使用 EDITOR。

Model Context Protocol (MCP)

Model Context Protocol servers 可以把 Codex 连接到更多工具。

你可以在 ~/.codex/config.toml 中添加 STDIO 或 streaming HTTP servers，也可以用 codex mcp CLI commands 管理。

Codex 会在 session 启动时自动启动这些 servers，并把它们的 tools 和 built-ins 一起暴露。

当另一个 Agent 需要消费 Codex 时，你甚至可以把 Codex 本身作为 MCP server 运行。

MCP 配置示例、auth flows 和详细说明：

https://developers.openai.com/codex/mcp

Tips and shortcuts

在 composer 中输入 @，会打开 workspace root 上的 fuzzy file search。按 Tab 或 Enter 把高亮路径放进 message。
Codex 正在运行时，按 Enter 可以向当前 turn 注入新 instructions；按 Tab 可以把 follow-up input 排队到下一 turn。Queued input 可以是普通 prompt、/review 这类 slash command，或 ! shell command。Codex 会在执行时解析 queued slash commands。
在一行前加 ! 可以运行 local shell command，例如 !ls。Codex 会把输出当作用户提供的 command result，同时仍然应用 approval 和 sandbox settings。
当 composer 为空时，连续按两次 Esc 可以编辑上一条用户消息。继续按 Esc 可以沿 transcript 回退；按 Enter 会从该点 fork。
可以从任意目录运行 codex --cd <path>，不需要先 cd。active path 会显示在 TUI header 中。
如果要跨多个项目协调改动，用 --add-dir 暴露更多 writable roots，例如：

codex --cd apps/frontend --add-dir ../backend --add-dir ../shared

启动 Codex 前，确保 environment 已经准备好，避免 Codex 花 tokens 探测要激活什么。例如先 source Python virtual environment 或其他 language environments，启动所需 daemons，并提前 export 任务需要的 environment variables。

On this page