Gmail

How it works

The /add-gmail skill connects NanoClaw to your Gmail account. Unlike the messaging channel skills, Gmail offers two distinct modes — you choose which one fits your workflow during setup.

Tool mode gives your agent the ability to read, send, search, and draft emails when asked. The agent doesn’t monitor your inbox automatically. Instead, you trigger email actions from a messaging channel: “Check my inbox,” “Send an email to Sarah about the meeting,” or “Search for invoices from last month.” This mode requires minimal code changes — it mounts your Gmail credentials into the container and adds an MCP server that provides email tools to the agent.

Channel mode goes further. Gmail becomes a full NanoClaw channel, just like WhatsApp or Telegram. The agent polls your inbox for new messages matching certain criteria and can respond to them directly. You can set up scheduled tasks like “Summarize my unread emails every morning at 8am” or have the agent automatically handle certain types of emails. This mode applies the full skills engine and adds the GmailChannel class to the codebase.

OAuth setup

Both modes require OAuth 2.0 authentication with Google Cloud Platform. The skill guides you through creating a GCP project, enabling the Gmail API, and downloading OAuth client credentials. You then authorize NanoClaw to access your Gmail account through a browser-based flow.

The credentials are stored locally in ~/.gmail-mcp/ and mounted into the container. They include a refresh token, so re-authentication is rarely needed. The MCP server (@gongrzhe/server-gmail-autoauth-mcp) handles token refresh automatically.

What the agent can do

Once Gmail is set up, the agent has access to these capabilities:

• Read emails — fetch recent messages, read specific threads, check unread count.
• Send emails — compose and send new messages or replies.
• Search — use Gmail’s search syntax to find specific emails.
• Draft — create drafts without sending, for your review.

In channel mode, the agent can also receive incoming emails as triggers and respond to them in-thread.

Tips

• Tool mode is the lighter option if you just want occasional email access from WhatsApp or Telegram. Channel mode is for people who want their agent to actively manage email.
• GCP projects in “Testing” mode limit OAuth to 100 users, but since this is your personal agent, that’s not an issue. You won’t need to publish the app.
• The Gmail API has a daily quota of 1 billion quota units for most projects. Normal personal use stays far below this.
• If you see authentication errors after a long period of inactivity, the refresh token may have expired. Re-run the OAuth flow to get a new one.