Um node é um dispositivo complementar (macOS/iOS/Android/headless) que se conecta ao WebSocket do Gateway (mesma porta dos operadores) comDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
role: "node" e expõe uma superfície de comandos (por exemplo, canvas.*, camera.*, device.*, notifications.*, system.*) via node.invoke. Detalhes do protocolo: protocolo do Gateway.
Transporte legado: protocolo Bridge (TCP JSONL;
apenas histórico para os nodes atuais).
O macOS também pode ser executado em modo node: o app da barra de menus se conecta ao servidor WS do Gateway e expõe seus comandos locais de canvas/câmera como um node (então openclaw nodes … funciona contra este Mac). No modo de gateway remoto, a automação de navegador é tratada pelo host de node da CLI (openclaw node run ou o serviço de node instalado), não pelo node do app nativo.
Observações:
- Nodes são periféricos, não gateways. Eles não executam o serviço de gateway.
- Mensagens do Telegram/WhatsApp/etc. chegam ao gateway, não aos nodes.
- Runbook de solução de problemas: /nodes/troubleshooting
Pareamento + status
Nodes WS usam pareamento de dispositivo. Nodes apresentam uma identidade de dispositivo duranteconnect; o Gateway cria uma solicitação de pareamento de dispositivo para role: node. Aprove pela CLI de dispositivos (ou pela UI).
CLI rápida:
requestId será criado. Execute novamente openclaw devices list antes de aprovar.
Observações:
nodes statusmarca um node como pareado quando sua função de pareamento de dispositivo incluinode.- O registro de pareamento de dispositivo é o contrato durável de função aprovada. A rotação de token permanece dentro desse contrato; ela não pode promover um node pareado para uma função diferente que a aprovação de pareamento nunca concedeu.
node.pair.*(CLI:openclaw nodes pending/approve/reject/remove/rename) é um armazenamento de pareamento de node separado, pertencente ao gateway; ele não controla o handshake WSconnect.openclaw nodes remove --node <id|name|ip>exclui entradas obsoletas desse armazenamento separado de pareamento de node pertencente ao gateway.- O escopo de aprovação segue os comandos declarados pela solicitação pendente:
- solicitação sem comandos:
operator.pairing - comandos de node sem exec:
operator.pairing+operator.write system.run/system.run.prepare/system.which:operator.pairing+operator.admin
- solicitação sem comandos:
Host de node remoto (system.run)
Use um host de node quando seu Gateway for executado em uma máquina e você quiser que comandos sejam executados em outra. O modelo ainda conversa com o gateway; o gateway encaminha chamadasexec para o host de node quando host=node é selecionado.
O que roda onde
- Host do Gateway: recebe mensagens, executa o modelo, roteia chamadas de ferramentas.
- Host de node: executa
system.run/system.whichna máquina do node. - Aprovações: aplicadas no host de node via
~/.openclaw/exec-approvals.json.
- Execuções de node respaldadas por aprovação vinculam o contexto exato da solicitação.
- Para execuções diretas de arquivos por shell/runtime, o OpenClaw também tenta, em regime de melhor esforço, vincular um operando de arquivo local concreto e nega a execução se esse arquivo mudar antes da execução.
- Se o OpenClaw não conseguir identificar exatamente um arquivo local concreto para um comando de interpretador/runtime, a execução respaldada por aprovação será negada em vez de simular cobertura completa de runtime. Use sandboxing, hosts separados ou uma allowlist/workflow completo explicitamente confiável para semânticas mais amplas de interpretador.
Iniciar um host de node (primeiro plano)
Na máquina do node:Gateway remoto via túnel SSH (bind de loopback)
Se o Gateway fizer bind ao loopback (gateway.bind=loopback, padrão no modo local), hosts de node remotos não conseguem se conectar diretamente. Crie um túnel SSH e aponte o host de node para a extremidade local do túnel.
Exemplo (host de node -> host do gateway):
openclaw node runaceita autenticação por token ou senha.- Variáveis de ambiente são preferidas:
OPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD. - O fallback de configuração é
gateway.auth.token/gateway.auth.password. - No modo local, o host de node ignora intencionalmente
gateway.remote.token/gateway.remote.password. - No modo remoto,
gateway.remote.token/gateway.remote.passwordsão elegíveis conforme as regras de precedência remota. - Se SecretRefs locais ativos
gateway.auth.*estiverem configurados, mas não resolvidos, a autenticação do host de node falha fechada. - A resolução de autenticação do host de node considera apenas variáveis de ambiente
OPENCLAW_GATEWAY_*.
Iniciar um host de node (serviço)
Parear + nomear
No host do gateway:openclaw devices list e aprove o requestId atual.
Opções de nomeação:
--display-nameemopenclaw node run/openclaw node install(persiste em~/.openclaw/node.jsonno node).openclaw nodes rename --node <id|name|ip> --name "Build Node"(substituição no gateway).
Colocar os comandos na allowlist
Aprovações de exec são por host de node. Adicione entradas de allowlist pelo gateway:~/.openclaw/exec-approvals.json.
Apontar exec para o node
Configure os padrões (configuração do gateway):exec com host=node é executada no host de node (sujeita à allowlist/aprovações do node).
host=auto não escolherá implicitamente o node por conta própria, mas uma solicitação explícita por chamada host=node é permitida a partir de auto. Se você quiser que exec no node seja o padrão da sessão, defina tools.exec.host=node ou /exec host=node ... explicitamente.
Relacionado:
Invocando comandos
Baixo nível (RPC bruto):Política de comandos
Comandos de node devem passar por duas barreiras antes de poderem ser invocados:- O node deve declarar o comando em sua lista
connect.commandsdo WebSocket. - A política de plataforma do gateway deve permitir o comando declarado.
canvas.*, camera.list, location.get e screen.snapshot. Nodes confiáveis que anunciam a capacidade talk ou declaram comandos talk.* também permitem, por padrão, comandos push-to-talk declarados (talk.ptt.start, talk.ptt.stop, talk.ptt.cancel, talk.ptt.once), independentemente do rótulo de plataforma. Comandos perigosos ou com grande impacto de privacidade, como camera.snap, camera.clip e screen.record, ainda exigem opt-in explícito com gateway.nodes.allowCommands. gateway.nodes.denyCommands sempre prevalece sobre os padrões e entradas extras de allowlist.
Comandos de node pertencentes a Plugins podem adicionar uma política de node-invoke do Gateway. Essa política é executada após a verificação da allowlist e antes do encaminhamento para o node, então node.invoke bruto, auxiliares de CLI e ferramentas dedicadas de agente compartilham o mesmo limite de permissão do Plugin. Comandos de node perigosos de Plugin ainda exigem opt-in explícito em gateway.nodes.allowCommands.
Depois que um node alterar sua lista de comandos declarados, rejeite o pareamento de dispositivo antigo e aprove a nova solicitação para que o gateway armazene o snapshot de comandos atualizado.
Capturas de tela (snapshots do canvas)
Se o node estiver mostrando o Canvas (WebView),canvas.snapshot retornará { format, base64 }.
Auxiliar de CLI (grava em um arquivo temporário e imprime MEDIA:<path>):
Controles do Canvas
canvas presentaceita URLs ou caminhos de arquivos locais (--target), além de--x/--y/--width/--heightopcionais para posicionamento.canvas evalaceita JS inline (--js) ou um argumento posicional.
A2UI (Canvas)
- Apenas A2UI v0.8 JSONL é compatível (v0.9/createSurface é rejeitado).
Fotos + vídeos (câmera do node)
Fotos (jpg):
mp4):
- O node deve estar em primeiro plano para
canvas.*ecamera.*(chamadas em segundo plano retornamNODE_BACKGROUND_UNAVAILABLE). - A duração do clipe é limitada (atualmente
<= 60s) para evitar payloads base64 muito grandes. - O Android solicitará permissões
CAMERA/RECORD_AUDIOquando possível; permissões negadas falham com*_PERMISSION_REQUIRED.
Gravações de tela (nodes)
Nodes compatíveis expõemscreen.record (mp4). Exemplo:
- A disponibilidade de
screen.recorddepende da plataforma do node. - Gravações de tela são limitadas a
<= 60s. --no-audiodesativa a captura do microfone em plataformas compatíveis.- Use
--screen <index>para selecionar uma tela quando várias telas estiverem disponíveis.
Localização (nodes)
Nodes expõemlocation.get quando Localização está ativada nas configurações.
Auxiliar de CLI:
- Localização fica desativada por padrão.
- “Sempre” requer permissão do sistema; busca em segundo plano é feita em regime de melhor esforço.
- A resposta inclui lat/lon, precisão (metros) e carimbo de data/hora.
SMS (nodes Android)
Nodes Android podem exporsms.send quando o usuário concede permissão de SMS e o dispositivo oferece suporte a telefonia.
Invocação de baixo nível:
- A solicitação de permissão deve ser aceita no dispositivo Android antes que a capacidade seja anunciada.
- Dispositivos somente Wi-Fi sem telefonia não anunciarão
sms.send.
Dispositivo Android + comandos de dados pessoais
Nodes Android podem anunciar famílias adicionais de comandos quando as capacidades correspondentes estão ativadas. Famílias disponíveis:device.status,device.info,device.permissions,device.healthnotifications.list,notifications.actionsphotos.latestcontacts.search,contacts.addcalendar.events,calendar.addcallLog.searchsms.searchmotion.activity,motion.pedometer
- Os comandos de movimento são controlados por capacidade, conforme os sensores disponíveis.
Comandos do sistema (host de Node / Node Mac)
O Node macOS expõesystem.run, system.notify e system.execApprovals.get/set.
O host de Node headless expõe system.run, system.which e system.execApprovals.get/set.
Exemplos:
system.runretorna stdout/stderr/código de saída no payload.- A execução de shell agora passa pela ferramenta
execcomhost=node;nodescontinua sendo a superfície de RPC direto para comandos explícitos de Node. nodes invokenão expõesystem.runnemsystem.run.prepare; eles permanecem apenas no caminho de exec.- O caminho de exec prepara um
systemRunPlancanônico antes da aprovação. Depois que uma aprovação é concedida, o Gateway encaminha esse plano armazenado, não quaisquer campos command/cwd/session editados posteriormente pelo chamador. system.notifyrespeita o estado de permissão de notificações no app macOS.- Metadados de Node
platform/deviceFamilynão reconhecidos usam uma allowlist padrão conservadora que excluisystem.runesystem.which. Se você precisar intencionalmente desses comandos para uma plataforma desconhecida, adicione-os explicitamente viagateway.nodes.allowCommands. system.runaceita--cwd,--env KEY=VAL,--command-timeoute--needs-screen-recording.- Para wrappers de shell (
bash|sh|zsh ... -c/-lc), valores--envcom escopo de requisição são reduzidos a uma allowlist explícita (TERM,LANG,LC_*,COLORTERM,NO_COLOR,FORCE_COLOR). - Para decisões de sempre permitir em modo allowlist, wrappers de despacho conhecidos (
env,nice,nohup,stdbuf,timeout) persistem caminhos de executáveis internos em vez de caminhos de wrappers. Se desembrulhar não for seguro, nenhuma entrada de allowlist será persistida automaticamente. - Em hosts de Node Windows no modo allowlist, execuções de wrapper de shell via
cmd.exe /cexigem aprovação (a entrada de allowlist sozinha não permite automaticamente o formato de wrapper). system.notifyaceita--priority <passive|active|timeSensitive>e--delivery <system|overlay|auto>.- Hosts de Node ignoram substituições de
PATHe removem chaves perigosas de inicialização/shell (DYLD_*,LD_*,NODE_OPTIONS,PYTHON*,PERL*,RUBYOPT,SHELLOPTS,PS4). Se você precisar de entradas extras em PATH, configure o ambiente do serviço do host de Node (ou instale ferramentas em locais padrão) em vez de passarPATHvia--env. - No modo Node macOS,
system.runé controlado por aprovações de exec no app macOS (Ajustes → Aprovações de exec). Ask/allowlist/full se comportam da mesma forma que o host de Node headless; prompts negados retornamSYSTEM_RUN_DENIED. - No host de Node headless,
system.runé controlado por aprovações de exec (~/.openclaw/exec-approvals.json).
Vinculação de Node exec
Quando vários Nodes estão disponíveis, você pode vincular exec a um Node específico. Isso define o Node padrão paraexec host=node (e pode ser substituído por agente).
Padrão global:
Mapa de permissões
Nodes podem incluir um mapapermissions em node.list / node.describe, indexado pelo nome da permissão (por exemplo, screenRecording, accessibility) com valores booleanos (true = concedida).
Host de Node headless (multiplataforma)
O OpenClaw pode executar um host de Node headless (sem UI) que se conecta ao WebSocket do Gateway e expõesystem.run / system.which. Isso é útil no Linux/Windows
ou para executar um Node mínimo junto de um servidor.
Inicie-o:
- O pareamento ainda é obrigatório (o Gateway mostrará um prompt de pareamento de dispositivo).
- O host de Node armazena seu id de Node, token, nome de exibição e informações de conexão do Gateway em
~/.openclaw/node.json. - Aprovações de exec são aplicadas localmente via
~/.openclaw/exec-approvals.json(consulte Aprovações de exec). - No macOS, o host de Node headless executa
system.runlocalmente por padrão. DefinaOPENCLAW_NODE_EXEC_HOST=apppara rotearsystem.runpelo host de exec do app complementar; adicioneOPENCLAW_NODE_EXEC_FALLBACK=0para exigir o host do app e falhar fechado se ele não estiver disponível. - Adicione
--tls/--tls-fingerprintquando o WS do Gateway usar TLS.
Modo Node Mac
- O app de barra de menus do macOS se conecta ao servidor WS do Gateway como um Node (então
openclaw nodes …funciona nesse Mac). - No modo remoto, o app abre um túnel SSH para a porta do Gateway e se conecta a
localhost.