App-server 传输

OpenClaw 如何启动并连接到 Codex app-server，以及每个 appServer 字段。属于 Codex 测试框架参考；各章节迁移位置 列出所有章节。

App-server 传输¶

对于普通测试框架回合，OpenClaw 会启动随官方插件一起发布的受管理 Codex 二进制文件（当前为 @openai/codex 0.158.0）：

codex app-server --listen stdio://

这使 app-server 版本与官方 codex 插件绑定，而不是本地碰巧安装的某个独立 Codex CLI。OpenClaw 使用 Node 包解析从加载器选择的插件根目录解析 @openai/codex/bin/codex.js，包括 npm 提升和 pnpm 链接的依赖。对于受管理的启动，它不会搜索 .bin 垫片或全局 PATH。在 Windows 上，Node 运行相同的包入口点，无需 codex.cmd 垫片。仅当有意使用不同的可执行文件时，才设置 appServer.command。使用默认隔离 agent 主目录的普通受管理回合，即使安装了 macOS 桌面捆绑包，也优先使用此固定包。当启用 Computer Use，或当 homeScope 为 "user" 且能够加载原生 Computer Use 状态时，受管理的启动会改为优先使用拥有所需 macOS 权限的桌面应用二进制文件。当隔离 agent 主目录的有效 Codex 配置启用原生 Computer Use 时，同样适用桌面优先规则。如果未安装桌面应用捆绑包，OpenClaw 会回退到固定包二进制文件。

在切换已暂存的 OpenClaw 包之前，针对候选安装运行可选的受管理二进制文件检查：

openclaw doctor --lint --only codex/managed-app-server --json

该检查是只读的。对于每个已配置的 Codex agent，它会应用与实时测试框架回合相同的最终命令选择，然后验证所选的包拥有的原生二进制文件是否存在，并报告插件的确切固定版本。所选的 Codex Desktop 二进制文件、显式自定义命令和远程 app-server 不在此包检查范围内。如果存在错误级别的问题，该命令会以非零状态退出，因此部署者可以在切换前拒绝候选版本，而无需更改 Codex 状态或 app-server 设置。

可执行文件交接和原生配置围栏在一个运行的 Gateway 进程内协调客户端。在另一个进程更改原生 Codex 插件配置后，重启 Gateway。

监督会解析一个独立连接。在没有显式 appServer 连接设置时，它使用 homeScope: "user" 的受管理 stdio；普通测试框架仍使用 homeScope: "agent" 的受管理 stdio。两条路径都会遵循显式连接设置。当普通测试框架应与原生客户端共享 $CODEX_HOME（或 ~/.codex）时，显式设置 homeScope: "user"。私有监督绑定无论普通测试框架默认值如何，都使用监督连接。独立的 App Server 进程保留各自独立的实时状态和审批状态。

对于针对已运行 app-server 的非生产测试，可使用 WebSocket 传输：

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            authToken: "${CODEX_APP_SERVER_TOKEN}",
            requestTimeoutMs: 60000,
          },
        },
      },
    },
  },
}

Codex 将 WebSocket 传输归类为实验性且不受支持。对于生产工作负载，请优先使用受管理 stdio 或本地 Unix 控制套接字。

appServer 字段：

appServer.args 接受数组（推荐）或带引号的参数字符串。 OPENCLAW_CODEX_APP_SERVER_ARGS 在每个平台上使用相同的字符串解析： 单引号和双引号用于将单词分组，反斜杠和 # 保持字面量，未闭合的引号会将剩余文本分组。这保留了 v2026.9.1 中提供的字符串语法；字符串不使用 shell 转义。

对于包含嵌入引号的值，请使用数组项，例如 'model="gpt-5.6-luna"'。对于包含字面反斜杠的目录，以下两种形式都会向 Codex 传递同一路径：

```json5 validate=false args: "app-server --listen stdio:// -c log_dir=/tmp/openclaw\logs"

```json5 validate=false
args: ["app-server", "--listen", "stdio://", "-c", "log_dir=/tmp/openclaw\\logs"]

JSON5 中的 \\ 编码一个反斜杠。数组项会保留嵌入的引号 和反斜杠，但会修剪周围空白并省略空项。字符串也会省略空引号参数。在将现有字符串转换为数组之前，请考虑这些限制。

appServer.serviceTier 仅在未提供共享 Fast 模式运行控制时使用。在 Codex harness 轮次中，共享 Fast 开启会发送 priority，Fast 关闭会发送 null 以清除 OpenClaw 拥有的层级，而 auto 会为每次模型调用做出决定。/codex fast off 是独立的：它会在绑定的原生会话偏好中持久化 flex，用于后续绑定到会话的轮次，并且不会更改共享的 OpenClaw 会话策略。这些值描述的是原生配置和偏好状态，而不是观察到的提供商路由。

Set appServer.enableUltrafast: true 以对受支持的模型优先使用 Ultrafast。 OpenClaw 会在请求 ultrafast 之前，通过实际回合的 Codex app-server 连接检查所选模型的 serviceTiers。无访问权限的模型、 自定义模型提供商以及不可用的目录将保留现有层级。 该设置不会更改 appServer.serviceTier 或共享 Fast 模式策略： Fast 关闭和非活动 auto 保持关闭，而活动 auto 可以使用 Ultrafast。 在没有共享 Fast 控制或显式层级的情况下，启用的 Ultrafast 仅适用于 声明支持的模型。禁用该设置会恢复正常的层级选择。

appServer.networkProxy 是显式的，因为它会更改 Codex 沙箱 契约。启用时，OpenClaw 还会在 Codex 线程配置中设置 features.network_proxy.enabled 和 default_permissions，以便生成的权限 配置文件能够启动 Codex 管理的网络。OpenClaw 默认会根据 配置文件主体生成抗冲突的 openclaw-network-<fingerprint> 配置文件名称；仅在需要稳定的本地名称时 使用 profileName。

{
  plugins: {
    entries: {
      codex: {
        config: {
          appServer: {
            approvalPolicy: "never",
            sandbox: "workspace-write",
            networkProxy: {
              enabled: true,
              domains: {
                "api.openai.com": "allow",
                "blocked.example.com": "deny",
              },
            },
          },
        },
      },
    },
  },
}

未出现在有效原生允许列表中的主机将被拒绝。示例中的 approvalPolicy: "never" 可防止基于批准的例外；原生系统 要求仍可提供允许的主机名。这些限制适用于 Codex 沙箱命令。有关匹配、策略继承、范围以及在更新后对空白可选字段进行显式 Doctor 修复，请参阅 网络代理配置参考。

如果正常的 app-server 运行时本应为 danger-full-access，启用 networkProxy 会为生成的权限 配置文件改用工作区式文件系统访问。Codex 管理的网络强制是沙箱化 网络，因此完全访问配置文件无法保护出站流量。

该插件管理稳定的 Codex app-server 0.158.0。显式自定义 可执行文件、远程 app-server 和 macOS 桌面二进制文件必须报告可 解析的语义化版本，且为 0.149.0 或更高版本。较旧、格式错误和 无版本的手shake将被拒绝。较新版本会记录兼容性警告 并继续通过正常的运行时和能力验证。

OpenClaw 将非回环 WebSocket app-server URL 视为远程，并要求 通过 appServer.authToken 或 Authorization 头进行携带身份的 WebSocket 身份验证。appServer.authToken 和每个 appServer.headers.* 值都可以是 SecretInput；secrets 运行时会在 OpenClaw 构建 app-server 启动选项之前解析 SecretRefs 和 env 简写，未解析的结构化 SecretRefs 会在发送任何 token 或头之前失败。

当配置了原生 Codex 插件时，OpenClaw 会缓存一个 运行时和工作区范围的 plugin/installed 快照。该快照涵盖 从 Codex 发现的市场中安装的插件，包括已禁用的所有权； plugin/read 仅解析精确配置的插件标识。失败或 不完整的已安装快照永远不会被缓存。/codex plugins available 会为当前对话工作区查询 plugin/list，而 /codex plugins install <plugin>@<marketplace> 只有在所有者或 operator.admin 明确授权该插件后才会安装。现有显式 配置的精选插件保留其自动恢复路径。模型的 插件发现工具无法安装、启用或身份验证插件。

app/installed 报告已安装应用的运行时状态，app/read 每次调用最多返回所请求的 100 个应用 ID 的已认证元数据。OpenClaw 会强制刷新第一个冷已安装快照，并将成功的 精选安装合并为一次应用清单刷新。后续缓存读取不会 强制重复连接器刷新。

默认拒绝的 Codex 应用策略按线程评估，因此显式 允许的应用可以在其可调用之前被安装和身份验证。 OpenClaw 仅临时允许所有权已证明且策略已批准的应用， 使用 _default.enabled = false 和显式应用覆盖创建线程， 然后使用该线程 ID 和 forceRefresh: false 调用一次 app/installed。 如果该快照报告缺失、已禁用或不可调用的应用，OpenClaw 会记录 一条警告，并继续使用其余工具。Codex 仍会强制执行 托管限制、工作区策略以及应用/工具权限；不可用的 应用不会获得任何访问权限。

该检查在 OpenClaw 注入历史、启动回合或 持久化原生线程绑定之前完成。如果快照请求失败，OpenClaw 会使用 thread/delete 删除持久临时 线程，或使用 thread/unsubscribe 取消订阅临时线程。 如果无法确认安全清理，它会退役所属 app-server 连接。受监督分支也会清理其临时 探测，并在清理失败时保留恢复状态。

在 allow_all_plugins 下，显式禁用的已配置工作区插件 仍会拒绝其拥有的应用。当 app/read 未公开该所有权时， OpenClaw 会使用其 plugin/installed 快照，并仅读取精确 配置的插件详情，以保留被拒绝的应用 ID。它不会扫描 无关市场，也不会安装、启用或身份验证已禁用的插件； 缺失所有权会失败关闭。

仅将 OpenClaw 连接到受信任的 0.149.0 或更高版本的远程 app-server，该服务器可接受 已配置市场插件安装和清单刷新。缺少现代 清单方法以及服务器、身份验证或传输故障都会失败关闭。

环境覆盖¶

环境覆盖仍可用于本地测试：

• OPENCLAW_CODEX_APP_SERVER_BIN
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

OPENCLAW_CODEX_APP_SERVER_BIN 在 appServer.command 未设置时绕过受管二进制文件。

OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 已在 2026.4.22 中移除。请改用 plugins.entries.codex.config.appServer.mode: "guardian"，或 OPENCLAW_CODEX_APP_SERVER_MODE=guardian 用于一次性本地测试。对于可重复部署，建议优先使用配置，因为它会将插件行为与 Codex harness 设置的其他部分保留在同一份经过审查的文件中。