google-workspace-byok
# 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
```bash
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](https://console.cloud.google.com) 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](https://console.cloud.google.com/auth/audience))
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](https://console.cloud.google.com/auth/clients))
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:
```bash
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:
```bash
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
```bash
# 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
```bash
# 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:someone@example.com" --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.
```bash
# 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
```bash
# 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.
标签
skill
ai
