iMessage

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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", // used for SCP attachment fetches
      includeAttachments: true,
      // Optional: override allowed attachment roots.
      // Defaults include /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 / cancelar envio / resposta encadeada / efeitos / operações de grupo), a Proteção de Integridade do Sistema deve estar desativada — veja Ativando 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"

​

Ativando a API privada do imsg

• Modo básico (padrão, sem alterações na SIP necessárias): texto e mídia enviados via send, observação/histórico de recebidos, lista de chats. É isso que você obtém imediatamente após uma instalação nova com brew install steipete/tap/imsg mais as permissões padrão do macOS acima.
• Modo API privada: imsg injeta uma dylib auxiliar em Messages.app para chamar funções internas de IMCore. É isso que desbloqueia react, edit, unsend, reply (encadeada), sendWithEffect, 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 enriquecido com suporte de bridge, mutação de mensagem e gerenciamento de chats são opcionais. Eles exigem que a SIP esteja desativada e que uma dylib auxiliar seja injetada em Messages.app. imsg launch se recusa a injetar quando a SIP está ativada.

​

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 informa 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. Isso é específico da versão do macOS porque o requisito subjacente da Apple depende do sistema operacional e do hardware:
   • 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 posteriores), 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 na Recuperação; em versões recentes do macOS, mantenha a tecla Shift esquerda pressionada ao clicar em Continuar, depois csrutil disable. Configurações de máquina virtual seguem um fluxo separado — faça primeiro um snapshot da VM.
   • macOS 26 / Tahoe: políticas de validação de biblioteca e verificações de entitlement privado do imagent ficaram ainda mais rígidas; imsg pode precisar de uma build atualizada para acompanhar. Se a injeção de imsg launch ou selectors específicos começarem a retornar false após uma atualização principal do macOS, verifique as notas de versão do imsg antes de presumir que a etapa da SIP foi bem-sucedida.
   Siga o fluxo de Modo de Recuperação da Apple para o seu Mac para desativar a SIP antes de executar imsg launch.
3. Injete o auxiliar. Com a SIP desativada e o Messages.app com sessão iniciada:
   imsg launch
   
   imsg launch se recusa a injetar quando a SIP ainda está ativada, então isso também serve como confirmação de que a etapa 2 funcionou.
4. Verifique a bridge pelo OpenClaw:
   openclaw channels status --probe
   
   A entrada do iMessage deve informar works, e imsg status --json | jq '.selectors' deve mostrar retractMessagePart: true mais quaisquer seletores de edição / digitação / leitura que sua build do macOS expõe. O controle por método do Plugin OpenClaw em actions.ts anuncia apenas ações cujo seletor subjacente é true, então a superfície de ações que você vê na lista de ferramentas do agente reflete o que a bridge realmente consegue fazer neste host.

​

Quando você não pode desativar a SIP

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

​

Vinculações de conversas ACP

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

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

{
  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: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is
        // slow or under memory pressure (observed gap can stretch past 2 s
        // then).
        imessage: 2500,
      },
    },
  },
}

​

Cenários e o que o agente vê

​

Recuperando mensagens após indisponibilidade do gateway

channels: {
  imessage: {
    catchup: {
      enabled: true,             // master switch (default: false)
      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)
      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)
      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)
      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)
    },
  },
}

​

Como ele executa

​

Semântica de cursor e repetição

{
  "lastSeenMs": 1717900800000,
  "lastSeenRowid": 482910,
  "updatedAt": 1717900801234,
  "failureRetries": { "<guid>": 1 }
}

• O cursor avança a cada despacho bem-sucedido e é mantido quando o despacho de uma linha lança uma exceção — a próxima inicialização tenta novamente a mesma linha a partir do cursor mantido.
• Após maxFailureRetries exceções consecutivas contra o mesmo guid, o catchup registra um warn e força o avanço do cursor além da mensagem travada, para que inicializações posteriores possam progredir.
• GUIDs já abandonados são ignorados ao serem vistos (sem tentativa de despacho) em execuções posteriores e contabilizados em skippedGivenUp no resumo da execução.

​

Sinais visíveis para o operador

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…
imessage catchup: giving up on guid=<guid> after <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

Quando deixar desativado

• O Gateway executa continuamente com reinício automático por watchdog e os intervalos são sempre < alguns segundos — o padrão desativado é suficiente.
• O volume de DMs é baixo e mensagens perdidas não mudariam o comportamento do agente — a janela inicial de firstRunLookbackMinutes pode despachar contexto antigo inesperado na primeira ativação.

​

Solução de problemas

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

#!/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 da referência de configuração

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

​

Relacionado

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