​

iMessage (legado: imsg)

Recomendado: Use BlueBubbles para novas configurações do iMessage. O canal imsg é uma integração legada via CLI externa e pode ser removido em uma versão futura.

​

Início rápido (iniciante)

1. Garanta que o Messages esteja conectado neste Mac.
2. Instale imsg:
   • brew install steipete/tap/imsg
3. Configure o OpenClaw com channels.imessage.cliPath e channels.imessage.dbPath.
4. Inicie o gateway e aprove quaisquer prompts do macOS (Automação + Acesso Total ao Disco).

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

​

O que é

• Canal do iMessage baseado em imsg no macOS.
• Roteamento determinístico: respostas sempre retornam ao iMessage.
• DMs compartilham a sessão principal do agente; grupos são isolados (agent:<agentId>:imessage:group:<chat_id>).
• Se um tópico com múltiplos participantes chegar com is_group=false, você ainda pode isolá-lo chat_id usando channels.imessage.groups (veja “Tópicos tipo grupo” abaixo).

​

Escritas de configuração

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

​

Requisitos

• macOS com o Messages conectado.
• Acesso Total ao Disco para o OpenClaw + imsg (acesso ao DB do Messages).
• Permissão de Automação ao enviar.
• channels.imessage.cliPath pode apontar para qualquer comando que faça proxy de stdin/stdout (por exemplo, um script wrapper que conecta via SSH a outro Mac e executa imsg rpc).

​

Solução de problemas de Privacidade e Segurança TCC do macOS

• Acesso Total ao Disco: permita acesso ao processo que executa o OpenClaw (e a qualquer wrapper de shell/SSH que execute imsg). Isso é necessário para ler o banco de dados do Messages (chat.db).
• Automação → Messages: permita que o processo que executa o OpenClaw (e/ou seu terminal) controle o Messages.app para envios de saída.
• Saúde da CLI imsg: verifique se imsg está instalado e oferece suporte a RPC (imsg rpc --help).

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

​

Configuração (caminho rápido)

1. Garanta que o Messages esteja conectado neste Mac.
2. Configure o iMessage e inicie o gateway.

​

Usuário macOS dedicado para bot (para identidade isolada)

1. Crie um Apple ID dedicado (exemplo: [email protected]).
   • A Apple pode exigir um número de telefone para verificação / 2FA.
2. Crie um usuário macOS (exemplo: openclawhome) e faça login nele.
3. Abra o Messages nesse usuário macOS e entre no iMessage usando o Apple ID do bot.
4. Ative o Login Remoto (Ajustes do Sistema → Geral → Compartilhamento → Login Remoto).
5. Instale imsg:
   • brew install steipete/tap/imsg
6. Configure o SSH para que ssh <bot-macos-user>@localhost true funcione sem senha.
7. Aponte channels.imessage.accounts.bot.cliPath para um wrapper SSH que execute imsg como o usuário do bot.

#!/usr/bin/env bash
set -euo pipefail

# Run an interactive SSH once first to accept host keys:
#   ssh <bot-macos-user>@localhost true
exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
  "/usr/local/bin/imsg" "$@"

{
  channels: {
    imessage: {
      enabled: true,
      accounts: {
        bot: {
          name: "Bot",
          enabled: true,
          cliPath: "/path/to/imsg-bot",
          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db",
        },
      },
    },
  },
}

​

Variante remota/SSH (opcional)

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

{
  channels: {
    imessage: {
      cliPath: "~/imsg-ssh", // SSH wrapper to remote Mac
      remoteHost: "user@gateway-host", // for SCP file transfer
      includeAttachments: true,
    },
  },
}

​

Mac remoto via Tailscale (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 "$@"

• Garanta que o Mac esteja conectado ao Messages e que o Login Remoto esteja ativado.
• Use chaves SSH para que ssh [email protected] funcione sem prompts.
• remoteHost deve corresponder ao destino SSH para que o SCP possa buscar anexos.

​

Controle de acesso (DMs + grupos)

• Padrão: channels.imessage.dmPolicy = "pairing".
• Remetentes desconhecidos recebem um código de pareamento; as mensagens são ignoradas até a aprovação (códigos expiram após 1 hora).
• Aprovar via:
  • openclaw pairing list imessage
  • openclaw pairing approve imessage <CODE>
• O pareamento é a troca de tokens padrão para DMs do iMessage. Detalhes: Pareamento

• channels.imessage.groupPolicy = open | allowlist | disabled.
• channels.imessage.groupAllowFrom controla quem pode acionar em grupos quando allowlist está definido.
• O bloqueio por menção usa agents.list[].groupChat.mentionPatterns (ou messages.groupChat.mentionPatterns) porque o iMessage não tem metadados nativos de menção.
• Substituição multiagente: defina padrões por agente em agents.list[].groupChat.mentionPatterns.

​

Como funciona (comportamento)

• imsg transmite eventos de mensagens; o gateway os normaliza no envelope de canal compartilhado.
• As respostas sempre retornam ao mesmo id de chat ou handle.

​

Tópicos tipo grupo (is_group=false)

• isolamento de sessão (chave de sessão agent:<agentId>:imessage:group:<chat_id> separada)
• comportamento de lista de permissões de grupo / bloqueio por menção

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "42": { requireMention: false },
      },
    },
  },
}

​

Mídia + limites

• Ingestão opcional de anexos via channels.imessage.includeAttachments.
• Limite de mídia via channels.imessage.mediaMaxMb.

​

Limites

• Texto de saída é dividido em blocos de channels.imessage.textChunkLimit (padrão 4000).
• Divisão opcional por nova linha: defina channels.imessage.chunkMode="newline" para dividir em linhas em branco (limites de parágrafo) antes da divisão por tamanho.
• Uploads de mídia são limitados por channels.imessage.mediaMaxMb (padrão 16).

​

Endereçamento / destinos de entrega

• chat_id:123 (preferido)
• chat_guid:...
• chat_identifier:...
• handles diretos: imessage:+1555 / sms:+1555 / [email protected]

imsg chats --limit 20

​

Referência de configuração (iMessage)

• channels.imessage.enabled: habilitar/desabilitar a inicialização do canal.
• channels.imessage.cliPath: caminho para imsg.
• channels.imessage.dbPath: caminho do DB do Messages.
• channels.imessage.remoteHost: host SSH para transferência de anexos via SCP quando cliPath aponta para um Mac remoto (por exemplo, user@gateway-host). Auto-detectado a partir do wrapper SSH se não estiver definido.
• channels.imessage.service: imessage | sms | auto.
• channels.imessage.region: região de SMS.
• channels.imessage.dmPolicy: pairing | allowlist | open | disabled (padrão: pareamento).
• channels.imessage.allowFrom: lista de permissões de DM (handles, e-mails, números E.164 ou chat_id:*). open requer "*". O iMessage não tem nomes de usuário; use handles ou destinos de chat.
• channels.imessage.groupPolicy: open | allowlist | disabled (padrão: lista de permissões).
• channels.imessage.groupAllowFrom: lista de permissões de remetentes de grupo.
• channels.imessage.historyLimit / channels.imessage.accounts.*.historyLimit: máximo de mensagens de grupo a incluir como contexto (0 desativa).
• channels.imessage.dmHistoryLimit: limite de histórico de DM em turnos de usuário. Substituições por usuário: channels.imessage.dms["<handle>"].historyLimit.
• channels.imessage.groups: padrões por grupo + lista de permissões (use "*" para padrões globais).
• channels.imessage.includeAttachments: ingerir anexos no contexto.
• channels.imessage.mediaMaxMb: limite de mídia de entrada/saída (MB).
• channels.imessage.textChunkLimit: tamanho de bloco de saída (caracteres).
• channels.imessage.chunkMode: length (padrão) ou newline para dividir em linhas em branco (limites de parágrafo) antes da divisão por tamanho.

• agents.list[].groupChat.mentionPatterns (ou messages.groupChat.mentionPatterns).
• messages.responsePrefix.