Signal

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Vereisten

• OpenClaw geïnstalleerd op je server (Linux-flow hieronder getest op Ubuntu 24).
• Een van:
  • signal-cli beschikbaar op de host (native modus), of
  • bbernhard/signal-cli-rest-api Docker-container (containermodus).
• Een telefoonnummer dat één verificatie-sms kan ontvangen (voor het registratiepad via sms).
• Browsertoegang voor Signal-captcha (signalcaptchas.org) tijdens registratie.

​

Snelle setup (beginner)

1. Gebruik een apart Signal-nummer voor de bot (aanbevolen).
2. Installeer signal-cli (Java is vereist als je de JVM-build gebruikt).
3. Kies één setup-pad:
   • Pad A (QR-koppeling): signal-cli link -n "OpenClaw" en scan met Signal.
   • Pad B (sms-registratie): registreer een dedicated nummer met captcha + sms-verificatie.
4. Configureer OpenClaw en herstart de Gateway.
5. Stuur een eerste DM en keur koppelen goed (openclaw pairing approve signal <CODE>).

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

​

Wat het is

• Signal-kanaal via signal-cli (geen ingebedde libsignal).
• Deterministische routering: antwoorden gaan altijd terug naar Signal.
• DM’s delen de hoofdsessie van de agent; groepen zijn geïsoleerd (agent:<agentId>:signal:group:<groupId>).

​

Configuratieschrijfacties

{
  channels: { signal: { configWrites: false } },
}

​

Het nummermodel (belangrijk)

• De Gateway maakt verbinding met een Signal-apparaat (het signal-cli-account).
• Als je de bot op je persoonlijke Signal-account draait, negeert hij je eigen berichten (lusbescherming).
• Gebruik een apart botnummer voor “ik stuur de bot een bericht en hij antwoordt”.

​

Setuppad A: bestaand Signal-account koppelen (QR)

1. Installeer signal-cli (JVM- of native build).
2. Koppel een botaccount:
   • signal-cli link -n "OpenClaw" en scan daarna de QR in Signal.
3. Configureer Signal en start de Gateway.

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

​

Setuppad B: dedicated botnummer registreren (sms, Linux)

1. Neem een nummer dat sms kan ontvangen (of spraakverificatie voor vaste lijnen).
   • Gebruik een dedicated botnummer om account- en sessieconflicten te voorkomen.
2. Installeer signal-cli op de Gateway-host:

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. Registreer en verifieer het nummer:

signal-cli -a +<BOT_PHONE_NUMBER> register

1. Open https://signalcaptchas.org/registration/generate.html.
2. Rond captcha af, kopieer het signalcaptcha://...-linkdoel van “Open Signal”.
3. Voer dit waar mogelijk uit vanaf hetzelfde externe IP als de browsersessie.
4. Voer registratie direct opnieuw uit (captcha-tokens verlopen snel):

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

4. Configureer OpenClaw, herstart de Gateway, verifieer het kanaal:

# 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. Koppel je DM-afzender:
   • Stuur een willekeurig bericht naar het botnummer.
   • Keur de code goed op de server: openclaw pairing approve signal <PAIRING_CODE>.
   • Sla het botnummer op als contact op je telefoon om “Onbekend contact” te vermijden.

• signal-cli README: https://github.com/AsamK/signal-cli
• Captcha-flow: https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
• Koppelflow: https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

​

Externe daemonmodus (httpUrl)

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

​

Containermodus (bbernhard/signal-cli-rest-api)

• De container moet draaien met MODE=json-rpc voor realtime berichtontvangst.
• Registreer of koppel je Signal-account binnen de container voordat je OpenClaw verbindt.

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
    },
  },
}

• Gebruik autoStart: false met containermodus. OpenClaw hoort geen native daemon te starten wanneer apiMode: "container" is geselecteerd.
• Gebruik MODE=json-rpc voor ontvangst. MODE=normal kan /v1/about gezond laten lijken, maar /v1/receive/{account} voert geen WebSocket-upgrade uit, dus OpenClaw selecteert geen containerontvangststreaming in auto-modus.
• Stel apiMode: "container" in wanneer je weet dat de httpUrl naar de REST API van bbernhard wijst. Stel apiMode: "native" in wanneer je weet dat deze naar native signal-cli JSON-RPC/SSE wijst. Gebruik "auto" wanneer de deployment kan variëren.
• Containerbijlagedownloads respecteren dezelfde mediabytelimieten als native modus. Te grote responses worden geweigerd voordat ze volledig worden gebufferd wanneer de server Content-Length verzendt, en anders tijdens streaming.

​

Toegangsbeheer (DM’s + groepen)

• Standaard: channels.signal.dmPolicy = "pairing".
• Onbekende afzenders ontvangen een koppelcode; berichten worden genegeerd totdat ze zijn goedgekeurd (codes verlopen na 1 uur).
• Goedkeuren via:
  • openclaw pairing list signal
  • openclaw pairing approve signal <CODE>
• Koppelen is de standaard tokenuitwisseling voor Signal-DM’s. Details: Koppelen
• Afzenders met alleen UUID (van sourceUuid) worden opgeslagen als uuid:<id> in channels.signal.allowFrom.

• channels.signal.groupPolicy = open | allowlist | disabled.
• channels.signal.groupAllowFrom bepaalt welke groepen of afzenders groepsantwoorden kunnen triggeren wanneer allowlist is ingesteld; vermeldingen kunnen Signal-groeps-ID’s zijn (raw, group:<id> of signal:group:<id>), telefoonnummers van afzenders, uuid:<id>-waarden of *.
• channels.signal.groups["<group-id>" | "*"] kan groepsgedrag overschrijven met requireMention, tools en toolsBySender.
• Gebruik channels.signal.accounts.<id>.groups voor overrides per account in setups met meerdere accounts.
• Het toestaan van een Signal-groep via groupAllowFrom schakelt mention-gating niet op zichzelf uit. Een specifiek geconfigureerde channels.signal.groups["<group-id>"]-vermelding verwerkt elk groepsbericht tenzij requireMention=true is ingesteld.
• Runtime-opmerking: als channels.signal volledig ontbreekt, valt runtime terug op groupPolicy="allowlist" voor groepscontroles (zelfs als channels.defaults.groupPolicy is ingesteld).

​

Hoe het werkt (gedrag)

• Native modus: signal-cli draait als daemon; de Gateway leest events via SSE.
• Containermodus: de Gateway verzendt via REST API en ontvangt via WebSocket.
• Inkomende berichten worden genormaliseerd naar de gedeelde kanaalenvelop.
• Antwoorden worden altijd teruggerouteerd naar hetzelfde nummer of dezelfde groep.

​

Media + limieten

• Uitgaande tekst wordt opgedeeld tot channels.signal.textChunkLimit (standaard 4000).
• Optioneel opdelen op nieuwe regels: stel channels.signal.chunkMode="newline" in om te splitsen op lege regels (alinea-grenzen) vóór opdelen op lengte.
• Bijlagen ondersteund (base64 opgehaald uit signal-cli).
• Voice-note-bijlagen gebruiken de signal-cli-bestandsnaam als MIME-fallback wanneer contentType ontbreekt, zodat audiotranscriptie AAC-spraakmemo’s nog steeds kan classificeren.
• Standaard medialimiet: channels.signal.mediaMaxMb (standaard 8).
• Gebruik channels.signal.ignoreAttachments om het downloaden van media over te slaan.
• Groepsgeschiedeniscontext gebruikt channels.signal.historyLimit (of channels.signal.accounts.*.historyLimit) en valt terug op messages.groupChat.historyLimit. Stel in op 0 om uit te schakelen (standaard 50).

​

Typen + leesbewijzen

• Typindicatoren: OpenClaw verzendt typsignalen via signal-cli sendTyping en vernieuwt ze terwijl een antwoord loopt.
• Leesbewijzen: wanneer channels.signal.sendReadReceipts true is, stuurt OpenClaw leesbewijzen door voor toegestane DM’s.
• Signal-cli geeft geen leesbewijzen voor groepen bloot.

​

Reacties (berichttool)

• Gebruik message action=react met channel=signal.
• Doelen: afzender-E.164 of UUID (gebruik uuid:<id> uit de koppelingsuitvoer; een kale UUID werkt ook).
• messageId is de Signal-tijdstempel voor het bericht waarop je reageert.
• Groepsreacties vereisen targetAuthor of 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: schakel reactie-acties in/uit (standaard true).
• channels.signal.reactionLevel: off | ack | minimal | extensive.
  • off/ack schakelt agentreacties uit (berichttool react geeft een foutmelding).
  • minimal/extensive schakelt agentreacties in en stelt het begeleidingsniveau in.
• Overrides per account: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

​

Bezorgdoelen (CLI/Cron)

• DM’s: signal:+15551234567 (of gewone E.164).
• UUID-DM’s: uuid:<id> (of kale UUID).
• Groepen: signal:group:<groupId>.
• Gebruikersnamen: username:<name> (als dit door je Signal-account wordt ondersteund).

​

Probleemoplossing

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

openclaw pairing list signal

• Daemon bereikbaar maar geen antwoorden: controleer account-/daemoninstellingen (httpUrl, account) en ontvangstmodus.
• DM’s genegeerd: afzender wacht op koppelingsgoedkeuring.
• Groepsberichten genegeerd: groepsafzender-/vermeldingspoort blokkeert bezorging.
• Configuratievalidatiefouten na bewerkingen: voer openclaw doctor --fix uit.
• Signal ontbreekt in diagnostiek: bevestig 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

​

Beveiligingsnotities

• signal-cli slaat accountsleutels lokaal op (meestal ~/.local/share/signal-cli/data/).
• Maak een back-up van de Signal-accountstatus vóór servermigratie of herbouw.
• Houd channels.signal.dmPolicy: "pairing" aan, tenzij je expliciet bredere DM-toegang wilt.
• Sms-verificatie is alleen nodig voor registratie- of herstelstromen, maar controleverlies over het nummer/account kan herregistratie bemoeilijken.

​

Configuratiereferentie (Signal)

• channels.signal.enabled: schakel kanaalopstart in/uit.
• channels.signal.apiMode: auto | native | container (standaard: auto). Zie Containermodus.
• channels.signal.account: E.164 voor het botaccount.
• channels.signal.cliPath: pad naar signal-cli.
• channels.signal.httpUrl: volledige daemon-URL (overschrijft host/poort).
• channels.signal.httpHost, channels.signal.httpPort: daemonbinding (standaard 127.0.0.1:8080).
• channels.signal.autoStart: daemon automatisch starten (standaard true als httpUrl niet is ingesteld).
• channels.signal.startupTimeoutMs: wachttime-out bij opstarten in ms (limiet 120000).
• channels.signal.receiveMode: on-start | manual.
• channels.signal.ignoreAttachments: downloads van bijlagen overslaan.
• channels.signal.ignoreStories: verhalen van de daemon negeren.
• channels.signal.sendReadReceipts: leesbewijzen doorsturen.
• channels.signal.dmPolicy: pairing | allowlist | open | disabled (standaard: pairing).
• channels.signal.allowFrom: DM-toegestane lijst (E.164 of uuid:<id>). open vereist "*". Signal heeft geen gebruikersnamen; gebruik telefoon-/UUID-id’s.
• channels.signal.groupPolicy: open | allowlist | disabled (standaard: allowlist).
• channels.signal.groupAllowFrom: toegestane lijst voor groepen; accepteert Signal-groeps-ID’s (onbewerkt, group:<id> of signal:group:<id>), E.164-nummers van afzenders of uuid:<id>-waarden.
• channels.signal.groups: overrides per groep, gesleuteld op Signal-groeps-ID (of "*"). Ondersteunde velden: requireMention, tools, toolsBySender.
• channels.signal.accounts.<id>.groups: accountversie van channels.signal.groups voor setups met meerdere accounts.
• channels.signal.historyLimit: maximaal aantal groepsberichten dat als context wordt opgenomen (0 schakelt uit).
• channels.signal.dmHistoryLimit: DM-geschiedenislimiet in gebruikersbeurten. Overrides per gebruiker: channels.signal.dms["<phone_or_uuid>"].historyLimit.
• channels.signal.textChunkLimit: uitgaande blokgrootte (tekens).
• channels.signal.chunkMode: length (standaard) of newline om op lege regels (alineagrenzen) te splitsen vóór splitsing op lengte.
• channels.signal.mediaMaxMb: limiet voor inkomende/uitgaande media (MB).

• agents.list[].groupChat.mentionPatterns (Signal ondersteunt geen native vermeldingen).
• messages.groupChat.mentionPatterns (globale fallback).
• messages.responsePrefix.

​

Gerelateerd

• Kanalenoverzicht — alle ondersteunde kanalen
• Koppelen — DM-authenticatie en koppelingsflow
• Groepen — groepschatgedrag en vermeldingspoort
• Kanaalroutering — sessieroutering voor berichten
• Beveiliging — toegangsmodel en verharding