Pipedream Connect

此技能用于 OpenClaw 的 Pipedream 集成。

当前集成概览

OpenClaw 当前使用以下模型：

• 全局 Pipedream 页签 = 仅平台级凭据
• Agent Tools → Pipedream = 按 Agent 级别的应用连接与启用
• 已连接的 Pipedream 应用将成为一级 Agent 工具
• 已连接的应用通过 Pipedream Connect 账户 API 实时发现
• “浏览全部应用”按需加载完整的动态应用目录
• 目录图标在可用时，直接来自已认证的 Pipedream 应用元数据（img_src）

已实现的关键改进

1) 已连接的 Pipedream 工具为一级工具

已连接应用的 MCP 工具将以常规方式注册至 Agent 运行时环境。

这意味着：

• 在常规聊天交互中，Agent 无需 使用原始的 mcporter call ... 桥接语法
• 工具目录将直接呈现已连接应用的工具
• 执行仍会在底层经由各 Agent 对应的 mcporter 服务路由

服务器命名模式：

pipedream-{externalUserId}-{appSlug}

2) 按 Agent 的连接模型

每个 Agent 均通过 external_user_id 拥有独立的 Pipedream 身份。

默认行为：

• external_user_id 默认取值为 Agent 的 slug / id
• 每个 Agent 拥有隔离的 OAuth 账户及 MCP 工具可见性

按 Agent 的配置路径：

~/.openclaw/workspace/config/integrations/pipedream/{agentId}.json

3) 实时连接账户发现

Agent 刷新操作调用 Pipedream Connect 账户 API，实时发现已连接的应用。

若具备实时 API 访问能力，则不应将本地配置视为已连接应用的唯一可信来源。

4) 完整应用目录为动态生成

应用浏览器应使用实时的完整目录，而非静态硬编码列表。

当前预期行为：

• 点击 浏览全部应用 将动态加载完整目录
• 不应依赖陈旧的前端应用常量作为权威的应用元数据来源

5) 真实应用图标现由 Pipedream 元数据提供

在可用时，使用已认证的 Pipedream 应用元数据，使应用可渲染真实图标。

重要细节：

• 已认证的应用端点暴露 img_src
• 公开的 MCP 目录端点可能不会在相同路径下暴露等效的图标元数据
• UI 应在 iconUrl 存在时渲染该 URL；若缺失或加载失败，须安全降级

架构

全局 Pipedream 页签
  -> 保存平台凭据
  -> 显示整体状态

Agents -> [Agent] -> Tools -> Pipedream
  -> 设置 / 覆盖 external user id
  -> 连接应用
  -> 刷新已连接账户
  -> 启用已连接应用的 MCP 工具
  -> 浏览完整的动态应用目录

设置工作流

1) 创建 Pipedream 凭据

在 Pipedream 中：

• 创建一个 OAuth 客户端
• 复制 client_id 和 client_secret
• 创建或选择一个项目
• 复制 project_id

2) 配置 OpenClaw 全局凭据

在 OpenClaw 控制台的 Pipedream 页签中，保存以下信息：

• Client ID
• Client Secret
• Project ID
• Environment

除非明确在开发环境中测试，否则优先使用 production。

3) 按 Agent 连接应用

在 Agents → [Agent] → Tools → Pipedream 中：

• 验证 external user id
• 连接一个应用
• 完成 OAuth 授权流程
• 刷新账户列表
• 如需，启用该应用

4) 正常使用这些工具

启用后，已连接的 MCP 工具将作为该 Agent 的普通工具出现。

存储与安全

密钥（Secrets）

将 clientId 和 clientSecret 存储于 OpenClaw 密钥库中：

~/.openclaw/secrets.json

非密钥配置项

将非密钥类的 Pipedream 配置存储于：

~/.openclaw/workspace/config/pipedream-credentials.json

预期的非密钥字段包括：

• projectId
• environment
• externalUserId

切勿将明文 client secrets 保留在常规配置文件中。

需保留的运行时行为

修改此集成时，请确保维持以下行为：

1. 已连接应用保持按 Agent 隔离
2. 已连接应用的工具在 Agent 运行时中继续保持一级工具地位
3. 实时 API 数据优先于陈旧的本地展示元数据
4. “浏览全部应用”使用动态完整目录
5. 图标在可用时优先使用 img_src / iconUrl
6. 若图标 URL 加载失败，UI 必须安全降级

常用 RPC / 方法

本集成涉及的常见网关方法包括：

• pipedream.status
• pipedream.saveCredentials
• pipedream.catalog
• pipedream.connect
• pipedream.disconnect
• pipedream.activate
• pipedream.test
• pipedream.agent.status
• pipedream.agent.save
• pipedream.agent.delete

在文档编写或调试过程中，请以网关服务器方法及 Agent/全局 Pipedream UI 控制器中的实际实现为准。

调试指南

已连接应用缺失

请按如下顺序排查：

1. 全局凭据是否已配置
2. 项目与环境是否正确
3. OAuth 是否成功完成
4. Agent 的 external user id 是否符合预期
5. 刷新操作是否成功调用实时账户 API
6. 应用启用是否已完成

应用连接后工具缺失

请检查：

1. pipedream.agent.status 中是否存在该已连接账户
2. 是否已为 pipedream-{externalUserId}-{appSlug} 创建对应的 mcporter 服务
3. 运行时工具注册逻辑是否已将 MCP 工具加载进 Agent 工具目录

图标错误 / 陈旧

请检查：

1. 目录路径是否使用了已认证的 Pipedream 应用元数据
2. img_src 是否已映射至 iconUrl
3. UI 渲染是否基于实时目录数据，而非旧的静态回退方案
4. 回退渲染是否掩盖了图像加载失败问题

应用列表行为异常

若“浏览”功能依赖陈旧的前端常量，请改用动态目录路径。

Shell / 底层调试

仅限底层调试：mcporter 服务遵循如下模式：

mcporter call pipedream-main-gmail.gmail-find-email 
  instruction="Find unread emails from today"

但对常规 OpenClaw Agent 使用场景，应优先采用一级工具路径，而非指导用户直接调用 mcporter。

常涉及的文件

更新该集成时，请检查以下区域：

• 网关服务器中 pipedream.* 相关方法
• 全局 Pipedream 的 UI 视图 / 控制器
• Agent 级 Pipedream 的 UI 视图 / 控制器
• 将已连接 MCP 工具导入 Agent 工具注册表的运行时工具注册路径
• mcporter 配置写入 / 刷新路径

实用规则

若问题涉及：

• 凭据或项目设置 → 查看全局页签
• 应用连接 / 启用 → 查看 Agent Tools 面板
• 工具可用性 → 查看运行时 MCP 工具注册逻辑
• 图标 / 目录显示 → 查看动态目录路径
• 陈旧元数据 → 首先移除对静态回退方案的依赖