docs/channels/googlechat.md
Status: downloadable plugin for DMs + spaces via Google Chat API webhooks (HTTP only).
Install Google Chat before configuring the channel:
openclaw plugins install @openclaw/googlechat
Local checkout (when running from a git repo):
openclaw plugins install ./path/to/local/googlechat-plugin
openclaw-chat).~/.openclaw/googlechat-service-account.json).OpenClaw)https://openclaw.ai/logo.png)Personal AI Assistant)/googlechat.
openclaw status to find your gateway's public URL.<Your Domain>.[email protected]) in the text box.GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.jsonchannels.googlechat.serviceAccountFile: "/path/to/service-account.json".Once the gateway is running and your email is added to the visibility list:
Google Chat webhooks require a public HTTPS endpoint. For security, only expose the /googlechat path to the internet. Keep the OpenClaw dashboard and other sensitive endpoints on your private network.
Use Tailscale Serve for the private dashboard and Funnel for the public webhook path. This keeps / private while exposing only /googlechat.
Check what address your gateway is bound to:
ss -tlnp | grep 18789
Note the IP address (e.g., 127.0.0.1, 0.0.0.0, or your Tailscale IP like 100.x.x.x).
Expose the dashboard to the tailnet only (port 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 Tailscale IP only (e.g., 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789
Expose only the webhook path publicly:
# 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 Tailscale IP only (e.g., 100.106.161.80):
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
Authorize the node for Funnel access: If prompted, visit the authorization URL shown in the output to enable Funnel for this node in your tailnet policy.
Verify the configuration:
tailscale serve status
tailscale funnel status
Your public webhook URL will be:
https://<node-name>.<tailnet>.ts.net/googlechat
Your private dashboard stays tailnet-only:
https://<node-name>.<tailnet>.ts.net:8443/
Use the public URL (without :8443) in the Google Chat app config.
Note: This configuration persists across reboots. To remove it later, run
tailscale funnel resetandtailscale serve reset.
If you use a reverse proxy like Caddy, only proxy the specific path:
your-domain.com {
reverse_proxy /googlechat* localhost:18789
}
With this config, any request to your-domain.com/ will be ignored or returned as 404, while your-domain.com/googlechat is safely routed to OpenClaw.
Configure your tunnel's ingress rules to only route the webhook path:
/googlechat -> http://localhost:18789/googlechatAuthorization: Bearer <token> header.
authorizationEventObject.systemIdToken in the body are supported via a stricter pre-auth body budget.audienceType + audience:
audienceType: "app-url" → audience is your HTTPS webhook URL.audienceType: "project-number" → audience is the Cloud project number.agent:<agentId>:googlechat:direct:<spaceId>.agent:<agentId>:googlechat:group:<spaceId>.openclaw pairing approve googlechat <code>botUser if mention detection needs the app’s user name.Use these identifiers for delivery and allowlists:
users/<userId> (recommended).[email protected] is mutable and only used for direct allowlist matching when channels.googlechat.dangerouslyAllowNameMatching: true.users/<email> is treated as a user id, not an email allowlist.spaces/<spaceId>.{
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",
webhookPath: "/googlechat",
botUser: "users/1234567890", // optional; helps mention detection
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,
},
},
}
Notes:
serviceAccount (JSON string).serviceAccountRef is also supported (env/file SecretRef), including per-account refs under channels.googlechat.accounts.<id>.serviceAccountRef./googlechat if webhookPath isn’t set.dangerouslyAllowNameMatching re-enables mutable email principal matching for allowlists (break-glass compatibility mode).reactions tool and channels action when actions.reactions is enabled.send for text and upload-file for explicit attachment sends. upload-file accepts media / filePath / path plus optional message, filename, and thread targeting.typingIndicator supports none, message (default), and reaction (reaction requires user OAuth).mediaMaxMb).Secrets reference details: Secrets Management.
If Google Cloud Logs Explorer shows errors like:
status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
This means the webhook handler isn't registered. Common causes:
Channel not configured: The channels.googlechat section is missing from your config. Verify with:
openclaw config get channels.googlechat
If it returns "Config path not found", add the configuration (see Config highlights).
Plugin not enabled: Check plugin status:
openclaw plugins list | grep googlechat
If it shows "disabled", add plugins.entries.googlechat.enabled: true to your config.
Gateway not restarted: After adding config, restart the gateway:
openclaw gateway restart
Verify the channel is running:
openclaw channels status
# Should show: Google Chat default: enabled, configured, ...
openclaw channels status --probe for auth errors or missing audience config.botUser to the app's user resource name and verify requireMention.openclaw logs --follow while sending a test message to see if requests reach the gateway.Related docs: