Signal

​

Передумови

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

​

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

1. Використовуйте окремий номер Signal для бота (рекомендовано).
2. Установіть OpenClaw Plugin:

openclaw plugins install @openclaw/signal

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

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

​

Що це таке

• Канал Signal через signal-cli (не вбудований libsignal).
• Детермінізоване маршрутизування: відповіді завжди повертаються в Signal.
• DM використовують основну сесію агента; групи ізольовані (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. Пройдіть captcha, скопіюйте ціль посилання signalcaptcha://... з “Open Signal”.
3. За можливості запускайте з тієї самої зовнішньої IP-адреси, що й сесія браузера.
4. Негайно запустіть реєстрацію знову (captcha-токени швидко спливають):

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

• README signal-cli: https://github.com/AsamK/signal-cli
• Процес captcha: https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
• Процес зв’язування: https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

​

Режим зовнішнього daemon (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 не має запускати нативний daemon, коли вибрано 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.

​

Контроль доступу (DM + групи)

• За замовчуванням: channels.signal.dmPolicy = "pairing".
• Невідомі відправники отримують код pairing; повідомлення ігноруються, доки їх не підтверджено (коди спливають через 1 годину).
• Підтвердьте через:
  • openclaw pairing list signal
  • openclaw pairing approve signal <CODE>
• Pairing є типовим обміном токенами для Signal DM. Докладно: Pairing
• Відправники лише з 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 для перевизначень за обліковим записом у налаштуваннях із кількома обліковими записами.
• Allowlisting групи Signal через groupAllowFrom сам собою не вимикає mention gating. Спеціально налаштований запис channels.signal.groups["<group-id>"] обробляє кожне повідомлення групи, якщо не встановлено requireMention=true.
• Примітка runtime: якщо channels.signal повністю відсутній, runtime повертається до groupPolicy="allowlist" для перевірок груп (навіть якщо встановлено channels.defaults.groupPolicy).

​

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

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

​

Медіа + ліміти

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

​

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

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

​

Реакції стану життєвого циклу

​

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

• Використовуйте message action=react з channel=signal.
• Цілі: E.164 відправника або UUID (використовуйте uuid:<id> з виводу сполучення; звичайний UUID також працює).
• messageId — це часова мітка 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.

​

Реакції схвалення

• 👍 схвалює один раз.
• 👎 відхиляє.
• Використовуйте /approve <id> allow-always, коли запит пропонує постійне схвалення.

​

Цілі доставлення (CLI/cron)

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

​

Псевдоніми

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

​

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

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

openclaw pairing list signal

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

​

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

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

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

​

Пов’язане

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