How to Connect Gmail to OpenClaw

Go to console.cloud.google.com and sign in with your Google account. Create a new project (or use an existing one) — click the project dropdown at the top, then 'New Project', give it a name like 'OpenClaw Gmail Integration', and click 'Create'. With your project selected, go to 'APIs & Services' > 'Library'. Search for 'Gmail API' and click on it. Click 'Enable' to activate it for your project. Next, create OAuth credentials. Go to 'APIs & Services' > 'Credentials' > 'Create Credentials' > 'OAuth client ID'. If prompted to configure the consent screen first, do that now: - User Type: External (unless you have a Google Workspace org) - App name: 'OpenClaw Gmail' - User support email: your email - Developer contact: your email - Scopes: add `https://www.googleapis.com/auth/gmail.modify` (covers read + send + label management) - Test users: add your Gmail address - Save and continue back to credential creation For 'Application type', select 'Desktop app' (this is important — it allows the local OAuth flow). Name it 'OpenClaw'. Click 'Create'. Google will show you your Client ID and Client Secret — download the JSON file and store it safely. These are your OAuth credentials.

1# Downloaded credentials JSON format (credentials.json):
2{
3  "installed": {
4    "client_id": "123456789-abc.apps.googleusercontent.com",
5    "project_id": "openclaw-gmail",
6    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
7    "token_uri": "https://oauth2.googleapis.com/token",
8    "client_secret": "GOCSPX-XXXXXXXXXXXXXXXXXXXX",
9    "redirect_uris": ["http://localhost"]
10  }
11}

Google's OAuth 2.0 requires a one-time authorization step where you sign in to your Google account and grant permission to the application. This produces an access token (short-lived) and a refresh token (long-lived) — OpenClaw uses the refresh token to get new access tokens automatically. The authorization URL follows a specific pattern using your client ID. Open the URL in a browser while signed into the Gmail account you want to connect. Google will show a consent screen listing the permissions you are granting — for `gmail.modify` scope, this includes read and write access to your Gmail. Click 'Allow'. After authorization, Google redirects to a localhost URL with an authorization `code` parameter. Copy that code and exchange it for tokens using the token exchange endpoint. The response includes both `access_token` and `refresh_token`. Copy the `refresh_token` — this is what goes into OpenClaw's config. The access token expires in one hour; the refresh token is permanent unless revoked. Note: if you see 'App is not verified' warning, click 'Advanced' > 'Go to OpenClaw Gmail (unsafe)' — this appears because the OAuth app is in testing mode, which is expected for personal use.

1# Step 1: Build authorization URL and open in browser:
2# https://accounts.google.com/o/oauth2/v2/auth?
3#   client_id=YOUR_CLIENT_ID
4#   &redirect_uri=http://localhost
5#   &response_type=code
6#   &scope=https://www.googleapis.com/auth/gmail.modify
7#   &access_type=offline
8#   &prompt=consent
9
10# Step 2: After browser redirect, copy 'code' from the URL:
11# http://localhost/?code=4/0AYYYYYY...&scope=...
12
13# Step 3: Exchange code for tokens:
14curl -X POST https://oauth2.googleapis.com/token \
15  -H "Content-Type: application/x-www-form-urlencoded" \
16  -d "code=YOUR_AUTH_CODE\
17      &client_id=YOUR_CLIENT_ID\
18      &client_secret=YOUR_CLIENT_SECRET\
19      &redirect_uri=http://localhost\
20      &grant_type=authorization_code"
21
22# Response includes:
23# {"access_token": "ya29.xxx", "refresh_token": "1//xxx", "expires_in": 3600, ...}
24# SAVE the refresh_token — it is only returned on the first authorization

Open `~/.openclaw/config.yaml` and add the Gmail integration block under `integrations`. You need four values from the previous steps: `client_id` and `client_secret` (from your OAuth credentials JSON), `refresh_token` (from the token exchange), and `user_email` (your Gmail address — used for identifying the account and as the sender in outgoing emails). The `scopes` field must match exactly what you authorized in the OAuth flow. If you authorized `gmail.modify`, list that scope. If you need more restricted access (read-only monitoring), use `gmail.readonly` instead — but you would need to complete a new authorization flow with that scope. The optional `poll_interval` controls how frequently OpenClaw checks for new messages matching your configured filters. Setting `max_results` limits how many messages are fetched per poll to prevent processing overload on inboxes with high volume. After saving, run `clawhub reload`. OpenClaw will immediately attempt to exchange your refresh token for an access token and verify the Gmail API connection.

1# ~/.openclaw/config.yaml
2integrations:
3  gmail:
4    client_id: "123456789-abc.apps.googleusercontent.com"
5    client_secret: "GOCSPX-XXXXXXXXXXXXXXXXXXXX"
6    refresh_token: "1//0eXXXXXXXXXXXXXXXXXXXXXX"
7    user_email: "you@gmail.com"
8    scopes:
9      - https://www.googleapis.com/auth/gmail.modify
10    poll_interval: 60             # Seconds between inbox checks
11    max_results: 10               # Max messages fetched per poll
12    query: "is:unread in:inbox"   # Gmail search query to filter messages
13    label_filter: ""              # Optional: restrict to specific label ID

Verify the integration by calling Gmail API endpoints directly to list recent messages and send a test email. This confirms that your OAuth credentials are working and that OpenClaw has the correct permissions. To list messages, call the `users.messages.list` endpoint with your Gmail search query. The response returns message IDs — to get the full content, call `users.messages.get` with a specific message ID. Messages are returned in a format where the body is base64url-encoded — decode it to read the content. To send an email, construct a MIME message, base64url-encode it, and POST it to the `users.messages.send` endpoint. The examples below show the complete flow for both operations. Send a test email to yourself first to confirm the send pipeline works before connecting it to automated workflows. Check that the email arrives in Gmail with the correct sender address, subject, and body.

1# Get access token from refresh token (needed for direct API testing):
2curl -X POST https://oauth2.googleapis.com/token \
3  -H "Content-Type: application/x-www-form-urlencoded" \
4  -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&refresh_token=YOUR_REFRESH_TOKEN&grant_type=refresh_token"
5# Returns: {"access_token": "ya29.xxx", "expires_in": 3600}
6
7# List recent unread emails:
8curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
9  "https://gmail.googleapis.com/gmail/v1/users/me/messages?q=is:unread+in:inbox&maxResults=5"
10
11# Send a test email (body is base64url-encoded MIME message):
12# First, create the MIME message:
13# From: you@gmail.com
14# To: you@gmail.com
15# Subject: OpenClaw Gmail Test
16# 
17# Test message from OpenClaw Gmail integration.
18
19# Encode and send:
20MIME_MESSAGE=$(echo -e "From: you@gmail.com\nTo: you@gmail.com\nSubject: OpenClaw Gmail Test\n\nTest message from OpenClaw." | base64 -w 0 | tr '+/' '-_')
21curl -X POST "https://gmail.googleapis.com/gmail/v1/users/me/messages/send" \
22  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
23  -H "Content-Type: application/json" \
24  -d "{\"raw\": \"$MIME_MESSAGE\"}"

With read and send confirmed, configure OpenClaw to act on incoming emails automatically. The common automation pattern is: poll for new emails matching a query, extract structured information (sender, subject, body snippet), process with AI, and take action (reply, label, notify via Telegram, log to Notion). Configure OpenClaw workflows with Gmail as the trigger source. The workflow receives the email event (with subject, from, body, message ID, thread ID), runs AI processing on the content, and calls back to Gmail API or other integrations with the result. For reply automation, use the `threadId` from the incoming message to create a reply in the same thread — Gmail groups replies by thread ID, so using it keeps conversations organized. RapidDev recommends saving AI-generated replies as drafts first (using the `users.drafts.create` endpoint) rather than sending automatically, at least during initial testing — it gives you a review step before responses go out to real contacts. The config below shows a simple email-to-Telegram notification workflow as a starting pattern.

1# ~/.openclaw/config.yaml — email notification workflow
2workflows:
3  gmail-support-alert:
4    trigger:
5      integration: gmail
6      event: new_message
7      conditions:
8        - field: subject
9          contains_any: ["urgent", "help", "issue", "broken"]
10    actions:
11      - type: ai-response
12        prompt: "Summarize this email in 2 sentences: Subject: {{trigger.subject}} | From: {{trigger.from}} | Body: {{trigger.snippet}}"
13      - type: integration-call
14        integration: telegram
15        endpoint: /sendMessage
16        method: POST
17        body:
18          chat_id: YOUR_TELEGRAM_CHAT_ID
19          text: "<b>New urgent email</b>\nFrom: {{trigger.from}}\nSubject: {{trigger.subject}}\n\n{{ai-response.output}}"
20          parse_mode: HTML
21      - type: integration-call
22        integration: gmail
23        endpoint: /gmail/v1/users/me/messages/{{trigger.message_id}}/modify
24        method: POST
25        body:
26          addLabelIds: ["Label_urgent_id"]
27          removeLabelIds: ["UNREAD"]