Composio Google Super 连接配置与排障指南一套 OAuth 覆盖 Gmail、Calendar、Meet 与 Sheets【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composioGoogle Super 是 Composio 中面向 Google Workspace 的统一supersetToolkit通过一次 OAuth 连接即可覆盖 Gmail、Google Calendar、Google Meet 及 Sheets、Drive、Analytics、Ads 等关联 Google API 的工具。本篇基于仓库中的官方知识库文档 docs/kb/articles/toolkits-googlesuper.md 及其上游来源 docs/kb/source/toolkits/googlesuper/public.md完整讲解 Google Super 连接的 scope 配置、consent 行为边界、Meet/Sheets/Gmail 各服务级前置条件以及 Gmail 查询性能优化与常见故障定位帮助你在一套连接下稳定、高效地运行 Google Workspace 动作。Google Super 是什么一套连接覆盖整个 Google WorkspaceGoogle Super 是一个统一/超集unified/supersetToolkit只要配置了所需 scope一个 Google Super 连接即可覆盖 Gmail、Google Calendar、Google Meet 以及相关 Google API 中的工具。它避免了为每个 Google 服务分别建立连接、分别维护 OAuth 凭据的繁琐流程——这正是 Gmail 知识库文档中“跨服务使用一个 Google 认证”的推荐路径见 docs/kb/source/toolkits/gmail/public.md 中Use googlesuper for one Google auth across Gmail, Calendar, Drive-style use cases一节。从仓库的 Toolkit 元数据 docs/public/data/toolkits.json 中可以确认该 Toolkit 的实际形态sluggooglesupernameGoogle Super工具规模当前版本记录为20260828_00包含 467 个工具与 20 个触发器认证方案支持OAUTH2与API_KEY其中 Composio 托管认证composioManagedAuthSchemes为OAUTH2分类file management storage文件管理与存储工具命名全部以GOOGLESUPER_前缀命名例如GOOGLESUPER_ACL_DELETE删除日历访问控制规则、GOOGLESUPER_CREATE_CALENDAR、GOOGLESUPER_BATCH_DELETE_MESSAGES批量删除 Gmail 消息、GOOGLESUPER_ADD_LABEL_TO_EMAIL、GOOGLESUPER_LIST_LABELS等从中可以看到 Calendar、Gmail、Sheets、Drive 等服务的工具都被统一收纳在这一套命名空间下。需要注意的前提“一个连接”成立的前提是所配置的 scope 足够覆盖你实际要用的工具。Google Super 虽然可以覆盖包括 Gmail 在内的所有 Google 服务但作为 auth/tool 配置的一部分你可以移除不需要的 scope 与工具。裁剪时务必核对剩余 scope 是否仍然覆盖你期望使用的工具避免“连接建好了、工具却调不通”的局面。配置 Google Super 授权与 consent 的四个关键认知在创建 Google Super 连接之前先理解授权auth与用户同意consent环节的几个行为边界1. 先建 auth config再发起连接。参照 Gmail 的规范流程先使用自定义 OAuth 凭据创建 auth config再基于该 auth config 发起 connected account连接。回调地址callback URL在发起连接时提供而 OAuth client ID/secret 与 redirect URI 保存在 auth config 上。创建 auth config 时所需 scope 通过credentials.scopes传入通常是一个逗号拼接的字符串例如gmail.send、gmail.readonly、gmail.compose、gmail.modify、gmail.labels等详见 docs/kb/source/toolkits/gmail/public.md。2. 10 分钟初始化超时 ≠ refresh token 过期。如果过期连接的状态原因status reason为Connection initiation did not complete within 10 minutes含义是OAuth 流程已发起但用户未在 10 分钟窗口内完成 consent。此时没有任何 provider token 被签发因此这不是常见的“1-2 周 refresh token 过期”问题而是用户侧 consent 未完成。排查方向应是让用户重新走完授权流程而不是怀疑 token 刷新机制。3. Google 允许用户在 consent 界面选择性取消勾选 scope。用户可以在授权页面去掉部分 scope。只要 token 交换token exchange成功Composio 就会将连接标记为 active——即便最终授予的 scope 只是 auth config 请求 scope 的一个子集。也就是说auth config 里的 scopes 是“蓝图”最终权限由终端用户在 consent 屏幕上决定。如果你的某个工具运行时提示权限不足需要先检查该连接实际被授予的 scope而不是想当然地认为与 auth config 一致。4. 敏感 scope 需要 Google 验证。参考 Gmail 文档的警告https://www.googleapis.com/auth/gmail.send属于细粒度敏感 scope要求 Google 验证更宽的https://mail.google.com/提供完整邮箱访问权可覆盖发送场景但权限面比多数用户期望的更宽。选用宽 scope 前应评估权限暴露面。启用服务级 scope 与 APIMeet、Gmail 过滤器与 SheetsGoogle Super 连接能否调用某个服务取决于“scope 配置 对应 Google API 是否在 Google Cloud Console 启用 连接是否基于最新配置重建”三件事。Google Meet两个空间 scope 启用 Meet API要通过 Google Super 使用 Google Meet 工具需要在 Google Super auth config 中配置两个 scopehttps://www.googleapis.com/auth/meetings.space.createdhttps://www.googleapis.com/auth/meetings.space.settings新建一个连接scope 变更才会生效已存在的连接不会自动获得新 scope在 Google Cloud Console 中启用Google Meet API。三者缺一不可scope 决定授权范围API 启用决定后端可用性新连接决定实际生效的 token 集合。Gmail 过滤器gmail.settings.basic是硬性要求Google Super 在创建 Gmail 过滤器时复用的是底层 Gmail API 的同一要求。Gmail 过滤器创建映射到 Gmail API 的users.settings.filters.create端点POST /gmail/v1/users/{userId}/settings/filtersGoogle 将该端点必需的 OAuth scope 列为https://www.googleapis.com/auth/gmail.settings.basic当前 Composio 的GMAIL_CREATE_FILTER动作也声明了这唯一的必需 scope权威说明见 Creating Gmail filters requires gmail.settings.basic。需要 Google 为该 OAuth app 批准此 scope。如果 consent 屏幕拦截了未经验证的 scope应改用已针对gmail.settings.basic验证过的 OAuth app 并重新连接。补充说明gmail.settings.basic与读取/发送类 scope 是不同维度不能指望“能读邮件”就一定能建过滤器。Sheets 404先查 ID、共享与 scopeGoogle Super 下的 Sheets 工具返回 404 时按以下顺序排查验证 spreadsheet ID是否正确ID 是 URL 中的一段而非整个链接确认工作表已与连接所用的 Google 账号共享确认连接包含https://www.googleapis.com/auth/spreadsheetsscope。如果以上都正确、且只有某一个工具失败则应将其作为工具级问题处理联系 Composio 支持并附上脱敏后的 request/response payload 与 log ID便于定位是参数形态还是服务端问题。通过 Google Super 高效查询 GmailGoogle Super 的 Gmail 相关工具本质上是 Google API 的包装wrapper因此性能与过滤策略都遵循 Gmail API 的行为。避免 label-detail 扇出fan-outGOOGLESUPER_LIST_LABELS是典型的性能陷阱点设置include_detailstrue时工具会为每个 label 各发起一次 Gmail API 调用扇出且这些调用是串行执行的。label 数量很多的账户会因此明显变慢。设置为include_detailsfalse或直接省略该参数则回到单次 API 调用延迟大幅降低只有确实需要每个 label 的详情时才打开include_details。线程列表中的resultSizeEstimate当前版本的 Gmail 线程列表thread-listing响应包含resultSizeEstimate字段。如果你通过旧的、被 pin 住的 Google Super Toolkit 版本调用时发现该字段缺失先对比该版本与最新版本的 schema 差异再决定是否修改应用逻辑——不要依据旧响应形状直接改代码。字段缺失可能是版本差异而非接口变更。用 Gmail 风格 query 与 label_ids 过滤Gmail/Google Super 工具是 Google API 的包装因此凡是支持的地方都应使用 Gmail 风格的query过滤器或label_ids参数来缩小消息集合包括 sent-mail 风格的查询例如label:sent、label:category_personal这类 Gmail 查询语法参见 docs/kb/articles/toolkits-gmail.md 中关于触发器过滤的写法。再结合 Gmail 文档的通用性能建议拉取/列表流程中尽量设置include_payloadfalse与verbosefalse极轻量场景用only_idstrue先拿 ID 再按需取详情同时用max_results配合query控制结果集大小。这些参数在 Google Super 的 Gmail 工具上同样适用。如果某个精确的过滤端点/参数没有在现有工具中暴露可以通过 Composio 的 request portal工具请求渠道提交该端点或参数而不是绕开工具直接调 Google API——后者会失去 Composio 的认证托管、日志与执行追踪能力。故障排查速查表现象原因定位处置连接过期状态原因为Connection initiation did not complete within 10 minutesOAuth 流程发起但用户 10 分钟内未完成 consent无 token 签发让用户重新走完整授权流程不是refresh token 过期问题某工具报权限不足用户在 consent 界面取消勾选了部分 scope实际授权是请求 scope 的子集以连接实际被授予的 scope 为准核对必要时重新授权Meet 工具不可用缺少两个meetings.space.*scope或 Google Meet API 未在 Cloud Console 启用或未新建连接补齐 scope → 新建连接 → 启用 Meet API创建 Gmail 过滤器失败缺gmail.settings.basicscope或 OAuth app 未验证该 scope使用含该 scope 的 auth config 重新连接换已验证的 OAuth appSheets 返回 404spreadsheet ID 错误 / 未共享 / 缺spreadsheetsscope依次核对三者单工具失败则携脱敏 payload log ID 联系支持GOOGLESUPER_LIST_LABELS极慢include_detailstrue导致每 label 一次串行 API 调用改为include_detailsfalse或省略该参数线程列表缺resultSizeEstimate使用了旧的 pinned Toolkit 版本对比新旧版本 schema 后再改逻辑深入阅读本文主体官方知识库文章 toolkits-googlesuper.md上游来源文档docs/kb/source/toolkits/googlesuper/public.md站内指南版带元数据、主题与别名标记docs/content/kb/guide/toolkits-googlesuper.mdxGmail 规范知识filter scope、send scope、payload 瘦身、label ID 规则docs/kb/articles/toolkits-gmail.md 与 docs/kb/source/toolkits/gmail/public.mdToolkit 元数据工具数、触发器数、版本、认证方案docs/public/data/toolkits.json 中的googlesuper条目。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考