OpenCore文档与知识Gmail

Gmail Service Account

以 Markdown 格式查看

当 Google Workspace 组织集中批准邮箱索引时，使用 Service Account。Workspace 管理员负责配置 Domain-Wide Delegation，OpenCore Admin 负责上传密钥并提供 Primary Admin Email。

前置条件

请使用 Standard 模式。你需要一个由组织控制的 Google Cloud Project，在该项目中启用 Gmail API 和 Admin SDK API，需要可配置 Domain-Wide Delegation 的 Google Workspace 管理员，以及 Workspace 组织内已获批准的管理员或所有者账号。

创建 Service Account

在 Google Cloud 中创建 Service Account，为它启用 Domain-Wide Delegation，并创建 JSON 密钥。OpenCore 要求 JSON 对象的 type 为 service_account。

1{
2  "type": "service_account",
3  "project_id": "<google-cloud-project-id>",
4  "private_key_id": "<service-account-key-id>",
5  "private_key": "<service-account-private-key>",
6  "client_email": "<service-account-email>",
7  "client_id": "<service-account-oauth-client-id>",
8  "token_uri": "https://oauth2.googleapis.com/token"
9}

请对密钥保密。另行记录 Service Account OAuth client ID；Workspace 委派条目使用该数字 client ID，而不是 Service Account 邮箱。

配置 Domain-Wide Delegation

在 Google Workspace Admin console 中，将 Service Account OAuth client ID 添加到 Domain-Wide Delegation，并且仅授权当前 Gmail 连接器所需的 Scope：

Scope当前用途
https://www.googleapis.com/auth/gmail.readonly模拟 Admin SDK 返回的每个 Workspace 用户，以列出线程和读取邮件。
https://www.googleapis.com/auth/admin.directory.user.readonly模拟 Primary Admin Email，以列出 Workspace 域中的用户邮箱地址。
https://www.googleapis.com/auth/admin.directory.group.readonly提供 Google 凭据合同所需的群组目录只读授权；Gmail 线程访问记录不会获得群组 ID。

请勿将 Google Drive Scope 复制到此委派中。Gmail 连接器不会请求 Drive 内容或元数据访问权限。

将凭据添加到 OpenCore

  1. 以 Admin 身份登录 OpenCore，并打开“文档与知识”。
  2. 选择 Gmail，选择 Service account，然后上传或粘贴 Service Account JSON 密钥。
  3. 输入拥有已批准索引的 Gmail 账号所属 Google 组织中管理员或所有者的 Primary Admin Email。
  4. 创建凭据，确认它出现在凭据列表中，并在创建 Gmail 连接器时选择它。

Primary Admin Email 用于 Admin SDK 目录访问。连接器列出 Workspace 用户后，Service Account 会在读取每个用户的 Gmail 线程时模拟该用户。

账号范围与权限同步

当 Domain-Wide Delegation 和目录权限正常工作时，连接器会处理 Primary Admin Email 所属 Workspace 域返回的用户地址。目录列表返回 403 或 404 时，实现会退回到所配置的 Primary Admin Email，因此请从实际索引结果确认账号范围。

每个已索引线程均为非公开，并将获取它的邮箱作为唯一外部用户访问权限。邮件收件人和 Workspace 群组不会被添加到该访问记录。当 Gmail 权限同步运行时，它会为时间窗口内返回的线程刷新这一“仅邮箱”记录。

验证更新

使用已批准的索引开始日期和有代表性的邮箱边界创建 Gmail 连接器。默认刷新频率为 30 分钟，可更改为其他不低于一分钟的值。运行首次索引尝试，并在将文档集附加给 Agent 前验证预期账号、线程和纯文本内容。

创建另一个 Service Account 或 OAuth 凭据会保留现有 Gmail 凭据。对不同 Workspace 组织或批准边界使用独立凭据，并在运行索引尝试前检查所选凭据。

故障排查

现象检查并修正
JSON 类型被拒绝上传 type 为 service_account 的有效密钥，而不是 Web OAuth 客户端 JSON。
无法模拟用户确认 Service Account 已启用 Domain-Wide Delegation，且委派使用它的 OAuth client ID。确认该用户仍存在且已启用 Gmail。
目录或 Scope 缺失错误在 Workspace 委派条目中授权全部三项 Gmail 连接器 Scope，并确认 Primary Admin Email 可列出用户。
仅索引 Primary Admin Email目录用户列表返回了 403 或 404。修正 Admin SDK 访问和委派，然后运行新的索引尝试。
某用户邮箱被跳过当 Gmail 报告该用户未启用邮件服务时，连接器会跳过该邮箱。确认该账号已配置 Gmail 邮箱。

相关页面