Mainstream messaging

iMessage

Status: integração nativa com CLI externa. O Gateway inicia imsg rpc e se comunica por JSON-RPC em stdio (sem daemon/porta separados).

BlueBubbles (fallback legado)

Continue usando para roteamento existente baseado no BlueBubbles; evite em novas configurações quando o imsg atender.

Pareamento

DMs do iMessage usam o modo de pareamento por padrão.

Referência de configuração

Referência completa dos campos do iMessage.

Configuração rápida

Mac local (caminho rápido)

Instale e verifique o imsg

brew install steipete/tap/imsg
imsg rpc --help

Configure o OpenClaw

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

Inicie o gateway

openclaw gateway

Aprove o primeiro pareamento por DM (dmPolicy padrão)

openclaw pairing list imessage
openclaw pairing approve imessage &lt;CODE&gt;

Solicitações de pareamento expiram após 1 hora.

Mac remoto por SSH

O OpenClaw requer apenas um cliPath compatível com stdio, então você pode apontar cliPath para um script wrapper que usa SSH para acessar um Mac remoto e executar imsg.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Configuração recomendada quando anexos estão habilitados:

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

Se remoteHost não estiver definido, o OpenClaw tentará detectá-lo automaticamente analisando o script wrapper SSH. remoteHost deve ser host ou user@host (sem espaços ou opções SSH). O OpenClaw usa verificação estrita de chave de host para SCP, portanto a chave do host de retransmissão já deve existir em ~/.ssh/known_hosts. Caminhos de anexos são validados contra raízes permitidas (attachmentRoots / remoteAttachmentRoots).

Requisitos e permissões (macOS)

O Messages deve estar conectado no Mac que executa imsg.
Acesso Total ao Disco é necessário para o contexto de processo que executa OpenClaw/imsg (acesso ao banco de dados do Messages).
Permissão de Automação é necessária para enviar mensagens pelo Messages.app.

Tip

Permissões são concedidas por contexto de processo. Se o gateway for executado sem interface (LaunchAgent/SSH), execute um comando interativo uma vez nesse mesmo contexto para acionar os prompts:

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

Controle de acesso e roteamento

Política de DM

channels.imessage.dmPolicy controla mensagens diretas:

pairing (padrão)
allowlist
open (requer que allowFrom inclua "*")
disabled

Campo de lista de permissões: channels.imessage.allowFrom.

Entradas da lista de permissões podem ser identificadores ou destinos de chat (chat_id:*, chat_guid:*, chat_identifier:*).

Política de grupo + menções

channels.imessage.groupPolicy controla o tratamento de grupos:

allowlist (padrão quando configurado)
open
disabled

Lista de permissões de remetentes de grupo: channels.imessage.groupAllowFrom.

Fallback em runtime: se groupAllowFrom não estiver definido, as verificações de remetente de grupo do iMessage usam allowFrom como fallback quando disponível. Observação de runtime: se channels.imessage estiver completamente ausente, o runtime usa groupPolicy="allowlist" como fallback e registra um aviso (mesmo que channels.defaults.groupPolicy esteja definido).

Controle de menções para grupos:

iMessage não tem metadados nativos de menção
a detecção de menções usa padrões regex (agents.list[].groupChat.mentionPatterns, fallback messages.groupChat.mentionPatterns)
sem padrões configurados, o controle por menção não pode ser aplicado

Comandos de controle de remetentes autorizados podem ignorar o controle por menção em grupos.

Sessões e respostas determinísticas

DMs usam roteamento direto; grupos usam roteamento de grupo.
Com session.dmScope=main padrão, DMs do iMessage são agrupadas na sessão principal do agente.
Sessões de grupo são isoladas (agent:<agentId>:imessage:group:<chat_id>).
Respostas são roteadas de volta ao iMessage usando metadados do canal/destino de origem.

Comportamento de conversas semelhantes a grupos:

Algumas conversas do iMessage com vários participantes podem chegar com is_group=false. Se esse chat_id estiver configurado explicitamente em channels.imessage.groups, o OpenClaw o tratará como tráfego de grupo (controle de grupo + isolamento de sessão de grupo).

Vínculos de conversa ACP

Chats legados do iMessage também podem ser vinculados a sessões ACP.

Fluxo rápido do operador:

Execute /acp spawn codex --bind here dentro da DM ou do chat de grupo permitido.
Mensagens futuras nessa mesma conversa do iMessage serã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 o vínculo.

Vínculos persistentes configurados são compatíveis por meio de entradas bindings[] de nível superior com type: "acp" e match.channel: "imessage".

match.peer.id pode usar:

identificador de DM normalizado, como +15555550123 ou [email protected]
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 o comportamento compartilhado de vínculo ACP.

Padrões de implantação

Usuário macOS dedicado para bot (identidade iMessage separada)

Use um Apple ID e um usuário macOS dedicados para que o tráfego do bot fique isolado do seu perfil pessoal do Messages.

Fluxo típico:

Crie/acesse um usuário macOS dedicado.
Entre no Messages com o Apple ID do bot nesse usuário.
Instale imsg nesse usuário.
Crie um wrapper SSH para que o OpenClaw possa executar imsg nesse contexto de usuário.
Aponte channels.imessage.accounts.<id>.cliPath e .dbPath para esse perfil de usuário.

A primeira execução pode exigir aprovações pela GUI (Automação + Acesso Total ao Disco) nessa sessão de usuário do bot.

Mac remoto por Tailscale (exemplo)

Topologia comum:

o gateway é executado em Linux/VM
iMessage + imsg é executado em um Mac na sua tailnet
o wrapper cliPath usa SSH para executar imsg
remoteHost habilita buscas de anexos por SCP

Exemplo:

{
channels: {
imessage: {
  enabled: true,
  cliPath: "~/.openclaw/scripts/imsg-ssh",
  remoteHost: "[email protected]",
  includeAttachments: true,
  dbPath: "/Users/bot/Library/Messages/chat.db",
},
},
}

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

Use chaves SSH para que tanto SSH quanto SCP sejam não interativos. Garanta que a chave do host seja confiável primeiro (por exemplo, ssh [email protected]) para que known_hosts seja preenchido.

Padrão multi-conta

iMessage permite configuração por conta em channels.imessage.accounts.

Cada conta pode sobrescrever campos como cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, configurações de histórico e listas de permissões de raízes de anexos.

Mídia, fragmentação e destinos de entrega

Anexos e mídia

a ingestão de anexos recebidos é opcional: channels.imessage.includeAttachments
caminhos de anexos remotos podem ser buscados por SCP quando remoteHost está definido
caminhos de anexos devem corresponder às raízes permitidas:
- channels.imessage.attachmentRoots (local)
- channels.imessage.remoteAttachmentRoots (modo SCP remoto)
- padrão de raiz padrão: /Users/*/Library/Messages/Attachments
SCP usa verificação estrita de chave de host (StrictHostKeyChecking=yes)
o tamanho de mídia enviada usa channels.imessage.mediaMaxMb (padrão 16 MB)

Fragmentação de saída

limite de fragmento de texto: channels.imessage.textChunkLimit (padrão 4000)
modo de fragmentação: channels.imessage.chunkMode
- length (padrão)
- newline (divisão priorizando parágrafos)

Formatos de endereçamento

Destinos explícitos preferidos:

chat_id:123 (recomendado para roteamento estável)
chat_guid:...
chat_identifier:...

Destinos por identificador também são compatíveis:

imessage:+1555...
sms:+1555...
[email protected]

imsg chats --limit 20

Gravações de configuração

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

Desabilitar:

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

Solução de problemas

imsg não encontrado ou RPC sem suporte

Valide o binário e o suporte a RPC:

imsg rpc --help
openclaw channels status --probe

Se a sondagem informar que RPC não tem suporte, atualize imsg.

DMs são ignoradas

Verifique:

channels.imessage.dmPolicy
channels.imessage.allowFrom
aprovações de pareamento (openclaw pairing list imessage)

Mensagens de grupo são ignoradas

Verifique:

channels.imessage.groupPolicy
channels.imessage.groupAllowFrom
comportamento da lista de permissões de channels.imessage.groups
configuração de padrão de menção (agents.list[].groupChat.mentionPatterns)

Anexos remotos falham

Verifique:

channels.imessage.remoteHost
channels.imessage.remoteAttachmentRoots
autenticação por chave SSH/SCP a partir do host do gateway
a chave do host existe em ~/.ssh/known_hosts no host do gateway
legibilidade do caminho remoto no Mac que executa Messages

Prompts de permissão do macOS foram perdidos

Execute novamente em um terminal GUI interativo no mesmo contexto de usuário/sessão e aprove os prompts:

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

Confirme que Acesso Total ao Disco + Automação foram concedidos para o contexto de processo que executa OpenClaw/imsg.

Ponteiros de referência de configuração

Relacionado

Visão geral dos canais — todos os canais compatíveis
Pareamento — autenticação por DM e fluxo de pareamento
Grupos — comportamento do chat em grupo e restrição por menções
Roteamento de canais — roteamento de sessões para mensagens
Segurança — modelo de acesso e endurecimento

# Configuração rápida

Mac local (caminho rápido)

Instale e verifique o imsg

Configure o OpenClaw

Inicie o gateway

Aprove o primeiro pareamento por DM (dmPolicy padrão)

Mac remoto por SSH

# Requisitos e permissões (macOS)

# Controle de acesso e roteamento

Política de DM

Política de grupo + menções

Sessões e respostas determinísticas

# Vínculos de conversa ACP

# Padrões de implantação

# Mídia, fragmentação e destinos de entrega

# Gravações de configuração

# Solução de problemas

# Ponteiros de referência de configuração

# Relacionado

Configuração rápida

Requisitos e permissões (macOS)

Controle de acesso e roteamento

Vínculos de conversa ACP

Padrões de implantação

Mídia, fragmentação e destinos de entrega

Gravações de configuração

Solução de problemas

Ponteiros de referência de configuração

Relacionado