How to Connect an AI Agent to Gmail (Step-by-Step Guide)

Your AI agent is only as useful as the systems it can access. And for most businesses, the first system that matters is email.

This guide walks you through connecting an OpenClaw agent to Gmail. Not the theory. The actual steps, the gotchas, and the things nobody warns you about until you're three hours into an OAuth debugging session.

What You'll Get When This Is Done

Your agent will be able to:

• Read incoming emails and categorize them (urgent, routine, noise)
• Draft replies based on context and your communication style
• Send follow-ups on threads that have gone quiet
• Flag emails that need your human attention
• Archive newsletters and notifications without you seeing them

One client measured this: 93% of their incoming email was handled without human input after setup. 156 emails in a week. 11 needed a human. The rest? Predictable work that didn't require a brain.

Before You Start

You'll need three things:

1. A Google Workspace or personal Gmail account
2. An OpenClaw instance running on your server (local or cloud)
3. About 45 minutes of uninterrupted time (the first time takes longest)

If you don't have OpenClaw installed yet, start with our What is OpenClaw? guide first.

Step 1: Create a Google Cloud Project

Head to console.cloud.google.com and create a new project. Name it something you'll recognize later. "AI Agent Email" works fine.

This project is just a container for your API credentials. It doesn't cost anything. Google gives you a generous free tier for Gmail API usage, and a single agent won't come close to hitting it.

The mistake everyone makes here: Using an existing project that has other APIs enabled. Keep your agent's credentials isolated. If something goes wrong, you want to revoke access without breaking your other tools.

Step 2: Enable the Gmail API

In your new project, go to APIs & Services > Library. Search for "Gmail API" and enable it.

While you're there, also enable the Google Calendar API if you want your agent to handle scheduling later. Saves you a trip back.

Step 3: Configure the OAuth Consent Screen

This is where most people get stuck.

Go to APIs & Services > OAuth consent screen. Choose "Internal" if you're on Google Workspace (recommended). Choose "External" if you're on a personal Gmail account.

For External apps, Google requires you to submit for verification if you want to move past the "testing" phase. For a personal AI agent, testing mode is fine. You'll just need to manually add your email as a test user.

Fill in:

• App name: Whatever you want. Your agent's name works.
• User support email: Your email
• Scopes: Add gmail.readonly, gmail.send, gmail.modify, and gmail.labels
• Test users: Add the Gmail address your agent will access

The scope trap: Only request the scopes you actually need. gmail.readonly lets the agent read but not send. gmail.send lets it send but not read drafts. gmail.modify gives it the ability to mark as read, archive, and label. Most agents need all four, but start with readonly if you're nervous.

Step 4: Create OAuth Credentials

Go to APIs & Services > Credentials. Click "Create Credentials" > "OAuth client ID."

Type: Desktop application (not Web application, even though your agent runs on a server).

Download the JSON file. This is your client secret. Treat it like a password. Don't commit it to git. Don't leave it in a plaintext file in your home directory. OpenClaw has a credential encryption system. Use it.

Step 5: Configure OpenClaw's Google Workspace Skill

In your OpenClaw config, you'll need to point the Google Workspace skill at your credentials:

skills:
  google-workspace:
    credentials_path: /path/to/your/client_secret.json
    token_path: /path/to/token.json
    scopes:
      - gmail.readonly
      - gmail.send
      - gmail.modify
      - gmail.labels

The first time OpenClaw tries to access Gmail, it'll open a browser window (or give you a URL) for the OAuth flow. Log in, grant permissions, and it'll save a refresh token.

If you're running headless (no browser on the server): Use the --no-browser flag and copy the authorization URL to your local machine. Complete the flow there and paste the authorization code back.

Step 6: Test the Connection

Run a simple test to make sure your agent can read email:

openclaw test google-workspace gmail-read

If it works, you'll see your latest emails listed. If it doesn't, 90% of the time it's one of three things:

1. Token expired: Delete token.json and re-authenticate
2. Wrong scopes: You added scopes after the initial auth. Delete the token and re-auth with the new scopes.
3. Test user not added: If you're on External OAuth, you need to explicitly add your email as a test user in the consent screen.

Step 7: Configure Email Triage Rules

This is where the agent becomes useful. OpenClaw's email triage works on a priority system:

email:
  triage:
    urgent:
      - from_domain: ["your-biggest-client.com", "investor.com"]
      - subject_contains: ["urgent", "ASAP", "invoice overdue"]
    routine:
      - categories: ["scheduling", "follow-up", "acknowledgment"]
      - auto_draft: true
    noise:
      - from_domain: ["newsletter.substack.com", "notifications@github.com"]
      - action: archive_and_label
    escalate:
      - sentiment: negative
      - contains: ["legal", "complaint", "refund"]

Start conservative. Let the agent categorize and draft for a week before you let it send anything automatically. Trust is earned, even from software.

Common Mistakes (and How to Avoid Them)

Giving send permissions too early. Start with read-only. Let the agent draft replies in Slack for you to review. Once you trust its judgment, enable sending.

Not setting up filters. Without triage rules, your agent will try to respond to every email including spam, newsletters, and automated notifications. Be specific about what it should handle.

Forgetting token refresh. OAuth tokens expire. OpenClaw handles refresh automatically, but if your server reboots and the token file permissions change, you'll wake up to a broken agent. Set proper file permissions and test after every reboot.

Running without Docker. Your email contains sensitive business data. Run OpenClaw in a Docker container with restricted network access. The agent should only be able to reach Gmail's API endpoints, your Slack webhook, and nothing else.

What Happens Next

Once your agent is reading email reliably, you'll notice something in about a week: you stop checking your inbox compulsively. The agent sends you a morning brief in Slack with what matters. Everything else is handled.

That feeling is worth the 45-minute setup.

If the setup feels like too much work, or if you want someone to handle the OAuth dance, the Docker sandboxing, the security hardening, and the triage configuration for you, that's what we do. Book a call and we'll have your agent reading email by end of day. $999 one-time. No subscription. No recurring fees.