> 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 概览

> 在索引邮件会话前，选择 Gmail 认证方式并了解邮箱、更新和权限边界。

Gmail 连接器会将已批准的邮件会话索引为 OpenCore 知识。Admin 负责创建和维护 Google 凭据，创建连接器时选择该凭据，并在将其文档集附加给 Agent 前验证索引结果。

## 连接器索引的内容

每个 Gmail 线程会成为一份文档。第一个可用主题作为标题，每封邮件贡献一个链接到 Gmail 线程的分段。

| 数据   | 当前行为                                                                          |
| ---- | ----------------------------------------------------------------------------- |
| 邮件内容 | 解码线程中每封邮件的 `text/plain` MIME 部分。HTML 和非文本附件载荷会被忽略；`text/plain` 附件部分不会与正文文本区分。 |
| 邮件头  | 在索引文本中包含主题以及 `From`、`To`、`Cc` 和 `Bcc` 值。邮件日期可解析时，会成为文档时间戳。                    |
| 所有者  | 将发件人记录为主要所有者，将其他邮件参与者记录为次要所有者。                                                |
| 大小保护 | 当单个纯文本部分的估算解码大小超过 10 MB 时跳过它。线程中其他可用部分仍可被索引。                                  |
| 时间窗口 | 使用连接器的索引开始时间和轮询窗口，按 Gmail 时间范围查询线程。                                           |

该连接器不提供 Google Drive 式的文件、文件夹或共享云端硬盘筛选条件。Gmail 范围由所选凭据可用的邮箱账号决定。

## 选择认证方式

| 方式              | 适用场景                                                 | 账号边界                                                                                                                                                             |
| --------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OAuth app       | 获授权人员可以用应索引 Gmail 的 Google 账号完成浏览器授权。                | OpenCore 会将已授权的 Gmail 资料保存为主要账号。OAuth 仅读取已授权账号的邮箱。即使该账号可通过 Admin SDK 列出其他 Workspace 用户，OAuth 凭据也不能模拟这些用户；域级邮箱覆盖必须使用已配置 Domain-Wide Delegation 的 Service Account。 |
| Service Account | Google Workspace 组织通过 Domain-Wide Delegation 管理邮箱访问。 | Service Account 使用配置的 Primary Admin Email 列出 Admin SDK 返回的每个 Workspace 用户，然后模拟每个邮箱用户。如果目录列表不可用，连接器会退回到所配置的主要账号。                                                  |

两种方式都会请求 Gmail 只读 Scope，以及 Workspace 用户和群组目录只读 Scope。请选择与组织 Google 管理方式相符的认证方式；不要对个人 Gmail 邮箱使用 Service Account。

## 邮箱权限与同步

对于每个已索引线程，OpenCore 会为获取它的邮箱地址记录一条非公开的外部访问权限。Gmail 连接器不会向该记录添加 Google 群组 ID，也不会把线程变成公开内容。

当部署运行 Gmail 权限同步时，它会在同步时间窗口内重新访问精简线程记录，并为每个返回的线程更新外部访问记录。该路径保持相同的“仅邮箱、非公开”边界；它不会根据邮件收件人或 Workspace 群组推断更广泛的可见性。

## 更新和多凭据

连接器创建表单默认每 30 分钟拉取一次新内容。Admin 可以选择不低于一分钟的其他刷新频率，并可以设置索引开始日期以限定首次历史查询。内容来源变更只会在后续索引尝试成功后出现。

创建第二个 Gmail 凭据会保留现有 Gmail 凭据。当 Google 环境或邮箱访问边界不同时，请使用独立凭据和连接器，并在创建连接器前确认选中了哪个凭据。撤销或替换某个凭据会影响使用它的连接器，不会影响无关的 Gmail 凭据。

## 连接前准备

1. 请使用 Standard 模式，因为连接器和文档索引需要向量数据库。
2. 获得对将要索引的邮箱和历史时段的批准。
3. 先使用较窄的索引开始日期和有代表性的账号边界。
4. 在将首次索引尝试的文档集附加给 Agent 前，请先检查该尝试。

## 后续步骤

* [Gmail OAuth](/opencore/knowledge/gmail/oauth) 介绍上传 OAuth app JSON 和浏览器授权流程。
* [Gmail Service Account](/opencore/knowledge/gmail/service-account) 介绍 Domain-Wide Delegation 和 Primary Admin Email。
* [连接器与索引](/opencore/knowledge/connectors) 说明文档集和索引尝试。