Conecta Gmail a OpenClaw: Configuración rápida en 5 minutos

¿Alguna vez has intentado automatizar acciones basadas en correos electrónicos y has terminado frustrado con el polling constante? Es un dolor de cabeza configurar webhooks que realmente funcionen en tiempo real sin complicar toda tu infraestructura o quemar tus cuotas de API.

Si buscas una forma directa de conectar Gmail con tus flujos de trabajo, esta guía te muestra cómo usar Pub/Sub para enviar notificaciones push directamente a OpenClaw. Es la mejor ruta para tener una respuesta inmediata y eficiente.

Gmail Pub/Sub -> OpenClaw

Objetivo: Gmail watch -> Pub/Sub push -> gog gmail watch serve -> OpenClaw webhook.

Requisitos previos

• gcloud instalado y con sesión iniciada (guía de instalación).
• gog (gogcli) instalado y autorizado para la cuenta de Gmail (gogcli.sh).
• OpenClaw hooks habilitados (ver Webhooks).
• tailscale con sesión iniciada (tailscale.com). La configuración soportada usa Tailscale Funnel para el endpoint público HTTPS. Otros servicios de túnel pueden funcionar, pero son DIY (hazlo tú mismo), no tienen soporte y requieren cableado manual. Ahora mismo, Tailscale es lo que soportamos.

Ejemplo de configuración de hook (habilita el mapeo preestablecido de Gmail):

{
  hooks: {
    enabled: true,
    token: "OPENCLAW_HOOK_TOKEN",
    path: "/hooks",
    presets: ["gmail"],
  },
}

Para entregar el resumen de Gmail a una superficie de chat, sobrescribe el preset con un mapeo que configure deliver y opcionalmente channel/to:

{
  hooks: {
    enabled: true,
    token: "OPENCLAW_HOOK_TOKEN",
    presets: ["gmail"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
        model: "openai/gpt-5.2-mini",
        deliver: true,
        channel: "last",
        // to: "+15551234567"
      },
    ],
  },
}

Si quieres un canal fijo, configura channel + to. De lo contrario, channel: "last" usa la última ruta de entrega (por defecto WhatsApp).

Para forzar un modelo más barato en las ejecuciones de Gmail, configura model en el mapeo (provider/model o alias). Si aplicas agents.defaults.models, inclúyelo allí.

Para establecer un modelo predeterminado y un nivel de pensamiento específicos para los hooks de Gmail, añade hooks.gmail.model / hooks.gmail.thinking en tu configuración:

{
  hooks: {
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

Notas:

• El model/thinking por hook en el mapeo sigue teniendo prioridad sobre estos valores predeterminados.
• Orden de respaldo: hooks.gmail.model → agents.defaults.model.fallbacks → primario (auth/límites de tasa/timeouts).
• Si agents.defaults.models está configurado, el modelo de Gmail debe estar en la lista de permitidos.
• El contenido del hook de Gmail está envuelto con límites de seguridad para contenido externo por defecto. Para desactivarlo (peligroso), configura hooks.gmail.allowUnsafeExternalContent: true.

Para personalizar más el manejo de la carga útil (payload), añade hooks.mappings o un módulo de transformación JS/TS bajo hooks.transformsDir (ver Webhooks).

Asistente (recomendado)

Usa el ayudante de OpenClaw para conectar todo (instala dependencias en macOS a través de brew):

openclaw webhooks gmail setup \
  --account openclaw@gmail.com

Valores por defecto:

• Usa Tailscale Funnel para el endpoint de push público.
• Escribe la configuración hooks.gmail para openclaw webhooks gmail run.
• Habilita el preset del hook de Gmail (hooks.presets: ["gmail"]).

Nota sobre la ruta: cuando tailscale.mode está habilitado, OpenClaw configura automáticamente hooks.gmail.serve.path como / y mantiene la ruta pública en hooks.gmail.tailscale.path (por defecto /gmail-pubsub) porque Tailscale elimina el prefijo de la ruta configurada antes de actuar como proxy. Si necesitas que el backend reciba la ruta con prefijo, configura hooks.gmail.tailscale.target (o --tailscale-target) con una URL completa como http://127.0.0.1:8788/gmail-pubsub y haz que coincida con hooks.gmail.serve.path.

¿Quieres un endpoint personalizado? Usa --push-endpoint <url> o --tailscale off.

Nota de plataforma: en macOS el asistente instala gcloud, gogcli y tailscale vía Homebrew; en Linux instálalos manualmente primero.

Auto-inicio del Gateway (recomendado):

• Cuando hooks.enabled=true y hooks.gmail.account está configurado, el Gateway inicia gog gmail watch serve al arrancar y renueva automáticamente el watch.
• Configura OPENCLAW_SKIP_GMAIL_WATCHER=1 para excluirte (útil si ejecutas el demonio tú mismo).
• No ejecutes el demonio manual al mismo tiempo, o te encontrarás con el error listen tcp 127.0.0.1:8788: bind: address already in use.

Demonio manual (inicia gog gmail watch serve + renovación automática):

openclaw webhooks gmail run

Configuración única

1. Selecciona el proyecto de GCP que sea propietario del cliente OAuth utilizado por gog.

gcloud auth login
gcloud config set project <project-id>

Nota: Gmail watch requiere que el tema (topic) de Pub/Sub resida en el mismo proyecto que el cliente OAuth.

2. Habilita las API:

gcloud services enable gmail.googleapis.com pubsub.googleapis.com

3. Crea un tema:

gcloud pubsub topics create gog-gmail-watch

4. Permite que el push de Gmail publique:

gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
  --role=roles/pubsub.publisher

Iniciar el watch

gog gmail watch start \
  --account openclaw@gmail.com \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

Guarda el history_id de la salida (para depuración).

Ejecutar el controlador de push

Ejemplo local (autenticación con token compartido):

gog gmail watch serve \
  --account openclaw@gmail.com \
  --bind 127.0.0.1 \
  --port 8788 \
  --path /gmail-pubsub \
  --token <shared> \
  --hook-url http://127.0.0.1:18789/hooks/gmail \
  --hook-token OPENCLAW_HOOK_TOKEN \
  --include-body \
  --max-bytes 20000

Notas:

• --token protege el endpoint de push (x-gog-token o ?token=).
• --hook-url apunta a OpenClaw /hooks/gmail (mapeado; ejecución aislada + resumen al principal).
• --include-body y --max-bytes controlan el fragmento del cuerpo enviado a OpenClaw.

Recomendado: openclaw webhooks gmail run envuelve el mismo flujo y renueva automáticamente el watch.

Exponer el controlador (avanzado, no soportado)

Si necesitas un túnel que no sea Tailscale, conéctalo manualmente y usa la URL pública en la suscripción de push (no soportado, sin protecciones):

cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate

Usa la URL generada como endpoint de push:

gcloud pubsub subscriptions create gog-gmail-watch-push \
  --topic gog-gmail-watch \
  --push-endpoint "https://<public-url>/gmail-pubsub?token=<shared>"

Producción: usa un endpoint HTTPS estable y configura Pub/Sub OIDC JWT, luego ejecuta:

gog gmail watch serve --verify-oidc --oidc-email <svc@...>

Prueba

Envía un mensaje a la bandeja de entrada vigilada:

gog gmail send \
  --account openclaw@gmail.com \
  --to openclaw@gmail.com \
  --subject "watch test" \
  --body "ping"

Verifica el estado del watch y el historial:

gog gmail watch status --account openclaw@gmail.com
gog gmail history --account openclaw@gmail.com --since <historyId>

Solución de problemas

• Invalid topicName: desajuste de proyecto (el tema no está en el proyecto del cliente OAuth).
• User not authorized: falta roles/pubsub.publisher en el tema.
• Mensajes vacíos: el push de Gmail solo proporciona el historyId; recupéralo a través de gog gmail history.

Limpieza

gog gmail watch stop --account openclaw@gmail.com
gcloud pubsub subscriptions delete gog-gmail-watch-push
gcloud pubsub topics delete gog-gmail-watch

Siguientes pasos

• Configuración de Webhooks
• Gestión de Agentes

¿Necesitas ayuda para configurar esto en tu entorno específico? Prueba el AI Setup Assistant.