Docs

GSuite Integration

Connect your agent to Gmail and Google Calendar via a service account with domain-wide delegation.

The GSuite bridge gives your agent read/write access to Gmail and Google Calendar without storing user sessions or going through OAuth flows. It uses a Google Cloud service account with domain-wide delegation (DWD), which lets it impersonate your Workspace account.

Requirements

  • A Google Workspace account — free personal Gmail accounts don't support domain-wide delegation. Workspace starts at $6/user/month. If your domain already has Workspace (you have email at your domain), you're set.
  • Google Workspace Admin access — you need to be the admin of the Workspace to grant delegation.
  • A Google Cloud account — free tier is fine. You only need it for the API project and service account.

Step 1 — Create a Google Cloud Project

  1. Go to console.cloud.google.com
  2. Click the project dropdown at the top → New Project
  3. Name it something like agent-bridge and click Create
  4. Make sure your new project is selected in the top dropdown before continuing

Step 2 — Enable the APIs

In your project:

  1. Go to APIs & Services → Library (left sidebar)
  2. Search for and enable each of these:
    • Gmail API → click Enable
    • Google Calendar API → click Enable
    • People API → click Enable (optional, used for contacts)

Step 3 — Create a Service Account

  1. Go to IAM & Admin → Service Accounts (left sidebar)
  2. Click + Create Service Account
  3. Give it a name like agent-bridge — the email will be auto-generated (e.g., agent-bridge@your-project.iam.gserviceaccount.com)
  4. Click Create and Continue
  5. Skip the optional role assignment steps — click Done
  6. Back on the service accounts list, click the service account you just created to open its details
  7. Copy the Unique ID — this is a long number like 118234567890123456789. This is the Client ID you'll need in Step 5.

Step 4 — Create and Download a JSON Key

  1. In the service account details, click the Keys tab
  2. Click Add Key → Create new key
  3. Choose JSON and click Create
  4. A .json file downloads automatically — this is the service account credential file. Google only stores the public key; this is your only copy of the private key.

Blocked by org policy? If you see "Service account key creation is disabled", your GCP organization has the iam.disableServiceAccountKeyCreation constraint enforced (Google has been rolling this out automatically). To override it at the project level:

  1. Go to IAM & Admin → Organization Policies (left sidebar)
  2. Search for iam.disableServiceAccountKeyCreation
  3. Click it → Manage policy
  4. Under Policy source, select Override parent's policy
  5. Set to Not enforced → click Set policy

This only affects your project, not the entire organization. Then retry key creation.

No permission to manage policies? If you get "The following permissions are required: orgpolicy.policies.create...", you need the Organization Policy Administrator role. This must be granted at the organization level, not the project level:

  1. Click the project dropdown at the top of the GCP console → select your organization (above any projects in the list)
  2. Go to IAM & Admin → IAM
  3. Find your account in the list → click the pencil (edit) icon
  4. Click Add another role → search for Organization Policy Administrator → select it
  5. Click Save
  6. Switch back to your project and retry the org policy override above

Store it on your server:

# Create credentials directory
mkdir -p /home/openclaw/credentials
chmod 700 /home/openclaw/credentials

# Upload the file (run this from your local machine)
scp /path/to/downloaded-key.json root@your-server:/home/openclaw/credentials/gsuite-service-account.json

# Lock down permissions on the server
chmod 600 /home/openclaw/credentials/gsuite-service-account.json
chown openclaw:openclaw /home/openclaw/credentials/gsuite-service-account.json

Step 5 — Grant Delegation in Google Workspace Admin

  1. Go to admin.google.com
  2. Navigate to Security → Access and data control → API controls
  3. Click Manage Domain-Wide Delegation
  4. Click Add new
  5. Paste the Client ID (Unique ID) you copied in Step 3
  6. Add these OAuth scopes (paste the full block):
https://mail.google.com/,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/contacts.readonly
  1. Click Authorize

Propagation can take a few minutes, and in some cases up to 24 hours. If the bridge returns an authentication error immediately after setup, wait and try again before troubleshooting further.

Step 6 — Configure the Bridge

Add these environment variables to /opt/openclaw.env:

GSUITE_USER=your@workspace-email.com
GOOGLE_APPLICATION_CREDENTIALS=/home/openclaw/credentials/gsuite-service-account.json

GSUITE_USER should be the actual email address the agent will act on behalf of — your own email, not the service account email.

Then restart the bridge and verify it's responding:

systemctl restart gsuite-bridge
curl http://localhost:3031/health

A healthy response looks like {"status":"ok"}. If you get a connection error, check journalctl -u gsuite-bridge -n 50 for the error.

Verify It Works

Test the connection by checking your inbox:

curl "http://localhost:3031/gmail/inbox?maxResults=5"

If you see a JSON array of email objects, it's working. If you get an authentication error, the most common causes are:

  • The Client ID in Workspace Admin doesn't match the one from your service account
  • The scopes weren't saved correctly — check Manage Domain-Wide Delegation in Workspace Admin
  • GSUITE_USER in openclaw.env doesn't match a real user in your Workspace
  • The JSON key path is wrong or the file has wrong permissions

Bridge API Reference

The bridge runs on localhost:3031. All endpoints are local-only — never exposed publicly.

GET  /gmail/inbox?maxResults=20&query=is:unread
GET  /gmail/thread/:id
POST /gmail/send        { to, subject, body, cc? }
POST /gmail/reply       { threadId, body }

GET  /calendar/events?days=7
POST /calendar/create   { title, start, end, description?, attendees? }
DELETE /calendar/event/:id

GET  /health

Safety Notes

  • The bridge does not send email automatically — the agent must explicitly call /gmail/send
  • Every outbound action (email sent, calendar event created) is logged to /home/openclaw/gsuite-bridge/audit.log
  • Review the audit log after first enabling autonomous email sending
  • Consider adding a per-day send limit in the bridge config before going live with outreach

A Note on the DWD Approach

The service account + domain-wide delegation setup documented here works well for a single-user Google Workspace, but it has friction: it requires Workspace Admin access, org policy overrides, and Google actively discourages service account key creation through their "Secure by Default" enforcement.

For a multi-user or productized deployment, OAuth 2.0 with a stored refresh token is the better approach:

  • Works with personal Gmail (no Workspace required)
  • No domain-wide delegation needed — only grants access to the authorizing user's account
  • Setup is a one-time browser authorization flow, not an admin console operation
  • Easier to revoke from Google Account settings

The bridge service would need to be updated to use google.auth.OAuth2 instead of google.auth.JWT. The API endpoints remain identical — only the auth layer changes. If you're deploying this for someone else, OAuth is the path of least resistance.

Back to Docs Issue with this page?