Configuration

Pareamento

"Emparelhamento" é a etapa explícita de aprovação de acesso do OpenClaw. Ela é usada em dois lugares:

Emparelhamento por DM (quem tem permissão para falar com o bot)
Emparelhamento de Node (quais dispositivos/nós têm permissão para entrar na rede do Gateway)

Contexto de segurança: Segurança

1) Emparelhamento por DM (acesso de chat recebido)

Quando um canal é configurado com a política de DM pairing, remetentes desconhecidos recebem um código curto e a mensagem deles não é processada até você aprovar.

As políticas de DM padrão estão documentadas em: Segurança

dmPolicy: "open" é público somente quando a lista de permissões de DM efetiva inclui "*". A configuração e a validação exigem esse curinga para configurações públicas abertas. Se o estado existente contiver open com entradas concretas em allowFrom, em tempo de execução ainda serão admitidos somente esses remetentes, e aprovações no armazenamento de emparelhamento não ampliam o acesso open.

Códigos de emparelhamento:

8 caracteres, maiúsculos, sem caracteres ambíguos (0O1I).
Expiram após 1 hora. O bot só envia a mensagem de emparelhamento quando uma nova solicitação é criada (aproximadamente uma vez por hora por remetente).
Solicitações pendentes de emparelhamento por DM são limitadas a 3 por canal por padrão; solicitações adicionais são ignoradas até que uma expire ou seja aprovada.

Aprovar um remetente

openclaw pairing list telegram
openclaw pairing approve telegram &lt;CODE&gt;

Se nenhum proprietário de comandos estiver configurado ainda, aprovar um código de emparelhamento por DM também inicializa commands.ownerAllowFrom com o remetente aprovado, como telegram:123456789. Isso dá às configurações iniciais um proprietário explícito para comandos privilegiados e prompts de aprovação de execução. Depois que um proprietário existe, aprovações de emparelhamento posteriores concedem apenas acesso por DM; elas não adicionam mais proprietários.

Canais compatíveis: bluebubbles, discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams, nextcloud-talk, nostr, openclaw-weixin, signal, slack, synology-chat, telegram, twitch, whatsapp, zalo, zalouser.

Grupos de remetentes reutilizáveis

Use accessGroups de nível superior quando o mesmo conjunto de remetentes confiáveis deve se aplicar a vários canais de mensagem ou tanto a listas de permissões de DM quanto de grupos.

Grupos estáticos usam type: "message.senders" e são referenciados com accessGroup:<name> nas listas de permissões dos canais:

{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
        whatsapp: ["+15551234567"],
      },
    },
  },
  channels: {
    telegram: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"] },
    whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["accessGroup:operators"] },
  },
}

Grupos de acesso estão documentados em detalhes aqui: Grupos de acesso

Onde o estado fica armazenado

Armazenado em ~/.openclaw/credentials/:

Solicitações pendentes: <channel>-pairing.json
Armazenamento da lista de permissões aprovada:
- Conta padrão: <channel>-allowFrom.json
- Conta não padrão: <channel>-<accountId>-allowFrom.json

Comportamento de escopo de conta:

Contas não padrão leem/gravam apenas seu arquivo de lista de permissões com escopo.
A conta padrão usa o arquivo de lista de permissões sem escopo, com escopo de canal.

Trate esses arquivos como sensíveis (eles controlam o acesso ao seu assistente).

2) Emparelhamento de dispositivo Node (nós iOS/Android/macOS/headless)

Nós se conectam ao Gateway como dispositivos com role: node. O Gateway cria uma solicitação de emparelhamento de dispositivo que precisa ser aprovada.

Emparelhar via Telegram (recomendado para iOS)

Se você usa o Plugin device-pair, pode fazer o emparelhamento inicial do dispositivo inteiramente pelo Telegram:

No Telegram, envie uma mensagem ao seu bot: /pair
O bot responde com duas mensagens: uma mensagem de instruções e uma mensagem separada de código de configuração (fácil de copiar/colar no Telegram).
No seu telefone, abra o app OpenClaw para iOS → Configurações → Gateway.
Escaneie o código QR ou cole o código de configuração e conecte.
De volta ao Telegram: /pair pending (revise IDs de solicitação, função e escopos), depois aprove.

O código de configuração é um payload JSON codificado em base64 que contém:

url: a URL WebSocket do Gateway (ws://... ou wss://...)
bootstrapToken: um token de bootstrap de curta duração e dispositivo único usado para o handshake inicial de emparelhamento

Esse token de bootstrap carrega o perfil de bootstrap de emparelhamento integrado:

o token node entregue principal permanece com scopes: []
qualquer token operator entregue permanece limitado à lista de permissões de bootstrap: operator.approvals, operator.read, operator.talk.secrets, operator.write
verificações de escopo de bootstrap são prefixadas por função, não um único conjunto plano de escopos: entradas de escopo de operador satisfazem apenas solicitações de operador, e funções que não são de operador ainda precisam solicitar escopos sob seu próprio prefixo de função
rotação/revogação posterior de tokens continua limitada tanto pelo contrato de função aprovado do dispositivo quanto pelos escopos de operador da sessão chamadora

Trate o código de configuração como uma senha enquanto ele estiver válido.

Para Tailscale, emparelhamento móvel público ou outro emparelhamento móvel remoto, use Tailscale Serve/Funnel ou outra URL wss:// do Gateway. Códigos de configuração em texto claro ws:// são aceitos somente para local loopback, endereços de LAN privada, hosts Bonjour .local e o host do emulador Android. Endereços CGNAT de tailnet, nomes .ts.net e hosts públicos ainda falham de forma fechada antes da emissão do QR/código de configuração.

Aprovar um dispositivo Node

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

Quando uma aprovação explícita é negada porque a sessão de dispositivo emparelhado aprovadora foi aberta com escopo somente de emparelhamento, a CLI tenta novamente a mesma solicitação com operator.admin. Isso permite que um dispositivo emparelhado existente com capacidade de admin recupere um novo emparelhamento de UI de Controle/navegador sem editar devices/paired.json manualmente. O Gateway ainda valida a conexão repetida; tokens que não conseguem autenticar com operator.admin permanecem bloqueados.

Se o mesmo dispositivo tentar novamente com detalhes de autenticação diferentes (por exemplo, função/escopos/chave pública diferentes), a solicitação pendente anterior é substituída e um novo requestId é criado.

Autoaprovação opcional de Node por CIDR confiável

O emparelhamento de dispositivo permanece manual por padrão. Para redes de nós rigidamente controladas, você pode optar pela autoaprovação inicial de Node com CIDRs explícitos ou IPs exatos:

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

Isso se aplica somente a novas solicitações de emparelhamento com role: node sem escopos solicitados. Clientes operador, navegador, UI de Controle e WebChat ainda exigem aprovação manual. Mudanças de função, escopo, metadados e chave pública ainda exigem aprovação manual.

Armazenamento de estado de emparelhamento de Node

Armazenado em ~/.openclaw/devices/:

pending.json (curta duração; solicitações pendentes expiram)
paired.json (dispositivos emparelhados + tokens)

Observações

A API legada node.pair.* (CLI: openclaw nodes pending|approve|reject|remove|rename) é um armazenamento de emparelhamento separado, pertencente ao gateway. Nós WS ainda exigem emparelhamento de dispositivo.
O registro de emparelhamento é a fonte durável da verdade para funções aprovadas. Tokens de dispositivo ativos permanecem limitados a esse conjunto de funções aprovado; uma entrada de token avulsa fora das funções aprovadas não cria novo acesso.

Documentos relacionados

Modelo de segurança + injeção de prompt: Segurança
Atualização segura (execute o doctor): Atualização
Configurações de canais:
- Telegram: Telegram
- WhatsApp: WhatsApp
- Signal: Signal
- iMessage: iMessage
- BlueBubbles (ponte legada de iMessage): BlueBubbles
- Discord: Discord
- Slack: Slack

# 1) Emparelhamento por DM (acesso de chat recebido)

# Aprovar um remetente

# Grupos de remetentes reutilizáveis

# Onde o estado fica armazenado

# 2) Emparelhamento de dispositivo Node (nós iOS/Android/macOS/headless)

# Emparelhar via Telegram (recomendado para iOS)

# Aprovar um dispositivo Node

# Autoaprovação opcional de Node por CIDR confiável

# Armazenamento de estado de emparelhamento de Node

# Observações

# Documentos relacionados