Настройка Signal

VibeOS подключается к Signal через демон signal-cli, работающий в режиме HTTP. Адаптер передаёт сообщения в реальном времени через SSE (Server-Sent Events) и отправляет ответы через JSON-RPC.

Signal — самый приватный из массовых мессенджеров: сквозное шифрование по умолчанию, протокол с открытым исходным кодом, минимальный сбор метаданных. Это делает его идеальным для агентных рабочих процессов, чувствительных к безопасности.

Без новых зависимостей Python

Адаптер Signal использует httpx (уже входит в ядро VibeOS) для всей коммуникации. Дополнительные пакеты Python не требуются. Нужен только signal-cli, установленный извне.

---

Предварительные требования

• signal-cli — Signal-клиент на Java (GitHub)
• Java 17+ — среда выполнения, необходимая для signal-cli
• Номер телефона с установленным Signal (для привязки в качестве вторичного устройства)

Установка signal-cli

# macOS
brew install signal-cli

# Linux (скачать последний релиз)
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} \
  https://github.com/AsamK/signal-cli/releases/latest | sed 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}.tar.gz"
sudo tar xf "signal-cli-${VERSION}.tar.gz" -C /opt
sudo ln -sf "/opt/signal-cli-${VERSION}/bin/signal-cli" /usr/local/bin/

предупреждение

signal-cli отсутствует в репозиториях apt или snap. Установка для Linux, описанная выше, загружает файлы напрямую из релизов GitHub.

---

Шаг 1: Привязка учётной записи Signal

Signal-cli работает как привязанное устройство — аналогично WhatsApp Web, но для Signal. Ваш телефон остаётся основным устройством.

# Создание URI для привязки (отображает QR-код или ссылку)
signal-cli link -n "VibeosAgent"

1. Откройте Signal на телефоне
2. Перейдите в Настройки → Привязанные устройства
3. Нажмите Привязать новое устройство
4. Отсканируйте QR-код или введите URI

---

Шаг 2: Запуск демона signal-cli

# Замените +1234567890 на ваш номер Signal (формат E.164)
signal-cli --account +1234567890 daemon --http 127.0.0.1:8080

подсказка

Оставьте этот процесс работать в фоне. Можно использовать systemd, tmux, screen или запустить как службу.

Проверьте, что он работает:

curl http://127.0.0.1:8080/api/v1/check
# Должно вернуть: {"versions":{"signal-cli":...}}

---

Шаг 3: Настройка VibeOS

Самый простой способ:

vibeos gateway setup

Выберите Signal в меню платформ. Мастер выполнит:

1. Проверку установки signal-cli
2. Запрос HTTP-URL (по умолчанию: http://127.0.0.1:8080)
3. Тест соединения с демоном
4. Запрос номера телефона учётной записи
5. Настройку разрешённых пользователей и политик доступа

Ручная настройка

Добавьте в ~/.vibeos/.env:

# Обязательно
SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+1234567890

# Безопасность (рекомендуется)
SIGNAL_ALLOWED_USERS=+1234567890,+0987654321    # Номера E.164 или UUID через запятую

# Опционально
SIGNAL_GROUP_ALLOWED_USERS=groupId1,groupId2     # Включить группы (опустите для отключения, * для всех)
SIGNAL_HOME_CHANNEL=+1234567890                  # Канал по умолчанию для задач cron

Затем запустите шлюз:

vibeos gateway              # На переднем плане
vibeos gateway install      # Установить как пользовательскую службу
sudo vibeos gateway install --system   # Только Linux: системная служба автозапуска

---

Контроль доступа

Доступ в личных сообщениях

Доступ в личных сообщениях следует тому же принципу, что и на других платформах VibeOS:

1. SIGNAL_ALLOWED_USERS задан → только эти пользователи могут писать
2. Белый список не задан → неизвестные пользователи получают код привязки в ЛС (подтвердите через vibeos pairing approve signal CODE)
3. SIGNAL_ALLOW_ALL_USERS=true → писать может кто угодно (используйте с осторожностью)

Доступ в группах

Доступ в группах управляется переменной SIGNAL_GROUP_ALLOWED_USERS:

Конфигурация	Поведение
Не задана (по умолчанию)	Все групповые сообщения игнорируются. Бот отвечает только в ЛС.
Задана с ID групп	Отслеживаются только указанные группы (например, groupId1,groupId2).
Задана как *	Бот отвечает в любой группе, где он состоит.

---

Возможности

Вложения

Адаптер поддерживает отправку и получение медиафайлов в обоих направлениях.

Входящие (пользователь → агент):

• Изображения — PNG, JPEG, GIF, WebP (автоопределение по сигнатуре)
• Аудио — MP3, OGG, WAV, M4A (голосовые сообщения расшифровываются, если настроен Whisper)
• Документы — PDF, ZIP и другие типы файлов

Исходящие (агент → пользователь):

Агент может отправлять медиафайлы через теги MEDIA: в ответах. Поддерживаются следующие способы доставки:

• Изображения — send_multiple_images и send_image_file отправляют PNG, JPEG, GIF, WebP как нативные вложения Signal
• Голос — send_voice отправляет аудиофайлы (OGG, MP3, WAV, M4A, AAC) как вложения
• Видео — send_video отправляет видеофайлы MP4
• Документы — send_document отправляет файлы любого типа (PDF, ZIP и т. д.)

Все исходящие медиафайлы проходят через стандартный API вложений Signal. В отличие от некоторых платформ, Signal не различает голосовые сообщения и файловые вложения на уровне протокола.

Ограничение размера вложений: 100 МБ (в обоих направлениях).

предупреждение

Серверы Signal ограничивают скорость загрузки вложений. Адаптер использует планировщик для отправки нескольких изображений, группируя их по 32 и регулируя загрузку в соответствии с политикой сервера Signal.

Нативное форматирование, цитаты и реакции

Сообщения Signal отображаются с нативным форматированием вместо буквальных символов Markdown. Адаптер преобразует Markdown (**жирный**, *курсив*, `код`, ~~зачёркнутый~~, ||спойлер||, заголовки) в bodyRanges Signal, так что текст отображается с реальным стилем в клиенте получателя, а не как видимые символы ** / `.

Цитаты. Когда VibeOS отвечает на конкретное сообщение, теперь публикуется нативный ответ с цитированием исходного — тот же интерфейс, который видят пользователи Signal при использовании «Ответить». Это происходит автоматически для ответов, сгенерированных на входящее сообщение.

Реакции. Агент может реагировать на сообщения через стандартный API реакций; реакции отображаются в Signal как эмодзи-реакции на указанное сообщение, а не как дополнительный текст.

Всё это не требует дополнительной настройки — работает по умолчанию в последних сборках signal-cli. Если ваша версия signal-cli слишком старая, VibeOS переключается на обычную текстовую доставку и однократно выводит предупреждение в лог.

Индикаторы набора текста

Бот отправляет индикаторы набора текста во время обработки сообщений, обновляя их каждые 8 секунд.

Отображение прогресса инструментов

Signal не поддерживает редактирование уже отправленных сообщений. Поэтому VibeOS подавляет сообщения о прогрессе инструментов шлюза в Signal, даже если включён /verbose и для платформы установлен режим, отличный от off.

Вы по-прежнему можете видеть активность инструментов в CLI, а финальные ответы Signal могут содержать обычный вывод ассистента. Если вам нужен прогресс по каждому инструменту в чате в реальном времени, используйте платформу с поддержкой редактирования сообщений.

Маскировка номеров телефонов

Все номера телефонов автоматически маскируются в логах:

• +15551234567 → +155****4567
• Это относится как к логам шлюза VibeOS, так и к глобальной системе маскировки

Заметка для себя (настройка с одним номером)

Если вы запускаете signal-cli как привязанное вторичное устройство на своём собственном номере телефона (а не на отдельном номере бота), вы можете взаимодействовать с VibeOS через функцию «Заметка для себя» в Signal.

Просто отправьте сообщение самому себе с телефона — signal-cli его подхватит, и VibeOS ответит в том же диалоге.

Как это работает:

• Сообщения «Заметка для себя» приходят как конверты syncMessage.sentMessage
• Адаптер определяет, что они адресованы собственной учётной записи бота, и обрабатывает их как обычные входящие сообщения
• Защита от зацикливания (отслеживание временных меток отправки) предотвращает бесконечные циклы — собственные ответы бота автоматически отфильтровываются

Никакой дополнительной настройки не требуется. Это работает автоматически, если SIGNAL_ACCOUNT совпадает с вашим номером телефона.

Мониторинг состояния

Адаптер отслеживает SSE-соединение и автоматически переподключается в следующих случаях:

• Обрыв соединения (с экспоненциальной задержкой: 2 с → 60 с)
• Отсутствие активности в течение 120 секунд (отправляет ping signal-cli для проверки)

---

Устранение неполадок

Проблема	Решение
«Cannot reach signal-cli» при настройке	Убедитесь, что демон signal-cli запущен: signal-cli --account +YOUR_NUMBER daemon --http 127.0.0.1:8080
Сообщения не приходят	Проверьте, что SIGNAL_ALLOWED_USERS включает номер отправителя в формате E.164 (с префиксом +)
«signal-cli not found on PATH»	Установите signal-cli и убедитесь, что он находится в PATH, или используйте Docker
Соединение постоянно обрывается	Проверьте логи signal-cli на наличие ошибок. Убедитесь, что установлена Java 17+.
Групповые сообщения игнорируются	Настройте SIGNAL_GROUP_ALLOWED_USERS с конкретными ID групп или * для разрешения всех групп.
Бот никому не отвечает	Настройте SIGNAL_ALLOWED_USERS, используйте привязку в ЛС или явно разрешите всех пользователей через политику шлюза, если нужен более широкий доступ.
Дублирующиеся сообщения	Убедитесь, что только один экземпляр signal-cli прослушивает ваш номер телефона.

---

Безопасность

предупреждение

Всегда настраивайте контроль доступа. По умолчанию бот имеет доступ к терминалу. Без SIGNAL_ALLOWED_USERS или привязки в ЛС шлюз отклоняет все входящие сообщения в целях безопасности.

• Номера телефонов маскируются во всех выводах логов
• Используйте привязку в ЛС или явные белые списки для безопасного подключения новых пользователей
• Отключайте группы, если они не нужны, или разрешайте только те группы, которым доверяете
• Сквозное шифрование Signal защищает содержимое сообщений при передаче
• Данные сессии signal-cli в ~/.local/share/signal-cli/ содержат учётные данные учётной записи — защищайте их как пароль

---

Справочник переменных окружения

Переменная	Обязательно	По умолчанию	Описание
SIGNAL_HTTP_URL	Да	—	HTTP-адрес signal-cli
SIGNAL_ACCOUNT	Да	—	Номер телефона бота (E.164)
SIGNAL_ALLOWED_USERS	Нет	—	Номера телефонов/UUID через запятую
SIGNAL_GROUP_ALLOWED_USERS	Нет	—	ID групп для мониторинга или * для всех (опустите для отключения групп)
SIGNAL_ALLOW_ALL_USERS	Нет	false	Разрешить любому пользователю взаимодействие (пропустить белый список)
SIGNAL_HOME_CHANNEL	Нет	—	Канал доставки по умолчанию для задач cron