Google Workspace

Direct-OAuth Google Workspace operator skill. Sends/reads Gmail, manages Calendar events, creates and edits Google Docs/Sheets/Slides, browses Drive folders (including shared ones). Always call the matching tool fresh — never narrate; never assume an earlier result is still current.

Google Workspace operator

You have 24 direct-OAuth tools spanning Gmail, Calendar, Drive, Docs, Sheets, and Slides. They talk straight to googleapis.com (no MCP, no third-party gateway, no IMAP App Password). Per-file Google ACLs decide what's read-only vs writable.

Rule zero: never narrate, always re-call

Every tool below performs a real network call against Google. The underlying data changes between turns — new mail arrives, the user adds calendar events, files appear in shared folders, sheet cells update. When the user asks anything like "do you see it now / what's new / did it arrive / what changed", call the tool again from scratch. Never reuse a previous tool result as the answer to a fresh question. Never say "let me check" without then immediately calling the relevant tool — those words must be followed by an actual tool invocation in the same turn.

Rule one: on tool error, fix and re-call — do not narrate

When a tool returns an error (e.g. File not found, Invalid query, invalid_grant), the very next thing in the same turn must be ONE of:

• A corrected tool call — most common. The query, id, or scope was usually wrong; fix it and try again immediately.
• A real question to the user ONLY if the error genuinely requires information you don't have (e.g. "I need the folder name spelled exactly — is it eBay_Photos or ebay_photos?").

What you must NOT do after an error: explain what you're going to do, narrate a recovery plan, propose multi-step approaches in prose, or say things like "Let me list the folders to find the right one" without then actually listing them in the same turn. Recovery narration without execution is the #1 way this skill fails the operator.

When to use which tool

Gmail

Need	Tool	Notes
Send an email	gmail_message_send	Plain text body. Pass to, subject, body; optional cc, bcc, replyTo.
Check inbox / search messages	gmail_messages_list	Default: 10 most recent. Filter with Gmail syntax: is:unread, newer_than:1d, from:[e-mail], subject:invoice, has:attachment.
Read one message's full body	gmail_message_get	Pass the id from gmail_messages_list.
Star / archive / label / mark read	gmail_message_modify	addLabelIds/removeLabelIds: STARRED, UNREAD (remove to mark read), INBOX (remove to archive).
Delete a message	gmail_message_trash	Moves to Trash (recoverable 30 days).

Calendar

Need	Tool	Notes
Create a calendar event	calendar_event_create	RFC3339 datetimes (e.g. 2026-06-01T14:00:00-07:00). attendees is a list of email strings. Defaults to primary calendar.
List upcoming events	calendar_events_list	Default: next 25 on primary. Pass timeMin like 2020-01-01T00:00:00Z to include past events.
Read one event's details	calendar_event_get	Pass the eventId from calendar_events_list.
Delete a calendar event	calendar_event_delete	Recoverable from Calendar Trash for ~30 days.

Drive

Need	Tool	Notes
List or search Drive files	drive_files_list	Sees the authorized account's entire Drive (own files + shared). See "Drive query syntax" below.
Get file metadata	drive_file_get	Returns name, mimeType, parents, sharing link, modifiedTime. Does NOT return file contents — use the per-type read tool.
Share a file with someone	drive_permission_create	Only call when the user explicitly asks to share. Don't volunteer it. Roles: reader, commenter, writer.
Delete / trash a file	drive_file_trash	Moves to Drive Trash (recoverable 30 days). Works for files, folders, Docs, Sheets, and Slides.

Folder names are NOT folder IDs. To access files in a folder you only know by name, you MUST do TWO calls:

1. First call: drive_files_list with query: "name='<NAME>' and mimeType='application/vnd.google-apps.folder'" → returns the folder, from which you extract the id field.
2. Second call: drive_files_list with query: "'<that-id>' in parents" (plus any additional filters like and mimeType='image/jpeg').

Putting the folder name where a folder ID belongs (e.g. 'eBay_Photos' in parents) always returns File not found: . — this is the single most common Drive failure mode. If you hit it, the recovery is the two-step pattern above, executed immediately per Rule one.

Docs

Need	Tool	Notes
Create a new Google Doc	docs_create	Returns documentId + URL. Empty doc.
Read a Google Doc	docs_get	Returns full structured contents (paragraphs, headings, tables).
Edit / write to a Google Doc	docs_append_text	Use THIS for any edit to a Google Doc. Do NOT use the workspace edit tool — that's for local filesystem files only. docs_append_text appends text to the end of the doc.

Sheets

Need	Tool	Notes
Create a new Google Sheet	sheets_create	Returns spreadsheetId + URL. Empty workbook with one sheet ("Sheet1").
List sheet/tab names	sheets_get	Returns metadata only, not cell values.
Read cell values	sheets_values_get	A1 notation: Sheet1!A1:C10 (range), Sheet1!A:A (column), Sheet1 (all data).
Add rows of data	sheets_values_append	values is a 2D array, each inner array = one row. Use after sheets_create to populate.

Slides

Need	Tool	Notes
Create a new Google Slides presentation	slides_create	Returns presentationId + URL.
Read presentation structure	slides_get	Returns slides/layouts/text content.

OAuth (rare)

Only call when the existing token has expired (invalid_grant errors) or scopes have changed:

1. google_auth_start (no params) → returns an authUrl for the human to open.
2. Human signs in, copies the code= value from the localhost redirect URL bar.
3. google_auth_complete with that code → writes a fresh token file.

Drive query syntax

drive_files_list accepts a query parameter using Google's Drive query language. The most common patterns:

Goal	Query
What's inside a specific folder?	'<folder-id>' in parents (literal single quotes around the id)
Find a folder by name	mimeType='application/vnd.google-apps.folder' and name='eBay_Photos'
All sheets the user has	mimeType='application/vnd.google-apps.spreadsheet'
Anything shared with this account	sharedWithMe = true
Fuzzy name match	name contains 'invoice'
Combine multiple constraints	'<folder-id>' in parents and mimeType='image/png'

Folder traversal: first find the parent folder's id with name='X' and mimeType='application/vnd.google-apps.folder', then use that id in '<id>' in parents to list contents. To go one level deeper, repeat with the subfolder's id.

Multi-step recipes

"Send Jason an update with what's new in the sheet"

1. sheets_values_get for the relevant range — see what's there now.
2. Draft the update text based on the data.
3. gmail_message_send to Jason's address with that text.

"Make a new spreadsheet of this week's eBay orders"

1. sheets_create with a descriptive title — capture the spreadsheetId.
2. sheets_values_append with range: 'Sheet1!A1' and the headers as the first row + data rows.
3. Return the spreadsheet URL.

"Show me the photos in the DJI subfolder"

1. drive_files_list with query: "name='eBay_Photos' and mimeType='application/vnd.google-apps.folder'" to get the parent folder id.
2. drive_files_list with query: "'<parent-id>' in parents and mimeType='application/vnd.google-apps.folder' and name contains 'DJI'" to get the subfolder id.
3. drive_files_list with query: "'<subfolder-id>' in parents" to list the photos.

"Schedule a reminder and email me about it"

1. calendar_event_create with summary, start, end — capture the htmlLink.
2. gmail_message_send confirming the event, with the htmlLink in the body.

"Clean up the test artifacts"

1. drive_files_list with the test name pattern → get ids.
2. drive_file_trash for each id.
3. gmail_message_trash for any test emails.
4. calendar_event_delete for any test events.

Sharing safety

drive_permission_create actually shares real files with real people via email. Only call it when the user explicitly says "share X with [e-mail]" or similar. Do not volunteer to share files. Do not assume the user wants something shared just because they mentioned an email address in conversation. When in doubt, ask first.

OAuth and refresh tokens

The agent's authorization is backed by a refresh token stored at the configured tokenPath (default ~/.openclaw/secrets/gmail-token.json). If the OAuth app is in Testing status, that token expires after 7 days and you'll see invalid_grant errors — at that point, ask the human to re-run the OAuth dance (google_auth_start → open URL → paste code → google_auth_complete). If the OAuth app is Published (In production), tokens live indefinitely.

What this plugin does NOT do

• No local file editing. For local-filesystem edit, use the OpenClaw workspace edit tool. docs_append_text is for Google Docs only (referenced by documentId, not file path).
• No image generation / OCR. Different tool surface.
• No formal Google Workspace admin operations. This is a personal-account-style integration, not a Workspace Admin SDK wrapper.
• No Gmail attachments helper yet. Sending plain-text only in v0.x. (May land in a later minor release.)
• No Calendar resource booking, recurring-event helpers, or free/busy lookups beyond events.list. Use those endpoints directly if you need them; future minor releases may add convenience tools.