[龙虾进化论] OpenClaw 工作流真正的瓶颈:不是提示词,是数据接口 gws

AGENT-008 · Day 3 副文 A

写好了 SKILL.md，工作流设计完了，跑起来发现 AI 只会说「请把邮件内容粘贴给我」——

这时候你意识到问题所在：提示词写得再好，AI 没有办法自己去打开你的邮箱。

这就是工作流真正的瓶颈。不是提示词的质量，而是数据接口的有无。

gws（Google Workspace CLI）解决的就是这件事：它是一把钥匙，把 Gmail 和 Google Calendar 打开，让 Agent 可以直接读取，不需要你手动复制粘贴。

gws 能做什么，不能做什么

先把边界说清楚，别用到一半发现不支持。

能做的：

搜索 Gmail 邮件（支持 Gmail 原生搜索语法，非常强大）
读取邮件完整内容（包括正文、附件列表、发件人、时间）
查询 Google Calendar 事件（支持时间范围、日历筛选）
整理邮件：归档、加标签、标记已读
批量操作：+triage 命令可以对一批匹配邮件执行相同操作

不能做的：

发送邮件（需要额外的 OAuth 权限，默认不开启，也不建议开）
读取 Google Docs / Sheets / Drive（这是另一个工具链）
修改日历事件（只读，不能创建或删除）
访问 Gmail 草稿箱

速率限制：

Gmail API 有每分钟调用次数限制。在工作流里一次性搜索几百封邮件是没问题的，但如果你写了一个循环逐封读取，可能会触发限速。设计工作流时，尽量用 users.messages.list 批量获取 ID，再有选择地用 +read 读取关键邮件，而不是对每封邮件都完整读取。

两个核心命令，搞清楚再用

gws 的命令格式看起来有点奇怪，但有规律。

users.messages.list——返回匹配的邮件 ID 列表

gws gmail users.messages.list --params '{"userId": "me", "q": "newer_than:7d label:inbox"}'

这个命令只返回邮件 ID，不返回内容。适合先过滤再读取的场景——先找到符合条件的邮件，再决定读哪几封。

"q" 里面是 Gmail 搜索语法，支持的功能非常丰富：

newer_than:7d          → 最近 7 天from:boss@company.com  → 指定发件人subject:(发票 OR 收据)  → 主题包含关键词has:attachment         → 有附件label:unread           → 未读-label:promotions      → 排除促销邮件

这些语法可以任意组合，而且是 Gmail 原生的，搜索精度比你想象的高。

+read——读取单封邮件的完整内容

gws gmail +read --id MESSAGE_ID --headers

--headers 参数让它同时返回邮件头信息（发件人、收件人、时间、主题），没有这个参数只返回正文。

在工作流里通常这样配合用：先用 users.messages.list 拿到一批 ID，再用 +read 读取其中重要的几封。不要对每一封都 +read——速率限制和上下文 token 消耗都会让你后悔。

+triage——批量操作的唯一安全方式

gws gmail +triage --query "label:promotions older_than:30d" --archive

批量归档 30 天以前的促销邮件，一条命令。+triage 支持 --archive、--add-label、--remove-label 等操作。

为什么说它是「唯一安全方式」？因为它在操作前会展示匹配的邮件数量和预览，让你确认之后再执行，而不是直接修改。在工作流里用它做批量操作，远比直接调用 API 更可控。

日历命令：时间格式是最常见的坑

gws calendar events.list --params '{  "calendarId": "primary",  "timeMin": "2026-03-24T00:00:00Z",  "timeMax": "2026-03-31T00:00:00Z",  "singleEvents": true,  "orderBy": "startTime"}'

几个必须知道的细节：

timeMin 和 timeMax 必须是 RFC 3339 格式，带时区偏移。"2026-03-24" 这种写法会报错。在工作流里，让 Agent 先用 date 命令获取当前时间，再拼接成正确格式，比手写时间字符串可靠得多。

"singleEvents": true 这个参数很重要——如果不加，重复性事件（比如每周例会）只会返回一条记录，而不是展开成每个具体日期的事件。

"orderBy": "startTime" 只在 singleEvents: true 时有效，两者必须配合用。

web_fetch 和 web_search：不依赖 Google 的信息来源

gws 解决的是你自己邮件和日历的数据接入问题。但很多工作流还需要外部信息——新闻、RSS、公开 API。这时候 web_fetch 和 web_search 上场。

web_fetch

直接获取指定 URL 的内容，返回网页的文本或结构化数据。适合你知道数据在哪里的场景：

Hacker News 实时榜单：https://hacker-news.firebaseio.com/v0/topstories.jsonReddit 某个版块的帖子：https://reddit.com/r/programming.jsonRSS 订阅源：直接 fetch RSS feed 的 URL

注意：web_fetch 的结果会进入上下文，一次 fetch 一个完整页面可能消耗几千 token。在工作流里用它时，要在 Process 里明确写「只提取关键信息，不保留原始 HTML」，否则上下文会被撑满。

web_search

用 Brave Search 主动搜索，适合不知道具体 URL 的情报收集场景——比如「搜索过去 24 小时某个关键词的最新新闻」。

两者的核心区别：web_fetch 是精确抓取，web_search 是模糊检索。大多数工作流优先用 web_fetch，只有在 URL 不固定时才用 web_search。

国内场景的适配

gws 依赖 Google，国内直接用需要代理。如果你的工作环境没有稳定代理，有几个替代方向：

飞书：飞书开放平台的 API 完整度相当高，可以读取消息、日历、文档。OpenClaw 可以通过飞书机器人 webhook 接入，数据读取用飞书 API 替代 gws。

企业微信：适合有公司账号的场景。企业微信的开放 API 覆盖消息、日程、文件，接入方式和飞书类似。

邮件客户端导出：如果你用的是 163、QQ 邮箱等国内邮件服务，gws 不适用，但可以配置 IMAP 读取——OpenClaw 支持通过 IMAP 协议接入非 Google 邮箱，命令格式和 gws 不同，但工作流逻辑可以复用。

国内场景最大的现实是：大多数信息散落在微信对话和飞书文档里，而不是 Gmail。 这意味着数据接口问题比 Google 场景更麻烦，但也意味着谁先打通这条链路，谁的工作流价值就越高。

提示词模板（直接发给 Agent 执行）

帮我搜索最近 45 天内所有与 [关键词] 相关的邮件。条件：发件人包含 [域名或关键字]，时间范围：newer_than:45d对每封匹配邮件，提取：发件人、主题、日期、核心内容（不超过 100 字）以表格格式输出，按日期降序排列。最后统计：共找到多少封，其中需要我回复的有多少封。