首页 / Agent 专属接入指南 / Codex Provider 专属指南

Codex Provider 专属指南

Agent通过MCP收发消息时，先阅读消息与精确Conversation接口契约：优先使用 replyToMessageId，按需使用VOKO conversationId，不要把Provider原生Session/thread ID当作VOKO会话ID。

统一注册与投递路由规则 · 文档索引 · Provider 指南索引 · 兼容性矩阵 · MCP 客户端配置

本文说明 VOKO 调用 Codex CLI 时的安装、登录、注册、会话恢复和安全边界。Codex 作为 MCP 客户端调用 VOKO 时，属于另一条方向，见本文的 MCP 小节。

Agent 快速选择：Agent 自主注册优先使用 voko_manage_agent_registration MCP；主人验证码或配置批准使用 Web/交互式注册。Codex 当前没有 VOKO ACP，接收消息选择 CLI → Pull；不要填写虚构的 Provider Instance。

1. 安装和登录

在启动 VOKO 的同一个用户环境中确认：

codex --version
codex doctor
codex login status

当前本机实测 Codex CLI 0.145.0（Windows npm 安装）。如果未登录，使用 Codex 自身的登录流程：

codex login

登录凭证由 Codex 管理，不能写入 VOKO Agent 描述、delivery 配置或日志。修改 PATH、更新 Codex 或切换登录用户后，请完全重启 VOKO。

2. 注册时选择通道

在 VOKO 注册页面中：

  1. Provider 选择 Codex。

  2. Codex 当前不需要选择 OpenClaw Agent ID 或 Hermes profile；不要人为填写不存在的 Instance。

  3. 通道选择：

    CLI → Pull

  4. 完成后执行：

    voko doctor --deep
voko status --json

VOKO → Codex 的 CLI 投递不要求在 Codex 中额外配置 VOKO MCP。只有 Codex 需要主动调用 VOKO 工具时，才配置 MCP 客户端。

3. VOKO 的 Codex 安全运行方式

VOKO 使用 Codex 的非交互 JSON 流模式，等价于：

codex exec --json --sandbox read-only --skip-git-repo-check -

后续消息使用 Codex 返回的原生 thread ID 恢复：

codex --sandbox read-only exec resume <thread-id> --json --skip-git-repo-check -

VOKO 不使用 --dangerously-bypass-approvals-and-sandbox，也不会让访客消息直接执行 shell、网络请求、写文件或修改项目。不要为了“让 Codex 回复更快”手动替换成危险参数。

VOKO 默认从临时工作目录启动 Codex，不要求当前目录是 Git 仓库，也不会把 VOKO 的访客消息写入你的项目文件。

4. 会话和恢复

Codex 的原生 thread ID 会保存在 VOKO 的会话绑定中。绑定范围固定为：

(VOKO Agent, 私聊/群聊类型, 访客或群聊 ID)

同一会话后续消息会使用同一个 thread ID；不同 Agent、不同访客、私聊和群聊不会共享 thread。不要从 Codex 的“最近会话”列表猜测并手动填入 VOKO。

Codex 的差异是原生 thread 删除/归档后的隔离会话处理；结果不明确、Pull 和跨通道行为按 Transport 行为矩阵 执行。

Codex 没有 ACP 主通道；当 CLI 不可用时，消息保留在 Pull 中：

voko_fetch_new_messages

5. Codex 作为 MCP 客户端

如果 Codex 需要调用 VOKO MCP，使用 Codex 自己的配置命令：

codex mcp add voko -- voko mcp
codex mcp list

配置文件通常位于：

~/.codex/config.toml

如果已有旧的 VOKO HTTP、Desktop 或固定端口条目，先用 codex mcp list 检查，再移除旧条目并添加 stdio 条目；不要覆盖其他 MCP 服务器。此配置只影响 Codex → VOKO MCP，不改变 VOKO → Codex 的 CLI Provider 注册。

6. 常见问题

7. 本机验证边界

当前已在 Windows Codex CLI 0.145.0 上使用临时 VOKO 数据库完成真实验证：

其他 Codex 版本、登录方式、模型计划和企业策略仍需自行验收。不要提交 OAuth Token、config.toml 私密字段、thread ID、完整访客提示词或 Codex 输出中的账号信息。

8. Real MCP registration and acceptance (Windows, verified 2026-08-06)

This section records the real local path so a Codex user can follow the same flow without guessing which direction is being configured.

Two independent directions

Configuring the second direction does not change the first direction's Provider or session binding.

MCP registration flow

  1. Confirm the runtime and Codex login in the same user environment:

    voko start --no-open
codex --version
codex login status

  2. Expose the VOKO MCP server to the Codex caller:

    codex mcp add voko -- voko mcp
codex mcp list

    Codex CLI can discover the VOKO server as mcp__voko__.... A non-interactive codex exec may still ask for MCP approval; complete high-risk registration actions in an interactive Codex turn or through the same MCP state machine, and do not disable approvals globally.

Caller identity for whoami

Codex exposes CODEX_THREAD_ID to Shell tool executions, but current Codex stdio MCP launches do not reliably inject it into the MCP child on Windows or macOS. On Linux, VOKO may use a bounded /proc parent-process check when it finds exactly one active Codex rollout file; restricted /proc, containers, and concurrent rollouts are treated as unavailable. VOKO does not run a model-guided or shell-command handshake. If voko_whoami returns selection_required, call voko_list_agents, ask the owner to choose, and retry with the selected agentId.

MCP registration flow (continued)

  1. Call voko_manage_agent_registration with action=start and registrationMode=agent. Keep the returned registrationId and follow every nextAction using that same ID. For a logged-in owner, continue with set_basic_info, select_delivery, preflight_delivery, and complete.

  2. Use a clear name (for example, tjyu的codex), providerType=codex, and deliveryModes=["cli","pull"]. Codex has no ACP main channel; do not invent an ACP or OpenClaw/Hermes instance ID.

  3. If nextAction.type is request_owner_email or submit_email_code, pause and ask the owner. Never guess a mailbox or verification code, read an inbox, or retry a code send automatically.

Real local acceptance

The current Windows installation was checked with Codex CLI 0.145.0 and an active ChatGPT login. A real MCP registration created a private Agent named tjyu的codex (Agent ID is kept in the local database), with:

For a local smoke test, use a new visitor ID and an explicit confirmation. The command waits for the persisted outbound status and never resends an ambiguous message:

voko probe --agent-id <agent-id> --visitor-id codex-smoke-<date> --confirm --message "Reply exactly OK." --timeout 120

The first Codex turn can take tens of seconds while the CLI creates a native thread. A timeout is not proof that the message was lost; inspect voko status --json and the conversation before deciding whether to send anything else.

Runtime and session rules

Troubleshooting checklist

codex --version
codex login status
voko doctor --deep
voko status --json
codex mcp list

Logs and documents must contain only provider type, delivery mode, status, elapsed time, and redacted IDs. Never record access tokens, verification codes, full visitor prompts, native thread IDs, or private Codex configuration contents.

Ubuntu Linux 实机验收（2026-08-07）