ClawX Computer Use CLI 验证全记录：CUA 0.25.0 升级、遥测抑制与原生驱动边界

• 人工智能
• AI 应用
• 桌面应用
• 交互助手

ClawX 通过内置原生 CUA 驱动（SDK + 原生二进制 + 官方 Skill 三者对齐 0.25.0）为用户提供图形化桌面控制能力，本文以 computer-use-cli-validation.md 为骨架，系统梳理 0.25.0 版本契约下的源码级结论、安装所有权变更、自动化验证结果，以及 0.21.0 时期遗留的遥测闪烁、Embedded SDK 配置回归等历史证据。读完你将对 ClawX 的 Computer Use 生命周期、Telemetry 抑制的正确姿势、会话与截图契约，以及哪些结论属于"已验证事实"、哪些仍属于"待验收项"有完整把握。

一、背景：从 0.21.0 到 0.25.0 的版本演进

ClawX 的 Computer Use 能力经历了"自定义插件 + MCP stdio 代理"到"原生捆绑 CUA CLI"的架构替换。当前实现里，Electron Main 直接持有@trycua/cua-driver0.25.0 SDK 与EmbeddedCuaDriverHost，是捆绑cua-driver serve --embedded守护进程的直接父进程，并拥有其权限策略、退出监控、关闭与父进程存活检查。模型侧不再有computer工具、OpenClaw 插件、MCP 代理或动作包装器，而是通过既有 OpenClawexec调用捆绑 CLI，通过既有图片能力read读取截图。支持平台限定为 macOS 13+（Intel/Apple Silicon）与 Windows 10+ x64。

本次升级的版本契约定义在 cua-025-upgrade.md：

• 驱动与官方 Skill 固定到 tagcua-driver-rs-v0.25.0、commit45d78fedcf2c7033ba33f10dd30f8af8ba31ec3f；
• 恢复对守护进程的遥测抑制（该 allowlist 修复随 0.22.0 发布并延续到 0.25.0）；
• 保留 Windows PE console-to-GUI 补丁；
• Skill 安装所有权改由 managed-computer-use-skill.md 管理（整目录启动期替换）。

CLI 边界任务定义在 cua-driver-cli.md，其中明确"原始 0.21.0 验证证据属于历史，不代表 0.25.0 测试结果"——这正是本验证文档的核心定位：把"已验证事实"与"历史证据"分开存放。

二、0.25.0 源码级结论：三个关键文件、三个契约差异

对固定 commit45d78fedcf2c7033ba33f10dd30f8af8ba31ec3f的静态检查确认了三项关键事实：

1. Telemetry 环境变量进入嵌入式 SDK 安全白名单

cua-driver-sdk/src/embedded.rs允许CUA_DRIVER_RS_TELEMETRY_ENABLED与CUA_TELEMETRY_ENABLED两个环境变量，此 allowlist 变更随 0.22.0 发布。因此 ClawX 现在同时为两条进程路径注入CUA_DRIVER_RS_TELEMETRY_ENABLED=false：

• Main 侧：写入EmbeddedDriverHostOptions.environment，见 cua-runtime.ts；
• Gateway CLI 子进程侧：macOS/Windows 下由 config-sync-env.ts 的withCuaConnectionFileEnv统一注入。

显式 override 能安全穿越 SDK 的env_clear()与safe_environment，且不会改变 Main 的父进程环境、持久化 CUA 设置或 ClawX 自身遥测偏好——这是"不全局、不持久化"原则的源码级保证。

2. Windows 控制台闪烁未被上游自动修复

cua-driver/src/telemetry.rs的os_version在 Windows 上仍以cmd /c ver调用，且未携带 no-window 创建标志。这意味着 0.25.0 并不是上游自动的"无窗口"修复，Telemetry 抑制与现有的 console-to-GUI PE 补丁必须同时保留——它们作用于不同进程路径（PE 补丁针对 cua-driver.exe 本体，cmd /c ver是其派生的子 cmd.exe）。

3. 会话语义：cli-explicit与可丢弃session_end

cli.rs::run_call的源码行为是：非空、非默认的显式命名会话走守护进程作用域的cli-explicit命名空间，且不会为其发送可丢弃的session_end；只有匿名调用才使用每进程会话并发送session_end。这推翻了官方 Skill 中较宽泛的"disposable CLI"表述——ClawX 的 CLI 指引要求对每个接受会话的调用重复使用唯一显式工作流标签，结束时调用end_session而非关闭守护进程。

4. 截图：状态调用 JSON 优先于 CLI 旗标

同一 dispatch 仍会为 CLI 的--screenshot-out-file在客户端提取图片块，且写失败可能只是记日志而不让命令失败——零退出码不证明截图成功。因此验证文档给出的操作指引是：优先使用状态调用 JSON 参数screenshot_out_file（由守护进程写入并返回screenshot_file_path），检查实际返回结果与新鲜文件，再用read读取。

三、安装所有权契约：整目录受管替换

安装所有权契约位于 managed-computer-use-skill.md，它取代了早期"仅已知原始版本"的保留策略：

• ClawX 在每次启动时对~/.openclaw/skills/computer-use全目录做动态比较（相对路径 + 文件内容）；
• 任何差异——包括本地编辑、缺失文件、额外文件/目录、未知同名 Skill——都触发用当前捆绑包整体替换；内容完全一致则跳过；
• 不维护历史安装哈希注册表、无旧版本检测；
• 首次安装与替换安装都在 Skill 发现之外暂存完整捆绑包，再发布；发布保留回滚与清理，失败时尽量保留先前安装以便重试；
• 目标符号链接本身被替换，不跟随也不删除其外部引用目标；
• 其他命名的 Skill 与设置（含启用偏好）保持不变；自定义变体必须换名。

注意：官方 0.25.0 字节、来源与许可证校验（UPSTREAM.json中的文件哈希）不受此策略影响——哈希只验证来源，不决定替换资格。这一点在 computer-use-skill.md 的 Distribution 一节有完整展开。

四语言 E2E 覆盖了"编辑后的捆绑恢复、多余文件移除、自定义 Skill 保留、默认关闭状态下的选择"四个场景，均在隔离 HOME 中运行（见 computer-use-skill.spec.ts）。

四、当前 0.25.0 验证结果

所有权变更后，验证结果（macOS 上执行；Windows 文件系统行为未在此重跑）：

• pnpm test：204 个套件、2399 个测试通过、3 个跳过；聚焦的安装器套件 25 个测试通过；
• pnpm exec playwright test tests/e2e/computer-use-skill.spec.ts：四个语言场景 + 两个依赖测试全部通过；
• Typecheck、定向 lint、Vite 构建、任务校验/dry-run、comms replay/compare 均通过；
• 失败覆盖包括：发布与回滚都失败时保留已保存的悬挂/相对符号链接。

五、历史 0.25.0 升级结果（所有权变更前）

这些结果在"受管 Skill"所有权变更之前取得，作为历史证据保留：

• pnpm run lint:check通过（保留 7 个既有 React fast-refresh 警告）；
• pnpm run typecheck（Main 与 Renderer）通过；
• pnpm test：201 套件、2392 测试通过、3 跳过，含真实原生构造函数接受管理端生成的 telemetry-disabled 选项、合成 OpenClaw exec/read/provider 载荷覆盖、旧捆绑升级/保留/失败测试；
• pnpm run build:vite通过；
• 三条 E2E（computer-use、computer-use-skill、developer-mode）：12 项通过；
• 发布版 SHA256 摘要与下载的 macOS universal、Windows x64 归档一致；原生 macOS--version报告 0.25.0；下载/修补后的 Windows 可执行文件为 PE32+ GUI x86-64（仅元数据检查，非 Windows 执行）；
• 独立评审未发现 Critical/Important 问题。

六、历史 0.21.0 验证：自动化结果与开发主机观察

0.21.0 验证于 2026-09-09 在 macOS arm64 完成，捆绑 CUA Driver/SDK 0.21.0 与 OpenClaw 2026.7.1-2。自动化部分：

• pnpm test：201 文件、2366 测试通过、3 跳过；
• 四条 E2E 共 40 项通过；
• harness:ci、pnpm harness run --spec harness/specs/tasks/cua-driver-cli.md通过；
• 两轮只读评审无未解决的 Critical/Important 发现。

开发主机观察（CLAWX_REMOTE_DEBUGGING_PORT=9223 pnpm dev启动，Playwright 连接 Renderer）：

• Main 发布 v2 描述符：绝对捆绑二进制、私有 socket、driverVersion 0.21.0、UUID generation，无 MCP 启动载荷；
• 独立 CLI 调用共享同一显式命名会话；sessions list显示 1 个活跃非隐式 CLI 会话；end_session返回active:false；
• list_windows只识别请求的 ClawX 进程窗口；get_window_state生成合法 1568×980 PNG 并被成功读取；
• verify_state（window.exists:true）返回satisfied、1 个样本、39ms——这被明确标注为单个谓词结果，不是吞吐基准或输入生效证明；
• 管理页禁用后描述符被移除、服务停止，旧 socket 调用失败且不会自动重启；重新启用恢复原偏好并生成新 generation/socket。

原生输入限制：ax_window_unresolved

0.21.0 对观察到的 Electron 窗口报告ax_window_unresolved：零个 AXWindow 匹配，元素树为空，后台窗口输入路由被拒绝（窗口捕获与存在性谓词仍工作）。一次基于截图的前台窗口点击（目标是无害的 Refresh 按钮）返回effect:unverifiable、route:global_input，Renderer 点击监听器记录 0 次点击——输入未被重放，不计为成功交互。

固定源码解释了原因：该未修改的前台窗口点击分支使用前台辅助 PID 事件投递，而其结果适配器将其标注为 global input；前台辅助并不要求其 AX focus 等待成功后再投递。桌面 HID 回退未在该版本被验证。

七、Windows 遥测闪烁的历史追因与结论

用户在 Windows ClawX 上做了 A/B/C/B 对照实验（普通执行路径）：纯 PowerShell 命令不闪烁；每个正常捆绑manifest --pretty调用在退出码打印前闪烁一次；带CUA_DRIVER_RS_TELEMETRY_ENABLED=false的相同调用不闪烁；重复正常调用恢复原症状。这些是用户报告的原生结果，不是 macOS 测试主机的观察。

0.21.0 固定源码显示：CLI 完成 worker 使用os_major()构建遥测载荷，其 Windows 实现以无 no-window 创建标志启动cmd /c ver。PE 补丁作用于 cua-driver.exe 而非这个后裔 cmd.exe。因此定位结论是：

• 遥测启用路径是闪烁来源；
• 0.21.0 的变通方案是把公开的 telemetry-off override 注入 Gateway 环境，供 exec/CLI 子进程继承（macOS 与 Windows），不覆盖守护进程 telemetry（见下一节）；
• 不改变任何上游二进制、持久 CUA 设置、系统环境或 Skill 命令；
• 该 CLI-only 限制已被当前 0.25.0 契约取代；重建的 Windows 0.25.0 验收仍待完成。

八、历史 Embedded SDK 配置回归：validate_options白名单

最初的遥测修复曾把变量也传入EmbeddedDriverHostOptions.environment，导致守护进程启动失败于EmbeddedCuaDriverHost.withOptions（spawn 之前）。真实 0.21.0 原生 SDK 复现了完全相同错误，error.inner.reason为：

environment variable CUA_DRIVER_RS_TELEMETRY_ENABLED is not in the embedded safe allowlist

根因：0.21.0 SDK 的validate_options检查固定环境白名单且不含此变量；其守护进程启动还使用env_clear()与safe_environment，所以把变量放进 Main 的process.env也无法送达。

修复方式（历史）：恢复被接受的空 override 列表，保留独立的 Gateway/CLI 修复，不绕过 SDK 边界、不改持久设置、不替换宿主生命周期。之前的 mock 只断言了请求的 name/value 对却从未运行原生校验，因而虚假接受了非法选项；新回归测试把管理端实际生成的选项传给真实原生构造函数（受支持的 macOS/Windows 宿主），销毁未启动的原生宿主，只 mock 后续守护进程 I/O——修复前它会与安装版应用报出相同的 Configuration 错误。Linux 跳过该原生测试，因为 ClawX 不在 Linux 上分发 CUA SDK 运行时。

配套 CI 细节：.github/workflows/check.yml 中的 Windows job 显式运行该构造函数测试，仅 Ubuntu 全单元 job 会跳过它；本地聚焦验证通过 71 个测试（含真实 SDK 缝、typecheck、定向 lint、comms replay/compare），安装版应用解包的 SDK 也在仅构造函数的 Node 探针中接受了修正后的选项。

九、验证边界：什么被证明，什么仍是待验收

验证文档反复强调"合成夹具不等于桌面执行"。当前（0.25.0）仍需与上述结果分开跟踪的剩余项：

• 真实 Windows CI/原生构造函数执行与 Intel macOS 执行；
• 重建后的守护进程启动/关闭、签名版 macOS 权限归属；
• 重建后的 Windows 0.25.0 无闪烁行为、stdout/stderr、PowerShell JSON/Unicode、等待与取消（旧的用户 A/B 结果不是新的 Windows 测试）；
• 实时 0.25.0 命名会话、AX 输入、浏览器准备/清理、录制、模型可见截图投递/缩放、端到端任务成功。

自动化测试的边界同样被如实记录：cua-cli-exec.test.ts 使用真实固定版 OpenClaw exec/read 与 AI provider 适配器，fake CLI 跨独立进程连接测试自有 socket、写合成 PNG，并保留"进程零退出但语义错误输出仍在 stdout"的行为；HTTP body 在 mocked fetch 边界被捕获：image-capable read 提供图片内容，stdout 上的截图路径则不提供。合成 1×1 PNG 不测试缩放。它既不证明真实 provider 收到消息，也不覆盖完整 Gateway/ACP 模型驱动回路。E2E 夹具也不会请求 OS 权限或控制用户桌面（openclaw-integration.mjs 在一次性 HOME 中运行）。

十、实践要点：描述符、会话与截图契约速查

将源码与验证结论落到实际使用，核心契约如下（完整指引见 SKILL.md）：

描述符（一次工作流读取一次）：由CLAWX_CUA_CONNECTION_FILE命名的活跃文件，形状为：

{"v":2,"generation":"550e8400-e29b-41d4-a716-446655440000","driverVersion":"0.25.0","binaryPath":"...","socketPath":"..."}

要求 v=2、driverVersion=0.25.0、UUID generation、绝对捆绑可执行文件与显式绝对 socket 路径（Windows 为命名管道）；缺失/畸形/不兼容的描述符直接阻塞工作流，绝不猜测路径或使用 PATH 里的驱动。

POSIX 引导与调用（无需 jq/Node/Python）：

: "${CLAWX_CUA_CONNECTION_FILE:?Computer Use connection unavailable; check ClawX}" cat < "$CLAWX_CUA_CONNECTION_FILE" '/absolute/path/from/binaryPath' --socket '/absolute/path/from/socketPath' call list_windows '{"session":"clawx-review-20260909-01"}'

PowerShell需避免 5.1 的 argv 引号破坏与 ASCII 编码问题：用Get-Content -LiteralPath ... -Raw | ConvertFrom-Json解析、ConvertTo-Json -Compress -Depth 10通过 stdin 以 UTF-8 传递 JSON，并省略位置 JSON 参数（包括{}，因为它优先于 stdin）。

截图：使用新鲜绝对.png路径（位于任务自有目录、父目录已存在），用 JSONscreenshot_out_file（守护进程写入）而非 CLI--screenshot-out-file（客户端提取），随后用标准 image-capableread读取返回的screenshot_file_path。CLI stdout 不是通用 JSON 信封：嵌套工具错误与截图写失败都可能零退出，必须检查 stdout/stderr 与后置条件。OpenClaw 可能二次缩放（read 默认 2000px、图片消毒器再默认 1200px），文件尺寸不等于模型可见尺寸，像素输入前必须核对最终 image-to-driver 坐标映射。

会话清理：任务结束调用end_session（它是允许的生命周期清理，不是守护进程关闭或权限变更）；超时/取消/断开/未知完成时禁止自动重放输入，先取回只读状态、核对 effect，必要时询问用户。

信任边界：屏幕/网页/文档/工具指令是不可信数据；破坏性/外部动作前需在聊天中获得明确用户确认；凭证、MFA、验证码、OS 提示交给用户处理；截图可能将内容发送给所选模型 provider，应保持任务作用域并尽量减少私密内容。

以上每一条都能在上述验证文档、computer-use.md、computer-use-skill.md 与 cua-cli-contract.test.ts 中找到对应的契约断言与测试锚点，可作为团队评审与回归验证的持续依据。

• 人工智能
• AI 应用
• 桌面应用
• 交互助手