为 OpenConnector 创建 Google OAuth app

自部署 OOMOL OpenConnector 需要连接用户的 Google 账号时，使用 Google OAuth app。一个 Google Cloud project 可以保存 Gmail、Google Drive、Google Calendar、Google Sheets、Google Docs、Google Slides、YouTube、Google Analytics、Google BigQuery 等 provider 使用的 OAuth client。

OpenConnector services

Service ID	Provider
`gmail`	Gmail
`googledrive`	Google Drive
`googlecalendar`	Google Calendar
`googlesheets`	Google Sheets
`googledocs`	Google Docs
`googleslides`	Google Slides
`youtube`	YouTube
`google_analytics`	Google Analytics
`google_bigquery`	Google BigQuery

每个 service 在 OpenConnector 中单独保存 OAuth client config。如果同一个 Google OAuth client 已允许相同 redirect URI，并且已启用所需 API 和 scopes，你可以把同一组 client ID / client secret 保存给多个 Google service。

前置条件

一个正在运行的 OpenConnector runtime。
可以访问 Google Cloud project 的 Google 账号。
有权限配置 OAuth consent、启用 APIs、创建 OAuth credentials。
用户在浏览器中打开的 OpenConnector origin，例如 http://localhost:3000 或 https://connect.example.com。

第 1 步：确定 OpenConnector callback URL

本地测试时使用：

http://localhost:3000/oauth/callback

公开 runtime 请先设置 OOMOL_CONNECT_ORIGIN，重启后使用：

https://connect.example.com/oauth/callback

第 2 步：准备 Google Cloud project

在 Google Cloud Console 中：

创建或选择一个 project。
打开 APIs & Services。
启用 OpenConnector service 需要的 API，例如 Gmail API、Google Drive API、Google Calendar API、Google Sheets API、YouTube Data API、Google Analytics Data API 或 BigQuery API。
打开 OAuth consent screen，按 Google 要求配置 app name、support email、audience、contact information 和 test users。
添加 OpenConnector service 需要的 scopes，或在启动 OAuth 授权时由 Google 展示这些 scopes。

敏感或受限 scopes 在广泛生产使用前可能需要 Google verification。本地使用或内部测试时，请按你的 Google 账号类型使用 testing 或 internal 状态。

第 3 步：创建 OAuth credentials

在 APIs & Services > Credentials 中：

选择 Create credentials。
选择 OAuth client ID。
Application type 选择 Web application。
在 authorized redirect URIs 中添加 OpenConnector 的准确 callback URL。
创建 client。
复制 client ID 和 client secret。

Google 官方文档见 Using OAuth 2.0 for Web Server Applications。

第 4 步：在 OpenConnector 中保存 client

优先在 OpenConnector Web 控制台中配置目标 service：

打开 OpenConnector Web 控制台，例如 http://localhost:3000。
打开 Providers，选择 Gmail 或其他 Google provider。
点击 Configure OAuth Client 或 Edit OAuth Client。
粘贴 Google client ID 和 client secret。
点击 Save OAuth Client。

如果要把同一 Google OAuth client 用到其他 Google provider，请在对应 Google provider 页面重复这些步骤。

第 5 步：连接并测试

保存 OAuth client 后，在 Google provider 页面点击 Connect。完成 Google consent，回到 OpenConnector，并确认 provider 页面显示账号已连接。

Gmail 可用 gmail.get_profile 或 gmail.list_labels 做低风险测试。运行 action 前，先在控制台 action 详情中确认准确输入。

排查建议

现象	检查项
`redirect_uri_mismatch`	Google 收到的 URI 必须和 OAuth client 中的 authorized redirect URI 完全一致。确认它是 `<openconnector-origin>/oauth/callback`。
Google 显示 app 未验证	使用允许的 test users 测试，能用 internal mode 时使用 internal mode；广泛使用前完成 Google verification。
Google 没有发 refresh token	重新连接账号。需要 refresh token 的 OpenConnector Google provider 会在定义中请求 offline access 和 consent。
Google action 提示权限不足	在 Google Cloud 启用所需 API，添加或批准所需 scope，然后重新连接账号。
执行时用了错误 Google 账号	使用已登录目标 Google 账号的浏览器 profile 重新连接。

请把 Google client secret 放在密钥管理系统中，并在 OpenConnector 中保存 OAuth client 前设置 OOMOL_CONNECT_ENCRYPTION_KEY。