Connect Openclaw to Gmail: Step-by-Step Tutorial (2026)

The most common way to give your Openclaw agent an email address is by connecting it to Gmail. This works, but setup is tricky and there are limitations that make it hard to scale.

This guide explains three ways to connect Openclaw to Gmail, starting with the easiest and moving to more advanced options. It also helps you decide when Gmail is a good fit and when to use dedicated agent email infrastructure instead.

Why Connecting Gmail to Openclaw is Hard

Here is why the Gmail integration with OpenClaw is difficult:

1. Ban risk. Gmail's automated abuse detection can flag agent behavior as suspicious. If Google thinks you are a bot, your account gets banned. You lose access to email, calendar, and all Google services tied to that account.
2. Manual inbox creation. Each Gmail account requires manual setup through Google's UI. You cannot spin up 10 test inboxes via the API.
3. OAuth complexity. Google requires multi-step OAuth flows with refresh tokens, consent screens, and API scope management. OAuth tokens can expire at any moment, prompting reauthentication that interrupts workflows and requires manual intervention.
4. Rate limits. Gmail API has strict quotas. Agents that check email frequently or process large volumes hit these limits fast.
5. Send limits. Free Gmail accounts are capped at 500 emails per day. Google Workspace accounts get 2,000 per day. Exceed this, and Gmail blocks sending for 24 hours.

These limitations make Gmail a tough choice for production agent systems. However, it can still work for personal use or testing.

Method 1: gogcli Skill

The simplest way to connect Openclaw to Gmail is through the gogcli skill available on ClawHub. gogcli is a command-line tool that provides unified access to Google Workspace services including Gmail, Calendar, Drive, Contacts, Tasks, Sheets, and Docs.

What is gogcli?

gogcli (command: gog) is an open-source CLI tool that brings Google Workspace to your terminal. It uses OAuth authentication, stores credentials securely in your OS keyring, and provides JSON output for easy scripting and automation.

When to Use This Method

Use gogcli if you:

• Want the fastest setup.
• Have an existing Gmail account with established usage history.
• Need Gmail, Calendar, and Drive integration in one tool
• Are comfortable with command-line tools and OAuth setup
• Want script-friendly JSON output for automation

Important Warning About New Gmail Accounts

Account Ban Risk: While gogcli works well with existing Gmail accounts, there is significant risk if you create a new Gmail account specifically for your agent and immediately start using it via CLI tools.

Gmail's automated abuse detection flags new accounts that show unusual patterns like:

• Account created and immediately accessed via third-party tools
• High email volume from a brand-new account
• CLI-only access without browser activity
• Automated behavior patterns

Recommendation: Only use gogcli with an established Gmail account that has normal usage history. For dedicated agent inboxes, use AgentMail to avoid ban risks entirely.

Step 1: Install gogcli

First, install the gogcli tool itself via Homebrew:

brew install steipete/tap/gogcli

Alternative installation methods:

Build from source:

git clone https://github.com/steipete/gogcli.git
cd gogcli
make
./bin/gog --help

Verify installation:

gog --version

Step 2: Set Up OAuth Credentials

gogcli requires OAuth 2.0 credentials from Google Cloud Console.

Create OAuth credentials:

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Navigate to APIs & Services → Credentials
4. Click Create Credentials → OAuth client ID
5. Select Desktop app as the application type
6. Download the JSON credentials file (e.g., client_secret_....json)

Register credentials with gogcli:

gog auth credentials ~/Downloads/client_secret_....json

This stores your OAuth client credentials securely.

Step 3: Authorize Your Gmail Account

Add and authorize your existing Gmail account:

gog auth add your-email@gmail.com

This will:

1. Open your browser to Google's OAuth consent screen
2. Prompt you to sign in with your Gmail account
3. Ask for permissions to access Gmail, Calendar, Drive, and other services
4. Store authentication tokens securely in your OS keyring (macOS Keychain, Linux Secret Service, or Windows Credential Manager)

For headless/remote servers:

If you are setting this up on a server without a browser, use manual mode:

gog auth add your-email@gmail.com --manual

This will provide a URL to visit on another device and a code to enter.

Verify authentication:

gog auth list

You should see your email address listed as an authorized account.

Set default account (optional):

export GOG_ACCOUNT=your-email@gmail.com

Or add to your ~/.bashrc or ~/.zshrc to make it permanent.

Important: Use an existing Gmail account with established usage history. Do not create a brand-new Gmail account and immediately authenticate it via CLI tools, as this significantly increases ban risk.

Step 4: Test Gmail Access

Test that gogcli can access your Gmail:

gog gmail search 'is:unread newer_than:7d' --max 5

You should see a list of your recent unread emails. If this works, gogcli is successfully connected.

Other test commands:

# List recent emails
gog gmail search '' --max 10

# Search for specific emails
gog gmail search 'from:example@gmail.com' --max 5

# Check all available Gmail commands
gog gmail --help

Step 5: Install gogcli Skill in Openclaw

Now install the Openclaw skill that wraps gogcli:

clawd skill add luccast/gogcli

Or via ClawHub CLI:

clawdhub install luccast/gogcli

Verify the skill is installed:

openclaw skills list --eligible

You should see luccast/gogcli in the list.

The skill bridges Openclaw to the gogcli tool you installed earlier, allowing your agent to execute Gmail commands through natural language.

Step 6: Test Openclaw Integration

Start Openclaw and test email functionality:

You: How many unread emails do I have?
Agent: Let me check your Gmail... You have 12 unread emails.

You: Show me the subject lines from today.
Agent: Here are today's emails:
- "Meeting agenda for tomorrow"
- "Invoice #2026-042"
- "Weekly team update"

You: Send an email to test@example.com with subject "Test" and body "Testing gogcli integration"
Agent: I've sent the email from your-email@gmail.com successfully.

Your agent can now:

• List and read emails from your Gmail inbox
• Search by sender, subject, date, or keywords using Gmail search syntax
• Send emails through your Gmail account
• Access Google Calendar events
• Browse and manage Google Drive files
• Work with Google Sheets, Docs, and Slides
• Manage contacts and tasks
• All with JSON output for structured data parsing

Limitations and Considerations

Account Ban Risk:

• High risk for new accounts: Creating a new Gmail account and immediately using it via CLI can trigger Google's abuse detection
• Best for existing accounts only: Only use with Gmail accounts that have established usage history
• No guarantee of safety: Even existing accounts can be flagged if usage patterns change dramatically

Technical Limitations:

• No webhook support for real-time notifications (uses polling or manual checks)
• Still subject to Gmail's rate limits and sending quotas
• OAuth tokens can expire, requiring reauthentication
• Requires OAuth setup with Google Cloud Console (more complex than simple API key)

Feature Coverage:

• While gogcli provides broad Google Workspace access (Gmail, Calendar, Drive, etc.), it's not as comprehensive as full Gmail API integration for advanced features

If you need:

• Dedicated agent inboxes without ban risk → Use AgentMail
• Real-time webhook notifications → Use Method 3 (Gmail Pub/Sub) or AgentMail
• Production-grade reliability and scaling → Use AgentMail
• Simple API key authentication → Use AgentMail

Method 2: OAuth Integration with Google Cloud (Full API Access)

This method gives your Openclaw agent full access to the Gmail API, including labels, filters, thread management, and real-time notifications via Pub/Sub.

When to Use This Method

Use OAuth if you:

• Need advanced Gmail features (labels, filters, thread management).
• Want proper authentication without App Passwords.
• We are building production agents that interact heavily with Gmail.
• Need real-time email notifications via webhooks.

Prerequisites

• A Google Account.
• Access to Google Cloud Console.
• Basic familiarity with OAuth flows.

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console.
2. Click Select a project → New Project.
3. Enter project name: "Openclaw Gmail Integration".
4. Click Create.

Step 2: Enable Gmail API

1. In your project, go to APIs & Services → Library.
2. Search for "Gmail API".
3. Click Enable.

Optionally, enable the Google Calendar API to access calendars.

Step 3: Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen.
2. Select External user type (unless you have a Google Workspace).
3. Fill in required fields:
4. • App name: Openclaw Agent.
   • User support email: your-email@gmail.com.
   • Developer contact: your-email@gmail.com.
5. Click Save and Continue.

Step 4: Add OAuth Scopes

On the Scopes screen, click Add or Remove Scopes and add:

• https://www.googleapis.com/auth/gmail.modify (Read, send, delete emails).
• https://www.googleapis.com/auth/gmail.send (Send emails only, if you prefer a narrower scope).
• https://www.googleapis.com/auth/calendar.events (Optional, for calendar access).

Click Save and Continue.

Step 5: Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Name: "Openclaw Desktop Client"
5. Click Create

Download the credentials file:

1. Click the download icon next to your newly created OAuth client.
2. Save the file as google-credentials.json

Step 6: Save Credentials for Openclaw

Move the credentials file to your Openclaw directory:

mkdir -p ~/.openclaw/credentials
mv ~/Downloads/google-credentials.json ~/.openclaw/credentials/

Step 7: Configure Openclaw Adapter

Create the Google adapter configuration file:

mkdir -p ~/.openclaw/adapters/google

Create ~/.openclaw/adapters/google/config.json:

{
  "credentials_path": "~/.openclaw/credentials/google-credentials.json",
  "scopes": [
    "https://www.googleapis.com/auth/gmail.modify",
    "https://www.googleapis.com/auth/calendar.events"
  ],
  "redirect_uri": "http://localhost:8080"
}

Step 8: Authorize Openclaw

Start Openclaw and run the authorization command:

openclaw

In the Openclaw chat interface:

You: /connect google

This will:

1. Open a browser window.
2. Prompt you to sign in to Google.
3. Ask for permission to access Gmail and Calendar.
4. Redirect to localhost with an authorization code.
5. Store the OAuth tokens securely.

Step 9: Verify Connection

Test the connection:

You: /google test-connection

Agent: ✅ Successfully connected to Google.
Gmail: Authorized
Calendar: Authorized

Step 10: Use Gmail API Features

Your agent now has full API access:

You: Label all emails from john@example.com as "Work"
Agent: I've applied the "Work" label to 23 emails from john@example.com.

You: Create a filter for newsletter@ emails to skip inbox
Agent: Filter created. Emails from senders containing "newsletter@" will skip the inbox.

You: Summarize my unread emails from this week
Agent: You have 15 unread emails this week:
- 8 work-related (mostly project updates)
- 4 newsletters
- 3 personal

Advantages of This Method

• Full Gmail API access (labels, filters, threads)
• OAuth provides secure, industry-standard authentication
• No App Passwords needed
• Secure, industry-standard authentication
• Access to Google Calendar, Drive, and Docs (if you enable those APIs)

Disadvantages of This Method

• Complex setup (multiple steps in Google Cloud Console)
• Requires OAuth consent screen configuration
• Still subject to Gmail API rate limits (250 units/sec per user)
• Risk of account ban if agent behavior triggers Google's automated abuse detection

Method 3: Gmail Pub/Sub Integration (Advanced Real-Time Setup)

This is the most advanced method. It uses Google Cloud Pub/Sub to send real-time webhook notifications when emails arrive, so your agent can respond right away without polling.

When to Use This Method

Use Pub/Sub if you:

• Need real-time email notifications (webhooks instead of polling).
• We are building production systems that must respond to emails within seconds.
• Have experience with Google Cloud infrastructure.
• Are comfortable with CLI tools and webhook servers.

Prerequisites

• Completed Method 2 (OAuth setup).
• Google Cloud project with billing enabled.
• Pub/Sub API enabled.
• gogcli tool installed.
• Public webhook endpoint (via Tailscale Funnel, ngrok, or similar).

Step 1: Enable Pub/Sub API

1. Go to Google Cloud Console.
2. Navigate to APIs & Services → Library.
3. Search for "Cloud Pub/Sub API".
4. Click Enable.

Step 2: Install gogcli

Option 1: npm

npm install -g gogcli

Option 2: Homebrew

brew install gogcli

Step 3: Authorize gogcli

gogcli auth login --scopes gmail.readonly,gmail.send,gmail.compose

This opens your browser for OAuth consent. Sign in and grant permissions.

Step 4: Set Up Public Webhook Endpoint

Your Openclaw agent needs a publicly accessible webhook URL to receive notifications from Google.

Option A: Tailscale Funnel (Recommended)

Install Tailscale, then expose a local port:

tailscale funnel 8080

Your public URL will be something like: https://your-machine.tailscale-network.ts.net

Option B: ngrok

ngrok http 8080

Copy the forwarding URL: https://abc123.ngrok.io

Step 5: Configure Gmail Pub/Sub in Openclaw

Run the setup wizard:

openclaw webhooks gmail setup --account your-email@gmail.com

This will:

1. Create a Pub/Sub topic in your Google Cloud project.
2. Subscribe to Gmail to push notifications to that topic.
3. Configure Openclaw to listen for those notifications.
4. Set up the webhook endpoint.

Step 6: Test Real-Time Notifications

Send a test email to your Gmail account. Your Openclaw agent should receive a webhook notification within 1-2 seconds.

[Webhook received]
Agent: New email from sender@example.com
Subject: "Test email"
Would you like me to summarize it?

Advantages of This Method

• Real-time email notifications (no polling).
• Sub-second response times.
• Scalable for high-volume automation.
• Full Gmail API access.

Disadvantages of This Method

• Most complex setup.
• Requires a public webhook endpoint.
• Google Cloud billing required (Pub/Sub has costs, though minimal for most use cases).
• More infrastructure to maintain.

Security Best Practices

Connecting your Gmail to an AI agent has some security risks. Follow these tips to keep your data safe.

1. Use OAuth, Not Passwords

Never hardcode your Gmail password in Openclaw configuration files. Use OAuth (Method 2 or 3) or App Passwords (Method 1).

2. Limit OAuth Scopes

Only grant the minimum permissions your agent needs.

If your agent only sends emails:

{
  "scopes": [
    "https://www.googleapis.com/auth/gmail.send"
  ]
}

If your agent reads and sends:

{
  "scopes": [
    "https://www.googleapis.com/auth/gmail.modify"
  ]
}

Avoid using gmail.full unless you really need them.

3. Store Credentials Securely

Don't put OAuth tokens or App Passwords in version control.

# Add to .gitignore
.openclaw/credentials/
.env

Use environment variables for API keys:

export GMAIL_APP_PASSWORD="your-app-password"

4. Monitor Agent Activity

Set up alerts for unusual behavior:

• Sending more than 100 emails per hour
• Accessing emails from new IP addresses
• Failed authentication attempts

Gmail's Security Checkup tool can help you monitor connected apps.

5. Use a Dedicated Gmail Account

Don't connect your personal Gmail account to an agent. Set up a separate Gmail account just for your agent.

Why:

• If the agent gets compromised, your personal email stays safe.
• If Gmail bans the account for automation, you do not lose access to personal services.
• Easier to debug and monitor agent-specific email activity.

6. Revoke Access When Not in Use

If you are not using the agent, revoke its access:

1. Go to Google Account Permissions.
2. Find "Openclaw Agent" or the app name you configured.
3. Click Remove Access.

You can always give access again later if needed.

Common Issues and Troubleshooting

Issue 1: "Gmail banned my account"

Cause: Gmail detected automation patterns and flagged your account.

Solution:

Unfortunately, there is no guaranteed fix. You can:

• Appeal the ban (success rate is low).
• Use a different Gmail account (but the same behavior may still get you banned).
  • Switch to AgentMail, designed for agents, which does not ban automation.

Issue 2: "Invalid credentials" Error

Cause: App Password is incorrect, or OAuth tokens are stale.

Solution:

• For App Passwords: Regenerate a new one and update your configuration.
• For OAuth: Delete ~/.openclaw/credentials/google-oauth-tokens.json and re-run /connect google

Issue 3: "API quota exceeded"

Cause: You hit Gmail's 250 units/second rate limit.

Solution:

Reduce polling frequency in your Openclaw configuration:

email:
  check_interval: 60  # Check every 60 seconds instead of every 5

Or switch to Pub/Sub for real-time notifications without polling.

Issue 4: "Emails are not showing up in Openclaw"

Cause: IMAP sync issue or incorrect folder configuration.

Solution:

Verify IMAP connection:

himalaya list --account your-email@gmail.com

Check that you are looking in the correct folder (INBOX vs All Mail).

When to Use Gmail vs AgentMail

Gmail is fine for personal agents and small tests. For production systems, though, dedicated agent email tools are usually a better choice.

Use Gmail If:

• You already pay for Google Workspace for your business.
• You only need one or two agent inboxes.
• You want integration with Google Calendar, Drive, and Docs.
• You are comfortable with OAuth complexity and setup time.
• Your agent sends fewer than 500 emails per day.

Use AgentMail If:

• You dont want your inboxes getting banned.
• You need to create inboxes programmatically.
• You want real-time webhooks without a complex Pub/Sub setup.
• You are building multi-tenant systems (one inbox per customer)
• Your agent sends thousands of emails per day.
• You want to avoid the risk of account bans.
• You need a semantic search across agent emails.
• You value simple API key authentication over OAuth flows.

Setting Up AgentMail as an Alternative

If Gmail's limitations don't work for you, AgentMail is a simpler option. It's made for AI agents and removes OAuth complexity, rate limits, and the risk of account bans.

Why AgentMail for Openclaw?

Advantages over Gmail:

• Setup time: 3-5 minutes vs 30-60 minutes for Gmail OAuth.
• Authentication: Simple API key vs complex OAuth flows.
• Inbox creation: One API call vs manual account setup.
• Rate limits: Built for high-volume automation vs Gmail's 2,000 emails/day cap.
• Risk: No automation restrictions vs account ban possibility

Quick Start Overview

Here is what the AgentMail setup process looks like:

1. Sign up at agentmail.to and get your API key.
2. Install SDK: npm install agentmail
3. Create an inbox with a single API call.
4. Install AgentMail skill in Openclaw.
5. Set up webhooks for real-time notifications.
6. Start sending and receiving emails immediately.

Example: Creating an inbox

import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({
  environment: "https://api.agentmail.to",
  apiKey: process.env.AGENTMAIL_API_KEY
});

const inbox = await client.inboxes.create({
  username: "my-openclaw-agent",
  displayName: "My Openclaw Agent"
});

console.log(`Inbox created: ${inbox.inboxId}`);
// Output: my-openclaw-agent@agentmail.to

Your inbox is ready to send and receive right away. There's no OAuth and no manual setup needed.

Complete Setup Guide

For the full step-by-step tutorial on setting up AgentMail with Openclaw, including:

• Installing the AgentMail skill
• Configuring webhooks for real-time email notifications
• Handling verification emails and OTP codes
• Managing multiple agent inboxes
• Setting up custom domains
• Implementing email threading
• Production best practices

Read the comprehensive guide: How to Give Your Openclaw Agent Its Own Email Inbox.

The guide covers everything from basic setup to advanced topics like coordinating multiple agents, searching across email history, and managing inboxes automatically.

Hybrid Approach: Gmail + AgentMail

You do not have to choose only one. Many users run a hybrid setup:

• Personal agent → Gmail (familiar, integrated with Calendar/Drive)
• Production agents (customer support, testing, automation) → AgentMail (scalable, cost-effective)

Example Architecture

Personal Openclaw Agent
├── Gmail (you@gmail.com)
├── Google Calendar
└── Google Drive

Production Openclaw Agents
├── support@agentmail.to (Customer Support)
├── billing@agentmail.to (Billing Inquiries)
├── qa-test-1@agentmail.to (QA Testing)
└── qa-test-2@agentmail.to (QA Testing)

This way, you get the best of both options.

Conclusion

You can connect Openclaw to Gmail, but it's not easy. OAuth is complex, rate limits are strict, and account bans are a real risk. Gmail was designed for people, not agents.

For personal use or small tests, Gmail works fine. Use the Himalaya CLI for a quick setup, or OAuth if you need full API access.

For production systems, look at dedicated agent email tools. AgentMail lets you create inboxes with code, get real-time webhooks, and pay based on usage, all without worrying about account bans.

Choose the path that fits your needs:

• One personal agent → Gmail (Method 1 or 2)
• Production agents at scale → AgentMail
• Best of both → Hybrid approach

Your Openclaw agent needs email, so be sure to set up the right system so it can work properly.