Google Workspace BYOK

Google Calendar and Gmail integration using your own GCP project credentials (BYoK — Bring Your Own Key). Direct OAuth2 auth against your own Google Cloud pr...

Security Scan

The skill's code, instructions, and requirements are consistent with a BYoK Google Calendar/Gmail integration that stores your OAuth client and tokens locally and uses the googleapis client; nothing in the bundle requests unrelated credentials or hidden endpoints.

Purpose & Capability

Name/description describe BYoK Gmail/Calendar access and the code implements exactly that: setup, OAuth flow, token storage, Gmail and Calendar read/list/attachment operations, and account management. The files and required npm packages (googleapis, PDF extraction libs) are appropriate for the claimed functionality.

Instruction Scope

SKILL.md instructs a local npm install and running included Node scripts. Runtime instructions operate on the user's Google OAuth credentials and tokens stored in a dedicated ~/.openclaw/google-workspace-byok directory. The auth flow is manual (paste-a-url/code). The instructions do not ask the agent to read unrelated system files or exfiltrate data to external endpoints other than Google APIs.

Install Mechanism

There is no automated install spec in the registry (instruction-only), but the bundle includes a package.json/package-lock and expects the user to run npm install in the scripts directory. npm pulling many dependencies (including native/optional packages and PDF libs like mupdf/pdf-parse) is normal for PDF extraction but increases surface area; verify packages before installing and be aware native components may compile or download binaries.

Credentials

The skill requests no environment variables or external credentials beyond the user's own Google OAuth client JSON and the account authorization. Tokens and credentials are stored locally under ~/.openclaw/google-workspace-byok. Persisting refresh tokens is expected behavior for offline access; treat these files as sensitive.

Persistence & Privilege

Skill is not always-enabled and does not request elevated platform privileges. It persists its own credentials/tokens under a dedicated per-skill config directory and does not modify other skills or system configs. Autonomous invocation is allowed by default (platform behavior) but not combined with other red flags.

Assessment

This skill appears to do what it claims: run locally with your own Google OAuth client and save tokens under ~/.openclaw/google-workspace-byok. Before installing, consider: 1) review package.json and package-lock and audit the npm packages (mupdf and pdf libraries can include native code); 2) run npm install in a controlled environment (container/VM) if you want to avoid native builds or supply-chain risk; 3) keep the downloaded credentials.json and tokens private (they grant access to your accounts); 4) prefer --readonly scopes if you only need read access; and 5) be aware that apps in Google 'Testing' mode may issue short-lived tokens (the README notes a 7-day expiry) — publish to production only if you understand verification implications. If you need higher assurance, request a reproducible build or a minimal package list from the author.

Google Workspace BYoK (Bring Your Own Key)

Direct Google Calendar and Gmail API access using your own GCP project OAuth2 credentials. Supports multiple Google accounts.

Prerequisites

• Node.js (v18+)
• A Google Cloud project with Calendar and Gmail APIs enabled
• OAuth2 Desktop app credentials from your GCP project

Setup

Step 1: Install Dependencies

cd {baseDir}/scripts && npm install

This installs googleapis (Google API client) and mupdf (PDF text extraction for email attachments).

Step 2: Create a Google Cloud Project

1. Go to Google Cloud Console and create a new project (or use an existing one)
2. Enable the Google Calendar API and Gmail API:
   • Go to APIs & Services → Library
   • Search for "Google Calendar API" → click Enable
   • Search for "Gmail API" → click Enable

Step 3: Configure the OAuth Consent Screen

1. Go to Google Auth Platform → Audience (direct link)
2. If prompted, configure the consent screen:
   • App name: anything (e.g., "OpenClaw")
   • User support email: your email
   • Scopes: skip (the auth script requests scopes at runtime)
3. If your app is in Testing publishing status (the default), add every Google account you want to authorize as a test user:
   • Under Test users, click Add users
   • Enter the email addresses of each account you'll connect
   • Save

⚠️ Important: Apps in "Testing" status have a 7-day token expiry. To get long-lived tokens, publish your app to "Production" in the Audience settings. For personal Gmail accounts (External user type), you can skip Google's verification review — you'll just see an "unverified app" warning during consent. This is fine for personal use.

Step 4: Create OAuth Credentials

1. Go to Google Auth Platform → Clients (direct link)
2. Click Create Client → choose Desktop app as the application type
3. Name it whatever you like (e.g., "OpenClaw")
4. Click Create and download the credentials JSON
5. Run the setup script:

node {baseDir}/scripts/setup.js --credentials /path/to/downloaded-credentials.json

This copies your credentials to ~/.openclaw/google-workspace-byok/credentials.json.

Step 5: Authorize Google Accounts

For each Google account you want to connect:

node {baseDir}/scripts/auth.js --account <label>

The <label> is a friendly name you'll use to reference this account (e.g., "personal", "work", "household").

Auth flow:

1. The script prints an authorization URL
2. Open the URL in your browser and sign in with the Google account
3. Grant the requested permissions
4. You'll be redirected to http://localhost/... — the page won't load, and that's expected
5. Copy the full URL from your browser's address bar and paste it back into the script
6. The script exchanges the code for tokens and saves them

Scopes requested (default — read/write):

• calendar — Full read/write access to Google Calendar
• gmail.readonly — Read-only access to Gmail

Pass --readonly to request read-only calendar access instead.

Tokens are stored in ~/.openclaw/google-workspace-byok/tokens/<label>.json.

Usage

All scripts are in {baseDir}/scripts/. Run them with node.

Calendar

# List all calendars
node {baseDir}/scripts/calendar.js --account <label> --action list-calendars

# List upcoming events (default: next 7 days, primary calendar)
node {baseDir}/scripts/calendar.js --account <label> --action events

# List events with options
node {baseDir}/scripts/calendar.js --account <label> --action events --calendar <calendarId> --days <number> --max <number>

# Get a specific event
node {baseDir}/scripts/calendar.js --account <label> --action get-event --calendar <calendarId> --event-id <eventId>

# Check free/busy
node {baseDir}/scripts/calendar.js --account <label> --action freebusy --days <number>

Gmail

# List recent emails (default: 10)
node {baseDir}/scripts/gmail.js --account <label> --action list

# Search emails
node {baseDir}/scripts/gmail.js --account <label> --action list --query "from:[e-mail]" --max 20

# Read a specific email (includes attachment metadata with IDs)
node {baseDir}/scripts/gmail.js --account <label> --action read --message-id <messageId>

# Download all attachments from an email
node {baseDir}/scripts/gmail.js --account <label> --action attachment --message-id <messageId> --out-dir /tmp/attachments

# Download a specific attachment
node {baseDir}/scripts/gmail.js --account <label> --action attachment --message-id <messageId> --attachment-id <id> --out-dir /tmp

# List labels
node {baseDir}/scripts/gmail.js --account <label> --action labels

Gmail search uses the same query syntax as the Gmail web search box (e.g., is:unread, from:, newer_than:1d, has:attachment).

Reading PDF Attachments

The skill includes mupdf for extracting text from PDF attachments — useful for newsletters, invoices, school letters, etc. It handles multilingual text (Japanese, Chinese, etc.) well.

# 1. Download the attachment
mkdir -p /tmp/attachments
node {baseDir}/scripts/gmail.js --account <label> --action attachment --message-id <id> --out-dir /tmp/attachments

# 2. Extract text from the PDF
node --input-type=module -e "
import * as mupdf from '{baseDir}/scripts/node_modules/mupdf/dist/mupdf.js';
import fs from 'fs';
const data = fs.readFileSync('/tmp/attachments/filename.pdf');
const doc = mupdf.Document.openDocument(data, 'application/pdf');
for (let i = 0; i < doc.countPages(); i++) {
  const page = doc.loadPage(i);
  console.log(page.toStructuredText('preserve-whitespace').asText());
}
"

Note: mupdf is an ESM module — use node --input-type=module with import syntax, not require().

Account Management

# List configured accounts
node {baseDir}/scripts/accounts.js --action list

# Check token status
node {baseDir}/scripts/accounts.js --action status --account <label>

File Layout

~/.openclaw/google-workspace-byok/
├── credentials.json          # Your GCP OAuth credentials
└── tokens/
    ├── personal.json          # Token for "personal" account
    └── work.json              # Token for "work" account

Troubleshooting

Error 403: access_denied — "has not completed the Google verification process"

Your app is in Testing mode and the Google account isn't listed as a test user. Fix: Google Auth Platform → Audience → Test users → Add the email.

Error: invalid_grant

The refresh token expired or was revoked. Re-run node {baseDir}/scripts/auth.js --account <label> to re-authorize.

Tokens expire after 7 days

Apps in "Testing" publishing status issue tokens that expire after 7 days. Publish your app to "Production" for long-lived tokens. For personal Gmail (External user type), you can skip verification and just accept the "unverified app" warning.

Error: redirect_uri_mismatch

Your credentials.json doesn't include http://localhost as a redirect URI. Edit your OAuth client in GCP Console → Authorized redirect URIs → add http://localhost.

npm install fails or mupdf won't install

mupdf requires a C++ build toolchain on some platforms. If it fails, you can still use all other features — PDF text extraction is the only feature that requires it. Try: npm install --ignore-scripts to skip native compilation, then install mupdf separately if needed.