Connectors

Connectors bridge agents to external systems. Most are chat-platform bridges such as WhatsApp, Telegram, Slack, Discord, Matrix, Teams, Google Chat, Signal, Email, BlueBubbles (iMessage), and OpenClaw. SwarmClaw also ships local File Queue connectors for filesystem command handoff and a SwarmDock connector for marketplace work instead of chat delivery.

File Queue

File Queue connectors watch local folders instead of a hosted chat service.

They use:

  • inbox for JSON command envelopes written by external tools
  • outbox for structured JSON replies written by SwarmClaw
  • archive for processed inbound commands
  • errors for malformed or failed commands with diagnostic sidecars

Configure a root directory in the connector sheet or CLI. Relative inbox, outbox, archive, and error paths resolve under that root. If you leave the root empty, SwarmClaw creates a managed queue folder under connector data.

Inbound command envelopes can use fields such as text, body, prompt, or string command. Optional sender, channel, thread, and reply identifiers are preserved when present. Queue traffic uses the same connector route target, session isolation, policy, follow-up, health, and readiness paths as other connectors.

SwarmDock

SwarmDock is a marketplace connector rather than a chat connector.

It lets an agent:

  • register on the SwarmDock marketplace with its Ed25519 identity
  • auto-bid on matching paid work
  • receive assignments as local board tasks
  • submit completed results back to SwarmDock

See SwarmDock for the dedicated setup and operations guide.

Two Surfaces: Connectors vs Inbox

  • Connectors is the setup and administration surface.
  • Inbox is the conversation-review surface for external connector sessions.

This split keeps external sender traffic isolated from the operator's main chat threads.

Session Isolation

For direct external senders:

  • the connector owner or self-chat can stay on the main agent thread
  • other senders get isolated direct connector sessions in Inbox
  • external connector sessions use session-scoped memory by default

This prevents memory and context bleed across multiple WhatsApp or other connector senders.

Access and Ownership

Connectors expose explicit access controls such as:

  • DM policy
  • allow/deny lists
  • owner sender ID
  • pairing approvals and pending requests

These controls are available from both the connector editor and the Inbox access panel.

WhatsApp

WhatsApp connectors support:

  • QR pairing
  • isolated external sender sessions
  • inbound voice-note transcription when STT is configured
  • outbound voice-note delivery through the connector tool path

Delivery hardening prevents duplicate direct replies and false "sent" confirmations when there is no verified delivery evidence.

BlueBubbles (iMessage)

BlueBubbles connectors bridge agents to iMessage through a local BlueBubbles server:

  • webhook-driven inbound message delivery
  • sender handle extraction from iMessage chat GUIDs
  • isolated external sender sessions in Inbox
  • media attachment support for inbound images and files

Requires a running BlueBubbles server with webhook forwarding configured to the SwarmClaw connector webhook endpoint.

Follow-Ups and Schedules

Connector-origin schedule and task follow-ups prefer the originating connector route instead of inferring from the last active chat.

That means:

  • follow-ups stay bound to the correct sender or session
  • archived or cancelled schedule work does not keep sending late connector updates
  • owner-thread schedules no longer leak into the wrong external sender thread

Connector Doctor

Connector Doctor previews routing, access, and policy issues before or after saving a connector.

Useful checks include:

  • not running
  • missing owner or access policy
  • risky DM configuration
  • sample inbound policy issues