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", // usado para buscas de anexos por SCP  includeAttachments: true,  // Opcional: sobrescreve as raízes de anexos permitidas.  // Os padrões incluem /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 / desfazer envio / resposta em thread / efeitos / enquetes / operações de grupo), a Proteção de Integridade do Sistema deve ser desativada — consulte Habilitando a API privada do imsg abaixo. Envio/recebimento básico de texto e mídia funciona sem isso.

Not authorized to send Apple events to Messages. (-1743)

kTCCServiceAppleEvents | /usr/libexec/sshd-keygen-wrapper | auth_value=0 | com.apple.MobileSMS

Habilitando a API privada do imsg

imsg é distribuído em dois modos operacionais:

• Modo básico (padrão, sem necessidade de alterações no SIP): texto e mídia de saída via send, observação/histórico de entrada, lista de chats. Isso é o que você obtém de imediato com uma instalação nova via brew install steipete/tap/imsg mais as permissões padrão do macOS acima.
• Modo de API privada: imsg injeta uma dylib auxiliar no Messages.app para chamar funções internas do IMCore. Isso desbloqueia react, edit, unsend, reply (em thread), sendWithEffect, poll e poll-vote (enquetes nativas do Messages), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, além de indicadores de digitação e recibos de leitura.

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

Recursos avançados como read, typing, launch, envio rico com suporte de ponte, mutação de mensagens e gerenciamento de chats são opcionais. Eles exigem que o SIP esteja desativado e que uma dylib auxiliar seja injetada no Messages.app. imsg launch se recusa a injetar quando o SIP está habilitado.

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 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 relata 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 e, (no macOS moderno) a Validação de Biblioteca. Injetar uma dylib auxiliar não Apple no Messages.app assinado pela Apple exige SIP desativado e validação de biblioteca relaxada. A etapa de SIP no modo de Recuperação é específica da versão do macOS:

   • 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 posterior), 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 em Recuperação; em versões recentes do macOS, mantenha pressionada a tecla Shift Esquerdo ao clicar em Continuar, depois csrutil disable. Configurações de máquina virtual seguem um fluxo separado, então faça primeiro um snapshot da VM.

   No macOS 11 e posteriores, apenas csrutil disable geralmente não é suficiente. A Apple ainda aplica validação de biblioteca contra o Messages.app como binário de plataforma, então um auxiliar assinado ad hoc é rejeitado (Library Validation failed: ... platform binary, but mapped file is not) mesmo com SIP desativado. Após desativar o SIP, também desative a validação de biblioteca e reinicie:

   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true

   macOS 26 (Tahoe), verificado na 26.5.1: SIP desativado mais o comando DisableLibraryValidation acima é suficiente para injetar o auxiliar da 26.0 até a 26.5.x. Nenhum boot-arg é necessário. O plist é o fator decisivo e a etapa ausente mais comum quando a injeção falha no Tahoe:

   • Com o plist: imsg launch injeta e imsg status relata advanced_features: true.
   • Sem o plist (mesmo com SIP desativado): imsg launch falha com Failed to launch: Timeout waiting for Messages.app to initialize. O AMFI rejeita o auxiliar ad hoc no carregamento, então a ponte nunca fica pronta e o lançamento expira. Esse timeout é o sintoma que a maioria das pessoas encontra no Tahoe, e a correção é o plist acima, não algo mais drástico.

   Isso foi confirmado com um antes/depois controlado no macOS 26.5.1 (Apple Silicon): com o plist, a dylib é mapeada no Messages.app e a ponte sobe; remova o plist e reinicie, e imsg launch produz a falha de timeout acima, com a dylib não mapeada.

   Se a injeção de imsg launch ou selectors específicos começarem a retornar falso após uma atualização do macOS, esse gate geralmente é a causa. Verifique o estado do SIP e da validação de biblioteca antes de presumir que a própria etapa do SIP falhou. Se essas configurações estiverem corretas e a ponte ainda não conseguir injetar, colete imsg status --json mais a saída de imsg launch e relate ao projeto imsg em vez de enfraquecer controles adicionais de segurança em todo o sistema.

   Siga o fluxo em modo de Recuperação da Apple para seu Mac para desabilitar o SIP antes de executar imsg launch.

3. Injete o auxiliar. Com o SIP desabilitado e o Messages.app conectado:

   imsg launch

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

4. Verifique a ponte a partir do OpenClaw:

   openclaw channels status --probe

   A entrada do iMessage deve relatar works, e imsg status --json | jq '{rpc_methods, selectors}' deve mostrar as capacidades expostas pela sua compilação do macOS. A criação de enquetes exige selectors.pollPayloadMessage; a votação exige tanto selectors.pollVoteMessage quanto o método RPC poll.vote. O Plugin do OpenClaw anuncia apenas ações compatíveis com a sondagem em cache, enquanto um cache vazio permanece otimista e sonda no primeiro envio.

Se openclaw channels status --probe relatar o canal como works, mas ações específicas gerarem "iMessage <action> requires the imsg private API bridge" no momento do envio, execute imsg launch novamente — o auxiliar pode sair de operação (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 desabilitar o SIP

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

• imsg volta para o modo básico — texto + mídia + recebimento apenas.
• O Plugin do OpenClaw ainda anuncia envio de texto/mídia e monitoramento de entrada; ele apenas oculta react, edit, unsend, reply, sendWithEffect e operações de grupo da superfície de ações (conforme o gate de capacidade por método).
• Você pode executar um Mac separado que não seja Apple Silicon (ou um Mac dedicado para bot) com SIP desativado para a carga de trabalho do iMessage, mantendo o SIP habilitado 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: "",        },      },    },  },}

Associações de conversa ACP

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

Fluxo rápido do operador:

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

Associaçõ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 de DM normalizado como +15555550123 ou user@example.com
• chat_id:<id> (recomendado para associaçõ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" },    },  ],}

Veja Agentes ACP para o comportamento compartilhado de associação ACP.

Padrões de implantação

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

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

Mídia, fragmentação e alvos 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 de texto normais.

{  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,        polls: true,      },    },  },}

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

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).

Desative:

{  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 Mensagens da Apple divide o envio em duas linhas chat.db separadas:

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 somente o comando no turno 1, responde (muitas vezes "envie-me a URL") e só vê a URL no turno 2 — momento em que o contexto do comando já foi perdido. Esse é o pipeline de envio da Apple, não algo introduzido pelo OpenClaw ou pelo imsg.

channels.imessage.coalesceSameSenderDms opta uma DM por armazenar em buffer linhas consecutivas do mesmo remetente. Quando imsg expõe o marcador estrutural de pré-visualização de URL balloon_bundle_id: "com.apple.messages.URLBalloonProvider" em uma das linhas de origem, o OpenClaw mescla somente esse envio dividido real e mantém quaisquer outras linhas em buffer como turnos separados. Em builds mais antigas do imsg que não emitem nenhum metadado de balão, o OpenClaw não consegue distinguir um envio dividido de envios separados, então recorre a mesclar o balde. Isso preserva o comportamento anterior aos metadados em vez de regredir envios divididos Dump <url> para dois turnos. Chats em grupo continuam despachando por mensagem, para que a estrutura de turnos multiusuário seja preservada.

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

{  messages: {    inbound: {      byChannel: {        // 7000 ms covers observed Messages.app URL-preview delays.        imessage: 7000,      },    },  },}

Cenários e o que o agente vê

A coluna "Sinalizador ativado" mostra o comportamento em um build do imsg que emite balloon_bundle_id. Em builds antigos do imsg que não emitem nenhum metadado de balão, as linhas abaixo marcadas como "Dois turnos" / "N turnos" recorrem a uma mesclagem legada (um turno): o OpenClaw não consegue distinguir estruturalmente um split-send de envios separados, então preserva a mesclagem anterior aos metadados. A separação precisa é ativada quando o build emite metadados de balão.

Recuperação de entrada após uma reinicialização da ponte ou do gateway

O iMessage recupera mensagens perdidas enquanto o gateway estava fora do ar e, ao mesmo tempo, suprime a "bomba de backlog" obsoleta que a Apple pode liberar após uma recuperação por Push. O comportamento padrão está sempre ativado, construído sobre a deduplicação de entrada.

• Deduplicação de replay. Toda mensagem de entrada despachada é registrada por seu GUID da Apple no estado persistente do Plugin (imessage.inbound-dedupe), reivindicada na ingestão e confirmada após o processamento (liberada em uma falha transitória para que possa tentar novamente). Qualquer coisa já processada é descartada em vez de ser despachada duas vezes. É isso que permite que a recuperação faça replay agressivamente sem bookkeeping por mensagem.
• Recuperação de indisponibilidade. Na inicialização, o monitor lembra o último rowid de chat.db despachado (um cursor persistido por conta) e o passa para imsg watch.subscribe como since_rowid, para que o imsg reproduza as linhas que chegaram enquanto o gateway estava fora do ar e depois acompanhe ao vivo. O replay é limitado às linhas mais recentes e a mensagens com até ~2 horas de idade, e a deduplicação descarta qualquer coisa já processada.
• Cerca de idade para backlog obsoleto. Linhas acima do limite de inicialização são genuinamente ao vivo; uma cujo envio é mais de ~15 minutos anterior à chegada é backlog de flush do Push e é suprimida. Linhas reproduzidas (no limite ou abaixo dele) usam a janela de recuperação mais ampla, então uma mensagem perdida recentemente é entregue enquanto histórico antigo não é.

A recuperação funciona tanto em configurações locais quanto remotas de cliPath, porque o replay de since_rowid usa a mesma conexão RPC do imsg. A diferença é a janela: quando o gateway consegue ler chat.db (local), ele ancora o limite de rowid de inicialização, limita o intervalo de replay e entrega mensagens perdidas com até algumas horas de idade. Por um cliPath remoto via SSH, ele não consegue ler o banco de dados, então o replay não tem limite e toda linha usa a cerca de idade ao vivo — ele ainda recupera mensagens perdidas recentemente e ainda suprime backlog antigo, só com a janela ao vivo mais estreita. Execute o gateway no Mac do Messages para a janela de recuperação mais ampla.

Sinal visível ao operador

Backlog suprimido é registrado no nível padrão, nunca descartado silenciosamente (o sinalizador recovery mostra qual janela foi aplicada):

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; suppressed since start)

Migração

channels.imessage.catchup.* está obsoleto — a recuperação de indisponibilidade agora é automática e não precisa de configuração para novas instalações. Configurações existentes com catchup.enabled: true continuam sendo honradas como um perfil de compatibilidade para a janela de replay de recuperação. Blocos de catchup desativados (enabled: false ou sem enabled: true) foram aposentados; openclaw doctor --fix os remove.

Solução de problemas

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

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

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

openclaw channels status --probe --channel imessage

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

Ponteiros de referência de configuração

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

Relacionados

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