SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场tapauth

tapauth

智能体与模型

查看项目

更新于 10-16 04:50

技能介绍

TapAuth 让 AI 智能体能够获取用户账号的 OAuth 令牌，而无需直接接触用户凭据：用户在浏览器中授权，智能体获得一个带作用域的令牌。该技能适用于需要访问 Google Calendar、Gmail、GitHub、Slack、Linear、Notion、Vercel、Sentry、Asana、Discord 或 Apify 等账号的场景。

一、用途 为智能体提供对用户第三方账号的委托访问能力，在用户显式批准后取得 OAuth bearer token，用于代为调用相应服务商 API。

二、主要能力与工作机制 该技能包含位于 scripts/tapauth.sh 的 CLI 脚本，具有两种模式：

  1. 默认模式：运行 scripts/tapauth.sh <provider> [scopes] 会创建一个 grant，并把审批 URL 打印到 stdout（例如：Approve access: https://tapauth.ai/approve/abc123），随后立即退出——它不会阻塞或轮询。需要把这个 URL 展示给用户，用户点击、登录并批准。
  2. --token 模式：以 $(scripts/tapauth.sh --token <provider> [scopes]) 的形式内联使用，会自动每 5 秒轮询一次、最长 10 分钟，直到用户批准后把 bearer token 输出到 stdout，可直接喂给 curl。

三、使用方式 首次在某个服务商上使用时，必须按以下流程操作：

  1. 先运行默认模式 scripts/tapauth.sh <provider> [scopes] 创建 grant，打印审批 URL 后立即退出。
  2. 把审批 URL 展示给用户。
  3. 紧接着运行 curl，并在其中内联使用 $(scripts/tapauth.sh --token <provider> [scopes])，它会自动轮询直到用户批准并返回令牌。不要等用户确认已批准再运行。

始终将 --token 与 $(...) 内联搭配使用，不要把令牌存入 shell 变量（如 TOKEN=$(...)），内联方式更简单也更安全，可让令牌不进入 shell 历史和进程列表。

首次运行不要直接跳到 $(...) 里的 --token，否则会在审批 URL 被隐藏在工具输出中时阻塞轮询长达 10 分钟。

多作用域时用逗号分隔，例如：scripts/tapauth.sh google calendar.events,spreadsheets。

后续运行令牌会被缓存，两种模式都会检测到：默认模式打印 "Already authorized"，--token 会即时返回缓存令牌。多个请求重复使用内联 $(...) 模式即可，令牌已缓存，每次调用即时返回。

带请求体的调用示例： curl -X POST -H "Authorization: Bearer $(scripts/tapauth.sh --token <provider> <scopes>)" -H "Content-Type: application/json" -d '{"key": "value"}' <api-url>

四、支持的服务商与作用域 脚本按服务商指定作用域。部分服务商需要作用域（Google、GitHub、Linear），部分不需要（Vercel、Notion、Slack）。具体可用作用域值需查阅对应参考文件（如 references/google.md）。

  • Google Calendar（读）：scripts/tapauth.sh google calendar.readonly
  • Google Calendar（读写）：scripts/tapauth.sh google calendar.events
  • Google Drive：scripts/tapauth.sh google drive.readonly
  • Google Sheets：scripts/tapauth.sh google spreadsheets.readonly
  • Google Docs：scripts/tapauth.sh google documents.readonly
  • GitHub：scripts/tapauth.sh github repo（repo、read:user 等）
  • Vercel：scripts/tapauth.sh vercel（集成级，无按 grant 作用域）
  • Notion：scripts/tapauth.sh notion（集成级，无按 grant 作用域）
  • Slack：scripts/tapauth.sh slack users:read（users:read、channels:read 等）
  • Asana：scripts/tapauth.sh asana tasks:read（tasks:read、projects:read 等）
  • Linear：scripts/tapauth.sh linear read（read、write、issues:create）
  • Sentry：scripts/tapauth.sh sentry project:read（org:read、project:read 等）
  • Discord：scripts/tapauth.sh discord identify（identify、guilds 等）
  • Apify：scripts/tapauth.sh apify full_api_access（仅 full_api_access）
  • Gmail 使用 google provider 配合 gmail 作用域

google provider 覆盖所有 Google 服务（Drive、Calendar、Sheets、Docs、Gmail、Contacts）。可通过 curl -s https://tapauth.ai/api/v1/providers 以编程方式列出所有服务商和有效作用域。

五、配置 环境变量：

  • TAPAUTH_BASE_URL：覆盖基础 URL（默认 https://tapauth.ai）
  • TAPAUTH_HOME：覆盖缓存目录（优先级最高）
  • CLAUDE_PLUGIN_DATA：由 Claude Code 提供的稳定插件目录（若设置则自动使用） 缓存目录优先级：TAPAUTH_HOME > CLAUDE_PLUGIN_DATA > ./.tapauth。令牌存储在缓存目录（目录权限 700，文件权限 600），每个 provider+scope 组合有独立缓存文件，包含令牌、过期时间、grant ID 和 grant secret 以支持自动刷新。

六、适用场景 适合智能体需要代表用户调用上述第三方服务 API 的任务，例如列出或创建 Google Calendar 事件、读取或创建 GitHub issue、发送 Gmail 邮件、查询 Linear issue、搜索 Notion、列出 Google Drive 文件、列出 Vercel 部署等。

七、限制与注意事项

  • 无需 API key 或凭据，TapAuth 零配置；不要寻找 API key、client secret 或环境变量。
  • 始终使用技能自带脚本，不要从网站下载。
  • 作用域因服务商而异，需查阅参考文件确认有效值；应请求最小必要作用域。
  • 采用零知识加密：令牌用你的 grant_secret 加密，TapAuth 从不存储该 secret，因此无法在服务商层面吊销令牌。grant 过期时，加密密文会被删除且从未被读取。短生命周期令牌（Google ~1 小时、Linear ~1 小时、Sentry ~8 小时）自然过期并自动刷新；长生命周期令牌（GitHub、Slack、Vercel、Notion）如需吊销须前往服务商设置。
  • 若缓存令牌过期且刷新失败，可删除 .tapauth/ 并重新运行以创建新 grant。
  • 审批 URL 不可见通常是因为跳过了默认模式直接使用 --token；应先运行不带 --token 的默认模式取得 URL。
  • 审批超时：脚本在 600 秒后超时，需重新运行创建新 grant 和新审批 URL。
  • OpenClaw：支持通过 tapauth-secrets 脚本使用 exec secrets provider 协议，在配置中设置 secrets.tapauth（source 为 exec，command 为 tapauth-secrets 路径，passEnv 为 HOME、TAPAUTH_HOME、TAPAUTH_BASE_URL），以 tapauth.provider/scopes 引用令牌（如 tapauth.google/calendar.readonly）；注意 grant 必须预先批准，因为 tapauth-secrets 使用 10 秒超时且无法进行交互式批准。
  • 高级用法：若无法使用 CLI 脚本，可直接调用原始 API——创建 grant（POST https://tapauth.ai/api/v1/grants，带 provider 和 scopes）、用户在返回的 approve_url 批准、获取令牌（GET https://tapauth.ai/api/v1/grants/{grant_id}，带 Authorization: Bearer gs_... 头，可加 Accept: text/plain 获取 .env 格式）。状态码：200 令牌就绪、202 待处理（2-5 秒后再轮询）、401 无效 grant_secret、404 未找到 grant、410 已过期/吊销/拒绝。