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

# Google Drive OAuth

> 上传 Google OAuth 客户端，并授权 OpenCore 要索引的 Google Drive 账号。

当获授权人员可以为待索引的 Google Drive 内容完成浏览器授权时，使用此方式。只有 OpenCore Admin 可以上传或维护已保存的 OAuth 凭据；该凭据不会让 Agent 直接访问 Google Drive。

## 前置条件

请使用 Standard 模式，因为连接器和文档索引需要此模式。Admin 需要访问 OpenCore 的 Google Drive 凭据页面，Google 账号所有者必须批准预期内容和索引范围。Curator 无法访问凭据控制项。

请在 Google Cloud 中使用由组织控制的项目。为该项目启用 Google Drive API，并准备一个 Web OAuth 客户端。

## 创建 OAuth 应用

在 Google Cloud Project 中配置 OAuth 同意屏幕，然后创建 Web OAuth 客户端。请精确添加下列 Authorized redirect URI，并将 `<WEB_DOMAIN>` 替换为 OpenCore 部署的公开基础 URL：

`<WEB_DOMAIN>/admin/connectors/google-drive/auth/callback`

下载该 Web 客户端的 OAuth Client JSON。请妥善保护下载的文件；其中包含 OpenCore 仅在完成授权流程时使用的客户端配置。

## OAuth Scope 与数据访问

请在 Google Cloud OAuth 同意屏幕配置的 **Data Access** 中添加以下四项只读 Scope。授权人员看到的同意内容由该配置决定；最终索引哪些 Drive 内容，仍同时受连接器所选范围和账号原有权限限制。

| OAuth Scope                                                      | 用途                                    |
| ---------------------------------------------------------------- | ------------------------------------- |
| `https://www.googleapis.com/auth/drive.readonly`                 | 读取授权账号可访问且已获批准的 Drive 文件内容。           |
| `https://www.googleapis.com/auth/drive.metadata.readonly`        | 读取用于发现、筛选和索引所选范围的 Drive 文件与文件夹元数据。    |
| `https://www.googleapis.com/auth/admin.directory.group.readonly` | 读取解析群组访问权限所需的 Google Workspace 群组元数据。 |
| `https://www.googleapis.com/auth/admin.directory.user.readonly`  | 读取解析用户访问权限所需的 Google Workspace 用户元数据。 |

四项 Scope 均为只读。同意会把数据读取权限授予连接器，但不会让 OpenCore 修改 Drive 内容，也不会扩大 Google 账号原有权限。Google Workspace 组织的应用访问策略可能还需要允许此 OAuth client，其用户才能完成同意。

## 上传并授权

1. 以 Admin 身份登录 OpenCore，并打开 **文档与知识**。
2. 选择 **Google Drive**，选择 **OAuth app**，并上传 Google Cloud Project 中的 OAuth Client JSON。
3. 选择 **使用 Google Drive 授权**。浏览器会打开 Google 的授权流程。
4. 使用 Google 账号登录；该账号应可访问获准索引的 Drive 内容。检查请求的访问权限并完成同意。

浏览器返回 OpenCore 后，请由 Admin 确认凭据显示为已授权。若账号、同意屏幕、redirect URI 或上传的客户端不匹配，请先修正配置，再发起新的授权流程。

只有 Admin 可以上传、替换、重新授权或以其他方式维护凭据。配置连接器时，也由 Admin 选择或关联该 Google 凭据；不要假定该凭据已与其他角色共享。

## 配置索引范围

创建连接器时，请选择最小的已批准范围。

| 区域       | 可用选项                                                                                    |
| -------- | --------------------------------------------------------------------------------------- |
| General  | **Include My Drive**、**Include shared drives** 和 **Include All Files Shared With You**。 |
| Specific | 逗号分隔的多个 **Shared Drive URLs** 和 **Folder URLs**。被索引的文件夹包含全部子文件夹。                        |
| Advanced | 可选的 **Hide domain link-only files**：跳过向域内或公开范围广泛共享、但需要链接才能访问的文件。                        |

所选范围和 Google 账号权限都会限制连接器可读取的内容。扩大连接器范围不会为该账号新增 Google Drive 访问权限。

## 验证连接器

使用一个小且有代表性的已批准范围创建连接器，并运行一次索引尝试。在将文档集附加给 Agent 或扩大范围前，请检查尝试结果、已索引文档集，以及报告的跳过文件或错误。

## 故障排查

| 症状                 | 检查并修正                                                                                                                                                                      |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Redirect URI 不匹配   | 确认 Google Cloud Web 客户端为启动授权流程的部署精确配置了 `<WEB_DOMAIN>/admin/connectors/google-drive/auth/callback`。                                                                         |
| 同意内容缺少 Scope       | 在 Google Cloud OAuth 同意屏幕中确认 **Data Access** 包含 `drive.readonly`、`drive.metadata.readonly`、`admin.directory.group.readonly` 和 `admin.directory.user.readonly`；保存同意配置后重新授权。 |
| 应用被 Workspace 策略阻止 | 请 Google Workspace 管理员检查组织的应用访问策略，并在需要时允许该 OAuth client，然后重新授权。                                                                                                            |
| 账号无法访问内容           | 使用对所选 My Drive、Shared Drive、文件或文件夹拥有 Google Drive 权限的账号登录。                                                                                                                 |
| 授权已撤销              | 使用已批准账号重新执行浏览器授权，然后运行新的索引尝试。                                                                                                                                               |

## 相关页面

* [Google Drive 概览](/opencore/knowledge/google-drive/overview) 对比认证方式和索引范围。
* [Google Drive Service Account](/opencore/knowledge/google-drive/service-account) 介绍通过 Domain-Wide Delegation 管理组织访问。
* [连接器与索引](/opencore/knowledge/connectors) 说明文档集和索引尝试。