Google Workspace Skill

Operate all Google Workspace services through the gws CLI from OpenClaw.

Prerequisites

- Node.js 18+
A Google Cloud project with OAuth credentials
INLINECODE1 CLI installed: INLINECODE2

Authentication

First-Time Setup & Authentication Workflow (For the Agent)

When a user wants to start using this skill or if credentials are missing, you (the AI agent) MUST follow this specific authentication workflow:

1. Ask for client_secret.json: Prompt the user to provide their Google Cloud OAuth client_secret.json. They can either upload the file or paste its contents into the chat. Once they do, save it as credentials.json in the workspace.
Explain the Flow: Once you have the file, explain to the user exactly how the auth will work:

> "I have saved your credentials. I am now going to start the authentication process. I'll provide you with a Google login link. You'll need to click it, authorize your account, and then your browser will redirect to a blank http://localhost... page. Copy that full localhost URL and paste it back to me here!"

3. Run Authentication: Run gws auth login in the background (using your exec tool). Extract the generated Google OAuth URL from the output and send it to the user.
Complete Handshake: When the user replies with the http://localhost... callback URL, use curl to fetch that exact URL. This completes the local webserver handshake for gws. Confirm successful authentication with the user.

Alternative: First-time setup (machine with browser)

CODEBLOCK0

Alternative: Headless server (no browser) - PREFERRED MANUAL METHOD

Complete auth on a machine with a browser, then export:

CODEBLOCK1

Security notes:

- Set file permissions: INLINECODE12
Do not commit credential files to git — add credentials.json to your INLINECODE14
For production environments, prefer using a service account instead of user credentials

On the headless server:

CODEBLOCK2

Service account

CODEBLOCK3

Pre-obtained token

CODEBLOCK4

Priority: Token env > Credentials file env > gws auth login store > plaintext file.

Command Pattern

CODEBLOCK5

All responses are structured JSON. Use jq for extraction.

Global Flags

Flag	Purpose
INLINECODE17	Preview request without executing
INLINECODE18

Discover commands

CODEBLOCK6

Common Operations

Drive

CODEBLOCK7

Gmail

CODEBLOCK8

Calendar

CODEBLOCK9

Sheets

CODEBLOCK10

Docs

CODEBLOCK11

Chat

CODEBLOCK12

Tasks

CODEBLOCK13

Admin (Directory)

CODEBLOCK14

Workflow Patterns

Pipeline: Find → Process → Act

CODEBLOCK15

Dry-run first

Always use --dry-run before destructive operations:

CODEBLOCK16

Tips

- Use gws schema <method> to discover exact parameter names and types.
All commands accept --params for URL/query parameters and --json for request body.
Pipe through jq for field extraction in agent pipelines.
Use --page-all for full result sets with automatic pagination.
Credentials are encrypted at rest (AES-256-GCM) with OS keyring.

Recipes

For 50+ ready-made workflow recipes (label & archive emails, organize Drive folders, schedule meetings, etc.), see the official recipe library.

Disclaimer

The gws CLI is not an officially supported Google product. It is a community/experimental tool. Use at your own discretion, and refer to the upstream repository for license and support details.

Troubleshooting

Issue	Fix
INLINECODE28	INLINECODE29
Auth fails / scope error

Google Workspace 技能

通过 OpenClaw 的 gws CLI 操作所有 Google Workspace 服务。

前提条件

- Node.js 18+
具有 OAuth 凭据的 Google Cloud 项目
已安装 gws CLI：npm install -g @googleworkspace/cli

身份验证

首次设置与身份验证工作流程（供代理使用）

当用户想要开始使用此技能或凭据缺失时，你（AI 代理）必须遵循此特定身份验证工作流程：

1. 请求 clientsecret.json： 提示用户提供其 Google Cloud OAuth clientsecret.json。他们可以上传文件或将内容粘贴到聊天中。完成后，将其保存为工作区中的 credentials.json。
解释流程： 获取文件后，向用户准确解释身份验证的工作方式：

> 我已保存您的凭据。现在将启动身份验证过程。我将为您提供一个 Google 登录链接。您需要点击它，授权您的帐户，然后您的浏览器将重定向到一个空白的 http://localhost... 页面。复制完整的 localhost URL 并粘贴回给我！

3. 运行身份验证： 在后台运行 gws auth login（使用您的 exec 工具）。从输出中提取生成的 Google OAuth URL 并发送给用户。
完成握手： 当用户回复 http://localhost... 回调 URL 时，使用 curl 获取该确切 URL。这将完成 gws 的本地 Web 服务器握手。向用户确认身份验证成功。

替代方案：首次设置（带浏览器的机器）

bash
gws auth setup # 创建 GCP 项目，启用 API，登录
gws auth login -s drive,gmail,sheets,calendar # 选择所需服务

替代方案：无头服务器（无浏览器）- 推荐的手动方法

在带浏览器的机器上完成身份验证，然后导出：

bash
gws auth export --unmasked > credentials.json

安全说明：

- 设置文件权限：chmod 600 credentials.json
不要将凭据文件提交到 git — 将 credentials.json 添加到您的 .gitignore
对于生产环境，建议使用服务帐户而不是用户凭据

在无头服务器上：

bash
export GOOGLEWORKSPACECLICREDENTIALSFILE=/path/to/credentials.json

服务帐户

bash
export GOOGLEWORKSPACECLICREDENTIALSFILE=/path/to/service-account.json

预先获取的令牌

bash
export GOOGLEWORKSPACECLI_TOKEN=$(gcloud auth print-access-token)

优先级： 令牌环境变量 > 凭据文件环境变量 > gws auth login 存储 > 明文文件。

命令模式

bash
gws <服务> <资源> <方法> [--params {}] [--json {}] [标志]

所有响应均为结构化 JSON。使用 jq 进行提取。

全局标志

标志	用途
--dry-run	预览请求而不执行
--page-all

发现命令

bash
gws --help # 列出所有服务
gws drive --help # 列出服务中的资源
gws drive files --help # 列出资源上的方法
gws schema drive.files.list # 完整的请求/响应模式

常见操作

Drive

bash

列出最近的文件

gws drive files list --params {pageSize: 10}

搜索文件

gws drive files list --params {q: name contains \report\, pageSize: 20}

上传文件

gws drive +upload ./report.pdf

下载文件

gws drive files get --params {fileId: FILE_ID, alt: media} > output.pdf

创建文件夹

gws drive files create --json {name: Project, mimeType: application/vnd.google-apps.folder}

共享文件

gws drive permissions create \ --params {fileId: FILE_ID} \ --json {role: reader, type: user, emailAddress: user@example.com}

列出所有页面

gws drive files list --params {pageSize: 100} --page-all | jq -r .files[].name

Gmail

bash

列出收件箱邮件

gws gmail users-messages list --params {userId: me, maxResults: 10}

阅读邮件

gws gmail users-messages get --params {userId: me, id: MSG_ID}

发送邮件

gws gmail users-messages send \ --params {userId: me} \ --json {raw: BASE64ENCODEDEMAIL}

搜索邮件

gws gmail users-messages list --params {userId: me, q: from:boss@company.com is:unread}

列出标签

gws gmail users-labels list --params {userId: me}

创建过滤器

gws gmail users-settings-filters create \ --params {userId: me} \ --json {criteria: {from: noreply@example.com}, action: {addLabelIds: [LABEL_ID], removeLabelIds: [INBOX]}}

Calendar

bash

列出即将到来的事件

gws calendar events list --params {calendarId: primary, timeMin: 2026-01-01T00:00:00Z, maxResults: 10, orderBy: startTime, singleEvents: true}

创建事件

gws calendar events insert \ --params {calendarId: primary} \ --json {summary: 团队同步, start: {dateTime: 2026-03-07T10:00:00+08:00}, end: {dateTime: 2026-03-07T11:00:00+08:00}, attendees: [{email: user@example.com}]}

删除事件

gws calendar events delete --params {calendarId: primary, eventId: EVENT_ID}

查找空闲/忙碌时段

gws calendar freebusy query \ --json {timeMin: 2026-03-07T00:00:00Z, timeMax: 2026-03-07T23:59:59Z, items: [{id: user@example.com}]}

Sheets

bash

创建电子表格

gws sheets spreadsheets create --json {properties: {title: Q1 预算}}

读取单元格值

gws sheets spreadsheets-values get --params {spreadsheetId: SHEET_ID, range: Sheet1!A1:D10}

写入值

gws sheets spreadsheets-values update \ --params {spreadsheetId: SHEETID, range: Sheet1!A1, valueInputOption: USERENTERED} \ --json {values: [[名称, 金额], [租金, 2000]]}

追加行

gws sheets spreadsheets-values append \ --params {spreadsheetId: SHEETID, range: Sheet1!A1, valueInputOption: USERENTERED} \ --json {values: [[新项目, 500]]}

Docs

bash

创建文档

gws docs documents create --json {title: 会议记录}

获取文档内容

gws docs documents get --params {documentId: DOC_ID}

插入文本（batchUpdate）

gws docs documents batchUpdate \ --params {documentId: DOC_ID} \ --json {requests: [{insertText: {location: {index: 1}, text: Hello World\n}}]}

Chat

bash

列出空间

gws chat spaces list

发送消息

gws chat spaces messages create \ --params {parent: spaces/SPACE_ID} \ --json {text: 部署完成 ✅}

Tasks

bash

google-workspace谷歌工作空间