iMessage (legado: imsg)¶

Recomendado: Use BlueBubbles para nuevas configuraciones de iMessage.

El canal imsg es una integración heredada de CLI externa y puede eliminarse en una versión futura.

Estado: integración heredada de CLI externa. El Gateway inicia imsg rpc (JSON-RPC sobre stdio).

Configuración rápida (principiante)¶

Asegúrese de que Mensajes haya iniciado sesión en este Mac.
Instale imsg: - brew install steipete/tap/imsg
Configure OpenClaw con channels.imessage.cliPath y channels.imessage.dbPath.
Inicie el gateway y apruebe cualquier aviso de macOS (Automatización + Acceso total al disco).

Configuración mínima:

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

Qué es¶

Canal de iMessage respaldado por imsg en macOS.
Enrutamiento determinista: las respuestas siempre regresan a iMessage.
Los mensajes directos comparten la sesión principal del agente; los grupos están aislados (agent:<agentId>:imessage:group:<chat_id>).
Si llega un hilo con múltiples participantes con is_group=false, aún puede aislarlo chat_id usando channels.imessage.groups (consulte “Hilos tipo grupo” más abajo).

Escrituras de configuración¶

De forma predeterminada, iMessage puede escribir actualizaciones de configuración activadas por /config set|unset (requiere commands.config: true).

Desactivar con:

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

Requisitos¶

macOS con Mensajes iniciado sesión.
Acceso total al disco para OpenClaw + imsg (acceso a la base de datos de Mensajes).
Permiso de Automatización al enviar.
channels.imessage.cliPath puede apuntar a cualquier comando que proxee stdin/stdout (por ejemplo, un script envoltorio que use SSH a otro Mac y ejecute imsg rpc).

Solución de problemas de Privacidad y Seguridad TCC de macOS¶

Si el envío/recepción falla (por ejemplo, imsg rpc sale con código distinto de cero, expira o el gateway parece colgarse), una causa común es un aviso de permisos de macOS que nunca se aprobó.

macOS concede permisos TCC por contexto de app/proceso. Apruebe los avisos en el mismo contexto que ejecuta imsg (por ejemplo, Terminal/iTerm, una sesión de LaunchAgent o un proceso iniciado por SSH).

Lista de verificación:

Acceso total al disco: permita el acceso para el proceso que ejecuta OpenClaw (y cualquier envoltorio de shell/SSH que ejecute imsg). Esto es necesario para leer la base de datos de Mensajes (chat.db).
Automatización → Mensajes: permita que el proceso que ejecuta OpenClaw (y/o su terminal) controle Messages.app para envíos salientes.
Estado de la CLI de imsg: verifique que imsg esté instalado y admita RPC (imsg rpc --help).

Consejo: Si OpenClaw se ejecuta sin interfaz (LaunchAgent/systemd/SSH), el aviso de macOS puede ser fácil de pasar por alto. Ejecute un comando interactivo único en una terminal GUI para forzar el aviso y luego reintente:

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

Permisos de carpetas relacionados de macOS (Escritorio/Documentos/Descargas): /platforms/mac/permissions.

Configuración (ruta rápida)¶

Asegúrese de que Mensajes haya iniciado sesión en este Mac.
Configure iMessage e inicie el gateway.

Usuario macOS de bot dedicado (para identidad aislada)¶

Si desea que el bot envíe desde una identidad de iMessage separada (y mantener limpios sus Mensajes personales), use un Apple ID dedicado + un usuario macOS dedicado.

Cree un Apple ID dedicado (ejemplo: my-cool-bot@icloud.com). - Apple puede requerir un número de teléfono para verificación / 2FA.
Cree un usuario macOS (ejemplo: openclawhome) e inicie sesión en él.
Abra Mensajes en ese usuario macOS e inicie sesión en iMessage usando el Apple ID del bot.
Habilite Inicio de sesión remoto (Ajustes del sistema → General → Compartir → Inicio de sesión remoto).
Instale imsg: - brew install steipete/tap/imsg
Configure SSH para que ssh <bot-macos-user>@localhost true funcione sin contraseña.
Apunte channels.imessage.accounts.bot.cliPath a un envoltorio SSH que ejecute imsg como el usuario del bot.

Nota de primera ejecución: el envío/recepción puede requerir aprobaciones de GUI (Automatización + Acceso total al disco) en el usuario macOS del bot. Si imsg rpc parece atascado o sale, inicie sesión en ese usuario (Screen Sharing ayuda), ejecute una vez imsg chats --limit 1 / imsg send ..., apruebe los avisos y luego reintente. Consulte Solución de problemas de Privacidad y Seguridad TCC de macOS.

Ejemplo de envoltorio (chmod +x). Reemplace <bot-macos-user> con su nombre de usuario real de macOS:

#!/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" "$@"

Ejemplo de configuración:

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

Para configuraciones de una sola cuenta, use opciones planas (channels.imessage.cliPath, channels.imessage.dbPath) en lugar del mapa accounts.

Variante remota/SSH (opcional)¶

Si desea iMessage en otro Mac, configure channels.imessage.cliPath para que apunte a un envoltorio que ejecute imsg en el host macOS remoto por SSH. OpenClaw solo necesita stdio.

Ejemplo de envoltorio:

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

Adjuntos remotos: Cuando cliPath apunta a un host remoto vía SSH, las rutas de adjuntos en la base de datos de Mensajes hacen referencia a archivos en la máquina remota. OpenClaw puede obtenerlos automáticamente por SCP configurando channels.imessage.remoteHost:

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

Si remoteHost no está configurado, OpenClaw intenta detectarlo automáticamente analizando el comando SSH en su script envoltorio. Se recomienda la configuración explícita por confiabilidad.

Mac remoto vía Tailscale (ejemplo)¶

Si el Gateway se ejecuta en un host/VM Linux pero iMessage debe ejecutarse en un Mac, Tailscale es el puente más sencillo: el Gateway se comunica con el Mac a través de la tailnet, ejecuta imsg por SSH y recupera los adjuntos por SCP.

Arquitectura:

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#ffffff',
    'primaryTextColor': '#000000',
    'primaryBorderColor': '#000000',
    'lineColor': '#000000',
    'secondaryColor': '#f9f9fb',
    'tertiaryColor': '#ffffff',
    'clusterBkg': '#f9f9fb',
    'clusterBorder': '#000000',
    'nodeBorder': '#000000',
    'mainBkg': '#ffffff',
    'edgeLabelBackground': '#ffffff'
  }
}}%%
flowchart TB
 subgraph T[" "]
 subgraph Tailscale[" "]
    direction LR
      Gateway["<b>Gateway host (Linux/VM)<br></b><br>openclaw gateway<br>channels.imessage.cliPath"]
      Mac["<b>Mac with Messages + imsg<br></b><br>Messages signed in<br>Remote Login enabled"]
  end
    Gateway -- SSH (imsg rpc) --> Mac
    Mac -- SCP (attachments) --> Gateway
    direction BT
    User["user@gateway-host"] -- "Tailscale tailnet (hostname or 100.x.y.z)" --> Gateway
end

Ejemplo concreto de configuración (hostname de Tailscale):

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

Ejemplo de envoltorio (~/.openclaw/scripts/imsg-ssh):

#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Notas:

Asegúrese de que el Mac haya iniciado sesión en Mensajes y que Inicio de sesión remoto esté habilitado.
Use claves SSH para que ssh bot@mac-mini.tailnet-1234.ts.net funcione sin avisos.
remoteHost debe coincidir con el destino SSH para que SCP pueda obtener los adjuntos.

Compatibilidad con múltiples cuentas: use channels.imessage.accounts con configuración por cuenta y name opcional. Consulte gateway/configuration para el patrón compartido. No confirme ~/.openclaw/openclaw.json (a menudo contiene tokens).

Control de acceso (mensajes directos + grupos)¶

DMs:

Predeterminado: channels.imessage.dmPolicy = "pairing".
Los remitentes desconocidos reciben un código de emparejamiento; los mensajes se ignoran hasta su aprobación (los códigos expiran después de 1 hora).
Apruebe mediante:
openclaw pairing list imessage
openclaw pairing approve imessage <CODE>
El emparejamiento es el intercambio de tokens predeterminado para mensajes directos de iMessage. Detalles: Emparejamiento

Grupos:

channels.imessage.groupPolicy = open | allowlist | disabled.
channels.imessage.groupAllowFrom controla quién puede activar en grupos cuando allowlist está configurado.
El control por menciones usa agents.list[].groupChat.mentionPatterns (o messages.groupChat.mentionPatterns) porque iMessage no tiene metadatos nativos de menciones.
Anulación multiagente: configure patrones por agente en agents.list[].groupChat.mentionPatterns.

Cómo funciona (comportamiento)¶

imsg transmite eventos de mensajes; el gateway los normaliza en el sobre compartido del canal.
Las respuestas siempre se enrutan de vuelta al mismo id de chat o identificador.

Hilos tipo grupo (`is_group=false`)¶

Algunos hilos de iMessage pueden tener múltiples participantes pero aun así llegar con is_group=false según cómo Mensajes almacena el identificador del chat.

Si configura explícitamente un chat_id bajo channels.imessage.groups, OpenClaw trata ese hilo como un “grupo” para:

aislamiento de sesión (clave de sesión agent:<agentId>:imessage:group:<chat_id> separada)
comportamiento de lista de permitidos de grupo / control por menciones

Ejemplo:

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

Esto es útil cuando desea una personalidad/modelo aislado para un hilo específico (consulte Enrutamiento multiagente). Para aislamiento del sistema de archivos, consulte Sandboxing.

Medios + límites¶

Ingesta opcional de adjuntos mediante channels.imessage.includeAttachments.
Límite de medios mediante channels.imessage.mediaMaxMb.

Límites¶

El texto saliente se fragmenta a channels.imessage.textChunkLimit (predeterminado 4000).
Fragmentación opcional por saltos de línea: configure channels.imessage.chunkMode="newline" para dividir en líneas en blanco (límites de párrafo) antes de la fragmentación por longitud.
Las cargas de medios están limitadas por channels.imessage.mediaMaxMb (predeterminado 16).

Direccionamiento / destinos de entrega¶

Prefiera chat_id para un enrutamiento estable:

chat_id:123 (preferido)
chat_guid:...
chat_identifier:...
identificadores directos: imessage:+1555 / sms:+1555 / user@example.com

Listar chats:

imsg chats --limit 20

Referencia de configuración (iMessage)¶

Configuración completa: Configuración

Opciones del proveedor:

channels.imessage.enabled: habilitar/deshabilitar el inicio del canal.
channels.imessage.cliPath: ruta a imsg.
channels.imessage.dbPath: ruta de la base de datos de Mensajes.
channels.imessage.remoteHost: host SSH para la transferencia de adjuntos por SCP cuando cliPath apunta a un Mac remoto (p. ej., user@gateway-host). Se detecta automáticamente desde el envoltorio SSH si no se configura.
channels.imessage.service: imessage | sms | auto.
channels.imessage.region: región de SMS.
channels.imessage.dmPolicy: pairing | allowlist | open | disabled (predeterminado: emparejamiento).
channels.imessage.allowFrom: lista de permitidos de mensajes directos (identificadores, correos electrónicos, números E.164 o chat_id:*). open requiere "*". iMessage no tiene nombres de usuario; use identificadores o destinos de chat.
channels.imessage.groupPolicy: open | allowlist | disabled (predeterminado: lista de permitidos).
channels.imessage.groupAllowFrom: lista de permitidos de remitentes de grupo.
channels.imessage.historyLimit / channels.imessage.accounts.*.historyLimit: máximo de mensajes de grupo a incluir como contexto (0 deshabilita).
channels.imessage.dmHistoryLimit: límite de historial de mensajes directos en turnos de usuario. Anulaciones por usuario: channels.imessage.dms["<handle>"].historyLimit.
channels.imessage.groups: valores predeterminados por grupo + lista de permitidos (use "*" para valores predeterminados globales).
channels.imessage.includeAttachments: ingerir adjuntos en el contexto.
channels.imessage.mediaMaxMb: límite de medios entrantes/salientes (MB).
channels.imessage.textChunkLimit: tamaño de fragmento saliente (caracteres).
channels.imessage.chunkMode: length (predeterminado) o newline para dividir en líneas en blanco (límites de párrafo) antes de la fragmentación por longitud.

Opciones globales relacionadas:

agents.list[].groupChat.mentionPatterns (o messages.groupChat.mentionPatterns).
messages.responsePrefix.

Overview

Messaging platforms

Configuration

iMessage

iMessage (legado: imsg)¶

Configuración rápida (principiante)¶

Qué es¶

Escrituras de configuración¶

Requisitos¶

Solución de problemas de Privacidad y Seguridad TCC de macOS¶

Configuración (ruta rápida)¶

Usuario macOS de bot dedicado (para identidad aislada)¶

Variante remota/SSH (opcional)¶

Mac remoto vía Tailscale (ejemplo)¶

Control de acceso (mensajes directos + grupos)¶

Cómo funciona (comportamiento)¶

Hilos tipo grupo (`is_group=false`)¶

Medios + límites¶

Límites¶

Direccionamiento / destinos de entrega¶

Referencia de configuración (iMessage)¶

Overview

Messaging platforms

Configuration

iMessage (legado: imsg)¶

Configuración rápida (principiante)¶

Qué es¶

Escrituras de configuración¶

Requisitos¶

Solución de problemas de Privacidad y Seguridad TCC de macOS¶

Configuración (ruta rápida)¶

Usuario macOS de bot dedicado (para identidad aislada)¶

Variante remota/SSH (opcional)¶

Mac remoto vía Tailscale (ejemplo)¶

Control de acceso (mensajes directos + grupos)¶

Cómo funciona (comportamiento)¶

Hilos tipo grupo (is_group=false)¶

Medios + límites¶

Límites¶

Direccionamiento / destinos de entrega¶

Referencia de configuración (iMessage)¶

Hilos tipo grupo (`is_group=false`)¶