Mail Agent

---

name: mail-agent version: 0.2.0 description: Set up AI-powered Gmail monitoring in OpenClaw. Watches inbox via Google Pub/Sub and pushes important emails to Telegram. Use when the user wants to install mail-agent, set up email notifications, configure Gmail monitoring, or troubleshoot why email alerts aren't arriving. homepage: https://github.com/nanaco666/openclaw-mail-agent metadata: {"clawdbot":{"emoji":"📬","requires":{"bins":["gog","gcloud"]},"install":[{"id":"gog","kind":"brew","formula":"steipete/tap/gogcli","bins":["gog"],"label":"Install gog (brew)"},{"id":"gcloud","kind":"brew","formula":"google-cloud-sdk","bins":["gcloud"],"label":"Install gcloud (brew)"}]}}

---

Sets up mail-agent — an AI Gmail monitor that runs inside OpenClaw and delivers important emails to your Telegram.

When invoked, walk the user through every step below in order. Check each prerequisite before proceeding. Do not skip steps.

---

Step 1 — Check gog

gog auth list

If no accounts are listed, stop and tell the user to set up gog first:

gog auth credentials /path/to/client_secret.json
gog auth add you@gmail.com --services gmail

Note which Gmail account is being watched (GOG_ACCOUNT or the default).

---

Step 2 — Check Google Cloud

gcloud auth application-default print-access-token 2>&1 | head -1

If this fails (not logged in):

gcloud auth application-default login

Check if a suitable GCP project exists:

gcloud projects list

If no project exists, create one:

gcloud projects create mail-agent-YOUR_NAME --name "Mail Agent"
gcloud config set project mail-agent-YOUR_NAME

If a project exists, set it:

gcloud config set project YOUR_PROJECT_ID

Note the project ID — needed for plugin config.

---

Step 3 — Enable APIs

gcloud services enable gmail.googleapis.com pubsub.googleapis.com

---

Step 4 — Create Pub/Sub topic and subscription

gcloud pubsub topics create mail-agent-inbox
gcloud pubsub subscriptions create mail-agent-inbox-sub --topic=mail-agent-inbox

Grant Gmail permission to publish to the topic:

gcloud pubsub topics add-iam-policy-binding mail-agent-inbox \
  --member="serviceAccount:gmail-api-push@system.gserviceaccount.com" \
  --role="roles/pubsub.publisher"

---

Step 5 — Install the plugin

openclaw plugins install https://github.com/nanaco666/openclaw-mail-agent/archive/refs/tags/v0.2.1.tar.gz

---

Step 6 — Configure

Set required values (replace placeholders):

openclaw plugins config mail-agent --set chatId=YOUR_TELEGRAM_CHAT_ID
openclaw plugins config mail-agent --set gcpProject=YOUR_GCP_PROJECT_ID
openclaw plugins config mail-agent --set pubsubSubscription=mail-agent-inbox-sub

Set LLM for email classification (recommended — skip to use pass-through):

openclaw plugins config mail-agent --set llmApiKey=sk-...
openclaw plugins config mail-agent --set llmModel=gpt-4o-mini

To find your Telegram chat ID: message @userinfobot on Telegram.

---

Step 7 — Restart OpenClaw

openclaw gateway restart

Wait a few seconds, then check logs:

openclaw gateway logs | grep mail-agent

Expected output:

mail-agent: watch registered, historyId=...
mail-agent: watching inbox

If you see watch registration failed, re-check Step 3 and Step 4.

---

Step 8 — Test

Send a test email to the watched Gmail account with urgent content, e.g.:

> Subject: Urgent: server is down > Body: Production database crashed, users can't log in.

Wait up to 60 seconds. A notification should arrive in Telegram.

If nothing arrives after 2 minutes:

openclaw gateway logs | grep mail-agent

Common issues:

telegram runtime not available → restart OpenClaw gateway

watch registration failed → APIs not enabled or wrong project

subscription error → subscription name mismatch, check Step 4

No logs at all → plugin not loaded, check openclaw plugins list

---

Reconfigure / update settings

openclaw plugins config mail-agent --set KEY=VALUE
openclaw gateway restart

Uninstall

openclaw plugins uninstall mail-agent
openclaw gateway restart