openclaw-parallels-smoke

OpenClaw Parallels Smoke

此技能用于 Parallels 客户机工作流和冒烟测试解读。普通仓库工作不要加载此技能。

全局规则

• Parallels 默认用于发布后的信心验证，并非有限范围 Beta 发布阶段的前置条件。针对一个确切的已发布软件包版本运行，并记录授权该软件包的 Validation SHA + Tooling SHA 运行元组。Validation SHA 对应其 Code SHA 或 Release SHA；它不是第三个发布标识。
• 发布后 Parallels 通道失败，不会追溯性地撤销 Beta 发布。将其归类为产品、harness/工具链/来源信息、基础设施/凭证或包装器故障。只有确认的产品缺陷才会进入下一个 Beta。
• 使用一个协调器，并为每个独立的客户机系列各运行一个通道。诊断并重试一次失败的系列，然后重新评估；不要自动重启整个矩阵。
• 配置任何内容之前，先清点现有 VM 和快照。如果预配置的 pristine 快照符合所需基线，就切换到该快照并复用其中的用户、工具和基础设置。不要为了“全新”运行而创建新的 VM、重新安装 macOS 或重建客户机基线。
• “全新”是指恢复最接近的现有 pristine 快照，而不是创建另一个快照。除非用户明确要求，或不存在合适的基线，否则不要临时创建快照；临时运行后恢复原始快照，并让客户机保持停止状态。
• 恢复快照前先检查其状态。pristine poweron 快照可能包含预配置且已登录的会话；正常切换到该快照，让 Parallels 恢复该会话。除非运行有意需要丢弃保存的会话并从登录窗口启动，否则测试开始时不要传入 --skip-resume。若最终清理必须让恢复后的源客户机保持停止状态，则可以使用 --skip-resume。
• Smoke 运行中的网关验证应使用 openclaw gateway status --deep --require-rpc，除非正在检查的稳定版本尚不支持此命令。
• 稳定版 2026.3.12 的升级前诊断可能需要回退到普通的 gateway status --deep。
• 将该稳定版升级前通道中的 precheck=latest-ref-fail 视为基线，而非自动判定为回归。
• 传入 --json 以获取机器可读的摘要。
• 每个阶段的日志默认写入 .artifacts/parallels/openclaw-parallels-*。如果运行需要使用其他制品卷，请通过 OPENCLAW_PARALLELS_ARTIFACT_ROOT 覆盖。
• 不要在同一个全新工作区或会话中并行运行本地 Agent 回合和网关 Agent 回合。
• 使用主机上的 timeout --foreground 为每个顶层 Parallels 通道设置硬超时；如果可用的二进制文件是 gtimeout，则使用 gtimeout --foreground，以免卡住的安装、快照切换或 prlctl exec 传输耗尽剩余测试时间。默认值：
  • macOS：75m
  • Linux：75m
  • Windows：90m
  • npm 更新聚合包装器：150m 如果某个通道达到上限，就在此处停止，检查最新的 /tmp/openclaw-parallels-* 运行目录和阶段日志，然后修复或重跑受影响范围最小的通道。不要继续等待已达上限的通道。
• 实际的 OpenClaw npm 安装/更新阶段比整条通道的超时上限更能反映问题：安装阶段通常应在 7 分钟内完成，更新阶段通常应在 5 分钟内显示明显进展。如果名为 install-main、install-latest、install-baseline 或 install-baseline-package 的阶段超过 420s，或者名为 update-dev / 同一客户机上的 openclaw update 阶段超过 300s 且没有新标记，则应从该阶段的日志和客户机进程状态着手诊断。目前 Windows 更新阶段可能仍会在大约 10-15 分钟后通过，因为 doctor --fix 可能会安装捆绑的插件运行时依赖；除非日志确实停滞，否则脚本的硬超时应设在 20 分钟左右。
• 对于完整的 OS 矩阵，如果主机容量允许，优先并行运行相互独立的客户机系列通道：
  • timeout --foreground 75m pnpm test:parallels:macos -- --json
  • timeout --foreground 90m pnpm test:parallels:windows -- --json
  • timeout --foreground 75m pnpm test:parallels:linux -- --json 每个通道都在独立的 shell/会话中运行，并跟踪各自的运行目录。启动矩阵前，先完成任何必需的主机构建/打包门禁。需要为当前 main 打包 tgz 时，smoke 脚本会在 pnpm build、清点/暂存和 npm pack 期间持有共享的软件包锁；如果缺少该锁或锁已失效，就应串行运行矩阵，而不是接受并发修改 dist。
• 不要同时对同一客户机系列运行多个 smoke 通道。Tahoe 通道共享主机 HTTP 端口；如果两个任务同时操作同一 VM，Windows/Linux 通道可能会在快照恢复/启动状态上发生冲突。
• 不要将聚合的 pnpm test:parallels:npm-update 包装器与单独的 macOS/Windows/Linux smoke 通道并行运行；它们会操作相同的客户机系列和快照。
• 如果任何无关的主机命令可能重建、清理或重新暂存 dist，就不要启动 Parallels 通道（例如 pnpm build、pnpm ui:build、pnpm release:check、pnpm test:install:smoke、npm pack/install smoke，或会运行软件包/构建准备步骤的 Docker 通道）。先运行无关的构建/打包门禁并等待其完成，然后再启动 VM 矩阵。并发修改 dist 可能导致主机上的 npm pack 因缺少文件而失败，白白浪费一整轮 VM 测试。
• 运行或优化矩阵时，记录每个通道的实际耗时以及 /tmp/openclaw-parallels-* 日志中最慢的阶段。在更改 smoke 顺序、超时或辅助工具行为之前，先参考这些耗时数据。
• 如果主机构建修改了已跟踪的生成文件（例如 src/canvas-host/a2ui/.bundle.hash），就先停下来，不要继续消耗 VM 测试时间。单独提交生成的制品，或修复生成器漂移，然后重跑受影响范围最小的通道。
• 如果多 Agent 工作正在进行且 main 持续变化，长时间运行 Parallels 套件时优先使用固定在某个提交上的 detached worktree。smoke 脚本现在会验证打包后的 tgz 提交，而不是实时运行 git rev-parse HEAD；不过，固定的 worktree 仍可避免重跑期间发生嘈杂的重建/版本漂移。
• 对于 openclaw update --channel dev 通道，请记住客户机克隆的是 GitHub main，而不是你的本地 worktree。如果本地已有修复，但重跑仍在克隆的 dev 检出目录中失败，那么在分支推送之前，不要将此结果视为修复无效的证据。
• 对于 prlctl exec，请将 VM 名称放在 --current-user 之前（prlctl exec "$VM" --current-user ...），不要反过来。
• 如果工作流从仓库检出目录安装 OpenClaw，而不是通过网站安装程序/npm 发布版安装，请在结束前安装真正的客户机 CLI shim，并在全新的客户机 shell 中验证。在仓库内运行 pnpm openclaw ... 不足以保证交接一致性。
• 对于 macOS 客户机，优先使用用户级全局安装以及稳定且可通过 PATH 访问的 shim：
  • 使用 NPM_CONFIG_PREFIX="$HOME/.npm-global" npm install -g . 安装
  • 确保 ~/.local/bin/openclaw 存在，或确保 ~/.npm-global/bin 位于 PATH 中
  • 在全新的客户机 shell 中运行 which openclaw 和 openclaw --version 进行验证

使用 npm 安装后更新

• 首选入口：pnpm test:parallels:npm-update
• 若要检查仅适用于 macOS 的已发布版本更新，请使用：
  • timeout --foreground 75m pnpm test:parallels:npm-update -- --platform macos --package-spec openclaw@<old-version> --update-target <target-version-or-tag> --json 这会保留同一虚拟机中的 openclaw update --tag ... 覆盖范围，并使用共享的 macOS 当前用户／sudo 回退方案，而不会启动 Windows/Linux 测试通道。
• 必需覆盖范围：每次发布／更新回归测试都必须包含以下两个测试通道：
  • 全新快照 → 安装指定的软件包／基线版本 → 冒烟测试
  • 同一虚拟机上的基线版本 → 运行虚拟机已安装的 openclaw update ... 命令 → 再次进行冒烟测试
• 更新测试通道必须测试 OpenClaw 的内置更新程序。直接执行 npm install -g <tgz-or-spec> 或由测试框架直接替换软件包，不能算作更新流程覆盖；这些都只是安装冒烟测试。
• 对于已发布的目标版本，请先安装旧基线软件包（例如 [email protected]），然后在虚拟机中运行已安装的 CLI，使用指定的渠道／标签（例如 openclaw update --channel beta --yes --json），并在命令执行后验证 openclaw --version、openclaw update status --json、网关 RPC 和一次 Agent 轮次。
• 对于尚未发布的目标版本，请在主机上打包候选版本，通过测试框架 HTTP 服务提供 .tgz，并让虚拟机中的更新程序指向该软件包。优先使用 openclaw update --tag http://<host-ip>:<port>/openclaw-<version>.tgz --yes --json；如果还需要验证渠道持久性，则传入 --channel <stable|beta>，并在虚拟机更新环境中将 OPENCLAW_UPDATE_PACKAGE_SPEC 设为相同的服务 URL。被测试的命令仍必须是 openclaw update，而非直接运行 npm。
• 验证尚未发布版本的本地修复时，请记住，首次更新由旧基线中的更新程序代码控制。仅存在于新更新程序代码中的修复无法影响已经运行的旧进程；提供的候选版本必须与基线主机的包／插件元数据保持兼容，或者基线本身必须包含该更新程序修复。
• 验证 beta／stable 版本时，请在运行前立即解析标签（npm view openclaw@beta version dist.tarball 或 npm view openclaw@latest ...）。长时间运行的虚拟机矩阵测试期间，标签可能会变动；如果早前因注册表返回 404／标签滞后而检查失败，之后出现预期的预发布版本，则应重新启动矩阵测试。
• 使用已配置的密钥工作流，仅为 OpenAI/Anthropic 测试通道注入所需的提供商密钥。不要打印密钥或环境变量转储；通过虚拟机执行环境传递提供商密钥。
• 同一虚拟机更新验证应在 Agent 轮次之前显式将默认模型设为 openai/gpt-5.4，并使用全新的显式 --session-id，以免旧会话的模型状态影响测试。
• npm 更新聚合包装器必须在全新安装和更新两个测试通道开始前，按照 parallels-linux-smoke.sh 的相同 Ubuntu 回退策略解析 Linux 虚拟机。找不到准确的默认虚拟机时，任何主版本号 >= 24 的 Ubuntu 虚拟机均可接受；优先选择版本最新且具有全新关机快照的 Ubuntu 虚拟机。目前 Peter 的主机应使用 Ubuntu 26.04。
• 在 macOS 同一虚拟机更新检查中，npm 升级后、执行 gateway status / agent 之前，应重启网关；否则，launchd 可能报告服务已加载，但旧进程已经退出，而新进程尚未准备好接受 RPC。
• npm 更新聚合测试的 macOS 更新步骤会以 root 身份写入虚拟机更新脚本，然后以桌面用户身份运行。如果 prlctl exec "$MACOS_VM" --current-user ... 无法验证身份，请改用普通 root prlctl exec，并通过 sudo -u <desktop-user> /usr/bin/env HOME=/Users/<desktop-user> USER=<desktop-user> LOGNAME=<desktop-user> PATH=/opt/homebrew/bin:/opt/homebrew/opt/node/bin:/usr/bin:/bin:/usr/sbin:/sbin ... 重试。这只是 Parallels 传输回退方案；更新后仍须验证 openclaw --version、网关 RPC 和一次 Agent 轮次。
• 在 Windows 同一虚拟机更新检查中，npm 升级后、执行 gateway status / agent 之前，应重启网关；就地全局 npm 更新可能会导致正在运行的服务中仍有过时的哈希 dist/* 模块导入。
• 在这些 Windows 同一虚拟机更新检查中，不要将一次非零退出码的 openclaw gateway restart 视为确定失败。目前的登录项重启可能会在后台服务重新可见之前报告失败；随后应延长等待时间，直到 RPC 就绪。只有在就绪状态仍未恢复时，才将 gateway start 用作恢复步骤。
• 在该 Windows 重启之后，不要在固定等待时间后仅凭一次 gateway status --deep --require-rpc 判断状态。应重试 RPC 就绪探测约 30 秒，并记录每次尝试；当前虚拟机可能会在新的 RPC 端点仍在启动时继续占用端口 18789。
• 对于 Windows 同一虚拟机更新检查，优先使用基于完成文件／日志排空的 PowerShell 运行器模式，而不是使用单个长期运行的 prlctl exec ... powershell -EncodedCommand ... 传输。虚拟机内的任务可能已成功完成，但外层 prlctl exec 仍会挂起。
• Windows 同一虚拟机更新助手应在下载 tgz、npm install -g 等耗时步骤开始前，先将阶段标记写入日志，以免外部进度监视器在安装正常但没有日志输出时一直显示 waiting for first log line。
• Linux 同一虚拟机更新验证还应导出 HOME=/root，通过 prlctl exec ... /usr/bin/env 传入 OPENAI_API_KEY，并使用 openclaw agent --local；全新的 Linux 基线不依赖已持久化的网关凭据。
• npm 更新包装器现在会根据嵌套日志文件输出各测试通道的进度。如果某个测试通道看起来仍然卡住，请先检查 runDir 中的嵌套日志（macos-fresh.log、windows-fresh.log、linux-fresh.log、macos-update.log、windows-update.log、linux-update.log），不要直接认定外层包装器已挂起。
• 每次运行都会写入 summary.json 和 summary.md；请先阅读 Markdown 文件以便快速人工排查，然后再查看 JSON／计时信息以供自动化处理。
• 在标签发布后进行完整的 beta 验证时，优先使用一条命令：
  • timeout --foreground 150m pnpm test:parallels:npm-update -- --beta-validation beta3 --json 这会将 beta3 解析为最新的 *-beta.3 版本，运行从最新版本更新到该版本的同一虚拟机更新覆盖测试，然后在相同选定的操作系统矩阵上，对该已发布目标版本进行全新安装冒烟测试。使用 --platform macos|windows|linux 可缩小重跑范围。
• 对于带 Agent 轮次的 beta 4 npm 验证，已验证可用的命令形式为：
  • gtimeout --foreground 150m pnpm test:parallels:npm-update -- --beta-validation beta4 --model openai/gpt-5.4 --json 验证指定预发布版本号时，优先使用显式的 beta4 别名，而不是 openclaw@beta；npm 标签可能会变动。
• 如果某个测试通道导致包装器失败，请先查看自动输出的日志尾部，然后再查看 .artifacts/parallels/openclaw-parallels-npm-update.* 下完整的嵌套测试通道日志。
• 当前 macOS 更新测试通道中，若缺少或绕过回退方案，已知的传输错误特征为：Unable to authenticate the user. Make sure that the specified credentials are correct and try again. 应将其视为 Parallels 当前用户身份验证问题，而不是先归咎于 npm 或 OpenClaw。
• macOS 打包版全新安装中，如果全局软件包目录或捆绑文件的权限为 0777，通常意味着测试框架在宽松的 umask 下使用了 root prlctl exec 回退方案。POSIX 虚拟机传输命令应在开头添加 umask 022；在归咎于 npm 之前，请先核对阶段预检日志行。

CLI 调用注意事项

• Parallels 冒烟测试 shell 脚本应兼容字面值的裸 -- 参数，这样 pnpm test:parallels:* -- --json 等转发调用无需直接运行 bash scripts/e2e/... 即可正常工作。

macOS 来宾命令传输

macOS 冒烟测试和同一来宾更新通道会通过 scripts/e2e/parallels/parallels-exec.py 路由来宾命令；macOS 主机需要安装带标准 库的 python3。在已验证的 Parallels 27.0.0 (58628) 和 27.0.2 (58673) Apple 芯片版安装中，客户端会在提取结果期间保留 SDK 登录作业句柄，从而避免 主机 CLI 间歇性出现 PrlJob_GetRetCode: Invalid argument 故障。此错误 并不能证明来宾需要重新安装或再次更新 Tools。

选择逻辑会在执行前检查 PATH 中实际使用的 prlctl 及已安装 CLI 的摘要。其他二进制文件仍使用常规 prlctl；SDK 故障绝不会通过其他传输方式重试。root/当前用户选择、原始 shell 参数拼接、stdin、stdout/stderr 以及来宾退出状态都会保留。调用方仍需负责 shell 引号处理。裸 UUID 使用 CLI 的带大括号查询形式；如果找不到该 UUID，客户端会在执行任何来宾命令前，对原始字面值 VM 名称再检查一次。其他查询失败均为终止性错误。快照/启动/停止/输入/捕获以及 Linux/Windows 执行均不变。

对于已归属且正在运行的 macOS 来宾，可直接检查同一传输方式：

python3 -B scripts/e2e/parallels/parallels-exec.py --timeout-ms 30000 -- exec "<owned-macos-vm>" --current-user /bin/echo ready

完整通道仍应设置外层主机超时；SDK 等待期限不能证明来宾进程已终止。这是有范围限制的变通方案，并非受支持的公共 SDK 集成。在添加已安装二进制文件摘要前，需重新验证 ABI 以及实时命令、stdio 和清理行为；在确认厂商已修复 CLI 后移除此变通方案。临时验证后恢复原始快照并停止来宾。

macOS 流程

• 首选入口：pnpm test:parallels:macos
• parallels-macos-smoke.sh --mode fresh --target-package-spec openclaw@<version> 仅用于安装冒烟测试。在 macOS 上验证已发布的旧版本到新版本更新时，优先使用带有 --platform macos 的 npm-update 包装器；parallels-macos-smoke.sh --mode upgrade --target-package-spec ... 会安装目标软件包，不会测试基线 CLI 的更新器。
• macOS 上的默认升级覆盖现在应包括：全新快照 -> 固定到最新稳定标签的站点安装程序 -> 在来宾系统上运行 openclaw update --channel dev。将其视为 Tahoe 默认回归计划的一部分，而不是可选的支线任务。
• parallels-macos-smoke.sh --mode upgrade 默认应运行该发布版到开发版流程。仅在调用方明确传入 --target-package-spec 时，才保留旧的主机 tgz 升级路径。
• 由于默认升级流程不再需要主机 tgz，除非设置了 --target-package-spec，否则 --mode upgrade 应跳过 npm pack 和主机 HTTP 服务器启动。fresh 和 both 仍应保留打包/服务器路径。
• 如果该发布版到开发版流程以 reason=preflight-no-good-commit 失败，且 preflight build 的尾部日志反复出现 sh: pnpm: command not found，应优先将其视为更新器回归。修复应放在 git/开发版更新器引导路径中，而不是 Parallels 重试逻辑中。
• 在公开稳定版本序列包含该更新器引导修复之前，macOS 发布版到开发版流程可以在运行 openclaw update --channel dev 前，在来宾系统本地临时提供 pnpm 补丁程序。此变通方案应仅用于冒烟测试框架，并在最新稳定版不再需要时移除。
• 在 Tahoe 的 prlctl exec --current-user 调用中，发布版到开发版的交接本身以及更新后的验证，优先使用显式的 node .../openclaw.mjs ... 调用。带 shebang 的全局 openclaw 包装器可能因 env: node: No such file or directory 而失败；通过该包装器自行更新，也不如在固定的 node 下调用入口可靠。
• 默认选择最接近 macOS 26.5 latest 的快照。
• 在 Peter 的 Tahoe VM 上，fresh-latest-march-2026 可能会卡在 prlctl snapshot-switch；如果在此处恢复超时，请先使用 --snapshot-hint 'macOS 26.5 latest' 重试，再怀疑身份验证或测试框架。
• parallels-macos-smoke.sh 现在会在强制停止卡住的运行中/挂起状态的来宾系统后，将 snapshot-switch 重试一次。如果 Tahoe 在该恢复路径后仍超时，则将其视为真正的 Parallels/主机问题，并手动重试。
• macOS 冒烟测试应在网关健康检查后增加仪表板加载阶段：使用 openclaw dashboard --no-open 解析带令牌的 URL，验证提供的 HTML 包含 Control UI 标题/根框架，然后打开 Safari，并要求 Safari 与网关端口建立 localhost TCP 连接。
• 对于 Tahoe fresh.gateway-status，优先使用非 TTY 的 prlctl exec --current-user ... openclaw gateway status ...，并进行几次短暂重试。即使 CLI 本身运行正常，prlctl enter 也可能刷出 TTY 控制字节并导致阶段日志挂起。
• 如果 Tahoe 流程在 fresh.first-agent-turn 超时，且阶段日志在 models set 输出 __OPENCLAW_RC__:0 后立即停止，请先怀疑 prlctl enter / expect 包装器，而不是身份验证或模型流程。这种模式意味着第一条来宾命令已完成，但传输层没有释放，导致下一次 guest_current_user_cli 调用无法执行。
• 如果打包安装在 fresh.install-main 或 upgrade.install-main 后，于 /、/healthz 或 __openclaw/control-ui-config.json 返回 500，请怀疑打包的插件运行时依赖是从软件包根目录的 node_modules 而不是 dist/extensions/*/node_modules 解析的。在怀疑仪表板身份验证或 Safari 之前，先用真实的 npm pack/全局安装流程快速复现。
• 对于确定性的仓库命令，prlctl exec 没问题；涉及安装程序一致性或依赖 shell 的行为时，请使用来宾系统的 Terminal 或 prlctl enter。
• 多词的 openclaw agent --message ... 检查应通过来宾 shell 包装器（guest_current_user_sh / guest_current_user_cli 或 /bin/sh -lc ...）执行，而不是使用原始的 prlctl exec ... node openclaw.mjs ...；否则消息可能被拆成额外的 argv 参数，Commander 会报告 too many arguments for 'agent'。
• 绕过 --current-user 时也应遵循同一包装器规则：在来宾系统上写入一个小型 /tmp/*.sh 文件，并通过 sudo 桌面用户环境执行 /bin/bash /tmp/*.sh。不要将 openclaw agent --message '...' 作为一条原始 prlctl exec 命令直接传入。
• 当 ref 模式引导将 OPENAI_API_KEY 保存为环境变量机密引用时，后续的引导后 Agent 验证也应为来宾命令导出 OPENAI_API_KEY。网关仍可能以 pairing-required 拒绝请求并回退到嵌入式执行；该回退需要在 shell 中提供基于环境变量的凭据。
• 在全新的 Tahoe 快照上，brew 存在，但非交互式 exec 中的 PATH 可能不包含 node。必要时使用 /opt/homebrew/bin/node。
• 从主机提供服务的全新 tgz 安装应以来宾 root 用户身份安装，并设置 HOME=/var/root，然后通过 prlctl exec --current-user 以桌面用户身份运行引导。
• 以 root 安装的 tgz 冒烟测试可能会因 extensions/* 可被所有用户写入而记录插件阻止信息；除非任务涉及插件加载，否则不要将其视为引导或网关失败。

Windows 流程

• 此仓库负责通用的 Windows VM 生命周期：远程 prlctl 管理、干净状态检查、WSL 2、Git/Node、快照创建/恢复和 OpenClaw 冒烟测试。假设已安装/激活 Parallels Desktop，且已下载 Windows 11 VM，然后运行：

  pnpm test:parallels:windows:prepare -- inventory
  pnpm test:parallels:windows:prepare -- prepare
  pnpm test:parallels:windows:prepare -- verify
  

• prepare 会在进行更改前盘点环境，要求安装 Parallels Tools 且桌面会话已登录，拒绝存在 OpenClaw CLI/应用/托盘/进程状态及 WSL 发行版的环境；仅在来宾系统尚未准备就绪时，创建一个带日期且处于关机状态的干净 OS 快照；启用 WSL/Virtual Machine Platform，安装已签名的 Microsoft WSL 软件包，将 WSL 2 设为默认版本，安装 Git 和 Node/npm，验证 Windows 虚拟机监控程序已启用且没有待处理的重启，然后创建一个处于关机状态的 pre-openclaw-native-e2e-<date> 快照。

• 如果今天的 E2E 快照已存在，prepare 会恢复并验证该快照，而不是仅凭名称判断。将 prepare 视为会破坏快照之后来宾系统更改的操作，与显式恢复一样。

• 软件包提权流程会从 Microsoft 官方 WinGet 清单中解析确切版本和 SHA-256，验证预期的 Authenticode 发布者，并在执行前将文件复制到全新且 ACL 受限的 SYSTEM 目录。此处保留这一通用机制；配套应用专属的软件包选择留在 Windows 应用仓库中。

• 恢复 clean、e2e、确切名称或 ID：

  pnpm test:parallels:windows:prepare -- restore --snapshot e2e
  

• 恢复快照会丢弃快照之后的所有更改。先清点现状；如果 VM 由另一位开发者或其他通道占用，请勿恢复。e2e 会选择最新的 pre-openclaw-native-e2e-*；如需复现历史状态，请指定确切快照。

• 开发原生配套应用时，请阅读 ../../../../openclaw-windows-node/.agents/skills/openclaw-proof-validation/PARALLELS.md。这个可选的 macOS sidecar 会复用此控制器，并且只额外需要 .NET、Windows SDK、WebView2、应用检出目录、应用层快照、构建/测试和原生验证。

• 首选入口：pnpm test:parallels:windows

• 使用最新的已验证 pre-openclaw-native-e2e-* 快照，并通过 --snapshot-hint 传入其确切名称。

• Windows 上的默认升级测试现在应包括：新建快照 -> 将站点安装程序固定到请求的稳定版标签 -> 在来宾机上运行 openclaw update --channel dev。只有调用方明确传入 --target-package-spec 时，才保留较旧的主机端 tgz 升级路径。

• Windows 上可选的确切 npm 标签基线：bash scripts/e2e/parallels-windows-smoke.sh --mode upgrade --target-package-spec openclaw@<tag> --json。该通道会先安装已发布的 npm tarball 作为基线，然后运行 openclaw update --channel dev。

• 可选的 Windows 前向修复验证：bash scripts/e2e/parallels-windows-smoke.sh --mode upgrade --upgrade-from-packed-main --json。该通道会先安装打包后的当前 main npm tgz 作为基线，然后运行 openclaw update --channel dev。

• 始终使用 prlctl exec --current-user；普通的 prlctl exec 会以 NT AUTHORITY\\SYSTEM 身份运行。

• 优先使用显式的 npm.cmd 和 openclaw.cmd。

• 仅将 PowerShell 用作传输方式，并使用 -ExecutionPolicy Bypass；然后在其中调用 .cmd shim。

• 当前 Windows Node 安装会将 corepack 作为 .cmd shim 提供。如果从 release 升级到 dev 的通道发现 PATH 中有 corepack，但 openclaw update --channel dev 仍表现得像缺少 corepack，首先应将其视为 exec shim 回归问题。

• 如果精确的已发布标签 Windows 通道在预检阶段因 npm run build 和 'pnpm' is not recognized 失败，请记住来宾机仍在运行旧的已发布更新程序。使用 --upgrade-from-packed-main 验证修复，然后等到下一个带标签的 npm 版本发布后，再期待历史标签通道通过。

• 检查多词 openclaw agent --message ... 时，应在 PowerShell 中调用 & $openclaw ...，不要对 openclaw.cmd 使用 Start-Process ... -ArgumentList，否则 Commander 可能会看到拆分后的 argv，并抛出 too many arguments for 'agent'。

• Windows 安装程序/tgz 阶段现在会在重新检查来宾机就绪状态后重试一次；新增 Windows smoke 步骤时应确保其幂等，以便安全地应对传输波动导致的重试。

• 如果 Windows 重试时发现 VM 状态变为 suspended 或 stopped，请在下一次 prlctl exec 前恢复或启动 VM；否则第二次尝试只会重复相同的 rc=255。

• 即使运行正常，Windows 全局 npm install -g 阶段也可能安静一分钟或更久；判断其卡住之前，请先检查阶段日志；只有重试封装程序或超时触发后，才应将其视为回归问题。

• 这些 Windows 全局安装长时间没有输出时，有用的进度信息往往在来宾机的 npm 调试日志中，而不是辅助阶段日志中。smoke 脚本现在会在较长的基线/软件包安装期间，将 npm-cache/_logs/*-debug-0.log 中新增的内容持续写入阶段日志；在假定通道卡住之前，请先查看这些内容。

• Windows 基线软件包辅助程序现在会在超时或以非零状态码结束时，自动输出来宾机最新的 npm-cache/_logs/*-debug-0.log 尾部内容。在打开第二个来宾机 shell 之前，请先查看阶段日志中的这部分内容。

• 相同的增量 npm 调试日志流式输出也适用于 --upgrade-from-packed-main / 打包安装基线阶段。如果阶段日志仍只显示 install.start、install.download-tgz、install.install-tgz，但流式输出的 npm 调试日志显示正在获取注册表数据或执行捆绑插件的 postinstall，则该阶段仍可能运行正常。

• 全新的 Windows tgz 安装阶段也应使用后台 PowerShell 运行器和完成文件/日志排空模式；不要依赖一次长时间运行的 prlctl exec ... powershell ... npm install -g 传输来安装软件包。

• Windows release-to-dev 辅助程序应在更新前后记录 where pnpm，并要求更新后 where pnpm 成功。这可以证明更新程序本身安装或启用了 pnpm，而不是依赖仅供 smoke 测试使用的引导步骤。

• 全新的 Windows ref-mode 引导设置应采用与 npm 更新辅助程序相同的后台 PowerShell 运行器和完成文件/日志排空模式，包括启动时的内容生成检查、对较短轮询 prlctl exec 调用设置主机端超时，以及在遇到临时传输波动时于轮询失败后重试。

• 全新 Windows 守护进程健康可达性检查应使用 openclaw gateway probe --json，并设置更长的超时时间；将 ok: true 视为成功。当前 main 在启动初期执行完整的 gateway status --require-rpc 检查过于急切。

• 全新的 Windows ref-mode Agent 验证应在调用 openclaw.cmd agent 前，于 PowerShell 环境中设置 OPENAI_API_KEY，原因与 macOS 相同：需要配对的回退方案。

• 独立的 Windows 升级 smoke 通道应在 upgrade.install-main 之后、upgrade.onboard-ref 之前停止受管理的 gateway。在 onboard 前重启可能会让旧进程继续使用 onboard 前的令牌运行，而 onboard 会重写 ~/.openclaw/openclaw.json，继而导致 gateway-health 因 unauthorized: gateway token mismatch 失败。

• 如果独立的 Windows 升级因 gateway 令牌不匹配而失败，但 pnpm test:parallels:npm-update 通过，应首先将此不匹配视为独立流程中 ref-onboard 顺序错误；npm-update 辅助程序不会在同一台来宾机上重新运行 ref-mode onboard。

• 日志中的引导设置和状态输出应保持纯 ASCII；在当前的采集路径中，特殊标点会变成乱码。

• 如果遇到较早的运行记录，显示 rc=255，且 fresh.install-main.log 或 upgrade.install-main.log 为空，应将其视为来宾机启动后 prlctl exec 传输可能中断，而不是立即认定 npm/软件包失败。

• 如果已启用 WSL 功能，但 wsl.exe --version 失败，请重新运行 prepare；Windows 内置功能和已签名的 WSL 软件包是两个独立的前置条件。如果默认版本恢复为 1，请运行 wsl.exe --set-default-version 2，然后重新运行 verify。

• 如果 winget 脱离终端运行，或通过 prlctl 没有输出，请通过 cmd.exe /d /s /c 调用。避免远程 UAC：使用桌面用户下载，然后让控制器验证可信清单的哈希/发布者信息，并从受保护的 SYSTEM 暂存目录安装。

• 如果恢复快照时提示已保存的 CPU 状态不兼容，请根据已知正常的磁盘状态创建一个关机状态下的替代快照，并使用其确切名称。对于新建+升级这两个通道的声明，绝不要绕过快照恢复。

• 如果基线验证发现 OpenClaw 状态，请恢复为 clean，或有意移除产品状态；绝不要认可状态不干净的来宾机。检查 %APPDATA% 和 %LOCALAPPDATA% 中是否存在 stable 和 dev 两种配套应用标识，以及 Inno 卸载注册信息。

• Windows 安装程序长时间没有输出但仍可能运行正常。宣布卡住之前，请检查 tasklist 和安装程序/MSI 日志；长时间运行的操作应放在后台运行器中，并通过主机端超时的短轮询调用进行检查。

Linux 流程

• 首选入口：pnpm test:parallels:linux
• 使用最新版本的 Ubuntu 客户机，并采用全新的关机快照。今天在 Peter 的主机上，该版本为 Ubuntu 26.04。
• 如果主机上没有所请求的确切 Ubuntu 虚拟机，则任何主版本号 >= 24 的 Ubuntu 客户机都可以；优先使用最新版本的 Ubuntu 客户机，而不是较旧的备用快照。
• 使用普通的 prlctl exec；此快照不适合使用 --current-user 作为传输方式。
• 全新快照可能缺少 curl，且 apt-get update 可能因时钟偏差而失败。使用 apt-get -o Acquire::Check-Date=false update 引导安装，并安装 curl ca-certificates。
• 全新 main tgz 冒烟测试仍需先运行最新版本安装程序，因为引导安装前快照中没有 Node 或 npm。
• 此快照没有可用的 systemd --user 会话；不支持托管守护进程安装。
• Linux 冒烟测试现在会回退到手动启动 setsid openclaw gateway run --bind loopback --port 18789 --force，并设置 HOME=/root、导出提供商密钥；随后在可用时验证 gateway status --deep --require-rpc。
• Linux 手动启动网关时，应在 gateway-start 阶段等待 gateway status --deep --require-rpc；否则首次状态探测可能与后台绑定操作发生竞争，导致健康的测试流程失败。
• 如果 Linux 网关启动失败，请先检查客户机阶段日志中的 /tmp/openclaw-parallels-linux-gateway.log；常见故障原因是启动的网关环境中缺少提供商密钥。

Discord 往返测试

• Discord 往返测试为可选项，应通过以下参数启用：
  • --discord-token-env
  • --discord-guild-id
  • --discord-channel-id
• Discord 冒烟测试／往返测试成功后，交接前应关闭客户机虚拟机（运行 prlctl stop "$VM_NAME" 或指定具体虚拟机名称）。macOS 冒烟测试工具应在 Discord 验证成功后自动执行此操作；临时进行 Discord 检查后仍需手动停止虚拟机。不要让配置了 Discord 的客户机继续运行；它可能会在 #maintainer 中持续读取或发帖，并在验证完成后向 Discord 发送垃圾信息。
• 仅将 Discord 令牌保存在主机环境变量中。
• 使用已安装的 openclaw message send/read，不要使用 node openclaw.mjs message ...。
• 将 channels.discord.guilds 设置为一个 JSON 对象，不要使用包含雪花 ID 的点分配置路径。
• 避免使用耗时较长的 prlctl enter 或由 expect 驱动的 Discord 配置脚本；优先使用 prlctl exec --current-user /bin/sh -lc ... 执行简短命令。
• 若要运行范围更窄、仅针对 macOS 的 Discord 验证，请使用现有的 parallels-discord-roundtrip 技能进行深入检查。