> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Gmail Service Account

> 使用 Domain-Wide Delegation 配置 Google Workspace Service Account，以进行组织管理的 Gmail 索引。

当 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`。

```json
{
  "type": "service_account",
  "project_id": "<google-cloud-project-id>",
  "private_key_id": "<service-account-key-id>",
  "private_key": "<service-account-private-key>",
  "client_email": "<service-account-email>",
  "client_id": "<service-account-oauth-client-id>",
  "token_uri": "https://oauth2.googleapis.com/token"
}
```

请对密钥保密。另行记录 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 邮箱。                                        |

## 相关页面

* [Gmail 概览](/opencore/knowledge/gmail/overview) 介绍索引内容、账号范围、更新和权限边界。
* [Gmail OAuth](/opencore/knowledge/gmail/oauth) 介绍使用已上传 OAuth app JSON 的浏览器授权。
* [连接器与索引](/opencore/knowledge/connectors) 说明文档集和索引尝试。