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 只发出工具事件与最终响应事件，不发出中间 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 事件
`item.type == "agent_message"`	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 id。该 Agent 会把这个 id 存入 session state 的 codex.StateKeyThreadID，并在后续轮次使用：

首轮：把 prompt 写入 codex exec --json 的 stdin
后续轮次：把 prompt 写入 codex exec resume --json <thread-id> 的 stdin

如果 resume 失败，该 Agent 会重新发起一次新的 codex exec；如果新执行返回了 thread id，则更新已保存的 thread id。如果 resume 与新建执行都失败，本次调用会返回 run error。

如需保持上下文，请在 runner 中持续使用相同的 app name、user ID、session ID。

原始日志落盘

使用 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 结束后、解析前调用。