openclaw node

Execute um host de Node sem interface gráfica que se conecta ao WebSocket do Gateway e expõe system.run / system.which nesta máquina.

No macOS, o aplicativo da barra de menus já incorpora esse runtime de host de Node à própria conexão de Node e adiciona recursos nativos do Mac. Use openclaw node run em um Mac somente quando quiser intencionalmente um Node sem interface gráfica e sem o aplicativo. Executar ambos cria duas identidades de Node para a mesma máquina.

Por que usar um host de Node?

Use um host de Node quando quiser que agentes executem comandos em outras máquinas da sua rede sem instalar nelas um aplicativo complementar completo para macOS.

Casos de uso comuns:

• Execute comandos em máquinas Linux/Windows remotas (servidores de compilação, máquinas de laboratório, NAS).
• Mantenha a execução em sandbox no Gateway, mas delegue execuções aprovadas a outros hosts.
• Forneça um destino de execução leve e sem interface gráfica para automação ou Nodes de CI.

A execução continua protegida por aprovações de execução e listas de permissões por agente no host de Node, permitindo manter o acesso a comandos limitado e explícito.

openclaw node run pode publicar ferramentas de Plugin ou baseadas em MCP após se conectar. Por padrão, o Gateway confia nos descritores do Node pareado, mas exige que o comando de cada descritor permaneça na superfície de comandos aprovada do Node. O agente vê cada descritor aceito como uma ferramenta de Plugin normal, mas a execução ainda passa por node.invoke; portanto, desconectar o Node remove a ferramenta de novas execuções de agentes. Os operadores do Gateway podem desativar a publicação com gateway.nodes.pluginTools.enabled: false.

Para ferramentas MCP declarativas, adicione a estrutura normal do servidor MCP em nodeHost.mcp.servers no openclaw.json da máquina do Node e reinicie o host de Node. O Node declara a família de comandos mcp.tools.call.v1, sujeita a aprovação, e publica as ferramentas listadas após se conectar; alterar posteriormente a lista de servidores não exige novo pareamento. Consulte Servidores MCP hospedados em Nodes.

Proxy de navegador (sem configuração)

Os hosts de Node anunciam automaticamente um proxy de navegador se browser.enabled não estiver desativado no Node. Isso permite que o agente use automação de navegador nesse Node sem configuração adicional.

Por padrão, o proxy expõe a superfície normal de perfis de navegador do Node. Se você definir nodeHost.browserProxy.allowProfiles, o proxy se tornará restritivo: o direcionamento a perfis que não estejam na lista de permissões será rejeitado, e as rotas de criação/exclusão de perfis persistentes serão bloqueadas pelo proxy.

Desative-o no Node, se necessário:

{  nodeHost: {    browserProxy: {      enabled: false,    },  },}

Executar (primeiro plano)

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

Opções:

• --host <host>: host do WebSocket do Gateway (padrão: 127.0.0.1)
• --port <port>: porta do WebSocket do Gateway (padrão: 18789)
• --context-path <path>: caminho de contexto do WebSocket do Gateway (por exemplo, /openclaw-gw). Anexado à URL do WebSocket.
• --tls: use TLS para a conexão com o Gateway
• --no-tls: force uma conexão de texto simples com o Gateway mesmo quando a configuração local do Gateway habilitar TLS
• --tls-fingerprint <sha256>: impressão digital esperada do certificado TLS (sha256)
• --node-id <id>: substitua o ID da instância cliente armazenado no estado SQLite compartilhado (não redefine o pareamento)
• --display-name <name>: substitua o nome de exibição do Node

Autenticação do Gateway para o host de Node

openclaw node run e openclaw node install resolvem a autenticação do Gateway pela configuração/ambiente (sem flags --token/--password nos comandos de Node):

• OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD são verificados primeiro.
• Em seguida, usa-se a configuração local como alternativa: gateway.auth.token / gateway.auth.password.
• No modo local, o host de Node intencionalmente não herda gateway.remote.token / gateway.remote.password.
• Se gateway.auth.token / gateway.auth.password estiver explicitamente configurado via SecretRef e não for resolvido, a resolução da autenticação do Node falhará de modo seguro (sem alternativa remota para mascarar a falha).
• Em gateway.mode=remote, os campos do cliente remoto (gateway.remote.token / gateway.remote.password) também são considerados de acordo com as regras de precedência remota.
• A resolução de autenticação do host de Node considera somente variáveis de ambiente OPENCLAW_GATEWAY_*.

Para um Node que se conecta a um Gateway ws:// de texto simples, são aceitos endereços de loopback, literais de IP privado, .local e hosts *.ts.net da Tailnet. Para outros nomes DNS privados confiáveis, defina OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1; sem isso, a inicialização do Node falhará de modo seguro e solicitará o uso de wss://, um túnel SSH ou Tailscale. Essa é uma opção habilitada pelo ambiente do processo, não uma chave de configuração openclaw.json. openclaw node install a mantém no serviço supervisionado do Node quando ela está presente no ambiente do comando de instalação.

Serviço (segundo plano)

Instale um host de Node sem interface gráfica como serviço de usuário (launchd no macOS, systemd no Linux e Agendador de Tarefas do Windows no Windows).

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

Opções:

• --host <host>: host do WebSocket do Gateway (padrão: 127.0.0.1)
• --port <port>: porta do WebSocket do Gateway (padrão: 18789)
• --context-path <path>: caminho de contexto do WebSocket do Gateway (por exemplo, /openclaw-gw). Anexado à URL do WebSocket.
• --tls: use TLS para a conexão com o Gateway
• --tls-fingerprint <sha256>: impressão digital esperada do certificado TLS (sha256)
• --node-id <id>: substitua o ID da instância cliente armazenado no estado SQLite compartilhado (não redefine o pareamento)
• --display-name <name>: substitua o nome de exibição do Node
• --runtime <runtime>: runtime do serviço (node)
• --force: reinstale/substitua se já estiver instalado

Gerencie o serviço:

openclaw node statusopenclaw node startopenclaw node stopopenclaw node restartopenclaw node uninstall

Use openclaw node run para um host de Node em primeiro plano (sem serviço).

Os comandos de serviço aceitam --json para saída legível por máquina.

O host de Node tenta novamente, dentro do processo, após reinicializações do Gateway e encerramentos de rede. Se o Gateway informar uma pausa terminal de autenticação por token/senha/bootstrap, o host de Node registrará os detalhes do encerramento e terminará com código diferente de zero para que launchd/systemd/Agendador de Tarefas possa reiniciá-lo com configurações e credenciais atualizadas. Pausas que exigem pareamento permanecem no fluxo em primeiro plano para permitir a aprovação da solicitação pendente.

Pareamento

A primeira conexão cria uma solicitação pendente de pareamento de dispositivo (role: node) no Gateway.

Quando o host do Gateway consegue acessar o host de Node via SSH sem interação (mesmo usuário, chave de host confiável), a solicitação pendente é aprovada automaticamente: o Gateway executa openclaw node identity --json no host de Node via SSH e aprova quando a chave do dispositivo corresponde exatamente. Isso fica ativado por padrão; consulte Aprovação automática de dispositivo verificada por SSH para conhecer os requisitos e saber como desativá-la (gateway.nodes.pairing.sshVerify: false).

Caso contrário, aprove manualmente por meio de:

openclaw devices listopenclaw devices approve <requestId>

Inspecione a identidade local do Node que o Gateway verifica:

openclaw node identity --json

O comando exibe o ID do dispositivo e a chave pública de identity/device.json e nunca cria nem modifica arquivos de identidade.

Em redes de Nodes rigorosamente controladas, o operador do Gateway pode habilitar explicitamente a aprovação automática do primeiro pareamento de Nodes provenientes de CIDRs confiáveis:

{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

Isso fica desativado por padrão (autoApproveCidrs não está definido). Aplica-se somente a um pareamento role: node inicial, sem escopos solicitados, originado de um IP de cliente em que o Gateway confia. Clientes operadores/de navegador, Control UI, WebChat, bem como atualizações de função, escopo, metadados ou chave pública, ainda exigem aprovação manual.

Se o Node tentar novamente o pareamento com detalhes de autenticação alterados (função/escopos/chave pública), a solicitação pendente anterior será substituída, e um novo requestId será criado. Execute openclaw devices list novamente antes da aprovação.

Estado da identidade e do pareamento

O Node sem interface gráfica separa o ID da instância cliente da identidade assinada do dispositivo que o Gateway usa para pareamento e roteamento. Esse estado reside no diretório de estado do OpenClaw (~/.openclaw por padrão ou $OPENCLAW_STATE_DIR quando definido):

--node-id altera apenas o ID da instância cliente no estado SQLite compartilhado. Ele não altera o ID criptográfico do dispositivo nem limpa a autenticação de pareamento. Migrar um node.json descontinuado com openclaw doctor --fix também não redefine o pareamento. Para revogar e parear novamente um Node:

1. No Gateway, execute openclaw nodes remove --node <id|name|ip>.
2. No Node, reinicie o serviço instalado com openclaw node restart ou interrompa e execute novamente o comando openclaw node run em primeiro plano. Isso inicia o fluxo de pareamento de dispositivo. Se openclaw devices list não mostrar uma solicitação e o Node informar AUTH_DEVICE_TOKEN_MISMATCH, reinicie-o ou execute-o novamente mais uma vez. A tentativa rejeitada limpa o token local que agora foi revogado; a próxima tentativa poderá solicitar o pareamento.
3. No Gateway, execute openclaw devices list e, em seguida, openclaw devices approve <deviceRequestId>.
4. Reinicie ou execute novamente o Node. Um cliente pausado para pareamento não retoma automaticamente após a aprovação; essa reconexão cria a solicitação separada de superfície de comandos.
5. No Gateway, execute openclaw nodes pending e, em seguida, openclaw nodes approve <nodeRequestId>.

Os dois IDs de solicitação são distintos. Uma política aplicável de CIDR confiável pode aprovar automaticamente a etapa inicial de pareamento do dispositivo; a aprovação da superfície de comandos continua sendo uma verificação separada.

Versões anteriores do OpenClaw armazenavam o estado do host de Node em node.json e podiam deixar ali um campo token obsoleto. Interrompa o host de Node e execute openclaw doctor --fix uma vez; o Doctor importa para o SQLite os campos compatíveis de identidade e conexão, descarta o campo de token não utilizado, verifica a linha e remove o arquivo descontinuado. Os comandos normais de Node falham de modo seguro, exibindo essa instrução de reparo, enquanto o arquivo ou uma reivindicação interrompida do Doctor permanecer. Mantenha privados os dois arquivos em identity/; eles contêm o par de chaves do dispositivo e tokens de autenticação.

Aprovações de execução

system.run é controlado por aprovações locais de execução:

• $OPENCLAW_STATE_DIR/exec-approvals.json ou ~/.openclaw/exec-approvals.json quando a variável não estiver definida
• Aprovações de execução
• openclaw approvals --node <id|name|ip> (edite no Gateway)

Para a execução assíncrona aprovada no Node, o OpenClaw prepara um systemRunPlan canônico antes de solicitar aprovação. O encaminhamento system.run aprovado posteriormente reutiliza esse plano armazenado; portanto, edições nos campos de comando/cwd/sessão após a criação da solicitação de aprovação serão rejeitadas, em vez de alterar o que o Node executa.

Relacionado

• Referência da CLI
• Nodes