feat: add providers CLI and multi-account onboarding

docs/gateway/configuration.md

@@ -260,6 +260,33 @@ Notes:
 - Outbound commands default to account `default` if present; otherwise the first configured account id (sorted).
 - The legacy single-account Baileys auth dir is migrated by `clawdbot doctor` into `whatsapp/default`.
 
+### `telegram.accounts` / `discord.accounts` / `slack.accounts` / `signal.accounts` / `imessage.accounts`
+
+Run multiple accounts per provider (each account has its own `accountId` and optional `name`):
+
+```json5
+{
+  telegram: {
+    accounts: {
+      default: {
+        name: "Primary bot",
+        botToken: "123456:ABC..."
+      },
+      alerts: {
+        name: "Alerts bot",
+        botToken: "987654:XYZ..."
+      }
+    }
+  }
+}
+```
+
+Notes:
+- `default` is used when `accountId` is omitted (CLI + routing).
+- Env tokens only apply to the **default** account.
+- Base provider settings (group policy, mention gating, etc.) apply to all accounts unless overridden per account.
+- Use `routing.bindings[].match.accountId` to route each account to a different agent.
+
 ### `routing.groupChat`
 
 Group messages default to **require mention** (either metadata mention or regex patterns). Applies to WhatsApp, Telegram, Discord, and iMessage group chats.
@@ -560,6 +587,7 @@ Set `web.enabled: false` to keep it off by default.
 
 Clawdbot starts Telegram only when a `telegram` config section exists. The bot token is resolved from `TELEGRAM_BOT_TOKEN` or `telegram.botToken`.
 Set `telegram.enabled: false` to disable automatic startup.
+Multi-account support lives under `telegram.accounts` (see the multi-account section above). Env tokens only apply to the default account.
 
 ```json5
 {
@@ -609,6 +637,7 @@ Retry policy defaults and behavior are documented in [Retry policy](/concepts/re
 ### `discord` (bot transport)
 
 Configure the Discord bot by setting the bot token and optional gating:
+Multi-account support lives under `discord.accounts` (see the multi-account section above). Env tokens only apply to the default account.
 
 ```json5
 {
@@ -728,6 +757,8 @@ Slack runs in Socket Mode and requires both a bot token and app token:
 }
 ```
 
+Multi-account support lives under `slack.accounts` (see the multi-account section above). Env tokens only apply to the default account.
+
 Clawdbot starts Slack when the provider is enabled and both tokens are set (via config or `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`). Use `user:<id>` (DM) or `channel:<id>` when specifying delivery targets for cron/CLI commands.
 
 Reaction notification modes:
@@ -764,10 +795,19 @@ Clawdbot spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required.
 }
 ```
 
+Multi-account support lives under `imessage.accounts` (see the multi-account section above).
+
 Notes:
 - Requires Full Disk Access to the Messages DB.
 - The first send will prompt for Messages automation permission.
 - Prefer `chat_id:<id>` targets. Use `imsg chats --limit 20` to list chats.
+- `imessage.cliPath` can point to a wrapper script (e.g. `ssh` to another Mac that runs `imsg rpc`); use SSH keys to avoid password prompts.
+
+Example wrapper:
+```bash
+#!/usr/bin/env bash
+exec ssh -T mac-mini "imsg rpc"
+```
 
 ### `agent.workspace`
 

docs/providers/discord.md

@@ -106,6 +106,8 @@ Or via config:
 }
 ```
 
+Multi-account support: use `discord.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
+
 #### Allowlist + channel routing
 Example “single server, only allow me, only allow #help”:
 

docs/providers/imessage.md

@@ -19,11 +19,28 @@ Status: external CLI integration. Gateway spawns `imsg rpc` (JSON-RPC over stdio
 - macOS with Messages signed in.
 - Full Disk Access for Clawdbot + `imsg` (Messages DB access).
 - Automation permission when sending.
+ - `imessage.cliPath` can point to a wrapper script (for example, an SSH hop to another Mac that runs `imsg rpc`).
 
 ## Setup (fast path)
 1) Ensure Messages is signed in on this Mac.
 2) Configure iMessage and start the gateway.
 
+### Remote/SSH variant (optional)
+If you want iMessage on another Mac, set `imessage.cliPath` to a wrapper that
+execs `ssh` and runs `imsg rpc` on the remote host. Clawdbot only needs a
+stdio stream; `imsg` still runs on the remote macOS host.
+
+Example wrapper (save somewhere in your PATH and `chmod +x`):
+```bash
+#!/usr/bin/env bash
+exec ssh -T mac-mini "imsg rpc"
+```
+
+Notes:
+- Remote Mac must have Messages signed in and `imsg` installed.
+- Full Disk Access + Automation prompts happen on the remote Mac.
+- Use SSH keys (no password prompt) so the gateway can launch `imsg rpc` unattended.
+
 Example:
 ```json5
 {
@@ -36,6 +53,8 @@ Example:
 }
 ```
 
+Multi-account support: use `imessage.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
+
 ## Access control (DMs + groups)
 DMs:
 - Default: `imessage.dmPolicy = "pairing"`.

docs/providers/signal.md

@@ -39,6 +39,8 @@ Example:
 }
 ```
 
+Multi-account support: use `signal.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
+
 ## Access control (DMs + groups)
 DMs:
 - Default: `signal.dmPolicy = "pairing"`.

docs/providers/slack.md

@@ -22,6 +22,8 @@ read_when: "Setting up Slack or debugging Slack socket mode"
 
 Use the manifest below so scopes and events stay in sync.
 
+Multi-account support: use `slack.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
+
 ## Manifest (optional)
 Use this Slack app manifest to create the app quickly (adjust the name/command if you want).
 

docs/providers/telegram.md

@@ -29,6 +29,8 @@ Status: production-ready for bot DMs + groups via grammY. Long-polling by defaul
 }
 ```
 
+Multi-account support: use `telegram.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
+
 3) Start the gateway. Telegram starts when a `telegram` config section exists and a token is resolved.
 4) DM access defaults to pairing. Approve the code when the bot is first contacted.
 5) For groups: add the bot, disable privacy mode (or make it admin), then set `telegram.groups` to control mention gating + allowlists.