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

# Dropbox

> 使用访问令牌配置 Dropbox 文件递归索引，并显式设置 OpenCore 访问控制。

## 索引内容

Dropbox 连接器从访问令牌可见的根目录开始，递归索引每个可见子文件夹中的可下载文件。每个文件会成为一个可搜索文档；文件夹只用于组织遍历，本身不会作为文档索引。

| 范围行为 | 索引效果                                                                                         |
| ---- | -------------------------------------------------------------------------------------------- |
| 根目录  | 连接器始终从令牌可见的根目录开始。Admin 表单没有文件夹、Prefix、包含或排除字段。                                               |
| 子文件夹 | 每个可见子文件夹都会被递归遍历。                                                                             |
| 文件   | Dropbox 列表请求会排除不可下载条目。下载失败不会按文件捕获，可能会停止当前遍历或索引尝试。只有文件提取或解码异常会按文件捕获并跳过。                       |
| 链接   | OpenCore 会先列出现有共享链接。列表调用成功且没有现有链接时，才会尝试创建链接。列出或创建共享链接时出现 API 错误会生成空源链接；列表调用失败后，连接器不会再尝试创建链接。 |

## 前置条件

* 通过组织批准的流程创建 Dropbox App 或令牌。
* 将令牌的 Dropbox 可见范围限制为所有预期 OpenCore 受众都可索引的内容；连接器不提供更窄的文件夹选择器。
* 允许令牌列出和下载文件，并允许列出共享链接；仅当列表调用成功且没有现有链接时，还需要允许创建共享链接。
* 允许连接器 Worker 通过 HTTPS 访问 Dropbox API。

## 凭据

| 方式                   | OpenCore 凭据值                                   | 说明                                                                                  |
| -------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------- |
| Dropbox Access Token | `dropbox_access_token: <DROPBOX_ACCESS_TOKEN>` | Admin UI 将该值标为 **Dropbox API Key**。文档中只使用占位符，并将真实令牌保存在 OpenCore Credential Store 中。 |

当前 Admin UI 中的 Dropbox 索引连接器不提供 OAuth 流程。请通过正常的 Dropbox App 流程轮换 Access Token。

## 在 OpenCore 中配置

1. 在 Admin 后台打开 **Connectors**，选择 **Dropbox**，然后创建 Dropbox Token 凭据。
2. 审查令牌能看到的内容。连接器没有文件夹、Prefix 或文件名过滤器。
3. 对受限内容选择 **Private** 并分配 OpenCore 用户组。只有当所有 OpenCore 账号都可搜索令牌可见的每个文件时，才使用 **Public**。
4. 设置刷新和清理选项，创建连接器，然后运行首次索引尝试。
5. 将生成的文档集附加给 Agent 前，先审查实际索引的文件。

## 权限

Dropbox 源权限不会同步。令牌决定 OpenCore 能摄取什么内容，但 Dropbox 共享设置和逐文件 Viewer 列表不会复制到 OpenCore。

因此，任何能访问该连接器或其文档集的 OpenCore 用户都能搜索所有成功索引的文件，即使该用户无法在 Dropbox 中打开对应文件。请为敏感区域使用分别限定范围的 Dropbox 凭据或 App，并通过 OpenCore **Private** 用户组执行访问控制。源共享链接也可能根据 Dropbox 链接设置暴露内容，因此索引前应审查 App 的共享策略。

## 验证

1. 验证凭据，并确认连接器能够列出令牌可见的根目录。
2. 运行索引尝试，分别搜索一个根目录文件和一个嵌套文件中的文本。
3. 确认不可下载或刻意设为令牌不可访问的文件没有出现。
4. 打开搜索结果中的源链接。如果没有链接，检查 Token 能否列出共享链接，以及列表为空时能否创建链接。
5. 使用分配给连接器的每个 OpenCore 用户组测试搜索访问；Dropbox ACL 不会提供第二次授权检查。

## 故障排除

| 现象                      | 检查项                                                                |
| ----------------------- | ------------------------------------------------------------------ |
| 凭据验证报告 Token 无效         | 替换过期或已撤销的 Token，并确认它属于目标 Dropbox App。                              |
| 验证报告权限不足                | 为 Token 授予列出根目录和下载文件所需的能力。                                         |
| 缺少某个文件夹                 | 确认 Token 能从其根目录看到该文件夹。连接器无法定位该可见边界之外的任意文件夹。                        |
| 缺少某个文件或索引尝试停止           | 下载失败位于逐文件异常处理之外，可能会停止当前遍历。文件提取或解码失败则会记录日志，并且只跳过该文件。                |
| 搜索结果没有 Dropbox 链接       | 允许 App 列出共享链接，并在列表成功但为空时创建链接。任一操作出现 API 错误都会返回空链接；列表调用失败时不会继续尝试创建。 |
| 用户能搜索其无法在 Dropbox 打开的文件 | 源 ACL 不同步时这是预期行为。请用 OpenCore 用户组限制连接器，或将来源拆分为范围更窄的凭据。              |

## 相关页面

* [连接器与索引](/opencore/knowledge/connectors)
* [索引设置](/opencore/knowledge/index-settings)