App-server 传输
OpenClaw 如何启动并连接 Codex 应用服务器,以及每一个 appServer 字段。本文是 Codex harness 参考 的一部分;各章节移往何处 列出了所有章节。
应用服务器传输¶
对于普通 harness 回合,OpenClaw 会启动随官方插件一起提供的受管 Codex 二进制文件(当前为 @openai/codex 0.160.0):
这样可将应用服务器版本与官方 codex 插件绑定,而不是与本地恰好安装的独立 Codex CLI 绑定。OpenClaw 使用 Node 包解析,从加载器选定的插件根目录解析 @openai/codex/bin/codex.js,包括 npm 提升和 pnpm 链接的依赖。它不会为受管启动搜索 .bin shim 或全局 PATH。在 Windows 上,Node 运行相同的包入口点,无需 codex.cmd shim。仅当你确实想要使用不同的可执行文件时,才设置 appServer.command。
默认隔离的 agent 主目录下的普通受管回合会优先使用这个固定版本的包,即使已安装 macOS 桌面应用包也是如此。当启用 Computer Use,或当 homeScope 为 "user" 且可加载原生 Computer Use 状态时,受管启动会改而优先选择拥有所需 macOS 权限的桌面应用二进制文件。当隔离 agent 主目录中的有效 Codex 配置启用了原生 Computer Use 时,同样适用桌面优先规则。如果未安装桌面应用包,OpenClaw 会回退到固定版本的包二进制文件。
在切换暂存的 OpenClaw 包之前,请针对候选安装运行选择加入的受管二进制检查:
该检查是只读的。对于每个配置的 Codex agent,它会应用与实时 harness 回合相同的最终命令选择,然后验证所选包自带的原生二进制文件是否存在,并报告该插件精确固定的版本。所选 Codex Desktop 二进制文件、显式自定义命令和远程应用服务器不在此包检查范围内。该命令在发现错误级问题时以非零状态退出,因此部署人员可以在切换前拒绝该候选版本,而无需更改 Codex 状态或应用服务器设置。
可执行文件交接和原生配置隔离用于协调单个运行中的 Gateway 进程内的客户端。当另一个进程更改原生 Codex 插件配置后,请重启 Gateway。
Supervision 使用一个独立的连接。如果没有显式的 appServer 连接设置,它会使用 homeScope: "user" 的受管 stdio;普通 harness 仍使用 homeScope: "agent" 的受管 stdio。两条路径都会遵循显式连接设置。当普通 harness 需要与原生客户端共享 $CODEX_HOME(或 ~/.codex)时,请显式设置 homeScope: "user"。无论普通 harness 的默认设置如何,私有受监督绑定都会使用监督连接。独立的 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 字段:
| 字段 | 默认值 | 含义 |
|---|---|---|
transport |
"stdio" |
"stdio" 会生成 Codex;显式 "unix" 连接到本地控制套接字;"websocket" 连接到 url。 |
homeScope |
"agent" |
"agent" 按 OpenClaw agent 隔离普通 harness 状态。"user" 是显式选择加入,共享原生 $CODEX_HOME 或 ~/.codex,使用原生身份验证,并启用仅限所有者的线程管理。用户范围支持本地 stdio 或 Unix 传输。对于单独的监督连接,未设置的值在 stdio 或 Unix 下解析为 "user",在 WebSocket 下解析为 "agent"。 |
command |
受管 Codex 二进制文件 | stdio 传输使用的可执行文件。留空以使用受管二进制文件。 |
| 字段 | 默认值 | 含义 |
|---|---|---|
args |
["app-server", "--listen", "stdio://"] |
stdio 传输的参数。 |
url |
未设置 | WebSocket App Server URL 或 unix:// URL。显式空 Unix 路径会选择规范的用户主目录控制套接字。 |
authToken |
未设置 | WebSocket 传输的 Bearer token。接受字面字符串或 SecretInput,例如 ${CODEX_APP_SERVER_TOKEN}。 |
headers |
{} |
额外的 WebSocket 请求头。请求头值接受字面字符串或 SecretInput 值,例如 x-codex-client-session-token: "${CODEX_CLIENT_SESSION_TOKEN}"。 |
clearEnv |
[] |
在 OpenClaw 构建其继承环境后,从生成的 stdio app-server 进程中移除的额外环境变量名称。 |
remoteWorkspaceRoot |
未设置 | 远程 Codex app-server 工作区根目录。OpenClaw 将本地 cwd 映射到该根目录,并通过一个输出受限、无 shell 的 command/exec 读取器传输权威的远程附件。逃逸任一工作区的路径、符号链接、超大文件以及无限制的附件批次均会失败关闭;上传保留已配置的通道身份和 app-server 请求超时。 |
loopDetectionPreToolUseRelay |
true |
当 OpenClaw 循环检测启用时,启用 Codex PreToolUse 中继以进行循环检测。当没有工具前插件钩子、可信工具策略或已启用的循环检测器具有本地工作时,OpenClaw 不安装 PreToolUse 中继。设置 false 可在检测启用时禁用循环检测中继;工具前插件钩子和可信工具策略仍会安装其所需的失败关闭中继。 |
requestTimeoutMs |
60000 |
app-server 控制平面调用的超时时间。 |
mode |
"yolo",除非本地 Codex 要求不允许 YOLO |
YOLO 或 guardian 审核执行的预设。 |
| 字段 | 默认值 | 含义 |
|---|---|---|
approvalPolicy |
"never" 或允许的 guardian 审批策略 |
发送到线程启动、恢复和回合的原生 Codex 审批策略。 |
sandbox |
"danger-full-access" 或允许的 guardian 沙箱 |
发送到线程启动和恢复的原生 Codex 沙箱模式。活动的 OpenClaw 沙箱会将 danger-full-access 回合收窄为 Codex workspace-write;回合网络标志遵循 OpenClaw 沙箱出站。 |
approvalsReviewer |
"user" 或允许的 guardian 审查者 |
使用 "auto_review" 可在允许时让 Codex 审查原生审批提示。 |
defaultWorkspaceDir |
当前进程目录 | 当省略 --cwd 时,/codex bind 使用的工作区。 |
serviceTier |
未设置 | 当未提供共享 Fast 模式控制时,原生 app-server 的偏好设置。非空字符串会直接透传;文档中记载的值为 "priority" 和 "flex"。旧版 "fast" 会规范化为 "priority",null 会清除覆盖。原生 "ultrafast" 从 priority 开始,并要求显式的共享 Ultrafast 选择。共享 Fast 发送 priority,关闭时发送 null,Auto 则按每次调用决定。这不会配置直接内嵌的 OpenAI 请求。 |
enableUltrafast |
true |
仅当显式选择共享 "ultrafast" 且存在已通告的原生模型时,才允许 ultrafast。未设置或 true 允许该选择;false 会在 Codex 选择器中隐藏 Ultrafast,对显式选择发送普通 Fast(priority),并跳过 Ultrafast 目录检查。Fast、Auto 和未指定的选择永远不会自动升级。不受支持的模型和不可用的目录会保持基线层级。 |
networkProxy |
禁用 | 为 app-server 命令选择加入 Codex 权限配置文件网络。OpenClaw 会定义所选的 permissions.<profile>.network 配置,并使用 default_permissions 选择它,而不是发送 sandbox。 |
experimental.sandboxExecServer |
false |
预览选择加入项,用于将 OpenClaw 沙箱支持的 Codex 环境注册到受支持的 Codex app-server,使原生 Codex 执行可以在活动的 OpenClaw 沙箱内运行。 |
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 会话策略。这些值描述的是原生配置和偏好状态,而不是观察到的提供商路由。
Ultrafast 要求生效的共享 Fast 模式选择为 "ultrafast"。在 Control UI 中选择它,使用 /fast ultrafast,在会话或运行控制中提供 fastMode: "ultrafast",或在配置中编写 fastModeDefault: "ultrafast"。未设置 appServer.enableUltrafast 或为 true 时,允许这种显式选择。设置 appServer.enableUltrafast: false 以在 Codex 运行时的选择器中隐藏 Ultrafast。即使保存或显式选择了 Ultrafast,也会发送普通 Fast(priority)并跳过 Ultrafast 目录检查。
只有开关启用时的显式 Ultrafast 选择,才会通过该轮次已认证的 Codex app-server 连接检查所选原生模型的 serviceTiers。目录未宣传该层级的模型、自定义模型提供商以及不可用的目录都会回退到 Fast(priority)。原生目录可能包含离线回退元数据,因此该轮次检查不会确立账户权限。Control UI 在显示 Ultrafast 之前需要单独的已认证账户发现证据。保存的偏好并不保证请求会获得被认可的上游层级。
Fast(true)、激活的 Auto 以及未指定的共享运行控制永远不会自动升级或执行 Ultrafast 目录查找。它们保持基线层级(Fast 或激活的 Auto 为 priority);原生 serviceTier: "ultrafast" 也将从 priority 开始,直到共享选择显式请求 Ultrafast。Standard(false)和非激活的 Auto 保持关闭。
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.160.0。显式自定义可执行文件、远程 app-server 和 macOS 桌面二进制文件必须报告可解析的语义化版本,且为 0.149.0 或更高版本。较旧、格式错误和无版本的握手会被拒绝。较新版本会记录兼容性警告,并继续通过常规运行时和能力验证。
OpenClaw 将非回环 WebSocket app-server URL 视为远程,并要求通过 appServer.authToken 或 Authorization 头进行携带身份的 WebSocket 认证。appServer.authToken 和每个 appServer.headers.* 值都可以是 SecretInput;secrets 运行时会在 OpenClaw 构建 app-server 启动选项之前解析 SecretRefs 和 env 简写,未解析的结构化 SecretRefs 会在发送任何 token 或 header 之前失败。
当配置了原生 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 和显式应用覆盖的线程,然后仅调用一次 app/installed,传入该线程的 ID 和 forceRefresh: false。
如果该快照报告缺失、已禁用或不可调用的应用,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,且该 app-server 必须可信,能够接受已配置市场插件的安装和清单刷新。缺失的现代清单方法以及服务器、身份验证或传输故障都会失败关闭。
环境覆盖¶
环境覆盖仍可用于本地测试:
OPENCLAW_CODEX_APP_SERVER_BINOPENCLAW_CODEX_APP_SERVER_ARGSOPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardianOPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICYOPENCLAW_CODEX_APP_SERVER_SANDBOX
当 appServer.command 未设置时,OPENCLAW_CODEX_APP_SERVER_BIN 会绕过托管二进制文件。
OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 已在 2026.4.22 中移除。请改用 plugins.entries.codex.config.appServer.mode: "guardian",或对于一次性本地测试使用 OPENCLAW_CODEX_APP_SERVER_MODE=guardian。对于可重复部署,优先使用配置,因为它会将插件行为保留在与其余 Codex 测试框架设置相同的已审查文件中。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw