OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Mainstream messaging

Google Chat

Google Chat se ejecuta como el Plugin oficial @openclaw/googlechat: mensajes directos y espacios mediante Webhooks de la API de Google Chat (solo endpoint HTTP, sin Pub/Sub).

Instalación

bash
openclaw plugins install @openclaw/googlechat

Repositorio local (cuando se ejecuta desde un repositorio git):

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

Configuración rápida (principiantes)

  1. Cree un proyecto de Google Cloud y habilite la Google Chat API.
  2. Cree una Service Account:
    • Pulse Create Credentials > Service Account.
    • Asígnele el nombre que desee (por ejemplo, openclaw-chat).
    • Deje en blanco los permisos y las entidades principales (Continue y, después, Done).
  3. Cree y descargue la clave JSON:
    • Haga clic en la nueva cuenta de servicio > pestaña Keys > Add Key > Create new key > JSON > Create.
  4. Guarde el archivo JSON descargado en el host del Gateway (por ejemplo, ~/.openclaw/googlechat-service-account.json).
  5. Cree una aplicación de Google Chat en la configuración de Chat de Google Cloud Console:
    • Complete Application info (nombre de la aplicación, URL del avatar y descripción).
    • Habilite Interactive features.
    • En Functionality, marque Join spaces and group conversations.
    • En Connection settings, seleccione HTTP endpoint URL.
    • En Triggers, seleccione Use a common HTTP endpoint URL for all triggers y establézcalo en la URL pública del Gateway seguida de /googlechat (consulte URL pública).
    • En Visibility, marque Make this Chat app available to specific people and groups in <Your Domain> e introduzca su dirección de correo electrónico.
    • Haga clic en Save.
  6. Habilite el estado de la aplicación: actualice la página, busque App status, establézcalo en Live - available to users y vuelva a pulsar Save.
  7. Configure OpenClaw con la cuenta de servicio y la audiencia del Webhook (debe coincidir con la configuración de la aplicación de Chat):
    • Variable de entorno: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json (solo para la cuenta predeterminada), o
    • Configuración: consulte Aspectos destacados de la configuración. openclaw channels add --channel googlechat también acepta --audience-type, --audience, --webhook-path y --webhook-url.
  8. Inicie el Gateway. Google Chat enviará solicitudes POST a la ruta de su Webhook (de forma predeterminada, /googlechat).

Añadir a Google Chat

Una vez que el Gateway esté en ejecución y su correo electrónico figure en la lista de visibilidad:

  1. Vaya a Google Chat.
  2. Haga clic en el icono + (más) junto a Direct Messages.
  3. Busque el App name que configuró en Google Cloud Console.
    • El bot no aparece en la lista de exploración de Marketplace porque es una aplicación privada; búsquelo por su nombre.
  4. Seleccione el bot, haga clic en Add o Chat y envíe un mensaje.

URL pública (solo Webhook)

Los Webhooks de Google Chat requieren un endpoint HTTPS público. Por seguridad, exponga a Internet únicamente la ruta /googlechat y mantenga privados el panel de OpenClaw y los demás endpoints.

Opción A: Tailscale Funnel (recomendada)

Use Tailscale Serve para el panel privado y Funnel para la ruta pública del Webhook.

  1. Compruebe a qué dirección está vinculado el Gateway:

    bash
    ss -tlnp | grep 18789

    Anote la IP (por ejemplo, 127.0.0.1, 0.0.0.0 o una dirección de Tailscale 100.x.x.x).

  2. Exponga el panel únicamente a la tailnet (puerto 8443):

    bash
    # 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. Exponga públicamente solo la ruta del Webhook:

    bash
    # 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 le solicita, visite la URL de autorización que aparece en la salida para habilitar Funnel en este Node.

  5. Verifique:

    bash
    tailscale serve statustailscale funnel status

La URL pública del Webhook es https://<node-name>.<tailnet>.ts.net/googlechat; el panel permanece disponible solo en la tailnet en https://<node-name>.<tailnet>.ts.net:8443/. Use la URL pública (sin :8443) en la configuración de la aplicación de Google Chat.

Nota: Esta configuración se conserva tras los reinicios. Para eliminarla más adelante, use tailscale funnel reset y tailscale serve reset.

Opción B: proxy inverso (Caddy)

Envíe mediante proxy únicamente la ruta del Webhook:

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

Las solicitudes a your-domain.com/ se ignoran o devuelven un error 404, mientras que your-domain.com/googlechat se dirige a OpenClaw.

Opción C: Cloudflare Tunnel

Configure las reglas de entrada del túnel para dirigir únicamente la ruta del Webhook:

  • Path: /googlechat -> http://localhost:18789/googlechat
  • Default rule: HTTP 404 (Not Found)

Funcionamiento

  1. Google Chat envía JSON mediante POST a la ruta del Webhook del Gateway (solo POST, se requiere el tipo de contenido JSON y se aplica un límite de frecuencia por IP).
  2. OpenClaw autentica cada solicitud antes de procesarla:
    • Los eventos de la aplicación de Chat incluyen Authorization: Bearer <token>; el token se verifica antes de analizar el cuerpo completo.
    • Los eventos de complementos de Google Workspace incluyen el token en el cuerpo (authorizationEventObject.systemIdToken) y se leen con límites de preautenticación más estrictos (16 KB, 3 s) antes de la verificación.
  3. El token se comprueba con audienceType + audience:
    • audienceType: "app-url" → la audiencia es la URL HTTPS de su Webhook.
    • audienceType: "project-number" → la audiencia es el número del proyecto de Cloud.
    • Los tokens de complementos con app-url requieren además que appPrincipal esté establecido en el ID de cliente numérico de OAuth 2.0 de la aplicación (21 dígitos, no un correo electrónico); de lo contrario, la verificación falla y se registra una advertencia.
  4. Los mensajes se enrutan por espacio:
    • Los espacios reciben sesiones específicas por espacio agent:<agentId>:googlechat:group:<spaceId>; las respuestas se envían al hilo del mensaje.
    • De forma predeterminada, los mensajes directos se agrupan en la sesión principal del agente; establezca session.dmScope para crear sesiones de mensajes directos por interlocutor (consulte Sesión).
  5. De forma predeterminada, el acceso a los mensajes directos utiliza emparejamiento. Los remitentes desconocidos reciben un código de emparejamiento; apruébelo con:
    • openclaw pairing approve googlechat <code>
  6. De forma predeterminada, los espacios de grupo requieren una @mención. Las menciones se detectan mediante anotaciones USER_MENTION de Chat dirigidas a la aplicación; establezca botUser (por ejemplo, users/1234567890) si la detección necesita el nombre de recurso de usuario de la aplicación.
  7. Cuando se inicia una aprobación de ejecución o de Plugin 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 contienen tokens opacos de devolución de llamada; la indicación manual /approve <id> <decision> solo aparece cuando la entrega nativa no está disponible.

Destinos

Use estos identificadores para la entrega y las listas de permitidos:

  • Mensajes directos: users/<userId> (recomendado).
  • Espacios: spaces/<spaceId>.
  • La dirección de correo sin procesar name@example.com es mutable y solo se utiliza para comprobar la lista de permitidos cuando channels.googlechat.dangerouslyAllowNameMatching: true.
  • Obsoleto: users/<email> se trata como un ID de usuario, no como una entrada de correo electrónico de la lista de permitidos.
  • Se aceptan y eliminan los prefijos googlechat:, google-chat: y gchat:.

Aspectos destacados de la configuración

json5
{  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.",        },      },      typingIndicator: "message",      mediaMaxMb: 20,    },  },}

Notas:

  • Credenciales de la cuenta de servicio: serviceAccountFile (ruta), serviceAccount (cadena JSON u objeto insertado) o serviceAccountRef (SecretRef de variable de entorno/archivo). Las variables de entorno GOOGLE_CHAT_SERVICE_ACCOUNT (JSON insertado) y GOOGLE_CHAT_SERVICE_ACCOUNT_FILE (ruta) se aplican únicamente a la cuenta predeterminada. Las configuraciones con varias cuentas utilizan channels.googlechat.accounts.<id> con las mismas claves, incluido un 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 identificadores estables de espacios (spaces/<spaceId>). Las claves basadas en nombres visibles están obsoletas y se registran como tales.
  • dangerouslyAllowNameMatching vuelve a habilitar la comparación de entidades principales mediante direcciones de correo mutables para las listas de permitidos (modo de compatibilidad de emergencia); el doctor advierte sobre las entradas de correo electrónico.
  • Las acciones de reacción de Google Chat no están disponibles. El Plugin utiliza autenticación mediante cuenta de servicio, mientras que los endpoints de reacciones de Google Chat requieren autenticación de usuario. La configuración existente de actions.reactions se acepta por compatibilidad, pero no tiene ningún efecto.
  • Las tarjetas de aprobación nativas utilizan clics en botones cardsV2 de Google Chat, no eventos de reacción. Los aprobadores proceden de dm.allowFrom o defaultTo y deben ser valores numéricos estables con el formato users/<id>.
  • Las acciones de mensajes solo ofrecen el envío de texto mediante send. La carga de archivos adjuntos de Google Chat requiere autenticación de usuario, mientras que este Plugin utiliza autenticación mediante cuenta de servicio, por lo que no se ofrece la carga de archivos salientes.
  • typingIndicator: message (valor predeterminado) publica un marcador de posición _&lt;Bot&gt; is typing..._ y lo sustituye por la primera respuesta; none lo deshabilita; reaction requiere OAuth de usuario y, actualmente, con la autenticación mediante cuenta de servicio utiliza message como alternativa y registra un error.
  • Los archivos adjuntos entrantes (el primero de cada mensaje) se descargan mediante la API de Chat y se introducen en el flujo de procesamiento multimedia, con el límite de mediaMaxMb (20 de forma predeterminada).
  • De forma predeterminada, se ignoran los mensajes creados por bots. Con allowBots: true, los mensajes de bots aceptados utilizan la protección compartida contra bucles de bots: configure channels.defaults.botLoopProtection y, después, sobrescríbala con channels.googlechat.botLoopProtection o channels.googlechat.groups.<space>.botLoopProtection.

Detalles sobre las referencias a secretos: Gestión de secretos.

Solución de problemas

405 Método no permitido

Si el explorador de registros de Google Cloud muestra errores como:

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

El controlador del Webhook no está registrado. Causas habituales:

  1. Canal no configurado: falta la sección channels.googlechat. Verifíquelo con:

    bash
    openclaw config get channels.googlechat

    Si devuelve "Config path not found", añada la configuración (consulte Aspectos destacados de la configuración).

  2. Plugin no habilitado: compruebe el estado del Plugin:

    bash
    openclaw plugins list | grep googlechat

    Si muestra "disabled", añada plugins.entries.googlechat.enabled: true a su configuración.

  3. El Gateway no se ha reiniciado después de cambiar la configuración:

    bash
    openclaw gateway restart

Compruebe que el canal esté en ejecución:

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

Otros problemas

  • openclaw channels status --probe muestra los errores de autenticación y la ausencia de configuración de audiencia (audience y audienceType son obligatorios).
  • Si no llega ningún mensaje, confirme la URL del Webhook de la aplicación de Chat y la configuración de los activadores.
  • Si el requisito de mención bloquea las respuestas, establezca botUser en el nombre de recurso de usuario de la aplicación y compruebe requireMention.
  • Ejecutar openclaw logs --follow mientras envía un mensaje de prueba muestra si las solicitudes llegan al Gateway.

Relacionado

Was this useful?
On this page

On this page