Vindo do BlueBubbles

​

Lista de verificação da migração

1. Verifique o imsg diretamente no Mac que executa o Messages.app (imsg chats, imsg history, imsg send, 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 as chaves de transporte que não existem mais: serverUrl, password, URLs de Webhook e a configuração do servidor BlueBubbles.
4. Se o Gateway não estiver em execução no Mac com o Messages, defina channels.imessage.cliPath como um wrapper SSH e defina remoteHost para buscar anexos remotos.
5. Ative channels.imessage, reinicie o Gateway e execute openclaw channels status --probe --channel imessage.
6. Teste uma mensagem direta, um grupo permitido, anexos se estiverem ativados e todas as ações da API privada que você espera que o agente use.
7. Exclua o servidor BlueBubbles e a configuração antiga de channels.bluebubbles depois de verificar o caminho do iMessage.

​

O que o imsg faz

• As leituras são feitas em ~/Library/Messages/chat.db usando uma conexão SQLite somente leitura.
• As mensagens recebidas em tempo real vêm de imsg watch / watch.subscribe, que acompanha eventos do sistema de arquivos de chat.db com consulta periódica como alternativa.
• Os envios usam a automação do Messages.app para enviar textos e arquivos comuns.
• As ações avançadas usam imsg launch para injetar o auxiliar do imsg no Messages.app. É isso que habilita confirmações de leitura, indicadores de digitação, envios avançados, edição, cancelamento de envio, respostas em conversas encadeadas, tapbacks, enquetes e gerenciamento de grupos.
• As compilações para Linux podem inspecionar uma cópia de chat.db, mas não podem enviar mensagens, monitorar o banco de dados ativo do Mac nem controlar o Messages.app. Para usar o iMessage com o OpenClaw, execute o imsg no Mac com a sessão iniciada 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
   brew update && brew upgrade imsg
   imsg --version
   imsg chats --limit 3
   
   Na configuração local habitual, o assistente de configuração do OpenClaw pode oferecer, mediante confirmação do usuário, a instalação ou atualização do imsg pelo Homebrew no Mac com sessão iniciada no Messages. A configuração manual e as topologias com wrapper SSH continuam sob responsabilidade do operador: repita a atualização pelo Homebrew no mesmo contexto de usuário local ou remoto que executará o imsg. Se imsg chats falhar com unable to open database file, não produzir saída ou exibir authorization denied, conceda Acesso Total ao Disco ao terminal, editor, processo do Node, serviço do Gateway ou processo pai do SSH que inicia o imsg e, em seguida, reabra esse processo pai.
2. Verifique as funcionalidades de leitura, monitoramento, 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 "Teste do imsg no OpenClaw"
   imsg rpc --help
   
   Substitua 42 por um ID de conversa real obtido com imsg chats. O envio exige permissão de Automação para o Messages.app. Se o OpenClaw for executado por SSH, execute esses comandos usando o mesmo wrapper SSH ou contexto de usuário que o OpenClaw usará. Se a leitura funcionar, mas os envios falharem com o erro -1743 do AppleEvents, verifique se a permissão de Automação foi atribuída a /usr/libexec/sshd-keygen-wrapper; consulte Falha de envios pelo wrapper SSH com AppleEvents -1743.
3. Ative a ponte da API privada. Isso é altamente recomendado para o iMessage no OpenClaw, pois respostas, tapbacks, efeitos, enquetes, respostas a anexos e ações de grupo dependem dela:
   imsg launch
   imsg status --json
   
   imsg launch exige que o SIP esteja desativado (e, nas versões modernas do macOS, que a validação de bibliotecas esteja flexibilizada — consulte Como ativar a API privada do imsg). O envio básico, o histórico e o monitoramento funcionam sem imsg launch; a superfície completa de ações do iMessage no OpenClaw não funciona.
4. Depois de ativar channels.imessage e iniciar o Gateway, verifique a ponte pelo OpenClaw:
   openclaw channels status --probe
   
   A conta do iMessage deve informar works; com --json, a carga útil da sondagem inclui privateApi.available: true. Se ela informar false, corrija isso primeiro — consulte Detecção de recursos. A sondagem exige que o Gateway esteja acessível (caso contrário, a CLI recorre a uma saída baseada apenas na configuração) e verifica somente contas configuradas e ativadas.
5. Crie uma cópia de segurança da configuração:
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   

​

Conversão da configuração

​

Armadilha do registro de grupos

1. Lista de permissões do remetente/alvo do chat (channels.imessage.groupAllowFrom) — corresponde ao identificador do remetente ou ao alvo do chat (entradas chat_id:, chat_guid:, chat_identifier:). Quando groupAllowFrom não está definido, essa verificação recorre a allowFrom; um groupAllowFrom: [] explícito desativa esse fallback e descarta todas as mensagens de grupo com groupPolicy: "allowlist".
2. Registro de grupos (channels.imessage.groups) — indexado pelo chat_id numérico do iMessage:
   • Sem um bloco groups (ou com um bloco vazio): os grupos passam por essa verificação desde que a verificação 1 tenha uma lista efetiva e não vazia de remetentes permitidos; a filtragem de remetentes controla o acesso e nenhum aviso de descarte total é emitido na inicialização.
   • groups com entradas, mas sem "*": somente as chaves chat_id listadas passam. Listar qualquer grupo transforma o registro em uma lista de permissões, mesmo com groupPolicy: "open".
   • groups: { "*": { ... } }: todos os grupos passam por essa verificação.

• Uma vez por conta durante a inicialização, quando groupPolicy: "allowlist" está definido e a lista efetiva de remetentes de grupo permitidos está vazia: imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured .... Defina groupAllowFrom (ou allowFrom) para admitir remetentes; adicionar apenas groups não atende à verificação de remetente.
• Uma vez por chat_id durante a execução, quando o registro descarta um grupo: imessage: dropping group message from chat_id=<id> ... not in channels.imessage.groups allowlist, indicando a chave exata que deve ser adicionada.

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

​

Passo a passo

1. Traduza a configuração. Mantenha o novo bloco desativado enquanto edita; o bloco antigo channels.bluebubbles é ignorado pelo OpenClaw atual e pode permanecer ao lado como referência:
   {
     channels: {
       imessage: {
         enabled: false, // altere para true quando estiver pronto para fazer a transição
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copie de bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copie de bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // o curinga é copiado literalmente; redefina as chaves das entradas por conversa usando chat_id
         // as ações são ativadas por padrão; defina opções individuais como false para desativá-las
       },
     },
   }
   
2. Faça a transição e execute a sondagem. Defina channels.imessage.enabled: true, reinicie o Gateway e confirme que o canal é relatado como íntegro:
   openclaw gateway restart
   openclaw channels status --probe --channel imessage   # espere "works"; --json mostra privateApi.available: true
   
   A sondagem exige um Gateway acessível e verifica somente contas configuradas e ativadas. Use os comandos diretos de imsg em Antes de começar para validar o próprio Mac.
3. Verifique as mensagens diretas. Envie uma mensagem direta ao agente e confirme que a resposta chega.
4. Verifique os grupos separadamente. Mensagens diretas e grupos seguem caminhos de código diferentes — o sucesso das mensagens diretas não comprova que o roteamento dos grupos funciona. Envie uma mensagem em uma conversa de grupo permitida e confirme que a resposta chega. Se o grupo ficar silencioso (sem resposta do agente e sem erro), verifique no log do Gateway as duas linhas warn da seção “Armadilha do registro de grupos” acima. O aviso de inicialização significa que a lista de remetentes permitidos efetiva está vazia; um aviso por chat_id significa que um registro groups preenchido não contém essa conversa.
5. Verifique a superfície de ações. Em uma mensagem direta pareada, peça ao agente para reagir, editar, cancelar o envio, responder, enviar uma foto e, em um grupo, renomear o grupo ou adicionar/remover um participante. Cada ação deve ocorrer de forma nativa no Messages.app. Se alguma ação gerar iMessage <action> requires the imsg private API bridge, execute imsg launch novamente e atualize com openclaw channels status --probe.
6. Remova o servidor BlueBubbles e o bloco channels.bluebubbles depois de verificar as mensagens diretas, os grupos e as ações do iMessage. O OpenClaw não lê channels.bluebubbles.

​

Comparação rápida de ações

​

Pareamento, sessões e vínculos ACP

• As listas de permissões são mantidas por identificador. channels.imessage.allowFrom reconhece as mesmas strings +15555550123 / user@example.com usadas pelo BlueBubbles — copie-as literalmente.
• As aprovações do armazenamento de pareamento não são transferidas. O armazenamento de pareamento é específico de cada canal, e nada migra o armazenamento antigo do BlueBubbles. Os remetentes aprovados somente por pareamento precisam parear novamente no iMessage, ou você deve adicionar os identificadores deles a allowFrom.
• As sessões permanecem restritas por agente + conversa. As mensagens diretas são consolidadas na sessão principal do agente com o padrão session.dmScope=main; as sessões de grupo permanecem isoladas por chat_id (agent:<agentId>:imessage:group:<chat_id>). O histórico antigo de conversas armazenado sob chaves de sessão do BlueBubbles não é transferido para as sessões do iMessage.
• Os vínculos ACP que fazem referência a match.channel: "bluebubbles" devem ser alterados para "imessage". Os formatos de match.peer.id (chat_id:, chat_guid:, chat_identifier:, identificador simples) são idênticos.

​

Nenhum canal de reversão

​

Relacionados

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