连接 Codex App Server

Codex App Server 是更底层的服务接口，适合远程 TUI、自研富客户端和需要实时事件流的集成。它不是新手自动化首选；如果只是跑一次任务，优先用 codex exec 或 Codex SDK。

App Server 会暴露能操作 workspace 的入口。跨机器使用前必须先处理认证、TLS、token 保管、日志脱敏和 sandbox / approval 边界。

Codex App Server

查看官方 App Server 协议和使用说明。

Remote TUI

学习如何把本地 TUI 连接到远程执行环境。

Non-interactive mode

一次性自动化任务优先看 codex exec。

它解决什么问题

flowchart TB
    AppServer["Codex App Server"]
    Remote["远程 TUI<br/>本地操作，远端执行"]
    Client["自研客户端<br/>展示 thread、turn、diff、approval"]
    Events["实时事件流<br/>item started/completed、工具调用、审批"]

    AppServer --> Remote
    AppServer --> Client
    AppServer --> Events

适合：

代码和凭据必须留在远端机器，但用户想在本地操作。
你要做自己的 IDE 插件、内部代码平台或审查界面。
需要实时展示 agent 正在做什么。
需要处理 thread、turn、item、approval、diff 和事件流。

不适合：

新手学习 Codex。
CI 中跑一次检查。
批量文档处理。
没有认证和权限模型的远程访问。

和 exec、SDK 的边界

codex exec：

适合一次性自动化。
适合 CI、scheduled jobs、批处理和结构化输出。
比 App Server 更简单。

Codex SDK：

适合在后端程序里控制 Codex。
比 exec 更适合长期集成。
不要求你自己做完整富客户端协议。

App Server：

适合客户端级体验。
需要处理实时事件、审批、状态同步和连接安全。
复杂度最高。

学习顺序建议：CLI -> codex exec -> SDK -> App Server。

安全路线

最小风险路线：

flowchart LR
    Local["本机 TUI"] --> Loopback["127.0.0.1 app-server"]

远程但受控路线：

flowchart LR
    Local["本地 TUI"] --> Tunnel["SSH tunnel"]
    Tunnel --> Remote["远端 app-server"]

高风险路线：

flowchart LR
    Client["网络客户端"] --> TLS["TLS + auth"]
    TLS --> Server["非本机 app-server"]

如果要跨网络直接连接，至少需要：

WebSocket 认证。
TLS。
token 文件权限控制。
日志脱敏。
失败重试和超时处理。
明确 sandbox 与 approval。

不要裸露监听在公网地址。

心智模型

App Server 中常见对象：

Thread：一段会话。
Turn：一次用户请求。
Item：turn 中的工作单元，例如消息、工具调用、命令、diff、审批请求。

客户端要做的不只是“发 prompt 等回答”，而是持续消费事件流：

turn 开始。
item 开始。
工具调用。
审批请求。
文件变化。
item 完成。
turn 完成。

如果客户端只显示最终回答，而不显示过程事件，就很难做可信审查。

常见坑

把 App Server 当普通 HTTP API。
不处理事件顺序和断线重连。
只显示最终结果，不显示审批和 diff。
远程暴露但没有 TLS 和认证。
把 token 放进命令行、日志或仓库。
忽略 shell 命令和 sandbox 的边界差异。
没有 overloaded / timeout / retry 策略。

这些问题不是实现细节，而是产品安全边界。

CLI 入口和参数

官方 CLI reference 将 codex app-server 标记为 Experimental，用途是为 local development 或 debugging 启动 Codex app server。

默认监听方式：

codex app-server --listen stdio://

WebSocket 监听方式：

codex app-server --listen ws://127.0.0.1:PORT

WebSocket 相关参数包括：

参数	用途
`--listen`	监听 `stdio://` 或 `ws://IP:PORT`
`--ws-auth`	WebSocket client 认证模式
`--ws-token-file`	capability token 文件
`--ws-shared-secret-file`	signed bearer token 的 HMAC secret 文件
`--ws-issuer`	signed bearer token 的 expected `iss`
`--ws-audience`	signed bearer token 的 expected `aud`
`--ws-max-clock-skew-seconds`	校验 `exp` / `nbf` 的 clock skew

如果 --listen ws://IP:PORT 暴露给非本机客户端，必须把认证、TLS termination 和日志脱敏当成前置条件。

Remote TUI 最小流程

在远端机器启动 app server。
通过 SSH tunnel 或安全代理暴露到本机。
本机用 codex --remote ws://host:port 连接。
如果 server 要求 bearer token，用 --remote-auth-token-env 从环境变量读取。
连接后确认命令实际在远端 workspace 执行。
先跑 pwd、git status 这类只读命令验证环境。

token 不要放在命令行参数里。命令行历史、进程列表和日志都可能泄露它。

调试方式

官方 CLI reference 提供了 codex debug app-server send-message-v2，用于通过内置 test client 向 app-server 发送一条 V2 message，并观察 thread / turn flow。

适合调试：

app-server 是否能启动。
client 是否能建立 thread。
turn event 是否能正常流出。
approval 或 tool event 是否按预期出现。
客户端消费事件是否遗漏。

不适合调试业务任务成功率。业务任务失败时，仍要看 workspace、sandbox、approval、model、prompt 和项目命令。

最小验收清单

用对 App Server，至少应能证明：

命令在哪台机器执行。
workspace 在哪里。
token 存在哪里，如何轮换。
非本机连接如何认证和加密。
客户端能显示审批请求和 diff。
用户能拒绝高风险动作。
失败时能区分认证、连接、sandbox、模型和客户端消费问题。

如果这些问题说不清，不要把 App Server 用到真实项目里。