SunnyShu
21e9634f10
* [AI] fix(node-cli): warn when systemd user lingering is disabled after install openclaw node install now detects when systemd user lingering is off and warns the operator (text + JSON) to run 'sudo loginctl enable-linger <user>'. Without lingering, the user-level node service is torn down when the last SSH session ends, so the node silently goes offline after logout. The check is read-only and never auto-enables lingering, matching the operator-consent policy used elsewhere. It runs only on the verified-success path: an optional onVerified hook is added to installDaemonServiceAndEmit that fires after service.isLoaded() confirms the service is loaded and before the success payload is emitted. The linger diagnostic runs there, so a failed install or verification failure never carries a linger warning (avoids misdirecting the operator to fix lingering for a service that was not successfully installed). The already-installed short-circuit warns separately. Skipped on non-Linux and when systemd user service is unavailable. Adds unit tests for both paths, the linger=yes no-op, the install-failure isolation, the verification-failure no-warn regression, and the systemd-unavailable skip, plus response.test.ts cases covering onVerified running on success and failing safely when it throws. The readSystemdUserLingerStatus mock is typed with the full linger union to satisfy tsgo. Documents the linger step in docs/cli/node.md and docs/nodes/troubleshooting.md. Real-behavior evidence captured on a Linux host by toggling loginctl disable-linger/enable-linger and running the real install flow: linger=no emits the warning on successful install (text + JSON) and on the already-installed path; linger=yes emits nothing; a failed install or verification failure emits no warning. Fixes #107033 Co-Authored-By: deepseek-v4-flash <noreply@anthropic.com> * fix(node-cli): align linger user with service owner * docs(node): narrow crash-loop claim to gateway units The duplicate-scope guard that raises on two managers running the same unit name is enforced for gateway units (two supervisors on the same port SIGTERM each other in a restart loop); assertNoSystemGatewayOwnership returns early for node services, so claiming node services crash-loop misattributes gateway behavior. Qualify the troubleshooting note accordingly. Addresses ClawSweeper P3 finding on PR #118430. * fix(systemd): align linger checks with service owner * test(doctor): align linger status mock contract * style(doctor): format linger mock * test(wizard): mock systemd service account --------- Co-authored-by: deepseek-v4-flash <noreply@anthropic.com> Co-authored-by: Patrick Erichsen <patrick.a.erichsen@gmail.com>
8.8 KiB
summary, read_when, title
| summary | read_when | title | ||
|---|---|---|---|---|
| Troubleshoot node pairing, foreground requirements, permissions, and tool failures |
|
Node troubleshooting |
Use this page when a node is visible in status but node tools fail.
Node goes offline after SSH logout (Linux)
On Linux, openclaw node install creates a user-level systemd service. The
systemd --user instance is torn down when your last login session ends, so the
node service stops the moment you log out — even though it looked healthy
(enabled + running) while you were connected.
Check lingering:
loginctl show-user "$USER" -p Linger
If it reads Linger=no, enable it (may require sudo):
sudo loginctl enable-linger "$USER"
Then restart the node service and verify it survives logout:
openclaw node restart
# log out, then from another machine:
openclaw nodes status
openclaw node install prints a warning with this recovery command when it
detects lingering is disabled. Don't mix a user-level service with a
system-level one for the same node. The duplicate-scope guard that prevents
two managers from running the same unit name is enforced for gateway units
(two supervisors on the same port SIGTERM each other in a restart loop); for
node services the installer does not raise this guard, so a leftover unit in
the other scope can leave the node in an ambiguous state. Fully remove one
before switching.
Command ladder
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Then run node-specific checks:
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
Healthy signals:
- Node is connected and paired for role
node. nodes describeincludes the capability you're calling.- Exec approvals show the expected mode/allowlist.
Foreground requirements
canvas.*, camera.*, and screen.* are foreground-only on iOS/Android nodes.
Quick check and fix:
openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow
If you see NODE_BACKGROUND_UNAVAILABLE, bring the node app to the foreground and retry.
Permissions matrix
| Capability | iOS | Android | macOS node app | Typical failure code |
|---|---|---|---|---|
camera.snap, camera.clip |
Camera (+ mic for clip audio) | Camera (+ mic for clip audio) | Camera (+ mic for clip audio) | *_PERMISSION_REQUIRED |
screen.record |
Screen Recording (+ mic optional) | Screen capture prompt (+ mic optional) | Screen Recording | *_PERMISSION_REQUIRED |
computer.act |
n/a | n/a | Accessibility + Screen Recording | COMPUTER_DISABLED, ACCESSIBILITY_REQUIRED |
location.get |
While Using or Always (depends on mode) | Foreground/Background location based on mode | Location permission | LOCATION_PERMISSION_REQUIRED |
system.run |
n/a (node host path) | n/a (node host path) | Exec approvals required | SYSTEM_RUN_DENIED |
Pairing versus approvals
Three separate gates control whether a node command succeeds:
- Device pairing: can this node connect to the gateway?
- Gateway node command policy: is the RPC command ID allowed by
gateway.nodes.commands.allow/gateway.nodes.commands.denyand platform defaults? - Exec approvals: can this node run a specific shell command locally?
Node pairing is an identity/trust gate, not a per-command approval surface. For system.run, the per-node policy lives in that node's exec approvals file (openclaw approvals get --node ...), not in the gateway pairing record.
Quick checks:
openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
- Pairing missing: approve the node device first.
nodes describemissing a command: check the gateway node command policy and whether the node actually declared that command on connect.- Pairing fine but
system.runfails: fix exec approvals/allowlist on that node.
For approval-backed host=node runs, the gateway also binds execution to the prepared canonical systemRunPlan. If a later caller mutates the command, cwd, or session metadata before the approved run is forwarded, the gateway rejects the run as an approval mismatch instead of trusting the edited payload.
Common node error codes
| Code | Meaning |
|---|---|
NODE_BACKGROUND_UNAVAILABLE |
App is backgrounded; bring it to the foreground. |
CAMERA_DISABLED |
Camera toggle disabled in node settings. |
*_PERMISSION_REQUIRED |
OS permission missing/denied. |
LOCATION_DISABLED |
Location mode is off. |
LOCATION_PERMISSION_REQUIRED |
Requested location mode not granted. |
LOCATION_BACKGROUND_UNAVAILABLE |
App is backgrounded but only While Using permission exists. |
COMPUTER_DISABLED |
Enable Allow Computer Control in the macOS app, then approve the pairing update. |
ACCESSIBILITY_REQUIRED |
Grant Accessibility to the current OpenClaw app bundle in macOS System Settings. |
SYSTEM_RUN_DENIED: approval required |
Exec request needs explicit approval. |
SYSTEM_RUN_DENIED: allowlist miss |
Command blocked by allowlist mode. On Windows node hosts, shell-wrapper forms like cmd.exe /c ... are treated as allowlist misses in allowlist mode unless approved via the ask flow. |
Fast recovery loop
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
If still stuck:
- Re-approve device pairing.
- Re-open the node app (foreground).
- Re-grant OS permissions.
- Recreate/adjust the exec approval policy.
For computer control, also verify that the node-local Computer Control toggle is enabled, its pairing update is approved, a vision-capable agent exposes the computer tool, and screen.snapshot succeeds with Screen Recording permission. A gateway.nodes.commands.deny entry always overrides a platform default or gateway.nodes.commands.allow.