Google Chat

​

Instalar

openclaw plugins install @openclaw/googlechat

openclaw plugins install ./path/to/local/googlechat-plugin

​

Configuración rápida (principiante)

1. Crea un proyecto de Google Cloud y habilita la API de Google Chat.
   • Ve a: Credenciales de la API de Google Chat
   • Habilita la API si aún no está habilitada.
2. Crea una cuenta de servicio:
   • Pulsa Crear credenciales > Cuenta de servicio.
   • Ponle el nombre que quieras (por ejemplo, openclaw-chat).
   • Deja en blanco los permisos y las entidades principales (Continuar y luego Listo).
3. Crea y descarga la clave JSON:
   • Haz clic en la nueva cuenta de servicio > pestaña Claves > Añadir clave > Crear clave nueva > JSON > Crear.
4. Guarda el archivo JSON descargado en tu host del Gateway (por ejemplo, ~/.openclaw/googlechat-service-account.json).
5. Crea una app de Google Chat en la Configuración de Chat de Google Cloud Console:
   • Rellena Información de la aplicación (nombre de la app, URL del avatar, descripción).
   • Habilita Funciones interactivas.
   • En Funcionalidad, marca Unirse a espacios y conversaciones de grupo.
   • En Configuración de conexión, selecciona URL de endpoint HTTP.
   • En Activadores, selecciona Usar una URL de endpoint HTTP común para todos los activadores y establécela en la URL pública de tu Gateway seguida de /googlechat (consulta URL pública).
   • En Visibilidad, marca Hacer que esta app de Chat esté disponible para personas y grupos específicos en <Your Domain> e introduce tu dirección de correo electrónico.
   • Haz clic en Guardar.
6. Habilita el estado de la app: actualiza la página, busca Estado de la app, establécelo en En vivo: disponible para usuarios y vuelve a hacer clic en Guardar.
7. Configura OpenClaw con la cuenta de servicio y la audiencia del Webhook (debe coincidir con la configuración de la app de Chat):
   • Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json (solo cuenta predeterminada), o
   • Config: consulta Aspectos destacados de la configuración. openclaw channels add --channel googlechat también acepta --audience-type, --audience, --webhook-path y --webhook-url.
8. Inicia el Gateway. Google Chat hará POST a tu ruta de Webhook (predeterminada: /googlechat).

​

Añadir a Google Chat

1. Ve a Google Chat.
2. Haz clic en el icono + (más) junto a Mensajes directos.
3. Busca el nombre de la app que configuraste en Google Cloud Console.
   • El bot no aparece en la lista de exploración de Marketplace porque es una app privada; búscalo por nombre.
4. Selecciona el bot, haz clic en Añadir o Chat y envía un mensaje.

​

URL pública (solo Webhook)

​

Opción A: Tailscale Funnel (recomendado)

1. Comprueba a qué dirección está enlazado tu Gateway:
   ss -tlnp | grep 18789
   
   Anota la IP (por ejemplo, 127.0.0.1, 0.0.0.0 o una dirección Tailscale 100.x.x.x).
2. Expón el panel solo a la tailnet (puerto 8443):
   # If bound to localhost (127.0.0.1 or 0.0.0.0):
   tailscale serve --bg --https 8443 http://127.0.0.1:18789
   
   # If bound to a Tailscale IP only:
   tailscale serve --bg --https 8443 http://100.x.x.x:18789
   
3. Expón públicamente solo la ruta del Webhook:
   # If bound to localhost (127.0.0.1 or 0.0.0.0):
   tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
   
   # If bound to a Tailscale IP only:
   tailscale funnel --bg --set-path /googlechat http://100.x.x.x:18789/googlechat
   
4. Si se te solicita, visita la URL de autorización que se muestra en la salida para habilitar Funnel para este nodo.
5. Verifica:
   tailscale serve status
   tailscale funnel status
   

Nota: Esta configuración persiste tras los reinicios. Elimínala más adelante con tailscale funnel reset y tailscale serve reset.

​

Opción B: Proxy inverso (Caddy)

your-domain.com {
    reverse_proxy /googlechat* localhost:18789
}

​

Opción C: Cloudflare Tunnel

• Ruta: /googlechat -> http://localhost:18789/googlechat
• Regla predeterminada: HTTP 404 (No encontrado)

​

Cómo funciona

1. Google Chat envía JSON mediante POST a la ruta del Webhook del Gateway (solo POST, tipo de contenido JSON requerido, con límite de tasa por IP).
2. OpenClaw autentica cada solicitud antes de despacharla:
   • Los eventos de la aplicación de Chat llevan Authorization: Bearer <token>; el token se verifica antes de analizar el cuerpo completo.
   • Los eventos de complementos de Google Workspace llevan el token en el cuerpo (authorizationEventObject.systemIdToken) y se leen con un presupuesto de preautenticación más estricto (16 KB, 3 s) antes de la verificación.
3. El token se comprueba contra audienceType + audience:
   • audienceType: "app-url" → la audiencia es tu URL HTTPS del Webhook.
   • audienceType: "project-number" → la audiencia es el número del proyecto de Cloud.
   • Los tokens de complementos bajo app-url también requieren que appPrincipal se establezca en el ID de cliente OAuth 2.0 numérico de la aplicación (21 dígitos, no un correo electrónico); de lo contrario, la verificación falla con una advertencia registrada.
4. Los mensajes se enrutan por espacio:
   • Los espacios obtienen sesiones por espacio agent:<agentId>:googlechat:group:<spaceId>; las respuestas van al hilo del mensaje.
   • Los DM se agrupan en la sesión principal del agente de forma predeterminada; establece session.dmScope para sesiones de DM por interlocutor (consulta Sesión).
5. El acceso a DM usa emparejamiento de forma predeterminada. Los remitentes desconocidos reciben un código de emparejamiento; apruébalo con:
   • openclaw pairing approve googlechat <code>
6. Los espacios de grupo requieren @mención de forma predeterminada. Las menciones se detectan a partir de anotaciones USER_MENTION de Chat dirigidas a la aplicación; establece botUser (por ejemplo, users/1234567890) si la detección necesita el nombre de recurso de usuario de la aplicación.
7. Cuando una aprobación de ejecución o Plugin se inicia desde Google Chat y hay configurado un aprobador estable users/<id>, OpenClaw publica una tarjeta de aprobación nativa (cardsV2) en el espacio o hilo de origen. Los botones de la tarjeta llevan tokens de devolución de llamada opacos; el mensaje manual /approve <id> <decision> aparece solo cuando la entrega nativa no está disponible.

​

Destinos

• Mensajes directos: users/<userId> (recomendado).
• Espacios: spaces/<spaceId>.
• El correo electrónico sin procesar name@example.com es mutable y solo se usa para coincidencia de listas de permitidos cuando channels.googlechat.dangerouslyAllowNameMatching: true.
• Obsoleto: users/<email> se trata como un id de usuario, no como una entrada de lista de permitidos de correo electrónico.
• Los prefijos googlechat:, google-chat: y gchat: se aceptan y se eliminan.

​

Aspectos destacados de configuración

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      // or serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      appPrincipal: "123456789012345678901", // add-on verification only; numeric OAuth client ID
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; helps mention detection
      allowBots: false,
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          enabled: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Short answers only.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• Credenciales de cuenta de servicio: serviceAccountFile (ruta), serviceAccount (cadena JSON u objeto en línea) o serviceAccountRef (env/file SecretRef). Las variables de entorno GOOGLE_CHAT_SERVICE_ACCOUNT (JSON en línea) y GOOGLE_CHAT_SERVICE_ACCOUNT_FILE (ruta) se aplican solo a la cuenta predeterminada. Las configuraciones con varias cuentas usan channels.googlechat.accounts.<id> con las mismas claves, incluido serviceAccountRef por cuenta.
• La ruta predeterminada del Webhook es /googlechat cuando webhookPath no está establecido; webhookUrl puede proporcionar la ruta en su lugar.
• Las claves de grupo deben ser ids de espacio estables (spaces/<spaceId>). Las claves de nombre para mostrar están obsoletas y se registran como tales.
• dangerouslyAllowNameMatching vuelve a habilitar la coincidencia de principales de correo electrónico mutables para listas de permitidos (modo de compatibilidad de emergencia); doctor advierte sobre entradas de correo electrónico.
• Las reacciones están habilitadas de forma predeterminada y se exponen mediante la herramienta reactions y channels action; deshabilítalas con actions.reactions: false.
• Las tarjetas de aprobación nativas usan clics de botones cardsV2 de Google Chat, no eventos de reacción. Los aprobadores provienen de dm.allowFrom o defaultTo y deben ser valores numéricos estables users/<id>.
• Las acciones de mensaje exponen send para texto y upload-file para envíos explícitos de adjuntos. upload-file acepta media / filePath / path más message, filename y destino de hilo opcionales (threadId / replyTo).
• typingIndicator: message (predeterminado) publica un marcador de posición _<Bot> is typing..._ y lo edita para convertirlo en la primera respuesta; none lo deshabilita; reaction requiere OAuth de usuario y actualmente vuelve a message con un error registrado bajo autenticación de cuenta de servicio.
• Los adjuntos entrantes (primer adjunto por mensaje) se descargan mediante la API de Chat en la canalización de medios, con un límite de mediaMaxMb (predeterminado 20).
• Los mensajes creados por bots se ignoran de forma predeterminada. Con allowBots: true, los mensajes de bot aceptados usan la protección contra bucles de bot compartida: configura channels.defaults.botLoopProtection y luego sobrescribe con channels.googlechat.botLoopProtection o channels.googlechat.groups.<space>.botLoopProtection.

​

Solución de problemas

​

405 Método no permitido

status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed

1. Canal no configurado: falta la sección channels.googlechat. Verifícalo con:
   openclaw config get channels.googlechat
   
   Si devuelve “Config path not found”, agrega la configuración (consulta Aspectos destacados de configuración).
2. Plugin no habilitado: comprueba el estado del Plugin:
   openclaw plugins list | grep googlechat
   
   Si muestra “disabled”, agrega plugins.entries.googlechat.enabled: true a tu configuración.
3. Gateway no reiniciado después de cambios de configuración:
   openclaw gateway restart
   

openclaw channels status
# Should show: Google Chat default: enabled, configured, ...

​

Otros problemas

• openclaw channels status --probe muestra errores de autenticación y configuración de audiencia faltante (audience y audienceType son ambos obligatorios).
• Si no llegan mensajes, confirma la URL del Webhook de la aplicación de Chat y la configuración del disparador.
• Si la compuerta de menciones bloquea respuestas, establece botUser en el nombre de recurso de usuario de la aplicación y comprueba requireMention.
• openclaw logs --follow al enviar un mensaje de prueba muestra si las solicitudes llegan al Gateway.

​

Relacionado

• Resumen de canales — todos los canales admitidos
• Enrutamiento de canales — enrutamiento de sesiones para mensajes
• Configuración del Gateway
• Grupos — comportamiento del chat grupal y control de menciones
• Emparejamiento — autenticación por DM y flujo de emparejamiento
• Reacciones
• Seguridad — modelo de acceso y refuerzo