OpenClaw Google Chat Integration: Webhook Auth and Setup Guide

Google Chat Integration Overview

Google Chat is one of OpenClaw's more complex integrations to set up. Unlike WhatsApp or Telegram where you scan a QR code or paste a bot token, Google Chat requires a Google Cloud project, a Chat API app, service account credentials, and workspace admin approval. The process involves three separate Google consoles (Cloud Console, Apps Script, and Admin Console) and the authentication flow is not well documented in OpenClaw's official docs.

This guide walks through the entire setup process, including the appPrincipal authentication requirement that trips up most operators. The discussion in GitHub issue #53888 surfaced many of these undocumented requirements, and this guide consolidates the community's findings into a step-by-step process.

There are two modes for receiving messages from Google Chat:

• HTTP endpoint (push): Google Chat sends messages to a public HTTPS URL on your OpenClaw server. This is the faster option but requires a public URL with a valid SSL certificate.
• Cloud Pub/Sub (pull): Google Chat publishes messages to a Pub/Sub topic, and OpenClaw polls the topic for new messages. This works without a public URL but adds latency (typically 1-3 seconds).

For sending messages, both modes use the Chat API with service account credentials. The mode choice only affects how OpenClaw receives incoming messages.

Prerequisites

Before starting the setup, make sure you have:

• Google Workspace account: Google Chat apps only work with Google Workspace (formerly G Suite). Personal Gmail accounts do not support Chat apps. If your organization uses Google Workspace, you are good.
• Admin access: You need Google Workspace admin access to publish the Chat app. A regular user account cannot create or deploy Chat apps, even for internal use.
• OpenClaw running: Your OpenClaw instance should already be deployed and accessible. If you are using HTTP endpoint mode, it needs a public URL with HTTPS.
• Google Cloud project: You can use an existing project or create a new one. The Chat API and Cloud Pub/Sub API (if using pull mode) need to be enabled.

Google Cloud Project Setup

Start by creating or selecting a Google Cloud project:

1. Go to console.cloud.google.com
2. Create a new project or select an existing one
3. Note the project ID — you will need it for OpenClaw's configuration

Enable the required APIs. Navigate to APIs & Services > Library and enable:

• Google Chat API — required for all Chat integrations
• Cloud Pub/Sub API — only required if using pull mode

Create a service account. Go to IAM & Admin > Service Accounts:

1. Click "Create Service Account"
2. Name it something descriptive like openclaw-chat-bot
3. Grant the role "Chat Bots Owner" (or "Chat Bots Viewer" for read-only access)
4. If using Pub/Sub mode, also grant "Pub/Sub Subscriber"
5. Click "Done"

Generate a key for the service account:

1. Click on the service account you just created
2. Go to the "Keys" tab
3. Click "Add Key" > "Create new key"
4. Select JSON format
5. Download the JSON key file

This JSON key file contains the credentials that OpenClaw will use to authenticate with the Chat API. Store it securely — it has full access to your Chat bot.

Next, configure the Chat API app. Go to APIs & Services > Google Chat API > Configuration:

• Set the app name (this is what users will see in Google Chat)
• Set the avatar URL (optional)
• Set the description
• Under "Connection settings," choose your mode:
  • For HTTP endpoint: enter your OpenClaw URL + /api/channels/google-chat/webhook
  • For Cloud Pub/Sub: enter the Pub/Sub topic name (create one first in the Pub/Sub console)
• Under "Visibility," set it to "Make this Chat app available to specific people and groups in your domain" and add the users or groups who should have access

Understanding appPrincipal Authentication

This is where most operators get stuck. The appPrincipal authentication is Google Chat's mechanism for verifying that incoming webhook requests are actually from Google and not from an attacker sending fake messages to your endpoint.

When Google Chat sends a message to your HTTP endpoint, the request includes a Bearer token in the Authorization header. Your OpenClaw instance needs to verify this token to confirm the request came from Google. The token is a signed JWT (JSON Web Token) that Google signs with its private key.

To verify the JWT, OpenClaw needs to know the expected audience value. This is your Google Cloud project number (not the project ID — the numeric project number). You can find it in your Google Cloud Console dashboard.

Set the following environment variables in your OpenClaw configuration:

OPENCLAW_GOOGLE_CHAT_ENABLED=true
OPENCLAW_GOOGLE_CHAT_PROJECT_NUMBER=123456789012
OPENCLAW_GOOGLE_CHAT_CREDENTIALS_FILE=/app/data/google-chat-credentials.json

The credentials file path should point to the JSON key file you downloaded earlier. Mount it into the Docker container via your docker-compose.yml volumes section:

volumes:
  - ./data:/app/data
  - ./google-chat-credentials.json:/app/data/google-chat-credentials.json:ro

The :ro flag mounts the credentials file as read-only, which is a security best practice.

The appPrincipal verification happens automatically once you set the project number. OpenClaw fetches Google's public keys, verifies the JWT signature, checks the audience matches your project number, and confirms the token has not expired. If any of these checks fail, the request is rejected with a 401 Unauthorized response.

This is the part that is poorly documented in OpenClaw's official docs. The docs mention Google Chat integration but do not explain the appPrincipal flow or the difference between project ID and project number. GitHub issue #53888 has extensive community discussion about this gap.

OpenClaw Configuration

Here is the complete set of environment variables for Google Chat integration in HTTP endpoint mode:

# Enable Google Chat channel
OPENCLAW_GOOGLE_CHAT_ENABLED=true

# Your Google Cloud project number (numeric, not the project ID)
OPENCLAW_GOOGLE_CHAT_PROJECT_NUMBER=123456789012

# Path to the service account JSON key file
OPENCLAW_GOOGLE_CHAT_CREDENTIALS_FILE=/app/data/google-chat-credentials.json

# Mode: 'http' for push, 'pubsub' for pull
OPENCLAW_GOOGLE_CHAT_MODE=http

# Optional: restrict which spaces (rooms) the bot responds in
# Comma-separated list of space IDs. Leave empty to respond in all spaces.
OPENCLAW_GOOGLE_CHAT_ALLOWED_SPACES=

# Optional: respond to @mentions only, or all messages
OPENCLAW_GOOGLE_CHAT_MENTION_ONLY=false

Add these to your docker-compose.yml and restart. After restarting, check the logs for successful initialization:

docker logs openclaw --tail 50 | grep -i "google"

You should see a line indicating the Google Chat channel is connected and listening.

To test, open Google Chat in your browser, search for your app by name, and send it a message. If everything is configured correctly, the message should appear in OpenClaw's logs and the bot should respond.

Alternative: Cloud Pub/Sub Mode

If you do not have a public URL for your OpenClaw instance (for example, running on a local network or behind a firewall), Cloud Pub/Sub mode is the alternative. Instead of Google Chat pushing messages to your server, it publishes them to a Pub/Sub topic, and OpenClaw pulls from that topic.

First, create a Pub/Sub topic in your Google Cloud Console:

1. Navigate to Pub/Sub > Topics
2. Click "Create Topic"
3. Name it openclaw-google-chat
4. Leave default settings

Create a subscription:

1. Click on the topic
2. Click "Create Subscription"
3. Name it openclaw-google-chat-sub
4. Set delivery type to "Pull"
5. Set acknowledgement deadline to 60 seconds

Update the Chat API configuration to use Pub/Sub instead of HTTP endpoint. In the Chat API Configuration page, change the connection settings to "Cloud Pub/Sub" and enter your topic name.

Update your OpenClaw environment:

OPENCLAW_GOOGLE_CHAT_MODE=pubsub
OPENCLAW_GOOGLE_CHAT_PUBSUB_TOPIC=projects/your-project-id/topics/openclaw-google-chat
OPENCLAW_GOOGLE_CHAT_PUBSUB_SUBSCRIPTION=projects/your-project-id/subscriptions/openclaw-google-chat-sub

Pub/Sub mode adds 1-3 seconds of latency compared to HTTP endpoint mode because OpenClaw polls for new messages rather than receiving them instantly. The default poll interval is 1 second, configurable via OPENCLAW_GOOGLE_CHAT_POLL_INTERVAL=1000 (milliseconds).

The advantage of Pub/Sub is that it works from anywhere — your home network, a private VPS, behind a corporate firewall. No public URL or SSL certificate needed. The tradeoff is the additional latency and the slightly more complex setup.

Troubleshooting Common Issues

"401 Unauthorized" on incoming messages: The appPrincipal verification is failing. Check that you are using the project number (numeric), not the project ID (alphanumeric). These are different values in Google Cloud. Find your project number on the Cloud Console dashboard.

"Permission denied" when sending messages: The service account does not have the correct Chat API permissions. Go to IAM & Admin and verify the service account has the "Chat Bots Owner" role. Also verify the JSON key file is correctly mounted in the Docker container.

Bot does not appear in Google Chat search: The Chat app has not been published. Go to the Chat API Configuration page and ensure the app visibility is set correctly. It can take up to 24 hours for a newly published app to appear in Chat search for all users in the workspace.

Bot receives messages but does not respond: Check OpenClaw logs for errors in the Google Chat handler. Common causes: the agent's model is rate-limited, the gateway token is not set, or there is a message filter blocking the response. Also check that OPENCLAW_GOOGLE_CHAT_MENTION_ONLY is set to false if you want the bot to respond to all messages (not just @mentions).

"API not enabled" error: You forgot to enable the Google Chat API in your Cloud project. Go to APIs & Services > Library, search for "Google Chat API," and enable it.

Frequently Asked Questions

Does OpenClaw work with Google Chat?

Yes. OpenClaw supports Google Chat integration through the Google Chat API using webhook-based or HTTP endpoint connections. You need a Google Cloud project with the Chat API enabled and a service account with the correct permissions. The setup requires Google Workspace admin access.

What is appPrincipal and why does OpenClaw need it for Google Chat?

appPrincipal is Google Chat's authentication mechanism for bot applications. It allows your OpenClaw instance to authenticate as a Chat app rather than as a user. This is required for receiving messages via HTTP endpoint (push) mode. Without appPrincipal, your bot can only send messages via webhooks but cannot receive incoming messages from users.

Do I need Google Workspace admin access for OpenClaw Google Chat?

Yes. Publishing a Chat app (even an internal one) requires Google Workspace admin permissions. A regular Google Workspace user cannot create or publish Chat apps. You need the admin to either set up the app themselves or grant you the necessary permissions in the Google Cloud Console and Admin Console.

Can I use OpenClaw Google Chat without a public URL?

Partially. You can use Google Chat webhooks (outbound only) without a public URL. However, to receive incoming messages from users, you need either a public HTTPS endpoint for HTTP endpoint mode, or you can use Cloud Pub/Sub as an intermediary. The Pub/Sub approach lets OpenClaw pull messages without exposing a public URL.