高级用法

高级用法
非交互式 / CI 模式
- 恢复非交互会话
跟踪 / 详细日志
Model Context Protocol (MCP)
将 Codex 作为 MCP Server 使用
- Codex MCP Server 快速开始
- 尝试运行

非交互式 / CI 模式

在流水线中无头运行 Codex。示例 GitHub Action 步骤：

- name: Update changelog via Codex
  run: |
    npm install -g @openai/codex
    codex login --api-key "${{ secrets.OPENAI_KEY }}"
    codex exec --full-auto "update CHANGELOG for next release"

恢复非交互会话

你可以恢复之前的无头运行，以继续相同的对话上下文并追加到相同的 rollout 文件。

交互式 TUI 等价命令：

codex resume             # 选择器
codex resume --last      # 最近一次
codex resume <SESSION_ID>

兼容性：

最新源码构建包含 codex exec resume（下面有示例）。
当前已发布的 CLI 可能还没有。如果 codex exec --help 中没有 resume，请使用下一小节的替代方法。

# 恢复最近一次的会话并使用新的 prompt 运行（源码构建）
codex exec "ship a release draft changelog" resume --last
# 或者通过 stdin 传入 prompt（源码构建）
# 注意：省略末尾的 '-' 以避免被解析为 SESSION_ID
echo "ship a release draft changelog" | codex exec resume --last
# 或者通过 id (UUID) 恢复特定会话（源码构建）
codex exec resume 7f9f9a2e-1b3c-4c7a-9b0e-123456789abc "continue the task"

注意事项：

使用 --last 时，Codex 会选择最新的已记录会话；如果没有，则表现为新建。
恢复会话时会将新的事件追加到现有的会话文件，并保持相同的 conversation id。

跟踪 / 详细日志

因为 Codex 是用 Rust 编写的，它遵循 RUST_LOG 环境变量来配置日志行为。

TUI 默认使用 RUST_LOG=codex_core=info,codex_tui=info，日志写入到 ~/.codex/log/codex-tui.log，因此你可以在单独的终端中运行以下命令实时查看日志：

tail -F ~/.codex/log/codex-tui.log

相比之下，非交互模式（codex exec）默认使用 RUST_LOG=error，日志消息会直接打印在命令行，不需要单独监控文件。

更多配置选项请参见 Rust 文档中关于 RUST_LOG 的说明。

Model Context Protocol (MCP)

Codex CLI 可以通过在 ~/.codex/config.toml 中定义 mcp_servers 来配置使用 MCP 服务器。它的设计是参考 Claude 和 Cursor 如何在各自的 JSON 配置文件中定义 mcpServers，不过 Codex 使用的是 TOML 格式而不是 JSON，例如：

# 重要：顶层键是 `mcp_servers` 而不是 `mcpServers`。
[mcp_servers.server-name]
command = "npx"
args = ["-y", "mcp-server"]
env = { "API_KEY" = "value" }

将 Codex 作为 MCP Server 使用

Codex CLI 也可以通过 codex mcp 作为 MCP server 运行。例如，你可以用 codex mcp 将 Codex 暴露为一个工具，用在多智能体框架中，比如 OpenAI 的 Agents SDK。

Codex MCP Server 快速开始

你可以用 Model Context Protocol Inspector 启动 Codex MCP server：

npx @modelcontextprotocol/inspector codex mcp

发送一个 tools/list 请求，你会看到有两个可用的工具：

codex - 运行一个 Codex 会话。接受的配置参数与 Codex Config 结构体一致。codex 工具有以下属性：

属性	类型	描述
`prompt` (必填)	string	启动 Codex 对话的初始用户 prompt。
`approval-policy`	string	模型生成的 shell 命令的审批策略：`untrusted`、`on-failure`、`never`。
`base-instructions`	string	使用的一组指令，替代默认指令。
`config`	object	单独的 config 配置项，会覆盖 `$CODEX_HOME/config.toml` 中的设置。
`cwd`	string	会话的工作目录。如果是相对路径，则相对于 server 进程的当前目录解析。
`include-plan-tool`	boolean	是否在对话中包含 plan tool。
`model`	string	可选的模型名称覆盖（例如 `o3`、`o4-mini`）。
`profile`	string	`config.toml` 中的配置 profile，用于指定默认选项。
`sandbox`	string	Sandbox 模式：`read-only`、`workspace-write` 或 `danger-full-access`。

codex-reply - 通过提供 conversation id 和 prompt 来继续一个 Codex 会话。codex-reply 工具有以下属性：

属性	类型	描述
`prompt` (必填)	string	继续 Codex 对话的下一个用户 prompt。
`conversationId` (必填)	string	要继续的对话的 id。

尝试运行

[!TIP] Codex 运行通常需要几分钟。为此，可以在 MCP inspector 的配置里将 Request 和 Total 超时时间调整为 600000ms (10 分钟)。

使用 MCP inspector 和 codex mcp 构建一个简单的井字棋 (tic-tac-toe) 游戏，配置如下：

approval-policy: never

prompt: 使用 HTML、Javascript 和 CSS 实现一个简单的井字棋游戏。将游戏写在一个名为 index.html 的单文件中。

sandbox: workspace-write

点击 “Run Tool”，你应该会看到 Codex MCP server 在构建游戏时发出的事件列表。