openclaw-parallels-smoke

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenClaw Parallels Smoke

OpenClaw Parallels 冒烟测试

Use this skill for Parallels guest workflows and smoke interpretation. Do not load it for normal repo work.

本技能适用于Parallels客户机工作流及冒烟测试结果解读。请勿在常规仓库工作中加载本技能。

Global rules

全局规则

Use the snapshot most closely matching the requested fresh baseline.
Gateway verification in smoke runs should use
```
openclaw gateway status --deep --require-rpc
```
unless the stable version being checked does not support it yet.
Stable
```
2026.3.12
```
pre-upgrade diagnostics may require a plain
```
gateway status --deep
```
fallback.
Treat
```
precheck=latest-ref-fail
```
on that stable pre-upgrade lane as baseline, not automatically a regression.
Pass
```
--json
```
for machine-readable summaries.
Per-phase logs land under
```
/tmp/openclaw-parallels-*
```
.
Do not run local and gateway agent turns in parallel on the same fresh workspace or session.
Hard-cap every top-level Parallels lane with host
```
timeout --foreground
```
(or
```
gtimeout --foreground
```
if that is the available binary) so a stalled install, snapshot switch, or
```
prlctl exec
```
transport cannot consume the rest of the testing window. Defaults:
- macOS:
```
75m
```
- Linux:
```
75m
```
- Windows:
```
90m
```
- aggregate npm-update wrapper:
```
150m
```
  If a lane hits the cap, stop there, inspect the newest
```
/tmp/openclaw-parallels-*
```
  run directory and phase log, then fix or rerun the smallest affected lane. Do not keep waiting on a capped lane.
Actual OpenClaw npm install/update phases are a stricter signal than whole-lane caps: install phases should normally finish within 7 minutes, and update phases should normally show meaningful progress within 5 minutes. If a phase named
```
install-main
```
,
```
install-latest
```
,
```
install-baseline
```
, or
```
install-baseline-package
```
exceeds 420s, or a phase named
```
update-dev
```
/ same-guest
```
openclaw update
```
exceeds 300s without new markers, start diagnosis from that phase log and guest process state. Current Windows update phases can still pass after roughly 10-15 minutes because
```
doctor --fix
```
may install bundled plugin runtime deps; keep the script hard cap near 20 minutes unless the log is truly stale.
For a full OS matrix, prefer running independent guest-family lanes in parallel when host capacity allows:
- ```
timeout --foreground 75m pnpm test:parallels:macos -- --json
```
- ```
timeout --foreground 90m pnpm test:parallels:windows -- --json
```
- ```
timeout --foreground 75m pnpm test:parallels:linux -- --json
```
  Keep each lane in its own shell/session and track the run directory for each one. Before starting the matrix, run any required host build/package gate to completion. When current-main tgz packaging is needed, the smoke scripts hold a shared package lock through
```
pnpm build
```
  , inventory/staging, and
```
npm pack
```
  ; if that lock is missing or broken, serialize the matrix instead of accepting concurrent
```
dist
```
  mutation.
Do not run multiple smoke lanes against the same guest family at once. Tahoe lanes share the host HTTP port, and Windows/Linux lanes can collide on snapshot restore/start state if two jobs touch the same VM concurrently.
Do not run the aggregate
```
pnpm test:parallels:npm-update
```
wrapper in parallel with individual macOS/Windows/Linux smoke lanes; it touches the same guest families and snapshots.
Do not start Parallels lanes while any unrelated host command may rebuild, clean, or restage
```
dist
```
(
```
pnpm build
```
,
```
pnpm ui:build
```
,
```
pnpm release:check
```
,
```
pnpm test:install:smoke
```
, npm pack/install smoke, or Docker lanes that run package/build prep). Run unrelated build/package gates first, let them finish, then start the VM matrix. Concurrent
```
dist
```
mutation can make host
```
npm pack
```
fail with missing files and wastes a full VM cycle.
While running or optimizing the matrix, record wall-clock duration per lane and the slowest phase from
```
/tmp/openclaw-parallels-*
```
logs. Use that timing before changing smoke order, timeouts, or helper behavior.
If a host build changes tracked generated files such as
```
src/canvas-host/a2ui/.bundle.hash
```
, stop before spending VM time. Commit the generated artifact separately or fix the generator drift, then rerun the smallest affected lane.
If
```
main
```
is moving under active multi-agent work, prefer a detached worktree pinned to one commit for long Parallels suites. The smoke scripts now verify the packed tgz commit instead of live
```
git rev-parse HEAD
```
, but a pinned worktree still avoids noisy rebuild/version drift during reruns.
For
```
openclaw update --channel dev
```
lanes, remember the guest clones GitHub
```
main
```
, not your local worktree. If a local fix exists but the rerun still fails inside the cloned dev checkout, do not treat that as disproof of the fix until the branch has been pushed.

For

prlctl exec

, pass the VM name before

--current-user

(

prlctl exec "$VM" --current-user ...

), not the other way around.

If the workflow installs OpenClaw from a repo checkout instead of the site installer/npm release, finish by installing a real guest CLI shim and verifying it in a fresh guest shell.
```
pnpm openclaw ...
```
inside the repo is not enough for handoff parity.
On macOS guests, prefer a user-global install plus a stable PATH-visible shim:
- install with
```
NPM_CONFIG_PREFIX="$HOME/.npm-global" npm install -g .
```
- make sure
```
~/.local/bin/openclaw
```
  exists or
```
~/.npm-global/bin
```
  is on PATH
- verify from a brand-new guest shell with
```
which openclaw
```
  and
```
openclaw --version
```

使用与所需全新基线最匹配的快照。
冒烟测试中的网关验证应使用
```
openclaw gateway status --deep --require-rpc
```
，除非待检查的稳定版本暂不支持该命令。
稳定版本
```
2026.3.12
```
的升级前诊断可能需要回退使用普通的
```
gateway status --deep
```
。
将该稳定版本升级前测试流程中的
```
precheck=latest-ref-fail
```
视为基线情况，不要自动判定为回归问题。
传递
```
--json
```
参数以获取机器可读的摘要。
各阶段日志存储在
```
/tmp/openclaw-parallels-*
```
路径下。
不要在同一个全新工作区或会话中并行运行本地和网关Agent任务。
为每个顶级Parallels测试流程设置主机端
```
timeout --foreground
```
硬时限（若可用二进制文件为
```
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
```
的阶段耗时超过420秒，或名为
```
update-dev
```
/ 同客户机的
```
openclaw update
```
阶段耗时超过300秒且无新标记，应从该阶段日志和客户机进程状态开始诊断。当前Windows更新阶段在约10-15分钟后仍可能成功，因为
```
doctor --fix
```
可能会安装捆绑的插件运行时依赖；除非日志确实停滞，否则保持脚本硬时限在20分钟左右。
若要测试完整的操作系统矩阵，在主机容量允许的情况下，优先并行运行独立的客户机系列测试流程：
- ```
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包时，冒烟测试脚本会通过
```
pnpm build
```
  、清单/暂存和
```
npm pack
```
  保持共享包锁；若锁缺失或损坏，应序列化矩阵测试，避免并发修改
```
dist
```
  目录。
不要同时针对同一客户机系列运行多个冒烟测试流程。Tahoe流程共享主机HTTP端口，Windows/Linux流程若同时操作同一VM，可能会在快照恢复/启动状态上发生冲突。
不要将聚合的
```
pnpm test:parallels:npm-update
```
包装器与单独的macOS/Windows/Linux冒烟测试流程并行运行；它会操作相同的客户机系列和快照。
当任何无关的主机命令可能重建、清理或重新暂存
```
dist
```
目录时（如
```
pnpm build
```
、
```
pnpm ui:build
```
、
```
pnpm release:check
```
、
```
pnpm test:install:smoke
```
、npm打包/安装冒烟测试，或执行包/构建准备的Docker流程），不要启动Parallels测试流程。先运行无关的构建/包网关检查，待其完成后再启动VM矩阵测试。并发修改
```
dist
```
目录可能导致主机
```
npm pack
```
因文件缺失而失败，浪费完整的VM测试周期。
运行或优化矩阵测试时，记录每个流程的实际耗时以及
```
/tmp/openclaw-parallels-*
```
日志中最慢的阶段。在更改冒烟测试顺序、超时时间或辅助工具行为前参考这些计时数据。
若主机构建修改了受跟踪的生成文件（如
```
src/canvas-host/a2ui/.bundle.hash
```
），不要继续消耗VM时间。单独提交生成的工件或修复生成器漂移问题，然后重新运行受影响最小的测试流程。
若
```
main
```
分支在多Agent活跃工作下频繁变动，对于长时间运行的Parallels套件，优先使用固定到某个提交的分离工作树。冒烟测试脚本现在会验证打包的tgz对应的提交，而非实时的
```
git rev-parse HEAD
```
，但固定工作树仍可避免重新运行时出现嘈杂的重建/版本漂移。
对于
```
openclaw update --channel dev
```
测试流程，请注意客户机会克隆GitHub的
```
main
```
分支，而非你的本地工作树。若存在本地修复但重新运行时克隆的dev检出仍失败，在分支推送前不要判定修复无效。
使用
```
prlctl exec
```
时，在
```
--current-user
```
前传递VM名称（
```
prlctl exec "$VM" --current-user ...
```
），不要颠倒顺序。
若工作流从仓库检出而非站点安装程序/npm版本安装OpenClaw，最后需安装真实的客户机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 install then update

npm安装后更新

Preferred entrypoint:
```
pnpm test:parallels:npm-update
```

For a macOS-only published release update check, use:

timeout --foreground 75m pnpm test:parallels:npm-update -- --platform macos --package-spec openclaw@<old-version> --update-target <target-version-or-tag> --json

This keeps the same-guest

openclaw update --tag ...

coverage and uses the shared macOS current-user/sudo fallback without starting Windows/Linux lanes.

Required coverage: every release/update regression run must include both lanes:
- fresh snapshot -> install requested package/baseline -> smoke
- same guest baseline -> run the guest's installed
```
openclaw update ...
```
  command -> smoke again
The update lane must exercise OpenClaw's internal updater. Do not count a direct
```
npm install -g <tgz-or-spec>
```
or harness-side package swap as update-flow coverage; those are install smokes only.
For published targets, install the old baseline package first (for example
```
openclaw@2026.4.9
```
), then run the installed guest CLI with the intended channel/tag (for example
```
openclaw update --channel beta --yes --json
```
) and verify
```
openclaw --version
```
,
```
openclaw update status --json
```
, gateway RPC, and an agent turn after the command.
For unpublished targets, pack the candidate on the host, serve the
```
.tgz
```
over the harness HTTP server, and point the guest updater at that served package. Prefer
```
openclaw update --tag http://<host-ip>:<port>/openclaw-<version>.tgz --yes --json
```
; when channel persistence also matters, pass
```
--channel <stable|beta>
```
and set
```
OPENCLAW_UPDATE_PACKAGE_SPEC
```
to the same served URL in the guest update environment. The command under test must still be
```
openclaw update
```
, not direct npm.
For unpublished local-fix validation, remember the old baseline updater code still controls the first hop. A fix that lives only in the new updater code cannot change that already-running old process; the served candidate must either keep package/plugin metadata compatible with the baseline host or the baseline itself must include the updater fix.
For beta/stable verification, resolve the tag immediately before the run (
```
npm view openclaw@beta version dist.tarball
```
or
```
npm view openclaw@latest ...
```
). Tags can move while a long VM matrix is already running; restart the matrix when the intended prerelease appears after an earlier registry 404/tag-lag check.
Source Peter's profile in the host shell (
```
set -a; source "$HOME/.profile"; set +a
```
) before OpenAI/Anthropic lanes. Do not print profile contents or env dumps; pass provider secrets through the guest exec environment.
Same-guest update verification should set the default model explicitly to
```
openai/gpt-5.4
```
before the agent turn and use a fresh explicit
```
--session-id
```
so old session model state does not leak into the check.
The aggregate npm-update wrapper must resolve the Linux VM with the same Ubuntu fallback policy as
```
parallels-linux-smoke.sh
```
before both fresh and update lanes. Treat any Ubuntu guest with major version
```
>= 24
```
as acceptable when the exact default VM is missing, preferring the closest version match. On Peter's current host today, missing
```
Ubuntu 24.04.3 ARM64
```
should fall back to
```
Ubuntu 25.10
```
.
On macOS same-guest update checks, restart the gateway after the npm upgrade before
```
gateway status
```
/
```
agent
```
; launchd can otherwise report a loaded service while the old process has exited and the fresh process is not RPC-ready yet.
The npm-update aggregate's macOS update leg writes the guest update script as root, then runs it as the desktop user. If
```
prlctl exec "$MACOS_VM" --current-user ...
```
cannot authenticate, retry through plain root
```
prlctl exec
```
plus
```
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 ...
```
. That is a Parallels transport fallback; still verify
```
openclaw --version
```
, gateway RPC, and an agent turn after the update.
On Windows same-guest update checks, restart the gateway after the npm upgrade before
```
gateway status
```
/
```
agent
```
; in-place global npm updates can otherwise leave stale hashed
```
dist/*
```
module imports alive in the running service.
In those Windows same-guest update checks, do not treat one nonzero
```
openclaw gateway restart
```
as definitive failure. Current login-item restarts can report failure before the background service becomes observable again; follow with a longer RPC-ready wait and use
```
gateway start
```
only as a recovery step if readiness still never returns.
After that Windows restart, do not trust one
```
gateway status --deep --require-rpc
```
call after a fixed sleep. Retry the RPC-ready probe for roughly 30 seconds and log each attempt; current guests can keep port
```
18789
```
bound while the fresh RPC endpoint is still coming up.
For Windows same-guest update checks, prefer the done-file/log-drain PowerShell runner pattern over one long-lived
```
prlctl exec ... powershell -EncodedCommand ...
```
transport. The guest can finish successfully while the outer
```
prlctl exec
```
still hangs.
The Windows same-guest update helper should write stage markers to its log before long steps like tgz download and
```
npm install -g
```
so the outer progress monitor does not sit on
```
waiting for first log line
```
during healthy but quiet installs.
Linux same-guest update verification should also export
```
HOME=/root
```
, pass
```
OPENAI_API_KEY
```
via
```
prlctl exec ... /usr/bin/env
```
, and use
```
openclaw agent --local
```
; the fresh Linux baseline does not rely on persisted gateway credentials.
The npm-update wrapper now prints per-lane progress from the nested log files. If a lane still looks stuck, inspect the nested logs in
```
runDir
```
first (
```
macos-fresh.log
```
,
```
windows-fresh.log
```
,
```
linux-fresh.log
```
,
```
macos-update.log
```
,
```
windows-update.log
```
,
```
linux-update.log
```
) instead of assuming the outer wrapper hung.
If the wrapper fails a lane, read the auto-dumped tail first, then the full nested lane log under
```
/tmp/openclaw-parallels-npm-update.*
```
.
Current known macOS update-lane transport signature when the fallback is missing or bypassed:
```
Unable to authenticate the user. Make sure that the specified credentials are correct and try again.
```
Treat that as Parallels current-user authentication before blaming npm or OpenClaw.

首选入口点:
```
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>
```
或测试工具端的包替换视为更新流程覆盖；这些仅属于安装冒烟测试。
针对已发布目标，先安装旧基线包（例如
```
openclaw@2026.4.9
```
），然后使用已安装的客户机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 ...
```
）。标签可能在长时间VM矩阵测试运行时发生变动；若预期的预发布版本在早期注册表404/标签延迟检查后出现，需重启矩阵测试。
在OpenAI/Anthropic测试流程前，在主机shell中加载Peter的配置文件（
```
set -a; source "$HOME/.profile"; set +a
```
）。不要打印配置文件内容或环境转储；通过客户机执行环境传递提供商密钥。
同客户机更新验证应在Agent任务前将默认模型显式设置为
```
openai/gpt-5.4
```
，并使用全新的显式
```
--session-id
```
，避免旧会话模型状态泄漏到检查中。
聚合npm更新包装器在全新和更新流程前，必须使用与
```
parallels-linux-smoke.sh
```
相同的Ubuntu回退策略解析Linux VM。当确切的默认VM缺失时，任何主版本
```
>= 24
```
的Ubuntu客户机均可接受，优先选择最接近的版本匹配。在Peter当前的主机上，若缺失
```
Ubuntu 24.04.3 ARM64
```
，应回退到
```
Ubuntu 25.10
```
。
在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
```
等长步骤前向日志写入阶段标记，避免外部进度监控在健康但安静的安装过程中一直显示“等待第一行日志”。
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
```
），不要假设外部包装器挂起。
若包装器某个流程失败，先查看自动导出的日志尾部，再查看
```
/tmp/openclaw-parallels-npm-update.*
```
下完整的嵌套流程日志。
当前已知的macOS更新流程传输特征：当回退机制缺失或被绕过时，会出现
```
Unable to authenticate the user. Make sure that the specified credentials are correct and try again.
```
。此时应先排查Parallels当前用户认证问题，再归咎于npm或OpenClaw。

CLI invocation footgun

CLI调用陷阱

The Parallels smoke shell scripts should tolerate a literal bare
```
--
```
arg so
```
pnpm test:parallels:* -- --json
```
and similar forwarded invocations work without needing to call
```
bash scripts/e2e/...
```
directly.

Parallels冒烟测试shell脚本应允许字面量裸参数
```
--
```
，以便
```
pnpm test:parallels:* -- --json
```
及类似转发调用无需直接调用
```
bash scripts/e2e/...
```
即可正常工作。

macOS flow

macOS流程

Preferred entrypoint:
```
pnpm test:parallels:macos
```
```
parallels-macos-smoke.sh --mode fresh --target-package-spec openclaw@<version>
```
is an install smoke only. For published old-version -> new-version update coverage on macOS, prefer the npm-update wrapper with
```
--platform macos
```
;
```
parallels-macos-smoke.sh --mode upgrade --target-package-spec ...
```
installs the target package and does not exercise the baseline CLI's updater.
Default upgrade coverage on macOS should now include: fresh snapshot -> site installer pinned to the latest stable tag ->
```
openclaw update --channel dev
```
on the guest. Treat this as part of the default Tahoe regression plan, not an optional side quest.
```
parallels-macos-smoke.sh --mode upgrade
```
should run that release-to-dev lane by default. Keep the older host-tgz upgrade path only when the caller explicitly passes
```
--target-package-spec
```
.
Because the default upgrade lane no longer needs a host tgz, skip
```
npm pack
```
+ host HTTP server startup for
```
--mode upgrade
```
unless
```
--target-package-spec
```
is set. Keep the pack/server path for
```
fresh
```
and
```
both
```
.
If that release-to-dev lane fails with
```
reason=preflight-no-good-commit
```
and repeated
```
sh: pnpm: command not found
```
tails from
```
preflight build
```
, treat it as an updater regression first. The fix belongs in the git/dev updater bootstrap path, not in Parallels retry logic.
Until the public stable train includes that updater bootstrap fix, the macOS release-to-dev lane may seed a temporary guest-local
```
pnpm
```
shim immediately before
```
openclaw update --channel dev
```
. Keep that workaround scoped to the smoke harness and remove it once the latest stable no longer needs it.
In Tahoe
```
prlctl exec --current-user
```
runs, prefer explicit
```
node .../openclaw.mjs ...
```
invocations for the release->dev handoff itself and for post-update verification. The shebanged global
```
openclaw
```
wrapper can fail with
```
env: node: No such file or directory
```
, and self-updating through the wrapper is a weaker lane than invoking the entrypoint under a fixed
```
node
```
.
Default to the snapshot closest to
```
macOS 26.3.1 latest
```
.
On Peter's Tahoe VM,
```
fresh-latest-march-2026
```
can hang in
```
prlctl snapshot-switch
```
; if restore times out there, rerun with
```
--snapshot-hint 'macOS 26.3.1 latest'
```
before blaming auth or the harness.
```
parallels-macos-smoke.sh
```
now retries
```
snapshot-switch
```
once after force-stopping a stuck running/suspended guest. If Tahoe still times out after that recovery path, then treat it as a real Parallels/host issue and rerun manually.
The macOS smoke should include a dashboard load phase after gateway health: resolve the tokenized URL with
```
openclaw dashboard --no-open
```
, verify the served HTML contains the Control UI title/root shell, then open Safari and require an established localhost TCP connection from Safari to the gateway port.
For Tahoe
```
fresh.gateway-status
```
, prefer non-TTY
```
prlctl exec --current-user ... openclaw gateway status ...
```
plus a few short retries.
```
prlctl enter
```
can spam TTY control bytes and hang the phase log even when the CLI itself is healthy.
If a Tahoe lane times out in
```
fresh.first-agent-turn
```
and the phase log stops right after
```
__OPENCLAW_RC__:0
```
from
```
models set
```
, suspect the
```
prlctl enter
```
/
```
expect
```
wrapper before blaming auth or the model lane. That pattern means the first guest command finished but the transport never released for the next
```
guest_current_user_cli
```
call.
If a packaged install regresses with
```
500
```
on
```
/
```
,
```
/healthz
```
, or
```
__openclaw/control-ui-config.json
```
after
```
fresh.install-main
```
or
```
upgrade.install-main
```
, suspect bundled plugin runtime deps resolving from the package root
```
node_modules
```
rather than
```
dist/extensions/*/node_modules
```
. Repro quickly with a real
```
npm pack
```
/global install lane before blaming dashboard auth or Safari.
```
prlctl exec
```
is fine for deterministic repo commands, but use the guest Terminal or
```
prlctl enter
```
when installer parity or shell-sensitive behavior matters.

Multi-word

openclaw agent --message ...

checks should go through a guest shell wrapper (

guest_current_user_sh

guest_current_user_cli

/bin/sh -lc ...

), not raw

prlctl exec ... node openclaw.mjs ...

, or the message can be split into extra argv tokens and Commander reports

too many arguments for 'agent'

The same wrapper rule applies when bypassing
```
--current-user
```
: write a tiny
```
/tmp/*.sh
```
on the guest and execute
```
/bin/bash /tmp/*.sh
```
through the sudo desktop-user environment. Do not pass
```
openclaw agent --message '...'
```
directly as one raw
```
prlctl exec
```
command.
When ref-mode onboarding stores
```
OPENAI_API_KEY
```
as an env secret ref, the post-onboard agent verification should also export
```
OPENAI_API_KEY
```
for the guest command. The gateway can still reject with pairing-required and fall back to embedded execution, and that fallback needs the env-backed credential available in the shell.
On the fresh Tahoe snapshot,
```
brew
```
exists but
```
node
```
may be missing from PATH in noninteractive exec. Use
```
/opt/homebrew/bin/node
```
when needed.
Fresh host-served tgz installs should install as guest root with
```
HOME=/var/root
```
, then run onboarding as the desktop user via
```
prlctl exec --current-user
```
.
Root-installed tgz smoke can log plugin blocks for world-writable
```
extensions/*
```
; do not treat that as an onboarding or gateway failure unless plugin loading is the task.

首选入口点:
```
pnpm test:parallels:macos
```
```
parallels-macos-smoke.sh --mode fresh --target-package-spec openclaw@<version>
```
仅为安装冒烟测试。若要在macOS上覆盖已发布旧版本到新版本的更新测试，优先使用带
```
--platform macos
```
的npm更新包装器；
```
parallels-macos-smoke.sh --mode upgrade --target-package-spec ...
```
会直接安装目标包，不会测试基线CLI的更新器。
macOS默认升级覆盖范围应包含：全新快照 -> 固定到最新稳定标签的站点安装程序 -> 客户机上执行
```
openclaw update --channel dev
```
。将此作为默认Tahoe回归计划的一部分，而非可选附加测试。
```
parallels-macos-smoke.sh --mode upgrade
```
默认应运行该版本到dev分支的测试流程。仅当调用者显式传递
```
--target-package-spec
```
时，才保留旧的主机tgz升级路径。
由于默认升级流程不再需要主机tgz，除非设置了
```
--target-package-spec
```
，否则
```
--mode upgrade
```
应跳过
```
npm pack
```
+ 主机HTTP服务器启动步骤。为
```
fresh
```
和
```
both
```
模式保留打包/服务器路径。
若该版本到dev分支的测试流程因
```
reason=preflight-no-good-commit
```
和
```
preflight build
```
中反复出现的
```
sh: pnpm: command not found
```
尾部日志而失败，应首先判定为更新器回归问题。修复应在git/dev更新器引导路径中进行，而非Parallels重试逻辑。
在公共稳定版本包含该更新器引导修复前，macOS版本到dev分支的测试流程可能需要在执行
```
openclaw update --channel dev
```
前立即临时添加客户机本地的
```
pnpm
```
shim。将此 workaround 限定在冒烟测试工具中，待最新稳定版本无需该修复后移除。
在Tahoe的
```
prlctl exec --current-user
```
运行中，版本到dev分支的交接及更新后验证优先使用显式的
```
node .../openclaw.mjs ...
```
调用。带shebang的全局
```
openclaw
```
包装器可能会因
```
env: node: No such file or directory
```
失败，且通过包装器自更新的测试流程强度弱于在固定
```
node
```
下调用入口点。
默认使用最接近
```
macOS 26.3.1 latest
```
的快照。
在Peter的Tahoe VM上，
```
fresh-latest-march-2026
```
可能在
```
prlctl snapshot-switch
```
中挂起；若恢复超时，先使用
```
--snapshot-hint 'macOS 26.3.1 latest'
```
重新运行，再归咎于认证或测试工具问题。
```
parallels-macos-smoke.sh
```
现在会在强制停止挂起的运行/暂停客户机后重试一次
```
snapshot-switch
```
。若Tahoe在该恢复路径后仍超时，再判定为真实的Parallels/主机问题并手动重新运行。
macOS冒烟测试应在网关健康检查后包含仪表板加载阶段：使用
```
openclaw dashboard --no-open
```
解析令牌化URL，验证提供的HTML包含Control UI标题/根shell，然后打开Safari并要求Safari与网关端口建立本地TCP连接。
对于Tahoe的
```
fresh.gateway-status
```
，优先使用非TTY的
```
prlctl exec --current-user ... openclaw gateway status ...
```
并进行几次短时间重试。
```
prlctl enter
```
可能会发送TTY控制字节并导致阶段日志挂起，即使CLI本身运行正常。
若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
```
命令传递。
当引用模式入门引导将
```
OPENAI_API_KEY
```
存储为环境密钥引用时，入门引导后的Agent验证也应为客户机命令导出
```
OPENAI_API_KEY
```
。网关仍可能因需要配对而拒绝请求并回退到嵌入式执行，而该回退需要shell中提供环境支持的凭据。
在全新的Tahoe快照中，
```
brew
```
已存在但非交互式exec的PATH中可能缺少
```
node
```
。必要时使用
```
/opt/homebrew/bin/node
```
。
全新的主机提供tgz安装应以客户机root身份进行，设置
```
HOME=/var/root
```
，然后通过
```
prlctl exec --current-user
```
以桌面用户身份运行入门引导。
root安装的tgz冒烟测试可能会记录插件对全局可写
```
extensions/*
```
的阻止信息；除非任务是测试插件加载，否则不要将其视为入门引导或网关失败。

Windows flow

Windows流程

Preferred entrypoint:
```
pnpm test:parallels:windows
```
Use the snapshot closest to
```
pre-openclaw-native-e2e-2026-03-12
```
.
Default upgrade coverage on Windows should now include: fresh snapshot -> site installer pinned to the requested stable tag ->
```
openclaw update --channel dev
```
on the guest. Keep the older host-tgz upgrade path only when the caller explicitly passes
```
--target-package-spec
```
.

Optional exact npm-tag baseline on Windows:

bash scripts/e2e/parallels-windows-smoke.sh --mode upgrade --target-package-spec openclaw@<tag> --json

. That lane installs the published npm tarball as baseline, then runs

openclaw update --channel dev

Optional forward-fix Windows validation:

bash scripts/e2e/parallels-windows-smoke.sh --mode upgrade --upgrade-from-packed-main --json

. That lane installs the packed current-main npm tgz as baseline, then runs

openclaw update --channel dev

Always use

prlctl exec --current-user

; plain

prlctl exec

lands in

NT AUTHORITY\\SYSTEM

Prefer explicit
```
npm.cmd
```
and
```
openclaw.cmd
```
.
Use PowerShell only as the transport with
```
-ExecutionPolicy Bypass
```
, then call the
```
.cmd
```
shims from inside it.
Current Windows Node installs expose
```
corepack
```
as a
```
.cmd
```
shim. If a release-to-dev lane sees
```
corepack
```
on PATH but
```
openclaw update --channel dev
```
still behaves as if corepack is missing, treat that as an exec-shim regression first.
If an exact published-tag Windows lane fails during preflight with
```
npm run build
```
and
```
'pnpm' is not recognized
```
, remember that the guest is still executing the old published updater. Validate the fix with
```
--upgrade-from-packed-main
```
, then wait for the next tagged npm release before expecting the historical tag lane to pass.

Multi-word

openclaw agent --message ...

checks should call

& $openclaw ...

inside PowerShell, not

Start-Process ... -ArgumentList

against

openclaw.cmd

, or Commander can see split argv and throw

too many arguments for 'agent'

Windows installer/tgz phases now retry once after guest-ready recheck; keep new Windows smoke steps idempotent so a transport-flake retry is safe.
If a Windows retry sees the VM become
```
suspended
```
or
```
stopped
```
, resume/start it before the next
```
prlctl exec
```
; otherwise the second attempt just repeats the same
```
rc=255
```
.
Windows global
```
npm install -g
```
phases can stay quiet for a minute or more even when healthy; inspect the phase log before calling it hung, and only treat it as a regression once the retry wrapper or timeout trips.
When those Windows global installs stay quiet, the useful progress often lives in the guest npm debug log, not the helper phase log. The smoke script now streams incremental
```
npm-cache/_logs/*-debug-0.log
```
deltas into the phase log during long baseline/package installs; read those lines before assuming the lane is stalled.
The Windows baseline-package helpers now auto-dump the latest guest
```
npm-cache/_logs/*-debug-0.log
```
tail on timeout or nonzero completion. Read that tail in the phase log before opening a second guest shell.
The same incremental npm-debug streaming also applies to
```
--upgrade-from-packed-main
```
/ packaged-install baseline phases. A phase log that still says only
```
install.start
```
,
```
install.download-tgz
```
,
```
install.install-tgz
```
can still be healthy if the streamed npm-debug section shows registry fetches or bundled-plugin postinstall work.
Fresh Windows tgz install phases should also use the background PowerShell runner plus done-file/log-drain pattern; do not rely on one long-lived
```
prlctl exec ... powershell ... npm install -g
```
transport for package installs.
Windows release-to-dev helpers should log
```
where pnpm
```
before and after the update and require
```
where pnpm
```
to succeed post-update. That proves the updater installed or enabled
```
pnpm
```
itself instead of depending on a smoke-only bootstrap.
Fresh Windows ref-mode onboard should use the same background PowerShell runner plus done-file/log-drain pattern as the npm-update helper, including startup materialization checks, host-side timeouts on short poll
```
prlctl exec
```
calls, and retry-on-poll-failure behavior for transient transport flakes.
Fresh Windows daemon-health reachability should use
```
openclaw gateway probe --json
```
with a longer timeout and treat
```
ok: true
```
as success; full
```
gateway status --require-rpc
```
checks are too eager during initial startup on current main.
Fresh Windows ref-mode agent verification should set
```
OPENAI_API_KEY
```
in the PowerShell environment before invoking
```
openclaw.cmd agent
```
, for the same pairing-required fallback reason as macOS.
The standalone Windows upgrade smoke lane should stop the managed gateway after
```
upgrade.install-main
```
and before
```
upgrade.onboard-ref
```
. Restarting before onboard can leave the old process alive on the pre-onboard token while onboard rewrites
```
~/.openclaw/openclaw.json
```
, which then fails
```
gateway-health
```
with
```
unauthorized: gateway token mismatch
```
.
If standalone Windows upgrade fails with a gateway token mismatch but
```
pnpm test:parallels:npm-update
```
passes, trust the mismatch as a standalone ref-onboard ordering bug first; the npm-update helper does not re-run ref-mode onboard on the same guest.
Keep onboarding and status output ASCII-clean in logs; fancy punctuation becomes mojibake in current capture paths.
If you hit an older run with
```
rc=255
```
plus an empty
```
fresh.install-main.log
```
or
```
upgrade.install-main.log
```
, treat it as a likely
```
prlctl exec
```
transport drop after guest start-up, not immediate proof of an npm/package failure.

首选入口点:
```
pnpm test:parallels:windows
```
使用最接近
```
pre-openclaw-native-e2e-2026-03-12
```
的快照。
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暴露。若版本到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冒烟测试步骤幂等，确保传输波动重试是安全的。
若Windows重试时发现VM变为
```
suspended
```
或
```
stopped
```
，在下次
```
prlctl exec
```
前恢复/启动VM；否则第二次尝试只会重复相同的
```
rc=255
```
。
Windows全局
```
npm install -g
```
阶段即使在健康状态下也可能保持静默一分钟以上；在判定挂起前检查阶段日志，仅当重试包装器或超时触发时才判定为回归问题。
当这些Windows全局安装保持静默时，有用的进度通常在客户机npm调试日志中，而非辅助工具阶段日志。冒烟测试脚本现在会在长时间基线/包安装期间将增量的
```
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-debug部分显示注册表获取或捆绑插件安装后操作，则流程仍可能是健康的。
全新Windows tgz安装阶段也应使用后台PowerShell运行器加完成文件/日志导出模式；不要依赖单一长期运行的
```
prlctl exec ... powershell ... npm install -g
```
传输进行包安装。
Windows版本到dev分支的辅助工具应在更新前后记录
```
where pnpm
```
，并要求更新后
```
where pnpm
```
成功。这证明更新器自行安装或启用了
```
pnpm
```
，而非依赖冒烟测试专用的引导程序。
全新Windows引用模式入门引导应使用与npm-update辅助工具相同的后台PowerShell运行器加完成文件/日志导出模式，包括启动具体化检查、主机端对短轮询
```
prlctl exec
```
调用的超时设置，以及针对临时传输波动的轮询失败重试行为。
全新Windows守护进程健康可达性应使用
```
openclaw gateway probe --json
```
并设置更长超时，将
```
ok: true
```
视为成功；当前main分支初始启动时，完整的
```
gateway status --require-rpc
```
检查过于急切。
全新Windows引用模式Agent验证应在调用
```
openclaw.cmd agent
```
前在PowerShell环境中设置
```
OPENAI_API_KEY
```
，原因与macOS的配对回退需求相同。
独立的Windows升级冒烟流程应在
```
upgrade.install-main
```
后、
```
upgrade.onboard-ref
```
前停止托管网关。入门引导前重启可能会使旧进程在入门引导重写
```
~/.openclaw/openclaw.json
```
时仍持有入门引导前的令牌，导致
```
gateway-health
```
因
```
unauthorized: gateway token mismatch
```
失败。
若独立Windows升级因网关令牌不匹配而失败，但
```
pnpm test:parallels:npm-update
```
通过，应首先判定为独立引用模式入门引导顺序错误；npm-update辅助工具不会在同一客户机上重新运行引用模式入门引导。
保持入门引导和状态输出在日志中为ASCII格式；特殊标点在当前捕获路径中会变成乱码。
若遇到旧的运行记录显示
```
rc=255
```
且
```
fresh.install-main.log
```
或
```
upgrade.install-main.log
```
为空，应首先判定为客户机启动后
```
prlctl exec
```
传输丢失，而非直接证明npm/包失败。

Linux flow

Linux流程

Preferred entrypoint:
```
pnpm test:parallels:linux
```
Use the snapshot closest to fresh
```
Ubuntu 24.04.3 ARM64
```
.
If that exact VM is missing on the host, any Ubuntu guest with major version
```
>= 24
```
is acceptable; prefer the closest versioned Ubuntu guest with a fresh poweroff snapshot. On Peter's host today, that is
```
Ubuntu 25.10
```
.
Use plain
```
prlctl exec
```
;
```
--current-user
```
is not the right transport on this snapshot.
Fresh snapshots may be missing
```
curl
```
, and
```
apt-get update
```
can fail on clock skew. Bootstrap with
```
apt-get -o Acquire::Check-Date=false update
```
and install
```
curl ca-certificates
```
.
Fresh
```
main
```
tgz smoke still needs the latest-release installer first because the snapshot has no Node or npm before bootstrap.
This snapshot does not have a usable
```
systemd --user
```
session; managed daemon install is unsupported.
The Linux smoke now falls back to a manual
```
setsid openclaw gateway run --bind loopback --port 18789 --force
```
launch with
```
HOME=/root
```
and the provider secret exported, then verifies
```
gateway status --deep --require-rpc
```
when available.
The Linux manual gateway launch should wait for
```
gateway status --deep --require-rpc
```
inside the
```
gateway-start
```
phase; otherwise the first status probe can race the background bind and fail a healthy lane.
If Linux gateway bring-up fails, inspect
```
/tmp/openclaw-parallels-linux-gateway.log
```
in the guest phase logs first; the common failure mode is a missing provider secret in the launched gateway environment.

首选入口点:
```
pnpm test:parallels:linux
```
使用最接近全新
```
Ubuntu 24.04.3 ARM64
```
的快照。
若主机上缺失该确切VM，任何主版本
```
>= 24
```
的Ubuntu客户机均可接受；优先选择带有全新关机快照的最接近版本的Ubuntu客户机。在Peter当前的主机上，替代版本为
```
Ubuntu 25.10
```
。
使用普通的
```
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 roundtrip

Discord往返测试

Discord roundtrip is optional and should be enabled with:

```
--discord-token-env
```
```
--discord-guild-id
```
```
--discord-channel-id
```

After a successful Discord smoke/roundtrip, shut down the guest VM before handoff (
```
prlctl stop "$VM_NAME"
```
or the concrete VM name). The macOS smoke harness should do this automatically after successful Discord proof; still stop the VM manually after ad-hoc Discord checks. Do not leave the Discord-configured guest running; it can keep reading/posting in
```
#maintainer
```
and spam Discord after the proof is complete.
Keep the Discord token only in a host env var.

Use installed

openclaw message send/read

, not

node openclaw.mjs message ...

Set
```
channels.discord.guilds
```
as one JSON object, not dotted config paths with snowflakes.
Avoid long
```
prlctl enter
```
or expect-driven Discord config scripts; prefer
```
prlctl exec --current-user /bin/sh -lc ...
```
with short commands.
For a narrower macOS-only Discord proof run, the existing
```
parallels-discord-roundtrip
```
skill is the deep-dive companion.

Discord往返测试为可选功能，需通过以下参数启用：
- ```
--discord-token-env
```
- ```
--discord-guild-id
```
- ```
--discord-channel-id
```
Discord冒烟测试/往返测试成功后，在交付前关闭客户机VM（
```
prlctl stop "$VM_NAME"
```
或具体的VM名称）。macOS冒烟测试工具应在Discord验证成功后自动执行此操作；临时Discord检查后仍需手动关闭VM。不要让配置了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
```
技能是深度测试的配套工具。