iMessage (legacy: imsg)¶

Anbefalet: Brug BlueBubbles til nye iMessage-opsætninger.

Kanalen imsg er en ældre ekstern CLI-integration og kan blive fjernet i en fremtidig version.

Status: ældre ekstern CLI integration. Gateway spawns imsg rpc (JSON-RPC over stdio).

Hurtig opsætning (begynder)¶

Sørg for, at Beskeder er logget ind på denne Mac.
Installér imsg: - brew install steipete/tap/imsg
Konfigurér OpenClaw med channels.imessage.cliPath og channels.imessage.dbPath.
Start gatewayen, og godkend eventuelle macOS-prompter (Automation + Fuld diskadgang).

Minimal konfiguration:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/<you>/Library/Messages/chat.db",
    },
  },
}

Hvad det er¶

iMessage-kanal baseret på imsg på macOS.
Deterministisk routing: svar går altid tilbage til iMessage.
DMs deler agentens hovedsession; grupper er isolerede (agent:<agentId>:imessage:group:<chat_id>).
Hvis en tråd med flere deltagere ankommer med is_group=false, kan du stadig isolere den ved chat_id med channels.imessage.groups (se “Gruppe-agtige tråde” nedenfor).

Konfigurationsskrivninger¶

Som standard må iMessage skrive konfigurationsopdateringer udløst af /config set|unset (kræver commands.config: true).

Deaktivér med:

{
  channels: { imessage: { configWrites: false } },
}

Krav¶

macOS med Beskeder logget ind.
Fuld diskadgang til OpenClaw + imsg (adgang til Beskeder-databasen).
Automation-tilladelse ved afsendelse.
channels.imessage.cliPath kan pege på enhver kommando, der proxyer stdin/stdout (for eksempel et wrapper-script, der SSH’er til en anden Mac og kører imsg rpc).

Fejlfinding af macOS Privacy and Security TCC¶

Hvis afsendelse/modtagelse fejler (for eksempel hvis imsg rpc afslutter med en ikke-nul status, får timeout, eller gatewayen ser ud til at hænge), er en almindelig årsag en macOS-tilladelsesprompt, der aldrig blev godkendt.

macOS giver TCC tilladelser pr. app / proces kontekst. Godkend prompter i samme sammenhæng, der kører imsg (for eksempel, Terminal/iTerm, en LaunchAgent session, eller en SSH-lanceret proces).

Tjekliste:

Fuld Disk Access: give adgang til den proces, der kører OpenClaw (og enhver shell/SSH-indpakning, der udfører imsg). Dette er nødvendigt for at læse Messages database (chat.db).
Automation → Beskeder: tillad processen, der kører OpenClaw (og/eller din terminal), at styre Messages.app for udgående afsendelser.
imsg CLI-sundhed: verificér at imsg er installeret og understøtter RPC (imsg rpc --help).

Tip: Hvis OpenClaw kører hovedløst (LaunchAgent/systemd/SSH) kan MacOS-prompten være nem at gå glip af. Kør en engangs interaktiv kommando i en GUI terminal for at tvinge prompten, og prøv derefter igen:

imsg chats --limit 1
# or
imsg send <handle> "test"

Relaterede macOS-mappetilladelser (Skrivebord/Dokumenter/Downloads): /platforms/mac/permissions.

Opsætning (hurtig vej)¶

Sørg for, at Beskeder er logget ind på denne Mac.
Konfigurér iMessage og start gatewayen.

Dedikeret bot-macOS-bruger (for isoleret identitet)¶

Hvis du vil have, at botten sender fra en separat iMessage-identitet (og holde dine personlige Beskeder rene), så brug et dedikeret Apple-id + en dedikeret macOS-bruger.

Opret et dedikeret Apple-id (eksempel: my-cool-bot@icloud.com). - Apple kan kræve et telefonnummer til verifikation / 2FA.
Opret en macOS-bruger (eksempel: openclawhome) og log ind på den.
Åbn Beskeder i den macOS-bruger, og log ind på iMessage med bot-Apple-id’et.
Aktivér Fjernlogin (Systemindstillinger → Generelt → Deling → Fjernlogin).
Installér imsg: - brew install steipete/tap/imsg
Opsæt SSH, så ssh <bot-macos-user>@localhost true fungerer uden adgangskode.
Peg channels.imessage.accounts.bot.cliPath på en SSH-wrapper, der kører imsg som bot-brugeren.

Første-run note: Afsendelse/modtagelse kan kræve GUI-godkendelse - Fuld Disk Access) i bot macOS user. If imsg rpc looks stuck or exits, log ind på denne bruger (Screen Sharing helps), køre en engangs imsg chats -- limit 1 / imsg send . ., godkende prompter, derefter prøve igen. Se Fejlfinding af macOS Privacy and Security TCC.

Eksempel på wrapper (chmod +x). Erstat <bot-macos-user> med dit faktiske macOS brugernavn:

#!/usr/bin/env bash
set -euo pipefail

# Run an interactive SSH once first to accept host keys:
#   ssh <bot-macos-user>@localhost true
exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
  "/usr/local/bin/imsg" "$@"

Eksempelkonfiguration:

{
  channels: {
    imessage: {
      enabled: true,
      accounts: {
        bot: {
          name: "Bot",
          enabled: true,
          cliPath: "/path/to/imsg-bot",
          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db",
        },
      },
    },
  },
}

For opsætninger med én konto, brug flade indstillinger (channels.imessage.cliPath, channels.imessage.dbPath) i stedet for accounts-kortet.

Fjern-/SSH-variant (valgfrit)¶

Hvis du vil have iMessage på en anden Mac, skal du indstille channels.imessage.cliPath til en wrapper, der kører imsg på den eksterne macOS vært over SSH. OpenClaw behøver kun stdio.

Eksempel-wrapper:

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Fjernvedhæftede filer: Når cliPath peger på en fjernvært via SSH, vedhæftede stier i Messages database referencefilerne på fjernmaskinen. OpenClaw kan automatisk hente disse over SCP ved at indstille channels.imessage.remoteHost:

{
  channels: {
    imessage: {
      cliPath: "~/imsg-ssh", // SSH wrapper to remote Mac
      remoteHost: "user@gateway-host", // for SCP file transfer
      includeAttachments: true,
    },
  },
}

Hvis remoteHost ikke er angivet, forsøger OpenClaw at auto-detektere det ved at parse SSH-kommandoen i dit wrapper script. Eksplicit konfiguration anbefales for pålidelighed.

Fjern-Mac via Tailscale (eksempel)¶

Hvis Gateway kører på en Linux-vært/VM, men iMessage skal køre på en Mac, er Tailscale den enkleste bro: Gatewayen taler med Mac’en over tailnettet, kører imsg via SSH og SCP’er vedhæftninger tilbage.

Arkitektur:

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#ffffff',
    'primaryTextColor': '#000000',
    'primaryBorderColor': '#000000',
    'lineColor': '#000000',
    'secondaryColor': '#f9f9fb',
    'tertiaryColor': '#ffffff',
    'clusterBkg': '#f9f9fb',
    'clusterBorder': '#000000',
    'nodeBorder': '#000000',
    'mainBkg': '#ffffff',
    'edgeLabelBackground': '#ffffff'
  }
}}%%
flowchart TB
 subgraph T[" "]
 subgraph Tailscale[" "]
    direction LR
      Gateway["<b>Gateway host (Linux/VM)<br></b><br>openclaw gateway<br>channels.imessage.cliPath"]
      Mac["<b>Mac med Beskeder + imsg<br></b><br>Beskeder logget ind<br>Fjernlogin aktiveret"]
  end
    Gateway -- SSH (imsg rpc) --> Mac
    Mac -- SCP (vedhæftninger) --> Gateway
    direction BT
    User["user@gateway-host"] -- "Tailscale tailnet (værtsnavn eller 100.x.y.z)" --> Gateway
end

Konkret konfigurationseksempel (Tailscale-værtsnavn):

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

Eksempel-wrapper (~/.openclaw/scripts/imsg-ssh):

#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Noter:

Sørg for, at Mac’en er logget ind i Beskeder, og at Fjernlogin er aktiveret.
Brug SSH-nøgler, så ssh bot@mac-mini.tailnet-1234.ts.net fungerer uden prompter.
remoteHost bør matche SSH-målet, så SCP kan hente vedhæftninger.

Multi-konto support: brug channels.imessage.accounts med per-konto konfiguration og valgfri navn. Se gateway/configuration for det delte mønster. Ikke begå ~/.openclaw/openclaw.json (det indeholder ofte tokens).

Adgangskontrol (DMs + grupper)¶

DMs:

Standard: channels.imessage.dmPolicy = "pairing".
Ukendte afsendere modtager en parringskode; beskeder ignoreres, indtil de godkendes (koder udløber efter 1 time).
Godkend via:
openclaw pairing list imessage
openclaw pairing approve imessage <CODE>
Parring er standard token udveksling for iMessage DMs. Detaljer: Pairing

Grupper:

channels.imessage.groupPolicy = open | allowlist | disabled.
channels.imessage.groupAllowFrom styrer, hvem der kan trigge i grupper, når allowlist er sat.
Mention-gating bruger agents.list[].groupChat.mentionPatterns (eller messages.groupChat.mentionPatterns), fordi iMessage ikke har native mention-metadata.
Multi-agent override: sæt mønstre pr. agent på agents.list[].groupChat.mentionPatterns.

Sådan virker det (adfærd)¶

imsg streamer beskedhændelser; gatewayen normaliserer dem til den fælles kanal-konvolut.
Svar routes altid tilbage til samme chat-id eller handle.

Gruppe-agtige tråde (`is_group=false`)¶

Nogle iMessage-tråde kan have flere deltagere, men stadig ankomme med is_group=false, afhængigt af hvordan Beskeder gemmer chat-identifikatoren.

Hvis du eksplicit konfigurerer et chat_id under channels.imessage.groups, behandler OpenClaw den tråd som en “gruppe” for:

sessionsisolering (separat agent:<agentId>:imessage:group:<chat_id>-sessionsnøgle)
gruppe-tilladelsesliste / mention-gating-adfærd

Eksempel:

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "42": { requireMention: false },
      },
    },
  },
}

Dette er nyttigt, når du ønsker en isoleret personlighed/model for en bestemt tråd (se Multi-agent routing). For isolering af filsystemet, se Sandboxing.

Medier + grænser¶

Valgfri indlæsning af vedhæftninger via channels.imessage.includeAttachments.
Medieloft via channels.imessage.mediaMaxMb.

Begrænsninger¶

Udgående tekst opdeles i bidder på channels.imessage.textChunkLimit (standard 4000).
Valgfri linjeskift-opdeling: sæt channels.imessage.chunkMode="newline" til at splitte på tomme linjer (afsnitsgrænser) før længdeopdeling.
Medieuploads er begrænset af channels.imessage.mediaMaxMb (standard 16).

Adressering / leveringsmål¶

Foretræk chat_id for stabil routing:

chat_id:123 (foretrukket)
chat_guid:...
chat_identifier:...
direkte handles: imessage:+1555 / sms:+1555 / user@example.com

List chats:

imsg chats --limit 20

Konfigurationsreference (iMessage)¶

Fuld konfiguration: Konfiguration

Udbyderindstillinger:

channels.imessage.enabled: aktivér/deaktivér kanalopstart.
channels.imessage.cliPath: sti til imsg.
channels.imessage.dbPath: sti til Beskeder-databasen.
channels.imessage.remoteHost: SSH vært for SCP vedhæftet fil overførsel, når cliPath peger på en ekstern Mac (fx, user@gateway-host). Auto-detekteret fra SSH-indpakning, hvis ikke angivet.
channels.imessage.service: imessage | sms | auto.
channels.imessage.region: SMS-region.
channels.imessage.dmPolicy: pairing | allowlist | open | disabled (standard: pairing).
channels.imessage.allowFrom: DM allowlist (håndtag, e-mails, E.164 numre, eller chat_id:*). open kræver "*". iMessage har ingen brugernavne; brug håndtag eller chat mål.
channels.imessage.groupPolicy: open | allowlist | disabled (standard: tilladelsesliste).
channels.imessage.groupAllowFrom: gruppesender-tilladelsesliste.
channels.imessage.historyLimit / channels.imessage.accounts.*.historyLimit: max gruppebeskeder til at omfatte som kontekst (0 disables).
channels.imessage.dmHistoryLimit: DM historik grænse i bruger sving. Per-user tilsidesættelser: channels.imessage.dms["<handle>"].historyLimit.
channels.imessage.groups: standarder pr. gruppe + tilladelsesliste (brug "*" for globale standarder).
channels.imessage.includeAttachments: indlæs vedhæftninger i kontekst.
channels.imessage.mediaMaxMb: ind-/udgående medieloft (MB).
channels.imessage.textChunkLimit: udgående chunk-størrelse (tegn).
channels.imessage.chunkMode: length (standard) eller newline for at splitte på tomme linjer (afsnitsgrænser) før længdeopdeling.

Relaterede globale indstillinger:

agents.list[].groupChat.mentionPatterns (eller messages.groupChat.mentionPatterns).
messages.responsePrefix.

Overview

Messaging platforms

Configuration

iMessage

iMessage (legacy: imsg)¶

Hurtig opsætning (begynder)¶

Hvad det er¶

Konfigurationsskrivninger¶

Krav¶

Fejlfinding af macOS Privacy and Security TCC¶

Opsætning (hurtig vej)¶

Dedikeret bot-macOS-bruger (for isoleret identitet)¶

Fjern-/SSH-variant (valgfrit)¶

Fjern-Mac via Tailscale (eksempel)¶

Adgangskontrol (DMs + grupper)¶

Sådan virker det (adfærd)¶

Gruppe-agtige tråde (`is_group=false`)¶

Medier + grænser¶

Begrænsninger¶

Adressering / leveringsmål¶

Konfigurationsreference (iMessage)¶

Overview

Messaging platforms

Configuration

iMessage (legacy: imsg)¶

Hurtig opsætning (begynder)¶

Hvad det er¶

Konfigurationsskrivninger¶

Krav¶

Fejlfinding af macOS Privacy and Security TCC¶

Opsætning (hurtig vej)¶

Dedikeret bot-macOS-bruger (for isoleret identitet)¶

Fjern-/SSH-variant (valgfrit)¶

Fjern-Mac via Tailscale (eksempel)¶

Adgangskontrol (DMs + grupper)¶

Sådan virker det (adfærd)¶

Gruppe-agtige tråde (is_group=false)¶

Medier + grænser¶

Begrænsninger¶

Adressering / leveringsmål¶

Konfigurationsreference (iMessage)¶

Gruppe-agtige tråde (`is_group=false`)¶