Codex Agent 使用指南

概述

tRPC-Agent-Go 提供了 Codex 的 Agent 实现，通过执行本地 Codex CLI 的 codex exec --json 获取 JSONL 事件流，并实时映射为框架事件。

该实现的主要用途包括：

在 runner 中运行 Codex
落盘 CLI 原始 stdout 与 stderr
在评估中对齐 Codex 命令与 MCP 工具轨迹

快速上手

前置条件

本地已安装并完成 Codex CLI 认证
CLI 可执行文件可从 PATH 访问，或通过 WithBin 指定绝对路径

基本用法

完整示例参见 examples/codex。该示例包含临时的项目内 MCP server 和项目内 skill。

import (
    "trpc.group/trpc-go/trpc-agent-go/agent/codex"
    "trpc.group/trpc-go/trpc-agent-go/model"
    "trpc.group/trpc-go/trpc-agent-go/runner"
)

ag, err := codex.New(
  codex.WithBin("codex"),
  codex.WithGlobalArgs("--sandbox", "workspace-write"),
)
if err != nil {
  log.Fatal(err)
}

r := runner.NewRunner("codex-cli-example", ag)
defer r.Close()

ch, err := r.Run(context.Background(), "user-1", "session-1", model.NewUserMessage("Run pwd and summarize the workspace."))
if err != nil {
  log.Fatal(err)
}

输出格式与解析

该 Agent 会强制为 codex exec 添加 --json，并按 JSONL 解析 stdout。除非需要控制参数顺序，否则不要手动追加 --json。

Prompt 文本会通过 stdin 写入 Codex CLI，因此 --help 这类用户输入不会被解析成 Codex CLI flag。

WithExtraArgs 会把参数追加到 exec 或 exec resume 之后，只适合传入同时被 codex exec 与 codex exec resume 接受的参数，例如 --model。

WithGlobalArgs 会把参数追加到 exec 子命令之前，适合传入 --ask-for-approval、--sandbox、--cd 等 Codex 根级参数。

ag, err := codex.New(
  codex.WithGlobalArgs("--ask-for-approval", "never"),
  codex.WithGlobalArgs("--sandbox", "read-only"),
)

Skill 与外部仓库

该 Agent 不安装、不合并、不改写 Codex skill 仓库。它只是在指定环境、profile 与工作目录下执行本地 Codex CLI；同一个 codex exec 命令能从本地 Codex 配置加载到的 skills、plugins 或 plugin marketplaces，在该 Agent 中同样可用。

可以通过 Codex CLI 既有配置机制选择 skill 来源：

WithEnv("CODEX_HOME=/path/to/codex-home") 选择隔离的 Codex home。
WithGlobalArgs("-p", "profile-name") 选择 Codex profile。
WithGlobalArgs("-c", "key=value") 传入 Codex config override。
WithGlobalArgs("--cd", "/path/to/workspace") 或 WithWorkDir("/path/to/workspace") 选择 workspace context。

如果该 Codex CLI 环境配置了多个外部 skill 仓库，该 Agent 不会过滤它们；但它也不会根据配置合成 skill 事件。当前 Codex CLI 更偏向通过 shell 命令处理 skill，而不是专门的 skill 工具，因此映射到框架事件时通常是 command_execution，而不是 skill_run。

事件映射

该 Agent 会随着 Codex JSONL 到达实时发出 assistant、工具与错误事件，并在 Codex turn 完成后发出最终完成响应。Codex 的 agent_message 是完整消息 item，不是 token delta，但该 Agent 会把它暴露为 partial chat.completion.chunk segment，确保 session 持久化只保存最终 assistant response。最终完成响应使用最后一个 assistant message 的内容，并携带最终 usage 与 thread state；不发出中间 reasoning 事件。

Codex JSONL 输出	框架事件
`type == "thread.started"`	默认持久化到 session state key `codex.StateKeyThreadID`
`item.type == "command_execution"`	tool-call 与 tool-result response 事件
`item.type == "mcp_tool_call"`	tool-call 与 tool-result response 事件
`web_search`、`file_change`、`image_view`、`image_generation` 等内置工具 item	tool-call 与 tool-result response 事件
`type == "turn.failed"` 或 `type == "error"`	不携带 `Response.Error` 的非终止 error observation chunk；命令结束后再发出一个终止 error
`item.type == "agent_message"`	partial assistant chunk 事件；最后一个 `agent_message` item 同时作为 final response 内容
`type == "turn.completed"`	final response usage

MCP 工具调用会尽量归一化为与 Claude Code 兼容的工具名：mcp__<server>__<tool>。内置工具调用会保留 Codex 工具名。当前 Codex CLI 的真实 skill 使用常作为 prompt context 注入，或通过 shell command_execution item 体现。该 Agent 会保留这些真实 item 类型，不会合成 skill_run 事件。

多轮会话

默认方式：使用 Codex thread

默认情况下，该 Agent 使用 Codex CLI 原生 thread 历史：

首轮把 prompt 写入 codex exec --json 的 stdin。
Codex 返回 thread.started 后，Agent 把 thread id 存入 session state 的 codex.StateKeyThreadID。
后续轮次如果 session state 中有 thread id，Agent 把 prompt 写入 codex exec resume --json <thread-id> 的 stdin。

如果 resume 在发出任何 transcript 事件前失败，该 Agent 会重新发起一次新的 codex exec；如果新执行返回了 thread id，则更新已保存的 thread id。如果 resume 已经发出过框架事件，或 stdout 解析失败，则不会再启动新的执行，以避免重复暴露进度或重复执行工具副作用，而是直接返回本次失败。如果 resume 与新建执行都失败，本次调用会返回 run error。

这种方式适合单实例服务，或请求总是固定路由到同一台机器、同一个用户目录和同一套 Codex 配置环境的场景。此时如需保持上下文，请在 runner 中持续使用相同的 app name、user ID、session ID。

使用 WithResumeEnabled(false) 可以关闭 Codex CLI 原生 resume。关闭后，该 Agent 不读取已有 codex.StateKeyThreadID，不调用 codex exec resume，也不会把新观察到的 thread id 写回 session state；每次调用都会执行新的 codex exec。

使用框架 session events 构造上下文

如果服务部署了多个实例、容器会重建，或者请求不会固定路由到同一台机器，Codex CLI 本地 thread 就不能作为可靠的多轮上下文来源。此时应把上下文放在框架 session service 中，例如 Redis 或数据库。所有服务实例通过相同的 app name、user ID、session ID 读取同一份 session events，再由 WithMessageBuilder 把这些 events 拼成传给 Codex CLI 的完整 prompt。

推荐配置方式：

给 runner 配置共享 session service。
使用 WithMessageBuilder 从 args.Events 构造完整 prompt。
使用 WithResumeEnabled(false) 关闭 Codex CLI 本地 thread resume，避免同一段历史同时来自 prompt 和本地 thread。

MessageBuilderArgs.Events 是只读浅快照，不应修改其中的 event、response、state delta 或 extensions。通过 runner.Run 调用时，runner 会先持久化当前 turn 的 user message，再调用 Agent；因此 builder 看到的 events 已经包含当前 turn user message，不要默认再追加一遍。

下面示例省略 context、strings 等标准库 import，只展示 Agent 相关配置。示例只拼接非 partial 的 message 文本；生产环境可以按业务需要选择是否加入工具调用和工具结果。

import "trpc.group/trpc-go/trpc-agent-go/agent/codex"

ag, err := codex.New(
  codex.WithMessageBuilder(func(ctx context.Context, args *codex.MessageBuilderArgs) (string, error) {
    var prompt strings.Builder
    for _, evt := range args.Events {
      if evt.Response == nil || len(evt.Choices) == 0 || evt.IsPartial {
        continue
      }
      msg := evt.Choices[0].Message
      if msg.Content == "" {
        continue
      }
      prompt.WriteString(string(msg.Role))
      prompt.WriteString(": ")
      prompt.WriteString(msg.Content)
      prompt.WriteString("\n")
    }
    return prompt.String(), nil
  }),
  codex.WithResumeEnabled(false),
)

原始日志落盘

使用 WithRawOutputHook 获取每次执行的 stdout/stderr，建议写入评估/观测产物目录中：

ag, err := codex.New(
  codex.WithRawOutputHook(func(ctx context.Context, args *codex.RawOutputHookArgs) error {
    // Write args.Stdout / args.Stderr to your log storage.
    return nil
  }),
)

RawOutputHookArgs 包含框架侧 SessionID 与 Codex 侧 ThreadID，可用于按 session 聚合日志。

配置选项说明

Option	说明
`WithName(name)`	设置 Agent 名称。该值会用作事件 author。
`WithBin(bin)`	设置 CLI 可执行文件路径。默认值为 `codex`。
`WithGlobalArgs(args...)`	在 `exec` 子命令前追加 Codex 根级 flags。
`WithExtraArgs(args...)`	在可选 resume session id 前追加 `codex exec` flags。
`WithEnv(env...)`	追加 CLI 环境变量。格式为 `KEY=VALUE`。
`WithWorkDir(dir)`	设置 CLI 进程工作目录。
`WithRawOutputHook(hook)`	观测 raw stdout/stderr。回调会在 CLI 结束后、流式事件发出后调用；如果返回错误，会追加错误事件并跳过最终 assistant response。
`WithMessageBuilder(builder)`	自定义传给 Codex CLI 的完整 prompt。
`WithResumeEnabled(enabled)`	控制是否使用 Codex CLI thread resume；默认 `true`。