Vindo do BlueBubbles

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.

​

Lista de verificação de migração

1. Verifique o imsg diretamente no Mac que executa o Messages.app (imsg chats, imsg history, imsg send e imsg rpc --help).
2. Copie as chaves de comportamento de channels.bluebubbles para channels.imessage: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, coalesceSameSenderDms e actions.
3. Remova chaves de transporte que não existem mais: serverUrl, password, URLs de Webhook e configuração do servidor BlueBubbles.
4. Se o Gateway não estiver em execução no Mac do Messages, defina channels.imessage.cliPath como um wrapper SSH e defina remoteHost para buscas remotas de anexos.
5. Com o Gateway parado, habilite channels.imessage e execute openclaw channels status --probe --channel imessage.
6. Teste uma DM, um grupo permitido, anexos se habilitados e cada ação de API privada que você espera que o agente use.
7. Exclua o servidor BlueBubbles e a configuração antiga de channels.bluebubbles depois que o caminho de iMessage for verificado.

​

Quando esta migração faz sentido

• Você já executa imsg no mesmo Mac (ou em um acessível por SSH) em que o Messages.app está conectado.
• Você quer um componente a menos em movimento — sem servidor BlueBubbles separado, sem endpoint REST para autenticar, sem encanamento de Webhook. Um único binário de CLI em vez de um servidor + aplicativo cliente + auxiliar.
• Você está em uma versão compatível de macOS / imsg em que a sondagem da API privada informa available: true.

​

O que o imsg faz

• As leituras vêm de ~/Library/Messages/chat.db usando um identificador SQLite somente leitura.
• Mensagens de entrada ao vivo vêm de imsg watch / watch.subscribe, que acompanha eventos do sistema de arquivos de chat.db com um fallback de sondagem.
• Envios usam automação do Messages.app para envios normais de texto e arquivos.
• Ações avançadas usam imsg launch para injetar o auxiliar imsg no Messages.app. É isso que desbloqueia confirmações de leitura, indicadores de digitação, envios ricos, edição, cancelamento de envio, resposta em tópico, tapbacks e gerenciamento de grupos.
• Compilações Linux podem inspecionar um chat.db copiado, mas não podem enviar, observar o banco de dados ao vivo do Mac nem acionar o Messages.app. Para iMessage no OpenClaw, execute imsg no Mac conectado ou por meio de um wrapper SSH para esse Mac.

​

Antes de começar

1. Instale o imsg no Mac que executa o Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   Se imsg chats falhar com unable to open database file, saída vazia ou authorization denied, conceda Acesso Total ao Disco ao terminal, editor, processo Node, serviço Gateway ou processo pai SSH que inicia imsg e reabra esse processo pai.
2. Verifique as superfícies de leitura, observação, envio e RPC antes de alterar a configuração do OpenClaw:
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   Substitua 42 por um ID de conversa real de imsg chats. O envio exige permissão de Automação para o Messages.app. Se o OpenClaw for executado por SSH, execute esses comandos pelo mesmo wrapper SSH ou contexto de usuário que o OpenClaw usará.
3. Habilite a ponte de API privada quando precisar de ações avançadas:
   imsg launch
   imsg status --json
   
   imsg launch exige que o SIP esteja desabilitado. Envio básico, histórico e observação funcionam sem imsg launch; ações avançadas não.
4. Depois de adicionar uma configuração habilitada de channels.imessage, verifique a ponte pelo OpenClaw:
   openclaw channels status --probe
   
   Você quer imessage.privateApi.available: true. Se ela informar false, corrija isso primeiro — consulte Detecção de capacidade. channels status --probe sonda apenas contas configuradas e habilitadas.
5. Faça um snapshot da sua configuração:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Tradução de configuração

​

Armadilha do registro de grupos

1. Lista de permissões de remetente / destino do chat (channels.imessage.groupAllowFrom) — verificada por isAllowedIMessageSender. Corresponde mensagens recebidas por identificador do remetente, chat_guid, chat_identifier ou chat_id. Mesmo formato que o BlueBubbles.
2. Registro de grupos (channels.imessage.groups) — verificado por resolveChannelGroupPolicy de inbound-processing.ts:199. Com groupPolicy: "allowlist", esta porta exige:
   • uma entrada curinga groups: { "*": { ... } } (define allowAll = true), ou
   • uma entrada explícita por chat_id em groups.

• Um warn de inicialização único por conta quando groupPolicy: "allowlist" está definido, mas channels.imessage.groups está vazio (sem curinga "*", sem entradas por chat_id) — disparado antes de qualquer mensagem chegar.
• Um warn único por chat_id na primeira vez que um grupo específico é descartado em tempo de execução, nomeando o chat_id e a chave exata a adicionar a groups para permiti-lo.

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

​

Passo a passo

1. Adicione um bloco iMessage junto ao bloco BlueBubbles existente. Mantenha-o desabilitado enquanto o Gateway ainda estiver roteando tráfego do BlueBubbles:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false,
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. Teste antes que o tráfego importe — pare o Gateway, habilite temporariamente o bloco iMessage e confirme que o iMessage aparece como saudável pela CLI:
   openclaw gateway stop
   # edit config: channels.imessage.enabled = true
   openclaw channels status --probe --channel imessage   # expect imessage.privateApi.available: true
   
   channels status --probe testa apenas contas configuradas e habilitadas. Não reinicie o Gateway com BlueBubbles e iMessage habilitados ao mesmo tempo, a menos que você queira intencionalmente que ambos os monitores de canal estejam em execução. Se você não for fazer a transição imediatamente, defina channels.imessage.enabled de volta como false antes de reiniciar o Gateway. Use os comandos diretos imsg em Antes de começar para validar o Mac antes de habilitar tráfego do OpenClaw.
3. Faça a transição. Depois que a conta iMessage habilitada reportar estado saudável, remova a configuração do BlueBubbles e mantenha o iMessage habilitado:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Reinicie o gateway. O tráfego de entrada do iMessage agora flui pelo Plugin incluído.
4. Verifique DMs. Envie uma mensagem direta ao agente; confirme que a resposta chega.
5. Verifique grupos separadamente. DMs e grupos usam caminhos de código diferentes — sucesso em DM não prova que grupos estão sendo roteados. Envie uma mensagem ao agente em um chat em grupo pareado e confirme que a resposta chega. Se o grupo ficar silencioso (sem resposta do agente, sem erro), verifique o log do gateway por imessage: dropping group message from chat_id=<id> ou pela linha de inicialização imessage: groupPolicy="allowlist" but channels.imessage.groups is empty — ambas aparecem no nível de log padrão. Se qualquer uma aparecer, seu bloco groups está ausente ou vazio — veja “Armadilha do registro de grupos” acima.
6. Verifique a superfície de ações — a partir de uma DM pareada, peça ao agente para reagir, editar, desfazer envio, responder, enviar uma foto e (em um grupo) renomear o grupo / adicionar ou remover um participante. Cada ação deve aparecer de forma nativa no Messages.app. Se alguma lançar “iMessage <action> requires the imsg private API bridge”, execute imsg launch novamente e atualize channels status --probe.
7. Remova o servidor e a configuração do BlueBubbles depois que DMs, grupos e ações do iMessage forem verificados. O OpenClaw não usará channels.bluebubbles.

​

Paridade de ações em resumo

​

Pareamento, sessões e associações ACP

• Aprovações de pareamento são mantidas por identificador. Você não precisa aprovar novamente remetentes conhecidos — channels.imessage.allowFrom reconhece as mesmas strings +15555550123 / user@example.com que o BlueBubbles usava.
• Sessões permanecem escopadas por agente + chat. DMs são consolidadas na sessão principal do agente com o padrão session.dmScope=main; sessões de grupo permanecem isoladas por chat_id. As chaves de sessão diferem (agent:<id>:imessage:group:<chat_id> versus o equivalente do BlueBubbles) — o histórico de conversas antigo sob chaves de sessão do BlueBubbles não é transferido para sessões do iMessage.
• Associações ACP que referenciam match.channel: "bluebubbles" precisam ser atualizadas para "imessage". Os formatos de match.peer.id (chat_id:, chat_guid:, chat_identifier:, identificador simples) são idênticos.

​

Sem canal de rollback

​

Relacionados

• Remoção do BlueBubbles e o caminho iMessage via imsg — anúncio curto e resumo para operadores.
• iMessage — referência completa do canal iMessage, incluindo configuração de imsg launch e detecção de capacidades.
• /channels/bluebubbles — URL legada que redireciona para este guia de migração.
• Pareamento — autenticação por DM e fluxo de pareamento.
• Roteamento de canais — como o gateway escolhe um canal para respostas de saída.