OHarness
下载

云端连接器

connector-cloud 是 OHarness 的一个架构插件，不是 MCP。Cloud 持有 Composio 项目 key 以及经过批准的应用/工具配置。客户端使用自己的 OHarness 登录；Gmail 的 OAuth 凭据留在 Composio，并限定于服务端验证过的 OHarness 用户 ID。不需要新建任何 Supabase 表。

配置

  • Cloud 网站的运行时密钥：COMPOSIO_API_KEY。绝不能用 NEXT_PUBLIC_ 前缀，也绝不能放进用户的 config.json、plugins.json、浏览器打包文件或模型上下文。
  • 启用哪些应用，是从 Composio 项目里的 Auth Config 推导出来的，而不是来自某个文件。一个带有工具限制的 Auth Config 就是一个已启用的应用，那个限制就是它的允许列表，所以新增一个集成只需在控制台操作，而不用重新部署。推导时宁可拒绝也不做假设：没有限制任何工具的配置会被跳过（Composio 会把缺失的限制理解为该工具包的全部工具），同一个工具包有两个已启用的配置时两个都不启用，被禁用的配置、不可用的 id 或格式错误的工具名会让该应用被剔除。20 个应用和 40 个工具的上限不变。这个集合在每个进程中只解析一次，所以在控制台改动后要重启 Cloud。
  • Cloud 的 website/connectors.json 现在是可选的，而且只能收窄范围：{"disabled": ["slug"]} 可以在不动 Composio 的情况下屏蔽一个应用。仍带有 toolkits 的文件会保持旧的显式行为。部署时也可以把 OHARNESS_CONNECTORS_FILE 指向一个挂载的绝对路径。它有意被加入了 gitignore，所以只有在用到时才需要打包或挂载。
  • 现有的网站 Supabase 环境负责验证 OHarness 登录 token。
  • 客户端 cloud.json：本地开发时可选写 { "siteUrl": "http://localhost:4000" }；默认是公开的 Cloud 地址。更换 Cloud 源可能需要重新登录。OHARNESS_SITE_URL 是另一种覆盖方式。
  • 客户端 plugins.json：默认插件不需要任何配置项。要禁用它：{ "runtimePlugins": [{ "id": "connector-cloud", "enabled": false }] }。

在 Composio 控制台中，为与 API key 相同的项目创建 Gmail OAuth Auth Config。检查它的权限范围，读取类任务使用只读的 Gmail 访问权限；执行允许列表不能替代最小权限的 OAuth 范围。示例配置里是占位符，不是可用的凭据。

使用 OHarness_Cloud/dev.sh 时，Cloud 相关变量要设置在 website 进程上（Next 会加载 website/.env.development.local）。harness 不需要 Composio key。启动 harness 前把它指向本地网站，例如 OHARNESS_SITE_URL=http://localhost:4000 ./dev.sh up harness。up 不会重启正在运行的进程；保存改动后用 restart website harness。在 localhost 上修改 Cloud 不会把 API 部署到公开网站。

对话流程

  1. Agent 调用 cloud_app_tools 列出应用，或发现某个应用确切的工具 schema/版本。即使还没有连接任何应用账号，它也可以使用。
  2. 先执行常规的 OHarness 权限策略。如果已批准但尚未绑定，当前工具会等待，Web 聊天界面显示连接 / 取消。
  3. 只有用户点击「连接」才会请求 Composio 托管链接。Cloud 根据已验证的登录设置 user_id，绝不取自模型输入。
  4. 界面打开授权页面。本地代理轮询 Cloud；Cloud 到 Composio 检查账号所有者、Auth Config、工具包以及活动/未禁用状态。
  5. 验证成功后，等待中的工具会在同一轮 Agent 中继续。它先发现 schema，然后通过常规的权限关卡调用 cloud_app_execute。不会产生重复的用户提示，也不会创建新的自主任务。

免费账号可以连接并使用两个应用；任何付费方案——包括 Plus，无论是个人的还是团队的，从会话 token 的 ent 声明中读取——都没有限制。额度分配给最先连接的应用：关联第三个应用，或者在前两个之外的应用上运行工具（比如方案到期之后），会被以 402 plan_required 拒绝，harness 会把它转成一条指向价格页面的消息。列出应用和检查连接永远不受限制。网站用 OHARNESS_FREE_CONNECTOR_APPS 设置这个数量；自托管的网站可以设置 OHARNESS_CONNECTORS_FREE=1，为所有已登录账号解除限制。

如果之前连接的账号被撤销，执行会在调用之前返回明确的 connection_required 拒绝，从而触发同样的流程。超时、厂商错误或结果不确定的执行失败永远不会被自动重放。进程存活期间，刷新 Web 页面会重放待处理的卡片状态。

安全性与 V1 边界

  • 只有四个原生客户端 POST 端点：目录、状态、链接和执行。认证链接只留在界面响应中，不进入模型输出和会话记录存储。
  • 待处理的交互会固定已验证的用户和 Cloud 源。切换登录后，无法用另一个账号恢复旧用户的授权任务。
  • 元数据和执行使用同一个具体的工具版本。如果服务器重启后 latest 解析出了不同的结果，就重新发现，而不是执行过期的 schema。需要可复现的部署时，请使用带日期的版本。
  • 取消、Agent 中止、十分钟超时和关闭都会停止等待中的调用。被取消的任务不会撤销一次独立完成的 OAuth 授权。
  • 不支持进程重启后的续接，也不支持后台任务重放。重启后，开始新的一轮；已经完成的 Composio 绑定仍然可以被发现。
  • V1 假设每个应用/Auth Config/用户只有一个活动账号。存在多个活动账号时会失败即拒绝，等待管理员选择。不支持共享账号，也没有 ACL 界面。
  • 卡片目前在 Web 聊天中渲染（包括桌面版里的 Web 界面），不在终端/无头界面中渲染。那些界面没有卡片 UI；首次绑定请使用 Web，或在无人值守/无头运行时禁用此插件。
  • 每个进程都有基本的速率限制。生产环境必须加上共享的边缘限流、审计/保留策略，并配置范围恰当的 OAuth Auth Config。

验证

npm run test:cloud-connectors 覆盖代理取消、并发、超时、权限拒绝，以及一个真实 Agent 在模拟授权后继续执行。Cloud 的 npm run test:composio 覆盖归属、允许列表、版本、撤销和不重试行为。node --conditions=oharness-source script/cloud-connector-ui-demo.ts 会启动一个隔离的离线 Web 演示；它永远不会访问真实的 Gmail。真实的 OAuth 仍然需要用户在浏览器中同意。

← Composio 插件记忆与同步 →