Setting Up Google APIs for Self-Hosted AI Agents

February 18, 2026 | Last updated: February 25, 2026

Categories: tutorial, google-cloud, openclaw, automation

This post was co-created with Clawsistant, my OpenClaw AI agent. Yes, an AI wrote part of this blog post with a little help from me.

When running a self-hosted AI assistant like OpenClaw, giving it access to your Google Workspace (Gmail, Calendar, Drive) opens up powerful automation possibilities: reading emails, checking calendar events, accessing files, and even sending messages on your behalf.

In this guide, I'll walk you through setting up Google API access — the right way.

Why Google APIs?

Most self-hosted AI agents need some way to interact with your digital life. Email and calendar are the most common use cases:

• Summarize emails — Get a daily digest of important messages
• Calendar management — Check upcoming events, schedule meetings
• File access — Read documents, spreadsheets, or drive files
• Send emails — Automate responses or notifications

Prerequisites

• A Google Workspace (formerly G Suite) account or personal Google account
• Access to Google Cloud Console (console.cloud.google.com)
• A self-hosted agent that supports OAuth 2.0 (like OpenClaw)

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click Select a project → New Project
3. Give it a descriptive name like "OpenClaw Integration"
4. Note your Project ID (we'll need it later)

Step 2: Enable Required APIs

In your project, go to APIs & Services → Library and enable these APIs:

• Gmail API — For reading and sending emails
• Google Calendar API — For reading/creating calendar events
• Google Drive API — For reading files and folders
• Google Sheets API (optional) — If you need spreadsheet access

Step 3: Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Choose External (unless you have a Workspace organization with internal apps)
3. Fill in the required fields:
   • App name: "OpenClaw Google Integration" (or whatever you prefer)
   • User support email: Your Google account
   • Developer contact information: Your email
4. Click Save and Continue
5. On Scopes, click Add or remove scopes and add:
   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/gmail.send
   • https://www.googleapis.com/auth/calendar.readonly
   • https://www.googleapis.com/auth/drive.readonly
   • https://www.googleapis.com/auth/spreadsheets.readonly
6. Save and continue through the remaining steps

Step 4: Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Choose Web application as the application type
4. Add these Authorized redirect URIs:
   • http://localhost
   • http://localhost:8080
   • http://127.0.0.1
   • https://developers.google.com/oauthplayground (for VPS/headless servers)

   (Add whatever redirect URIs your agent framework requires)

5. Click Create
6. Download the JSON file — this contains your Client ID and Client Secret

Step 5: Connect to Your Agent

Now you have:

• Client ID
• Client Secret
• Project ID

How you connect these to your agent depends on the framework. For OpenClaw, you typically:

1. Place the credentials JSON where your agent can read it
2. Run the OAuth flow (your agent should provide a URL to visit)
3. Grant permissions when prompted
4. Save the generated token for future use

What Each Scope Means

Scope	What it allows
gmail.readonly	Read emails, labels, settings
gmail.send	Send new emails
calendar.readonly	Read calendar events
drive.readonly	Read files in Drive
spreadsheets.readonly	Read Google Sheets

Notice I only requested readonly scopes where possible, and gmail.send specifically (not full Gmail access). Follow the principle of least privilege — only ask for what you need.

Troubleshooting

"App not verified" warnings

Google shows scary warnings for unverified apps. Since you're the only user, you can ignore this by clicking Advanced → Go to (App Name) (unsafe). This is normal during development.

Token expired errors

Google access tokens expire (typically 1 hour). Your agent should handle refresh tokens automatically. If not, you may need to re-authenticate.

Permission denied

Double-check that your email is added as a test user in the OAuth consent screen settings.

VPS or headless server?

Complete Headless OAuth Flow (Step-by-Step)

For VPS deployments without any browser access, use the manual_oauth.py script from the gmail-reader repo:

# On your VPS:
cd ~/openclaw-gmail-reader/
python3 manual_oauth.py

# This will output an authorization URL
# Copy it to your local browser, authorize, and paste the code back

The script handles token exchange and storage automatically. Token refresh is handled by the Google client library (tokens last ~6 months for published apps).

❌ Error: invalid_scope

Symptom: OAuth fails with invalid_scope or Access blocked: This app's request is invalid

Cause: The scopes in your authorization URL don't match what's configured in Google Cloud Console.

Fix:

1. Go to Google Cloud Console → APIs & Services → OAuth consent screen
2. Click "Add or remove scopes"
3. Ensure ALL these scopes are added:
   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/gmail.send
   • https://www.googleapis.com/auth/calendar.readonly
   • https://www.googleapis.com/auth/drive.readonly
   • https://www.googleapis.com/auth/spreadsheets.readonly
4. Save and wait 5-10 minutes for changes to propagate
5. Re-run the OAuth flow

Pro tip: If you're using the OAuth Playground method, make sure the scopes in your authorization URL exactly match what's in the console (including https:// prefix).

If your agent runs on a server without a browser (like a VPS), you can't use the standard flow.run_local_server() OAuth flow. Instead:

1. Add https://developers.google.com/oauthplayground as a redirect URI
2. Generate an authorization URL with this redirect URI
3. Visit the URL in your local browser, authorize
4. You'll be redirected to OAuth Playground with a ?code=... parameter
5. Exchange that code for a token via POST request

See the openclaw-gmail-reader repo for helper scripts that automate this.

What's Next?

In a follow-up post, I'll share the story of how I got OneDrive working with my AI agent — a much more painful journey that led me to use MultCloud as a workaround. Stay tuned!