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 is the one we exercised; it did not require a Google Cloud project or a 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.

In our test, the agent wrote a small mail client. A protected entry could not supply the plaintext password that client needed. The working route used an agent-readable entry entered by the owner 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. We witnessed a listing expose an agent-readable password in a 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.

Our personal-Gmail test read a message, downloaded a PDF and sent a test message back to the same inbox. A later authorized email was confirmed received at its destination. A Google Workspace account also accepted both incoming and outgoing logins; that second account was a login check, not a second full automation test.

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.

The end-to-end route we tested instead scheduled the agent’s mail client. It read a matching message, downloaded its PDF, sent it to Invoice Data Extraction, answered the service’s follow-up questions, added the returned row to a workbook on the agent’s computer, replied with the result and reported in Telegram. That run used DeepSeek V4.1 Flash and took about fifteen minutes.

Keeping the workbook on that computer also kept 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. In our test, that proved unattended execution. 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.