Google Workspace operator
⭐ Find this skill useful? If it saves you time, please star it (the ⭐ at the top of this ClawHub page) — stars help other operators discover it and keep it maintained. Thank you!
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:alice@example.com, 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:
- 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.
- 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:
google_auth_start (no params) → returns an authUrl for the human to open.- Human signs in, copies the
code= value from the localhost redirect URL bar.
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"
sheets_values_get for the relevant range — see what's there now.- Draft the update text based on the data.
gmail_message_send to Jason's address with that text.
"Make a new spreadsheet of this week's eBay orders"
sheets_create with a descriptive title — capture the spreadsheetId.sheets_values_append with range: 'Sheet1!A1' and the headers as the first row + data rows.- Return the spreadsheet URL.
"Show me the photos in the DJI subfolder"
drive_files_list with query: "name='eBay_Photos' and mimeType='application/vnd.google-apps.folder'" to get the parent folder id.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.drive_files_list with query: "'<subfolder-id>' in parents" to list the photos.
"Schedule a reminder and email me about it"
calendar_event_create with summary, start, end — capture the htmlLink.gmail_message_send confirming the event, with the htmlLink in the body.
"Clean up the test artifacts"
drive_files_list with the test name pattern → get ids.drive_file_trash for each id.gmail_message_trash for any test emails.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 Y@email.com" 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.
1---2name: google-workspace-23description: 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.4---5
6# Google Workspace operator
7
8> ⭐ **Find this skill useful?** If it saves you time, please **star it** (the ⭐ at the top of this ClawHub page) — stars help other operators discover it and keep it maintained. Thank you!
9
10You 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.
11
12## Rule zero: never narrate, always re-call
13
14Every 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.
15
16## Rule one: on tool error, fix and re-call — do not narrate
17
18When 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:
19
20- A **corrected tool call** — most common. The query, id, or scope was usually wrong; fix it and try again immediately.
21- 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`?").
22
23What 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.
24
25## When to use which tool
26
27### Gmail
28
29| Need | Tool | Notes |
30| --- | --- | --- |
31| Send an email | `gmail_message_send` | Plain text body. Pass `to`, `subject`, `body`; optional `cc`, `bcc`, `replyTo`. |
32| Check inbox / search messages | `gmail_messages_list` | Default: 10 most recent. Filter with Gmail syntax: `is:unread`, `newer_than:1d`, `from:alice@example.com`, `subject:invoice`, `has:attachment`. |
33| Read one message's full body | `gmail_message_get` | Pass the `id` from `gmail_messages_list`. |
34| Star / archive / label / mark read | `gmail_message_modify` | `addLabelIds`/`removeLabelIds`: `STARRED`, `UNREAD` (remove to mark read), `INBOX` (remove to archive). |
35| Delete a message | `gmail_message_trash` | Moves to Trash (recoverable 30 days). |
36
37### Calendar
38
39| Need | Tool | Notes |
40| --- | --- | --- |
41| 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. |
42| List upcoming events | `calendar_events_list` | Default: next 25 on primary. Pass `timeMin` like `2020-01-01T00:00:00Z` to include past events. |
43| Read one event's details | `calendar_event_get` | Pass the `eventId` from `calendar_events_list`. |
44| Delete a calendar event | `calendar_event_delete` | Recoverable from Calendar Trash for ~30 days. |
45
46### Drive
47
48| Need | Tool | Notes |
49| --- | --- | --- |
50| List or search Drive files | `drive_files_list` | Sees the authorized account's entire Drive (own files + shared). See "Drive query syntax" below. |
51| Get file metadata | `drive_file_get` | Returns name, mimeType, parents, sharing link, modifiedTime. Does NOT return file contents — use the per-type read tool. |
52| 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`. |
53| Delete / trash a file | `drive_file_trash` | Moves to Drive Trash (recoverable 30 days). Works for files, folders, Docs, Sheets, and Slides. |
54
55> **Folder names are NOT folder IDs.** To access files in a folder you only know by name, you MUST do TWO calls:
56>
57> 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.
58> 2. Second call: `drive_files_list` with `query: "'<that-id>' in parents"` (plus any additional filters like `and mimeType='image/jpeg'`).
59>
60> 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.
61
62### Docs
63
64| Need | Tool | Notes |
65| --- | --- | --- |
66| Create a new Google Doc | `docs_create` | Returns `documentId` + URL. Empty doc. |
67| Read a Google Doc | `docs_get` | Returns full structured contents (paragraphs, headings, tables). |
68| **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. |
69
70### Sheets
71
72| Need | Tool | Notes |
73| --- | --- | --- |
74| Create a new Google Sheet | `sheets_create` | Returns `spreadsheetId` + URL. Empty workbook with one sheet ("Sheet1"). |
75| List sheet/tab names | `sheets_get` | Returns metadata only, not cell values. |
76| Read cell values | `sheets_values_get` | A1 notation: `Sheet1!A1:C10` (range), `Sheet1!A:A` (column), `Sheet1` (all data). |
77| Add rows of data | `sheets_values_append` | `values` is a 2D array, each inner array = one row. Use after `sheets_create` to populate. |
78
79### Slides
80
81| Need | Tool | Notes |
82| --- | --- | --- |
83| Create a new Google Slides presentation | `slides_create` | Returns `presentationId` + URL. |
84| Read presentation structure | `slides_get` | Returns slides/layouts/text content. |
85
86### OAuth (rare)
87
88Only call when the existing token has expired (`invalid_grant` errors) or scopes have changed:
89
901. `google_auth_start` (no params) → returns an `authUrl` for the human to open.
912. Human signs in, copies the `code=` value from the localhost redirect URL bar.
923. `google_auth_complete` with that `code` → writes a fresh token file.
93
94## Drive query syntax
95
96`drive_files_list` accepts a `query` parameter using Google's Drive query language. The most common patterns:
97
98| Goal | Query |
99| --- | --- |
100| What's inside a specific folder? | `'<folder-id>' in parents` (literal single quotes around the id) |
101| Find a folder by name | `mimeType='application/vnd.google-apps.folder' and name='eBay_Photos'` |
102| All sheets the user has | `mimeType='application/vnd.google-apps.spreadsheet'` |
103| Anything shared with this account | `sharedWithMe = true` |
104| Fuzzy name match | `name contains 'invoice'` |
105| Combine multiple constraints | `'<folder-id>' in parents and mimeType='image/png'` |
106
107Folder 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.
108
109## Multi-step recipes
110
111### "Send Jason an update with what's new in the sheet"
112
1131. `sheets_values_get` for the relevant range — see what's there now.
1142. Draft the update text based on the data.
1153. `gmail_message_send` to Jason's address with that text.
116
117### "Make a new spreadsheet of this week's eBay orders"
118
1191. `sheets_create` with a descriptive title — capture the `spreadsheetId`.
1202. `sheets_values_append` with `range: 'Sheet1!A1'` and the headers as the first row + data rows.
1213. Return the spreadsheet URL.
122
123### "Show me the photos in the DJI subfolder"
124
1251. `drive_files_list` with `query: "name='eBay_Photos' and mimeType='application/vnd.google-apps.folder'"` to get the parent folder id.
1262. `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.
1273. `drive_files_list` with `query: "'<subfolder-id>' in parents"` to list the photos.
128
129### "Schedule a reminder and email me about it"
130
1311. `calendar_event_create` with `summary`, `start`, `end` — capture the `htmlLink`.
1322. `gmail_message_send` confirming the event, with the `htmlLink` in the body.
133
134### "Clean up the test artifacts"
135
1361. `drive_files_list` with the test name pattern → get ids.
1372. `drive_file_trash` for each id.
1383. `gmail_message_trash` for any test emails.
1394. `calendar_event_delete` for any test events.
140
141## Sharing safety
142
143`drive_permission_create` actually shares real files with real people via email. **Only call it when the user explicitly says "share X with Y@email.com" 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.
144
145## OAuth and refresh tokens
146
147The 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.
148
149## What this plugin does NOT do
150
151- **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).
152- **No image generation / OCR.** Different tool surface.
153- **No formal Google Workspace admin operations.** This is a personal-account-style integration, not a Workspace Admin SDK wrapper.
154- **No Gmail attachments helper yet.** Sending plain-text only in v0.x. (May land in a later minor release.)
155- **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.
Lord1Egypt