google-workspace-byok

使用您自己的 GCP 项目凭据（BYoK - 自带密钥）集成 Google 日历和 Gmail。 针对您自己的 Google Cloud 项目进行直接 OAuth2 身份验证。跨多个 Google 帐户阅读日历、活动和电子邮件。 当用户想要检查日历、阅读电子邮件或管理日程安排时，请使用此技能。 支持：列出/阅读电子邮件、Gmail 搜索查询、下载附件、从 PDF 附件中提取文本、 列出日历、列出/获取事件、检查空闲/忙碌状态以及管理多个 Google 帐户。

## 概述（中文）

使用您自己的 GCP 项目凭据（BYoK - 自带密钥）集成 Google 日历和 Gmail。
针对您自己的 Google Cloud 项目进行直接 OAuth2 身份验证。跨多个 Google 帐户阅读日历、活动和电子邮件。
当用户想要检查日历、阅读电子邮件或管理日程安排时，请使用此技能。
支持：列出/阅读电子邮件、Gmail 搜索查询、下载附件、从 PDF 附件中提取文本、
列出日历、列出/获取事件、检查空闲/忙碌状态以及管理多个 Google 帐户。

## 原文

# 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.