跳转至

App-server 策略

OpenClaw 如何启动并认证 Codex app-server，以及它从操作员环境中隔离了哪些内容。属于 Codex harness 指南的一部分；每个章节迁移到了哪里 列出了所有章节。

App-server 策略

默认情况下，插件会在本地以 stdio 传输方式启动 OpenClaw 托管的 Codex 二进制文件。只有当有意运行不同的可执行文件时，才设置 appServer.command。经过验证的配置接受原生 Codex 可执行文件或官方 @openai/codex npm 入口点，包括其已安装的符号链接或 Windows npm 启动器。任意包装脚本无法验证，因为其原生目标未知；请改为选择原生可执行文件或官方 npm 启动器。app-server proxy 也无法提供经过验证的配置，因为其本地可执行文件只是将请求转发到单独的守护进程。Codex 将 WebSocket 传输归类为实验性且不受支持；仅在对已在其他地方运行的 app-server 进行非生产测试时使用它：

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

Ask OpenClaw 可以通过显式配置的 WebSocket 或 Unix socket app-server 验证已配置的模型。初始 Codex 设置和登录流程仍需要本地 stdio；请先在远程主机上完成登录并配置远程端点，然后再使用此验证路径。远程验证会绑定所选端点、连接凭据和已初始化的 Codex 身份。它信任该已配置服务；它不会证明远程可执行文件的字节。OpenClaw 在重用前会重新检查连接选择，并在启动线程前比较新连接上的已初始化身份。端点、凭据、版本或报告的 Codex home/platform 变化都需要新的推理验证。模型、认证、托管要求和工具策略检查仍然适用。

WebSocket 传输会在网关启动时主动建立 app-server 连接，并将打开握手限制为 10 秒。空闲连接每 20 秒发送一次 WebSocket ping，并为其对应的 pong 允许 20 秒。健康的 app-server 消息或 pong 会重置错过的心跳计数；连续五次错过 pong 会关闭连接。瞬时故障会自动重连，采用有界、带抖动的指数退避。认证失败和不受支持的 app-server 版本会停止重连，并报告需要操作员操作。Ping 和 pong 帧是传输层健康检查：它们不会启动 Codex 轮次或调用模型。本地 stdio 和 Unix 传输不会执行这些远程连接检查。

当调用方在远程替换期间需要连接时，获取过程会在调用方的超时和取消范围内进行最多三次连接尝试。这只适用于 WebSocket 从未打开的情况，因此没有缓冲的初始化帧到达服务器。认证和证书错误会立即失败。已打开连接上的请求（包括模型轮次和工具执行）不会由此恢复机制重放。

WebSocket 和 Unix socket 关闭会在连接关闭时完成，包括服务器先断开连接的情况。如果对端无法完成关闭握手，OpenClaw 会在关闭截止时间终止其 socket。连接关闭并不能证明远程 app-server 上的工作已停止。

本地 stdio app-server 会话默认采用受信任的本地操作员姿态：approvalPolicy: "never"、approvalsReviewer: "user" 和 sandbox: "danger-full-access"。如果本地 Codex 要求不允许这种隐式 YOLO 姿态，OpenClaw 会改为选择允许的 guardian 权限。当 OpenClaw 沙箱对该会话处于活动状态时，OpenClaw 会禁用该轮次的 Codex 原生 Code Mode、用户 MCP 服务器和基于应用的插件执行，而不是依赖 Codex 主机端沙箱。当正常的 exec/process 工具可用时，Shell 访问会改为通过 OpenClaw 沙箱支持的动态工具（例如 sandbox_exec 和 sandbox_process）进行。

对于 Codex 原生自动审查，在允许沙箱逃逸或额外权限之前，请使用规范化 OpenClaw exec 模式：

{
  tools: {
    exec: {
      mode: "auto",
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

对于 Codex app-server 会话，tools.exec.mode: "auto" 映射到 Codex Guardian 审查的审批：通常当本地要求允许这些值时，为 approvalPolicy: "on-request"、approvalsReviewer: "auto_review" 和 sandbox: "workspace-write"。在 tools.exec.mode: "auto" 中，OpenClaw 不会保留旧的不安全 Codex approvalPolicy: "never" 或 sandbox: "danger-full-access" 覆盖；如有意采用无审批 Codex 姿态，请使用 tools.exec.mode: "full"。旧的 plugins.entries.codex.config.appServer.mode: "guardian" 预设仍然有效，但 tools.exec.mode: "auto" 是规范化 OpenClaw 界面。

如需了解与主机 exec 审批和 ACPX 权限的模式级比较，请参阅 权限模式。如需了解每个 app-server 字段、认证顺序、环境隔离和超时行为，请参阅 Codex harness 参考。

原生审批审计证据

在 tools.exec.mode: "ask" 和 Codex 用户审查者下，原生命令和文件提示会使用 OpenClaw 的两阶段操作员审批路径。提示仅显示原生请求能够保留的决策。只有单次原生决策的命令会提供允许一次和拒绝；字节绑定的脚本审批也保持单次。文件提示支持单次和会话审批。对于命令，当 Codex 提供时，始终允许会使用会话信任。否则，当提示能够显示确切的命令前缀或网络主机及其跨未来会话的范围时，它可以请求一个持久的原生允许规则。Codex 负责应用和保存该规则；审批事件报告的是请求的修订，而不是确认其已保存。自动命令和文件审批保持单次，并且从不选择持久策略修订。

如果另一个已连接的 Codex 客户端响应了某个原生审批请求，OpenClaw 会关闭匹配的待处理提示，而不会发送第二次答复，也不会将该解决视为超时或工具失败。

终端操作员决策会复用 Gateway 的权威审批记录及其精确的执行绑定。当启用执行身份收集时，使用 openclaw audit --run <run-id> --explain 检查已接受的运行。生成的回执可以报告 allow-once、allow-always、denial、no-route、expiry 或 cancellation，而不会暴露命令文本、补丁内容、路径或原生请求 ID。

Codex 自动审查、完全访问策略以及原生钩子或 OpenClaw 策略决策不会创建操作员审批记录。缺失或过期的原生轮次上下文会在路由前被拒绝。因此，这些情况不会产生强制执行的操作员审批回执；审计检查不会从后续工具事件中重建这样的回执。

认证顺序

在默认的每个 agent 主目录中，认证按以下顺序选择：

  1. 该 agent 的有序 OpenAI 认证配置文件，最好位于 auth.order.openai 下。运行 openclaw doctor --fix 以迁移旧版 Codex 认证配置文件 ID 和旧版 Codex 认证顺序。
  2. 该 agent 的 Codex 主目录中 app-server 的现有账户。
  3. 仅对于本地 stdio app-server 启动，当不存在 app-server 账户且仍需要 OpenAI 认证时，先使用 CODEX_API_KEY，然后使用 OPENAI_API_KEY。

当 OpenClaw 看到 ChatGPT 订阅类型的 Codex 认证配置文件时，它会从生成的 Codex 子进程中移除 CODEX_API_KEY 和 OPENAI_API_KEY。这样可以保持 Gateway 级别的 API 密钥可用于嵌入或直接 OpenAI 模型，同时避免原生 Codex app-server 轮次意外通过 API 计费。显式的 Codex API 密钥配置文件和本地 stdio 环境变量密钥回退会使用 app-server 登录，而不是继承的子进程环境变量。WebSocket app-server 连接不会获得 Gateway 环境变量 API 密钥回退；请使用显式认证配置文件或远程 app-server 自身的账户。

如果订阅配置文件遇到 Codex 使用限制，OpenClaw 会在 Codex 报告重置时间时记录该时间，并为同一 Codex 运行尝试下一个有序认证配置文件。当重置时间过去后，订阅配置文件会重新变得可用，而不会更改所选的 openai/gpt-* 模型或 Codex 运行时。

当 Codex 报告普通使用量为可用或未知时，耗尽的使用百分比不会使模型进入冷却。已知的耗尽配额仍可提供计划重置提示；该提示不保证恢复可用。特定功能的重置与普通账户权限保持分离。

当配置了原生 Codex 插件时，OpenClaw 会读取并缓存一个运行时和工作区范围的 plugin/installed 快照。该快照覆盖从 Codex 发现的市场中配置的插件，包括已禁用插件的所有权。plugin/read 仅解析显式配置的插件详情。/codex plugins available 使用绑定的工作区查询 plugin/list，而 /codex plugins install <plugin>@<marketplace> 是所有者或管理员授权的安装路径。常规线程设置保留现有显式配置的精选插件恢复。

app/installed 提供已安装应用运行时快照，app/read 以最多 100 个应用 ID 的批次提供经过身份验证的应用元数据。OpenClaw 会强制刷新一次冷快照，并将成功的精选安装合并为一次应用清单刷新。普通缓存读取不会为每个线程强制刷新连接器。

由于 Codex 尚未应用目标线程的限制性应用配置，已授权的应用最初可能显示为已禁用或不可调用。OpenClaw 暂时仅接受显式允许且所有权已证明的应用，以 _default.enabled = false 启动线程，并使用该线程的 ID 和 forceRefresh: false 读取一次 app/installed。缺失、已禁用或不可调用的应用会产生一条警告，而不会阻塞无关的聊天或心跳运行。Codex 仍会执行应用/工具权限、托管限制和工作区策略；继续对话不会启用不可用的应用。

该检查在 OpenClaw 启动轮次或提交线程绑定之前运行。如果快照请求失败，持久性临时线程会被删除，短暂线程会被取消订阅。如果无法确认清理，OpenClaw 会关闭 app-server 连接，而不是复用不安全的线程。

账户范围的应用访问权限永远不会覆盖显式禁用的已配置工作区插件。当 app/read 省略该插件的所有权时，OpenClaw 会使用 plugin/installed 快照，并仅读取确切配置的插件详情，以保持其应用被拒绝。此检查永远不会安装、启用或认证该插件。

OpenClaw 不会安装未知应用，也不会让模型授权新的插件安装。经所有者批准的插件安装会刷新目标运行时清单。缺失的清单方法、认证错误、传输失败和连接器刷新失败都会失败关闭。

计划应用权限

当 Codex 创建者轮次捕获计划应用权限时，没有显式 toolsAllow 列表的自动化会保存该轮次可调用的工具和应用程序策略。使用准备好的 ChatGPT 配置文件时，计划应用访问权限仍绑定到该确切配置文件和账户。没有准备好的配置文件时，agent 范围的已配置 WebSocket app-server 通过其连接指纹拥有该计划。将同一端点重新认证到另一个账户不会撤销计划：后续运行使用该端点的当前账户，受捕获的应用上限和当前应用/工具策略约束。计划权限不会存储或重放认证凭据。

计划应用审批上限会保留原生工具覆盖以及每个工具所识别账户的审批策略。对于在调用时选择账户的工具，共享工具上限会使用已配置账户和默认策略的最严格组合。即使一个账户自动允许该操作，此类工具也可能跨账户要求审批。

移除或取消配置端点、更改其连接指纹，或更改其捕获的托管需求，会在应用执行前拒绝运行。该任务仍可检查，自动化运行历史及其上次运行状态中会显示错误；正常的失败退避仍然适用。请恢复已授权的连接，或从新的、已认证的所有者回合重新创建自动化。账户变更导致对已捕获应用的访问被移除时，也会以可见方式失败。

在回滚到没有配置端点权威和 cron 权威水合的构建之前，请使用 openclaw automations disable <id> 禁用这些任务，并使用 openclaw automations list --all 验证它们。不要依赖旧版二进制文件来强制执行新的权威封装。在返回支持该功能的构建或在该构建支持的认证路径下重新创建任务之前，请保持这些任务处于禁用状态。有关运行历史和失败处理，请参阅自动化。

环境隔离

对于本地 stdio 应用服务器启动，OpenClaw 会将 CODEX_HOME 设置为每个代理（agent）的目录，这样 Codex 配置、认证/账户文件、插件缓存/数据以及原生线程状态默认不会读取或写入操作者的个人 ~/.codex。OpenClaw 保留正常的进程 HOME；由 Codex 运行的子进程仍然可以找到用户主目录下的配置和令牌，并且 Codex 可能会发现共享的 $HOME/.agents/skills 和 $HOME/.agents/plugins/marketplace.json 条目。使用 appServer.homeScope: "user" 时，OpenClaw 改为使用原生用户 Codex 主目录及其现有账户，而不会注入 OpenClaw 身份验证配置文件。在用户主目录的 stdio 或 Unix 连接上，标准的 openai/* 对话也会保留原生配置的模型提供者；请使用标准的 OpenClaw 模型引用选择模型。显式的非 OpenAI 提供者仍保持显式。准备好的路由兼容性以及订阅/API 密钥账户检查仍然适用。

如果部署需要额外的环境隔离，请将这些变量添加到 appServer.clearEnv：

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
          },
        },
      },
    },
  },
}

appServer.clearEnv 仅影响生成的 Codex 应用服务器子进程。在本地启动规范化期间，OpenClaw 会从该列表中移除 CODEX_HOME 和 HOME：CODEX_HOME 继续指向所选的代理或用户作用域，HOME 保持继承，以便子进程可以使用正常的用户主目录状态。

经过验证的本地设置回合也会验证所选的 Codex 启动器和软件包。继承的 NODE_OPTIONS 可能包含受限资源、警告、DNS 结果排序、网络族自动选择、环境代理和 CA 来源等选项，因为这些设置无法预加载代码或改变模块解析。例如，允许使用 --dns-result-order=ipv4first --no-network-family-autoselection。格式错误或未知的选项以及诸如 --require 或 --import 之类的代码加载选项会安全失败。如果某个继承选项不是 Codex 所需要的，请使用 appServer.clearEnv 移除 NODE_OPTIONS。

本地测试环境变量覆盖

  • 当 appServer.command 未设置时，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_GUARDIAN=1 已在 2026.4.22 中移除。请改用 plugins.entries.codex.config.appServer.mode: "guardian"，或使用 OPENCLAW_CODEX_APP_SERVER_MODE=guardian 进行一次性本地测试。对于可重复的部署，推荐使用配置，因为它能将插件行为与其余 Codex harness 设置保存在同一个经过审查的文件中。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw