Gmail、Drive、Docs、Calendar、Sheets——重度 Google Workspace 用户的日常几乎都泡在这套服务里。但想让命令行或 AI Agent 替你收发邮件、整理网盘、填表格,过去只有两条路:自己写 OAuth 胶水代码,或者在各种第三方封装里挑挑拣拣。Google 在 GitHub 上开源的 googleworkspace/cli 仓库给出了一个接近官方答案的方案:一个名为 gws 的命令行工具(CLI),口号是 "One CLI for all of Google Workspace — built for humans and AI agents",同时面向人类与 AI Agent 设计,并内置了一批可以一键装进 Agent 的 SKILL.md 技能文件。
本文按"概述 → 安装认证 → 命令设计 → 技能全景 → 装进 Agent → 注意事项"组织全文,读完大约十分钟,你可以据此判断它值不值得进入自己的日常工作流。
1、gws 概述
这个项目托管在 Google 官方的 googleworkspace GitHub 组织下,Apache-2.0 协议开源。它把 Workspace 全家桶装进一条 gws 命令:Drive、Gmail、Calendar 自不必说,Sheets、Docs、Slides、Tasks、People、Chat、Keep、Meet、Forms、Classroom 乃至 Apps Script、Admin 审计报表、Workspace 事件订阅和 Model Armor 内容安全过滤,都有对应子命令。
项目有两个鲜明定位。第一,它同时服务人类与 AI Agent 两类用户:工程师在终端里直接敲,Agent 在技能框架下调用,命令的 JSON 输出、参数自省、scope 收窄等设计都是冲着"机器可读、行为可控"去的。第二,技能是一等公民:仓库直接内置大量技能文件,并配有自动生成的索引文档,不依赖任何第三方整理。
安装渠道覆盖主流生态:
- npm:见下一节命令 (Node.js 18+)
- Homebrew:
brew install googleworkspace-cli - cargo、nix,以及 GitHub Releases 页面的预编译二进制
2、安装与首次认证
以 npm 为例,全局安装 @googleworkspace/cli 包后即可得到 gws 命令。首次使用需要两步认证,如下:
gws auth setup # 配置向导,需要机器上有 gcloud
gws auth login -s drive,gmail,sheets # 只授权这三个产品的 scope
第一行的向导带你走完 Google Cloud 项目相关配置;不想走向导,也可以手动创建 Desktop 类型的 OAuth 客户端,把 client_secret.json 放到 ~/.config/gws/ 目录下。第二行是常规 OAuth 登录,-s 参数值得专门一提:它能把授权范围收窄到当次任务真正用到的产品,只跑邮件、网盘、表格三件套时就别把日历权限也交出去。
给 Agent 或 CI 使用时,凭据可以脱离交互终端注入:gws 支持 GOOGLE_WORKSPACE_CLI_TOKEN 与 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE 两个环境变量,gws auth export 可导出凭据文件。涉及的 API 概念可对照 Google Workspace 开发者文档理解。
3、命令设计与日常用法
gws 的命令分两层。底层是动词直接映射 REST API 的原始层,核心参数有三个:--params 传查询参数、--json 传请求体、--dry-run 只打印不执行。先看原始层用法:
gws schema drive.files.list # 先查这个 API 支持哪些参数
gws drive files list --params '{"pageSize": 10}'
gws schema 是个聪明的设计:Agent 不用翻文档,先自省出参数结构再拼请求,能明显降低编造参数的概率。--dry-run 则允许打印将要发出的请求而不真正执行,对 Agent 场景是天然的保险丝。
上层是 + 助记符快捷命令,把高频操作压成一行:
gws gmail +send --to alice@example.com --subject "Hello" --body "正文"
gws calendar +agenda --timezone Asia/Shanghai
gws drive +upload ./report.pdf --name "Q1 Report"
gws workflow +standup-report
四条命令分别完成发邮件、查日程、传文件和生成站会摘要——最后一条是跨服务工作流,自动汇总日历与任务状态。作为合格的 Unix 工具,gws 的 JSON 输出可以直接接 jq 做管道处理:
gws drive files list --params '{"pageSize": 100}' --page-all \
| jq -r '.files[].name'
--page-all 自动翻页拉全量数据,配合 jq 一行列出网盘全部文件名,脚本化场景非常好用。
4、内置技能全景
仓库内的技能索引文档把内置技能分成四层,由 gws generate-skills 命令自动生成维护,加起来近百个条目:
| 类别 | 数量 | 定位 | 代表条目 |
|---|---|---|---|
| Services | 19 | 按产品划分的完整能力 | gws-gmail、gws-drive |
| Helpers | 24 | 单命令快捷方式 | gws-gmail-triage、gws-calendar-agenda |
| Personas | 10 | 按角色打包的技能束 | persona-it-admin、persona-researcher |
| Recipes | 41 | 多步骤操作配方 | recipe-block-focus-time、recipe-save-email-to-doc |
四层各有分工:Services 教 Agent 某个产品怎么操作,对应上一节的原始层命令;Helpers 是快捷命令的技能化版本;Personas 面向角色,行政助理、项目经理、IT 管理员等十种身份各有一捆预组合技能;Recipes 则是成品工作流,比如"屏蔽专注时间""把邮件存进 Docs""月底复制 Sheet"这类具体到能直接照抄的操作序列,官方宣传中常提及的 50+ 常用工作流大多出自这一层。
有意思的是数字口径:README 标语写 "40+ agent skills included",技能章节又写 100 多个 SKILL.md 加 50 个精选配方,而索引文档实际收录 94 个条目。三个数字互相对不上,说明项目处于快速迭代期,引用时以索引文档为准。
5、一条命令装进 Agent
这些技能不挑宿主,一条命令即可全量安装:
# 全量安装所有技能
npx skills add https://github.com/googleworkspace/cli
# 只安装网盘这一个技能
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
全量与按需安装都支持,后者对控制上下文体积很实用——近百个技能的描述全塞进 Agent 的技能目录,检索噪音不小。其他宿主也有对应路径:OpenClaw 用户把 skills/gws-* 目录软链或拷贝到 ~/.openclaw/skills/,Gemini CLI 用 gemini extensions install 一条命令接管,Claude Code 等主流 Agent 同样可以直接消费这些技能文件。
装好之后的工作方式是:你用自然语言下达任务,宿主 Agent 匹配并激活对应技能,把意图翻译成上一节那样的命令执行。技能文件里写清了参数结构、前置条件与错误处理,Agent 不必额外翻 API 文档。
6、注意事项与边界
上手之前,有几件事值得先想清楚。
仓库明确标注 "This is not an officially supported Google product"。它虽托管在 Google 官方组织下且开源,但享受的是社区项目待遇,生产环境接入要有自己的兜底预案。
第一是技能触发质量。第三方评测给出的技能自动激活率大约在 50%~70% 区间,社区里也不乏批评声音——技能数量上去之后,Agent 选错技能或干脆不触发的情况并不罕见。实践上的对策是显式点名:在工作流或提示词里直接引用 gws-gmail-send 这类技能名,而不是完全指望自动路由。
第二是权限面。给 Agent 装上这些技能,等于授予它替你发邮件、传文件、改日程的生产能力。建议组合使用三道闸门:登录时用 -s 收窄 scope,危险操作前用 --dry-run 预览,先在测试账号跑通再接主力账号。gws auth export 导出的凭据一旦落盘,务必按密钥标准保管。
第三是稳定性预期。数字口径不一、技能文档靠命令自动生成,都说明迭代节奏很快。团队采用的话,锁定版本、升级前 diff 技能清单,是更稳妥的做法。
7、总结
gws 把"操作 Google Workspace"统一成了一个对人类和 Agent 都友好的命令行入口:REST 映射加 schema 自省保证可编程性,+ 快捷命令压平高频操作,近百个内置技能又能一键装进 Claude Code、OpenClaw、Gemini CLI 等宿主。官方出身保证了 API 覆盖的完整度,但非官方支持的定位和五到七成的技能自动触发率也提醒我们:它适合当好用的工具箱,还不适合当无人值守的自动化系统。
对于重度 Workspace 用户,建议从 gws calendar +agenda、gws gmail +triage 这类只读命令起步,先把信息查询场景跑顺;对于构建 Agent 工作流的工程师,建议全量安装后以 Personas 和 Recipes 为骨架搭流程,并在每个写操作前保留 --dry-run 闸门——工具的边界意识,永远是自动化的第一行代码。

