Every guide for connecting Gmail to OpenClaw walks you through one method as if it's the only one. The top Google result teaches three but spends half the page selling you off Gmail entirely. So here's the map I wish existed when I started: the three routes, what each one is actually for, and the parts the tutorials gloss over.
Disclosure before anything else: I build ClawLink, which is route 3 below. Routes 1 and 2 are real options and I'll describe them straight.
Route 1: your own Google Cloud project, driven by gog
This is the path most tutorials cover, and for good reason: you own the OAuth client, the API quota is free, and the gog CLI is genuinely good. The catch is the prerequisite everyone underplays. Before the first email gets read, you'll create a Google Cloud project, enable the Gmail API, configure an OAuth consent screen, add yourself as a test user, and download a client secret. Budget 15 to 30 minutes for the Console part the first time.
Once that's done, the CLI side is four commands:
brew install openclaw/tap/gogcli
gog auth credentials ~/Downloads/client_secret_....json
gog auth add you@gmail.com --services gmail
gog gmail search 'newer_than:7d' --max 10
Two things the older guides get wrong or skip:
The install command changed. gogcli moved from steipete's personal GitHub to the openclaw org, so guides telling you to brew install steipete/tap/gogcli are pointing at the old location. The commands above are from the current README.
Headless servers are a special case. The OAuth step wants to open a browser. If OpenClaw runs on a VPS, you'll either do the flow through an SSH tunnel or use manual mode and paste an authorization code across machines. It works, but it's the step where most "45-minute setup" estimates come from.
Pick this route if you want full ownership of your credentials and infrastructure, and Google Cloud Console doesn't scare you.
Route 2: Gmail as a channel
This one does a different job than people expect, and mixing it up is how agents end up auto-replying to real contacts.
A channel setup (the community openclaw-gmail plugin, or an IMAP config with an app password) signs the agent into a mailbox. Incoming email becomes messages addressed to the agent, and it replies in-thread, on its own. That's the point: it makes your agent reachable by email. Send it a task from your phone, get the answer as a reply.
What it is not: a way to have the agent work on your personal inbox. The app password grants full mailbox access, the agent responds to whatever arrives, and there's no per-action approval. Run this on a dedicated inbox you created for the agent. Also worth knowing: the plugin flavor still needs Google Cloud OAuth credentials for its API backend, so route 2 doesn't actually let you skip the Console.
Pick this route if "email my agent and it emails back" is the feature you want.
Route 3: Gmail as hosted tools over MCP
This is the route I build, so calibrate accordingly. ClawLink exposes Gmail to OpenClaw as 15 callable tools (search, read, draft, send, labels) over MCP. The OAuth client is hosted on our side, which removes the Google Cloud project entirely: you click Connect, approve Google's standard consent screen, and the agent has Gmail about two minutes later.
The safety model is the part I care most about. The agent holds scoped OAuth tokens, not an app password. It only touches your mail when you ask it something. And the grant is revocable at myaccount.google.com/permissions like any other OAuth app, so trying it doesn't commit you to anything.
Pick this route if you want Gmail working today, on your real account, without owning OAuth infrastructure.
The ban question
Every thread about agents and Gmail eventually gets to "will Google ban my account?" The warnings trace back to a specific pattern: a brand-new Gmail account, accessed only through CLI tools, sending volume from day one. That pattern trips Google's abuse detection no matter which route you picked.
Connecting an established account through OAuth is the supported path; Google shows you a consent screen and you approve named scopes. What stays risky on any route is bulk automated sending: free Gmail caps you at 500 recipients a day, and blowing past behavioral norms on a personal account is what gets flagged, not the connection method.
Choosing in one line each
Own your OAuth client and infrastructure: route 1. Reach your agent BY email, on a dedicated inbox: route 2. Gmail working in the next two minutes with no Google Cloud Console: route 3.
The longer version of this guide, with the full tool list and setup steps for route 3, lives at claw-link.dev/openclaw/gmail. Questions about any of the three routes welcome in the comments; I've hit most of the failure modes personally.
Top comments (0)