---
title: "连接 Codex App Server"
description: "理解 Codex App Server 适合远程 TUI 和富客户端集成，不要把它误用成普通 CI 自动化入口。"
verifiedAt: "2026-05-07"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

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

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

<Cards>
  <Card title="Codex App Server" href="https://developers.openai.com/codex/app-server">
    查看官方 App Server 协议和使用说明。
  </Card>
  <Card title="Remote TUI" href="https://developers.openai.com/codex/cli/features#connect-the-tui-to-a-remote-app-server">
    学习如何把本地 TUI 连接到远程执行环境。
  </Card>
  <Card title="Non-interactive mode" href="/docs/codex/official/01-products/28-non-interactive">
    一次性自动化任务优先看 `codex exec`。
  </Card>
</Cards>

## 它解决什么问题

```mermaid
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。

## 安全路线

最小风险路线：

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

远程但受控路线：

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

高风险路线：

```mermaid
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。

默认监听方式：

```bash
codex app-server --listen stdio://
```

WebSocket 监听方式：

```bash
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 最小流程

1. 在远端机器启动 app server。
2. 通过 SSH tunnel 或安全代理暴露到本机。
3. 本机用 `codex --remote ws://host:port` 连接。
4. 如果 server 要求 bearer token，用 `--remote-auth-token-env` 从环境变量读取。
5. 连接后确认命令实际在远端 workspace 执行。
6. 先跑 `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 用到真实项目里。

## 官方资料

- [Command line options](https://developers.openai.com/codex/cli/reference)
- [Codex CLI features: remote app-server](https://developers.openai.com/codex/cli/features#connect-the-tui-to-a-remote-app-server)
- [Codex app features](https://developers.openai.com/codex/app/features)
