OHarness
下载

Composio 插件

connector-composio 是一个普通的 OHarness RuntimePlugin。它使用 Composio 官方 REST API 来查看账号、发现 schema 和执行工具。它不引入 MCP、另一个 Agent 循环、第二个插件宿主，也不依赖任何 SDK。createConnectorPlugin 仍然是与厂商无关的适配辅助函数。

范围与验证

  • 已实现：显式的工具允许列表、账号/用户绑定、schema 转换、版本固定、取消、响应大小限制，以及 OHarness 权限关卡。
  • 已实现：由人工显式操作的托管认证链接创建和账号状态查询。
  • 未实现：Pipedream、webhook、共享账号 ACL、OHarness Cloud 中的 OAuth 回调身份自动验证、远程插件安装、文件上传/下载自动化，以及运行时热重载。
  • 测试使用模拟的 HTTP 响应，不需要任何凭据。真实账号的冒烟测试需要另行用你自己的凭据并在你同意的前提下进行。

Composio 建议新的 agent 集成使用 Sessions，并把直接执行标为旧方式。这个首版适配器有意使用仍有文档的直接执行端点，以便让现有的 OHarness 工具注册表和逐工具权限继续掌控局面。只暴露被明确选中的工具，而不是一个能调用任意操作的通用路由。参见官方的直接执行指南。

这个直连适配器用于显式配置的开发/自托管场景。在托管产品中，平台的 Composio key 属于 Cloud，而不是每个客户端。托管产品请使用 Cloud 连接器：它提供授权卡片、服务端验证的用户绑定和任务续接。

1. 设置项目 API key

在运行 OHarness 的进程环境中设置 COMPOSIO_API_KEY。不要把它放进代码仓库、聊天消息或插件 JSON。配置里可以通过 apiKeyEnv 指定另一个环境变量名。

传输层只会把这个 key 发送到 https://backend.composio.dev，拒绝 HTTP 重定向，也不接受可配置的 API 源。所有远程调用都是显式的客户端请求；构造或导入插件本身不会发起任何调用。

2. 查看已经连接了什么

配置中的每个工具包条目都需要一个 connectedAccountId，所以第一个问题是你是否已经有了一个：

npm run composio:auth -- list --user YOUR_USER_ID

只读、限定于该用户、分页返回——传 --toolkit SLUG 缩小范围，--limit N（1-100，默认 50）设置每页大小，--cursor 配合上一次调用返回的 cursor 翻页。它为每个账号只打印 id、toolkit、status 和 disabled，别无其他：上游返回的行里带有凭据和状态字段，这个命令会像账号查看那样把它们去掉。

列在其他用户名下的账号会被拒绝，而不是被隐藏，因为一个混杂了多个用户的响应，即便是匹配上的那些行也不值得信任。

3. 连接账号

如果列表为空，或者缺少你需要的工具包，就先在 Composio 里为该应用创建一个认证配置，然后在仓库里显式请求一个托管的 Connect Link：

npm run composio:auth -- link --user YOUR_USER_ID --auth-config ac_YOUR_AUTH_CONFIG

这个命令会发起一次远程 POST，并打印 redirectUrl、connectedAccountId 以及可选的过期时间。自己打开那个 URL 并完成授权同意。把它当作私密的授权链接：不要分享给其他用户。这个命令不会打开浏览器、批准访问、保存配置，也不会向 Agent 暴露创建链接的工具。

用一个只读请求查看生成的连接：

npm run composio:auth -- status --user YOUR_USER_ID --account ca_YOUR_ACCOUNT

当状态为 ACTIVE、工具包正确且 disabled 为 false 时再继续。关联和执行要使用同一个用户 ID。适配器会有意拒绝属于其他用户的账号，即使项目 API key 能访问它。账号查看永远不会返回凭据/状态字段。

对于多用户的托管产品，要从经过认证的应用状态中推导出 userId，并创建相应隔离的 Harness 实例。不要把它当作模型输入来接受。Composio 可选的回调身份验证需要你的应用中有一个经过认证的 HTTPS 验证端；这个本地适配器不实现那个服务。参见官方的连接与回调身份文档。

4. 启用插件

构建工作区（npm run build），然后在你的用户 OHarness 插件文件中添加一项，通常是 ~/.oharness/plugins.json（或 $OHARNESS_HOME/plugins.json）。替换模块路径、用户 ID 和账号 ID；不要原样复制占位符。

{
  "runtimePlugins": [
    {
      "id": "connector-composio",
      "module": "/absolute/path/to/OHarness/packages/engine/dist/runtime-plugins/composio/index.js",
      "enabled": true,
      "required": false,
      "config": {
        "userId": "YOUR_USER_ID",
        "apiKeyEnv": "COMPOSIO_API_KEY",
        "timeoutMs": 30000,
        "toolkits": [
          {
            "slug": "gmail",
            "connectedAccountId": "ca_YOUR_ACCOUNT",
            "version": "latest",
            "tools": ["GMAIL_GET_PROFILE"]
          }
        ]
      }
    }
  ]
}

required: false 让这个可选连接器启动失败时 OHarness 依然可用；失败信息会显示在 /plugins 和 Web 的插件列表中。只有在没有这个连接器就必须启动失败时，才把它设为 true。项目配置不能启用可执行插件，也不能替换它们受信任的账号配置。

嵌入时，直接使用同一个实现：

import { Harness, composioPlugin, jsonlAuditPlugin } from "@oharness/engine";

const harness = await Harness.create({
  runtimePlugins: [
    {
      plugin: composioPlugin,
      config: {
        userId: authenticatedUserId,
        toolkits: [{
          slug: "gmail", connectedAccountId: approvedAccountId,
          version: "latest", tools: ["GMAIL_GET_PROFILE"],
        }],
      },
    },
    { plugin: jsonlAuditPlugin, config: { path: "/absolute/path/to/audit.jsonl" } },
  ],
});
// Use the existing Session / Agent API, then await harness.close().

执行语义

  1. 启动时验证每个已配置的账号属于配置中的用户、拥有配置中的工具包，且处于活动/未禁用状态。
  2. 只获取列出名字的工具 slug；最多 20 个工具包、共 40 个工具。
  3. 返回的 slug/工具包必须与允许列表一致。latest 会在启动时解析为一个具体的带日期版本，并在执行时复用。配置中写明的带日期版本必须与返回的 schema 版本完全一致。
  4. 工具注册为 composio__SLUG。超过 64 个字符的名字会被缩短，并加上稳定的哈希后缀。确切的名字可以在 ToolRegistry 中看到。
  5. 调用经过 OHarness 的常规权限引擎。所有 Composio 工具都是 readOnly: false 和 sessionLocal: false，即使是远程读取操作也是如此。只有当你常规的显式权限策略允许时，才会跳过批准。
  6. 每次执行前，都会再次检查账号归属、状态和工具包。POST 请求体使用受信任的用户/账号和固定的版本；模型参数嵌套在 arguments 之下，无法替换这些字段。
  7. 成功返回的数据会转换为 ToolResult，进入常规的 Agent 流程和执行审计。HTTP/API 失败会变成工具错误。

工具输入必须是一个对象。详细的参数 schema 校验由 Composio 完成；返回的 JSON Schema 会提供给模型。只支持显式的工具实现，不支持代理执行、自定义认证覆盖、自然语言执行或任意远程 URL。这个适配器不会读取或上传任何本地文件。

所有 HTTP 调用都不会自动重试。一次被取消或失败的 POST 可能已经执行了远程操作：重试之前，先去外部服务或 Composio 日志里确认。单次请求超时默认 30 秒，可在 100 ms 到 120 秒之间配置。响应上限为 2 MiB。原始错误正文和 API key 不会写入日志；成功返回的数据仍属于敏感的应用数据，并按设计对 Agent 可见。

最早的账号/元数据请求发生在插件于启动时被启用的时候；初始化不会创建新账号，也不会执行任何允许列表中的操作。

使用的官方 API 约定

适配器针对的是 backend.composio.dev 上有文档的 /api/v3 路由。这些已于 2026-09-02 对照官方文档核实过；HTTP 约定测试并不能证明真实账号的授权或厂商服务的可用性。

← 插件云端连接器 →