什么日志都没有——因为进程没活到能写日志

Guardian 日志只有 3 行。cache 目录的 logs 下面就一个 config-health.json。没有 gateway 业务日志。端口 18789 空闲。这三个事实同时出现时说明一件事：进程根本没活到能写日志的阶段。

现象

SSH 连接客户机（Windows 环境，便携包版本 0.0.1-s0）查看：

tasklist 无任何 panel / gateway / claw 进程
Guardian 日志仅有 3 行：[启动循环] → [暂停升级] → [恢复升级]，之后无任何输出
本地缓存目录 %LOCALAPPDATA%\Microsoft\WakouAI\Runtime\<cacheId>\data\openclaw\logs\ 只有一个 config-health.json，完全没有 gateway 业务日志
Guardian 调试日志显示 panel 19:35 启动、19:37 主动关闭，Guardian 正常 final sync 退出，不是崩溃
端口 18789 空闲
openclaw.json 配置正常：mode=local、port=18789、token 有、DeepSeek 模型已配

手动在命令行前台运行启动脚本，立即退出，唯一的输出是：

The system cannot find the path specified.

这条错误文本很模糊，没有指明哪个路径，凭这条消息无法直接定位。但关键信息是"立即退出"和"错误一闪而过"——这通常意味着启动脚本本身执行失败，而不是网关进程启动后才出问题。

排查过程

第一步：确认是没启动还是启动后崩溃

tasklist 找不到任何相关进程，说明进程根本没有起来。这排除了"启动后立即崩溃"的假设。

第二步：查启动链路

便携包有一条启动链路：运行龙虾.cmd → bin\start-local-cache.ps1 → bin\gateway-start.cmd

其中 gateway-start.cmd 的核心命令是：

"%ROOT%\runtime\nodejs\node.exe" "%ROOT%\engines\openclaw\node_modules\openclaw\openclaw.mjs" gateway run --port 18789 --force

这是一条标准的 Node.js 应用启动命令：先调用 node.exe，再加载入口文件 openclaw.mjs。

第三步：手动运行启动脚本，捕获完整输出

在便携包根目录下运行：

& ".\bin\gateway-start.cmd" 2>&1

出错退出，输出就是那条含糊的"找不到路径"。cmd.exe 在尝试运行第一行命令时找不到 %ROOT%\runtime\nodejs\node.exe。

第四步：验证关键文件

直接查看便携包目录结构：

便携包根/
├── bin/
├── data/
├── engines/
│   └── openclaw/
│       └── node_modules/       ← 子目录数只有 6 个
├── launcher.exe
├── WakouPanel.exe
└── （没有 runtime 目录）

对标源端机器的同一版本便携包：

关键路径	应有	客户 U 盘实际
`runtime\nodejs\node.exe`	~80 MB	整个 `runtime\` 目录不存在
`engines\openclaw\node_modules\openclaw\openclaw.mjs`	网关入口文件	缺失
`engines\openclaw\node_modules\`	数百个依赖包	只剩 `.bin` / `@agentclientprotocol` / `@anthropic-ai` / `@aws` / `@aws-crypto` / `@aws-sdk` 共 6 个

第五步：排除其他假设

端口冲突？netstat -ano | findstr :18789，端口空闲。
配置问题？openclaw.json 存在且有效。
Node.js 不兼容？node.exe 本来就不存在，不是版本问题。
网络问题？整个拷贝都完不成，网络不是瓶颈。

根因

便携包从源端机器拷到客户 U 盘时不完整。这个不完整不是物理损伤或网络中断，而是 NTFS 长路径限制与拷贝工具默认行为的组合：

NTFS MAX_PATH 限制：Windows 默认限制单个路径不超过 260 字符（包括目录和文件名）。便携包中 engines\openclaw\node_modules\ 的嵌套深度很深，加上包名很长（如 @anthropic-ai/sdk），容易超过 260 字符。

拷贝工具的静默跳过：当用资源管理器或 robocopy 等默认设置拷贝超长路径的文件时，如果 Windows 未启用长路径支持（LongPathsEnabled），拷贝工具不会报错，而是静默跳过这些文件。用户看不到任何警告，拷贝过程显示"成功"，但目录树已经被截断。

具体表现：拷贝 node_modules 时，前面的几层依赖（如 @aws-sdk）拷进去了，但更深层的包或更长名字的包在超过 260 字符时被跳过，最终 node_modules 从数百个包被截断到个位数。而最关键的 openclaw 包由于嵌套深度加包名长度恰好超过限制，整个被跳过。

为什么网关启动时没有日志：网关启动脚本没有重定向 stdout/stderr，启动信息输出到控制台。但 U 盘上根本没有 node.exe，所以 cmd.exe 在尝试执行 node.exe 这一步就报错退出了。错误消息（"找不到路径"）一闪而过，进程根本没活到能初始化日志系统的阶段。这是缺文件导致启动失败的典型症状：看起来"什么都没有"，其实是进程死在了能写日志之前。

对比 Guardian 日志的"三行后无输出"：Guardian 本身能启动，它检测到 panel 启动失败（网关无法启动），于是做了升级恢复，但由于网关依然起不来，Guardian 进入循环等待，不再输出日志。这不是 Guardian 的问题，是它上游依赖的网关起不来。

修复方法

短期方案（让客户能跑起来）

客户端启用 NTFS 长路径支持（关键步骤）：
```
reg add HKLM\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1 /f
```
修改后需重启或注销用户，才能让 Windows API 生效。
重新拷贝便携包：用 7-Zip 或 PowerShell 的 Expand-Archive 解压一份完整的便携包到 U 盘。解压工具通常比拷贝工具对长路径的处理更完善。
```
Compress-Archive -Path 便携包源目录 -DestinationPath wakou-portable.zip -CompressionLevel Fastest
# 或
7z a -mx=1 wakou-portable.7z 便携包源目录
```
不可行方案：只补传 runtime\ 和 openclaw 两个目录——这样的补丁仍然会因为路径超长而被静默跳过，治标不治本。

长期方案（产品/工程层预防）

启动脚本增加 stderr 重定向：gateway-start.cmd 当前不记录启动错误，导致诊断困难。改成：

start "OpenClaw Gateway" /min cmd /c ""%ROOT%\runtime\nodejs\node.exe" "%ROOT%\engines\openclaw\node_modules\openclaw\openclaw.mjs" gateway run --port 18789 --force >> "%OPENCLAW_HOME%\logs\gateway-stdout.log" 2>> "%OPENCLAW_HOME%\logs\gateway-stderr.log""

这样无论 node.exe 找不到还是启动报错，都会写入日志文件，大大加快诊断速度。

首启自检：部署包完整性校验。在 start-local-cache.ps1 或 launcher 的初始化阶段增加关键路径检查，拒绝启动不完整的包：
关键路径清单：
- runtime\nodejs\node.exe 存在且文件大小 > 30 MB
- engines\openclaw\node_modules\openclaw\openclaw.mjs 存在
- engines\openclaw\node_modules\ 一级子目录数 > 200（截断时通常只剩个位数，这个阈值用来快速检测）
- runtime\python\python.exe 存在且文件大小 > 20 MB
任一不通过，弹窗中文提示"安装包不完整：检测到 XXX 缺失，请重新解压完整的安装包"，拒绝继续启动。
分发流程改进：官方只发送 .zip / .7z 归档文件，不发送解压后的文件夹。在 README 或启动引导中明确写出"请启用 NTFS 长路径支持"的前置条件。
Panel UI 错误展示：当前 gateway 启动失败时，Panel 没有显式提示。建议把 stderr 内容展示给用户，而不是默默失败。

防回归

构建期检查是关键。发版前在构建机运行完整性校验脚本，遍历关键路径清单（runtime\nodejs\node.exe、engines\openclaw\node_modules\openclaw\openclaw.mjs、一级子目录数量等），缺任何一项直接 fail 禁止上传。

便携包生成后用自检脚本验证所有关键文件存在、文件大小合理、依赖包数量达标。与此同时，客户交付文档里新增"NTFS 长路径支持"为前置条件，并提供一键启用的 PowerShell 脚本。

缺文件导致的启动失败有个共同特征：进程没启动，日志空白，症状表现为"什么都没有"。下次遇到这种现象，排查应该是：先用 tasklist 确认进程不存在，再用 Test-Path 逐个验证启动脚本的依赖文件，最后手动前台运行脚本并用 2>&1 捕获完整的 stderr。不要先查配置——配置问题通常是进程起来后才报错。

■