Signal

Documentation Index

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

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

​

Передумови

• OpenClaw встановлено на вашому сервері (Linux-процес нижче протестовано на Ubuntu 24).
• Одне з наведеного:
  • signal-cli доступний на хості (нативний режим), або
  • Docker-контейнер bbernhard/signal-cli-rest-api (контейнерний режим).
• Номер телефону, який може отримати одне SMS для перевірки (для шляху реєстрації через SMS).
• Доступ до браузера для капчі Signal (signalcaptchas.org) під час реєстрації.

​

Швидке налаштування (для початківців)

1. Використовуйте окремий номер Signal для бота (рекомендовано).
2. Встановіть signal-cli (потрібна Java, якщо ви використовуєте JVM-збірку).
3. Виберіть один шлях налаштування:
   • Шлях A (зв’язування через QR): signal-cli link -n "OpenClaw" і відскануйте в Signal.
   • Шлях B (реєстрація через SMS): зареєструйте виділений номер із капчею та SMS-перевіркою.
4. Налаштуйте OpenClaw і перезапустіть Gateway.
5. Надішліть перше приватне повідомлення й підтвердьте сполучення (openclaw pairing approve signal <CODE>).

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

​

Що це таке

• Канал Signal через signal-cli (не вбудований libsignal).
• Детермінізована маршрутизація: відповіді завжди повертаються до Signal.
• Приватні повідомлення використовують основний сеанс агента; групи ізольовані (agent:<agentId>:signal:group:<groupId>).

​

Записи конфігурації

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

​

Модель номера (важливо)

• Gateway підключається до пристрою Signal (облікового запису signal-cli).
• Якщо ви запускаєте бота на своєму особистому обліковому записі Signal, він ігноруватиме ваші власні повідомлення (захист від циклів).
• Для сценарію «я пишу боту, і він відповідає» використовуйте окремий номер бота.

​

Шлях налаштування A: зв’язати наявний обліковий запис Signal (QR)

1. Встановіть signal-cli (JVM або нативну збірку).
2. Зв’яжіть обліковий запис бота:
   • signal-cli link -n "OpenClaw", потім відскануйте QR у Signal.
3. Налаштуйте Signal і запустіть Gateway.

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

​

Шлях налаштування B: зареєструвати виділений номер бота (SMS, Linux)

1. Отримайте номер, який може приймати SMS (або голосову перевірку для стаціонарних номерів).
   • Використовуйте виділений номер бота, щоб уникнути конфліктів облікового запису або сеансу.
2. Встановіть signal-cli на хості 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. Зареєструйте й перевірте номер:

signal-cli -a +<BOT_PHONE_NUMBER> register

1. Відкрийте https://signalcaptchas.org/registration/generate.html.
2. Пройдіть капчу, скопіюйте цільове посилання signalcaptcha://... з «Open Signal».
3. За можливості виконуйте з тієї самої зовнішньої IP-адреси, що й сеанс браузера.
4. Негайно повторіть реєстрацію (токени капчі швидко спливають):

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

4. Налаштуйте OpenClaw, перезапустіть Gateway, перевірте канал:

# 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. Сполучіть свого відправника приватних повідомлень:
   • Надішліть будь-яке повідомлення на номер бота.
   • Підтвердьте код на сервері: openclaw pairing approve signal <PAIRING_CODE>.
   • Збережіть номер бота як контакт на телефоні, щоб уникнути «Unknown contact».

• README signal-cli: https://github.com/AsamK/signal-cli
• Потік капчі: https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
• Потік зв’язування: https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

​

Режим зовнішнього демона (httpUrl)

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

​

Контейнерний режим (bbernhard/signal-cli-rest-api)

• Контейнер має запускатися з MODE=json-rpc для отримання повідомлень у реальному часі.
• Зареєструйте або зв’яжіть обліковий запис Signal усередині контейнера перед підключенням 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
    },
  },
}

• Використовуйте autoStart: false з контейнерним режимом. OpenClaw не має запускати нативний демон, коли вибрано apiMode: "container".
• Використовуйте MODE=json-rpc для отримання. MODE=normal може зробити /v1/about справним на вигляд, але /v1/receive/{account} не виконує WebSocket-upgrade, тож OpenClaw не вибере streaming отримання через контейнер у режимі auto.
• Задайте apiMode: "container", коли ви знаєте, що httpUrl вказує на REST API bbernhard. Задайте apiMode: "native", коли ви знаєте, що він вказує на нативний JSON-RPC/SSE signal-cli. Використовуйте "auto", коли розгортання може відрізнятися.
• Завантаження вкладень у контейнерному режимі дотримуються тих самих обмежень байтів медіа, що й нативний режим. Завеликі відповіді відхиляються до повного буферизування, якщо сервер надсилає Content-Length, і під час streaming в інших випадках.

​

Контроль доступу (приватні повідомлення + групи)

• За замовчуванням: channels.signal.dmPolicy = "pairing".
• Невідомі відправники отримують код сполучення; повідомлення ігноруються до підтвердження (коди спливають через 1 годину).
• Підтвердьте через:
  • openclaw pairing list signal
  • openclaw pairing approve signal <CODE>
• Сполучення є стандартним обміном токенами для приватних повідомлень Signal. Докладніше: Сполучення
• Відправники лише з UUID (із sourceUuid) зберігаються як uuid:<id> у channels.signal.allowFrom.

• channels.signal.groupPolicy = open | allowlist | disabled.
• channels.signal.groupAllowFrom керує тим, які групи або відправники можуть запускати групові відповіді, коли задано allowlist; записи можуть бути ID груп Signal (raw, group:<id> або signal:group:<id>), номерами телефонів відправників, значеннями uuid:<id> або *.
• channels.signal.groups["<group-id>" | "*"] може перевизначати поведінку групи за допомогою requireMention, tools і toolsBySender.
• Використовуйте channels.signal.accounts.<id>.groups для перевизначень на рівні облікового запису в налаштуваннях із кількома обліковими записами.
• Додавання групи Signal до allowlist через groupAllowFrom саме по собі не вимикає вимогу згадки. Спеціально налаштований запис channels.signal.groups["<group-id>"] обробляє кожне повідомлення групи, якщо не задано requireMention=true.
• Примітка часу виконання: якщо channels.signal повністю відсутній, середовище виконання відступає до groupPolicy="allowlist" для перевірок груп (навіть якщо задано channels.defaults.groupPolicy).

​

Як це працює (поведінка)

• Нативний режим: signal-cli працює як демон; Gateway читає події через SSE.
• Контейнерний режим: Gateway надсилає через REST API й отримує через WebSocket.
• Вхідні повідомлення нормалізуються до спільного конверта каналу.
• Відповіді завжди маршрутизуються назад до того самого номера або групи.

​

Медіа + обмеження

• Вихідний текст розбивається на фрагменти до channels.signal.textChunkLimit (за замовчуванням 4000).
• Необов’язкове розбиття за новими рядками: задайте channels.signal.chunkMode="newline", щоб розділяти за порожніми рядками (межами абзаців) перед розбиттям за довжиною.
• Вкладення підтримуються (base64 отримується з signal-cli).
• Вкладення голосових нотаток використовують ім’я файлу signal-cli як MIME-запасний варіант, коли contentType відсутній, тож транскрипція аудіо все ще може класифікувати голосові нотатки AAC.
• Стандартне обмеження медіа: channels.signal.mediaMaxMb (за замовчуванням 8).
• Використовуйте channels.signal.ignoreAttachments, щоб пропускати завантаження медіа.
• Контекст історії групи використовує channels.signal.historyLimit (або channels.signal.accounts.*.historyLimit) із відступом до messages.groupChat.historyLimit. Задайте 0, щоб вимкнути (за замовчуванням 50).

​

Набір тексту + квитанції про прочитання

• Індикатори набору: OpenClaw надсилає сигнали набору через signal-cli sendTyping і оновлює їх, поки виконується відповідь.
• Квитанції про прочитання: коли channels.signal.sendReadReceipts має значення true, OpenClaw пересилає квитанції про прочитання для дозволених приватних повідомлень.
• Signal-cli не надає квитанції про прочитання для груп.

​

Реакції (інструмент повідомлень)

• Використовуйте message action=react з channel=signal.
• Цілі: E.164 відправника або UUID (використовуйте uuid:<id> з виводу сполучення; простий UUID також працює).
• messageId — це timestamp Signal для повідомлення, на яке ви реагуєте.
• Реакції в групах потребують targetAuthor або 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: увімкнути/вимкнути дії реакцій (типово true).
• channels.signal.reactionLevel: off | ack | minimal | extensive.
  • off/ack вимикає реакції агента (інструмент повідомлень react поверне помилку).
  • minimal/extensive вмикає реакції агента та задає рівень настанов.
• Перевизначення для окремих облікових записів: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

​

Цілі доставки (CLI/Cron)

• Особисті повідомлення: signal:+15551234567 (або простий E.164).
• Особисті повідомлення UUID: uuid:<id> (або простий UUID).
• Групи: signal:group:<groupId>.
• Імена користувачів: username:<name> (якщо підтримується вашим обліковим записом Signal).

​

Усунення несправностей

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

openclaw pairing list signal

• Демон доступний, але відповідей немає: перевірте налаштування облікового запису/демона (httpUrl, account) і режим отримання.
• Особисті повідомлення ігноруються: відправник очікує схвалення сполучення.
• Групові повідомлення ігноруються: фільтрація за відправником/згадкою у групі блокує доставку.
• Помилки перевірки конфігурації після редагувань: виконайте openclaw doctor --fix.
• Signal відсутній у діагностиці: підтвердьте 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

​

Примітки з безпеки

• signal-cli зберігає ключі облікового запису локально (зазвичай у ~/.local/share/signal-cli/data/).
• Створіть резервну копію стану облікового запису Signal перед міграцією сервера або перебудовою.
• Залишайте channels.signal.dmPolicy: "pairing", якщо явно не хочете ширший доступ до особистих повідомлень.
• SMS-перевірка потрібна лише для потоків реєстрації або відновлення, але втрата контролю над номером/обліковим записом може ускладнити повторну реєстрацію.

​

Довідник конфігурації (Signal)

• channels.signal.enabled: увімкнути/вимкнути запуск каналу.
• channels.signal.apiMode: auto | native | container (типово: auto). Див. Режим контейнера.
• channels.signal.account: E.164 для облікового запису бота.
• channels.signal.cliPath: шлях до signal-cli.
• channels.signal.httpUrl: повна URL-адреса демона (перевизначає host/port).
• channels.signal.httpHost, channels.signal.httpPort: прив’язка демона (типово 127.0.0.1:8080).
• channels.signal.autoStart: автоматично запускати демон (типово true, якщо httpUrl не задано).
• channels.signal.startupTimeoutMs: тайм-аут очікування запуску в мс (ліміт 120000).
• channels.signal.receiveMode: on-start | manual.
• channels.signal.ignoreAttachments: пропускати завантаження вкладень.
• channels.signal.ignoreStories: ігнорувати stories від демона.
• channels.signal.sendReadReceipts: пересилати сповіщення про прочитання.
• channels.signal.dmPolicy: pairing | allowlist | open | disabled (типово: pairing).
• channels.signal.allowFrom: список дозволених для особистих повідомлень (E.164 або uuid:<id>). open потребує "*". Signal не має імен користувачів; використовуйте ідентифікатори телефону/UUID.
• channels.signal.groupPolicy: open | allowlist | disabled (типово: allowlist).
• channels.signal.groupAllowFrom: список дозволених для груп; приймає ідентифікатори груп Signal (raw, group:<id> або signal:group:<id>), номери відправників E.164 або значення uuid:<id>.
• channels.signal.groups: перевизначення для окремих груп, ключовані за id групи Signal (або "*"). Підтримувані поля: requireMention, tools, toolsBySender.
• channels.signal.accounts.<id>.groups: версія channels.signal.groups для окремого облікового запису в налаштуваннях із кількома обліковими записами.
• channels.signal.historyLimit: максимальна кількість групових повідомлень, які потрібно включати як контекст (0 вимикає).
• channels.signal.dmHistoryLimit: ліміт історії особистих повідомлень у ходах користувача. Перевизначення для окремих користувачів: channels.signal.dms["<phone_or_uuid>"].historyLimit.
• channels.signal.textChunkLimit: розмір вихідного фрагмента (символи).
• channels.signal.chunkMode: length (типово) або newline, щоб розділяти за порожніми рядками (межами абзаців) перед фрагментацією за довжиною.
• channels.signal.mediaMaxMb: ліміт вхідних/вихідних медіа (MB).

• agents.list[].groupChat.mentionPatterns (Signal не підтримує нативні згадки).
• messages.groupChat.mentionPatterns (глобальний запасний варіант).
• messages.responsePrefix.

​

Пов’язане

• Огляд каналів — усі підтримувані канали
• Сполучення — автентифікація особистих повідомлень і потік сполучення
• Групи — поведінка групового чату та фільтрація за згадками
• Маршрутизація каналів — маршрутизація сеансів для повідомлень
• Безпека — модель доступу та посилення захисту