iMessage

​

Configuração rápida

brew install steipete/tap/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>

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

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

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

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

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.

​

Configuração

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

​

Quando você não pode desabilitar o SIP

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

{
  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

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

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

{
  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, fragmentação e alvos de entrega

imsg chats --limit 20

​

Ações de 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,
    },
  },
}

​

Escritas de configuração

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

​

Coalescência 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 de pré-visualização OG como anexos.

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

​

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

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

​

Sinal visível ao operador

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

​

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"

​

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