教程

通过 Composio 为 Hermes Agent 和 OpenClaw 接入 HubSpot CRM

Q: Hermes Agent 也能通过 Composio 使用 HubSpot 吗？

可以。托管 Hermes Agent 与 OpenClaw 共用集成页面和 Composio Skill；自托管时分别配置 MCP。

Q: 必须创建 HubSpot 私有应用 token 吗？

托管 OAuth 不需要。API Key 方式使用 HubSpot 私有应用访问 token。

Q: 显示“已连接”后，所有 CRM 操作都能用吗？

不一定。调用还取决于授权 scopes、账号功能和工具选择，需要分别验证联系人和交易。

Q: 连接后会自动给客户发邮件吗？

连接本身不会创建营销活动。发邮件或将联系人加入工作流是单独的操作。

开会前整理客户背景，开会后把笔记变成可核对的 CRM 更新。先认准账号、联系人 ID 和销售阶段，再修改记录。

Read in English

从下一次客户会议开始

会前，让机器人整理客户的联系方式、未结交易、近期备注和待办。会后，再让它根据笔记列出准备修改的字段。这样既能减少来回查找，也能在提交前发现联系人选错、货币填错或销售阶段不对的问题。

本页使用 Composio 的 HubSpot 工具包。2026 年 10 月 5 日核对时，它位于按 Popularity 排序的目录第一页。这个 CRM 集成同时适用于 Hermes Agent 与 OpenClaw。

连接托管实例的 HubSpot 账号

Launch 上的 Hermes Agent 与 OpenClaw 使用相同的连接入口。请准备有权安装集成的 HubSpot 账号，并确认你要访问的是哪个工作账号。

打开 Dashboard → Integrations，搜索 HubSpot，选择对应卡片。工具包 slug 是 hubspot。
点击 Connect，按页面提示完成授权。托管精选连接器使用托管 OAuth；如果你能访问多个 HubSpot 账号，请选对目标账号。
核对授权内容，完成后等待卡片显示 Connected／已连接。
让机器人确认 HubSpot 连接处于 ACTIVE 状态，并读取少量联系人。首次验证不需要修改记录。

如果使用自己的 Composio 项目，官方工具包文档还提供 API Key 方式，凭据是 HubSpot 私有应用 token。把它填在应用连接表单中，不要发进聊天，也不要放到 MCP 的项目 key 请求头里。整理客户摘要时先准备联系人和交易的读取 scopes；需要修改时再配置对应写入权限。HubSpot 账号本身的功能与权限仍然适用。

先发现工具，再填写参数

composio connections
composio search hubspot list contacts
composio search hubspot list deals
composio search hubspot update contact

托管 Skill 会返回工具参数结构。执行前先查看记录 ID、字段、过滤条件和分页参数，不要凭印象拼 JSON。几个常用操作是：

HUBSPOT_LIST_CONTACTS：读取联系人及指定属性。
HUBSPOT_LIST_DEALS：读取交易记录。
HUBSPOT_LIST_CONTACT_NOTES：查看联系人关联的备注。
HUBSPOT_GET_PIPELINE_BY_ID：选择交易阶段前核对销售管道。
HUBSPOT_CREATE_CONTACT 和 HUBSPOT_CREATE_DEAL：创建已确认的记录。
HUBSPOT_UPDATE_CONTACT：按已知 ID 修改选定属性。

例如，下面这条托管命令只读取五个联系人的指定字段：

composio execute HUBSPOT_LIST_CONTACTS '{"limit":5,"properties":["firstname","lastname","email"]}'

读取联系人需要核对 crm.objects.contacts.read，读取交易对应 crm.objects.deals.read；修改则需要相应的 .write scopes。属性和管道工具可能另需权限。每次都查看参数结构：创建联系人的常用字段放在顶层，HUBSPOT_UPDATE_CONTACT 则使用 contactId 和 properties 对象。

使用我连接的 HubSpot 账号，读取最多五个联系人，返回 ID、姓名和邮箱。如果能读取账号信息，也请说明当前账号。不要创建、修改、合并、归档、发送邮件或加入工作流。

把会议笔记写回 CRM，避免重复建档

用准确邮箱查找已有联系人，保留记录 ID。如果有多个结果，先展示给你选择。
读取相关交易和销售管道。阶段和属性使用 HubSpot 返回的内部值，不要直接拿界面标签代替。
根据会议笔记生成预览：记录 ID、属性名、旧值、新值，以及需要新增的记录或关联。
确认后只执行这些变更。完成后重新读取记录，返回 ID 和实际写入的值。

找到这个邮箱对应的联系人，整理未结交易。根据以下会议笔记提出更新建议，列出记录 ID 和修改前后的值。等我确认再提交，不要发邮件，也不要把联系人加入工作流。

后续可以按阶段整理交易、找出没有负责人的记录，或结合 Gmail 起草跟进邮件。CRM 更新和邮件发送分别确认。如果还要将汇总写入 Airtable，先明确每个字段以哪个应用为准，避免双向同步相互覆盖。

分页、权限和服务限制

只请求需要的字段，并沿工具返回的分页游标继续读取。一页结果不能当作完整 CRM 导出。HubSpot 的搜索索引有独立限制，更新后的记录也可能不会立即出现在搜索结果中。验证写入时，优先用返回的记录 ID 直接读取。参见 HubSpot CRM 搜索说明。

遇到限流，按服务返回的提示暂停并退避重试。如果创建请求超时，先查记录是否已创建，再决定是否重试。HubSpot 套餐、API 限制、Composio 用量和机器人模型费用各自计算，完成连接并不会取消这些限制。

常见问题排查

读到了另一组联系人：检查 OAuth 时选择的 HubSpot 账号，尤其是一个登录身份能访问多个账号的情况。
401 或连接过期：从集成页面重新授权。私有应用 token 则检查是否被轮换或撤销。
403 或缺少 scopes：核对具体对象的读取、写入权限和账号可用功能。能读联系人，不代表能读交易或发营销邮件。
字段或阶段被拒绝：读取字段内部名与有效选项。界面里的自定义标签不一定就是 API 值。
触发器要求开发者凭据：本页讲工具调用。Composio 对 HubSpot 触发器另有 app ID 和开发者 key 要求，仅 OAuth 连接不会自动配置事件推送。

自托管：分别配置 Hermes 与 OpenClaw

如果机器人由你自己部署，在自己的 Composio 项目中为这个应用创建授权配置并连接账号。创建单工具包 MCP 配置时，只选择当前工作流需要的工具；生成 MCP URL 时，使用拥有 ACTIVE 连接的同一个用户 ID。复制生成的完整 URL。托管平台上的连接不会自动出现在你自己的 Composio 项目中。

Composio：单工具包 MCP 配置

将占位 URL 换成生成的地址。x-api-key 使用你自己的 Composio 项目 key，不能用 Airtable 或 HubSpot 的 token 代替。在机器人进程的环境中设置 COMPOSIO_API_KEY，并保管好 key 与 MCP URL。把下面的服务器配置合并到现有文件中，保留其他配置。

Hermes Agent

在 ~/.hermes/.env 中设置环境变量，把服务器条目加到 ~/.hermes/config.yaml 的 mcp_servers 下：

mcp_servers:
  composio:
    url: "YOUR_GENERATED_PLATFORM_MCP_URL"
    headers:
      x-api-key: "${COMPOSIO_API_KEY}"

运行 hermes mcp test composio 检查连接，然后开始新会话，或在 CLI 中执行 /reload-mcp。

Hermes 官方 MCP 配置说明

OpenClaw

使用包含原生 mcp 命令的 OpenClaw 版本，把服务器放到 ~/.openclaw/openclaw.json 的 mcp.servers 中：

{
  "mcp": {
    "servers": {
      "composio": {
        "url": "YOUR_GENERATED_PLATFORM_MCP_URL",
        "transport": "streamable-http",
        "headers": {
          "x-api-key": "${COMPOSIO_API_KEY}"
        }
      }
    }
  }
}

确保 Gateway 进程能读取 COMPOSIO_API_KEY；修改服务环境后重启该服务。运行 openclaw mcp doctor composio --probe，并开始新会话。旧版本如果没有这些命令，请先升级，避免向严格校验的配置添加不支持的字段。

OpenClaw 官方 MCP 命令 · HTTP 传输配置

MCP 探测成功只说明工具服务器可连接。最后还要执行本指南的只读请求，确认应用账号、数据范围与权限正确。上文的 composio shell 命令由 OpenClaw Launch 的托管 Skill 提供；独立 MCP 配置通过各框架的 MCP 客户端调用工具。

常见问题

Hermes Agent 也能通过 Composio 使用 HubSpot 吗？

可以。托管的 Hermes Agent 与 OpenClaw 使用同一个集成页面和 Composio Skill。自托管时，两者分别使用自己的 MCP 配置文件，本页都给出了配置。

必须创建 HubSpot 私有应用 token 吗？

托管 OAuth 流程不需要。自己配置 Composio 项目时，API Key 方式使用 HubSpot 私有应用的访问 token，不是账号密码，也不是旧版 HubSpot API key。

显示“已连接”后，所有 CRM 操作都能用吗？

不一定。实际调用还取决于授权 scopes、账号功能和选择的工具。联系人与交易要分别验证，不能用一个成功的读取代替全部权限检查。

连接后会自动给客户发邮件吗？

不会因为完成连接就创建营销活动。可以先让机器人整理客户摘要和邮件草稿。发营销邮件或将联系人加入工作流，需要另行下达明确指令。