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 de 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 (assim
openclaw nodes … funciona contra este Mac). No modo de gateway remoto, a automação
do 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 via CLI de dispositivos (ou UI).
CLI rápida:
requestId é 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 a uma função diferente que a aprovação de pareamento nunca concedeu.
node.pair.*(CLI:openclaw nodes pending/approve/reject/remove/rename) é um armazenamento separado de pareamento de nodes pertencente ao gateway; ele não bloqueia o handshake WSconnect.openclaw nodes remove --node <id|name|ip>exclui entradas obsoletas desse armazenamento separado de pareamento de nodes 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 é executado em uma máquina e você quer que comandos sejam executados em outra. O modelo ainda conversa com o gateway; o gateway encaminha chamadasexec ao 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 baseadas em aprovação vinculam o contexto exato da solicitação.
- Para execuções diretas de arquivos de shell/runtime, o OpenClaw também faz o melhor esforço para 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 baseada em aprovação é negada em vez de fingir cobertura completa de runtime. Use sandboxing, hosts separados ou uma allowlist/workflow completo confiável explícito 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 podem 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 runoferece suporte a 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
gateway.auth.*locais ativos 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 honra 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 nomenclatura:
--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 pelo gateway).
Colocar os comandos na allowlist
Aprovações de exec são por host de node. Adicione entradas de allowlist a partir do gateway:~/.openclaw/exec-approvals.json.
Apontar exec para o node
Configure os padrões (configuração do gateway):exec com host=node roda 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 em 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 precisam passar por dois controles antes que possam ser invocados:- O node deve declarar o comando na lista
connect.commandsdo WebSocket. - A política de plataforma do gateway deve permitir o comando declarado.
canvas.*, camera.list, location.get e screen.snapshot por padrão.
Comandos perigosos ou com alto 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
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
roda depois da verificação de allowlist e antes do encaminhamento para o node, então RPC bruto
node.invoke, auxiliares da CLI e ferramentas de agente dedicadas compartilham o mesmo limite de permissão
do Plugin. Comandos de node perigosos de Plugin ainda exigem opt-in explícito de
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 de canvas)
Se o node estiver exibindo o Canvas (WebView),canvas.snapshot retorna { format, base64 }.
Auxiliar da 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 grandes demais. - 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á habilitada nas configurações.
Auxiliar da CLI:
- Localização fica desativada por padrão.
- “Sempre” exige permissão do sistema; busca em segundo plano é feita em melhor esforço.
- A resposta inclui lat/lon, precisão (metros) e timestamp.
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:
- O prompt de permissão deve ser aceito no dispositivo Android antes que a capacidade seja anunciada.
- Dispositivos somente Wi-Fi sem telefonia não anunciarão
sms.send.
Comandos de dispositivo Android + dados pessoais
Nodes Android podem anunciar famílias de comandos adicionais quando as capacidades correspondentes estão habilitadas. 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
- 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 sem interface gráfica 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 RPC direta 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 de comando/cwd/sessão editados posteriormente pelo chamador. system.notifyrespeita o estado de permissão de notificações no aplicativo macOS.- Metadados de Node
platform/deviceFamilynão reconhecidos usam uma lista de permissões padrão conservadora que excluisystem.runesystem.which. Se você precisar intencionalmente desses comandos para uma plataforma desconhecida, adicione-os explicitamente viagateway.nodes.allowCommands. system.runoferece suporte a--cwd,--env KEY=VAL,--command-timeoute--needs-screen-recording.- Para wrappers de shell (
bash|sh|zsh ... -c/-lc), valores--envcom escopo de solicitação são reduzidos a uma lista de permissões explícita (TERM,LANG,LC_*,COLORTERM,NO_COLOR,FORCE_COLOR). - Para decisões de sempre permitir no modo de lista de permissões, wrappers de despacho conhecidos (
env,nice,nohup,stdbuf,timeout) persistem os caminhos dos executáveis internos em vez dos caminhos dos wrappers. Se o desempacotamento não for seguro, nenhuma entrada de lista de permissões será persistida automaticamente. - Em hosts de Node Windows no modo de lista de permissões, execuções de wrapper de shell via
cmd.exe /cexigem aprovação (a entrada de lista de permissões sozinha não permite automaticamente a forma com wrapper). system.notifyoferece suporte a--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 de serviço do host de Node (ou instale ferramentas em locais padrão) em vez de passarPATHvia--env. - No modo de Node macOS,
system.runé controlado por aprovações de exec no aplicativo macOS (Ajustes → Aprovações de exec). Solicitar/lista de permissões/completo se comportam da mesma forma que no host de Node sem interface gráfica; prompts negados retornamSYSTEM_RUN_DENIED. - No host de Node sem interface gráfica,
system.runé controlado por aprovações de exec (~/.openclaw/exec-approvals.json).
Vinculação de Node de 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 sem interface (multiplataforma)
O OpenClaw pode executar um host de Node sem interface (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 a um servidor.
Inicie-o:
- O pareamento ainda é obrigatório (o Gateway exibirá um prompt de pareamento de dispositivo).
- O host de Node armazena seu ID do Node, token, nome de exibição e informações de conexão com o Gateway em
~/.openclaw/node.json. - As aprovações de execução são aplicadas localmente via
~/.openclaw/exec-approvals.json(consulte Aprovações de execução). - No macOS, o host de Node sem interface executa
system.runlocalmente por padrão. DefinaOPENCLAW_NODE_EXEC_HOST=apppara rotearsystem.runpelo host de execução do app companion; adicioneOPENCLAW_NODE_EXEC_FALLBACK=0para exigir o host do app e falhar de forma fechada se ele estiver indisponível. - Adicione
--tls/--tls-fingerprintquando o WS do Gateway usar TLS.
Modo de Node no Mac
- O app de barra de menus do macOS se conecta ao servidor WS do Gateway como um Node (para que
openclaw nodes …funcione com este Mac). - No modo remoto, o app abre um túnel SSH para a porta do Gateway e se conecta a
localhost.