连接 Codex App Server

基于官方 Codex App Server 教程，面向新手讲清它适合什么场景、为什么危险、以及如何从安全边界开始使用。

Codex app-server 是 Codex 用来支撑富客户端的接口层，例如 VS Code 扩展这类体验。它能暴露认证、会话历史、审批流程和 Agent 运行事件。官方文档也明确说：如果你只是做自动化任务或 CI，不要从 app-server 开始，优先看 Codex SDK 或 codex exec。

所以这页先不带你抄完整 JSON-RPC 协议。新手更需要先理解：app-server 是把 Codex 变成“可被客户端连接和控制的服务”，它的能力更底层，风险也更直接。

先理解它解决什么问题

普通 Codex CLI 是你在一个终端里和 Codex 对话。App Server 则把“对话、审批、文件变化、命令执行、事件流”拆成协议，让另一个客户端可以连接它。

这适合两类场景。

第一类是远程 TUI：代码和命令在远程机器上，人在本地用 Codex TUI 操作。官方 CLI features 里说明，app-server host 拥有 workspace 并运行命令，本地 TUI 只是连接过去。

第二类是自研富客户端：你要自己做一个类似 IDE 插件、内部代码平台或审查界面，需要展示 thread、turn、item、审批、diff 和流式消息。

如果你的目标只是“让 Codex 在 CI 里跑一次”，app-server 太底层。先用 codex exec，它天然适合 pipeline、pre-merge check、scheduled job 和机器可读输出。

怎么判断该不该用

适合用 app-server：

你要做自己的 Codex 客户端，而不只是运行一次任务。
你需要实时展示 Agent 正在做什么，包括命令、文件变化、审批请求和最终结果。
你的代码、凭据或执行环境必须留在某台远程主机上，但你想在本地使用交互式 TUI。
你能处理认证、TLS、token 保管、断线重连、事件顺序和错误重试。

不适合用 app-server：

你只是新手学习 Codex。
你只是做 CI 自动化。
你还没有清楚的权限模型。
你没有准备好处理 WebSocket 暴露带来的安全问题。
你只是想“看起来更高级”。

两条安全路线

最安全的新手路线是本机或 SSH 隧道。让 app-server 只监听 127.0.0.1，本地连接，或者通过 SSH port forwarding 连接远程机器。这样风险边界清楚：服务不直接暴露到公网。

更复杂的路线是跨机器 WebSocket。官方文档提醒，plain WebSocket 优先用于 localhost 或 SSH port-forwarding；如果把 listener 暴露到非本机地址，要先配置认证，并把非本机认证连接放在 TLS 后面。token 文件要像密码一样保存，泄露后要重新生成。

新手不要从 0.0.0.0 裸露监听开始。能用 SSH 隧道，就先用 SSH 隧道。

最小心智模型

App Server 里最核心的是三个对象。

Thread 是一段会话。你可以开始、恢复、列出、归档一段会话。

Turn 是一次用户请求。你对 thread 发起一个 turn，Codex 开始工作。

Item 是 turn 里的工作单元。它可能是用户消息、Agent 回复、命令执行、文件改动、工具调用、计划更新或审查结果。

客户端真正要做的不是“发一个 prompt 然后等回答”，而是持续读取事件流，把 item/started、item/completed、审批请求、diff 更新和最终状态渲染给用户。

新手常见坑

把 app-server 当普通 HTTP API：它是双向 JSON-RPC 和事件流，客户端需要长期读取状态。
只看最终回答，不看过程事件：审批、命令、文件变化都在事件里，忽略它们就无法做可信 UI。
远程暴露不加 TLS 和认证：这等于把能操作 workspace 的入口暴露出去。
把 token 放命令行或日志：官方建议优先用 token file，token 要按密码处理。
忽略 sandbox 和审批：客户端必须清楚哪些命令能跑、哪些文件能改、哪些动作需要人确认。
误用 thread/shellCommand：官方说明它在 sandbox 外运行，不继承 thread sandbox policy，只适合用户主动触发的命令。
没有处理 overloaded：WebSocket 模式下 request ingress 满了会返回 server overloaded，客户端应该退避重试。

新手应该怎么试

先只做本地 loopback。启动 app-server 时只监听本机地址，再从同一台机器连接。目标不是马上做产品，而是确认你能看到 thread、turn 和 item 的生命周期。

然后做一个只读 turn。让 Codex 总结仓库结构，不允许改文件。你要观察的是事件顺序，而不是回答好不好看。

再做一个需要审批的小任务。比如让 Codex 提议修改一个测试文件，客户端必须能展示审批请求、用户决定、最终 diff 和完成状态。

最后再考虑远程连接。远程时先用 SSH port forwarding；确实要跨网络直接连接时，再补 TLS、WebSocket auth、token 管理和日志脱敏。

和 SDK、exec 的边界

codex exec 适合一次性自动化。它默认 read-only，可以按任务开启 workspace-write，也支持 JSONL 和结构化输出。

Codex SDK 适合在自己的后端程序里控制 Codex，比一次性 exec 更适合长期会话和产品集成。

App Server 适合做富客户端或远程 TUI。它不是更简单的 SDK，而是更底层的协议入口。

新手按这个顺序学：先 CLI，再 codex exec，再 SDK，最后 app-server。顺序反了，通常会先遇到安全和协议复杂度，而不是先解决真实问题。

怎么验收你用对了

你能明确说出命令在哪台机器执行、workspace 在哪里、token 存在哪里。

你能在客户端里看到 turn 开始、item 开始、审批请求、item 完成和 turn 完成。

你能证明非本机连接有认证和 TLS，或者只通过 SSH 隧道访问。

你能在失败时区分是认证失败、初始化失败、sandbox 失败、上游模型失败，还是客户端没有正确消费事件。

你能让用户在每次文件修改或危险命令前看到清楚的审批信息。