OpenClaw LaunchOpenClaw Launch
← 返回中文首页

教程

通过 Composio 为 Hermes Agent 或 OpenClaw 接入 Airtable

先看清已有 Base 的表结构，找到准确的记录，再预览并确认修改。适合内容排期、项目跟进和业务数据整理。

从一条已有记录开始

Airtable 常用来保存内容排期、客户跟进和项目进度。你可以让 Hermes Agent 读取这些数据，找出需要处理的事项，再提出修改建议；OpenClaw 也能使用相同的托管接入流程。第一次使用时，选一个你熟悉的 Base 和表，不要直接让助手“整理整个数据库”。

例如，内容排期表里有一条业务编号为 CONTENT-104 的记录。目标只是把它的 Status 从 Draft 改为 Ready for review。先读结构和现有值，核对记录 ID，再批准这一项修改。建表、改字段和批量删除应当另行安排。

在托管控制台连接 Airtable

  1. 打开 Dashboard → Integrations，搜索 Airtable。对应 toolkit slug 是 airtable。
  2. 点击 Connect，按当前表单操作。若进入 OAuth 页面，确认账号并选择要授权的 Base；若出现凭据输入框，则在表单中填写 Airtable 个人访问令牌。
  3. 完成前检查访问范围。令牌只填写在连接表单中，不要发给聊天助手。
  4. 显示 Connected 后，先让助手列出可访问的 Base，并明确禁止写入。看到预期 Base 后再继续。

这套托管步骤适用于 Hermes Agent 和 OpenClaw。Composio Airtable 文档列出了托管 OAuth2 与 API_KEY 两种认证。API_KEY 在这里使用以 pat 开头的 PAT（Personal Access Token）；Airtable 的旧 API Key 已停用。

本例使用 PAT 时，需要 schema.bases:read、data.records:read，并把目标 Base 加入访问资源。需要修改记录时再增加 data.records:write。令牌的作用域、资源范围和账号权限都要满足要求。OAuth 的默认权限可能更广，请阅读实际授权页面，不要把 PAT 的最小配置当作 OAuth 的承诺。具体含义见 Airtable 作用域文档。

发现工具，再读取参数结构

composio connections
composio search airtable list bases
composio search airtable list records

先检查当前运行环境中的工具和参数 schema。以下名称来自 Composio 的 Airtable 工具目录，参数应以实时发现结果为准。

工具用途
AIRTABLE_LIST_BASES列出有权访问的 Base 及其 ID。
AIRTABLE_GET_BASE_SCHEMA读取表、字段和字段类型。
AIRTABLE_LIST_RECORDS在指定表中查找候选记录。
AIRTABLE_GET_RECORD修改前后读取同一条记录。
AIRTABLE_UPDATE_RECORD按记录 ID 执行已确认的修改。
AIRTABLE_CREATE_RECORDS排除重复并获得确认后新增记录。

先读取，再预览、确认和验证

使用已连接的 Airtable。先列出可访问的 Base，再读取 Content Operations 的结构，显示 Content Calendar 表的 ID 和字段。查询业务编号为 CONTENT-104 的记录，返回 record ID 和当前 Status。不要新增、修改或删除任何内容。

核对结果是否只有一条，并确认它就是你要处理的事项。表结构能帮助助手识别字段类型和选项，避免把计算字段当作普通输入框。表名或显示名称可能变化，后续操作要保留实际返回的 Base ID、table ID 和 record ID。

为刚才那个 record ID 准备修改：把 Status 设为 Ready for review。先展示旧值和新值，不改其他字段，不新增记录，等我确认后再执行。

确认预览后，明确批准这条记录的修改，再让助手读取同一个 record ID，报告保存后的值。若执行时超时，先查询结果再重试，因为请求可能已经成功。后续跟进也沿用这个 ID，避免把“更新状态”误做成“新增一条”。如果有多个匹配项，先细化业务编号或其他筛选条件。

分页、空字段和限流

Airtable 每页最多返回 100 条记录。响应带有 offset 时，把它原样传入下一次请求，直到没有 offset；它是分页游标，不是行号。只读了部分数据就应说明范围。空值字段可能不出现在记录响应中，缺少键不等于表里没有该列，应结合 Base schema 判断。

Airtable 的 API 限制包括每个 Base 每秒五次请求，以及 PAT 流量限制。因速率触发 429 时，暂停 30 秒并使用退避重试。持续出现 429 还可能是工作区月度额度耗尽；要检查实际目标 Base 所在的工作区，减少重复全表扫描。

  • 找不到 Base：核对账号、OAuth 授权或 PAT 资源范围、读取作用域和组织 API 政策。
  • 能读不能改：检查写入作用域、协作权限、字段类型，以及字段是否可编辑。
  • 返回多条匹配：停止写入，进一步限定目标，不要随意选第一条。
  • 数量不符合预期：先检查分页和筛选条件，不要直接认定记录丢失。

自托管：分别配置 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 使用 Airtable 吗？

可以。托管 Hermes Agent 和 OpenClaw 共用 Dashboard → Integrations 的接入流程。自部署时，两者也可以连接 Composio MCP，但需要使用各自的框架配置。

应该选择 OAuth 还是 PAT？

以当前连接表单提供的认证方式为准。Composio 支持 Airtable 托管 OAuth2 和 API_KEY；后者填写的是 Personal Access Token，即个人访问令牌，不是已停用的旧 API Key。OAuth 要检查授权页面，PAT 要检查作用域和 Base 访问范围。

为什么 Connected 后仍看不到我的 Base？

检查连接的账号、OAuth 授权的 Base 或 PAT 的资源范围、schema.bases:read，以及账号本身的协作权限。企业组织的 API 访问限制也可能隐藏 Base；必要时请 Airtable 管理员检查。

接入后还会受到费用和 API 限额影响吗？

会。托管服务、模型调用、Composio 和 Airtable 的费用或用量规则分别计算。请查看实际使用服务的当前套餐。第三方集成发出的 Airtable 请求同样消耗工作区 API 额度，接入不会绕过限流。

如何防止重复创建记录？

先按稳定的业务编号查询已有记录，找到后保存 record ID 并更新该记录。只有确认没有匹配记录且批准新增时才创建；请求超时后先读取结果，避免盲目重试。

继续阅读

连接你的 Airtable Base

在托管 Hermes Agent 或 OpenClaw 中验证访问权限，再审核第一条记录更新。

打开集成页面