​

Nodes

• Nodes to urządzenia peryferyjne, a nie gateway. Nie uruchamiają usługi gateway.
• Wiadomości Telegram/WhatsApp/etc. trafiają do gateway, a nie do nodes.
• Procedura rozwiązywania problemów: /nodes/troubleshooting

​

Parowanie + status

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

• nodes status oznacza węzeł jako paired, gdy jego rola w parowaniu urządzenia obejmuje node.
• Rekord parowania urządzenia jest trwałą umową zatwierdzonej roli. Rotacja tokena pozostaje w granicach tej umowy; nie może podnieść sparowanego węzła do innej roli, której zatwierdzenie parowania nigdy nie przyznało.
• node.pair.* (CLI: openclaw nodes pending/approve/reject/rename) to osobny magazyn parowania węzłów należący do gateway; nie kontroluje on handshake connect dla WS.
• Zakres zatwierdzenia podąża za zadeklarowanymi poleceniami oczekującego żądania:
  • żądanie bez poleceń: operator.pairing
  • polecenia węzła inne niż exec: operator.pairing + operator.write
  • system.run / system.run.prepare / system.which: operator.pairing + operator.admin

​

Zdalny host node (system.run)

​

Co działa gdzie

• Host gateway: odbiera wiadomości, uruchamia model, kieruje wywołania narzędzi.
• Host node: wykonuje system.run/system.which na komputerze węzła.
• Approvals: egzekwowane na hoście node przez ~/.openclaw/exec-approvals.json.

• Uruchomienia node oparte na zatwierdzeniach wiążą dokładny kontekst żądania.
• Dla bezpośrednich wykonań plików powłoki/runtime OpenClaw dodatkowo w trybie best-effort wiąże jeden konkretny lokalny operand pliku i odrzuca uruchomienie, jeśli ten plik zmieni się przed wykonaniem.
• Jeśli OpenClaw nie może zidentyfikować dokładnie jednego konkretnego lokalnego pliku dla polecenia interpreter/runtime, wykonanie oparte na zatwierdzeniu jest odrzucane zamiast udawać pełne pokrycie runtime. Użyj sandboxingu, osobnych hostów albo jawnej zaufanej listy dozwolonych/pełnego workflow dla szerszej semantyki interpreterów.

​

Uruchom hosta node (na pierwszym planie)

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

​

Zdalny gateway przez tunel SSH (bind loopback)

# Terminal A (pozostaw uruchomiony): przekieruj lokalny 18790 -> gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: wyeksportuj token gateway i połącz się przez tunel
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

• openclaw node run obsługuje uwierzytelnianie tokenem lub hasłem.
• Preferowane są zmienne env: OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD.
• Zapasowa konfiguracja to gateway.auth.token / gateway.auth.password.
• W trybie local host node celowo ignoruje gateway.remote.token / gateway.remote.password.
• W trybie remote gateway.remote.token / gateway.remote.password kwalifikują się zgodnie z regułami pierwszeństwa dla remote.
• Jeśli aktywne lokalne SecretRef gateway.auth.* są skonfigurowane, ale nierozwiązane, uwierzytelnianie hosta node kończy się fail-closed.
• Rozwiązywanie uwierzytelniania hosta node uwzględnia tylko zmienne env OPENCLAW_GATEWAY_*.

​

Uruchom hosta node (jako usługę)

openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node restart

​

Sparuj + nazwij

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

• --display-name w openclaw node run / openclaw node install (utrwalane w ~/.openclaw/node.json na węźle).
• openclaw nodes rename --node <id|name|ip> --name "Build Node" (nadpisanie po stronie gateway).

​

Dodaj polecenia do listy dozwolonych

openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"

​

Skieruj exec do node

openclaw config set tools.exec.host node
openclaw config set tools.exec.security allowlist
openclaw config set tools.exec.node "<id-or-name>"

/exec host=node security=allowlist node=<id-or-name>

• Node host CLI
• Narzędzie exec
• Exec approvals

​

Wywoływanie poleceń

openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

​

Zrzuty ekranu (snapshoty canvas)

openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

​

Sterowanie Canvas

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
openclaw nodes canvas hide --node <idOrNameOrIp>
openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>
openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

• canvas present akceptuje URL-e lub lokalne ścieżki plików (--target), plus opcjonalne --x/--y/--width/--height dla pozycjonowania.
• canvas eval akceptuje JS inline (--js) lub argument pozycyjny.

​

A2UI (Canvas)

openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
openclaw nodes canvas a2ui reset --node <idOrNameOrIp>

• Obsługiwany jest tylko A2UI v0.8 JSONL (v0.9/createSurface jest odrzucane).

​

Zdjęcia + wideo (kamera node)

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # domyślnie: obie strony (2 linie MEDIA)
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

• Węzeł musi być na pierwszym planie dla canvas.* i camera.* (wywołania w tle zwracają NODE_BACKGROUND_UNAVAILABLE).
• Czas trwania klipu jest ograniczany (obecnie <= 60s), aby uniknąć zbyt dużych ładunków base64.
• Android wyświetli prośbę o uprawnienia CAMERA/RECORD_AUDIO, gdy to możliwe; odrzucone uprawnienia kończą się błędem *_PERMISSION_REQUIRED.

​

Nagrania ekranu (nodes)

openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

• Dostępność screen.record zależy od platformy node.
• Nagrania ekranu są ograniczane do <= 60s.
• --no-audio wyłącza przechwytywanie mikrofonu na obsługiwanych platformach.
• Użyj --screen <index>, aby wybrać ekran, gdy dostępnych jest wiele ekranów.

​

Lokalizacja (nodes)

openclaw nodes location get --node <idOrNameOrIp>
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

• Lokalizacja jest domyślnie wyłączona.
• „Always” wymaga uprawnienia systemowego; pobieranie w tle działa w trybie best-effort.
• Odpowiedź zawiera szer./dł. geograficzną, dokładność (metry) i timestamp.

​

SMS (węzły Android)

openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'

• Prompt uprawnień musi zostać zaakceptowany na urządzeniu Android, zanim capability zostanie ogłoszone.
• Urządzenia tylko z Wi‑Fi bez telefonii nie będą ogłaszać sms.send.

​

Polecenia urządzenia Android + danych osobowych

• device.status, device.info, device.permissions, device.health
• notifications.list, notifications.actions
• photos.latest
• contacts.search, contacts.add
• calendar.events, calendar.add
• callLog.search
• sms.search
• motion.activity, motion.pedometer

openclaw nodes invoke --node <idOrNameOrIp> --command device.status --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command notifications.list --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"limit":1}'

• Polecenia motion są ograniczane przez capability dostępnych sensorów.

​

Polecenia systemowe (host node / mac node)

openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"name":"git"}'

• system.run zwraca stdout/stderr/kod wyjścia w ładunku.
• Wykonanie powłoki przechodzi teraz przez narzędzie exec z host=node; nodes pozostaje bezpośrednią powierzchnią RPC dla jawnych poleceń node.
• nodes invoke nie udostępnia system.run ani system.run.prepare; pozostają one wyłącznie na ścieżce exec.
• Ścieżka exec przygotowuje kanoniczny systemRunPlan przed zatwierdzeniem. Gdy zatwierdzenie zostanie przyznane, gateway przekazuje ten zapisany plan, a nie później edytowane przez wywołującego pola command/cwd/session.
• system.notify respektuje stan uprawnienia do powiadomień w aplikacji macOS.
• Nierozpoznane metadane platform / deviceFamily node używają zachowawczej domyślnej listy dozwolonych poleceń, która wyklucza system.run i system.which. Jeśli celowo potrzebujesz tych poleceń dla nieznanej platformy, dodaj je jawnie przez gateway.nodes.allowCommands.
• system.run obsługuje --cwd, --env KEY=VAL, --command-timeout i --needs-screen-recording.
• Dla wrapperów powłoki (bash|sh|zsh ... -c/-lc) wartości --env o zakresie żądania są redukowane do jawnej listy dozwolonych (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• Dla decyzji allow-always w trybie allowlist znane wrappery dispatch (env, nice, nohup, stdbuf, timeout) utrwalają wewnętrzne ścieżki plików wykonywalnych zamiast ścieżek wrapperów. Jeśli bezpieczne rozpakowanie nie jest możliwe, żaden wpis listy dozwolonych nie jest utrwalany automatycznie.
• Na hostach node Windows w trybie allowlist uruchomienia wrapperów powłoki przez cmd.exe /c wymagają zatwierdzenia (sam wpis allowlist nie powoduje automatycznego zezwolenia na formę wrappera).
• system.notify obsługuje --priority <passive|active|timeSensitive> i --delivery <system|overlay|auto>.
• Hosty node ignorują nadpisania PATH i usuwają niebezpieczne klucze uruchomieniowe/powłoki (DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4). Jeśli potrzebujesz dodatkowych wpisów PATH, skonfiguruj środowisko usługi hosta node (lub zainstaluj narzędzia w standardowych lokalizacjach) zamiast przekazywać PATH przez --env.
• W trybie macOS node system.run jest ograniczane przez exec approvals w aplikacji macOS (Settings → Exec approvals). Ask/allowlist/full działają tak samo jak w headless node host; odrzucone prompty zwracają SYSTEM_RUN_DENIED.
• W headless node host system.run jest ograniczane przez exec approvals (~/.openclaw/exec-approvals.json).

​

Powiązanie exec z node

openclaw config set tools.exec.node "node-id-or-name"

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

openclaw config unset tools.exec.node
openclaw config unset agents.list[0].tools.exec.node

​

Mapa uprawnień

​

Headless node host (wieloplatformowy)

openclaw node run --host <gateway-host> --port 18789

• Parowanie nadal jest wymagane (Gateway pokaże prompt parowania urządzenia).
• Host node przechowuje swój identyfikator node, token, nazwę wyświetlaną i informacje o połączeniu z gateway w ~/.openclaw/node.json.
• Exec approvals są egzekwowane lokalnie przez ~/.openclaw/exec-approvals.json (zobacz Exec approvals).
• Na macOS headless node host domyślnie wykonuje system.run lokalnie. Ustaw OPENCLAW_NODE_EXEC_HOST=app, aby kierować system.run przez exec host aplikacji towarzyszącej; dodaj OPENCLAW_NODE_EXEC_FALLBACK=0, aby wymagać hosta aplikacji i stosować fail-closed, jeśli jest niedostępny.
• Dodaj --tls / --tls-fingerprint, gdy Gateway WS używa TLS.

​

Tryb mac node

• Aplikacja macOS w pasku menu łączy się z serwerem Gateway WS jako node (więc openclaw nodes … działa względem tego Maca).
• W trybie remote aplikacja otwiera tunel SSH dla portu Gateway i łączy się z localhost.