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

# HubSpot

> 配置 HubSpot CRM 索引，并明确主对象、关联、轮询与搜索访问边界。

## 索引内容

HubSpot 连接器可以为四种 CRM 对象创建主文档：**tickets**、**companies**、**deals** 与 **contacts**。默认选中全部四种；管理表单允许选择其中一部分。

| 主对象       | 索引内容                                               |
| --------- | -------------------------------------------------- |
| Tickets   | 工单正文、作为文档标识符的主题、优先级元数据，以及可用的关联联系人、公司、交易与 notes。    |
| Companies | 名称、域名、行业、地点、描述，以及可用的关联联系人、交易、工单与 notes。            |
| Deals     | 名称、金额、阶段、关闭日期、pipeline、描述，以及可用的关联联系人、公司、工单与 notes。 |
| Contacts  | 姓名或邮箱标识符、公司、职位、电话、地点，以及可用的关联公司、交易、工单与 notes。       |
| Files     | 该连接器不会下载附件与文件正文。Note 正文会从 HTML 转换为可搜索纯文本。          |

对象选择控制哪些类型成为主文档，但不会从这些文档中排除相关 CRM 数据。例如，即使未选择 **companies** 或 **deals** 作为主类型，工单文档仍可能包含关联公司或交易摘要。

## 前置条件

* 为获准账号创建或获取 HubSpot access token。
* 为 token 授予每个已选主对象类型的读取权限。
* 允许访问 integration identity 端点，使 OpenCore 能解析引用链接所需的 HubSpot portal ID。
* 授予关联读取权限，以及对需要出现在主文档中的相关联系人、公司、交易、工单和 notes 的读取权限。
* 连接器 worker 只需通过 HTTPS 访问 HubSpot API 主机（包括 `api.hubapi.com`）；worker 不会打开引用链接。
* 最终用户浏览器必须能访问 `app.hubspot.com`，才能打开 HubSpot 引用链接。
* 确认每个已选主文档中包含相关对象摘要与 note 正文是可接受的。

## 凭据

| 方式                   | OpenCore 凭据值                                   | 认证行为                                                                     |
| -------------------- | ---------------------------------------------- | ------------------------------------------------------------------------ |
| HubSpot access token | `hubspot_access_token: <HUBSPOT_ACCESS_TOKEN>` | OpenCore 向 HubSpot API 发送 token，并调用 integration identity 端点保存 portal ID。 |

当前管理后台凭据只有一个 access-token 字段。它不会启动浏览器 OAuth 流程，也不接收 client ID、client secret、refresh token、portal ID 或自定义 HubSpot Base URL。

## 在 OpenCore 中配置

1. 在管理后台打开**连接器**，选择 **HubSpot**，并创建 access-token 凭据。
2. 在**对象类型**中至少选择 **Tickets**、**Companies**、**Deals** 或 **Contacts** 之一。默认选中全部四种。
3. 检查可能嵌入每种已选主类型的相关记录。对象类型选择不会形成关联数据的隐私边界。
4. 对受限 CRM 数据选择**私有**并分配 OpenCore 群组。仅当每个 OpenCore 账号都可以搜索全部成功索引的主记录与关联记录时才使用**公开**。
5. 设置刷新与清理选项，创建连接器并运行首次索引。

标准管理后台连接器运行 `poll_source`。仅当有效轮询起点恰好是 Unix epoch 0 时，HubSpot 才会移除时间边界，并对每个已选主类型执行基于 cursor 的完整扫描。如果**索引开始日期**使有效起点非零，首次运行会改用 Search API 时间窗口。后续轮询使用各对象的最后修改属性及对应的计划任务起止窗口。

## 权限

HubSpot token 决定 OpenCore 可以摄取哪些内容，但 HubSpot 用户、团队、对象所有权与记录级访问不会同步到 OpenCore。该连接器不提供轻量权限文档路径或查询时 HubSpot 访问检查。

索引后，搜索访问由连接器的 OpenCore **私有**群组或**公开**模式控制。能够搜索主文档的用户也能搜索嵌入其中的关联对象摘要与 note 文本，即使该用户无法在 HubSpot 中打开这些记录。应使用最小权限 token，只选择必需的主类型，并在 token 可见性允许时把敏感数据集拆分到独立连接器与 OpenCore 群组。

## 验证

1. 创建凭据，并确认 OpenCore 解析到预期 HubSpot portal ID。
2. 记录首次有效轮询窗口，运行首次同步，并分别搜索每种已选主对象类型中的一条记录。有效起点非零时，检查 Search API 时间窗口内的一条记录和明显早于该窗口的一条记录；起点为 epoch 0 时，检查 cursor 扫描应覆盖的一条较早记录。
3. 确认未选择的类型不会产生独立主文档。
4. 检查一个有代表性的主文档是否包含关联记录与一条 note。确认即使其类型未选为主类型，这些相关数据仍可接受。
5. 使用已获 HubSpot 授权的浏览器会话打开引用链接，确认 portal 与对象正确。
6. 测试每个已分配的 OpenCore 群组，因为搜索时不会重新检查 HubSpot 访问。

## 故障排除

| 症状                      | 检查项                                                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| 创建凭据时无法解析 portal        | 替换无效或过期 access token，并允许 integration identity 端点。Portal ID 由系统发现，不是手动输入。                                                  |
| 已选对象类型返回 403            | 为 token 授予该 CRM 对象类型及其请求属性的读取权限。                                                                                          |
| 主文档存在但相关章节缺失            | 授予关联与相关对象读取权限。关联和 batch-read 失败会被记录，而主文档可以在没有这些章节时继续生成。                                                                   |
| Notes 缺失                | 授予 note 关联与 note batch read 访问。连接器读取 note 正文和时间戳属性，不读取文件附件。                                                               |
| 未选择的对象出现在搜索中            | 检查它是否为已选主文档中的关联章节。主对象选择不会移除相关摘要。                                                                                          |
| 首次运行的覆盖范围或耗时不符合预期       | 检查**索引开始日期**与该 attempt 的有效轮询起点。起点为 epoch 0 时会 cursor 扫描全部已选主对象；非零起点会使用有界的 Search API 路径。先核对已记录窗口，再按需要减少主类型或选择符合预期的索引开始日期。 |
| 轮询产生大量 API 调用           | Search 结果不包含内联关联，因此变更记录可能需要单独的分页关联请求和 batch read。HubSpot 限流会在本地节流，429 响应最多重试到已配置上限。                                       |
| 一个轮询窗口包含至少 10,000 条记录   | OpenCore 会从最后修改时间戳继续。共享边界时间戳的记录可能重复索引；如果时间戳缺失、无法解析或没有前进，超过上限的记录可能缺失。请缩小变更窗口并核对数量。                                         |
| 用户能搜索但无法在 HubSpot 中打开记录 | 这是预期行为，因为 HubSpot ACL 不会同步。使用 OpenCore 群组限制连接器，或拆分数据源。                                                                    |

## 相关页面

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