iMessage

​

Configuração rápida

brew install steipete/tap/imsg
brew update && brew upgrade imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

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

#!/usr/bin/env bash
exec 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.

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

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

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

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.

​

Configuração

1. Instale (ou atualize) imsg no Mac que executa o Messages.app:
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg 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.

​

Quando o SIP permanece ativado

• 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: { "*": { "requireMention": true } },
    },
  },
}

{
  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

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

• 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>

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

​

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 bash
exec 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

{
  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

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

​

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

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.

{
  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ê

​

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

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

​

Sinal visível para o operador

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

​

Migração

​

Solução de problemas

imsg rpc --help
imsg status --json
openclaw channels status --probe

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

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

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

openclaw channels status --probe --channel imessage

imsg chats --limit 1
imsg 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