ewilliams28/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-08-18 16:41:45 -06:00
Code Issues Packages Projects Releases Wiki Activity
Files
fix/github-hovercard-interactive
openclaw/docs/nodes/troubleshooting.md
T
SunnyShu 21e9634f10 fix(node-cli): warn when systemd user lingering is disabled after install (#118430) 
* [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>
2026-08-06 19:28:10 -07:00

163 lines
8.8 KiB
Markdown
Raw Permalink Blame History

---
summary: "Troubleshoot node pairing, foreground requirements, permissions, and tool failures"
read_when:
- Node is connected but camera/canvas/screen/exec tools fail
- You need the node pairing versus approvals mental model
title: "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:
```bash
loginctl show-user "$USER" -p Linger
```
If it reads `Linger=no`, enable it (may require sudo):
```bash
sudo loginctl enable-linger "$USER"
```
Then restart the node service and verify it survives logout:
```bash
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
```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```
Then run node-specific checks:
```bash
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
```
Healthy signals:
- Node is connected and paired for role `node`.
- `nodes describe` includes 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:
```bash
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:
1. **Device pairing**: can this node connect to the gateway?
2. **Gateway node command policy**: is the RPC command ID allowed by `gateway.nodes.commands.allow` / `gateway.nodes.commands.deny` and platform defaults?
3. **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:
```bash
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 describe` missing a command: check the gateway node command policy and whether the node actually declared that command on connect.
- Pairing fine but `system.run` fails: 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
```bash
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`.
## Related
- [Nodes overview](/nodes)
- [Camera nodes](/nodes/camera)
- [Location command](/nodes/location-command)
- [Computer use](/nodes/computer-use)
- [Exec approvals](/tools/exec-approvals)
- [Gateway pairing](/gateway/pairing)
- [Gateway troubleshooting](/gateway/troubleshooting)
- [Channel troubleshooting](/channels/troubleshooting)
Reference in New Issue View Git Blame Copy Permalink