Signal

​

Модель номерів (спочатку прочитайте це)

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

​

Встановлення

openclaw plugins install @openclaw/signal

​

Швидке налаштування

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

​

Що це таке

• Детермінізована маршрутизація: відповіді завжди повертаються до Signal.
• Приватні повідомлення використовують основний сеанс агента спільно; групи ізольовані (agent:<agentId>:signal:group:<groupId>).
• Типово Signal може записувати оновлення конфігурації, ініційовані /config set|unset (потрібен commands.config: true). Вимкніть за допомогою channels.signal.configWrites: false.

​

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

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

​

Шлях налаштування 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-адреси, що й сеанс браузера (строк дії токенів CAPTCHA швидко спливає).
4. Негайно зареєструйте та підтвердьте номер:

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

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

# Якщо ви запускаєте Gateway як користувацьку службу systemd:
systemctl --user restart openclaw-gateway.service

# Потім перевірте:
openclaw doctor
openclaw channels status --probe

5. Створіть пару з відправником приватних повідомлень:
   • Надішліть будь-яке повідомлення на номер бота.
   • Схваліть на сервері: 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)

​

Режим зовнішнього фонового процесу (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", // або "auto" для автоматичного визначення
    },
  },
}

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

​

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

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

{
  channels: {
    signal: {
      account: "+15551234567",
      accountUuid: "bot-signal-uuid",
      groupPolicy: "allowlist",
      groupAllowFrom: ["group:<signal-group-id>"],
      historyLimit: 8,
      groups: {
        "<signal-group-id>": { requireMention: true },
      },
    },
  },
  messages: {
    groupChat: {
      mentionPatterns: ["\\bopenclaw\\b"],
    },
  },
}

​

Принцип роботи (поведінка)

• Нативний режим: signal-cli працює як демон; Gateway зчитує події через SSE.
• Контейнерний режим: Gateway надсилає дані через REST API й отримує їх через WebSocket.
• Вхідні повідомлення нормалізуються до спільного конверта каналу.
• Відповіді завжди спрямовуються назад на той самий номер або в ту саму групу.
• Відповіді на вхідні повідомлення містять нативні метадані цитування Signal, коли серверна частина приймає позначку часу й автора вхідного повідомлення; якщо метадані цитування відсутні або відхилені, OpenClaw надсилає відповідь як звичайне повідомлення.
• Налаштуйте використання нативного цитування за допомогою channels.signal.replyToMode = off | first | all | batched або channels.signal.replyToModeByChatType.direct/group для перевизначень за типом чату. Значення рівня облікового запису в channels.signal.accounts.<id> мають пріоритет.

​

Медіафайли й обмеження

• Вихідний текст розбивається на фрагменти відповідно до channels.signal.textChunkLimit (типово 4000).
• Необов’язкове розбиття за новими рядками: установіть channels.signal.streaming.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 не надає сповіщень про прочитання для груп.

​

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

​

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

• Цілі: 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 (типово minimal).
  • off/ack вимикає реакції агента (інструмент повідомлень react повертає помилки).
  • minimal/extensive вмикає реакції агента й задає рівень настанов.
• Перевизначення для окремих облікових записів: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

​

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

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

​

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

• Особисті повідомлення: signal:+15551234567 (або звичайний E.164).
• Особисті повідомлення за 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 "Розгортання завершено"

{
  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

• Демон доступний, але відповідей немає: перевірте налаштування облікового запису й демона (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.accountUuid: необов’язковий UUID облікового запису бота для виявлення нативних @згадок і захисту від зациклення.
• channels.signal.cliPath: шлях до signal-cli.
• channels.signal.configPath: необов’язковий каталог signal-cli --config.
• channels.signal.httpUrl: повна URL-адреса демона (перевизначає хост і порт).
• channels.signal.httpHost, channels.signal.httpPort: адреса прив’язування демона (типово 127.0.0.1:8080).
• channels.signal.autoStart: автоматично запускати демон (типово true, якщо httpUrl не задано).
• channels.signal.startupTimeoutMs: граничний час очікування запуску в мс (мін. 1000, макс. 120000; типово 30000).
• channels.signal.receiveMode: on-start | manual.
• channels.signal.ignoreAttachments: пропускати завантаження вкладень.
• channels.signal.ignoreStories: ігнорувати історії від демона.
• channels.signal.sendReadReceipts: пересилати сповіщення про прочитання.
• channels.signal.dmPolicy: pairing | allowlist | open | disabled (типово: сполучення).
• channels.signal.allowFrom: список дозволених для особистих повідомлень (E.164 або uuid:<id>). open потребує "*". Signal не має імен користувачів; використовуйте ідентифікатори телефону або UUID.
• channels.signal.aliases: псевдоніми на стороні OpenClaw для цілей доставлення особистих або групових повідомлень.
• channels.signal.groupPolicy: open | allowlist | disabled (типово: список дозволених).
• channels.signal.groupAllowFrom: список дозволених для груп; приймає ідентифікатори груп Signal (без префікса, 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.replyToMode: режим нативного цитування у відповідях, off | first | all | batched (типово: all).
• channels.signal.replyToModeByChatType.direct, channels.signal.replyToModeByChatType.group: перевизначення нативного цитування у відповідях для окремих типів чатів.
• channels.signal.accounts.<id>.replyToMode, channels.signal.accounts.<id>.replyToModeByChatType.direct, channels.signal.accounts.<id>.replyToModeByChatType.group: перевизначення цитування у відповідях для окремих облікових записів.
• channels.signal.historyLimit: максимальна кількість групових повідомлень, що додаються як контекст (0 вимикає).
• channels.signal.dmHistoryLimit: обмеження історії особистих повідомлень у репліках користувача. Перевизначення для окремих користувачів: channels.signal.dms["<phone_or_uuid>"].historyLimit.
• channels.signal.textChunkLimit: розмір вихідного фрагмента в символах (типово 4000).
• channels.signal.streaming.chunkMode: length (типово) або newline, щоб спочатку розбивати текст за порожніми рядками (межами абзаців), а потім — за довжиною.
• channels.signal.mediaMaxMb: обмеження вхідних і вихідних медіафайлів у МБ (типово 8).
• channels.signal.reactionLevel: off | ack | minimal | extensive (типово minimal). Див. Реакції.
• channels.signal.reactionNotifications: off | own | all | allowlist (типово own) — коли агент отримує сповіщення про вхідні реакції інших користувачів.
• channels.signal.reactionAllowlist: відправники, чиї реакції сповіщають агента, коли reactionNotifications: "allowlist".
• channels.signal.streaming.block.enabled, channels.signal.streaming.block.coalesce: спільні для всіх каналів засоби керування потоковим передаванням у блоковому режимі. Див. Потокове передавання.

• agents.list[].groupChat.mentionPatterns (резервний варіант у вигляді звичайного тексту; нативні @згадки Signal виявляються зі структурованих метаданих, коли налаштовано ідентичність облікового запису бота).
• messages.groupChat.mentionPatterns (глобальний резервний варіант).
• messages.responsePrefix.

​

Пов’язані матеріали

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