pipedream-connect（梦想连接）

Pipedream Connect

Use this skill for the OpenClaw Pipedream integration.

Current integration summary

OpenClaw now uses this model:

• Global Pipedream tab = platform credentials only
• Agent Tools → Pipedream = per-agent app connections and activation
• Connected Pipedream apps become first-class agent tools
• Connected apps are discovered live from Pipedream Connect accounts API
• Browse All Apps loads the full dynamic catalog on demand
• Catalog icons come from authenticated Pipedream app metadata (img_src) when available

Key improvements already implemented

1) Connected Pipedream tools are first-class tools

Connected app MCP tools are registered into the agent runtime as normal tools.

This means:

• agents do not need raw mcporter call ... bridge syntax in normal chat use
• tool catalog surfaces connected app tools directly
• execution still routes through per-agent mcporter servers under the hood

Server naming pattern:

pipedream-{externalUserId}-{appSlug}

2) Per-agent connection model

Each agent gets its own Pipedream identity via external_user_id.

Default behavior:

• external_user_id defaults to the agent slug / id
• each agent gets isolated OAuth accounts and MCP tool exposure

Per-agent config path:

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

3) Live connected-account discovery

Agent refresh uses the Pipedream Connect accounts API to discover connected apps live.

Do not assume local config is the source of truth for connected apps if live API access is available.

4) Full app catalog is dynamic

The app browser should use the live full catalog, not a static baked-in list.

Current intended behavior:

• clicking Browse All Apps loads the full catalog dynamically
• do not rely on stale frontend app constants for authoritative app metadata

5) Real app icons now flow from Pipedream metadata

Use authenticated Pipedream app metadata when available so apps can render real icons.

Important detail:

• authenticated app endpoints expose img_src
• public MCP catalog endpoints may not expose equivalent icon metadata on the same path
• UI should render iconUrl when present and fall back safely when missing / broken

Architecture

Global Pipedream tab
  -> save platform credentials
  -> show overall status

Agents -> [Agent] -> Tools -> Pipedream
  -> set / override external user id
  -> connect app
  -> refresh connected accounts
  -> activate connected app MCP tools
  -> browse full dynamic app catalog

Setup workflow

1) Create Pipedream credentials

In Pipedream:

• create an OAuth client
• copy client_id and client_secret
• create / select a project
• copy project_id

2) Configure OpenClaw global credentials

In the OpenClaw dashboard Pipedream tab, save:

• Client ID
• Client Secret
• Project ID
• Environment

Prefer production unless explicitly testing in development.

3) Connect apps per agent

In Agents → [Agent] → Tools → Pipedream:

• verify the external user id
• connect an app
• complete OAuth
• refresh
• activate the app if needed

4) Use the tools normally

After activation, connected MCP tools should appear as ordinary tools for that agent.

Storage and security

Secrets

Store clientId and clientSecret in the OpenClaw vault:

~/.openclaw/secrets.json

Non-secret config

Store non-secret Pipedream config in:

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

Expected non-secret fields:

• projectId
• environment
• externalUserId

Do not keep plaintext client secrets in normal config files.

Runtime behavior to preserve

When editing this integration, preserve these behaviors:

1. Connected apps remain per-agent isolated
2. Connected app tools remain first-class tools in the agent runtime
3. Live API data beats stale local display metadata
4. Browse All Apps uses the dynamic full catalog
5. Icons use img_src / iconUrl when available
6. UI falls back safely if an icon URL fails

Useful RPCs / methods

Common gateway methods involved in this integration include:

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

When documenting or debugging, confirm the exact current implementation in gateway server methods and the agent/global Pipedream UI controllers.

Debugging guidance

Connected app missing

Check in this order:

1. global credentials configured
2. correct project / environment
3. OAuth completed successfully
4. agent external user id is the one you expect
5. refresh calls the live accounts API successfully
6. app activation completed

Tool missing after app connection

Check:

1. connected account is present in pipedream.agent.status
2. mcporter server was created for pipedream-{externalUserId}-{appSlug}
3. runtime tool registration is loading MCP tools into the agent catalog

Wrong / stale icon

Check:

1. whether the catalog path is using authenticated Pipedream app metadata
2. whether img_src is mapped to iconUrl
3. whether UI is rendering from live catalog data or an old static fallback
4. whether fallback rendering is masking an image load failure

Wrong app list behavior

If Browse uses stale frontend constants, prefer the dynamic catalog path instead.

Shell / low-level debugging

For low-level debugging only, mcporter servers follow this pattern:

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

But for normal OpenClaw agent use, prefer the first-class tool path rather than instructing users to call mcporter directly.

Files commonly involved

Check these areas when updating the integration:

• gateway server methods for pipedream.*
• global Pipedream UI view/controller
• agent Pipedream UI view/controller
• runtime tool registration path that imports connected MCP tools into the agent tool registry
• mcporter config write / refresh path

Practical rule

If the question is about:

• credentials or project setup -> global tab
• app connection / activation -> agent tools panel
• tool availability -> runtime MCP tool registration
• icons / catalog display -> dynamic catalog path
• stale metadata -> remove static fallback dependence first