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 ejecución

• El Gateway es responsable del socket de WhatsApp y del bucle de reconexión.
• Un monitor supervisa dos señales de forma independiente: la actividad de transporte sin procesar de WhatsApp Web y la actividad de mensajes de la aplicación. Una sesión inactiva pero conectada no se reinicia solo porque no se haya recibido ningún mensaje recientemente; solo fuerza la reconexión cuando dejan de llegar tramas de transporte durante un intervalo interno fijo (no configurable por el usuario) o los mensajes de la aplicación permanecen inactivos durante más de 4 veces el tiempo de espera normal de mensajes. Inmediatamente después de una reconexión de una sesión activa recientemente, ese primer intervalo utiliza el tiempo de espera normal de mensajes, más corto, en lugar del intervalo de 4 veces. OpenClaw puede responder automáticamente a los mensajes sin conexión que Baileys entrega al principio de esa reconexión, dentro del límite de la duración de la desduplicación de identificadores de mensajes entrantes; el inicio inicial mantiene la protección breve contra el historial obsoleto.
• Los envíos salientes requieren un listener de WhatsApp activo para la cuenta de destino; de lo contrario, fallan de inmediato.
• Los envíos a grupos adjuntan metadatos nativos de menciones para los tokens @+<digits> y @<digits> (en el texto y en los pies de contenido multimedia) cuando el token coincide con los metadatos actuales de un participante, incluidos los grupos respaldados por LID.
• Se ignoran los chats de estado y difusión (@status, @broadcast).
• Los chats directos utilizan las reglas de sesión de mensajes directos (session.dmScope; el valor predeterminado main agrupa los mensajes directos 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 @newsletter nativo, utilizando metadatos de sesión de canal (agent:<agentId>:whatsapp:channel:<jid>) en lugar de la semántica de mensajes directos.
• 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, y sus variantes en minúsculas). Se recomienda la configuración del proxy en el host en lugar de ajustes por canal.

​

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"

​

Solicitudes de aprobación

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

​

Reacciones a preguntas

​

Hooks de plugins 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 del número personal y del 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 contenido multimedia

​

Citas en respuestas

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

​

Nivel de reacciones

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

​

Reacciones de confirmación

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // siempre | menciones | nunca
      },
    },
  },
}

​

Reacciones de estado del ciclo de vida

{
  messages: {
    statusReactions: {
      enabled: true,
    },
  },
}

​

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).
• Controles de acciones: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (el valor predeterminado de las acciones existentes es true), channels.whatsapp.actions.calls (valor predeterminado: false; consulte MeowCaller más arriba).
• Las escrituras de configuración iniciadas por el canal están habilitadas de forma predeterminada; deshabilítelas mediante channels.whatsapp.configWrites: false.

​

Solución de problemas

openclaw channels login --channel whatsapp
openclaw channels status

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 del grupo (groups["<groupId>"].systemPrompt): se utiliza cuando existe la entrada del grupo y está definida su clave systemPrompt. Una cadena vacía ("") suprime el comodín y no aplica ningún prompt.
2. Prompt comodín de grupo (groups["*"].systemPrompt): se utiliza cuando la entrada específica del grupo no existe 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. Tanto en el ámbito raíz como en el de la cuenta, groups["*"] significa «se admiten todos los grupos» para ese ámbito.
• Añada un comodín systemPrompt solo cuando ya desee que ese ámbito admita todos los grupos. Para mantener como elegibles únicamente un conjunto fijo de identificadores de grupo, repita el prompt en cada entrada incluida explícitamente en la lista de permitidos en lugar de utilizar groups["*"].
• La admisión de grupos y la autorización de remitentes son comprobaciones independientes. groups["*"] amplía los grupos que llegan al procesamiento de grupos; no autoriza a todos los remitentes de esos grupos. Esto sigue controlado por groupPolicy/groupAllowFrom.
• channels.whatsapp.direct no tiene ningún efecto secundario equivalente para los mensajes directos: direct["*"] solo proporciona una configuración predeterminada después de que un mensaje directo ya se haya admitido mediante dmPolicy junto con allowFrom o las reglas del almacén de emparejamientos.

{
  channels: {
    whatsapp: {
      groups: {
        // Utilizar solo si deben admitirse todos los grupos en el ámbito raíz.
        // Se aplica a todas las cuentas que no definen su propio mapa groups.
        "*": { systemPrompt: "Prompt predeterminado para todos los grupos." },
      },
      direct: {
        // Se aplica a todas las cuentas que no definen su propio mapa direct.
        "*": { systemPrompt: "Prompt predeterminado para todos los chats directos." },
      },
      accounts: {
        work: {
          groups: {
            // Esta cuenta define sus propios grupos, por lo que los grupos raíz se
            // sustituyen por completo. Para conservar un comodín, defina "*" explícitamente también aquí.
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "Centrarse en la gestión de proyectos.",
            },
            // Utilizar solo si deben admitirse todos los grupos en esta cuenta.
            "*": { systemPrompt: "Prompt predeterminado para los grupos de trabajo." },
          },
          direct: {
            // Esta cuenta define su propio mapa direct, por lo que las entradas direct raíz se
            // sustituyen por completo. Para conservar un comodín, defina "*" explícitamente también aquí.
            "+15551234567": { systemPrompt: "Prompt para un chat directo de trabajo específico." },
            "*": { systemPrompt: "Prompt predeterminado para los chats directos de trabajo." },
          },
        },
      },
    },
  },
}

​

Referencias de configuración

​

Temas relacionados

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