imsg

O que imsg faz?

Use imsg quando um agente OpenClaw precisar agir por meio da conta do aplicativo Mensagens do macOS local: inspecione o histórico de iMessage/SMS, escolha o DM ou grupo correto, envie mensagens/arquivos, responda, reaja, vote em enquetes ou use recursos de iMessage de API privada.

Não use esta skill para Telegram, Signal, WhatsApp, Discord, Slack ou para responder dentro da conversa atual do OpenClaw quando o canal configurado já roteia a resposta.

Fluxo do Agente

1. Primeiro, resolva a conversa.
2. Escolha DM, grupo existente ou novo grupo.
3. Escolha o comando de menor capacidade que possa realizar a ação solicitada.
4. Confirme qualquer envio ou alteração de estado visível, a menos que o usuário já tenha fornecido destinatário, conteúdo e ação exatos.
5. Execute com identificadores estáveis: prefira --chat-id para envios/monitoramento/histórico normais e --chat GUID do chat para ações de ponte.

Nunca inferir um destinatário a partir de um nome casual sozinho quando vários chats ou handles podem corresponder. Mostre o nome de exibição correspondente, handle(s), participantes do grupo e texto/ação da mensagem antes de enviar.

Requisitos do Host

• macOS 14+ com o aplicativo Mensagens conectado para ações de envio/reação/ponte.
• Acesso total ao disco para o contexto de processo que executa imsg ou OpenClaw; leituras falham sem acesso ao banco de dados do Mensagens.
• Permissão de automação para o aplicativo Mensagens ao usar send público.
• Permissão de acessibilidade para o contexto de processo que executa imsg react público; ele usa automação de interface do System Events. O tapback da ponte usa API privada em vez disso.
• Permissão de contatos opcional para resolução de nomes de contato.
• Envios de SMS exigem Encaminhamento de Mensagens de Texto do iPhone do usuário para este Mac.
• Linux lê apenas um chat.db copiado; não pode enviar, reagir, iniciar o aplicativo Mensagens, marcar como lido ou digitar.

Resolver Destinos

Use leituras --json. A saída é JSON delimitado por nova linha; use jq -s quando jq estiver disponível, ou consuma um objeto por linha diretamente.

imsg chats --limit 25 --json | jq -s
imsg search --query "jantar" --match contains --json | jq -s
imsg history --chat-id 42 --limit 20 --attachments --json | jq -s
imsg group --chat-id 42 --json

Regras de destino:

• DM para telefone/email: use imsg send --to quando o usuário forneceu um handle exato, ou após uma correspondência de chat única e inequívoca.
• Thread de DM existente: imsg send --chat-id <id> é mais seguro do que resolver um nome novamente.
• Grupo existente: inspecione com imsg group --chat-id <id> --json; envie com --chat-id, use a ponte com o GUID do chat de group.
• Novo grupo: use chat-create apenas quando o usuário explicitamente pediu para criar um grupo ou nenhum grupo existente corresponde.
• Nomes de grupo ambíguos: confirme participantes, não apenas o nome de exibição.
• SMS: use --service sms apenas quando solicitado ou quando o fallback do iMessage não é desejado. O relé SMS exige Encaminhamento de Mensagens de Texto.

Não faça do jq um pré-requisito obrigatório para a skill; é apenas um formatador conveniente para exemplos.

Escolha de Capacidade

Use automação pública do Mensagens quando suficiente:

• Ler/listar/pesquisar/monitorar: chats, group, history, search, watch
• Envio básico de texto/arquivo: send
• Tapback padrão para a mensagem recebida mais recente em um chat: react

Use a ponte de API privada apenas para recursos que a automação pública não pode realizar:

• Respostas ricas, formatação de texto, efeitos, assuntos, envios em várias partes
• Enquetes nativas do Apple Messages e votos em enquetes
• Tapback por GUID de mensagem ou remoção de tapback
• Editar, desenviar, excluir, notificar mesmo assim
• Recibos de leitura, indicadores de digitação, monitoramento de eventos de ponte
• Criar/nomear/foto/membro/sair/excluir/marcar ações de grupo
• Verificação de conta, whois, apelidos

Antes de ações de ponte, verifique:

imsg status --json

Se o host suporta ações de ponte, mas o Mensagens ainda não foi injetado, pergunte antes de executar imsg launch. Ele mata e reinicia o aplicativo Mensagens para injetar a ponte, então trate isso como uma alteração de estado visível:

imsg launch
imsg status --json

Se SIP, validação de biblioteca, verificações de entitlement privado ou seletores ausentes ainda bloquearem a capacidade, não peça ao usuário para desabilitar o SIP casualmente. Explique que a ação de API privada solicitada não está disponível neste host e ofereça a ação não-ponte mais próxima, se existir.

Cenários de DM

Handle exato, envio básico:

imsg send --to "+14155551212" --text "A caminho" --service auto

Thread de DM conhecida:

imsg send --chat-id 42 --text "A caminho"
imsg send --chat-id 42 --file /caminho/para/foto.jpg

Force canal apenas quando o usuário pedir:

imsg send --to "+14155551212" --text "bolha verde" --service sms
imsg send --to "+14155551212" --text "apenas iMessage" --service imessage --no-sms-fallback

Resposta encadeada, formatação, efeitos ou resposta com anexo:

imsg send-rich --chat 'iMessage;-;+15551234567' \
  --reply-to <message-guid> --text "texto de resposta"
imsg send-rich --chat 'iMessage;-;+15551234567' --text 'olá mundo' \
  --format '[{"start":0,"length":5,"styles":["bold"]}]'
imsg send-rich --chat 'iMessage;-;+15551234567' --text "boom" --effect impact
imsg send-attachment --chat 'iMessage;-;+15551234567' \
  --reply-to <message-guid> --file /caminho/para/arquivo.jpg

As faixas de formatação são posições UTF-16. Os estilos suportados incluem bold, italic, underline e strikethrough; use --format-file para JSON gerado.

Cenários de Grupo

Inspecione antes de agir:

imsg group --chat-id 42 --json
imsg history --chat-id 42 --limit 20 --json | jq -s

Enviar para um grupo existente:

imsg send --chat-id 42 --text "Funciona para mim"

Resposta de ponte ou enquete em um grupo existente:

imsg send-rich --chat 'iMessage;+;chat0000' \
  --reply-to <message-guid> --text "respondendo na thread"
imsg poll send --chat 'iMessage;+;chat0000' \
  --question "Jantar?" --option "Pizza" --option "Sushi"

Criar ou alterar grupos apenas mediante solicitação explícita:

imsg chat-create --addresses '+15551111111,+15552222222' --name 'Equipe' --text 'bom dia'
imsg chat-name --chat 'iMessage;+;chat0000' --name 'Renomeado'
imsg chat-photo --chat 'iMessage;+;chat0000' --file /caminho/para/grupo.jpg
imsg chat-add-member --chat 'iMessage;+;chat0000' --address +15553333333
imsg chat-remove-member --chat 'iMessage;+;chat0000' --address +15553333333
imsg chat-leave --chat 'iMessage;+;chat0000'
imsg chat-delete --chat 'iMessage;+;chat0000'
imsg chat-mark --chat 'iMessage;+;chat0000' --read

Mutações de grupo são altamente visíveis. Confirme o grupo exato e a lista de participantes antes de alterar associação, nome, foto, estado de leitura, sair ou excluir.

Reações e Respostas

O react público é limitado: reage apenas à mensagem recebida mais recente no chat.

imsg react --chat-id 42 --reaction like
imsg react --chat-id 42 --reaction love
imsg react --chat-id 42 --reaction dislike
imsg react --chat-id 42 --reaction laugh
imsg react --chat-id 42 --reaction emphasis
imsg react --chat-id 42 --reaction question

Para um GUID de mensagem específico ou remoção, use tapback da ponte:

imsg tapback --chat 'iMessage;-;+15551234567' --message <message-guid> --kind love
imsg tapback --chat 'iMessage;-;+15551234567' --message <message-guid> --kind love --remove

Use send-rich --reply-to <message-guid> para respostas encadeadas. Confirme a mensagem referenciada se o usuário disser "aquela" ou "a anterior".

Enquetes

As enquetes nativas do Apple Messages exigem a ponte. A criação precisa de pelo menos dois valores --option. A votação requer um de --option-id, --option-index ou --option.

O Mensagens renderiza apenas as opções em um balão de enquete; o título --question não é mostrado aos destinatários. Defina --question (obrigatório) mais pelo menos dois valores --option.

imsg poll send --chat 'iMessage;-;+15551234567' \
  --question "Jantar?" --option "Pizza" --option "Sushi"
imsg poll send --chat 'iMessage;+;chat0000' --reply-to <message-guid> \
  --question "Aprovar?" --option "Sim" --option "Não"
imsg poll vote --chat 'iMessage;+;chat0000' \
  --poll <poll-message-guid> --option-id <option-id>

Encontre IDs e opções de enquete com:

imsg history --chat-id 42 --limit 20 --json | jq -s '.[] | select(.poll != null) | {guid, poll}'

As linhas de voto em enquete são eventos poll, não tapbacks; watch --reactions não é necessário para vê-los.

Monitoramento e Agentes de Longa Duração

Para uma espera única curta, use watch:

imsg watch --chat-id 42 --since-rowid 9000 --json
imsg watch --chat-id 42 --attachments --convert-attachments --json
imsg watch --chat-id 42 --reactions --json
imsg watch --chat-id 42 --bb-events --json

--since-rowid é exclusivo. Sem ele, watch começa na linha mais recente. watch usa eventos do sistema de arquivos mais um fallback de polling de baixa frequência, então pode recuperar após eventos sidecar do SQLite perdidos. Objetos de polling aparecem sem --reactions.

Para um daemon ou integração multi-chat, use imsg rpc. Ele fala JSON-RPC 2.0 sobre stdin/stdout. Inspecione imsg status --json para rpc_methods antes de usar métodos de ponte ou enquete mais recentes.

Regras de Segurança

• Confirme destinatário, chat e conteúdo antes de cada envio, a menos que a solicitação do usuário já contenha valores exatos.
• Confirme alterações de estado visíveis: recibos de leitura, indicadores de digitação, edições, desenvios, exclusões, votos em enquetes, tapbacks, associação de grupo, nome/foto do grupo, sair/excluir chats.
• Nunca envie para números desconhecidos ou correspondências de nome de contato ambíguas sem aprovação.
• Confirme que os anexos existem e são os arquivos pretendidos.
• Prefira números de telefone no formato E.164; use --region US ou outra região apenas quando necessário para formatos locais.
• Não use ações de ponte só porque estão disponíveis; use-as apenas quando o comportamento solicitado precisar delas.