OpenClaw

OpenClaw Google Chat Channel

Enterprise
Medium

Connect OpenClaw to Google Chat using the Google Chat API via an HTTP endpoint. This enterprise integration lets your AI assistant operate in Google Workspace — handling direct messages and space conversations. The bot receives HTTP POST requests from Google Chat, validates bearer tokens via a service account, and routes messages through the OpenClaw Gateway.

Quick Info
DifficultyMedium
CategoryEnterprise
Features Supported5 / 6

Google Chat Supported Features

Text Messages

Supported

Media & Files

Supported

Reactions

Supported

Threads

Supported

Voice Messages

Not Supported

Group Chat

Supported

Google Chat Prerequisites

  • A Google Workspace account (Business or Enterprise). Domain admin access may be needed for authorization scope approvals and app visibility settings
  • Google Cloud project with the Google Chat API enabled
  • A service account with a JSON key file
  • OpenClaw Gateway running and configured
  • A publicly accessible HTTPS endpoint for the webhook (e.g., via Tailscale Funnel, Caddy, or Cloudflare Tunnel)

Google Chat Quick Setup

1

Enable Google Chat API & create service account

Go to the Google Cloud Console, enable the Google Chat API. Create a new service account (e.g., 'openclaw-chat'), skip permission configurations, then generate and download a JSON key file. Store it on your gateway host (e.g., ~/.openclaw/googlechat-service-account.json).

2

Configure Chat App in Google Cloud Console

In the Google Cloud Console Chat Configuration, set up the app name, avatar URL, and description. Enable interactive features, allow the app to join spaces/group conversations. Select 'HTTP endpoint URL' as the connection setting and enter your gateway's public URL followed by '/googlechat' (use 'openclaw status' to find the gateway URL).

3

Set visibility, enable the app, and test

Restrict app availability to specific users or groups in your domain. Save the configuration, refresh the page, and change the app status to 'Live — available to users'. In Google Chat, click the '+' icon next to Direct Messages, search for your app name, and send a test message.

Google Chat Configuration Example

config.json
{
  "channels": {
    "googlechat": {
      "serviceAccountFile": "~/.openclaw/googlechat-service-account.json",
      "webhookPath": "/googlechat"
    }
  }
}

Google Chat Deep Dive

Architecture Overview

OpenClaw integrates with Google Chat through an HTTP endpoint architecture. The flow works as follows: 1. Google Chat sends HTTP POST requests to your gateway endpoint with an 'Authorization: Bearer <token>' header. 2. OpenClaw validates the bearer token against your configured audience settings. When the audience is set to app-url, the token is an OIDC ID token; when set to project-number, it is a self-signed JWT. 3. Messages are routed through session keys that differentiate between DMs and spaces. 4. Access control uses pairing codes for DMs and @-mentions for group spaces by default. Unlike WebSocket-based channels, Google Chat requires a publicly accessible HTTPS endpoint. The gateway listens for incoming POST requests on the configured endpoint path (default: /googlechat).
Use 'openclaw status' to find your gateway's public URL for the webhook configuration.
The service account JSON key file contains sensitive credentials — store it securely and restrict file permissions.

Service Account Setup

A Google Cloud service account is required for authentication. Follow these steps: 1. Go to the Google Cloud Console → IAM & Admin → Service Accounts 2. Click 'Create Service Account' 3. Name it (e.g., 'openclaw-chat') and skip the optional permission configurations 4. Click on the created service account → Keys tab → Add Key → Create new key 5. Select JSON format and download the key file 6. Place the file on your gateway host at a secure location (e.g., ~/.openclaw/googlechat-service-account.json) The service account credentials are used to validate incoming webhook requests from Google Chat and to send outbound messages via the Google Chat API.
openclaw.json
{
  "channels": {
    "googlechat": {
      "serviceAccountFile": "~/.openclaw/googlechat-service-account.json"
    }
  }
}
Never commit the service account JSON key file to version control. Add the file path to your .gitignore and restrict file permissions to the gateway process user.

Chat App Configuration

Configure the Chat App in the Google Cloud Console: 1. Navigate to Google Cloud Console → APIs & Services → Google Chat API → Configuration 2. Set the app name, avatar URL, and description 3. Under 'Interactive features', enable interactive features 4. Allow the app to join spaces and group conversations 5. Set the connection setting to 'HTTP endpoint URL' 6. Enter your gateway's public webhook URL (e.g., https://your-domain.com/googlechat) 7. Under 'Visibility', restrict access to specific users or groups in your domain 8. Save the configuration, refresh, and set the app status to 'Live — available to users' Note: Private apps don't appear in the Google Chat marketplace browsing. Users must search for the app by its exact name to find and add it.
After saving the configuration, you may need to refresh the page to see the status toggle.
Users add the bot by clicking '+' next to Direct Messages in Google Chat and searching for the configured app name.

Public URL & Webhook Configuration

Google Chat requires a publicly accessible HTTPS endpoint to send webhook events. There are three recommended options: Option A — Tailscale Funnel (Recommended): • Check gateway binding address: ss -tlnp | grep 18789 • Expose webhook publicly: tailscale funnel --set-path=/googlechat localhost:18789 • Public URL format: https://<node-name>.<tailnet>.ts.net/googlechat Option B — Caddy Reverse Proxy: • Limit proxying to the specific path: reverse_proxy /googlechat* localhost:18789 Option C — Cloudflare Tunnel: • Configure ingress rules to route only /googlechat path to the gateway, with default 404 for other requests. Whichever option you choose, the resulting public URL should be entered as the HTTP endpoint URL in the Google Chat app configuration.
terminal / config
# Tailscale Funnel example:
tailscale funnel --set-path=/googlechat localhost:18789

# Caddy example:
reverse_proxy /googlechat* localhost:18789

# Cloudflare Tunnel ingress:
- hostname: your-domain.com
  path: /googlechat
  service: http://localhost:18789
- service: http_status:404
Tailscale Funnel is recommended because it handles HTTPS certificates automatically and requires minimal configuration.
Only expose the /googlechat path publicly — do not expose your entire gateway to the internet.

DM & Group Policies

OpenClaw controls access to your Google Chat bot through DM and group policies: DM Policy (default: pairing): • pairing — New contacts must go through a pairing flow with a code you approve via CLI • allowlist — Only explicitly listed users can message the bot • open — Anyone can message the bot (use with caution) Group Policy: • By default, the bot responds only when @-mentioned in group spaces • You can configure an allowlist of specific spaces • Per-space configuration supports custom system prompts Access control differs between DMs and spaces: DMs use pairing codes by default, while spaces use @-mention activation.
openclaw.json
{
  "channels": {
    "googlechat": {
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "groupAllowList": ["spaces/AAAA1234"]
    }
  }
}

Targets & Session Routing

Google Chat targets are used for outbound messaging and session identification: • Direct messages: users/<userId> or users/<email> • Spaces: spaces/<spaceId> Session keys differentiate between DMs and spaces, ensuring each conversation has its own isolated context. The bot user identifier (botUser) is used for mention detection in group spaces. You can also configure individual spaces with custom settings including system prompts and access controls.
openclaw.json
{
  "channels": {
    "googlechat": {
      "botUser": "users/123456789",
      "spaces": {
        "spaces/AAAA1234": {
          "systemPrompt": "You are a helpful assistant for the engineering team."
        }
      }
    }
  }
}
Set the botUser field to enable accurate @-mention detection in group spaces.
Space IDs can be found in the Google Chat URL or in gateway logs when a space message is received.

Google Chat Configuration Reference

serviceAccountFile
Type: stringDefault: ""

Path to the Google Cloud service account JSON key file

audience
Type: stringDefault: "app-url"

Audience type for bearer token validation. When set to app-url, Google Chat sends an OIDC ID token; when set to project-number, it sends a self-signed JWT. Options: app-url, project-number

audienceValue
Type: stringDefault: ""

The audience value used for token validation (URL or project number)

webhookPath
Type: stringDefault: "/googlechat"

HTTP endpoint path for incoming Google Chat webhooks

botUser
Type: stringDefault: ""

Bot user identifier (users/<id>) for @-mention detection in spaces

dmPolicy
Type: stringDefault: "pairing"

Controls who can DM the bot. Options: pairing, allowlist, open, disabled

allowFrom
Type: string[]Default: []

User IDs or emails allowed to message the bot (when dmPolicy is allowlist)

groupPolicy
Type: stringDefault: "disabled"

Group space policy. Options: disabled, allowlist, open

groupAllowList
Type: string[]Default: []

Space IDs allowed when groupPolicy is allowlist

spaces.<id>.systemPrompt
Type: stringDefault: ""

Custom AI system prompt for a specific Google Chat space

mediaMaxMb
Type: numberDefault: 20

Maximum media file size in megabytes

actions.typing
Type: booleanDefault: true

Send typing indicators while the AI is generating a response

Google Chat Frequently Asked Questions

Google Chat Troubleshooting

405 Method Not Allowed error on webhook

The Google Chat plugin is not enabled, the channels.googlechat configuration section is missing, or the Gateway was not restarted after configuration changes.

Verify your configuration: run 'openclaw config get channels.googlechat' to check the config exists. Run 'openclaw plugins list | grep googlechat' to verify the plugin is active. Restart the gateway with 'openclaw gateway restart' and check status with 'openclaw channels status'.
Authentication errors or token validation failures

The service account file path is incorrect, the audience setting doesn't match, or the bearer token is expired.

Run 'openclaw channels status --probe' to diagnose authentication errors. Verify the serviceAccountFile path points to a valid JSON key file. Check that the audience type and value match your Google Cloud project configuration.
Bot doesn't respond to messages in spaces

The bot user identifier is not configured for mention detection, or the space is not in the allowlist.

Set the botUser field in your config for accurate @-mention detection. If using groupPolicy: allowlist, make sure the space ID is listed in groupAllowList. Check gateway logs with 'openclaw logs --follow' while sending a test message.
Webhook URL not reachable from Google Chat

The public URL is not properly configured, firewall is blocking incoming connections, or SSL certificate is invalid.

Verify the Chat app webhook URL matches your gateway's public endpoint. Test the URL is accessible from the internet. If using Tailscale Funnel, run 'tailscale funnel status' to verify the configuration. For Caddy or Cloudflare, check your reverse proxy logs.
View Full DocumentationBack to All Channels

Related Channels

Feishu / Lark

Medium

OpenClaw Feishu/Lark integration via WebSocket

Setup Guide

Slack

Medium

OpenClaw workspace app via Bolt SDK

Setup Guide

Microsoft Teams

Medium

OpenClaw enterprise integration via Bot Framework

Setup Guide