googlechatpubsub
Setup & Installation Guide

What it does, how it works, and what you need before you start.

What the Plugin Does

The googlechatpubsub plugin enables OpenClaw agents to listen to any Google Chat space continuously — without requiring @mentions. Messages are delivered via Google Cloud Pub/Sub in near-real-time, then routed to one or more configured agents based on keyword matching or always-on listeners.

Unlike the standard Chat REST API (which requires polling or webhooks), this plugin leverages the Google Workspace Events API to subscribe to space events and push them to a Pub/Sub topic. This gives you low-latency, reliable message delivery with automatic subscription renewal.

How It Works

When a message is sent in a monitored Chat space, Google's Workspace Events API fires an event that lands in your Pub/Sub topic. The plugin polls that subscription, decodes the event, and passes the message through OpenClaw's pipeline. Agents formulate a reply, which is sent back via the Google Chat REST API — all in under a second on a healthy connection.

Prerequisites

Six steps to configure Google Cloud. Work through them in order.

https://chat.google.com/room/AAQA6hUKWfM
                                      ↓
                              spaces/AAQA6hUKWfM

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://chat.googleapis.com/v1/spaces" | jq '.spaces[] | {name, displayName}'

Copy the plugin files into OpenClaw's extensions directory.

Clone the Repository

# Clone the plugin repo directly into the extensions directory
git clone https://github.com/teyou/openclaw-googlechatpubsub-plugin.git \
  ~/.openclaw/extensions/googlechatpubsub

Verify Files

ls ~/.openclaw/extensions/googlechatpubsub/
# Should output:
# CONTRIBUTING.md  LICENSE  README.md  index.ts  openclaw.plugin.json

Add the channel config and agent bindings to your openclaw.json.

Channel Config v0.2.0+

Add the following to your openclaw.json. Since v0.2.0 the plugin reads config from channels.googlechatpubsub (standard channel convention). The legacy plugins.entries path still works as a fallback.

{
  "plugins": {
    "allow": ["googlechatpubsub"]
  },

  "channels": {
    "googlechatpubsub": {
      "enabled": true,
      "projectId":        "my-gcp-project-id",
      "topicId":          "openclaw-gchat-events",
      "subscriptionId":   "openclaw-gchat-events-sub",
      "pollIntervalSeconds": 3,
      "renewalBufferMinutes": 30,
      "oauth": {
        "clientId":     "123456789-abc.apps.googleusercontent.com",
        "clientSecret": "GOCSPX-your-client-secret",
        "tokensFile":   "~/.openclaw/gchat-tokens.json"
      },
      "bindings": [
        {
          "space": "spaces/ABC123example",
          "replyInThread": true,
          "threadSessionIsolation": true,
          "agents": [
            {
              "agentId": "chief-of-staff",
              "alwaysListen": true
            },
            {
              "agentId": "engineer",
              "mentionKeyword": "eng"
            },
            {
              "agentId": "designer",
              "mentionKeyword": "design"
            }
          ]
        }
      ]
    }
  }
}

Root-Level Bindings

To route incoming Pub/Sub messages to the correct OpenClaw agent sessions, add a bindings array at the root of openclaw.json. Each binding maps an accountId (which matches the agentId in the channel config) to a specific agent.

{
  "bindings": [
    {
      "agentId": "chief-of-staff",
      "match": {
        "channel": "googlechatpubsub",
        "accountId": "chief-of-staff"
      }
    },
    {
      "agentId": "engineer",
      "match": {
        "channel": "googlechatpubsub",
        "accountId": "engineer"
      }
    },
    {
      "agentId": "designer",
      "match": {
        "channel": "googlechatpubsub",
        "accountId": "designer"
      }
    }
  ]
}

Multiple Spaces

To monitor more than one space, add additional entries to the bindings array inside the plugin config:

"bindings": [
  {
    "space": "spaces/ABC123example",
    "replyInThread": true,
    "threadSessionIsolation": true,
    "agents": [
      { "agentId": "chief-of-staff", "alwaysListen": true }
    ]
  },
  {
    "space": "spaces/XYZ789another",
    "replyInThread": false,
    "agents": [
      { "agentId": "engineer", "alwaysListen": true }
    ]
  }
]

One-time setup. After the initial token exchange, the plugin auto-refreshes.

https://accounts.google.com/o/oauth2/v2/auth
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=http://localhost:3000/oauth/callback
  &response_type=code
  &scope=https://www.googleapis.com/auth/chat.messages
         https://www.googleapis.com/auth/chat.spaces.readonly
         https://www.googleapis.com/auth/chat.messages.reactions
         https://www.googleapis.com/auth/pubsub
  &access_type=offline
  &prompt=consent

curl -X POST https://oauth2.googleapis.com/token \
  -d "code=AUTHORIZATION_CODE_HERE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=http://localhost:3000/oauth/callback" \
  -d "grant_type=authorization_code"

curl -X POST https://oauth2.googleapis.com/token \
  -d "code=AUTHORIZATION_CODE_HERE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=http://localhost:3000/oauth/callback" \
  -d "grant_type=authorization_code" \
  | jq '.' > ~/.openclaw/gchat-tokens.json

# Verify it contains a refresh_token:
cat ~/.openclaw/gchat-tokens.json | jq '.refresh_token'

openclaw gateway restart

# Check plugin loaded successfully:
openclaw plugins list

How the plugin creates and maintains Google Chat event subscriptions.

Auto-Create on Startup

When the plugin starts, it calls the Workspace Events API to create a subscription for each configured space. Subscriptions deliver google.workspace.chat.message.v1.created events directly to your Pub/Sub topic.

You don't need to create subscriptions manually — the plugin handles this automatically. Check the OpenClaw logs on startup to see subscription creation:

[googlechatpubsub] Creating subscription for spaces/ABC123example...
[googlechatpubsub] Subscription created: subscriptions/abc-123-def-456
[googlechatpubsub] Polling started (interval: 2000ms)

4-Hour TTL & Auto-Renewal

Workspace Events subscriptions have a maximum TTL of 4 hours. The plugin tracks expiry times and automatically calls the UpdateSubscription API before expiry to extend the TTL. This is invisible to you during normal operation.

If renewal fails (e.g., network issue), the plugin will log a warning and attempt to re-create the subscription on the next poll cycle.

[googlechatpubsub] Renewing subscription expiring in 5 minutes...
[googlechatpubsub] Subscription renewed until 2024-01-15T14:30:00Z

Manually Check Subscriptions

To list active subscriptions for your spaces:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://workspaceevents.googleapis.com/v1/subscriptions" | jq '.'

Required IAM Permissions

Recap of the IAM bindings needed for subscriptions to work end-to-end:

How incoming messages are matched and dispatched to agents.

Routing Logic

For each incoming message, the plugin evaluates all configured agents for that space. An agent receives the message if either:

• alwaysListen: true — always receives every message from the space
• mentionKeyword match — the keyword appears anywhere in the message text (case-insensitive)

Multiple agents can be dispatched for a single message. Each receives the full message and replies independently.

Routing Examples

Control how agents reply and how conversation context is scoped.

replyInThread

When replyInThread: true, the plugin always sends replies as thread replies to the original message — never to the top-level space. This keeps spaces clean and conversations organized.

When false (default), replies are sent to the space's main message window.

threadSessionIsolation

Controls how conversation context (session key) is scoped for multi-turn conversations. This determines what history an agent "remembers" within a space.

Common issues and how to resolve them.

All available config options for channels.googlechatpubsub in openclaw.json.

Channel Config

Binding Object (bindings[])

Agent Routing Object (bindings[].agents[])