← Back to Guides

Set Up Gmail Integration with OpenClaw on Windows (04/12/26)

This guide walks you through one reliable path: create Google OAuth credentials, connect them to gog, authorize Gmail access, validate read and send operations, and lock down credentials on a Windows OpenClaw machine.

1) Outcome + Architecture

  • You will have Gmail connected to an OpenClaw environment on Windows via gog.
  • OAuth client credentials are stored locally.
  • Refresh/access tokens are saved in your local credential/keyring store used by gog.
  • You can run Gmail commands like search and send from terminal workflows.
Flow: Google Cloud Project → Gmail API enabled → OAuth consent configured → Desktop OAuth client JSON downloaded → gog auth credentials + gog auth add → Gmail command tests.

2) Prerequisites

Accounts and access

  • A Google account with Gmail enabled.
  • Permission to create or use a Google Cloud project.
  • A Windows machine hosting the OpenClaw instance you want to integrate (this guide is for that other instance, not this current machine).

Windows software

  • PowerShell 7+ recommended (Windows PowerShell 5.1 works for most commands).
  • Node.js LTS (if OpenClaw is not already installed).
  • gog installed and available in PATH.

Folders to create

mkdir C:\OpenClaw\secrets
mkdir C:\OpenClaw\logs

Use your own secure path if you already standardize secrets elsewhere.

3) Windows Setup (OpenClaw + gog)

3.1 Verify OpenClaw on target Windows host

openclaw --version
openclaw gateway status

If commands are missing, install OpenClaw on that machine (adjust to your org standard):

npm install -g openclaw
openclaw --version

3.2 Verify gog

gog --version
gog --help
If gog is not installed on Windows, install it using your approved method for your environment, then re-run the checks above. (The official site documents Homebrew and source build; Windows orgs often deploy via internal package tooling.)

4) Google Cloud Project + Gmail API

  1. Open Google Cloud Console and select (or create) a dedicated project for this OpenClaw instance.
  2. Go to APIs & Services → Library.
  3. Enable Gmail API.
  4. Recommended: also enable Google People API and Google Calendar API if you expect future gog workflows that use contacts/calendar.
Principle: only enable APIs you actually plan to use.

6) Create Desktop OAuth Client + Download JSON

  1. Go to Google Auth Platform → Clients.
  2. Select Create Client.
  3. Application type: Desktop app.
  4. Name it clearly (example: openclaw-gmail-windows-desktop).
  5. Create and download the JSON file.
  6. Copy file to the target Windows machine, for example:
copy C:\Users\YourUser\Downloads\client_secret_*.json C:\OpenClaw\secrets\gmail-client.json
Do not check this file into Git. Treat it as a secret.

7) Store Credentials + Authorize Account in gog

Run on the target Windows OpenClaw machine:

gog auth credentials C:\OpenClaw\secrets\gmail-client.json

gog auth add youremail@example.com --services gmail

gog auth list

Optional default account (PowerShell for current session):

$env:GOG_ACCOUNT="youremail@example.com"
gog gmail labels list

Optional persistent environment variable:

setx GOG_ACCOUNT "youremail@example.com"
If you later add services/scopes and do not get a refreshed consent flow, re-authorize with --force-consent.

8) Test Gmail Search + Send

8.1 Search test (read access)

gog gmail search "newer_than:7d" --max 10

gog gmail messages search "in:inbox is:unread" --max 20

8.2 Send test (send access)

gog gmail send --to recipient@example.com --subject "OpenClaw Gmail test" --body "This is a Gmail integration test from Windows."

8.3 Multi-line body from file

@"
Hello,

This is a multi-line test sent from gog on Windows.

Thanks.
"@ | Out-File -FilePath C:\OpenClaw\secrets\gmail-test-body.txt -Encoding utf8

gog gmail send --to recipient@example.com --subject "OpenClaw body-file test" --body-file C:\OpenClaw\secrets\gmail-test-body.txt
Success criteria: search returns results, send returns message metadata (or success output), and recipient receives the test email.

9) Troubleshooting Common Errors

access_denied during auth

  • Make sure your account is allowed as a test user (for External apps in testing mode).
  • Confirm correct OAuth consent audience and publish/test status.

invalid_client or client not found

  • Wrong JSON file, wrong project, or malformed file path.
  • Re-download OAuth desktop client JSON and re-run gog auth credentials.

insufficientPermissions from Gmail commands

  • Scope mismatch, for example using send command without gmail.send access.
  • Re-authorize account with required scopes and --force-consent.

gog command not recognized on Windows

  • Binary not installed or not in PATH.
  • Restart PowerShell after install and verify with gog --version.

Browser auth flow does not open

  • Use manual auth mode if available in your build, or copy/paste auth URL from terminal when prompted.
  • Verify local security software is not blocking loopback callback behavior.

10) Security Notes and Best Practices

  • Use one dedicated Google Cloud project per environment (dev/test/prod).
  • Request the least-privilege Gmail scope needed.
  • Store OAuth client JSON under restricted NTFS permissions, not shared folders.
  • Do not store credential JSON or token material in plaintext docs, chat logs, or repos.
  • Use separate Google accounts/aliases for automation when appropriate.
  • Rotate/revoke credentials immediately if exposure is suspected.
  • Regularly review OAuth clients and authorized apps in Google Cloud and account security pages.

11) Sources