用途
该技能用于 vercel-openclaw 的沙箱生命周期调试，当沙箱状态机是主要怀疑对象时使用。对于 Sandbox v2 真值模型相关工作，还需加载 sandbox-v2-lifecycle。官方 Vercel Sandbox v2 文档优先于仓库中把手动快照视为常规恢复来源的旧指导。
主要能力
技能围绕沙箱状态机的诊断展开，帮助区分多种状态维度，并定位状态转换的触发原因。它覆盖创建、恢复、停止、快照、重置、陈旧 running 状态对账、持久化 Sandbox v2 行为等生命周期环节。
使用方式
起点
阅读 lat.md/sandbox-lifecycle.md 中的 Status State Machine、Triggers -- What Causes State Transitions 以及涉及的特定触发器。不确定时运行 lat locate "Sandbox Lifecycle" 或 lat search "sandbox lifecycle <symptom>"。
编辑前收集
- GET /api/status 以及触发该操作的任何 UI 状态。
- GET /api/admin/sandbox-diag。
- GET /api/admin/logs，过滤 sandbox.、gateway.、watchdog.、proxy.。
- 本地 git rev-parse HEAD、远程 git ls-remote origin main 以及实时部署证明。
拆分状态
分别报告以下内容：
- SingleMeta.status 中的 metadata status
- Vercel Sandbox SDK status
- 端口 3000 上的 gateway readiness
- 持久化自动保存状态可用性
- 相关时的手动 snapshot/checkpoint 可用性
- 可见时的 lifecycle lock 和 start lock 状态
- UI polling status
不要用 running 作为 gateway-ready 或 user-ready 的简写。
常见路径
- Admin ensure：/api/admin/ensure -> ensureSandboxRunning() / ensureSandboxReady()。
- Gateway 请求：auth -> ensureSandboxRunning() -> token refresh -> touchRunningSandbox() -> proxy。
- 停止/自动保存：stopSandbox() -> cleanup -> cron persistence -> sandbox.stop({ blocking: false }) -> snapshotting host metadata while v2 persists state。
- 状态轮询：GET /api/status -> stale running or snapshotting reconciliation。
- 重置：resetSandbox() 销毁活动沙箱和快照，清除 cron 和 token 元数据。
Sandbox v2 规则
- 主 OpenClaw 沙箱是一个命名的持久沙箱。
- 常规恢复使用持久名称和自动保存状态，而非手动 snapshotId。
- 观察 stopped/snapshotting 状态必须使用 resume:false。
- 手动 snapshot() 仅用于显式/调试/检查点，并会关闭沙箱。
- Worker/debug 沙箱是短生命周期的，必须使用 persistent:false。
修复边界
- 主要：src/server/sandbox/lifecycle.ts、src/server/sandbox/controller.ts。
- 路由：src/app/api/admin/{ensure,stop,snapshot,reset,status}/** 和 src/app/api/status/route.ts。
- 测试：src/server/sandbox/**.test.ts 和 src/test-utils/harness 下的生命周期与 harness 测试。
- 文档：lat.md/sandbox-lifecycle.md、docs/lifecycle-and-restore.md。
验证
使用覆盖该路径的最窄命令，当变更具有广泛生命周期影响时运行仓库验证器：
node scripts/verify.mjs --steps=test,typecheck lat check
对于实时生命周期事件，包含前后 /api/status、/api/admin/sandbox-diag 以及相关日志事件。
适用场景
适用于 vercel-openclaw 中沙箱状态机相关的调试工作，包括创建、恢复、停止、快照、重置、陈旧 running 状态对账、持久化 Sandbox v2 行为等生命周期问题。
限制
资料未提供该技能的收费、价格、平台支持范围或效果保证等信息。