# How to connect Gmail to OpenClaw (no API keys)

> Connect Gmail to OpenClaw with ClawLink in one click — 60 tools your AI agent can call from chat via hosted OAuth. No API keys, no manual setup.

Web version: https://claw-link.dev/openclaw/gmail

The usual route to Gmail access for OpenClaw is an MCP server you configure and keep running, plus your own OAuth app or API keys. ClawLink gives OpenClaw a more practical Gmail setup: install one ClawHub skill, connect Gmail in the browser, and OpenClaw can call real Gmail actions from any chat surface with no auth, token refresh, or tool wiring to build yourself.

**Start here:** install the ClawLink plugin (`openclaw plugins install clawhub:clawlink-plugin`), pair it in the browser, then connect the app in the ClawLink dashboard. The interactive install prompt is on the web version of this page: https://claw-link.dev/openclaw/gmail

## Setup

It takes three steps to connect OpenClaw to Gmail.

1. **Install ClawLink** — add the plugin to OpenClaw once.
2. **Connect Gmail** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask OpenClaw in plain English.

**Alternative for any agent (no plugin needed):** if the OpenClaw plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect gmail  # connect Gmail (browser OAuth)
npx -y @useclawlink/cli actions gmail  # list available actions
npx -y @useclawlink/cli run gmail <action> --input '<json>'  # execute (add --confirm for writes)
```

The install, start to finish. Run these once, then connect Gmail in the dashboard:

```bash
openclaw plugins install clawhub:clawlink-plugin
openclaw skills install @hith3sh/gmail-email
```

Start a fresh chat afterwards so OpenClaw reloads its tool catalog, then ask it to run `clawlink_list_integrations` to confirm Gmail is connected.

### Using a different agent?

The OpenClaw plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once Gmail is connected in the dashboard, that agent calls the same 60 Gmail tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## Watch the setup

A three-minute screen recording of the whole flow: install the skill, connect Gmail in the browser, and call the first tool from chat.

[How to Connect Gmail to OpenClaw Under 3 Minutes](https://www.youtube.com/watch?v=J6Yj9NtVD_I)

## Gmail MCP for OpenClaw

Looking for a Gmail MCP server for OpenClaw? ClawLink connects Gmail to OpenClaw and exposes 60 Gmail tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using Hermes instead? The [Hermes Gmail integration](https://claw-link.dev/hermes/gmail) works the same way.

## Four ways to connect Gmail to OpenClaw

Guides for connecting Gmail to OpenClaw describe several different methods, and most share one prerequisite they spend half the tutorial on: creating your own Google Cloud project. Here's the honest map.

### Do-it-yourself Google Cloud (gog or the Workspace CLI)

The path most tutorials cover. You create a Google Cloud project, enable the Gmail API, configure an OAuth consent screen, add yourself as a test user, download the client secret, then authorize the gog CLI or Google's Workspace CLI against it.

- Full control and free API quota; you own the OAuth client.
- Budget 15-30 minutes of Google Cloud Console work before the first email is read.
- On a headless server the browser OAuth step needs an SSH tunnel or manual code paste.
- gogcli now lives in the openclaw GitHub org; guides that install from steipete/tap point at the old location.

Once the Console part is done, the CLI side is four commands:

```bash
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
```

### Gmail as a channel (community plugin)

The openclaw-gmail channel plugin signs into a mailbox and treats incoming email as messages addressed to the agent, which replies in-thread. A different job: it makes the agent reachable by email.

- Best on a dedicated agent inbox, not your personal account, because the agent responds to incoming mail.
- Still needs Google Cloud OAuth credentials (or gog's) for its API backend.

### Gmail as a trigger (Gmail API push over Pub/Sub)

Instead of the agent checking your mail when you ask, Gmail pushes a notification the moment something arrives. This is what people mean by making OpenClaw react to new email, and it is a different mechanism from the other three.

- Needs your own Google Cloud project plus a Cloud Pub/Sub topic, and you have to grant publish rights on that topic to gmail-api-push@system.gserviceaccount.com.
- The subscription expires. Google's Gmail API push guide says you must call watch at least once every 7 days or notifications stop, and recommends calling it once a day. A push setup that worked last week and then went quiet almost always died here.
- ClawLink does not do this. Its Gmail tools are request-driven: the agent reads, drafts, and sends when you ask. If you want incoming mail to wake the agent up on its own, use this route or the channel plugin above.

### Gmail as hosted tools (ClawLink)

ClawLink exposes Gmail to OpenClaw as 60 callable tools over MCP: search, read, draft, send, labels. The OAuth client is hosted, so there is no Google Cloud project on your side.

- Browser-only setup: click Connect, approve on Google's consent screen, done in about two minutes.
- You approve on Google's own consent screen, the grant is listed at myaccount.google.com/permissions, and revoking it there takes one click. No app password or client secret ends up in a config file on your machine.
- Nothing runs on its own; the agent touches mail only when you ask.

Pick by what you're optimizing for: full ownership of the OAuth client and infrastructure, use gog or the Workspace CLI; an agent you can reach BY email, use the channel plugin on a dedicated inbox; incoming mail that wakes the agent on its own, use Gmail push over Pub/Sub; Gmail working in the next two minutes without touching the Google Cloud Console, use ClawLink.

## Is it safe to connect Gmail to OpenClaw?

The warnings you have read are mostly about a different setup than this one, so here is the specific version. What matters is which route you took and what it can reach.

- **What ClawLink asks for:** full mailbox access, approved on Google's own consent screen. That is what reading, searching, drafting, sending, forwarding, and labeling require, and it is the same reach a Gmail app password gives. We do not pretend it is narrower than it is.
- **What it does not involve:** no password and no app password, nothing durable stored on your machine or server, and no background polling. The grant is listed under Third-party apps and services in your Google account and one click at myaccount.google.com/permissions ends it.
- **The risk nobody else names: prompt injection.** An agent that reads your mail is reading text written by strangers, and that text can contain instructions. Treat an agent with send access the way you would treat a new assistant: ask for drafts, read them, then send. The draft-then-review flow in the example prompts above exists for this reason.
- **The account-ban warnings** describe brand-new Gmail accounts driven by CLI tools at high volume from day one. That pattern trips Google's abuse detection on any connection method. Free Gmail caps sending at 500 recipients a day, and bulk automated sending stays risky on a personal account regardless of how it is connected.
- **If that reach is more than you want**, connect a secondary Google account and forward the mail the agent should work on. You keep the agent useful and your primary mailbox out of scope.

The genuinely risky setups in the guides you have read are the ones that store a standing credential in a config file on a machine you may not be watching. That is worth avoiding whichever tool you pick.

## What the OpenClaw Gmail integration can do

60 Gmail tools are ready for OpenClaw once the account is connected. The 30 below are the ones people reach for most; your agent can call all 60.

### 30 of 60 Gmail tools for OpenClaw

| Tool | What it does |
|---|---|
| **Add label to email** `gmail_add_label_to_email` | Add a label to a Gmail message |
| **Create email draft** `gmail_create_email_draft` | Create a Gmail draft |
| **Create label** `gmail_create_label` | Create a Gmail label |
| **Fetch emails** `gmail_fetch_emails` | Search and fetch Gmail messages |
| **Fetch message by message ID** `gmail_fetch_message_by_message_id` | Get a Gmail message by ID |
| **Fetch message by thread ID** `gmail_fetch_message_by_thread_id` | Get a Gmail message by thread ID |
| **Forward message** `gmail_forward_message` | Forward a Gmail message |
| **Get attachment** `gmail_get_attachment` | Get a Gmail attachment |
| **Get profile** `gmail_get_profile` | Get the connected Gmail account profile |
| **List drafts** `gmail_list_drafts` | List Gmail drafts |
| **List labels** `gmail_list_labels` | List Gmail labels |
| **List send as** `gmail_list_send_as` | List Gmail send-as aliases |
| **List threads** `gmail_list_threads` | List Gmail threads |
| **Reply to thread** `gmail_reply_to_thread` | Reply to a Gmail thread |
| **Send email** `gmail_send_email` | Send a Gmail message |
| **Create prompt post** `gmail_create_prompt_post` | Send a one-shot prompt to the Sanity Content Agent |
| **Get auto forwarding** `gmail_get_auto_forwarding` | Get the auto-forwarding setting for the specified account |
| **Get contacts** `gmail_get_contacts` | Fetches contacts (connections) for the authenticated Google account, allowing selection of |
| **Get draft** `gmail_get_draft` | Retrieves a single Gmail draft by its ID |
| **Get filter** `gmail_get_filter` | Retrieve a specific Gmail filter by its ID |
| **Get label** `gmail_get_label` | Gets details for a specified Gmail label |
| **Get language settings** `gmail_get_language_settings` | Retrieve the language settings for a Gmail user |
| **Get people** `gmail_get_people` | Retrieves either a specific person's details (using `resource_name`) or lists 'Other Contacts' |
| **Get vacation settings** `gmail_get_vacation_settings` | Retrieve vacation responder settings for a Gmail user |
| **List filters** `gmail_list_filters` | List all Gmail filters (rules) in the mailbox |
| **List forwarding addresses** `gmail_list_forwarding_addresses` | List all forwarding addresses for the specified Gmail account |
| **List history** `gmail_list_history` | List Gmail mailbox change history since a known startHistoryId |
| **Search people** `gmail_search_people` | Searches contacts by matching the query against names, nicknames, emails, phone numbers, and |
| **Settings send as get** `gmail_settings_send_as_get` | Retrieve a specific send-as alias configuration for a Gmail user |
| **Batch modify messages** `gmail_batch_modify_messages` | Modify labels on multiple Gmail messages in one efficient API call |

## Example prompts

**Triage unread mail**

> Fetch my unread Gmail from the last 3 days with the query `is:unread newer_than:3d` and max_results 25, then tell me who is waiting on a reply and what each one needs.

**Find an invoice**

> Search Gmail for `from:stripe.com has:attachment newer_than:30d` with max_results 10, then download the attachment from the most recent one.

**Reply in a thread**

> Find the newest email from sarah@acme.com (`from:sarah@acme.com`, max_results 5), then reply in that same thread using the thread id from the result. Show me the draft before you send it.

**Label and clean up**

> List my Gmail labels and create one called "Needs reply" if it does not exist. Then find messages matching `is:unread older_than:7d in:inbox` with max_results 50 and add that label to them.

## What to tell the agent when it calls Gmail

These are the defaults the Gmail tools actually run with. Two of them surprise people, and both are fixed by saying one more thing in the prompt.

- `max_results` defaults to **1**. "Check my unread email" comes back with a single message. Say how many you want: "fetch my 25 most recent unread emails".
- `query` takes a full Gmail search string, the same syntax as the Gmail search box: `is:unread`, `from:sarah@acme.com`, `subject:invoice`, `has:attachment`, `newer_than:7d`, `older_than:1m`, `in:inbox`, `label:receipts`. Combine them freely.
- Spam and trash are excluded unless you ask for them. An email the agent "cannot find" is often sitting in one of the two.
- Label filters use label **ids**, not names. The built-in ids are uppercase (`INBOX`, `UNREAD`, `STARRED`, `SPAM`, `TRASH`); for your own labels, have the agent list labels first and use the id it gets back.
- Replying, forwarding, and labeling need a real thread id or message id from a search result. An id copied out of documentation is the most common cause of a 403 on an account that works fine otherwise.
- Sending HTML needs the html flag set, or the tags arrive as visible text. Only the recipient address and body are required; subject, cc, and bcc are optional.

## ClawLink vs. building it yourself

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for OpenClaw. That is fine if you want to build and maintain the integration yourself. Most teams just want Gmail working from chat.

| | Manual | ClawLink |
|---|---|---|
| **Connection flow** | Register a Gmail app, configure redirect URLs, manage consent details, and reconnect users when auth settings drift. | Users connect Gmail through the hosted browser flow and ClawLink keeps the token lifecycle out of your app code. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Gmail. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right Gmail actions to the runtime in a format your agent can reliably use. | 60 tools for Gmail are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes Gmail to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for OpenClaw users instead. You install the plugin once, connect Gmail in the browser, and the 60 tools above work from chat. There is no SDK, no config file, and no API key handling. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### OpenClaw installed the Gmail skill but can't call the tools
The ClawHub skill teaches OpenClaw about Gmail, but the calls run through the ClawLink plugin and your connected account. Make sure Gmail is connected in the dashboard, then start a fresh chat so OpenClaw reloads the tool catalog. If OpenClaw runs as a persistent gateway, restart it so the new tools register.

### Connection succeeds but no tools appear
Reconnect Gmail from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling Gmail tools
Gmail tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Gmail call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

### Gmail returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

### "invalid_grant: Token has been expired or revoked" about a week after setting Gmail up
This is the signature of a do-it-yourself Google Cloud setup, not a ClawLink one. Google issues refresh tokens that expire in 7 days when the OAuth consent screen's publishing status is still Testing, which is where gog, the Workspace CLI, and hand-rolled Gmail API projects leave it by default. Re-authorizing buys another 7 days; publishing the app is the actual fix. ClawLink connects through a hosted OAuth client that is not in Testing, so a connection made through the dashboard keeps working past that first week. If a ClawLink Gmail connection does stop, reconnect it from the dashboard and check the causes in the next entry.

Ask the agent to diagnose it:

```text
Run clawlink_list_integrations and report Gmail's connection status and auth state exactly as returned. Do not retry the failed call. If it reports needs_reauth, tell me to reconnect and stop there.
```

### Gmail worked for weeks, then every call failed after you changed your Google password
Google documents this one explicitly: changing your account password invalidates refresh tokens that carry Gmail scopes. It is not specific to ClawLink or to any agent, and nothing is wrong with the connection beyond the revoked token. Reconnect Gmail from the dashboard and the tools work again in the same chat. The other documented causes of a token going dead are revoking the app's access yourself, six months without using it, and granting time-limited access that has run out.

Ask the agent to diagnose it:

```text
Reconnect Gmail from the dashboard first, then run clawlink_list_integrations and show me the status you get back. Do not retry the original call until that shows an active connection.
```

### OAuth finished in the browser but the account is still missing
Try reconnecting Gmail and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

### Is there a OpenClaw Gmail integration?
Yes. ClawLink is the fastest way to connect OpenClaw to Gmail: link your Gmail account once in the browser and OpenClaw can call the Gmail API through 60 ready-made tools — no custom code or token handling.

### How do I add Gmail to OpenClaw with ClawLink?
Paste the setup prompt from this page into OpenClaw. It installs the ClawLink Gmail skill from ClawHub, then you click Connect in the dashboard to authorize Gmail. OpenClaw calls the tools from the next message — no config files or API keys to manage.

### How long does it take to connect Gmail to OpenClaw?
About two minutes. Sign in, click Connect next to Gmail in the dashboard, authenticate, and OpenClaw can use it from the next chat message.

### Why use ClawLink instead of wiring Gmail up myself?
The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for OpenClaw. That is fine if you want to build and maintain the integration yourself. Most teams just want Gmail working from chat.

### Do I need a Google Cloud project to connect Gmail to OpenClaw?
For the do-it-yourself paths, yes: gog, Google's Workspace CLI, direct Gmail API setups, and the Pub/Sub push route all require creating a Google Cloud project, enabling the Gmail API, configuring an OAuth consent screen, and downloading a client secret. Through ClawLink, no: the OAuth client is hosted, so you click Connect, approve on Google's consent screen, and OpenClaw gets 60 Gmail tools without any Google Cloud Console work.

### Will connecting Gmail to OpenClaw get my Google account banned?
The ban warnings in OpenClaw guides describe a specific pattern: a brand-new Gmail account, accessed only through CLI tools, sending high volume from day one. That pattern trips Google's abuse detection whichever connection method you use. Connecting an established account through OAuth is the supported path: Google shows its consent screen, you approve the access, and you can revoke the grant at myaccount.google.com/permissions without changing your password. ClawLink only touches your inbox when you ask, so there is no autonomous polling or bulk activity to flag. Bulk automated sending stays risky on any personal account; free Gmail caps sending at 500 recipients a day.

### Is it safe to connect my personal Gmail account to OpenClaw?
Here is the honest version. ClawLink's Gmail connection asks Google for full mailbox access, the same reach a Gmail app password gives, because the tools on this page read, search, draft, send, forward, and label mail. The difference from an app password is not a narrower permission: it is that no long-lived secret sits in a config file on your machine or server, the grant appears under Third-party apps and services in your Google account, and one click at myaccount.google.com/permissions ends it. The agent also acts only when you ask it to, rather than polling your inbox on a timer. If you would rather not give a personal account that reach, connect a secondary Google account instead and forward the mail you want the agent to work on.

### Can I connect Gmail to OpenClaw with an app password instead?
You can, and most no-Google-Cloud guides tell you to: enable 2-Step Verification, generate a 16-character app password, turn on IMAP in Gmail settings, and point an email skill at it. It works, and it is worth knowing the tradeoff. That password is a standing credential with full mailbox access, it lives in plain text wherever the agent runs, revoking it means deleting it from your Google account, and IMAP setups are what the ban warnings in those same guides describe. ClawLink skips the Google Cloud project too, but through Google's hosted OAuth flow instead: click Connect, approve on Google's consent screen, and nothing durable is stored on your machine.

### OpenClaw installed the Gmail skill but can't call the tools
The ClawHub skill teaches OpenClaw about Gmail, but the calls run through the ClawLink plugin and your connected account. Make sure Gmail is connected in the dashboard, then start a fresh chat so OpenClaw reloads the tool catalog. If OpenClaw runs as a persistent gateway, restart it so the new tools register.

## Related

- [Google Super](https://claw-link.dev/openclaw/google-super) — Unified access to multiple Google services in one integration
- [Google Drive tools](https://claw-link.dev/openclaw/google-drive) — Upload, search, and manage files
- [OpenClaw Google Analytics integration](https://claw-link.dev/openclaw/google-analytics) — Connect Google Analytics properties through hosted Google OAuth