How to connect OpenClaw to Gmail

Start with the mailbox and the job

You can connect an existing Gmail account or give the agent a separate mailbox. An existing account has the messages you already receive. A separate account contains only what you or your correspondents send there. That difference matters: an app password is not restricted to one sender, label or attachment type. A rule telling the agent to read only invoices does not narrow the credential’s access.

Tell the agent which mailbox you want to connect, what it should do with incoming mail, and whether it may send replies or must ask first. It needs the email address, but it should request the credential separately. Do not send your normal Google password, and do not paste an app password into chat.

Create a Google app password

Google recommends Sign in with Google for compatible email clients and documents app passwords as an alternative with 2-Step Verification. The app-password route needs no Google Cloud project and no ChatGPT connection.

1. Open the Google Account settings for the mailbox you intend to connect, and enable 2-Step Verification if it is not already on.
2. Open that account’s App passwords settings and create a password with a name you will recognize later.
3. Keep the value out of messages and screenshots. Tell the agent it is ready, then use the credential-entry surface it identifies in OpenClaw’s control panel.

If App passwords is unavailable, this route is not available for that account as configured. For a work or school account, ask its administrator about permitted mail-client access; a successful test on another account does not override your organization’s policy.

Check how the mail client will use the password

OpenClaw distinguishes a protected secret from an Agent-readable environment entry. Its masked credential request creates the protected kind. The agent receives a reference, not the value. An environment entry is different: commands the agent runs can receive its actual value, and a diagnostic that lists those entries can print it.

On this route the agent reaches the mailbox through a small mail client it writes itself, and a protected entry cannot supply the plaintext password that client needs. What works is an agent-readable entry, which you enter yourself under the control panel’s Settings → Secrets. That is a meaningful access decision: code the agent runs can read, use or expose the credential. Choose it only if you intend to grant that access. A dedicated mailbox reduces what is reachable; it does not make the password itself unreadable.

Ask the agent to verify authentication without printing the password or listing secret values; a listing can put an agent-readable password into the transcript. If that happens, revoke it at Google and replace it; deleting the chat message is not revocation. The SecretRefs guide explains why storing a credential and keeping it hidden from agent code are separate things.

Test reading and sending separately

The connection details are imap.gmail.com:993 with TLS for incoming mail, and smtp.gmail.com:587 with STARTTLS for outgoing mail. These are Google’s mail endpoints, reached from the computer running the mail client. The login name is the full email address.

Have the agent test both logins without reading or sending anything first. Then send a harmless message with one test attachment to the connected mailbox. Ask the agent to find that specific message, save the attachment and identify the saved file. Finally, approve a reply to an address you control and check that it arrives. A successful incoming login does not prove outgoing mail works.

On a personal Gmail account, this route reads a message, downloads its PDF and sends mail that arrives at its destination. A Google Workspace account accepts both the incoming and the outgoing login as well; that establishes the connection there, not the whole workflow.

A mail watcher is not a complete email assistant

The bundled IMAP trigger starts a restricted reader for new, allowed messages. It requires an available sandbox backend and does not itself send mail or replay messages that were already present when monitoring began. It is not a drop-in attachment-processing and reply workflow. For an agent that checks a mailbox on a schedule and drafts replies for you to approve, see the email assistant guide.

The route that works end to end schedules the agent’s own mail client instead. For invoices, that job reads a matching message, downloads its PDF, sends it to Invoice Data Extraction, answers the service’s follow-up questions, adds the returned row to a workbook on the agent’s computer, replies with the result and reports in Telegram. On DeepSeek V4.1 Flash, one run takes about fifteen minutes.

Keeping the workbook on the agent’s computer also keeps Google Drive out of the connection. Gmail access does not grant Drive or Google Sheets access. If you want the output sent back as a file, test that delivery too; an email containing totals is not proof that a spreadsheet was attached. The file-sharing guide covers that last step.

Put the working job on a schedule

Once the small test works, agree which mail is in scope, how repeats should be recognized, where results belong, when a reply is allowed, and what the agent should report when it cannot finish. Email and attachments are outside content, not instructions from you; prompt injection matters when a mail-reading agent also has tools.

Use a near-term one-off scheduled job to check the whole path without sending another chat message to start it; that proves the job runs unattended. Check the completed output and delivery before turning the one-off into a daily routine, and specify the time zone rather than just an hour.

When you no longer want mailbox access, cancel its scheduled jobs and revoke the app password in Google Account settings. Remove the stored credential as well. Stopping a schedule alone leaves a working password behind.