OpenCore文档与知识Gmail

Gmail OAuth

以 Markdown 格式查看

当获授权人员可以为待索引 Gmail 账号完成 Google 浏览器授权时，使用 OAuth。OpenCore Admin 负责上传 OAuth app JSON 并维护由此生成的凭据。

前置条件

请使用 Standard 模式。在由组织控制的 Google Cloud Project 中，启用 Gmail API 和 Admin SDK API，配置 OAuth 同意屏幕，并创建 Web application OAuth 客户端。为 OpenCore 授权的人员必须获准授予全部所请求 Scope。

创建 Web OAuth 客户端

请精确添加下列 Authorized redirect URI，并将 <WEB_DOMAIN> 替换为 OpenCore 部署的公开基础 URL：

<WEB_DOMAIN>/admin/connectors/gmail/auth/callback

下载 OAuth 客户端 JSON。OpenCore 要求下载对象包含 web.client_id 和 web.client_secret；Google 标准下载文件也会提供授权和 Token 端点。

1{
2  "web": {
3    "client_id": "<oauth-client-id>",
4    "project_id": "<google-cloud-project-id>",
5    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
6    "token_uri": "https://oauth2.googleapis.com/token",
7    "client_secret": "<oauth-client-secret>",
8    "redirect_uris": ["<WEB_DOMAIN>/admin/connectors/gmail/auth/callback"]
9  }
10}

请妥善保护该文件。只能通过 Gmail 凭据页面上传，切勿将其放入源代码管理、Agent 指令或共享文档。

配置所请求 Scope

OpenCore 当前为 Gmail OAuth 请求以下三项只读 Scope：

Scope当前用途
https://www.googleapis.com/auth/gmail.readonly列出线程，并读取连接器处理的每个邮箱账号中的邮件。
https://www.googleapis.com/auth/admin.directory.user.readonly尝试列出已授权 Workspace 域中的用户邮箱地址。
https://www.googleapis.com/auth/admin.directory.group.readonly提供 Google 凭据合同所需的群组目录只读授权；Gmail 线程访问记录仍仅限邮箱。

OAuth 流程会请求全部三项 Scope。目录用户列表不会授予 Gmail 模拟能力：OAuth 凭据仍仅限完成授权的账号。域级邮箱覆盖必须使用已配置 Domain-Wide Delegation 的 Service Account。

上传并授权

  1. 以 Admin 身份登录 OpenCore，并打开“文档与知识”。
  2. 选择 Gmail，选择 OAuth app，然后上传或粘贴 OAuth 客户端 JSON。
  3. 选择 Authenticate with Gmail，使用已获批准进行索引的 Gmail 账号完成 Google 同意流程。
  4. 浏览器返回 OpenCore 后，确认该凭据已出现在凭据列表中。

OpenCore 会在授权后读取当前 Gmail 资料，并将该邮箱保存为凭据的主要账号。OAuth 凭据只能读取该账号的邮箱，即使该账号是 Workspace 管理员并可列出 Directory 用户。域级邮箱覆盖必须使用已配置 Domain-Wide Delegation 的 Service Account。

验证连接器

使用已批准的索引开始日期创建 Gmail 连接器。默认刷新频率为 30 分钟，可更改为其他不低于一分钟的值。运行并检查首次索引尝试，确认仅包含预期邮箱线程，并检查代表性线程是否包含可用纯文本内容。

故障排查

现象检查并修正
OAuth JSON 被拒绝上传包含 web 对象的 Web application JSON，其中 client_id 和 client_secret 均为字符串值。
Redirect URI 不匹配为发起授权的精确部署配置 <WEB_DOMAIN>/admin/connectors/gmail/auth/callback。
同意或 Scope 缺失错误确认同意屏幕请求全部三项已记录 Scope，且组织策略允许该 OAuth client。然后重新授权。
仅索引一个邮箱OAuth 按设计只索引一个邮箱。如要索引 Admin SDK 返回的每个 Workspace 用户邮箱，请使用已配置 Domain-Wide Delegation 的 Service Account。
线程有邮件头但没有正文连接器索引 text/plain MIME 部分；纯 HTML 邮件或超大纯文本部分可能不贡献正文文本。

相关页面