Configuration

Emparejamiento

El «emparejamiento» es el paso explícito de aprobación de acceso de OpenClaw. Se utiliza en dos lugares:

Emparejamiento de mensajes directos (quién puede hablar con el bot)
Emparejamiento de Node (qué dispositivos/nodos pueden unirse a la red del Gateway)

Contexto de seguridad: Seguridad

1) Emparejamiento de mensajes directos (acceso a chats entrantes)

Cuando un canal está configurado con la política de mensajes directos pairing, los remitentes desconocidos reciben un código corto y su mensaje no se procesa hasta que se aprueba.

Las políticas predeterminadas de mensajes directos se documentan en: Seguridad

dmPolicy: "open" es público solo cuando la lista de permitidos efectiva para mensajes directos incluye "*". La configuración y la validación requieren ese comodín para las configuraciones abiertas al público. Si el estado existente contiene open con entradas concretas de allowFrom, el entorno de ejecución sigue admitiendo solo a esos remitentes, y las aprobaciones del almacén de emparejamiento no amplían el acceso de open.

Códigos de emparejamiento:

8 caracteres, en mayúsculas y sin caracteres ambiguos (0O1I).
Caducan después de 1 hora. El bot solo envía el mensaje de emparejamiento cuando se crea una nueva solicitud (aproximadamente una vez por hora y por remitente).
Las solicitudes pendientes de emparejamiento de mensajes directos están limitadas a 3 por cuenta de canal; las solicitudes adicionales se ignoran hasta que una caduque o se apruebe.

Aprobar un remitente

bash

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

Añada --notify al comando de aprobación para avisar al solicitante en el mismo canal. Los canales con varias cuentas aceptan --account <id>.

Si todavía no se ha configurado ningún propietario de comandos, aprobar un código de emparejamiento de mensajes directos también inicializa commands.ownerAllowFrom con el remitente aprobado, como telegram:123456789. Esto proporciona a las configuraciones iniciales un propietario explícito para los comandos con privilegios y las solicitudes de aprobación de ejecución. Cuando ya existe un propietario, las aprobaciones de emparejamiento posteriores solo conceden acceso a mensajes directos; no añaden más propietarios.

Canales compatibles (cualquier Plugin de canal instalado que declare el emparejamiento; los plugins externos como openclaw-weixin pueden añadir más): discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams, nextcloud-talk, nostr, signal, slack, sms, synology-chat, telegram, twitch, whatsapp, zalo, zalouser.

Grupos de remitentes reutilizables

Utilice accessGroups en el nivel superior cuando el mismo conjunto de remitentes de confianza deba aplicarse a varios canales de mensajería o tanto a las listas de permitidos de mensajes directos como de grupos.

Los grupos estáticos utilizan type: "message.senders" y se referencian mediante accessGroup:<name> desde las listas de permitidos de los canales:

json5

{  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"] },  },}

Los grupos de acceso se documentan en detalle aquí: Grupos de acceso

Dónde se almacena el estado

Se almacena en la base de datos de estado SQLite compartida en ~/.openclaw/state/openclaw.sqlite:

solicitudes pendientes en channel_pairing_requests
remitentes aprobados en channel_pairing_allow_entries

Comportamiento del ámbito de las cuentas:

cada solicitud y remitente aprobado se identifica por canal y cuenta
el entorno de ejecución solo lee las filas SQLite canónicas; no combina archivos heredados

Las versiones anteriores del Gateway escribían <channel>-pairing.json y <channel>-<accountId>-allowFrom.json en ~/.openclaw/credentials/. La migración de inicio y openclaw doctor --fix importan esos archivos en SQLite y eliminan cada origen tras importarlo correctamente. La base de datos SQLite debe tratarse como información confidencial, ya que estas filas controlan el acceso al asistente.

2) Emparejamiento de dispositivos Node (nodos iOS/Android/macOS/sin interfaz gráfica)

Los nodos se conectan al Gateway como dispositivos con role: node. El Gateway crea una solicitud de emparejamiento de dispositivo que debe aprobarse.

Emparejar desde la interfaz de control (recomendado)

Utilice una sesión ya conectada de la interfaz de control con acceso operator.admin:

Abra la interfaz de control y vaya a Settings → Devices.
En la página Devices, haga clic en Pair mobile device.
Mantenga Full access (recommended) o seleccione Limited access para omitir los controles administrativos del Gateway.
Haga clic en Create setup code.
En el teléfono, abra la aplicación OpenClaw → Settings → Gateway.
Escanee el código QR o pegue el código de configuración y, a continuación, conéctese.

Las aplicaciones oficiales de OpenClaw para iOS y Android se aprueban automáticamente cuando sus metadatos del código de configuración coinciden. Si Pending approval muestra una solicitud (por ejemplo, para un cliente no oficial o con metadatos que no coinciden), revise su rol y sus ámbitos antes de aprobarla.

El botón está deshabilitado cuando la sesión actual de la interfaz de control no tiene acceso de administrador. En ese caso, utilice el siguiente flujo de aprobación mediante la CLI desde el host del Gateway.

Emparejar mediante Telegram

Si se utiliza el Plugin device-pair, el emparejamiento inicial de dispositivos puede realizarse íntegramente desde Telegram:

En Telegram, envíe un mensaje al bot: /pair
El bot responde con dos mensajes: uno con instrucciones y otro independiente con el código de configuración (fácil de copiar y pegar en Telegram).
En el teléfono, abra la aplicación OpenClaw para iOS → Settings → Gateway.
Escanee el código QR (/pair qr) o pegue el código de configuración y conéctese.
La aplicación móvil oficial se conecta automáticamente. Si /pair pending muestra una solicitud, revise su rol y sus ámbitos antes de aprobarla.

El código de configuración es una carga útil JSON codificada en base64 que contiene:

url: la URL de WebSocket del Gateway (ws://... o wss://...)
urls: cuando están disponibles, las rutas ordenadas de la LAN/Tailnet que puede probar la aplicación móvil
bootstrapToken: un token de inicialización de un solo uso para el protocolo de enlace de emparejamiento inicial; el Gateway lo hace caducar después de 10 minutos

Ejecute /pair cleanup para invalidar los códigos de configuración sin usar cuando finalice el emparejamiento.

Ese token de inicialización incluye el perfil de inicialización de emparejamiento integrado:

una configuración segura de wss:// (o mediante bucle invertido en el mismo host) utiliza de forma predeterminada node, además de acceso completo a operator para dispositivos móviles nativos
el token node transferido permanece como scopes: []
el token operator transferido de forma predeterminada incluye operator.admin, operator.approvals, operator.read, operator.talk.secrets y operator.write
La opción Limited access de la interfaz de control y openclaw qr --limited omiten operator.admin, pero mantienen los demás ámbitos del operador
la configuración de ws:// mediante LAN con texto sin cifrar utiliza automáticamente el mismo perfil limitado; configure wss:// o Tailscale Serve y genere un nuevo código para obtener acceso completo
la rotación o revocación posterior del token sigue estando limitada tanto por el contrato de rol aprobado del dispositivo como por los ámbitos de operador de la sesión que realiza la llamada

Mientras sea válido, trate el código de configuración como una contraseña.

Las páginas Settings → Gateway de iOS y Android muestran el acceso Full o Limited. Para ampliar el acceso de un teléfono limitado, configure primero una ruta segura de wss:// o Tailscale Serve; después, genere un nuevo código de configuración con acceso completo, escanéelo o péguelo en esa página de configuración y vuelva a conectarse.

Para el emparejamiento móvil remoto mediante Tailscale, redes públicas u otros medios, utilice Tailscale Serve/Funnel u otra URL de Gateway wss://. Los códigos de configuración ws:// con texto sin cifrar solo se aceptan para bucle invertido, direcciones LAN privadas, hosts Bonjour .local y el host del emulador de Android. Las rutas con texto sin cifrar que no sean de bucle invertido reciben acceso limitado. Las direcciones CGNAT de Tailnet, los nombres .ts.net y los hosts públicos se siguen rechazando de forma segura antes de emitir el código QR o el código de configuración.

Para las URL de configuración gateway.bind=lan, OpenClaw detecta las raíces HTTPS persistentes de Tailscale Serve que actúan como proxy del puerto de bucle invertido del Gateway activo y las anuncia junto con la ruta LAN. El comando de configuración añade esta alternativa solo para lan; custom y tailnet mantienen sus rutas anunciadas explícitamente. La aplicación para iOS prueba las rutas anunciadas en orden y guarda el primer punto de conexión accesible.

Aprobar un dispositivo Node

bash

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>

Cuando se deniega una aprobación explícita porque la sesión del dispositivo emparejado que realiza la aprobación se abrió con un ámbito exclusivo de emparejamiento, la CLI vuelve a intentar la misma solicitud con operator.admin. Esto permite que un dispositivo emparejado existente con capacidad de administración recupere un nuevo emparejamiento de la interfaz de control o del navegador sin editar manualmente el almacén de emparejamiento. El Gateway sigue validando la conexión reintentada; los tokens que no pueden autenticarse con operator.admin permanecen bloqueados.

Si el mismo dispositivo vuelve a intentarlo con datos de autenticación diferentes (por ejemplo, otro rol, otros ámbitos u otra clave pública), la solicitud pendiente anterior se sustituye y se crea un nuevo requestId.

Aprobación automática opcional de nodos mediante CIDR de confianza

De forma predeterminada, el emparejamiento de dispositivos sigue siendo manual. En redes de nodos estrictamente controladas, se puede habilitar la aprobación automática del emparejamiento inicial de nodos mediante CIDR explícitos o direcciones IP exactas:

json5

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

Esto solo se aplica a nuevas solicitudes de emparejamiento de role: node sin ámbitos solicitados. Los clientes de operador, navegador, interfaz de control y WebChat siguen requiriendo aprobación manual. Los cambios de rol, ámbito, metadatos y clave pública también siguen requiriendo aprobación manual.

Almacenamiento del estado de emparejamiento de Node