用 Gws CLI控制谷歌邮箱、日程...

与企业工具交互最难的部分一直是管道工程、OAuth流程、分页。

admin

• 12 min read
用 Gws CLI控制谷歌邮箱、日程...
微信 ezpoda免费咨询：AI编程 | AI模型微调| AI私有化部署 | Tripo 3D | Meshy AI

我肯定花了整个周末写自定义Google API集成，做的事情无非就是列出Drive文件夹中的文件或发送电子邮件——十二个不同的包装库，每个都有自己对错误处理和重试逻辑的看法！

这正是Zapier、Make和n8n围绕其建立整个业务的确切痛点：将丑陋的集成管道隐藏在更好的界面后面。

但如果你是一个开发者，这种便利仍然像是你和API之间的另一层抽象。

所以Google没有再添加一层抽象，而是最近发布了gws，它在运行时读取Google的实时API目录，并动态构建每个命令、每个标志、每个参数。

这意味着当Google添加新的Sheets端点时，你的CLI将支持它，无需等待维护者跟进。

它还附带核心Google Workspace API技能、助手、角色和食谱，这些让Zapier和n8n这样的工具看起来非常手动。

这就是我们讨论它的原因。

让我们看看这对于在Google Workspace之上构建AI代理的人意味着什么，以及我认为真正的权衡在哪里，因为它们确实存在。

1、gws到底是什么

本质上，gws是一个单一的二进制文件（用Rust编写，通过npm、Cargo或预构建二进制分发），将整个Google Workspace API包装在可组合的终端命令后面。

npm install -g @googleworkspace/cli

这一安装让你可以编程访问Gmail、Drive、Calendar、Sheets、Docs、Chat、Admin、Meet、Forms、Keep、Classroom、Tasks，基本上每个有公共API的Google Workspace服务。

使gws与所有其他Google API包装器根本不同的是动态命令生成架构。

2、两阶段解析策略

当你运行这样的命令时：

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

CLI使用两阶段解析策略：

  1. 阶段1：服务识别：读取argv[1]（例如drive）以识别目标服务
  2. 阶段2：动态命令构建：从Google获取该服务的Discovery Document（缓存24小时），然后从文档的资源和方法构建clap::Command树
  3. 重新解析剩余参数以对抗这个动态生成的命令树
  4. 认证，构建HTTP请求，执行

Discovery Service是Google自己的机器可读目录，包含所有服务中每个API方法、参数、模式和OAuth范围。

这正是Google用来生成自己客户端库的相同元数据来源。gws只是在运行时直接读取它并将其转换为CLI命令。

这意味着这个工具 literally 不可能过时，因为没有跟踪API变化的维护负担。

3、输出是什么样的

每个响应——成功、错误、下载元数据——都以结构化JSON返回，这是主要输出格式，设计为可以直接管道传输到jq、由脚本解析或由LLM消费。

# 将分页结果流式传输为NDJSON
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'
  
# 在执行前预览请求（dry-run）
gws chat spaces messages create \
--params '{"parent": "spaces/xyz"}' \
--json '{"text": "Deploy complete."}' \
--dry-run
  
# 内省任何方法的请求/响应模式
gws schema drive.files.list

--dry-run标志是我希望在我使用过的每个API工具中早点知道的功能。能够在触发前预览确切的HTTP请求正是你想要的安全网，当代理在自动发送电子邮件或创建日历事件时。

4、这如何改变代理开发

如果你一直在构建需要与Google Workspace交互的AI代理，现状确实需要：

  • 使用正确的范围设置OAuth2凭证
  • 为你需要的每个API端点编写包装函数
  • 手动处理分页（Google的分页模型因服务而异）
  • 解析不同API的不同响应形状
  • 管理令牌刷新、凭证存储、错误处理
  • 针对实时API测试所有这些，因为Google的Workspace API没有很好的沙盒环境

对于你希望代理访问的每个新服务，在代理甚至可以进行第一次调用之前，你正在寻找数小时的样板代码。

但使用gws，你可以每个动作运行一个命令

# 发送电子邮件
gws gmail +send --to alice@company.com --subject 'Q2 Report Ready' \
--body 'Hey Alice, the Q2 report is ready for review.'
  
# 上传文件到Drive
gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf
  
# 创建电子表格
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
  
# 搜索来自特定人员的未读邮件
gws gmail users.messages list \
--params '{"userId": "me", "q": "from:boss@company.com is:unread"}'

当你尝试某些东西的成本是一个终端命令而不是200行Python脚本时，你会更愿意尝试代理到Workspace的集成。

5、MCP服务器

内置的MCP服务器模式在本文撰写后已被删除。由于该决定可能仍会被重新考虑，我们保留了此部分以供参考。如果您需要临时替代方案，可以考虑Google Workspace MCP

运行：

gws mcp -s drive,gmail,calendar

启动一个通过stdio的MCP服务器，将那些Workspace API作为结构化工具公开。

将其插入Claude Desktop、VS Code或任何MCP兼容客户端，LLM现在可以原生管理你的Workspace。

对于我自己的工作，我发现最有用的模式是：

  1. 在我的本地机器上认证一次：gws auth setup
  2. 启动我需要的服务的MCP服务器
  3. 让LLM通过结构化工具调用处理电子邮件分类、日程安排或文档管理

运行gemini extensions install https://github.com/googleworkspace/cli也让你的本地Gemini代理直接访问所有gws命令，继承你现有的凭证。

6、100+代理技能：这实际上意味着什么

Preview image

仓库附带超过100个代理技能，这些是SKILL.md文件，作为AI代理的结构化指令。

它们涵盖每个支持的API，加上常见工作流的更高级别助手，以及为Gmail、Docs、Calendar和Sheets精选的50个食谱。

你可以通过以下方式安装它们：

# 一次安装所有技能
npx skills add https://github.com/googleworkspace/cli
  
# 或者只选择你需要的
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

对于OpenClaw用户，你可以直接符号链接它们：

ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

gws-shared技能包含一个install块，这样OpenClaw如果gws不在PATH上，会自动通过npm安装CLI。（我对这种安装时体验的关注表示真诚的欣赏）。

7、Model Armor：没人谈论的安全故事

每个人都关注便利性和星标数，但几乎没有人讨论Model Armor集成。

当你的AI代理通过gws读取电子邮件时，电子邮件内容成为代理上下文的一部分，这是一个提示注入表面。

有人可能在电子邮件正文或共享文档中嵌入恶意指令，代理可能会遵循它们。

gws通过--sanitize标志解决此问题，该标志在API响应到达你的代理之前将其路由通过Google Cloud Model Armor：

gws gmail users messages get --params '...' \
--sanitize "projects/P/locations/L/templates/T"

Model Armor检查提示注入、越狱尝试、敏感数据泄露和恶意URL。

你可以将其设置为warn模式（记录并继续）或block模式（完全拒绝响应）。

你可以通过环境变量配置默认模板：

export GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE="projects/P/locations/L/templates/T"
export GOOGLE_WORKSPACE_CLI_SANITIZE_MODE="block"

Model Armor需要自己的Google Cloud设置，规模化时不是免费的。

但事实是响应清理是CLI的一等功能，而不是第三方附加组件，这显示了Google认为代理工作流的安全边界应该在哪里。

8、认证：仍然可能烧到你的部分

gws继承了Google OAuth生态系统所有传统复杂性，这就是认证故事。

快乐路径是如果你安装了gcloud，gws auth setup会引导你创建Cloud项目、启用API并登录。凭证在静态时加密（AES-256-GCM），密钥存储在你的OS密钥链中。这对个人使用效果很好。

企业痛苦是如果你在有托管Google Workspace的公司，你需要带有OAuth凭证的GCP项目，创建GCP项目只是为了获取认证令牌真的没有必要。

未验证的OAuth应用（测试模式）限制在约25个范围。推荐的范围预设包括85+个范围，未验证的应用将失败。

你需要选择单独的服务：

gws auth login -s drive,gmail,sheets

无头/CI是你在有浏览器的机器上完成交互式认证，然后导出凭证：

gws auth export --unmasked > credentials.json

# 在无头机器上：
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json

认证优先级

如果你配置了多种认证方法且某些功能不工作，首先检查此优先级表。

9、这对"工作流自动化"市场意味着什么

有一类SaaS工具，例如Zapier、Make、n8n、Bardeen和许多其他工具，主要收取每月20-99美元的费用， bridging"用户想在Gmail/Drive/Calendar中做X"和"这是做X的API调用"。

gws不会杀死这些工具，但对于开发者和AI代理，现在一个免费的npm install justifications每月支付订阅费的价值主张变得更加困难。

我发现更有趣的比较是gws与gcloud：

gws不是gcloud的替代品。它是一个特定于Workspace的工具，恰好非常适合AI代理集成，而gcloud从未试图成为这样的工具。

10、实用用例

从这里开始的一些实用用例。

代理电子邮件分类

# 获取最近5封未读邮件，为代理消费进行摘要
gws gmail +triage --max 5 --query 'is:unread'

+triage助手是一个更高级别的技能，返回结构化摘要而不是原始消息数据。这非常有帮助，特别是当我正在处理需要决定是否将电子邮件呈现给人类或自主处理的代理时。

文档管理管道

# 上传生成的报告
gws drive files create --json '{"name": "weekly-report.pdf"}' --upload ./report.pdf
  
# 与团队共享
gws drive permissions create \
--params '{"fileId": "FILE_ID"}' \
--json '{"role": "reader", "type": "user", "emailAddress": "team@company.com"}'

电子表格数据操作

# 读取范围
gws sheets spreadsheets values get \
--params '{"spreadsheetId": "ID", "range": "Sheet1!A1:C10"}'
  
# 追加行
gws sheets spreadsheets values append \
--params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
--json '{"values": [["Name", "Score"], ["Alice", 95]]}'

快速说明：Sheets范围使用!，bash将其解释为历史扩展。始终用单引号包装值。

11、失败模式

  • 登录时"访问被阻止"或403：你的OAuth应用处于测试模式，你的账户未列为测试用户。修复：在OAuth同意屏幕的测试用户下添加自己
  • "Google尚未验证此应用"：测试模式下预期出现。点击高级，然后继续。个人使用安全
  • 范围太多错误：未验证应用上限约25个范围。使用-s drive,gmail,calendar而不是推荐的预设
  • redirect_uri_mismatch：OAuth客户端未创建为桌面应用类型。删除它，重新创建为桌面应用，下载新的JSON
  • API未启用：你将看到带有accessNotConfigured的403。CLI有帮助地打印启用URL，点击它，启用API，等待10秒，重试
  • Discovery Document缓存：缓存24小时。如果在新API发布后需要强制刷新，我怀疑清除~/.config/gws/缓存可以工作，但这需要更多测试

12、结束语

通过在运行时读取Discovery Service而不是发布静态命令定义，Google以第三方库无法匹配的方式解决了API包装器维护问题。

他们拥有既是API提供者又是CLI构建者的优势。

但这里仍然需要改进：

  • 企业环境的认证设置很陡，GCP项目要求是真正的障碍
  • "非官方支持"对生产部署是有意义的风险
  • v1.0之前，预期会有重大更改，不适合稳定性关键的使用场景
  • Model Armor需要单独的Google Cloud设置，有自己的成本影响

原文链接: Google Workspace CLI: Agent Native Alternative to Zapier, n8n and Make

汇智网翻译整理，收费标准标明出处