dot × Linux Codex 接入实施蓝图

有一条基于公开接口的可行工程路线，仍需在真实 dot 上完成接入验证。让 dot 使用一个经用户授权的私有插件工具，再由工具服务转交给 Linux 上的 Codex。实际可用性还取决于账号的插件能力、工作区政策、OAuth 连接和所选 Codex 版本。

外部只需要一个公开可达、受鉴权保护的 HTTPS 网关。Linux 在 NAT 后面也可以主动连出；网关在这条已建立的双向连接内下发任务。

一次任务的完整往返

1. dot 调用 start_codex_job

   网关由 OAuth 主体确定 owner，校验 machine_id、workspace_id 与授权范围，保存幂等记录并立即返回 job_id。

2. 网关持久化后发出调度消息

   消息带 job_id、dispatch_id、请求摘要与控制版本；机器离线时先保留 queued，不伪造正在运行。

3. Linux 先记账，再启动 Codex

   本地 SQLite 持久化接收记录，校验工作区映射与权限，确认同一 dispatch 没有启动过，再创建或恢复会话。

4. 事件与日志按序回传

   每条记录携带 job_id、attempt、event_seq；网关先落盘再 ACK。重发可去重，断线后从最后确认位置补传。

5. dot 取得最终结果

   MVP 使用 get_codex_job 与分页日志。任务结束后返回摘要、明确终态、Codex thread / turn 关联及允许访问的产物信息。

示例地址：https://codex-gateway.example.com/mcp/codex 与 wss://codex-gateway.example.com/agent/codex。它们只说明路由设计。

机器注册与 owner 索引可单独使用一个持久化目录服务；规模增长后再考虑 D1 索引。DO 是协调点，本地台账是执行事实来源。两边都保留关键信息，才能在网络故障后对账。

Cloudflare Durable Objects 的 WebSocket API 可用于维持入站连接；选择 hibernation 方案时，要把恢复所需信息放进持久化存储或连接附件，不能依赖实例内存。具体兼容性与配额按最终部署环境验证。Cloudflare WebSocket 文档

以下五个名字、字段和返回值是本方案拟定的应用层契约，不是官方既有 Codex API。示例用 tool + arguments 表达调用意图；实际 MCP 外层封装由兼容所选协议版本的 SDK 实现。

所有工具都要求 OAuth。查询也必须校验 job 所属 owner。首版不允许工具传入任意路径、shell 命令、环境变量或原始 app-server RPC。

{
  "tool": "start_codex_job",
  "arguments": {
    "machine_id": "linux-dev-01",
    "workspace_id": "demo-repo",
    "instruction": "只读检查当前工作区的项目结构，给出摘要，不修改文件。",
    "client_request_id": "request-example-001"
  }
}

{
  "job_id": "job_example_01",
  "state": "queued",
  "revision": 1,
  "machine_id": "linux-dev-01",
  "workspace_id": "demo-repo",
  "deduplicated": false,
  "poll_after_ms": 3000
}

{
  "tool": "get_codex_job",
  "arguments": {
    "job_id": "job_example_01"
  }
}

{
  "job_id": "job_example_01",
  "state": "succeeded",
  "revision": 5,
  "latest_event_seq": 28,
  "result": {
    "summary": "已完成工作区只读检查。",
    "artifacts": []
  },
  "codex": {
    "thread_id": "thr_example_01",
    "turn_id": "turn_example_01"
  },
  "error": null,
  "blocked_reason": null
}

{
  "tool": "get_codex_logs",
  "arguments": {
    "job_id": "job_example_01",
    "cursor": null,
    "limit": 100
  }
}

{
  "job_id": "job_example_01",
  "entries": [
    {
      "event_seq": 28,
      "kind": "completion",
      "text": "只读检查完成",
      "redacted": true
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "truncated": false
}

{
  "tool": "continue_codex_job",
  "arguments": {
    "job_id": "job_example_01",
    "instruction": "沿用这次会话，解释测试入口；仍然只读。",
    "client_request_id": "request-example-002",
    "expected_revision": 5
  }
}

{
  "job_id": "job_example_01",
  "state": "queued",
  "revision": 6,
  "continuation_index": 1,
  "codex_thread_id": "thr_example_01",
  "deduplicated": false
}

{
  "tool": "cancel_codex_job",
  "arguments": {
    "job_id": "job_example_01",
    "client_request_id": "request-example-003"
  }
}

{
  "job_id": "job_example_01",
  "state": "cancel_requested",
  "revision": 8,
  "confirmed_stopped": false
}

为覆盖流式进度、审批、会话续聊与取消，详细适配可使用 app-server；如果只做短批处理或 CI，应先评估更简单的 Codex SDK。app-server 与相关传输仍有实验性质：固定版本、生成对应 schema 并做兼容测试后再上线。App Server 文档 · Codex SDK 文档

daemon 通过子进程的 stdin / stdout 通信。本地线协议是逐行 JSON；app-server 的 JSON-RPC 消息省略 jsonrpc 字段。下面只是初始化与生命周期骨架；权限设置必须由已审查的本地配置和沙箱强制执行。

codex app-server --listen stdio://

{"id":1,"method":"initialize","params":{"clientInfo":{"name":"linux_codex_bridge","version":"0.1.0"}}}
{"method":"initialized","params":{}}
{"id":2,"method":"thread/start","params":{"cwd":"/srv/codex-workspaces/demo"}}

// 从 id=2 的 result.thread.id 取真实 ID，再发送：
{"id":3,"method":"turn/start","params":{"threadId":"thr_example_01","input":[{"type":"text","text":"只读总结当前项目"}]}}

// 已有会话恢复后，再调用 turn/start：
{"id":4,"method":"thread/resume","params":{"threadId":"thr_example_01"}}

// 取消必须同时关联真实 thread 和正在运行的 turn：
{"id":5,"method":"turn/interrupt","params":{"threadId":"thr_example_01","turnId":"turn_example_01"}}

代码中的注释用于阅读，不能写入 JSONL 管道。真实 thread_id / turn_id 必须从响应读取并先持久化；示例 ID 不能直接执行。

需要持久化的数据

防重复执行的关键顺序

1. 网关以事务写入 job、幂等记录和待发消息，再回复调用方。
2. Linux 收到 dispatch 后先落本地台账；相同 dispatch 只返回已有执行信息。
3. 启动前保存 spawn_intent；尽快持久化真实 thread / turn ID。启动与落库之间若崩溃，进入 unknown 并对账，不能盲目重启。
4. 事件采用至少一次传送，使用序号去重；网关完成持久化后再 ACK，本地 outbox 才可清理。
5. 重连先交换 connection_epoch、ACK 位置和未结束任务清单；旧连接的控制命令被拒绝。新连接本身不意味着新任务。

同一工作区首版只允许一个写任务；revision 用于控制并发，event_seq 用于日志排序，两者不能混用。日志丢页要报告 gap，不把不完整输出包装成完整结果。

OAuth 发现、PKCE、resource / audience 与重连行为按官方插件认证规范实现；回调 URI 从实际插件管理界面复制，不猜固定地址。官方插件认证要求

工作区是服务端映射，不是自由参数

{
  "machine_id": "linux-dev-01",
  "gateway_url": "wss://codex-gateway.example.com/agent/codex",
  "credential_source": "os-protected-store:machine-identity",
  "workspaces": {
    "demo-repo": {
      "root": "/srv/codex-workspaces/demo",
      "permission_profile": "reviewed-readonly",
      "max_concurrent_jobs": 1
    }
  },
  "ledger_path": "/var/lib/codex-bridge/ledger.sqlite",
  "logs": {"redact": true, "max_event_bytes": 16384}
}

• 解析 realpath、拒绝路径穿越与越界符号链接；仅映射 cwd 还不够，必须同时限制读写根、挂载、网络与子进程能力。
• owner 必须由网关认证层注入；调用者不能自行指定、替换 owner_id。job ID 猜中也不赋予访问权。
• 不导出任意 shell、任意文件读取、环境变量注入、凭据读取或原始 RPC 转发接口。
• 任务输出是可能不可信的内容，不能因此改变授权或执行新的外部动作。脱敏后再入日志、工具响应与事件。
• 撤销机器凭据时关闭现有 WSS 并拒绝续接；明确在途任务的本地停止策略，无法确认停止则保留 unknown / cancel_requested。
• 密钥不进入聊天、URL 查询参数、日志、仓库或输出；用户通过受保护的配置 / 授权界面完成凭据交接。
• 审计记录任务提交、拒绝、审批、取消、续聊、机器注册 / 撤销；按保留期清理，不无限保存源码和完整会话。

Linux 前置检查

1. 确认发行版、架构、可用磁盘与内存；准备专用普通用户、一个测试仓库和可恢复的工作区快照。
2. 用户批准后，从官方渠道安装并固定 Codex 版本；验证本地登录、只读任务、沙箱与 app-server schema。
3. 确认 Linux 可出站访问网关 WSS 443，以及 Codex 所需的认证 / 推理服务；防火墙策略与网络代理单独审查。
4. 选定 daemon 运行时并固定依赖锁文件；要求 SQLite 持久化、子进程管理、日志轮转与磁盘告警。
5. 先在前台运行 daemon 做协议联调，通过后才安装并启用常驻服务。

建议仓库结构

codex-bridge/
  packages/contracts/       # 工具 schema、状态、错误与消息版本
  services/gateway/
    src/auth/               # OAuth 验证、owner 与 scope
    src/mcp/                # 五个工具与输入校验
    src/machine-object/     # WSS、租约、持久化、outbox
    src/events/             # 第二阶段订阅与 webhook
  services/linux-agent/
    src/transport/          # WSS 重连、ACK、心跳
    src/ledger/             # SQLite 调度与执行台账
    src/workspaces/         # 白名单与权限校验
    src/codex/              # stdio RPC、会话、审批适配
    src/supervisor/         # 子进程、停止与恢复
  tests/                    # 契约、故障注入、安全与端到端
  deploy/                   # 经审查的配置与 service 模板
  docs/                     # 运维、撤销、升级与回滚手册

按依赖实现，先用模拟器

1. 冻结契约与测试夹具

   定义五个工具、状态、身份边界、幂等规则。用假 Agent 跑通提交 → 结果，并覆盖重复调用。

2. 实现网关与机器通道

   分开验证 OAuth 用户身份和机器身份；先做持久化、ACK、重连与 owner 隔离，再接真实执行器。

3. 实现本地 Codex 适配

   逐请求关联响应，持续消费事件，处理审批和进程退出。用固定版本回归 initialization / resume / interrupt。

4. 接入真实私有插件

   使用当前平台支持的插件构建与测试流程配置 HTTPS MCP endpoint，完成用户连接后，检查五个工具是否出现在真实 dot 可用工具中。

5. 故障注入后再加事件

   断网、杀 daemon、重启网关、撤销凭据、并发续聊、乱序日志与重复 dispatch 全部有确定行为后，再实现主动完成通知。

常驻服务评审模板

codex-bridge-agent 是拟定的待实现程序名；下面没有对应已安装二进制。systemd 加固项须在目标系统逐项测试，不能替代 Codex 沙箱。

[Unit]
Description=Private Codex Bridge Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=codexbridge
Group=codexbridge
ExecStart=/opt/codex-bridge/bin/codex-bridge-agent --config /etc/codex-bridge/config.json
Restart=on-failure
RestartSec=5
UMask=0077
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
StateDirectory=codex-bridge
ReadWritePaths=/var/lib/codex-bridge
ReadOnlyPaths=/srv/codex-workspaces/demo

[Install]
WantedBy=multi-user.target

模板对应只读 MVP。Codex 状态目录、凭据读取与进程的 HOME 需按目标主机的受保护路径单独适配；确认无密钥被发送到 MCP。需要写工作区时，只在获准后替换相应只读挂载与写路径，并重复越界测试。

运维与成本

分开核算 Codex 使用额度 / 推理费用、Linux 主机、Worker 请求与 CPU、DO 请求 / 时长 / 存储、R2 容量与请求、日志保留、域名与身份服务。本文不估造价格；按最终地区、套餐和实际流量测量。先限制并发、单任务时长、日志大小、产物大小与排队期限。

MVP 先查询，第二阶段再加 MCP Events。不要把一次 MCP 工具调用挂起几十分钟。start 立即返回 job_id；get_job 查询进度。后台跑完后主动唤醒，需要平台支持且用户明确订阅事件。

官方文档已说明 MCP Events 可用于 dots，采用 MCP 2.0 协议版本 2026-07-28，由平台在订阅时提供回调地址与签名 secret。工作区政策仍然适用。MCP Events 官方文档

1. 网关发布 events 能力，实现 events/list、events/subscribe、events/unsubscribe。
2. 拟定事件 codex.job.completed 与 codex.job.blocked；按已认证 owner 与 job_id 限定订阅。
3. 用户明确要求“该任务完成 / 阻塞时通知我”后，由平台发起订阅；网关先验证回调，再存储订阅与有效期。
4. 任务状态落库和事件 outbox 同一事务；后续发送签名 webhook，独立记录送达与重试，避免阻塞任务完成。
5. 取消订阅或撤销访问后停止投递；回调失败不重跑 Codex，只重试合格的通知消息。

{
  "job_id": "job_example_01",
  "state": "succeeded",
  "revision": 5,
  "event_seq": 28,
  "summary": "指定工作区的只读检查已完成。"
}

事件 payload 只含必要结果元数据，完整日志仍走带身份校验的 get_codex_logs。端到端验收要真实证明：订阅成功、完成事件到达对应对话、重复通知去重、取消订阅后不再触发。

• 工具可见与授权真实 dot 能发现五个工具，未授权调用失败，授权后限定 owner 生效。
• 机器与工作区命中只在指定 Linux 的白名单工作区执行，可用预置测试文件证明。
• 结果关联job、dispatch、thread、turn、event_seq 可对应，结果无串任务。
• 幂等重放同请求重试不多建任务；同键不同参数冲突；重复投递不重复执行。
• 越权与越界拒绝其他 owner、非法 workspace、路径穿越、越界符号链接均被阻止。
• 撤销即时生效旧 token / 机器凭据无法继续接入；在途任务状态和停止策略明确。
• 重启与断网恢复daemon / 网关重启不丢台账；状态不明进入 unknown，恢复后对账。
• 续聊与取消续聊沿用 thread；版本冲突失败；取消依据对应 turn 的实际终态。
• 审批不被绕过审批请求进入 blocked；普通续聊、断线或超时都不会自动批准。
• 事件闭环用户订阅后准确通知；取消订阅、到期和撤销后停止投递。

故障排查顺序

上线后的回滚路径

先停止接收新任务并撤销受影响机器访问，记录在途任务事实；恢复到已测试的网关和 Agent 版本，保留兼容的台账与数据库备份。必须先确认本地进程状态，再决定是否重新执行。升级 Codex 时重跑协议与安全测试，不自动跟随 latest。

官方资料核对日期：2026 年 10 月 5 日。公开接口可能变化；上线时应再次核对并固定版本。以下来源支持接口能力；本文的网关拓扑、数据模型、工具名与可靠性策略属于设计建议。

• [01]
  Codex App Server

  传输、初始化、thread / turn 生命周期、审批与实验性边界。

• [02]
  Codex SDK

  批处理、脚本与自动化集成的替代入口。

• [03]
  Plugins · MCP server

  通过插件向 OpenAI host 提供工具的公开接入面。

• [04]
  Plugins · Authentication

  OAuth 发现、resource、scope、PKCE 与用户连接流程。

• [05]
  Durable Objects · WebSockets

  连接管理与 hibernation 的实现依据。

• [06]
  Plugins · MCP Events

  dots 支持范围、事件订阅、回调验证与签名投递。

上方原文内的参考资料保持原样；这里列出当前修订记录的来源。

• Codex App Server

• Codex SDK

• Plugins · MCP server

• Plugins · Authentication

• Durable Objects · WebSockets

• Plugins · MCP Events