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 separada. O modo de API privada é fortemente 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.

Na configuração local comum, a configuração do OpenClaw pode oferecer, mediante confirmação do usuário, a instalação ou atualização do imsg pelo Homebrew no Mac com sessão iniciada no Mensagens. A configuração manual e as topologias com wrapper SSH continuam sendo gerenciadas pelo operador: instale ou atualize o 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 (combinadas com o padrão  // /Users/*/Library/Messages/Attachments).  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Requisitos e permissões (macOS)

• Deve haver uma sessão iniciada no Mensagens no Mac que executa o imsg.
• O Acesso Total ao Disco é obrigatório para o contexto do 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 / cancelar envio / resposta em thread / efeitos / enquetes / operações de grupo), a Proteção de Integridade do Sistema deve ser desabilitada — consulte Habilitação da API privada do imsg. O envio e o recebimento básicos de texto e mídia funcionam sem isso.

Não autorizado a enviar eventos Apple para o Mensagens. (-1743)

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

Habilitação da API privada do imsg

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

• Modo básico (padrão, nenhuma alteração no SIP é necessária): envio de texto e mídia por meio de send, monitoramento/histórico de entrada e lista de conversas. Isso é o que se obtém imediatamente após uma nova execução de brew install steipete/tap/imsg, além das permissões padrão do macOS descritas acima.
• Modo de API privada: o imsg injeta uma dylib auxiliar no Messages.app para chamar funções internas do IMCore. Isso libera 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 do imsg é explícito quanto ao requisito:

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

A técnica de injeção do auxiliar usa a própria dylib do 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) o 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 os selectors de cada método, para que você possa ver o que a compilação atual oferece antes de começar.

2. Desabilite a Proteção de Integridade do Sistema e, no macOS moderno, a Validação de Biblioteca. A injeção de 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 flexibilizada. A etapa do SIP no modo de Recuperação é específica de cada versão do macOS:

   • macOS 10.13-10.15 (Sierra-Catalina): desabilite 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 posterior, apenas csrutil disable geralmente não é suficiente. A Apple ainda impõe a validação de bibliotecas para o Messages.app como um binário da plataforma; por isso, um auxiliar assinado de forma ad hoc é rejeitado (Library Validation failed: ... platform binary, but mapped file is not) mesmo com o SIP desativado. Após desativar o SIP, desative também a validação de bibliotecas 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 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 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 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 algo mais drástico.

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

3. Injete o auxiliar. Com o SIP desativado e a 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 efetivada.

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 tanto selectors.pollVoteMessage quanto 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 gerarem "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 estado available: true armazenado em cache continuará anunciando 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:

• O imsg volta ao modo básico — somente texto + mídia + recebimento.
• O Plugin do OpenClaw ainda anuncia 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 barreira de recursos por método).
• Você pode executar um Mac separado sem Apple Silicon (ou um Mac dedicado ao bot) com o SIP desativado para a carga de trabalho do iMessage, mantendo o SIP ativado nos seus 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 o operador:

• 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 para a sessão ACP criada.
• /new e /reset redefinem no local a mesma sessão ACP vinculada.
• /acp close fecha a sessão ACP e remove o vínculo.

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

match.peer.id pode usar:

• identificador normalizado de mensagem direta, como +15555550123 ou user@example.com
• chat_id:<id> (recomendado para vínculos estáveis de grupos)
• 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 saber mais sobre 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 blocos 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 ficam ativadas 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 MDs divididas no envio (comando + URL em uma única 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 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 um intervalo de aproximadamente 0.8-2.0 s na maioria das configurações. Sem a agregação, o agente recebe apenas o comando no turno 1 (e frequentemente responde "envie-me 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 pelo imsg.

channels.imessage.coalesceSameSenderDms habilita o armazenamento em buffer de linhas consecutivas do mesmo remetente em uma DM. Quando o imsg expõe o marcador estrutural de prévia de URL balloon_bundle_id: "com.apple.messages.URLBalloonProvider" em uma das linhas de origem, o OpenClaw mescla apenas esse envio realmente dividido e mantém quaisquer outras linhas armazenadas em buffer como turnos separados. Em versões 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 e, portanto, recorre à mesclagem do agrupamento. 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, // habilitação opcional (padrão: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms abrangem os atrasos observados nas prévias de URL do Messages.app.        imessage: 7000,      },    },  },}

Cenários e o que o agente vê

A coluna "Sinalizador ativado" mostra o comportamento em uma versão do imsg que emite balloon_bundle_id. Em versões mais antigas 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 envio dividido de envios separados e, portanto, preserva a mesclagem anterior aos metadados. A separação precisa é ativada assim que a versão 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 mensagens pendentes" obsoletas que a Apple pode descarregar após uma recuperação de Push. O comportamento padrão está sempre ativado e é baseado 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), reivindicada durante a ingestão e confirmada após o processamento (liberada em caso de falha transitória para permitir uma nova tentativa). Tudo o que já foi processado é descartado, em vez de ser despachado duas vezes. Isso permite que a recuperação repita as mensagens de forma agressiva sem manter registros individuais por mensagem.
• Recuperação do período de inatividade. Na inicialização, o monitor memoriza o último rowid despachado do chat.db (um cursor persistente por conta) e o passa para imsg watch.subscribe como since_rowid, para que o imsg repita as linhas recebidas enquanto o Gateway estava inativo e, em seguida, acompanhe as novas linhas em tempo real. A repetição é limitada às 500 linhas mais recentes e a mensagens com até ~2 horas, enquanto a desduplicação descarta tudo o que já tiver sido processado.
• Limite de idade para mensagens pendentes obsoletas. As linhas acima do limite de inicialização são realmente novas; uma linha cuja data de envio seja mais de ~15 minutos anterior à chegada pertence às mensagens pendentes descarregadas pelo Push e é suprimida. As linhas repetidas (no limite ou abaixo dele) usam a janela de recuperação mais ampla, para 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, porque a repetição de since_rowid ocorre pela mesma conexão RPC do imsg. A diferença é a janela: quando o Gateway consegue ler o chat.db (localmente), ele ancora o limite do rowid de inicialização, restringe o intervalo da repetição e entrega mensagens perdidas com até algumas horas. Por meio de um cliPath SSH remoto, ele não consegue ler o banco de dados; portanto, a repetição não é limitada e todas as linhas usam o limite de idade de mensagens em tempo real — ainda recupera mensagens perdidas recentemente e suprime mensagens pendentes antigas, mas com a janela mais estreita de mensagens em tempo real. Execute o Gateway no Mac com Messages para obter a janela de recuperação mais ampla.

Sinal visível para o operador

As mensagens pendentes suprimidas são registradas no nível padrão, nunca descartadas silenciosamente (o sinalizador recovery mostra qual janela foi aplicada):

imessage: mensagens pendentes de entrada obsoletas suprimidas account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; suprimidas 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 desabilitados (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 de configuração

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

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 conversão da configuração e transição passo a passo
• Pareamento — autenticação por mensagem direta e fluxo de pareamento
• Grupos — comportamento de chats em grupo e controle por menções
• Roteamento de canais — roteamento de sessões para mensagens
• Segurança — modelo de acesso e proteção