iMessage (legado: imsg)

Aviso: Para novas implantações de iMessage, use BlueBubbles.

A integração imsg é legada e pode ser removida em uma versão futura.

Status: integração CLI externa legada. O gateway inicia imsg rpc e se comunica via JSON-RPC sobre stdio (sem daemon/porta separados).

• BlueBubbles (recomendado) — Caminho preferido para iMessage em novas instalações.
• Pareamento — DMs do iMessage usam modo de pareamento por padrão.
• Referência de configuração — Referência completa dos campos do iMessage.

Configuração rápida

Mac local (caminho rápido)

  ### Passo 1: Instale e verifique o imsg

brew install steipete/tap/imsg
imsg rpc --help

  ### Passo 2: Configure o OpenClaw

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

  ### Passo 3: Inicie o gateway

openclaw gateway

  ### Passo 4: Aprove o primeiro pareamento por DM (dmPolicy padrão)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    Solicitações de pareamento expiram após 1 hora.

Mac remoto via SSH

O OpenClaw requer apenas um `cliPath` compatível com stdio, então você pode apontar `cliPath` para um script wrapper que conecta via SSH a um Mac remoto e executa `imsg`.

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

Configuração recomendada quando anexos estão ativados:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // used for SCP attachment fetches
      includeAttachments: true,
      // Optional: override allowed attachment roots.
      // Defaults include /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

Se `remoteHost` não estiver definido, o OpenClaw tenta detectá-lo automaticamente analisando o script wrapper SSH.
`remoteHost` deve ser `host` ou `user@host` (sem espaços ou opções SSH).
O OpenClaw usa verificação estrita de host-key para SCP, então a chave do host relay já deve existir em `~/.ssh/known_hosts`.
Os caminhos de anexos são validados contra raízes permitidas (`attachmentRoots` / `remoteAttachmentRoots`).

Requisitos e permissões (macOS)

• O Messages deve estar autenticado no Mac que executa imsg.
• Full Disk Access é necessário para o contexto de processo que executa o OpenClaw/imsg (acesso ao banco de dados do Messages).
• Permissão de Automação é necessária para enviar mensagens pelo Messages.app.

Dica: As permissões são concedidas por contexto de processo. Se o gateway roda headless (LaunchAgent/SSH), execute um comando interativo único nesse mesmo contexto para acionar os prompts:

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

Controle de acesso e roteamento

Política de DM

`channels.imessage.dmPolicy` controla mensagens diretas:

- `pairing` (padrão)
- `allowlist`
- `open` (requer que `allowFrom` inclua `"*"`)
- `disabled`

Campo de lista de permitidos: `channels.imessage.allowFrom`.

Entradas da lista de permitidos podem ser handles ou alvos de chat (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).

Política de grupo + menções

`channels.imessage.groupPolicy` controla o tratamento de grupos:

- `allowlist` (padrão quando configurado)
- `open`
- `disabled`

Lista de permitidos de remetentes de grupo: `channels.imessage.groupAllowFrom`.

Fallback em runtime: se `groupAllowFrom` não estiver definido, as verificações de remetente de grupo do iMessage recorrem a `allowFrom` quando disponível.
Observação de runtime: se `channels.imessage` estiver completamente ausente, o runtime recorre a `groupPolicy="allowlist"` e registra um aviso (mesmo que `channels.defaults.groupPolicy` esteja definido).

Filtragem por menção para grupos:

- o iMessage não possui metadados nativos de menção
- a detecção de menção usa padrões regex (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- sem padrões configurados, a filtragem por menção não pode ser aplicada

Comandos de controle de remetentes autorizados podem ignorar a filtragem por menção em grupos.

Sessões e respostas determinísticas

- DMs usam roteamento direto; grupos usam roteamento de grupo.
- Com o padrão `session.dmScope=main`, DMs do iMessage se agrupam na sessão principal do agente.
- Sessões de grupo são isoladas (`agent:<agentId>:imessage:group:<chat_id>`).
- As respostas retornam ao iMessage usando metadados de canal/alvo de origem.

Comportamento de threads similares a grupos:

Algumas threads do iMessage com múltiplos participantes podem chegar com `is_group=false`.
Se esse `chat_id` estiver explicitamente configurado em `channels.imessage.groups`, o OpenClaw o trata como tráfego de grupo (filtragem de grupo + isolamento de sessão de grupo).

Padrões de implantação

Use um Apple ID dedicado e um usuário macOS separado para que o tráfego do bot fique isolado do seu perfil pessoal do Messages.

Fluxo típico:

1. Crie/faça login em um usuário macOS dedicado.
2. Faça login no Messages com o Apple ID do bot nesse usuário.
3. Instale o `imsg` nesse usuário.
4. Crie um wrapper SSH para que o OpenClaw execute `imsg` no contexto desse usuário.
5. Aponte `channels.imessage.accounts.<id>.cliPath` e `.dbPath` para o perfil desse usuário.

A primeira execução pode exigir aprovações via GUI (Automação + Full Disk Access) na sessão do usuário bot.

Topologia comum:

- o gateway roda em Linux/VM
- o iMessage + `imsg` roda em um Mac na sua tailnet
- o wrapper `cliPath` usa SSH para executar `imsg`
- `remoteHost` permite busca de anexos via SCP

Exemplo:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

Use chaves SSH para que tanto SSH quanto SCP sejam não interativos.
Certifique-se de que a chave do host é confiável antes (por exemplo `ssh [email protected]`) para que o `known_hosts` seja populado.

O iMessage suporta configuração por conta em `channels.imessage.accounts`.

Cada conta pode sobrescrever campos como `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, configurações de histórico e listas de raízes de anexos permitidas.

Mídia, fragmentação e alvos de entrega

- a ingestão de anexos de entrada é opcional: `channels.imessage.includeAttachments`
- caminhos de anexos remotos podem ser buscados via SCP quando `remoteHost` está definido
- os caminhos de anexos devem corresponder a raízes permitidas:
  - `channels.imessage.attachmentRoots` (local)
  - `channels.imessage.remoteAttachmentRoots` (modo SCP remoto)
  - padrão de raiz: `/Users/*/Library/Messages/Attachments`
- o SCP usa verificação estrita de host-key (`StrictHostKeyChecking=yes`)
- o tamanho de mídia de saída usa `channels.imessage.mediaMaxMb` (padrão 16 MB)

- limite de fragmento de texto: `channels.imessage.textChunkLimit` (padrão 4000)
- modo de fragmentação: `channels.imessage.chunkMode`
  - `length` (padrão)
  - `newline` (divisão priorizando parágrafos)

Alvos explícitos preferidos:

- `chat_id:123` (recomendado para roteamento estável)
- `chat_guid:...`
- `chat_identifier:...`

Alvos por handle também são suportados:

- `imessage:+1555...`
- `sms:+1555...`
- `[email protected]`

imsg chats --limit 20

Escritas de configuração

O iMessage permite escritas de configuração iniciadas pelo canal por padrão (para /config set|unset quando commands.config: true).

Desativar:

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

Solução de problemas

Valide o binário e o suporte a RPC:

imsg rpc --help
openclaw channels status --probe

Se o probe reportar RPC não suportado, atualize o `imsg`.

Verifique:

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- aprovações de pareamento (`openclaw pairing list imessage`)

Verifique:

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- comportamento de lista de permitidos em `channels.imessage.groups`
- configuração de padrões de menção (`agents.list[].groupChat.mentionPatterns`)

Verifique:

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- autenticação por chave SSH/SCP do host do gateway
- chave do host existe em `~/.ssh/known_hosts` no host do gateway
- legibilidade do caminho remoto no Mac que executa o Messages

Execute novamente em um terminal GUI interativo no mesmo contexto de usuário/sessão e aprove os prompts:

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

Confirme que Full Disk Access + Automação estão concedidos para o contexto de processo que executa o OpenClaw/`imsg`.

Referência de configuração

• Referência de configuração - iMessage
• Configuração do gateway
• Pareamento
• BlueBubbles