Signal

​

El modelo de número (lee esto primero)

• El Gateway se conecta a un dispositivo de Signal: la cuenta de signal-cli.
• Ejecutar el bot en tu cuenta personal de Signal hace que ignore tus propios mensajes (protección contra bucles).
• Para “le escribo al bot y responde”, usa un número de bot separado.

​

Instalación

openclaw plugins install @openclaw/signal

​

Configuración rápida

openclaw plugins install @openclaw/signal

openclaw channels add

openclaw gateway call channels.status --params '{"probe":true}'

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      cliPath: "signal-cli",
      dmPolicy: "pairing",
      allowFrom: ["+15557654321"],
    },
  },
}

​

Qué es

• Enrutamiento determinista: las respuestas siempre vuelven a Signal.
• Los MD comparten la sesión principal del agente; los grupos están aislados (agent:<agentId>:signal:group:<groupId>).
• De forma predeterminada, Signal puede escribir actualizaciones de configuración activadas por /config set|unset (requiere commands.config: true). Desactívalo con channels.signal.configWrites: false.

​

Ruta de configuración A: vincular una cuenta existente de Signal (QR)

1. Instala signal-cli (JVM o compilación nativa), o deja que openclaw channels add lo instale por ti.
2. Vincula una cuenta de bot: signal-cli link -n "OpenClaw", luego escanea el QR en Signal.
3. Configura Signal e inicia el Gateway.

​

Ruta de configuración B: registrar un número dedicado de bot (SMS, Linux)

1. Obtén un número que pueda recibir SMS (o verificación por voz para líneas fijas). Un número dedicado de bot evita conflictos de cuenta/sesión.
2. Instala signal-cli en el host del Gateway:

VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux-native.tar.gz"
sudo tar xf "signal-cli-${VERSION}-Linux-native.tar.gz" -C /opt
sudo ln -sf /opt/signal-cli /usr/local/bin/
signal-cli --version

3. Registra y verifica el número:

signal-cli -a +<BOT_PHONE_NUMBER> register

1. Abre https://signalcaptchas.org/registration/generate.html.
2. Completa el captcha, copia el destino del enlace signalcaptcha://... desde “Open Signal”.
3. Ejecuta desde la misma IP externa que la sesión del navegador cuando sea posible (los tokens de captcha caducan rápidamente).
4. Registra y verifica de inmediato:

signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>

4. Configura OpenClaw, reinicia el Gateway y verifica el canal:

# If you run the gateway as a user systemd service:
systemctl --user restart openclaw-gateway.service

# Then verify:
openclaw doctor
openclaw channels status --probe

5. Empareja tu remitente de MD:
   • Envía cualquier mensaje al número del bot.
   • Aprueba en el servidor: openclaw pairing approve signal <PAIRING_CODE>.
   • Guarda el número del bot como contacto en tu teléfono para evitar “Unknown contact”.

• README de signal-cli: https://github.com/AsamK/signal-cli
• Flujo de captcha: https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
• Flujo de vinculación: https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

​

Modo de daemon externo (httpUrl)

{
  channels: {
    signal: {
      httpUrl: "http://127.0.0.1:8080",
      autoStart: false,
    },
  },
}

​

Modo de contenedor (bbernhard/signal-cli-rest-api)

• El contenedor debe ejecutarse con MODE=json-rpc para recibir mensajes en tiempo real.
• Registra o vincula tu cuenta de Signal dentro del contenedor antes de conectar OpenClaw.

signal-cli:
  image: bbernhard/signal-cli-rest-api:latest
  environment:
    MODE: json-rpc
  ports:
    - "8080:8080"
  volumes:
    - signal-cli-data:/home/.local/share/signal-cli

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      httpUrl: "http://signal-cli:8080",
      autoStart: false,
      apiMode: "container", // or "auto" to detect automatically
    },
  },
}

• Usa autoStart: false con el modo de contenedor; OpenClaw no debería iniciar un daemon nativo cuando se selecciona apiMode: "container".
• Usa MODE=json-rpc para recibir. MODE=normal puede hacer que /v1/about parezca sano, pero /v1/receive/{account} no se actualizará a WebSocket, por lo que OpenClaw no seleccionará el streaming de recepción por contenedor en modo auto.
• Establece apiMode: "container" cuando httpUrl apunta a la API REST de bbernhard, "native" cuando apunta a JSON-RPC/SSE nativos de signal-cli, y "auto" cuando el despliegue pueda variar.
• Las descargas de adjuntos del contenedor respetan los mismos límites de bytes de medios que el modo nativo. Las respuestas sobredimensionadas se rechazan antes de almacenarse completamente en búfer cuando el servidor envía Content-Length, y durante el streaming en caso contrario.

​

Control de acceso (MD + grupos)

• Predeterminado: channels.signal.dmPolicy = "pairing".
• Los remitentes desconocidos reciben un código de emparejamiento; los mensajes se ignoran hasta que se aprueban (los códigos caducan después de 1 hora).
• Aprueba mediante openclaw pairing list signal y openclaw pairing approve signal <CODE>.
• El emparejamiento es el intercambio de tokens predeterminado para los MD de Signal. Detalles: Emparejamiento
• Los remitentes solo con UUID (desde sourceUuid) se almacenan como uuid:<id> en channels.signal.allowFrom.

• channels.signal.groupPolicy = open | allowlist | disabled.
• channels.signal.groupAllowFrom controla qué grupos o remitentes pueden activar respuestas de grupo cuando se establece allowlist; las entradas pueden ser ID de grupo de Signal (sin procesar, group:<id> o signal:group:<id>), números de teléfono de remitente, valores uuid:<id> o *.
• channels.signal.groups["<group-id>" | "*"] puede sobrescribir el comportamiento de grupo con requireMention, tools y toolsBySender.
• Usa channels.signal.accounts.<id>.groups para sobrescrituras por cuenta en configuraciones multicuenta.
• Incluir un grupo en la lista de permitidos mediante groupAllowFrom no desactiva por sí solo el requisito de mención. Una entrada específicamente configurada de channels.signal.groups["<group-id>"] procesa cada mensaje de grupo salvo que requireMention: true se establezca explícitamente.
• Nota de runtime: si channels.signal falta por completo, el runtime recurre a groupPolicy="allowlist" para las comprobaciones de grupo (aunque channels.defaults.groupPolicy esté establecido).

​

Cómo funciona (comportamiento)

• Modo nativo: signal-cli se ejecuta como daemon; el Gateway lee eventos mediante SSE.
• Modo de contenedor: el Gateway envía mediante la API REST y recibe mediante WebSocket.
• Los mensajes entrantes se normalizan en el sobre de canal compartido.
• Las respuestas siempre se enrutan de vuelta al mismo número o grupo.

​

Medios + límites

• El texto saliente se divide en fragmentos según channels.signal.textChunkLimit (predeterminado 4000).
• División opcional por saltos de línea: define channels.signal.chunkMode="newline" para dividir por líneas en blanco (límites de párrafo) antes de dividir por longitud.
• Los adjuntos son compatibles (base64 obtenido desde signal-cli).
• Los adjuntos de notas de voz usan el nombre de archivo de signal-cli como reserva MIME cuando falta contentType, para que la transcripción de audio aún pueda clasificar notas de voz AAC.
• Límite de medios predeterminado: channels.signal.mediaMaxMb (predeterminado 8).
• Usa channels.signal.ignoreAttachments para omitir la descarga de medios.
• El contexto de historial de grupo usa channels.signal.historyLimit (o channels.signal.accounts.*.historyLimit), con reserva en messages.groupChat.historyLimit. Define 0 para desactivarlo (predeterminado 50).

​

Indicadores de escritura + confirmaciones de lectura

• Indicadores de escritura: OpenClaw envía señales de escritura mediante signal-cli sendTyping y las actualiza mientras se genera una respuesta.
• Confirmaciones de lectura: cuando channels.signal.sendReadReceipts es true, OpenClaw reenvía confirmaciones de lectura para MD permitidos.
• signal-cli no expone confirmaciones de lectura para grupos.

​

Reacciones de estado del ciclo de vida

​

Reacciones (herramienta de mensajes)

• Objetivos: E.164 o UUID del remitente (usa uuid:<id> de la salida de emparejamiento; un UUID sin prefijo también funciona).
• messageId es la marca de tiempo de Signal del mensaje al que reaccionas.
• Las reacciones de grupo requieren targetAuthor o targetAuthorUuid.

message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥
message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true
message action=react channel=signal target=signal:group:<groupId> targetAuthor=uuid:<sender-uuid> messageId=1737630212345 emoji=✅

• channels.signal.actions.reactions: activa/desactiva acciones de reacción (predeterminado true).
• channels.signal.reactionLevel: off | ack | minimal | extensive (predeterminado minimal).
  • off/ack desactiva las reacciones del agente (la herramienta de mensajes react genera errores).
  • minimal/extensive activa las reacciones del agente y define el nivel de orientación.
• Sobrescrituras por cuenta: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

​

Reacciones de aprobación

• 👍 aprueba una vez.
• 👎 deniega.
• Usa /approve <id> allow-always cuando una solicitud ofrece aprobación persistente.

​

Destinos de entrega (CLI/cron)

• MD: signal:+15551234567 (o E.164 simple).
• MD por UUID: uuid:<id> (o UUID sin prefijo).
• Grupos: signal:group:<groupId>.
• Nombres de usuario: username:<name> (si tu cuenta de Signal lo admite).

​

Alias

{
  channels: {
    signal: {
      aliases: {
        me: "+15557654321",
        jane: "uuid:123e4567-e89b-12d3-a456-426614174000",
        ops: "group:<groupId>",
      },
      defaultTo: "signal:me",
    },
  },
}

openclaw message send --channel signal --target signal:ops --message "Deployment is complete"

{
  channels: {
    signal: {
      aliases: {
        me: "+15557654321",
      },
      accounts: {
        work: {
          aliases: {
            ops: "group:<workGroupId>",
          },
        },
      },
    },
  },
}

​

Solución de problemas

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

openclaw pairing list signal

• Demonio accesible pero sin respuestas: verifica la configuración de cuenta/demonio (httpUrl, account) y el modo de recepción.
• MD ignorados: el remitente tiene aprobación de emparejamiento pendiente.
• Mensajes de grupo ignorados: el filtrado por remitente/mención de grupo bloquea la entrega.
• Errores de validación de configuración después de ediciones: ejecuta openclaw doctor --fix.
• Signal falta en los diagnósticos: confirma channels.signal.enabled: true.

openclaw pairing list signal
pgrep -af signal-cli
grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20

​

Notas de seguridad

• signal-cli almacena claves de cuenta localmente (normalmente en ~/.local/share/signal-cli/data/).
• Haz una copia de seguridad del estado de la cuenta de Signal antes de una migración o reconstrucción del servidor.
• Mantén channels.signal.dmPolicy: "pairing" salvo que quieras explícitamente un acceso más amplio a MD.
• La verificación por SMS solo es necesaria para flujos de registro o recuperación, pero perder el control del número/la cuenta puede complicar el nuevo registro.

​

Referencia de configuración (Signal)

• channels.signal.enabled: activa/desactiva el inicio del canal.
• channels.signal.apiMode: auto | native | container (predeterminado: auto). Consulta Modo contenedor.
• channels.signal.account: E.164 para la cuenta del bot.
• channels.signal.cliPath: ruta a signal-cli.
• channels.signal.configPath: directorio opcional de signal-cli --config.
• channels.signal.httpUrl: URL completa del demonio (sobrescribe host/puerto).
• channels.signal.httpHost, channels.signal.httpPort: enlace del demonio (predeterminado 127.0.0.1:8080).
• channels.signal.autoStart: inicia automáticamente el demonio (predeterminado true si httpUrl no está definido).
• channels.signal.startupTimeoutMs: tiempo de espera de inicio en ms (mín. 1000, límite 120000; predeterminado 30000).
• channels.signal.receiveMode: on-start | manual.
• channels.signal.ignoreAttachments: omite descargas de adjuntos.
• channels.signal.ignoreStories: ignora historias del demonio.
• channels.signal.sendReadReceipts: reenvía confirmaciones de lectura.
• channels.signal.dmPolicy: pairing | allowlist | open | disabled (predeterminado: pairing).
• channels.signal.allowFrom: lista de permitidos para MD (E.164 o uuid:<id>). open requiere "*". Signal no tiene nombres de usuario; usa IDs de teléfono/UUID.
• channels.signal.aliases: alias del lado de OpenClaw para destinos de entrega de MD o grupo.
• channels.signal.groupPolicy: open | allowlist | disabled (predeterminado: allowlist).
• channels.signal.groupAllowFrom: lista de permitidos de grupo; acepta IDs de grupo de Signal (sin procesar, group:<id> o signal:group:<id>), números E.164 de remitente o valores uuid:<id>.
• channels.signal.groups: sobrescrituras por grupo indexadas por ID de grupo de Signal (o "*"). Campos compatibles: requireMention, tools, toolsBySender.
• channels.signal.accounts.<id>.groups: versión por cuenta de channels.signal.groups para configuraciones con varias cuentas.
• channels.signal.accounts.<id>.aliases: alias por cuenta, fusionados con los alias de nivel superior.
• channels.signal.historyLimit: máximo de mensajes de grupo que se incluirán como contexto (0 desactiva).
• channels.signal.dmHistoryLimit: límite de historial de MD en turnos de usuario. Sobrescrituras por usuario: channels.signal.dms["<phone_or_uuid>"].historyLimit.
• channels.signal.textChunkLimit: tamaño de fragmento saliente en caracteres (predeterminado 4000).
• channels.signal.chunkMode: length (predeterminado) o newline para dividir por líneas en blanco (límites de párrafo) antes de dividir por longitud.
• channels.signal.mediaMaxMb: límite de medios entrantes/salientes en MB (predeterminado 8).
• channels.signal.reactionLevel: off | ack | minimal | extensive (predeterminado minimal). Consulta Reacciones.
• channels.signal.reactionNotifications: off | own | all | allowlist (predeterminado own) - cuándo se notifica al agente sobre reacciones entrantes de otras personas.
• channels.signal.reactionAllowlist: remitentes cuyas reacciones notifican al agente cuando reactionNotifications: "allowlist".
• channels.signal.blockStreaming, channels.signal.blockStreamingCoalesce: controles de streaming en modo bloque compartidos entre canales. Consulta Streaming.

• agents.list[].groupChat.mentionPatterns (Signal no admite menciones nativas).
• messages.groupChat.mentionPatterns (reserva global).
• messages.responsePrefix.

​

Relacionado

• Resumen de canales - todos los canales compatibles
• Emparejamiento - autenticación de MD y flujo de emparejamiento
• Grupos - comportamiento del chat de grupo y filtrado por mención
• Enrutamiento de canales - enrutamiento de sesión para mensajes
• Seguridad - modelo de acceso y endurecimiento