iMessage

Status: integração nativa com CLI externa. O Gateway inicia imsg rpc e se comunica por JSON-RPC via stdio — sem daemon ou porta separados. O modo de API privada é altamente recomendado para um canal iMessage completo; respostas, tapbacks, efeitos, enquetes, respostas a anexos e ações de grupo exigem imsg launch e uma sondagem bem-sucedida da API privada.

Para a configuração local comum, a configuração do OpenClaw pode oferecer, mediante confirmação do usuário, a instalação ou atualização de imsg pelo Homebrew no Mac com sessão iniciada no Mensagens. A configuração manual e as topologias com wrapper SSH continuam sob responsabilidade do operador: instale ou atualize imsg no mesmo contexto de usuário que executará o Gateway ou o wrapper.

Configuração rápida

brew install steipete/tap/imsgbrew update && brew upgrade 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>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

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

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // usado para buscar anexos via SCP  includeAttachments: true,  // Opcional: raízes adicionais permitidas para anexos (mescladas com a raiz padrão  // /Users/*/Library/Messages/Attachments).  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Requisitos e permissões (macOS)

• O Mensagens deve estar com a sessão iniciada no Mac que executa imsg.
• O Acesso Total ao Disco é obrigatório para o contexto de processo que executa o OpenClaw/imsg (acesso ao banco de dados do Mensagens).
• A permissão de Automação é obrigatória para enviar mensagens pelo Messages.app.
• Para ações avançadas (reagir / editar / desfazer envio / resposta em thread / efeitos / enquetes / operações de grupo), a Proteção da Integridade do Sistema deve ser desativada — consulte Ativação da API privada do imsg. O envio e recebimento básico de texto e mídia funciona sem isso.

Sem autorização para enviar eventos Apple ao Mensagens. (-1743)

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

Ativação da API privada do imsg

imsg é fornecido em dois modos operacionais. Para o OpenClaw, o modo de API privada é a configuração recomendada porque fornece ao canal as ações nativas do iMessage esperadas pelos usuários. O modo básico continua útil para instalações de baixo risco, verificação inicial ou hosts nos quais não é possível desativar o SIP.

• Modo básico (padrão, sem necessidade de alterar o SIP): envio de texto e mídia por send, monitoramento/histórico de entrada e lista de conversas. Isso é o que se obtém imediatamente com uma instalação nova de brew install steipete/tap/imsg e as permissões padrão do macOS descritas acima.
• Modo de API privada: imsg injeta uma dylib auxiliar em Messages.app para chamar funções internas de IMCore. Isso desbloqueia react, edit, unsend, reply (em thread), sendWithEffect, poll e poll-vote (enquetes nativas do Mensagens), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, além de indicadores de digitação e confirmações de leitura.

A superfície de ações recomendada nesta página exige o modo de API privada. O README de imsg é explícito sobre o requisito:

Recursos avançados, como read, typing, launch, envio avançado com suporte da ponte, alteração de mensagens e gerenciamento de conversas, são opcionais. Eles exigem que o SIP esteja desativado e que uma dylib auxiliar seja injetada em Messages.app. imsg launch se recusa a fazer a injeção quando o SIP está habilitado.

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

Configuração

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

   brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg status --json

   A saída de imsg status --json informa bridge_version, rpc_methods e selectors por método, para que seja possível verificar o que a compilação atual oferece 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 que não seja da Apple no Messages.app assinado pela Apple exige que o SIP esteja desativado e que a validação de biblioteca esteja relaxada. A etapa do SIP no modo de Recuperação varia conforme a 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 e reinicie.
   • macOS 11+ (Big Sur e posteriores), Intel: entre no modo de Recuperação (ou Recuperação pela Internet), execute csrutil disable e reinicie.
   • macOS 11+, Apple Silicon: use a sequência de inicialização pelo botão liga/desliga para entrar na Recuperação; nas versões recentes do macOS, mantenha pressionada a tecla Left Shift ao clicar em Continue e, em seguida, execute csrutil disable. Configurações de máquina virtual seguem um fluxo separado; portanto, primeiro crie um snapshot da VM.

   No macOS 11 e posteriores, apenas csrutil disable geralmente não é suficiente. A Apple ainda impõe a validação de biblioteca ao Messages.app por ele ser um binário da plataforma; portanto, um auxiliar com assinatura ad hoc é rejeitado (Library Validation failed: ... platform binary, but mapped file is not) mesmo com o SIP desativado. Depois de desativar o SIP, desative também 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 versão 26.5.1: o SIP desativado mais o comando DisableLibraryValidation acima são suficientes para injetar o auxiliar nas versões 26.0 a 26.5.x. Nenhum argumento de inicialização é 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 faz a injeção e imsg status informa advanced_features: true.
   • Sem o plist (mesmo com o SIP desativado): imsg launch falha com Failed to launch: Timeout waiting for Messages.app to initialize. O AMFI rejeita o auxiliar com assinatura ad hoc durante o carregamento; portanto, a ponte nunca fica pronta e a inicialização atinge o tempo limite. Esse tempo limite é o sintoma que a maioria das pessoas encontra no Tahoe; a correção é o plist acima, não alguma medida mais drástica.

   Se a injeção de imsg launch ou algum selectors específico começar a retornar falso após uma atualização do macOS, essa restrição 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 ainda não for possível injetar a ponte, colete imsg status --json junto com a saída de imsg launch e informe ao projeto imsg, em vez de enfraquecer outros controles de segurança em todo o sistema.

3. Injete o auxiliar. Com o SIP desativado e uma sessão iniciada no Messages.app:

   imsg launch

   imsg launch se recusa a fazer a injeção quando o SIP ainda está ativado; portanto, isso também serve como confirmação de que a etapa 2 foi realizada.

4. Verifique a ponte pelo OpenClaw:

   openclaw channels status --probe

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

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

Quando o SIP permanece ativado

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

• imsg recorre ao modo básico — somente texto, mídia e recebimento.
• O plugin do OpenClaw continua anunciando o envio de texto/mídia e o monitoramento de mensagens recebidas; ele oculta react, edit, unsend, reply, sendWithEffect e operações de grupo da superfície de ações (de acordo com a restrição de recursos por método).
• É possível executar um Mac separado que não use Apple Silicon (ou um Mac dedicado ao bot) com o SIP desativado para a carga de trabalho do iMessage, mantendo o SIP ativado nos dispositivos principais. Consulte Usuário dedicado do macOS para o bot (identidade separada do iMessage) abaixo.

Controle de acesso e roteamento

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Use a ortografia britânica." },        "8421": {          requireMention: true,          systemPrompt: "Esta é a conversa da escala de plantão. Mantenha as respostas com menos de 3 frases.",        },        "9907": {          // supressão explícita: o curinga "Use a ortografia britânica." não se aplica aqui          systemPrompt: "",        },      },    },  },}

Vínculos de conversas ACP

As conversas do iMessage podem ser vinculadas a sessões ACP.

Fluxo rápido para operadores:

• Execute /acp spawn codex --bind here dentro da mensagem direta ou da conversa de grupo permitida.
• As mensagens futuras nessa mesma conversa do iMessage serão encaminhadas à sessão ACP criada.
• /new e /reset redefinem no local a mesma sessão ACP vinculada.
• /acp close encerra a sessão ACP e remove o vínculo.

Vínculos persistentes configurados usam entradas bindings[] de nível superior com type: "acp" e match.channel: "imessage".

match.peer.id pode usar:

• um identificador normalizado de mensagem direta, como +15555550123 ou user@example.com
• chat_id:<id> (recomendado para vínculos 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 conhecer o comportamento compartilhado dos vínculos 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, divisão em partes e destinos de entrega

imsg chats --limit 20

Ações da API privada

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

Todas as ações são habilitadas por padrão; use channels.imessage.actions para desativar ações individuais:

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

Gravações de configuração

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

Para desativar:

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

Agregação 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 da pré-visualização OG como anexos.

As duas linhas chegam ao OpenClaw com um intervalo de aproximadamente 0.8-2.0 s na maioria das configurações. Sem agregação, o agente recebe apenas o comando no turno 1 (e frequentemente responde "envie a URL") antes de a URL chegar no turno 2. Isso faz parte do pipeline de envio da Apple, não é algo introduzido pelo OpenClaw ou por imsg.

channels.imessage.coalesceSameSenderDms permite que uma DM armazene 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 realmente dividido e mantém quaisquer outras linhas armazenadas em buffer como turnos separados. Em builds mais antigos de imsg, que não emitem nenhum metadado de balão, o OpenClaw não consegue distinguir um envio dividido de envios separados e, portanto, recorre à mesclagem do conjunto. Isso preserva o comportamento anterior aos metadados, em vez de regredir envios divididos de Dump <url> para dois turnos. Os chats em grupo continuam sendo despachados por mensagem para preservar a estrutura de turnos com vários usuários.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // ativação opcional (padrão: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms abrangem os atrasos observados na pré-visualização de URLs do Messages.app.        imessage: 7000,      },    },  },}

Cenários e o que o agente vê

A coluna "Sinalizador ativado" mostra o comportamento em um build de imsg que emite balloon_bundle_id. Em builds mais antigos de imsg, que não emitem nenhum metadado de balão, as linhas abaixo marcadas como "Dois turnos" / "N turnos" recorrem, em vez disso, a uma mesclagem legada (um turno): o OpenClaw não consegue distinguir estruturalmente um envio dividido de envios separados e, portanto, preserva a mesclagem anterior aos metadados. A separação precisa é ativada assim que o build passa a emitir metadados de balão.

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

O iMessage recupera mensagens perdidas enquanto o gateway estava inativo e, ao mesmo tempo, suprime a "bomba de backlog" obsoleta que a Apple pode descarregar após uma recuperação de Push. O comportamento padrão está sempre ativado e se baseia na desduplicação de entrada.

• Desduplicação de repetição. Cada mensagem de entrada despachada é registrada por seu GUID da Apple no estado persistente do plugin (imessage.inbound-dedupe), reservada na ingestão e confirmada após o processamento (liberada em caso de falha transitória para que possa ser tentada novamente). Tudo que já tiver sido processado é descartado, em vez de ser despachado duas vezes. Isso permite que a recuperação repita mensagens de forma agressiva sem manter registros por mensagem.
• Recuperação do período de inatividade. Na inicialização, o monitor recupera o último rowid despachado de chat.db (um cursor persistente por conta) e o passa para imsg watch.subscribe como since_rowid, para que o imsg repita as linhas que chegaram enquanto o gateway estava inativo e depois acompanhe as mensagens ao vivo. A repetição é limitada às 500 linhas mais recentes e a mensagens com até aproximadamente 2 horas, e a desduplicação descarta tudo que já tiver sido processado.
• Limite de idade para backlog obsoleto. As linhas acima do limite de inicialização são realmente ao vivo; uma linha cuja data de envio seja mais de aproximadamente 15 minutos anterior à chegada pertence ao backlog descarregado pelo Push e é suprimida. As linhas repetidas (no limite ou abaixo dele) usam a janela de recuperação mais ampla, permitindo que uma mensagem perdida recentemente seja entregue sem incluir o histórico antigo.

A recuperação funciona tanto em configurações locais quanto remotas de cliPath, pois a repetição de since_rowid é executada pela mesma conexão RPC de imsg. A diferença está na janela: quando o gateway consegue ler chat.db (local), ele fixa o limite de rowid da inicialização, limita o intervalo de repetição e entrega mensagens perdidas com até algumas horas de idade. Por meio de um cliPath SSH remoto, ele não consegue ler o banco de dados; portanto, a repetição não tem limite e cada linha usa o limite de idade das mensagens ao vivo — ele ainda recupera mensagens perdidas recentemente e suprime o backlog antigo, mas com a janela menor das mensagens ao vivo. Execute o gateway no Mac com o Mensagens para obter a janela de recuperação mais ampla.

Sinal visível para o operador

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

imessage: backlog de entrada obsoleto suprimido account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; suprimidos desde a inicialização)

Migração

channels.imessage.catchup.* está obsoleto — a recuperação do período de inatividade é automática e não exige configuração em novas instalações. Configurações existentes com catchup.enabled: true continuam sendo respeitadas como um perfil de compatibilidade para a janela de repetição da recuperação. Blocos de recuperação desativados (enabled: false ou sem enabled: true) foram descontinuados; 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"

Referências da configuração

• Referência de configuração — iMessage
• Configuração do Gateway
• Emparelhamento

Relacionados

• Visão geral dos canais — todos os canais compatíveis
• Remoção do BlueBubbles e o caminho do iMessage via imsg — anúncio e resumo da migração
• Migração do BlueBubbles — tabela de tradução da configuração e transição passo a passo
• Emparelhamento — autenticação de mensagens diretas e fluxo de emparelhamento
• Grupos — comportamento de conversas em grupo e controle por menções
• Roteamento de canais — roteamento de sessões para mensagens
• Segurança — modelo de acesso e proteção