OpenClaw can integrate with Gmail to read emails, send replies, and manage your inbox. This integration uses Google Cloud Pub/Sub to push real-time notifications to your Gateway, ensuring your agent reacts immediately to new messages.

• Google Cloud Account: You need to create a project in the Google Cloud Console.
• gcloud CLI: Installed and logged in (Install Guide).
• gog (gogcli): Helper tool for Gmail OAuth and setup (gogcli.sh).
• Tailscale (Recommended): Used to expose a secure public endpoint for Pub/Sub webhooks.

The easiest way to set up Gmail is using the OpenClaw CLI wizard, which automates the OAuth and Pub/Sub wiring.

1. Run the Setup Command Use the webhooks gmail setup command. Replace you@gmail.com with your email address.

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

   This command will:

   • Guide you through Google Cloud authentication.
   • Create a Pub/Sub topic and subscription.
   • Configure a watch on your Gmail inbox.
   • Generate the necessary OpenClaw configuration.

2. Start the Watcher Once setup is complete, you can start the runtime watcher (or restart your Gateway).

   openclaw webhooks gmail run

   Note: The Gateway automatically starts this service if configured.

If you prefer to configure it manually or need to customize the behavior, add the following to your ~/.openclaw/openclaw.json.

{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      // Pub/Sub details (generated by setup wizard)
      topic: "projects/my-project/topics/gmail-watch",
      subscription: "gmail-watch-sub",
      pushToken: "secret-token",

      // Where Google pushes events (Tailscale Funnel URL)
      hookUrl: "https://my-tailnet.ts.net/hooks/gmail",

      // Local server to receive the push
      serve: { bind: "127.0.0.1", port: 8788, path: "/" }
    }
  }
}

To control how the agent processes emails, configure the hooks.mappings section.

{
  hooks: {
    enabled: true,
    presets: ["gmail"], // Enable the default gmail handler
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now", // Wake up immediately
        name: "Gmail",
        // Unique session key prevents mixing emails with other chats
        sessionKey: "hook:gmail:{{messages[0].id}}",

        // Context template for the model
        messageTemplate: "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",

        // Use a cheaper/faster model for email triage?
        model: "openai/gpt-4o-mini",

        // Delivery: Send the agent's reply back to the user via WhatsApp/Telegram
        deliver: true,
        channel: "last" // Or specify specific channel like "telegram"
      }
    ]
  }
}

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

• Watch Expiration: Gmail watches expire after 7 days. OpenClaw automatically renews them if the Gateway is running.
• Tailscale Funnel: Ensure your Tailscale Funnel is active and publicly accessible if you rely on it for the webhook URL.
• Permissions: If you see 403 errors, check your Google Cloud IAM permissions for the Pub/Sub service account.