OpenAI Codex — App-Server provider (`codex-app-server`)

1. 架构

┌─ OmniRoute 应用 ────────────────┐        ┌─ codex-app-server 边车 ─────────────┐
│  CodexAppServerExecutor          │  WS    │  codex app-server                   │
│  ws://codex-app-server:1456 ─────┼───────▶│  --listen ws://0.0.0.0:1456         │
│  （+ 能力令牌）                   │  JSON  │  --ws-auth capability-token         │
│                                  │  RPC   │  自行管理 OpenAI OAuth              │
└──────────────────────────────────┘        │  (~/.codex/auth.json, 自动刷新)     │
        │ 共享（compose 卷）                 └─────────────────────────────────────┘
        ▼
  codex-appserver-token   → WS 能力令牌（两者都会挂载）
  codex-appserver-home    → ~/.codex（auth.json 由仪表板写入，
                             由边车中的 codex app-server 读取）

• 边车仅监听内部 compose 网络 （ws://codex-app-server:1456），并由能力令牌保护。它绝不会 发布到主机或互联网。
• Codex CLI 已内置于 omniroute:base 中，因此运行边车时， 无需在主机或用户的计算机上安装 codex。

2. 启动

# 使用 codex app-server 边车配置启动整个服务栈：
docker compose --profile base --profile codex-app-server up -d
# （podman：podman compose --profile base --profile codex-app-server up -d）

边车会在首次启动时生成其 WS 能力令牌（存入共享的 codex-appserver-token 卷），应用则通过 OMNIROUTE_CODEX_APPSERVER_WS_TOKEN_FILE 读取同一个令牌。无需手动配置令牌。

3. 连接并登录

1. 在仪表板中，添加一个 OpenAI Codex (App-Server) 连接。无需 API 密钥或令牌（这是一个无身份验证提供者 — 身份验证由边车负责）。
2. 如果边车中的 Codex CLI 尚未登录，连接健康检查会报告 “正在运行但未登录”（而不是红色的身份验证错误）。使用 通过 ChatGPT 登录：这会在浏览器中运行标准 Codex 设备 OAuth 流程， 然后通过应用身份验证信息将 ~/.codex/auth.json 写入共享卷 （同一次登录可同时供 codex 和 codex-app-server 提供者使用）。
3. 登录后，健康检查会变为绿色（它会同时验证 /readyz 和 account/read — 即服务已启动且已通过身份验证），并开始处理任务。

仪表板绝不会覆盖现有且有效的 ~/.codex/auth.json — 只有当文件不存在或 其中的令牌已过期时才会写入（并且始终会先创建备份）。

4. 部署场景

• 已有经过身份验证的 Codex CLI 的运维人员 — 将主机上的 ~/.codex 挂载到边车（codex-appserver-home），并跳过登录步骤。
• 公共用户，本地未安装 codex — 无关紧要：边车已包含 CLI。 用户只需通过仪表板进行身份验证。
• 裸机 OmniRoute（无边车，使用主机上的 codex） — 将 OMNIROUTE_CODEX_APPSERVER_WS 指向你自己的 codex app-server，并确保 主机上的 codex 已登录；如果缺少该二进制文件，则会显示“未安装 codex”的提示。

5. 住宅网络 / UDP 出站流量（运维人员附加配置，未随附）

上述通用边车通过容器的常规网络发送出站流量。需要让 Codex 流量经由 住宅网络出口（例如承载 TCP + UDP/QUIC 的 TUN tailscale 边车）发送的 运维人员，可以通过单独的 compose 覆盖配置来运行该方案；它有意不 包含在随附的 codex-app-server 配置中。有关该设置，请参阅内部运维手册。

---

undefined (a58000c7685f)