From bcfc9bead5f576fd5db1ab57edff2db96ff7e835 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 17 Jan 2026 00:39:48 +0000 Subject: [PATCH] docs: expand iMessage remote setup --- docs/channels/imessage.md | 48 ++++++++++++++++++++++++++++++++--- docs/gateway/configuration.md | 4 ++- 2 files changed, 48 insertions(+), 4 deletions(-) diff --git a/docs/channels/imessage.md b/docs/channels/imessage.md index d36ed22ef..66cf51670 100644 --- a/docs/channels/imessage.md +++ b/docs/channels/imessage.md @@ -108,7 +108,7 @@ If you want iMessage on another Mac, set `channels.imessage.cliPath` to a wrappe Example wrapper: ```bash #!/usr/bin/env bash -exec ssh -T mac-mini imsg "$@" +exec ssh -T gateway-host imsg "$@" ``` **Remote attachments:** When `cliPath` points to a remote host via SSH, attachment paths in the Messages database reference files on the remote machine. Clawdbot can automatically fetch these over SCP by setting `channels.imessage.remoteHost`: @@ -118,7 +118,7 @@ exec ssh -T mac-mini imsg "$@" channels: { imessage: { cliPath: "~/imsg-ssh", // SSH wrapper to remote Mac - remoteHost: "clawdbot@192.168.64.3", // for SCP file transfer + remoteHost: "user@gateway-host", // for SCP file transfer includeAttachments: true } } @@ -127,6 +127,48 @@ exec ssh -T mac-mini imsg "$@" If `remoteHost` is not set, Clawdbot attempts to auto-detect it by parsing the SSH command in your wrapper script. Explicit configuration is recommended for reliability. +#### Remote Mac via Tailscale (example) +If the Gateway runs on a Linux host/VM but iMessage must run on a Mac, Tailscale is the simplest bridge: the Gateway talks to the Mac over the tailnet, runs `imsg` via SSH, and SCPs attachments back. + +Architecture: +``` +┌──────────────────────────────┐ SSH (imsg rpc) ┌──────────────────────────┐ +│ Gateway host (Linux/VM) │──────────────────────────────────▶│ Mac with Messages + imsg │ +│ - clawdbot gateway │ SCP (attachments) │ - Messages signed in │ +│ - channels.imessage.cliPath │◀──────────────────────────────────│ - Remote Login enabled │ +└──────────────────────────────┘ └──────────────────────────┘ + ▲ + │ Tailscale tailnet (hostname or 100.x.y.z) + ▼ + user@gateway-host +``` + +Concrete config example (Tailscale hostname): +```json5 +{ + channels: { + imessage: { + enabled: true, + cliPath: "~/.clawdbot/scripts/imsg-ssh", + remoteHost: "bot@mac-mini.tailnet-1234.ts.net", + includeAttachments: true, + dbPath: "/Users/bot/Library/Messages/chat.db" + } + } +} +``` + +Example wrapper (`~/.clawdbot/scripts/imsg-ssh`): +```bash +#!/usr/bin/env bash +exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@" +``` + +Notes: +- Ensure the Mac is signed in to Messages, and Remote Login is enabled. +- Use SSH keys so `ssh bot@mac-mini.tailnet-1234.ts.net` works without prompts. +- `remoteHost` should match the SSH target so SCP can fetch attachments. + Multi-account support: use `channels.imessage.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern. Don't commit `~/.clawdbot/clawdbot.json` (it often contains tokens). ## Access control (DMs + groups) @@ -198,7 +240,7 @@ Provider options: - `channels.imessage.enabled`: enable/disable channel startup. - `channels.imessage.cliPath`: path to `imsg`. - `channels.imessage.dbPath`: Messages DB path. -- `channels.imessage.remoteHost`: SSH host for SCP attachment transfer when `cliPath` points to a remote Mac (e.g., `clawdbot@192.168.64.3`). Auto-detected from SSH wrapper if not set. +- `channels.imessage.remoteHost`: SSH host for SCP attachment transfer when `cliPath` points to a remote Mac (e.g., `user@gateway-host`). Auto-detected from SSH wrapper if not set. - `channels.imessage.service`: `imessage | sms | auto`. - `channels.imessage.region`: SMS region. - `channels.imessage.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing). diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index ddae75a13..206a5e9ff 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -1206,6 +1206,7 @@ Clawdbot spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required. enabled: true, cliPath: "imsg", dbPath: "~/Library/Messages/chat.db", + remoteHost: "user@gateway-host", // SCP for remote attachments when using SSH wrapper dmPolicy: "pairing", // pairing | allowlist | open | disabled allowFrom: ["+15555550123", "user@example.com", "chat_id:123"], historyLimit: 50, // include last N group messages as context (0 disables) @@ -1225,11 +1226,12 @@ Notes: - The first send will prompt for Messages automation permission. - Prefer `chat_id:` targets. Use `imsg chats --limit 20` to list chats. - `channels.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. +- For remote SSH wrappers, set `channels.imessage.remoteHost` to fetch attachments via SCP when `includeAttachments` is enabled. Example wrapper: ```bash #!/usr/bin/env bash -exec ssh -T mac-mini "imsg rpc" +exec ssh -T gateway-host imsg "$@" ``` ### `agents.defaults.workspace`