Google Chat (Chat API)

Estado: listo para DMs + spaces vía webhooks de la API de Google Chat (solo HTTP).

Configuración rápida (principiante)

Crea un proyecto de Google Cloud y habilita la API de Google Chat.
- Ve a: Google Chat API Credentials
- Habilita la API si aún no está habilitada.
Crea una Cuenta de Servicio:
- Presiona Create Credentials > Service Account.
- Ponle el nombre que quieras (por ejemplo, openclaw-chat).
- Deja los permisos en blanco (presiona Continue).
- Deja los principales con acceso en blanco (presiona Done).
Crea y descarga la Clave JSON:
- En la lista de cuentas de servicio, haz clic en la que acabas de crear.
- Ve a la pestaña Keys.
- Haz clic en Add Key > Create new key.
- Selecciona JSON y presiona Create.
Guarda el archivo JSON descargado en tu host del gateway (por ejemplo, ~/.openclaw/googlechat-service-account.json).
Crea una app de Google Chat en la Configuración de Chat de Google Cloud Console:
- Completa la Información de la aplicación:
  - App name: (por ejemplo OpenClaw)
  - Avatar URL: (por ejemplo https://openclaw.ai/logo.png)
  - Description: (por ejemplo Personal AI Assistant)
- Habilita Interactive features.
- En Functionality, marca Join spaces and group conversations.
- En Connection settings, selecciona HTTP endpoint URL.
- En Triggers, selecciona Use a common HTTP endpoint URL for all triggers y configúrala a la URL pública de tu gateway seguida de /googlechat.
  - Consejo: Ejecuta openclaw status para encontrar la URL pública de tu gateway.
- En Visibility, marca Make this Chat app available to specific people and groups in <Your Domain>.
- Ingresa tu dirección de email (por ejemplo [email protected]) en el campo de texto.
- Haz clic en Save en la parte inferior.
Habilita el estado de la app:
- Después de guardar, recarga la página.
- Busca la sección App status (generalmente cerca de la parte superior o inferior después de guardar).
- Cambia el estado a Live - available to users.
- Haz clic en Save de nuevo.
Configura OpenClaw con la ruta de la cuenta de servicio + audiencia del webhook:
- Variable de entorno: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- O configuración: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
Configura el tipo y valor de audiencia del webhook (debe coincidir con la configuración de tu app de Chat).
Inicia el gateway. Google Chat enviará POSTs a tu ruta de webhook.

Añadir a Google Chat

Una vez que el gateway esté ejecutándose y tu email esté en la lista de visibilidad:

Ve a Google Chat.
Haz clic en el icono + (más) junto a Direct Messages.
En la barra de búsqueda (donde normalmente agregas personas), escribe el Nombre de la app que configuraste en la Consola de Google Cloud.
- Nota: El bot no aparecerá en la lista del “Marketplace” porque es una app privada. Debes buscarlo por nombre.
Selecciona tu bot de los resultados.
Haz clic en Add o Chat para iniciar una conversación 1:1.
Envía “Hola” para activar al asistente.

URL pública (solo webhook)

Los webhooks de Google Chat requieren un endpoint HTTPS público. Por seguridad, solo expón la ruta /googlechat a internet. Mantén el dashboard de OpenClaw y otros endpoints sensibles en tu red privada.

Opción A: Tailscale Funnel (recomendado)

Usa Tailscale Serve para el dashboard privado y Funnel para la ruta pública del webhook. Esto mantiene / privado mientras expone solo /googlechat.

Verifica a qué dirección está vinculado tu gateway:
```
ss -tlnp | grep 18789
```
Anota la dirección IP (por ejemplo, 127.0.0.1, 0.0.0.0, o tu IP de Tailscale como 100.x.x.x).

Expón el dashboard solo a la tailnet (puerto 8443):

# Si está vinculado a localhost (127.0.0.1 o 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789

# Si está vinculado solo a la IP de Tailscale (por ejemplo, 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789

Expón solo la ruta del webhook públicamente:

# Si está vinculado a localhost (127.0.0.1 o 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

# Si está vinculado solo a la IP de Tailscale (por ejemplo, 100.106.161.80):
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat

Autoriza el nodo para acceso Funnel: Si se te solicita, visita la URL de autorización mostrada en la salida para habilitar Funnel para este nodo en la política de tu tailnet.

Verifica la configuración:

tailscale serve status
tailscale funnel status

Tu URL pública del webhook será: https://<node-name>.<tailnet>.ts.net/googlechat

Tu dashboard privado permanece solo en la tailnet: https://<node-name>.<tailnet>.ts.net:8443/

Usa la URL pública (sin :8443) en la configuración de la app de Google Chat.

Nota: Esta configuración persiste entre reinicios. Para eliminarla después, ejecuta tailscale funnel reset y tailscale serve reset.

Opción B: Proxy inverso (Caddy)

Si usas un proxy inverso como Caddy, solo haz proxy de la ruta específica:

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

Con esta configuración, cualquier solicitud a your-domain.com/ será ignorada o devolverá 404, mientras que your-domain.com/googlechat se enruta de forma segura a OpenClaw.

Opción C: Cloudflare Tunnel

Configura las reglas de ingress de tu tunnel para solo enrutar la ruta del webhook:

Path: /googlechat -> http://localhost:18789/googlechat
Regla predeterminada: HTTP 404 (Not Found)

Cómo funciona

Google Chat envía POSTs de webhook al gateway. Cada solicitud incluye un encabezado Authorization: Bearer <token>.
- OpenClaw verifica la autenticación del bearer antes de leer/analizar los cuerpos completos del webhook cuando el encabezado está presente.
- Las solicitudes de Google Workspace Add-on que incluyen authorizationEventObject.systemIdToken en el cuerpo son compatibles mediante un presupuesto más estricto de pre-autenticación del cuerpo.
OpenClaw verifica el token contra el audienceType + audience configurados:
- audienceType: "app-url" → la audiencia es tu URL de webhook HTTPS.
- audienceType: "project-number" → la audiencia es el número del proyecto Cloud.
Los mensajes se enrutan por space:
- Los DMs usan la clave de sesión agent:<agentId>:googlechat:direct:<spaceId>.
- Los Spaces usan la clave de sesión agent:<agentId>:googlechat:group:<spaceId>.
El acceso a DMs es por emparejamiento de forma predeterminada. Los remitentes desconocidos reciben un código de emparejamiento; aprueba con:
- openclaw pairing approve googlechat <code>
Los spaces de grupo requieren @mención de forma predeterminada. Usa botUser si la detección de menciones necesita el nombre de usuario de la app.

Destinos

Usa estos identificadores para entrega y listas de acceso:

Mensajes directos: users/<userId> (recomendado).
El email sin formato [email protected] es mutable y solo se usa para coincidencia directa de lista de acceso cuando channels.googlechat.dangerouslyAllowNameMatching: true.
Obsoleto: users/<email> se trata como ID de usuario, no como lista de acceso por email.
Spaces: spaces/<spaceId>.

Configuración destacada

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      // o serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // opcional; ayuda a la detección de menciones
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          allow: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Short answers only.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

Notas:

Las credenciales de la cuenta de servicio también se pueden pasar en línea con serviceAccount (cadena JSON).
serviceAccountRef también es compatible (SecretRef de env/archivo), incluyendo refs por cuenta bajo channels.googlechat.accounts.<id>.serviceAccountRef.
La ruta de webhook predeterminada es /googlechat si webhookPath no está configurado.
dangerouslyAllowNameMatching reactiva la coincidencia mutable de email para listas de acceso (modo de compatibilidad de emergencia).
Las reacciones están disponibles vía la herramienta reactions y channels action cuando actions.reactions está habilitado.
typingIndicator soporta none, message (predeterminado), y reaction (reaction requiere OAuth de usuario).
Los adjuntos se descargan a través de la API de Chat y se almacenan en el pipeline de multimedia (tamaño limitado por mediaMaxMb).

Detalles de referencia de secretos: Gestión de Secretos.

Resolución de problemas

405 Method Not Allowed

Si Google Cloud Logs Explorer muestra errores como:

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

Esto significa que el manejador de webhook no está registrado. Causas comunes:

Canal no configurado: La sección channels.googlechat falta en tu configuración. Verifica con:
```
openclaw config get channels.googlechat
```
Si devuelve “Config path not found”, añade la configuración (ver Configuración destacada).
Plugin no habilitado: Verifica el estado del plugin:
```
openclaw plugins list | grep googlechat
```
Si muestra “disabled”, añade plugins.entries.googlechat.enabled: true a tu configuración.
Gateway no reiniciado: Después de añadir la configuración, reinicia el gateway:
```
openclaw gateway restart
```

Verifica que el canal esté ejecutándose:

openclaw channels status
# Debería mostrar: Google Chat default: enabled, configured, ...

Otros problemas

Revisa openclaw channels status --probe para errores de autenticación o configuración de audiencia faltante.
Si no llegan mensajes, confirma la URL del webhook y las suscripciones de eventos de la app de Chat.
Si la restricción por mención bloquea las respuestas, configura botUser con el nombre de recurso de usuario de la app y verifica requireMention.
Usa openclaw logs --follow mientras envías un mensaje de prueba para ver si las solicitudes llegan al gateway.

Documentación relacionada: