WhatsApp

​

Instalación

openclaw plugins install clawhub:@openclaw/whatsapp

​

Configuración rápida

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

​

Patrones de despliegue

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

​

Modelo de runtime

• El Gateway es propietario del socket de WhatsApp y del bucle de reconexión.
• Un watchdog rastrea dos señales de forma independiente: la actividad sin procesar del transporte de WhatsApp Web y la actividad de mensajes de la aplicación. Una sesión silenciosa pero conectada no se reinicia solo porque no haya llegado ningún mensaje recientemente; fuerza la reconexión solo cuando los frames de transporte dejan de llegar durante una ventana interna fija (no configurable por el usuario) o los mensajes de la aplicación permanecen en silencio más allá de 4 veces el timeout normal de mensajes. Justo después de una reconexión de una sesión recientemente activa, esa primera ventana usa el timeout normal de mensajes más corto en lugar de la ventana de 4 veces. OpenClaw puede responder automáticamente a mensajes sin conexión que Baileys entrega al inicio de esa reconexión, limitado por la duración de deduplicación de los ID de mensajes entrantes; el arranque inicial conserva la protección corta contra historial obsoleto.
• Los tiempos del socket de Baileys son explícitos bajo web.whatsapp.*: keepAliveIntervalMs (intervalo de ping de la aplicación), connectTimeoutMs (timeout del handshake de apertura), defaultQueryTimeoutMs (esperas de consultas de Baileys, además de los timeouts de envío/presencia salientes y confirmación de lectura entrante de OpenClaw).
• Los envíos salientes requieren un listener de WhatsApp activo para la cuenta de destino; de lo contrario, los envíos fallan rápidamente.
• Los envíos a grupos adjuntan metadatos nativos de mención para tokens @+<digits> y @<digits> (en texto y pies de medios) cuando el token coincide con los metadatos actuales de participantes, incluidos grupos respaldados por LID.
• Los chats de estado y difusión (@status, @broadcast) se ignoran.
• Los chats directos usan reglas de sesión de DM (session.dmScope; el valor predeterminado main colapsa los DM en la sesión principal del agente). Las sesiones de grupo se aíslan por JID (agent:<agentId>:whatsapp:group:<jid>).
• Los canales/boletines de WhatsApp pueden ser destinos salientes explícitos mediante su JID nativo @newsletter, usando metadatos de sesión de canal (agent:<agentId>:whatsapp:channel:<jid>) en lugar de semántica de DM.
• El transporte de WhatsApp Web respeta las variables de entorno de proxy estándar en el host del Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, variantes en minúsculas). Prefiere la configuración de proxy a nivel de host sobre los ajustes por canal.
• Con messages.removeAckAfterReply habilitado, OpenClaw borra la reacción de acuse una vez que se entrega una respuesta visible.

​

Llamar al solicitante actual con MeowCaller (experimental)

{
  "channels": {
    "whatsapp": {
      "actions": {
        "calls": true
      }
    }
  }
}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -p "$HOME/.local/bin"
go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"
mkdir -p "$state_dir"
chmod 700 "$state_dir"
meowcaller pair --store "$state_dir/wa-voip.db"

​

Prompts de aprobación

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session",
    },
    plugin: {
      enabled: true,
      mode: "targets",
      targets: [{ channel: "whatsapp", to: "+15551234567" }],
    },
  },
}

​

Hooks de Plugin y privacidad

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

​

Control de acceso y activación

​

Enlaces ACP configurados

{
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "whatsapp",
        accountId: "work",
        peer: { kind: "direct", id: "+15555550123" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "whatsapp",
        accountId: "work",
        peer: { kind: "group", id: "120363424282127706@g.us" },
      },
    },
  ],
}

​

Comportamiento de número personal y chat propio

​

Normalización de mensajes y contexto

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

{ channels: { whatsapp: { sendReadReceipts: false } } }

​

Entrega, fragmentación y multimedia

​

Citas de respuesta

{ channels: { whatsapp: { replyToMode: "first" } } }

​

Nivel de reacción

{ channels: { whatsapp: { reactionLevel: "ack" } } }

​

Reacciones de acuse

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

​

Reacciones de estado del ciclo de vida

{
  messages: {
    statusReactions: {
      enabled: true,
      emojis: {
        deploy: "🛫",
        build: "🏗️",
        concierge: "💁",
      },
    },
  },
}

​

Varias cuentas y credenciales

​

Herramientas, acciones y escrituras de configuración

• La compatibilidad con herramientas del agente incluye la acción de reacción de WhatsApp (react).
• Compuertas de acciones: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (las acciones existentes tienen true de forma predeterminada), channels.whatsapp.actions.calls (valor predeterminado false, consulta MeowCaller arriba).
• Las escrituras de configuración iniciadas por el canal están habilitadas de forma predeterminada; deshabilítalas mediante channels.whatsapp.configWrites: false.

​

Solución de problemas

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
  ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

​

Prompts del sistema

1. Prompt específico de grupo (groups["<groupId>"].systemPrompt): se usa cuando la entrada del grupo existe y su clave systemPrompt está definida. Una cadena vacía ("") suprime el comodín y no aplica ningún prompt.
2. Prompt comodín de grupo (groups["*"].systemPrompt): se usa cuando la entrada específica del grupo está ausente, o existe sin una clave systemPrompt.

• channels.whatsapp.groups es tanto un mapa de configuración por grupo como la lista de permitidos de grupos a nivel de chat. En el ámbito raíz o de cuenta, groups["*"] significa “todos los grupos son admitidos” para ese ámbito.
• Añade un systemPrompt comodín solo cuando ya quieras que ese ámbito admita todos los grupos. Para mantener elegible solo un conjunto fijo de IDs de grupo, repite el prompt en cada entrada explícitamente incluida en la lista de permitidos en lugar de usar groups["*"].
• La admisión de grupos y la autorización de remitentes son comprobaciones separadas. groups["*"] amplía qué grupos llegan al manejo de grupos; no autoriza a todos los remitentes de esos grupos: eso sigue controlado por groupPolicy/groupAllowFrom.
• channels.whatsapp.direct no tiene un efecto secundario equivalente para DMs: direct["*"] solo proporciona una configuración predeterminada después de que un DM ya haya sido admitido por dmPolicy más reglas de allowFrom o del almacén de emparejamientos.

{
  channels: {
    whatsapp: {
      groups: {
        // Use only if all groups should be admitted at the root scope.
        // Applies to all accounts that do not define their own groups map.
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // Applies to all accounts that do not define their own direct map.
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // This account defines its own groups, so root groups are fully
            // replaced. To keep a wildcard, define "*" explicitly here too.
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // Use only if all groups should be admitted in this account.
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // This account defines its own direct map, so root direct entries are
            // fully replaced. To keep a wildcard, define "*" explicitly here too.
            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
            "*": { systemPrompt: "Default prompt for work direct chats." },
          },
        },
      },
    },
  },
}

​

Punteros de referencia de configuración

​

Relacionado

• Emparejamiento
• Grupos
• Seguridad
• Enrutamiento de canales
• Enrutamiento multiagente
• Solución de problemas