Node Troubleshooting

当你看到小帮手在线，但让它拍照、录屏或运行命令却不工作时，别着急，我们可以像爬梯子一样，一步一步来检查。

首先，我们用几个基础的“检查口令”看看整体情况。你可以把它们想成是医生的听诊器，用来听听系统哪里不舒服。

1. 检查整体状态：输入 openclaw status 和 openclaw gateway status，看看大管家（网关）和小帮手们是不是都醒着。
2. 看看运行日记：输入 openclaw logs --follow，这就像看一本实时写的日记，里面会告诉我们发生了什么错误。
3. 让系统自检：输入 openclaw doctor，它会自动检查一遍，看看有没有明显的问题。
4. 检查连接通道：输入 openclaw channels status --probe，这就像检查电话线通不通。

如果上面都没问题，我们就专门检查一下出问题的小帮手。

1. 看看所有小帮手：输入 openclaw nodes status，列出所有小帮手。
2. 仔细看看某一个：输入 openclaw nodes describe --node <idOrNameOrIp>，把 <idOrNameOrIp> 换成那个小帮手的名字或编号。这会告诉我们这个小帮手有什么本领（能力）。
3. 检查它的“许可条”：输入 openclaw approvals get --node <idOrNameOrIp>，看看它被允许做什么事情。

怎么知道小帮手是健康的呢？有三个好信号：它已经连接并配对了；nodes describe 的结果里包含你想用的本领（比如 camera.snap）；执行命令的许可（approvals）模式是你期望的。

有些本领很害羞，必须在手机前台才能工作。比如在苹果或安卓手机上，画画（canvas.*）、拍照（camera.*）和录屏（screen.*）就是这样。如果它们失败了，你可以：

1. 用 openclaw nodes describe 看看这个小帮手。
2. 试试让它拍个快照：openclaw nodes canvas snapshot。
3. 同时看看运行日记 openclaw logs --follow。 如果你在日记里看到 NODE_BACKGROUND_UNAVAILABLE 这个错误，意思就是小帮手的 App 躲到后台去了。你只要把手机上的那个 App 点开，让它回到前台，再试一次就行了。

不同的小帮手（在不同的手机上）需要不同的“通行证”（权限）。比如，拍照需要相机通行证，录屏需要录屏通行证。如果通行证没给，就会看到像 *_PERMISSION_REQUIRED 这样的错误。这时，你需要去手机的设置里，找到那个 App，把对应的通行证打开。

这里有两把不同的“锁”要打开：

1. 设备配对：这把锁管的是小帮手能不能连接到家里的大管家（网关）。检查命令是 openclaw devices list 和 openclaw nodes status。
2. 执行许可：这把锁管的是小帮手能不能运行某个具体的命令（比如 system.run）。检查命令是 openclaw approvals get。 如果配对没了，要先重新批准设备。如果配对着，但 system.run 命令失败，那就要去调整执行许可的规则。

最后，记住这个快速的“检查-修复”循环，当问题搞不清时，就按这个顺序做一遍：

1. openclaw nodes status
2. openclaw nodes describe --node <那个小帮手>
3. openclaw approvals get --node <那个小帮手>
4. openclaw logs --follow

如果还不行，就试试这些终极办法：重新批准设备配对、重新打开小帮手的 App（确保在前台）、去手机设置里重新给 App 通行证、重新设置一下命令执行的许可规则。