节点故障排查

当节点在状态中可见但节点工具失败时，使用此页面。

节点在 SSH 退出后离线（Linux）¶

在 Linux 上，openclaw node install 会创建一个 用户级 systemd 服务。当你的最后一个登录会话结束时， systemd --user 实例会被拆除，因此节点服务会在你退出登录的那一刻停止——即使在你连接期间它看起来是健康的（enabled + running）。

检查持续登录（linger）：

loginctl show-user "$USER" -p Linger

如果显示 Linger=no，请启用持续登录（可能需要 sudo）：

sudo loginctl enable-linger "$USER"

然后重启节点服务，并验证它在退出登录后仍保持运行：

openclaw node restart
# log out, then from another machine:
openclaw nodes status

openclaw node install 在检测到持续登录已禁用时，会打印包含此恢复命令的警告。不要为同一节点混用用户级服务和系统级服务。防止两个管理器运行同一单元名称的重复作用域保护机制，对 gateway 单元强制执行（同一端口上的两个 supervisor 会在重启循环中互相发送 SIGTERM）；对于节点服务，安装程序不会启用该保护，因此另一个作用域中残留的单元可能使节点处于不明确状态。切换前请完全移除其中一个。

命令阶梯¶

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

然后运行节点特定检查：

openclaw nodes pending
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>

健康信号：

节点已连接，并已为角色 node 配对。
nodes describe 包含你正在调用的能力。
执行审批显示预期的模式/允许列表。

如果启动准备禁用了你启用的容器会话托管，请检查节点主机的本地 stderr，查找 node host worker hosting disabled: ...，并按照报告的引擎或上下文恢复指引操作。macOS 应用会将工作进程 stderr 转发到其日志记录器，子系统为 ai.openclaw，类别为 node-host-worker；捕获选项参见 macOS 日志。修复原因后，重启节点主机。显式禁用的托管不会产生此类诊断信息。

节点主机重启后，会话容量会保持占用，直到验证工作进程清理完成。在 Linux 和 macOS 上，即使原进程组领导者已退出，已释放的直接工作进程也会通过其原进程组恢复。较新的工作进程会保留一个清理锚点，在退出前记录后代完成状态；恢复过程还会等待其进程组消失。如果锚点在没有该记录的情况下终止，节点会记录 lost its cleanup anchor without recorded lineage completion，并继续保留该槽位。请检查剩余的工作进程后代和节点主机日志；仅再次重启无法证明清理已完成。其他空闲槽位仍可用。在降级具有活动工作进程的节点之前，请参见数据库兼容性契约。

如果 Windows 节点主机在确认工作进程清理之前退出，其未完成的占用声明和槽位会在重启之间保持保留。丢失或重用工作进程的 PID 并不能证明其后代已停止。由原主机确认的清理仍会正常释放容量；受支持主机上的容器隔离工作进程会使用其容器引擎的移除确认。

节点运行时版本与 CLI 不同¶

打包的无头节点可能运行比全局安装的 CLI 更新的私有运行时。使用 openclaw nodes status --json 检查已连接节点的版本；openclaw --version 报告 CLI 版本。有关延迟更新、选择退出、回退以及迁移或修复延迟，请参见无头节点更新。

如果一个看似空闲的节点持续延迟更新，请检查其已安装的插件。没有空闲工作回调的插件无法确认其后台工作已完成，因此节点会保持运行。请更新该插件，或在手动更新并重启节点之前完成其工作。

前台要求¶

camera.* 和 screen.* 在 iOS/Android 节点上仅限前台。

快速检查和修复：

openclaw nodes describe --node <idOrNameOrIp>
openclaw logs --follow

如果你看到 NODE_BACKGROUND_UNAVAILABLE，请将节点应用切换到前台并重试。

权限矩阵¶

能力	iOS	Android	macOS 节点应用	典型失败代码
`camera.snap`, `camera.clip`	相机（剪辑音频需麦克风）	相机（剪辑音频需麦克风）	相机（剪辑音频需麦克风）	`*_PERMISSION_REQUIRED`
`screen.record`	屏幕录制（麦克风可选）	屏幕捕获提示（麦克风可选）	屏幕录制	`*_PERMISSION_REQUIRED`
`computer.act`	不适用	不适用	辅助功能 + 屏幕录制	`COMPUTER_DISABLED`, `ACCESSIBILITY_REQUIRED`
`location.get`	使用期间或始终（取决于模式）	根据模式使用前台/后台定位	位置权限	`LOCATION_PERMISSION_REQUIRED`
`system.run`	不适用（节点主机路径）	不适用（节点主机路径）	需要执行审批	`SYSTEM_RUN_DENIED`

配对与审批¶

四个独立的审批与策略关卡控制节点命令是否成功：

设备配对：该节点能否连接到 Gateway？
节点命令面审批：声明的命令是否已通过 openclaw nodes pending 和 openclaw nodes approve <nodeRequestId> 审批？
Gateway 节点命令策略：RPC 命令 ID 是否被 gateway.nodes.commands.allow / gateway.nodes.commands.deny 和平台默认值允许？
Exec 审批：该节点是否可以在本地运行特定的 shell 命令？

设备配对接受身份；命令面审批限制其已配对设备记录上的命令。这两个请求 ID 是不同的。初始未审批的命令面不暴露任何有效命令。待处理的扩展仅保留已审批、仍保持声明状态并通过 Gateway 策略的命令。对于 system.run，shell 允许列表和询问策略位于节点的 exec 审批（openclaw approvals get --node ...）中，而不是配对记录中。平台权限和前台要求仍然适用。

快速检查：

openclaw devices list
openclaw nodes pending
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

缺少配对：使用 openclaw devices approve <deviceRequestId> 审批当前设备请求，然后重启或重新运行因 PAIRING_REQUIRED 暂停的节点。重新连接会创建独立的命令面请求。
节点已配对并连接，但初始命令列表为空：检查 openclaw nodes pending，并使用 openclaw nodes approve <nodeRequestId> 审批其独立的 <nodeRequestId>。
nodes describe 缺少命令：检查 Gateway 节点命令策略，以及节点在连接时是否实际声明了该命令。
命令面已审批但 system.run 失败：检查 Gateway 策略，然后检查该节点的 exec 审批/允许列表。

SSH 验证和引导注册可以自动审批第一个命令面。受信任网络中的设备审批不会自动审批。后续的命令、能力或权限扩展仍需要命令面审批。

对于由审批支持的 host=node 运行，Gateway 还会将执行绑定到准备好的规范 systemRunPlan。如果后续调用者在已审批运行被转发之前修改了命令、cwd 或会话元数据，Gateway 会将其作为审批不匹配拒绝，而不是信任被编辑的 payload。

常见节点错误代码¶

代码	含义
`NODE_BACKGROUND_UNAVAILABLE`	应用处于后台；请将其切换到前台。
`CAMERA_DISABLED`	节点设置中已禁用相机开关。
`*_PERMISSION_REQUIRED`	缺少/被拒绝操作系统权限。
`LOCATION_DISABLED`	位置模式已关闭。
`LOCATION_PERMISSION_REQUIRED`	请求的位置模式未获授权。
`LOCATION_BACKGROUND_UNAVAILABLE`	应用处于后台，但仅存在“使用时”权限。
`COMPUTER_DISABLED`	在 macOS 应用中启用允许计算机控制，然后审批配对更新。
`ACCESSIBILITY_REQUIRED`	在 macOS 系统设置中，向当前 OpenClaw 应用包授予辅助功能权限。
`SYSTEM_RUN_DENIED: approval required`	Exec 请求需要显式审批。
`SYSTEM_RUN_DENIED: allowlist miss`	命令被允许列表模式阻止。在 Windows 节点主机上，类似 `cmd.exe /c ...` 的 shell 包装形式在允许列表模式下被视为允许列表未命中，除非通过询问流程审批。

快速恢复循环¶

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow

如果仍然卡住：

重新审批设备配对。
重启或重新运行因手动配对暂停的节点，然后使用 openclaw nodes pending / openclaw nodes approve <nodeRequestId> 审批其待处理的命令面请求。
重新打开节点应用（前台）。
重新授予操作系统权限。
重新创建/调整 exec 审批策略。

对于计算机控制，还需验证节点本地的计算机控制开关已启用、其配对更新已审批、具备视觉能力的代理暴露了 computer 工具，并且 screen.snapshot 在屏幕录制权限下成功。gateway.nodes.commands.deny 条目始终覆盖平台默认值或 gateway.nodes.commands.allow。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw