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 nodes atuais).
O macOS também pode executar 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 (para que
openclaw nodes … funcione 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 de 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 a função de pareamento do dispositivo incluinode.- O registro de pareamento do dispositivo é o contrato durável de função aprovada. A rotação de tokens 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 separado de pareamento de nodes pertencente ao gateway; ele não controla o handshake WSconnect.openclaw nodes remove --node <id|name|ip>remove um pareamento de node. Para um node respaldado por dispositivo, ele revoga a funçãonodedo dispositivo emdevices/paired.jsone desconecta as sessões desse dispositivo com função de node — um dispositivo de função mista mantém sua linha e perde apenas a funçãonode, enquanto uma linha de dispositivo apenas node é excluída. Ele também limpa qualquer entrada correspondente do armazenamento separado de pareamento de nodes pertencente ao gateway.operator.pairingpode remover linhas de node que não sejam de operador; um chamador com token de dispositivo que revoga sua própria função de node em um dispositivo de função mista também precisa deoperator.admin.- O escopo de aprovação segue os comandos declarados da solicitação pendente:
- solicitação sem comandos:
operator.pairing - comandos de node não 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 roda em uma máquina e você quer 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 ferramenta.
- 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 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 do runtime. Use sandboxing, hosts separados ou uma allowlist confiável explícita/fluxo completo 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 em loopback (gateway.bind=loopback, padrão no modo local),
hosts de node remotos não conseguirão 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 locais ativos
gateway.auth.*estiverem configurados, mas não resolvidos, a autenticação do host de node falhará 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 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 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 quiser que exec em node seja o padrão da sessão, defina explicitamente tools.exec.host=node ou /exec host=node ....
Relacionado:
Inferência local de modelo
Um node desktop ou servidor pode expor modelos compatíveis com chat de um servidor Ollama em execução nesse node. Agentes usam a ferramentanode_inference do Plugin Ollama para
descobrir modelos instalados e executar um prompt limitado remotamente; o Gateway
não precisa de acesso direto de rede ao Ollama. Consulte inferência local de node do Ollama
para configuração, filtragem de modelos e comandos de verificação direta.
Invocar comandos
Baixo nível (RPC bruto):Política de comandos
Comandos de node precisam passar por dois controles antes de poderem ser invocados:- O node precisa declarar o comando em sua lista WebSocket
connect.commands. - A política de plataforma do gateway precisa permitir o comando declarado.
canvas.*, camera.list, location.get e screen.snapshot por padrão.
Nodes confiáveis que anunciam a capacidade talk ou declaram comandos talk.*
também permitem comandos declarados de push-to-talk (talk.ptt.start, talk.ptt.stop,
talk.ptt.cancel, talk.ptt.once) por padrão, independentemente do rótulo de plataforma.
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 adicionais da allowlist.
Comandos de node pertencentes a Plugins podem adicionar uma política de node-invoke do Gateway. Essa política
roda após a verificação da allowlist e antes do encaminhamento ao node, então o
node.invoke bruto, os helpers da CLI e ferramentas dedicadas de agente compartilham o mesmo
limite de permissão do Plugin. Comandos perigosos de node de Plugin ainda exigem opt-in explícito em
gateway.nodes.allowCommands.
Depois que um node altera 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.
Configuração (openclaw.json)
Configurações relacionadas a nodes ficam em gateway.nodes e tools.exec:
denyCommands remove um comando mesmo quando um
padrão de plataforma ou entrada allowCommands o permitiria de outra forma. Consulte a
referência de configuração do Gateway
para detalhes dos campos de pareamento de nodes do gateway e política de comandos.
Substituição de node exec por agente:
Capturas de tela (snapshots do canvas)
Se o node estiver exibindo o Canvas (WebView),canvas.snapshot retornará { format, base64 }.
Helper da CLI (grava em um arquivo temporário e imprime o caminho salvo):
Controles de 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)
- Nodes móveis usam uma página A2UI agrupada e pertencente ao app para renderização com suporte a ações.
- Somente A2UI v0.8 JSONL é compatível (v0.9/createSurface é rejeitado).
- iOS e Android renderizam páginas remotas do Gateway Canvas, mas ações de botão A2UI são despachadas somente a partir da página A2UI agrupada e pertencente ao app. Páginas A2UI HTTP/HTTPS hospedadas pelo Gateway são somente renderização nesses clientes móveis.
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” requer permissão do sistema; a busca em segundo plano é feita por 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:
- 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.
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.healthdevice.appsquando o compartilhamento de apps instalados está habilitado nas Configurações do Androidnotifications.list,notifications.actionsphotos.latestcontacts.search,contacts.addcalendar.events,calendar.addcallLog.searchsms.searchmotion.activity,motion.pedometer
device.appsé opt-in e retorna apps visíveis no launcher por padrão.- Comandos de movimento são protegidos por capacidade conforme os sensores disponíveis.
Comandos do sistema (host do Node / Node Mac)
O Node macOS expõesystem.run, system.notify e system.execApprovals.get/set.
O host Node sem interface 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 somente 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 da permissão de notificação 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 permitir sempre no modo allowlist, wrappers de despacho conhecidos (
env,flock,nice,nohup,stdbuf,timeout) persistem caminhos de executáveis internos em vez de caminhos de wrapper. Se o desembrulhamento não for seguro, nenhuma entrada de allowlist será persistida automaticamente. - Em hosts 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 a forma de wrapper). system.notifyaceita--priority <passive|active|timeSensitive>e--delivery <system|overlay|auto>.- Hosts Node ignoram substituições de
PATHe removem chaves perigosas de inicialização/shell (DYLD_*,LD_*,BASHOPTS,FPATH,KSH_ENV,NODE_OPTIONS,NODE_REDIRECT_WARNINGS,NODE_REPL_EXTERNAL_MODULE,NODE_REPL_HISTORY,NODE_V8_COVERAGE,PYTHON*,PERL*,RUBYOPT,SHELLOPTS,PS4,TCLLIBPATH). Se você precisar de entradas extras em PATH, configure o ambiente do serviço do host Node (ou instale ferramentas em locais padrão) em vez de passarPATHvia--env. - No modo Node do macOS,
system.runé protegido por aprovações de exec no app macOS (Configurações → Aprovações de exec). Ask/allowlist/full se comportam da mesma forma que o host Node sem interface; prompts negados retornamSYSTEM_RUN_DENIED. - No host Node sem interface,
system.runé protegido por aprovações de exec (~/.openclaw/exec-approvals.json).
Vinculação de Node para 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 por nome de permissão (por exemplo, screenRecording, accessibility) com valores booleanos (true = concedida).
Host Node sem interface (multiplataforma)
O OpenClaw pode executar um host 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 é necessário (o Gateway mostrará uma solicitação de pareamento de dispositivo).
- O host 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 Node sem interface 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 estiver indisponível. - Adicione
--tls/--tls-fingerprintquando o WS do Gateway usar TLS.
Modo Node do Mac
- O app de barra de menu do macOS se conecta ao servidor WS do Gateway como um Node (então
openclaw nodes …funciona contra este Mac). - No modo remoto, o app abre um túnel SSH para a porta do Gateway e se conecta a
localhost.