gws 上手：把 Google Workspace API 变成可组合的命令（还能直接喂给 Agent）
做过 Google Workspace 自动化的人，大概率都熟悉这条路径：
-
先翻一圈 REST 文档 -
再写一坨 OAuth -
然后开始拼请求、处理分页、做重试 -
最后把返回值“揉”成脚本能消费的数据结构
googleworkspace/cli（命令：gws）给了一个更省事的解法：
-
用 一个 CLI 覆盖 Drive/Gmail/Calendar/Sheets…几乎所有 Workspace API -
默认输出 结构化 JSON（对脚本和 LLM 都友好） -
甚至可以直接 gws mcp启一个 MCP Server，把 Workspace 能力当成“工具”挂到你的 Agent 上
如果你希望把 Workspace 这类“企业胶水”做得更像工程化工具面，而不是一堆散脚本，gws 值得试。
先把它讲清楚：gws 是什么 / 不是什么
是什么：
-
One CLI for all of Google Workspace：Drive、Gmail、Calendar…以及更多 Workspace API。 -
动态命令面：它不会内置固定命令表，而是运行时读取 Google 的 Discovery Service，动态生成资源/方法树。 -
结构化输出：成功、错误、元数据都用 JSON，适合 jq、适合日志采集，更适合 Agent 做工具调用。
不是什么：
-
不是官方支持的 Google 产品（仓库明确写了）。 -
仍在快速迭代期，往 v1.0 走的过程中会有 breaking changes（适合你愿意跟着工具升级的场景）。
最短闭环：5 分钟确认它是不是你的菜
0）前置条件
-
Node.js 18+ -
一个 Google Cloud project（为了 OAuth） -
你的账号能访问目标 Google Workspace
1）安装
最省事：
npm install -g @googleworkspace/cli
npm 包自带预编译二进制，一般不需要 Rust。
（你也可以走 GitHub Releases / 从源码 cargo install / Nix flake，但先别折腾，先跑通再说。）
2）认证（本地交互最顺）
gws auth setup
gws auth login
gws auth setup 会引导你把 GCP 项目和 OAuth 跑起来；gws auth login 负责后续登录与 scope 选择。
3）验证：列 5 个 Drive 文件
gws drive files list --params '{"pageSize": 5}'
能拿到 JSON 输出，就说明你已经跑通闭环。
为什么我觉得它会火：不是“新”，是对 LLM/自动化太友好
1）你把 API 集成成本砍到“脚本级”
很多小需求（列文件、建表、发消息）不值得起一个 SDK 工程。
# 创建一个 Sheets
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
2）Schema 自省：让 Agent 能自己学会怎么调用
Agent 最怕“不知道 request/response 长什么样”。gws 直接给你查：
gws schema drive.files.list
3）MCP：把 Workspace 变成可插拔工具箱
如果你已经在用 Claude Desktop / Gemini CLI / VS Code 等 MCP 客户端，这个就很直观：
# 只暴露你要的服务，避免工具数爆炸
gws mcp -s drive,gmail,calendar
MCP 客户端里通常这样配：
{
"mcpServers": {
"gws": {
"command": "gws",
"args": ["mcp", "-s", "drive,gmail,calendar"]
}
}
}
一个非常实用的提醒：每个 service 可能带来 10–80 个工具，很多客户端有 50–100 的 tool limit，别一上来 -s all。
认证策略：本地、CI、服务器怎么选
你不用被 OAuth 绑死在“必须有浏览器”那种形态里。gws 支持几条常见路径：
1）本地交互（最推荐）
gws auth setup
gws auth login
它会把凭据加密存储（并使用系统 keyring 管钥匙），这是“既省事又相对安全”的默认路线。
2）Headless/CI：先在有浏览器的机器登录，再导出
# 在有浏览器的机器先登录
gws auth export --unmasked > credentials.json
# 在服务器/CI 上
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
3）你已经有 token：直接喂 access token
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
4）Service Account（server-to-server）
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list
认证优先级（很关键，排错先看这个）
从高到低：
-
GOOGLE_WORKSPACE_CLI_TOKEN -
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE -
gws auth login加密凭据 -
~/.config/gws/credentials.json
如果你觉得“明明设置了文件却没生效”，十有八九是上层优先级覆盖了。
工程化细节：它更像工具平台，不是玩具 CLI
我会重点看这些“能不能真上生产脚本”的点：
-
--dry-run：先预览请求（特别适合改动敏感资源的时候） -
自动分页： --page-all / --page-limit / --page-delay -
Multipart upload：例如 Drive 传文件
gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf
-
NDJSON：把分页结果当数据流处理
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'
高概率踩坑清单（建议你上来就看）
1）OAuth testing mode 的 scope 数量限制
如果你的 OAuth App 还在 testing mode，Google 对 consent 的 scope 数量有限制。
解决思路很简单：不要选“全家桶”，按服务过滤 scope：
gws auth login -s drive,gmail,sheets
2）登录 403 / “Access blocked”
常见原因是：你没把自己的账号加到 Test users。
处理方式：去 OAuth consent screen 里把账号加进去，再重试 gws auth login。
3）redirect_uri_mismatch
通常是 OAuth client 类型没选 Desktop app。删掉重建会快很多。
4）API 没开：accessNotConfigured
表现是 403，并提示某个 API 没启用。按提示去 GCP 控制台启用对应 API。
5）Sheets 的 !：bash history expansion
Sheet range 里有 !，在某些 shell 下会触发历史扩展。
稳妥做法：相关 JSON 都用单引号包起来。
gws sheets spreadsheets values get \
--params '{"spreadsheetId": "ID", "range": "Sheet1!A1:C10"}'
额外加分项：给 Agent 做“响应消毒”（防 prompt injection）
如果你会把 Gmail/Docs/Chat 的内容喂给 Agent，真正的问题不只是“拿到数据”，而是数据里可能带 prompt injection。
gws 提供了对接 Google Cloud Model Armor 的响应扫描：
gws gmail users messages get --params '...' \
--sanitize "projects/P/locations/L/templates/T"
你也可以用环境变量设默认策略（例如 warn 或 block）。
我会怎么把它接进 OpenClaw（很实用的一套接法）
你可以把 gws 当成 Workspace 的“统一工具面”，然后让不同 agent 各司其职：
-
research：查清楚要用哪个 API/method、参数怎么填（用 gws schema） -
coding：把调用固化成脚本/定时任务 -
ops：只管跑命令、拉 JSON、做数据流水线
如果你希望 OpenClaw 直接拥有 gws 的能力，仓库也给了现成的技能安装方式：
-
一次性装全套技能：
npx skills add https://github.com/googleworkspace/cli
-
或只装你用得上的（例如 Drive/Gmail）：
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail
（这类“按需装”的方式，反而更符合 Agent 的工具上限与权限最小化。）
一个很现实的选型标准
如果你对 Workspace 自动化的需求已经出现过两次以上（拉 Drive、发 Gmail、写 Calendar、批量操作 Sheets、发 Chat 消息），那 gws 值得你花 30 分钟跑完安装+认证。
跑完之后只问自己一句话：
我更想维护一堆零散脚本，还是更想维护一个“可组合、可被 Agent 调用的工具面”？
如果你偏后者，gws 大概率就是你要的那块“胶水底座”。
发表回复