Connect Gmail to OpenClaw: Automated Setup Guide

Ever felt like your inbox is a black hole where important data goes to die? You want to automate your email workflow, but polling an API every few minutes feels clunky and slow. If you want your Gmail to talk to your AI agents the moment a message hits your inbox, setting up a real-time push system is the way to go.

This guide helps you wire Gmail to OpenClaw using Google Cloud Pub/Sub. By the end, you’ll have a system that triggers your AI agents instantly whenever a new email arrives.

Prerequisites

You need a few tools ready before you start. Make sure you have gcloud installed and logged in, and gog (gogcli) authorized for your Gmail account. You also need OpenClaw hooks enabled and Tailscale running for the public HTTPS endpoint. While other tunnel services might work, Tailscale is the setup we currently support.

Here is an example hook config to enable the Gmail preset mapping:

{
  hooks: {
    enabled: true,
    token: "OPENCLAW_HOOK_TOKEN",
    path: "/hooks",
    presets: ["gmail"],
  },
}

To deliver the Gmail summary to a chat surface, you can override the preset with a mapping that sets deliver and your preferred channel:

{
  hooks: {
    enabled: true,
    token: "OPENCLAW_HOOK_TOKEN",
    presets: ["gmail"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
        model: "openai/gpt-5.2-mini",
        deliver: true,
        channel: "last",
        // to: "+15551234567"
      },
    ],
  },
}

If you want a fixed channel, set channel and to. Otherwise, channel: "last" uses the last delivery route. You can also set a default model and thinking level specifically for Gmail hooks in your config:

{
  hooks: {
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

A few things to keep in mind: per-hook settings in the mapping override these defaults. Also, Gmail hook content is wrapped with safety boundaries by default. If you want to disable this, set hooks.gmail.allowUnsafeExternalContent: true.

Wizard (recommended)

The easiest way to get this running is to use the OpenClaw helper. It handles the heavy lifting and even installs dependencies on macOS via Homebrew.

openclaw webhooks gmail setup \
  --account openclaw@gmail.com

This setup uses Tailscale Funnel for the public push endpoint and enables the Gmail hook preset automatically. If you are on Linux, you should install gcloud, gogcli, and tailscale manually before running this.

When hooks.enabled=true and your Gmail account is set, the Gateway starts the watcher on boot. If you prefer to run the daemon yourself, you can opt out by setting OPENCLAW_SKIP_GMAIL_WATCHER=1.

To run the manual daemon that starts the serve process and auto-renews the watch:

openclaw webhooks gmail run

One-time setup

You need to configure your Google Cloud Project. Make sure you select the project that owns the OAuth client used by gog.

gcloud auth login
gcloud config set project <project-id>

Next, enable the necessary APIs:

gcloud services enable gmail.googleapis.com pubsub.googleapis.com

Create a Pub/Sub topic for the watch:

gcloud pubsub topics create gog-gmail-watch

Finally, allow the Gmail push service to publish to your topic:

gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
  --role=roles/pubsub.publisher

Start the watch

Now you can tell Gmail to start watching your inbox and sending notifications to your topic.

gog gmail watch start \
  --account openclaw@gmail.com \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

Be sure to save the history_id from the output if you need to debug things later.

Run the push handler

The push handler receives the notification from Google and sends it to OpenClaw. Here is how you run it locally:

gog gmail watch serve \
  --account openclaw@gmail.com \
  --bind 127.0.0.1 \
  --port 8788 \
  --path /gmail-pubsub \
  --token <shared> \
  --hook-url http://127.0.0.1:18789/hooks/gmail \
  --hook-token OPENCLAW_HOOK_TOKEN \
  --include-body \
  --max-bytes 20000

The --token flag protects your push endpoint, while --hook-url points to your OpenClaw instance. Using openclaw webhooks gmail run is usually better as it wraps this flow and handles watch renewals for you.

Expose the handler (advanced, unsupported)

If you aren’t using Tailscale, you have to wire the tunnel manually. This is an advanced path without official support. You can use cloudflared to expose your local port:

cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate

Then, use that public URL to create the Pub/Sub subscription:

gcloud pubsub subscriptions create gog-gmail-watch-push \
  --topic gog-gmail-watch \
  --push-endpoint "https://<public-url>/gmail-pubsub?token=<shared>"

For production environments, use a stable HTTPS endpoint and OIDC verification:

gog gmail watch serve --verify-oidc --oidc-email <svc@...>

Test

You should verify that everything is connected. Send a test message to your watched inbox:

gog gmail send \
  --account openclaw@gmail.com \
  --to openclaw@gmail.com \
  --subject "watch test" \
  --body "ping"

You can check the status of the watch and your history with these commands:

gog gmail watch status --account openclaw@gmail.com
gog gmail history --account openclaw@gmail.com --since <historyId>

Troubleshooting

If you run into issues, check these common problems:

• Invalid topicName: This usually means your topic isn’t in the same project as your OAuth client.
• User not authorized: You likely missed the IAM policy binding step for the service account.
• Empty messages: Remember that Gmail push only sends a historyId. The system then uses that ID to fetch the actual content.

Cleanup

If you need to tear everything down, run these commands to stop the watch and remove the Pub/Sub resources:

gog gmail watch stop --account openclaw@gmail.com
gcloud pubsub subscriptions delete gog-gmail-watch-push
gcloud pubsub topics delete gog-gmail-watch

Next Steps

• Webhooks Documentation
• AI Setup Assistant