Por que o canal iMessage está obsoleto?

O canal iMessage depende do CLI de terceiros imsg e do frágil sistema de permissões TCC do macOS, que pode falhar após atualizações do sistema. O BlueBubbles oferece uma alternativa mais robusta baseada em API com funcionalidades adicionais como reações e suporte a chat em grupo.

Posso migrar do iMessage para o BlueBubbles?

Sim. Instale o BlueBubbles no seu Mac, configure o canal BlueBubbles no OpenClaw e desative o canal iMessage legado. O histórico de conversas não será transferido, mas todas as mensagens futuras serão roteadas pelo BlueBubbles.

Funciona em sistemas que não são Mac?

Não. A integração do iMessage requer macOS com o app Mensagens conectado. Não há suporte para Linux ou Windows. Para acesso multiplataforma ao iMessage, considere o BlueBubbles, que oferece um servidor baseado em web.

O bot pode enviar para usuários Android / SMS?

O bot responde apenas via iMessage. Se o destinatário não tiver um dispositivo Apple, a mensagem pode ser enviada como SMS dependendo das suas configurações do Mensagens, mas isso é gerenciado pelo macOS e não é controlado pelo OpenClaw.

OpenClaw GuideOpenClaw

Começar

Canal iMessage (Legacy) do OpenClaw

Mensagens

Avançado

Conecte o OpenClaw ao Apple iMessage usando a ferramenta CLI imsg no macOS. Esta integração legada usa uma interface JSON-RPC over stdio para ler e enviar iMessages através do banco de dados nativo de Mensagens do macOS. Nota: Este canal está obsoleto — para novas instalações, recomendamos fortemente o uso do BlueBubbles, que oferece uma integração baseada em REST API mais robusta com suporte mais amplo de funcionalidades.

Info rápida

DificuldadeAvançado

CategoriaMensagens

Recursos suportados2 / 6

iMessage (Legacy) Recursos suportados

Mensagens de texto

Suportado

Mídia e arquivos

Suportado

Reações

Não suportado

Threads

Não suportado

Mensagens de voz

Não suportado

Chat em grupo

Não suportado

iMessage (Legacy) Pré-requisitos

Um Mac executando macOS com o Mensagens conectado a um Apple ID
Permissão de Acesso Total ao Disco concedida ao OpenClaw e ao binário imsg
Permissão de Automação para envio de mensagens (concedida via prompts TCC do macOS)
O CLI imsg instalado via Homebrew: brew install steipete/tap/imsg
OpenClaw Gateway instalado e em execução

iMessage (Legacy) Configuração rápida

Instalar o CLI imsg

Execute 'brew install steipete/tap/imsg' para instalar a ferramenta CLI do iMessage. Após a instalação, execute 'imsg' uma vez em um terminal GUI para acionar os prompts de permissão do macOS (Acesso Total ao Disco e Automação).

Conceder permissões do macOS

Abra Ajustes do Sistema > Privacidade e Segurança. Conceda Acesso Total ao Disco tanto para o binário imsg quanto para o processo OpenClaw. A permissão de Automação para o Mensagens será solicitada automaticamente quando o imsg tentar enviar uma mensagem pela primeira vez.

Configurar e iniciar

Adicione a configuração do canal iMessage em ~/.openclaw/openclaw.json com as configurações cliPath e dbPath. Inicie o Gateway com 'openclaw start' e envie um iMessage de teste para verificar a conexão.

iMessage (Legacy) Exemplo de configuração

config.json

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/opt/homebrew/bin/imsg",
      "dbPath": "/Users/<username>/Library/Messages/chat.db"
    }
  }
}

iMessage (Legacy) Documentação Detalhada

Aviso de descontinuação

O canal iMessage é uma integração legada que pode ser removida em versões futuras do OpenClaw. Ele depende do CLI de terceiros imsg e das permissões TCC específicas do macOS, que podem se tornar instáveis após atualizações do sistema. Para novas implantações, recomendamos fortemente a migração para o canal BlueBubbles, que oferece: • Arquitetura baseada em REST API (sem dependência de CLI) • Suporte a reações com emoji • Suporte a chat em grupo • Gerenciamento de servidor multiplataforma via interface web • Entrega de mensagens mais confiável baseada em webhooks As configurações existentes do iMessage continuarão funcionando, mas nenhuma nova funcionalidade será adicionada a esta integração.

Este canal está obsoleto. Por favor, use o BlueBubbles para novas integrações com iMessage.

Visão geral da arquitetura

A integração do iMessage funciona iniciando o CLI imsg como processo filho via JSON-RPC over stdio: 1. O Gateway inicia 'imsg rpc' como subprocesso, comunicando-se via stdin/stdout. 2. O CLI imsg lê novas mensagens do banco de dados de Mensagens do macOS (chat.db) usando SQLite. 3. Quando uma nova mensagem chega, o imsg notifica o Gateway via JSON-RPC. 4. O Gateway processa a mensagem com seu agente de IA e envia a resposta via imsg, que usa a Automação do macOS para enviar o iMessage. Esta arquitetura requer que o Gateway execute no mesmo Mac onde o Mensagens está conectado. As respostas são roteadas de forma determinística para o iMessage, e cada conversa (DM ou grupo) mantém isolamento de sessão independente.

Políticas de mensagens diretas

As políticas de DM controlam como o bot lida com conversas individuais no iMessage. **pairing (padrão)** — Remetentes desconhecidos recebem um código de pareamento que deve ser confirmado antes do bot responder. Isso previne acesso não autorizado. **allowlist** — Apenas números de telefone ou Apple IDs listados em allowFrom podem interagir com o bot. **open** — Qualquer remetente do iMessage recebe uma resposta. Requer allowFrom: ["*"]. **disabled** — O bot ignora todas as mensagens diretas.

openclaw.json

{
  "channels": {
    "imessage": {
      "dmPolicy": "pairing",
      "allowFrom": ["+1234567890", "user@icloud.com"]
    }
  }
}

Configuração de chat em grupo

As políticas de chat em grupo controlam o comportamento do bot em conversas de grupo do iMessage. **open** — O bot responde a todas as mensagens em qualquer grupo ao qual seja adicionado. **allowlist** — O bot só responde em grupos explicitamente listados na configuração. **disabled (padrão)** — O bot não responde em chats de grupo. Quando o chat em grupo está habilitado, o acionamento por menção pode ser configurado para que o bot só responda quando seu nome for mencionado, reduzindo ruído em grupos movimentados.

openclaw.json

{
  "channels": {
    "imessage": {
      "groupPolicy": "allowlist",
      "mentionPattern": "@bot"
    }
  }
}

Configuração de Mac remoto via SSH

Para implantações headless ou remotas, o CLI imsg pode ser executado em outro Mac via SSH. O Gateway inicia o processo imsg através de uma conexão SSH, e os anexos são transferidos via SCP. Isso é útil quando o Mac executando o Mensagens está em um local diferente (por exemplo, um servidor Mac Mini), enquanto o Gateway executa em outro lugar. Requisitos: • Autenticação SSH baseada em chave (sem prompts interativos) • O Mac remoto deve ter o imsg instalado e as permissões concedidas • SCP deve estar disponível para transferência de anexos

openclaw.json

{
  "channels": {
    "imessage": {
      "remoteHost": "mac-server.local",
      "cliPath": "/usr/local/bin/imsg"
    }
  }
}

Use autenticação por chave SSH para evitar prompts interativos de senha.

Ferramentas como Tailscale podem simplificar o acesso remoto ao servidor Mac.

Permissões do macOS (TCC)

A integração do iMessage requer permissões de privacidade específicas do macOS (gerenciadas pelo framework TCC): **Acesso Total ao Disco** — Necessário para ler o banco de dados de Mensagens (chat.db). Tanto o binário imsg quanto o processo OpenClaw precisam desta permissão. **Automação** — Necessária para enviar mensagens através do app Mensagens. Esta permissão geralmente é concedida via prompt do sistema quando o imsg tenta enviar pela primeira vez. Se estiver executando em ambiente headless (por exemplo, via SSH ou launchd), os prompts de permissão podem não aparecer. Nesse caso, execute 'imsg' uma vez em uma sessão de terminal GUI interativa para acionar os prompts, e depois retorne à operação headless.

Os prompts de permissão do macOS só aparecem em sessões GUI. Execute o imsg interativamente pelo menos uma vez antes da implantação headless.

iMessage (Legacy) Referência de Configuração

Key	Type	Default	Description
enabled	boolean	true	Ativar ou desativar o canal iMessage
cliPath	string	"/usr/local/bin/imsg"	Caminho para o binário CLI imsg. O Homebrew instala em /opt/homebrew/bin/imsg em Macs com Apple Silicon ou /usr/local/bin/imsg em Macs com Intel
dbPath	string	"~/Library/Messages/chat.db"	Caminho para o banco de dados SQLite de Mensagens do macOS
dmPolicy	string	"pairing"	Política de acesso DM: 'pairing', 'allowlist', 'open' ou 'disabled'
groupPolicy	string	"disabled"	Política de chat em grupo: 'open', 'allowlist' ou 'disabled'
allowFrom	string[]	[]	Números de telefone ou Apple IDs autorizados a contatar o bot
includeAttachments	boolean	false	Se deve processar anexos de mídia de mensagens recebidas
mediaMaxMb	number	10	Tamanho máximo de arquivo de mídia em MB
textChunkLimit	number	4000	Máximo de caracteres por mensagem enviada
chunkMode	string	"length"	Modo de divisão de texto: 'length' (limite de caracteres) ou 'newline' (limites de parágrafo)
historyLimit	number	20	Máximo de mensagens anteriores incluídas como contexto da conversa
configWrites	boolean	true	Permitir comandos /config set\|unset via iMessage
remoteHost	string	""	Nome do host SSH para executar imsg em um Mac remoto

enabled

Type: booleanDefault: true

Ativar ou desativar o canal iMessage

cliPath

Type: stringDefault: "/usr/local/bin/imsg"

Caminho para o binário CLI imsg. O Homebrew instala em /opt/homebrew/bin/imsg em Macs com Apple Silicon ou /usr/local/bin/imsg em Macs com Intel

dbPath

Type: stringDefault: "~/Library/Messages/chat.db"

Caminho para o banco de dados SQLite de Mensagens do macOS

dmPolicy

Type: stringDefault: "pairing"

Política de acesso DM: 'pairing', 'allowlist', 'open' ou 'disabled'

groupPolicy

Type: stringDefault: "disabled"

Política de chat em grupo: 'open', 'allowlist' ou 'disabled'

allowFrom

Type: string[]Default: []

Números de telefone ou Apple IDs autorizados a contatar o bot

includeAttachments

Type: booleanDefault: false

Se deve processar anexos de mídia de mensagens recebidas

mediaMaxMb

Type: numberDefault: 10

Tamanho máximo de arquivo de mídia em MB

textChunkLimit

Type: numberDefault: 4000

Máximo de caracteres por mensagem enviada

chunkMode

Type: stringDefault: "length"

Modo de divisão de texto: 'length' (limite de caracteres) ou 'newline' (limites de parágrafo)

historyLimit

Type: numberDefault: 20

Máximo de mensagens anteriores incluídas como contexto da conversa

configWrites

Type: booleanDefault: true

Permitir comandos /config set|unset via iMessage

remoteHost

Type: stringDefault: ""

Nome do host SSH para executar imsg em um Mac remoto

iMessage (Legacy) Perguntas Frequentes

iMessage (Legacy) Solução de Problemas

O bot não recebe nem envia mensagens

Permissões do macOS ausentes (Acesso Total ao Disco ou Automação) para o binário imsg ou o processo OpenClaw.

Abra Ajustes do Sistema > Privacidade e Segurança. Verifique se tanto o imsg quanto o OpenClaw têm Acesso Total ao Disco. Execute 'imsg' em um terminal GUI para acionar os prompts de permissão ausentes. Reinicie o Gateway após conceder as permissões.

Os prompts de permissão não aparecem

O processo está executando em ambiente headless (SSH, launchd) onde o macOS não pode exibir prompts TCC.

Faça login no Mac via sessão GUI (compartilhamento de tela ou acesso físico). Execute 'imsg' no Terminal.app para acionar os prompts. Após as permissões serem concedidas, você pode retornar à operação headless.

Erro: chat.db não encontrado ou acesso negado

A configuração dbPath está incorreta ou o Acesso Total ao Disco não foi concedido.

Verifique se o dbPath aponta para o banco de dados de Mensagens correto (geralmente ~/Library/Messages/chat.db). Certifique-se de que o Acesso Total ao Disco está habilitado para o processo OpenClaw nos Ajustes do Sistema.

Conexão SSH remota falha

A autenticação por chave SSH não está configurada ou o host remoto está inacessível.

Certifique-se de que a autenticação por chave SSH está configurada entre o host Gateway e o Mac remoto. Teste a conexão manualmente com 'ssh <remoteHost> imsg --version'. Verifique o firewall e a conectividade de rede.

Ver documentação completa Voltar para todos os canais