> 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 OAuth

> 上传 Google Web OAuth app JSON，并授权 OpenCore 将要索引的 Gmail 账号。

当获授权人员可以为待索引 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 端点。

```json
{
  "web": {
    "client_id": "<oauth-client-id>",
    "project_id": "<google-cloud-project-id>",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "client_secret": "<oauth-client-secret>",
    "redirect_uris": ["<WEB_DOMAIN>/admin/connectors/gmail/auth/callback"]
  }
}
```

请妥善保护该文件。只能通过 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 邮件或超大纯文本部分可能不贡献正文文本。                                                |

## 相关页面

* [Gmail 概览](/opencore/knowledge/gmail/overview) 介绍索引内容、邮箱范围、更新和权限边界。
* [Gmail Service Account](/opencore/knowledge/gmail/service-account) 介绍组织管理的 Domain-Wide Delegation。
* [连接器与索引](/opencore/knowledge/connectors) 说明文档集和索引尝试。