Węzły

​

Parowanie i stan

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

• nodes status oznacza Node jako sparowany, gdy jego rola w parowaniu urządzenia obejmuje node.
• Połączony natywny Mac z uprawnieniem Dostępność może zgłaszać zagregowaną aktywność fizycznych urządzeń wejściowych. Gateway oznacza najświeższy kwalifikujący się Mac jako active, przekazuje agentowi stabilną wskazówkę identyfikatora Node i kieruje tam alerty o połączeniu Node przed opóźnionym użyciem rozwiązania zapasowego. Informacje o konfiguracji, prywatności, czasach i rozwiązywaniu problemów zawiera sekcja Obecność aktywnego komputera.
• Rekord parowania urządzenia stanowi trwałą umowę zatwierdzonych ról. Rotacja tokenu odbywa się w granicach tej umowy; nie może nadać sparowanemu Node’owi roli, której nigdy nie przyznano podczas zatwierdzania parowania.
• node.pair.* (CLI: openclaw nodes pending/approve/reject/remove/rename) to osobny, należący do Gateway magazyn parowania Node’ów, który między ponownymi połączeniami śledzi zatwierdzony interfejs poleceń i możliwości Node’a. Nie kontroluje uwierzytelniania transportu — odpowiada za to parowanie urządzeń.
• openclaw nodes remove --node <id|name|ip> usuwa parowanie Node’a. W przypadku Node’a powiązanego z urządzeniem unieważnia rolę node urządzenia w magazynie sparowanych urządzeń i rozłącza sesje tego urządzenia z rolą Node’a: urządzenie z wieloma rolami zachowuje swój wiersz i traci tylko rolę node, natomiast wiersz urządzenia mającego wyłącznie rolę Node’a zostaje usunięty. Usuwa również wszystkie pasujące wpisy z osobnego magazynu parowania Node’ów. operator.pairing może usuwać wiersze Node’ów niebędących operatorami na innych urządzeniach; wywołujący używający tokenu urządzenia, który unieważnia własną rolę Node’a na urządzeniu z wieloma rolami, potrzebuje dodatkowo operator.admin.
• Zakres zatwierdzenia wynika z poleceń zadeklarowanych w oczekującym żądaniu:
  • żądanie bez poleceń: operator.pairing
  • polecenia Node’a inne niż exec: operator.pairing + operator.write
  • system.run / system.run.prepare / system.which: operator.pairing + operator.admin

​

Rozbieżność wersji i kolejność aktualizacji

​

Zdalny host Node (system.run)

• Uruchomienia Node’a wymagające zatwierdzenia są powiązane z dokładnym kontekstem żądania. Ścieżka exec przygotowuje kanoniczny systemRunPlan przed zatwierdzeniem; po jego udzieleniu Gateway przekazuje zapisany plan, a nie zmodyfikowane później przez wywołującego pola polecenia/cwd/sesji, i ponownie sprawdza katalog roboczy przed uruchomieniem.
• W przypadku bezpośrednich wykonań plików przez powłokę/środowisko wykonawcze OpenClaw podejmuje również najlepszą możliwą próbę powiązania jednego konkretnego lokalnego operandu plikowego i odrzuca uruchomienie, jeśli plik zmieni się przed wykonaniem.
• Jeśli OpenClaw nie może zidentyfikować dokładnie jednego konkretnego pliku lokalnego dla polecenia interpretera/środowiska wykonawczego, wykonanie wymagające zatwierdzenia zostaje odrzucone zamiast pozorowania pełnego pokrycia środowiska wykonawczego. W przypadku szerszej semantyki interpretera należy użyć piaskownicy, osobnych hostów albo jawnej zaufanej listy dozwolonych elementów/pełnego przepływu pracy.

​

Uruchamianie hosta Node (na pierwszym planie)

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

​

Zdalny Gateway przez tunel SSH (powiązanie z interfejsem loopback)

# Terminal A (pozostawić uruchomiony): przekierowanie lokalnego portu 18790 -> Gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: wyeksportowanie tokenu Gateway i połączenie 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 środowiskowe: OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD.
• Zapasową konfiguracją jest gateway.auth.token / gateway.auth.password.
• W trybie lokalnym host Node celowo ignoruje gateway.remote.token / gateway.remote.password.
• W trybie zdalnym gateway.remote.token / gateway.remote.password kwalifikują się zgodnie z regułami pierwszeństwa trybu zdalnego.
• Jeśli skonfigurowano aktywne lokalne odwołania SecretRefs gateway.auth.*, ale nie można ich rozpoznać, uwierzytelnianie hosta Node zostaje bezpiecznie odrzucone.
• Rozpoznawanie uwierzytelniania hosta Node uwzględnia wyłącznie zmienne środowiskowe OPENCLAW_GATEWAY_*.

​

Uruchamianie hosta Node (jako usługi)

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

​

Parowanie i nadawanie nazwy

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

• --display-name w openclaw node run / openclaw node install (utrwalane we współdzielonym wierszu SQLite node_host_config wraz z identyfikatorem instancji klienta i metadanymi połączenia Gateway).
• openclaw nodes rename --node <id|name|ip> --name "Build Node" (nadpisanie w Gateway).

​

Serwery MCP hostowane na Node

{
  nodeHost: {
    mcp: {
      servers: {
        localDocs: {
          command: "npx",
          args: ["-y", "@modelcontextprotocol/server-filesystem", "/srv/docs"],
          toolFilter: {
            include: ["read_*", "search"],
          },
        },
        internalApi: {
          url: "https://mcp.internal.example/mcp",
          transport: "streamable-http",
          headers: {
            Authorization: "Bearer ${INTERNAL_MCP_TOKEN}",
          },
        },
      },
    },
  },
}

​

Skills hostowane na Node

​

Stan tożsamości bez interfejsu graficznego

• ~/.openclaw/state/openclaw.sqlite (node_host_config): identyfikator instancji klienta, nazwa wyświetlana i metadane połączenia z Gateway.
• ~/.openclaw/identity/device.json: podpisana para kluczy urządzenia i wyprowadzony kryptograficzny identyfikator urządzenia.
• ~/.openclaw/identity/device-auth.json: tokeny uwierzytelniania sparowanych urządzeń indeksowane według kryptograficznego identyfikatora urządzenia i roli.

​

Dodawanie poleceń 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"

​

Kierowanie wykonywania do węzła

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>

• CLI hosta węzła
• Narzędzie wykonywania
• Zatwierdzenia wykonywania

​

Lokalne wnioskowanie modelu

​

Sesje i transkrypcje Codex

​

Sesje i transkrypcje Claude

{
  nodeHost: {
    agentRuns: {
      claude: { enabled: true },
    },
  },
}

​

Sesje OpenCode i Pi

​

Przesyłanie plików do terminala

​

Wywoływanie poleceń

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

​

Zasady poleceń

1. Węzeł musi zadeklarować polecenie w swoich uwierzytelnionych metadanych połączenia (connect.commands).
2. Lista dozwolonych poleceń Gateway, wynikająca z platformy i zatwierdzenia, musi zawierać zadeklarowane polecenie.

​

Konfiguracja (openclaw.json)

{
  gateway: {
    nodes: {
      // Automatycznie zatwierdzaj pierwsze parowanie węzła z zaufanych sieci (lista CIDR).
      // Wyłączone, gdy nie ustawiono. Dotyczy tylko pierwszych żądań role:node
      // bez żądanych zakresów; nie zatwierdza automatycznie uaktualnień.
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
        // Automatyczne zatwierdzanie zweryfikowane przez SSH (domyślnie: włączone). Zatwierdza pierwsze
        // parowanie węzła przy dokładnej zgodności klucza urządzenia odczytanego zwrotnie przez SSH.
        sshVerify: true,
      },
      // Ufaj widocznym dla agenta narzędziom pluginów publikowanym przez sparowane węzły (domyślnie: true).
      pluginTools: {
        enabled: true,
      },
      // Włącz niebezpieczne lub silnie ingerujące w prywatność polecenia węzła (camera.snap itp.).
      allowCommands: ["camera.snap", "screen.record"],
      // Blokuj dokładne nazwy poleceń, nawet jeśli zawierają je wartości domyślne lub allowCommands.
      denyCommands: ["camera.clip"],
    },
  },
  tools: {
    exec: {
      // Domyślny host wykonywania: "node" kieruje wszystkie wywołania exec do sparowanego węzła.
      host: "node",
      // Tryb zabezpieczeń wykonywania na węźle: zezwalaj tylko na zatwierdzone polecenia z listy dozwolonych.
      security: "allowlist",
      // Przypisz wykonywanie do określonego węzła (identyfikatora lub nazwy). Pomiń, aby zezwolić na dowolny węzeł.
      node: "build-node",
    },
  },
}

{
  agents: {
    list: [
      {
        id: "main",
        tools: { exec: { node: "build-node" } },
      },
    ],
  },
}

​

Zrzuty ekranu (migawki Canvas)

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

​

Elementy sterujące 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 przyjmuje adresy URL lub lokalne ścieżki plików (--target) na węzłach obsługujących lokalne ścieżki, a także opcjonalne --x/--y/--width/--height do pozycjonowania. Canvas w systemie Linux przyjmuje adresy URL HTTP(S) lub dołączony do niego mechanizm renderujący A2UI.
• canvas eval przyjmuje kod JS podany bezpośrednio (--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>

• Węzły mobilne i komputerowe w systemie Linux używają dołączonej, należącej do aplikacji strony A2UI do renderowania z obsługą akcji.
• Obsługiwany jest tylko format JSONL A2UI v0.8 (v0.9/createSurface jest odrzucany).
• Systemy iOS i Android renderują zdalne strony Canvas Gateway, ale akcje przycisków A2UI są wysyłane tylko z dołączonej, należącej do aplikacji strony A2UI. Strony A2UI HTTP/HTTPS hostowane przez Gateway na tych klientach mobilnych służą wyłącznie do renderowania.
• System macOS może wysyłać akcje z dokładnej strony A2UI Gateway o zakresie określonym przez możliwości, wybranej przez aplikację. Inne strony HTTP/HTTPS służą wyłącznie do renderowania.
• System Linux wysyła akcje tylko z dołączonej strony A2UI. Inne strony HTTP/HTTPS służą wyłącznie do renderowania, a bezinterfejsowy węzeł Linux bez aplikacji komputerowej nie ogłasza Canvas.

​

Zdjęcia i filmy (kamera węzła)

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # domyślnie: oba kierunki kamery (2 wiersze MEDIA)
openclaw nodes camera snap --node <idOrNameOrIp> --facing front
openclaw nodes camera snap --node <idOrNameOrIp> --device-id <id> --max-width 1200 --quality 0.9 --delay-ms 2000

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

• Węzeł musi znajdować się na pierwszym planie dla canvas.* i camera.* (wywołania w tle zwracają NODE_BACKGROUND_UNAVAILABLE).
• Węzły ograniczają czas trwania klipu, aby zachować rozsądny rozmiar ładunku base64 (dokładne limity dla poszczególnych platform zawiera strona Przechwytywanie obrazu z kamery). Narzędzie agenta nodes dodatkowo ogranicza żądaną wartość durationMs do 300000 (5 minut) przed przekazaniem wywołania; sam węzeł egzekwuje bardziej rygorystyczny limit.
• Android wyświetli prośbę o uprawnienia CAMERA/RECORD_AUDIO, gdy będzie to możliwe; odrzucenie uprawnień powoduje błąd *_PERMISSION_REQUIRED.

​

Nagrania ekranu (węzły)

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 węzła.
• Narzędzie agenta nodes ogranicza żądaną wartość durationMs do 300000 (5 minut); węzeł może wymusić niższy limit, aby ograniczyć rozmiar zwracanego ładunku.
• --no-audio wyłącza przechwytywanie dźwięku z mikrofonu na obsługiwanych platformach.
• Gdy dostępnych jest wiele ekranów, użyj --screen <index>, aby wybrać ekran (0 = główny).

​

Lokalizacja (węzły)

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.
• Opcja „Always” wymaga uprawnienia systemowego; pobieranie w tle odbywa się w miarę możliwości.
• Odpowiedź zawiera szerokość i długość geograficzną, dokładność (w metrach) oraz znacznik czasu.
• Pełny format parametrów i odpowiedzi oraz kody błędów: Polecenie lokalizacji.

​

SMS (węzły Android)

{
  gateway: {
    nodes: {
      allowCommands: ["sms.search"],
    },
  },
}

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

• sms.search można zadeklarować przed przyznaniem READ_SMS, aby wywołanie mogło zwrócić diagnostykę uprawnień; odczytywanie wiadomości nadal wymaga tego uprawnienia systemu Android.
• Urządzenia działające wyłącznie przez Wi-Fi i nieobsługujące telefonii nie będą zgłaszać sms.send.
• Błąd requires explicit gateway.nodes.allowCommands opt-in oznacza, że telefon zadeklarował polecenie, ale operator Gateway go nie autoryzował.

​

Polecenia dotyczące urządzenia i danych osobowych

• device.status, device.info — iOS, Android, Windows.
• device.permissions, device.health, device.apps — tylko Android; device.apps wymaga włączenia udostępniania zainstalowanych aplikacji w ustawieniach systemu Android i domyślnie zwraca aplikacje widoczne w programie uruchamiającym.
• notifications.list, notifications.actions — tylko Android.
• photos.latest — iOS, Android.
• contacts.search — iOS, Android (domyślnie tylko do odczytu); contacts.add jest niebezpieczne i wymaga gateway.nodes.allowCommands.
• calendar.events — iOS, Android (domyślnie tylko do odczytu); calendar.add jest niebezpieczne i wymaga gateway.nodes.allowCommands.
• reminders.list — iOS, Android (domyślnie tylko do odczytu); reminders.add jest niebezpieczne i wymaga gateway.nodes.allowCommands.
• callLog.search — tylko Android.
• motion.activity, motion.pedometer — iOS, Android; dostępność zależy od dostępnych czujników.

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

​

Polecenia systemowe (host węzła / węzeł Mac)

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

• system.run zwraca w ładunku standardowe wyjście, standardowe wyjście błędów oraz kod wyjścia.
• Wykonywanie poleceń powłoki odbywa się teraz za pośrednictwem narzędzia exec z host=node; nodes pozostaje bezpośrednim interfejsem RPC dla jawnych poleceń węzła.
• nodes invoke nie udostępnia system.run ani system.run.prepare; są one dostępne wyłącznie w ścieżce wykonywania.
• Ścieżka wykonywania przygotowuje kanoniczny systemRunPlan przed zatwierdzeniem. Po udzieleniu zatwierdzenia Gateway przekazuje zapisany plan, a nie pola polecenia, katalogu roboczego ani sesji zmodyfikowane później przez wywołującego.
• system.notify uwzględnia stan uprawnień do powiadomień w aplikacji macOS; obsługuje --priority <passive|active|timeSensitive> i --delivery <system|overlay|auto>.
• Nierozpoznane metadane platform / deviceFamily węzła korzystają z zachowawczej domyślnej listy dozwolonych elementów, która wyklucza system.run i system.which. Jeśli te polecenia są celowo potrzebne na nieznanej platformie, należy dodać je jawnie za pomocą gateway.nodes.allowCommands.
• system.run obsługuje --cwd, --env KEY=VAL, --command-timeout i --needs-screen-recording.
• W przypadku nakładek powłoki (bash|sh|zsh ... -c/-lc) wartości --env o zakresie żądania są ograniczane do jawnej listy dozwolonych elementów (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• W przypadku decyzji „zawsze zezwalaj” w trybie listy dozwolonych elementów znane nakładki przekazujące (env, flock, nice, nohup, stdbuf, timeout) zapisują ścieżki wewnętrznych plików wykonywalnych zamiast ścieżek nakładek. Jeśli bezpieczne usunięcie nakładki nie jest możliwe, żaden wpis nie jest automatycznie zapisywany na liście dozwolonych elementów.
• Na hostach węzłów Windows działających w trybie listy dozwolonych elementów uruchamianie za pośrednictwem nakładki powłoki cmd.exe /c wymaga zatwierdzenia (sam wpis na liście dozwolonych elementów nie zezwala automatycznie na użycie nakładki).
• Hosty węzłów ignorują nadpisania PATH w --env i przed uruchomieniem polecenia usuwają duży, utrzymywany zestaw zmiennych uruchomieniowych interpretera lub powłoki (na przykład NODE_OPTIONS, PYTHONPATH, BASH_ENV, DYLD_*, LD_*). Jeśli potrzebne są dodatkowe wpisy PATH, należy skonfigurować środowisko usługi hosta węzła (lub zainstalować narzędzia w standardowych lokalizacjach), zamiast przekazywać PATH za pośrednictwem --env.
• W trybie węzła macOS system.run podlega zatwierdzeniom wykonywania w aplikacji macOS (Settings → Exec approvals). Tryby pytania, listy dozwolonych elementów i pełnego dostępu działają tak samo jak w bezinterfejsowym hoście węzła; odrzucone monity zwracają SYSTEM_RUN_DENIED.
• W bezinterfejsowym hoście węzła system.run podlega zatwierdzeniom wykonywania (~/.openclaw/exec-approvals.json); w przypadku systemu macOS zobacz poniżej zmienne środowiskowe kierowania hosta wykonywania w sekcji Bezinterfejsowy host węzła.

​

Powiązanie węzła wykonywania

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ń

​

Bezinterfejsowy host węzła (wieloplatformowy)

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

• Parowanie jest nadal wymagane (Gateway wyświetli monit o parowanie urządzenia).
• Metadane instancji klienta, podpisana tożsamość urządzenia i uwierzytelnianie parowania korzystają z osobnych plików; zobacz Stan tożsamości bezinterfejsowej.
• Zatwierdzenia wykonywania są wymuszane lokalnie za pośrednictwem ~/.openclaw/exec-approvals.json (zobacz Zatwierdzenia wykonywania).
• W systemie macOS bezinterfejsowy host węzła domyślnie wykonuje system.run lokalnie. Ustaw OPENCLAW_NODE_EXEC_HOST=app, aby kierować system.run przez host wykonywania aplikacji towarzyszącej; dodaj OPENCLAW_NODE_EXEC_FALLBACK=0, aby wymagać hosta aplikacji i bezpiecznie przerwać działanie, jeśli jest niedostępny.
• Dodaj --tls / --tls-fingerprint, gdy WebSocket Gateway korzysta z TLS.

​

Tryb węzła Mac

• Aplikacja paska menu systemu macOS łączy się z serwerem WebSocket Gateway jako węzeł (dzięki czemu openclaw nodes … działa na tym komputerze Mac).
• W trybie zdalnym aplikacja otwiera tunel SSH dla portu Gateway i łączy się z localhost.