Email integration is one of the highest-ROI OpenClaw capabilities — and also one of the highest-risk.
Community reports cluster around:
- OAuth works once, then repeatedly asks you to re-auth (or silently stops).
- Fresh VPS/Docker deploys “forget” the email session.
- New dedicated Gmail accounts get flagged quickly.
This guide focuses on reliability and blast-radius control rather than “just make it work once”.
Security reading (recommended before you give an agent inbox access):
What this guide helps you finish
By the end of this guide, you should be able to choose a mailbox pattern that is stable enough for your actual workload, not just the easiest thing to authenticate once.
That means you should know:
- whether OAuth, IMAP/SMTP, or a forwarding mailbox is the right first posture
- how to separate reader and sender identities before the workflow gets risky
- what evidence proves the integration is actually stable after restart or redeploy
- what alternative you will switch to if Gmail keeps forcing re-auth loops
Who this is for (and not for)
Use this guide if you want OpenClaw to read or send mail reliably over time, especially on VPS, Docker, or always-on setups.
This guide is less relevant if you only need a one-time local inbox test and can tolerate manual re-login.
Before you choose an email auth path: collect these five facts
- Is the workflow read-only or does it send mail? This changes your blast radius immediately.
- Will the integration survive restart and redeploy? If not, OAuth convenience is not really convenience.
- Can you use a dedicated mailbox or forwarding inbox? If yes, you can make failures much less expensive.
- Do you need Gmail specifically, or just reliable email ingestion? Many teams need the latter more than the former.
- How will you verify success after setup? A single successful login is not the same as a reliable integration.
0) Before you connect an inbox: safer defaults
Do these first:
- Use a dedicated mailbox (not your primary email).
- Use minimal permissions/scopes (read-only if that’s enough).
- Treat state persistence as mandatory (tokens live in state).
Persistence guide:
1) Choose an auth strategy you can operate
Option A: OAuth (convenient, but can be brittle)
OAuth is often the easiest to start with, but for unattended 24/7 agents it can become operational debt:
- refresh token invalidation
- “suspicious activity” checks
- device/session churn after redeploys
Option B: IMAP/SMTP (simpler mechanics, harder secret handling)
IMAP/SMTP can be more predictable if you:
- store credentials in a secret manager (not plaintext in git)
- limit the account’s privileges
- monitor for auth failures and rotate creds
If you are using a provider that supports app passwords (or a dedicated mailbox provider), this can be the boring path.
2) Why Gmail keeps asking you to re-auth
In practice, repeated re-auth prompts usually come from one of:
- State not persisting (containers reset / VM image reset) → tokens disappear.
- Multiple installs / wrong runtime → service writes tokens to a different home/state than you think.
- Token refresh failures (provider-side) → refresh fails, and the integration falls back to “needs login”.
- Security policy on the Google account (new account flags, Workspace restrictions, 2FA policy mismatch).
The first two are solvable on your side; fix them before assuming “Google is broken”.
Start with:
3) Make failures observable (so you stop guessing)
When email stops working, capture evidence before changing config:
openclaw status --deep
openclaw logs --followIf the failure is OAuth-related, you may see refresh errors in logs.
Related OAuth fix pattern (provider example):
4) Reliability patterns that actually work
4.1 “Forwarding mailbox” pattern (recommended for many teams)
Instead of giving OpenClaw your primary inbox:
- Create a dedicated mailbox (or alias) that only receives forwarded/filtered emails.
- Only forward messages that are safe to automate on (alerts, receipts, support queue).
Benefits:
- reduces prompt injection surface (less untrusted content)
- reduces business risk
- easier auditing (“what did the agent see?”)
4.2 Split “read” and “send” identities
If you need outbound email, separate identities:
- an inbox reader account
- a sending-only account with strict allowlist recipients
4.3 Always write artifacts + summaries
For cron-driven email processing, have each run:
- write a timestamped report into workspace
- send a short summary message (linking to the artifact)
Cron reliability:
5) If Gmail is too fragile: alternatives
Pragmatic alternatives when OAuth or account policy becomes too costly:
- A dedicated mailbox provider for automation (separate domain/user)
- IMAP/SMTP with app passwords / token-based credentials (where supported)
- A relay service that provides a stable API (with strict allowlists and audit logs)
The best “alternative” is the one you can:
- keep stable without daily manual login
- monitor and audit
- revoke quickly if compromised
Verification checklist after setup
Before you trust the mailbox, verify more than “I logged in once”:
- the integration survives a restart or container redeploy
- probe/status output still sees the mailbox after refresh
- the account is dedicated and the scope matches the real job
- inbound mail is filtered or forwarded in a way that limits prompt-injection surface
- you know what path you will switch to if Gmail starts forcing re-auth again
What to tighten first if reliability degrades
When the setup starts wobbling, tighten in this order: state persistence, runtime identity, mailbox scope, and only then provider choice. Most email instability gets solved faster by clarifying where tokens live and which runtime owns them than by immediately rebuilding the integration from scratch.