iMessage

Status: integração nativa com CLI externa. O Gateway inicia imsg rpc e se comunica por JSON-RPC em stdio (sem daemon/porta separado). Ações avançadas exigem imsg launch e uma sondagem bem-sucedida da API privada.

Configuração rápida

brew install steipete/tap/imsgimsg rpc --helpimsg launchopenclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessageopenclaw pairing approve imessage <CODE>

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

{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"],},},}

Requisitos e permissões (macOS)

• O Messages deve estar com sessão iniciada no Mac que executa imsg.
• Acesso Total ao Disco é obrigatório para o contexto de processo que executa OpenClaw/imsg (acesso ao banco de dados do Messages).
• Permissão de Automação é obrigatória para enviar mensagens por meio do Messages.app.
• Para ações avançadas (reagir / editar / cancelar envio / resposta encadeada / efeitos / operações de grupo), a Proteção de Integridade do Sistema deve estar desativada — veja Ativando a API privada do imsg abaixo. Envio/recebimento básico de texto e mídia funciona sem isso.

Ativando a API privada do imsg

imsg é fornecido em dois modos operacionais:

• Modo básico (padrão, sem alterações na SIP necessárias): texto e mídia enviados via send, observação/histórico de recebidos, lista de chats. É isso que você obtém imediatamente após uma instalação nova com brew install steipete/tap/imsg mais as permissões padrão do macOS acima.
• Modo API privada: imsg injeta uma dylib auxiliar em Messages.app para chamar funções internas de IMCore. É isso que desbloqueia react, edit, unsend, reply (encadeada), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, além de indicadores de digitação e confirmações de leitura.

Para acessar a superfície de ações avançadas documentada nesta página do canal, você precisa do modo API privada. O README do imsg é explícito sobre o requisito:

Recursos avançados como read, typing, launch, envio enriquecido com suporte de bridge, mutação de mensagem e gerenciamento de chats são opcionais. Eles exigem que a SIP esteja desativada e que uma dylib auxiliar seja injetada em Messages.app. imsg launch se recusa a injetar quando a SIP está ativada.

A técnica de injeção do auxiliar usa a própria dylib do imsg para acessar APIs privadas do Messages. Não há servidor de terceiros nem runtime do BlueBubbles no caminho iMessage do OpenClaw.

Configuração

1. Instale (ou atualize) imsg no Mac que executa Messages.app:

   brew install steipete/tap/imsgimsg --versionimsg status --json

   A saída de imsg status --json informa bridge_version, rpc_methods e selectors por método, para que você veja o que a build atual oferece suporte antes de começar.

2. Desative a Proteção de Integridade do Sistema. Isso é específico da versão do macOS porque o requisito subjacente da Apple depende do sistema operacional e do hardware:

   • macOS 10.13–10.15 (Sierra–Catalina): desative a Validação de Biblioteca pelo Terminal, reinicie no Modo de Recuperação, execute csrutil disable, reinicie.
   • macOS 11+ (Big Sur e posteriores), Intel: Modo de Recuperação (ou Recuperação pela Internet), csrutil disable, reinicie.
   • macOS 11+, Apple Silicon: sequência de inicialização pelo botão liga/desliga para entrar na Recuperação; em versões recentes do macOS, mantenha a tecla Shift esquerda pressionada ao clicar em Continuar, depois csrutil disable. Configurações de máquina virtual seguem um fluxo separado — faça primeiro um snapshot da VM.
   • macOS 26 / Tahoe: políticas de validação de biblioteca e verificações de entitlement privado do imagent ficaram ainda mais rígidas; imsg pode precisar de uma build atualizada para acompanhar. Se a injeção de imsg launch ou selectors específicos começarem a retornar false após uma atualização principal do macOS, verifique as notas de versão do imsg antes de presumir que a etapa da SIP foi bem-sucedida.

   Siga o fluxo de Modo de Recuperação da Apple para o seu Mac para desativar a SIP antes de executar imsg launch.

3. Injete o auxiliar. Com a SIP desativada e o Messages.app com sessão iniciada:

   imsg launch

   imsg launch se recusa a injetar quando a SIP ainda está ativada, então isso também serve como confirmação de que a etapa 2 funcionou.

4. Verifique a bridge pelo OpenClaw:

   openclaw channels status --probe

   A entrada do iMessage deve informar works, e imsg status --json | jq '.selectors' deve mostrar retractMessagePart: true mais quaisquer seletores de edição / digitação / leitura que sua build do macOS expõe. O controle por método do Plugin OpenClaw em actions.ts anuncia apenas ações cujo seletor subjacente é true, então a superfície de ações que você vê na lista de ferramentas do agente reflete o que a bridge realmente consegue fazer neste host.

Se openclaw channels status --probe informar que o canal está como works, mas ações específicas lançarem "iMessage <action> requires the imsg private API bridge" no momento do despacho, execute imsg launch novamente — o auxiliar pode deixar de estar ativo (reinicialização do Messages.app, atualização do SO etc.) e o status em cache available: true continuará anunciando ações até que a próxima sondagem atualize.

Quando você não pode desativar a SIP

Se SIP desativada não for aceitável para seu modelo de ameaça:

• imsg retorna ao modo básico — apenas texto + mídia + recebimento.
• O Plugin OpenClaw ainda anuncia envio de texto/mídia e monitoramento de recebidos; ele apenas oculta react, edit, unsend, reply, sendWithEffect e operações de grupo da superfície de ações (conforme o controle de capacidade por método).
• Você pode executar um Mac separado sem Apple Silicon (ou um Mac dedicado para bot) com SIP desativada para a carga de trabalho do iMessage, mantendo a SIP ativada nos seus dispositivos principais. Veja Usuário macOS dedicado para bot (identidade iMessage separada) abaixo.

Controle de acesso e roteamento

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Use British spelling." },        "8421": {          requireMention: true,          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",        },        "9907": {          // explicit suppression: the wildcard "Use British spelling." does not apply here          systemPrompt: "",        },      },    },  },}

Vinculações de conversas ACP

Chats legados do iMessage também podem ser vinculados a sessões ACP.

Fluxo rápido do operador:

• Execute /acp spawn codex --bind here dentro da DM ou do chat de grupo permitido.
• Mensagens futuras nessa mesma conversa do iMessage são roteadas para a sessão ACP iniciada.
• /new e /reset redefinem a mesma sessão ACP vinculada no lugar.
• /acp close fecha a sessão ACP e remove a vinculação.

Vinculações persistentes configuradas são compatíveis por meio de entradas bindings[] de nível superior com type: "acp" e match.channel: "imessage".

match.peer.id pode usar:

• identificador normalizado de DM, como +15555550123 ou [email protected]
• chat_id:<id> (recomendado para vinculações de grupo estáveis)
• chat_guid:<guid>
• chat_identifier:<identifier>

Exemplo:

{  agents: {    list: [      {        id: "codex",        runtime: {          type: "acp",          acp: { agent: "codex", backend: "acpx", mode: "persistent" },        },      },    ],  },  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "imessage",        accountId: "default",        peer: { kind: "group", id: "chat_id:123" },      },      acp: { label: "codex-group" },    },  ],}

Consulte Agentes ACP para o comportamento compartilhado de vinculação ACP.

Padrões de implantação

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

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

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

imsg chats --limit 20

Ações de API privada

Quando imsg launch está em execução e openclaw channels status --probe relata privateApi.available: true, a ferramenta de mensagens pode usar ações nativas do iMessage além dos envios normais de texto.

{  channels: {    imessage: {      actions: {        reactions: true,        edit: true,        unsend: true,        reply: true,        sendWithEffect: true,        sendAttachment: true,        renameGroup: true,        setGroupIcon: true,        addParticipant: true,        removeParticipant: true,        leaveGroup: true,      },    },  },}

{  channels: {    imessage: {      sendReadReceipts: false,    },  },}

Escritas de configuraçã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,    },  },}

Coalescência de DMs com envio dividido (comando + URL em uma composição)

Quando um usuário digita um comando e uma URL juntos — por exemplo, Dump https://example.com/article — o app Messages da Apple divide o envio em duas linhas separadas de chat.db:

1. Uma mensagem de texto ("Dump").
2. Um balão de pré-visualização de URL ("https://...") com imagens de pré-visualização OG como anexos.

As duas linhas chegam ao OpenClaw com ~0,8-2,0 s de diferença na maioria das configurações. Sem coalescência, o agente recebe apenas o comando no turno 1, responde (muitas vezes "me envie a URL") e só vê a URL no turno 2 — momento em que o contexto do comando já foi perdido. Isso é o pipeline de envio da Apple, não algo que o OpenClaw ou imsg introduz.

channels.imessage.coalesceSameSenderDms opta por mesclar linhas consecutivas do mesmo remetente em uma DM em um único turno do agente. Conversas em grupo continuam sendo despachadas por mensagem para preservar a estrutura de turnos com vários usuários.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // opt in (default: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 2500 ms works for most setups; raise to 4000 ms if your Mac is        // slow or under memory pressure (observed gap can stretch past 2 s        // then).        imessage: 2500,      },    },  },}

Cenários e o que o agente vê

Recuperando mensagens após indisponibilidade do gateway

Quando o gateway fica offline (falha, reinício, suspensão do Mac, máquina desligada), imsg watch retoma a partir do estado atual de chat.db assim que o gateway volta — tudo que chegou durante o intervalo, por padrão, nunca é visto. O catchup reproduz essas mensagens na próxima inicialização para que o agente não perca silenciosamente tráfego de entrada.

Catchup fica desabilitado por padrão. Habilite por canal:

channels: {  imessage: {    catchup: {      enabled: true,             // master switch (default: false)      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)    },  },}

Como ele executa

Uma passagem por inicialização de monitorIMessageProvider, sequenciada como imsg launch pronto → watch.subscribe → performIMessageCatchup → loop de despacho ao vivo. O próprio catchup usa chats.list + messages.history por conversa contra o mesmo cliente JSON-RPC usado por imsg watch. Tudo que chega durante a passagem de catchup flui normalmente pelo despacho ao vivo; o cache existente de deduplicação de entrada absorve qualquer sobreposição com linhas reproduzidas.

Cada linha reproduzida passa pelo caminho de despacho ao vivo (evaluateIMessageInbound + dispatchInboundMessage), portanto allowlists, política de grupo, debouncer, cache de eco e recibos de leitura se comportam de forma idêntica em mensagens reproduzidas e ao vivo.

Semântica de cursor e repetição

O catchup mantém um cursor por conta em <openclawStateDir>/imessage/catchup/<account>__<hash>.json (o diretório de estado do OpenClaw usa ~/.openclaw por padrão, substituível com OPENCLAW_STATE_DIR):

{  "lastSeenMs": 1717900800000,  "lastSeenRowid": 482910,  "updatedAt": 1717900801234,  "failureRetries": { "<guid>": 1 }}

• O cursor avança a cada despacho bem-sucedido e é mantido quando o despacho de uma linha lança uma exceção — a próxima inicialização tenta novamente a mesma linha a partir do cursor mantido.
• Após maxFailureRetries exceções consecutivas contra o mesmo guid, o catchup registra um warn e força o avanço do cursor além da mensagem travada, para que inicializações posteriores possam progredir.
• GUIDs já abandonados são ignorados ao serem vistos (sem tentativa de despacho) em execuções posteriores e contabilizados em skippedGivenUp no resumo da execução.

Sinais visíveis para o operador

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…imessage catchup: giving up on guid=<guid> after &lt;N&gt; failures; advancing cursor past itimessage catchup: fetched &lt;X&gt; rows across chats, capped to perRunLimit=&lt;Y&gt;

Uma linha WARN ... capped to perRunLimit significa que uma única inicialização não esvaziou todo o backlog. Aumente perRunLimit (máx. 500) se seus intervalos regularmente excedem a passagem padrão de 50 linhas.

Quando deixar desativado

• O Gateway executa continuamente com reinício automático por watchdog e os intervalos são sempre < alguns segundos — o padrão desativado é suficiente.
• O volume de DMs é baixo e mensagens perdidas não mudariam o comportamento do agente — a janela inicial de firstRunLookbackMinutes pode despachar contexto antigo inesperado na primeira ativação.

Quando você ativa o catchup, a primeira inicialização sem cursor olha para trás apenas firstRunLookbackMinutes (padrão de 30 min), não a janela completa de maxAgeMinutes — isso evita reproduzir um histórico longo de mensagens anteriores à ativação.

Solução de problemas

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

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

Ponteiros da referência de configuração

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

Relacionado

• Visão geral dos canais — todos os canais compatíveis
• Remoção do BlueBubbles e o caminho iMessage via imsg — anúncio e resumo da migração
• Vindo do BlueBubbles — tabela de tradução de configuração e migração passo a passo
• Pareamento — autenticação de DM e fluxo de pareamento
• Grupos — comportamento de conversa em grupo e bloqueio por menção
• Roteamento de canais — roteamento de sessão para mensagens
• Segurança — modelo de acesso e endurecimento