Introduction

Integrating Gmail with OpenClaw allows developers and automation engineers to send and receive emails programmatically through AI agents, scripts, or bots. This setup is particularly useful for workflows such as automated notifications, customer communication, monitoring inbox events, or triggering AI tasks from emails.

This technical guide explains how to integrate Gmail with OpenClaw using the Gmail API and OAuth authentication, including steps for environments like Linux, Ubuntu, and WSL on Windows 11.

The process involves:

Prerequisites

Before starting, make sure the following are ready:

Step 1: Create a Google Cloud Project

Open the Google Cloud Console:

https://console.cloud.google.com

  1. Click Select Project

  2. Click New Project

  3. Enter a project name (example: openclaw-gmail)

  4. Click Create

Once the project is created, ensure it is selected in the top project selector.

Step 2: Enable the Gmail API

Inside the same project:

  1. Navigate to

APIs & Services → Library

  1. Search for

Gmail API

  1. Click Enable

This allows your application to interact with Gmail programmatically.

Step 3: Configure OAuth Consent Screen

Go to:

APIs & Services → OAuth Consent Screen

  1. Select External

  2. Click Create

Fill the required fields:

Click Save and Continue.

Step 4: Add Test Users

Because the app is not verified yet, Google requires adding test users.

In the Test Users section:

  1. Click Add Users

  2. Add your Gmail address

  3. Save

Without this step, authentication will fail with a 403 access_denied error.

Step 5: Create OAuth Credentials

Go to:

APIs & Services → Credentials

Click:

Create Credentials → OAuth Client ID

Select:

Desktop Application

After creation, download the JSON file.

Example filename:

client_secret_XXXXXXXX.apps.googleusercontent.com.json

Step 6: Move the OAuth File to the OpenClaw Extension Folder

Inside the OpenClaw directory, create the Gmail extension folder:

mkdir -p ~/.openclaw/extensions/gmail

If you are using WSL with Windows 11, downloaded files are typically located at:

/mnt/c/Users/<windows_username>/Downloads

Move the OAuth file:

mv /mnt/c/Users/<windows_username>/Downloads/client_secret*.json ~/.openclaw/extensions/gmail/

Rename the file:

mv ~/.openclaw/extensions/gmail/client_secret*.json ~/.openclaw/extensions/gmail/client_secret.json

Step 7: Install Required Python Libraries

Install the Gmail API libraries:

pip install google-api-python-client google-auth google-auth-oauthlib google-auth-httplib2

These libraries allow Python scripts to authenticate and communicate with Gmail.

Step 8: Create the Gmail Authentication Script

Inside the Gmail extension folder, create a Python script:

nano auth_gmail.py

Add the following code:

from google_auth_oauthlib.flow import InstalledAppFlow
import pickle

SCOPES = ['https://www.googleapis.com/auth/gmail.modify']

flow = InstalledAppFlow.from_client_secrets_file(
    'client_secret.json',
    SCOPES
)

creds = flow.run_local_server(port=0)

with open("token.pickle", "wb") as token:
    pickle.dump(creds, token)

print("Authentication successful")

Save the file.

Step 9: Authenticate Gmail Access

Run the authentication script:

python auth_gmail.py

The terminal will display a Google authorization URL.

Open that URL in your browser and log in with your Gmail account.

Approve the requested permissions.

After authorization, a file named token.pickle will be created.

Verify:

ls ~/.openclaw/extensions/gmail

Expected output:

auth_gmail.py
client_secret.json
token.pickle

Step 10: Send Email Using Gmail API

Create another script:

nano send_email.py

Add the following code:

import base64
import pickle
from email.mime.text import MIMEText
from googleapiclient.discovery import build

with open("token.pickle", "rb") as token:
    creds = pickle.load(token)

service = build("gmail", "v1", credentials=creds)

def send_email(to, subject, message_text):
    message = MIMEText(message_text)
    message["to"] = to
    message["subject"] = subject

    raw = base64.urlsafe_b64encode(message.as_bytes()).decode()

    service.users().messages().send(
        userId="me",
        body={"raw": raw}
    ).execute()

send_email(
    "[email protected]",
    "Test from OpenClaw",
    "Email sent using Gmail API and OpenClaw integration."
)

Run the script:

python send_email.py

If configured correctly, the email will be delivered via Gmail.

Step 11: Install Telegram Bot Library

Install the Telegram bot Python library:

pip install python-telegram-bot --upgrade

Verify installation:

pip show python-telegram-bot

Step 12: Create a Telegram Bot

Open Telegram and start a conversation with

BotFather

Follow these steps:

  1. Send:

/start

  1. Create a new bot:

/newbot

  1. Provide a bot name

  2. Provide a bot username ending with bot

Example:

openclaw_mail_bot

After creation, BotFather will return a Bot Token.

Example format:

123456789:AAHxxxxxxxxxxxxxxxxxxxx

Save this token securely.

Step 13: Create Telegram Email Bot Script

Navigate to the Gmail extension directory:

cd ~/.openclaw/extensions/gmail

Create the bot script:

nano telegram_mail_bot.py

Add the following code:

import base64
import pickle
from email.mime.text import MIMEText
from googleapiclient.discovery import build

from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes

BOT_TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"

# Load Gmail credentials
with open("token.pickle", "rb") as token:
    creds = pickle.load(token)

service = build("gmail", "v1", credentials=creds)

def send_email(to, subject, body):
    message = MIMEText(body)
    message["to"] = to
    message["subject"] = subject

    raw = base64.urlsafe_b64encode(message.as_bytes()).decode()

    service.users().messages().send(
        userId="me",
        body={"raw": raw}
    ).execute()

async def sendmail(update: Update, context: ContextTypes.DEFAULT_TYPE):

    if len(context.args) < 3:
        await update.message.reply_text(
            "Usage:\n/sendmail email subject message"
        )
        return

    to = context.args[0]
    subject = context.args[1]
    body = " ".join(context.args[2:])

    send_email(to, subject, body)

    await update.message.reply_text("Email sent successfully")

app = ApplicationBuilder().token(BOT_TOKEN).build()

app.add_handler(CommandHandler("sendmail", sendmail))

print("Telegram Gmail bot running...")

app.run_polling()

Replace YOUR_TELEGRAM_BOT_TOKEN with the token received from BotFather.

Step 14: Start the Telegram Email Bot

Run the bot script:

python telegram_mail_bot.py

If successful, the terminal will display:

Telegram Gmail bot running...

The bot is now listening for Telegram commands.

Step 15: Send Email From Telegram Prompt

Open Telegram and send a command to your bot.

Example command:

/sendmail [email protected] Hello Test message from Telegram

Command structure:

/sendmail recipient_email subject message_body

Example:

/sendmail [email protected] Meeting Reminder Our meeting is tomorrow at 3 PM

After the command is sent:

  1. Telegram bot receives the message

  2. Python script processes the prompt

  3. Gmail API sends the email

The bot will respond with:

Email sent successfully
Screenshot 2026-03-12 130555

Step 16: Verify Email Delivery

Check the following:

The email should appear immediately after the command is executed.

Screenshot 2026-03-12 130425

Screenshot 2026-03-12 130403

Common Issues and Fixes

403 Access Denied

Cause: OAuth consent screen missing test user.

Fix: Add your Gmail address under OAuth Consent Screen → Test Users.

Browser Not Opening in WSL

WSL environments often lack GUI browsers.

Solution:

Copy the authorization URL from the terminal and open it manually in a Windows browser.

Module Not Found Errors

Install missing libraries using:

pip install <package_name>

Use Cases for Gmail + OpenClaw Integration

Integrating Gmail with OpenClaw enables several automation scenarios:

Conclusion

Integrating Gmail with OpenClaw using the Gmail API enables powerful automation workflows across email systems and AI-driven agents. By configuring OAuth authentication, enabling the Gmail API, and implementing simple Python scripts, developers can send and manage emails programmatically.

For teams building automation pipelines, AI assistants, or DevOps alerting systems, this integration significantly improves communication workflows while maintaining secure access through Google's OAuth system.