--- read_when: - Trabajo en las funciones del canal de Google Chat summary: Estado de compatibilidad, capacidades y configuración de la aplicación de Google Chat title: Google Chat x-i18n: generated_at: "2026-07-11T22:50:24Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 72a08c41f7da019f91265cbf7ae73134a0767c603449ebd8cd9a5354936a3b52 source_path: channels/googlechat.md workflow: 16 --- 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**. - Vaya a: [Credenciales de la API de Google Chat](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials) - Habilite la API si aún no está habilitada. 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](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat): - 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](#public-url-webhook-only)). - En **Visibility**, marque **Make this Chat app available to specific people and groups in ``** 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](#config-highlights). `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](https://chat.google.com/). 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 status tailscale funnel status ``` La URL pública del Webhook es `https://..ts.net/googlechat`; el panel permanece disponible solo en la tailnet en `https://..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 `; 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::googlechat:group:`; 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](/es/concepts/session)). 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 ` 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/`, 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 ` solo aparece cuando la entrega nativa no está disponible. ## Destinos Use estos identificadores para la entrega y las listas de permitidos: - Mensajes directos: `users/` (recomendado). - Espacios: `spaces/`. - 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/` 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.` 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/`). 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/`. - 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 `_ 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](/es/channels/bot-loop-protection): configure `channels.defaults.botLoopProtection` y, después, sobrescríbala con `channels.googlechat.botLoopProtection` o `channels.googlechat.groups..botLoopProtection`. Detalles sobre las referencias a secretos: [Gestión de secretos](/es/gateway/secrets). ## 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](#config-highlights)). 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 - [Descripción general de los canales](/es/channels) — todos los canales compatibles - [Enrutamiento de canales](/es/channels/channel-routing) — enrutamiento de sesiones para mensajes - [Configuración del Gateway](/es/gateway/configuration) - [Grupos](/es/channels/groups) — comportamiento de los chats grupales y control de menciones - [Emparejamiento](/es/channels/pairing) — autenticación de mensajes directos y flujo de emparejamiento - [Seguridad](/es/gateway/security) — modelo de acceso y protección