🏠 Главная › Документация › Мессенджеры

Настройка Signal

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

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

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

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

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

# macOS
brew install signal-cli

# Linux (download latest release)
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 releases](https://github.com/AsamK/signal-cli/releases).

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

# Generate a linking URI (displays a QR code or link)
signal-cli link -n "HermesAgent"

  1. Откройте Signal на телефоне

  2. Перейдите в Настройки → Подключённые устройства

  3. Нажмите Подключить новое устройство

  4. Отсканируйте QR-код или введите URI

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

# Replace +123****7890 with your Signal phone number (E.164 format)
signal-cli --account +123****7890 daemon --http 127.0.0.1:8080
Оставьте это работающим в фоне. Вы можете использовать `systemd`, `tmux`, `screen` или запустить как службу.

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

curl http://127.0.0.1:8080/api/v1/check
# Should return: {"versions":{"signal-cli":...}}

Шаг 3: Настройте Hermes

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

hermes gateway setup

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

  1. Проверит, установлен ли signal-cli

  2. Запросит HTTP URL (по умолчанию: http://127.0.0.1:8080)

  3. Проверит подключение к демону

  4. Запросит номер телефона аккаунта

  5. Настроит разрешённых пользователей и политики доступа

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

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

# Required
SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+123****7890

# Security (recommended)
SIGNAL_ALLOWED_USERS=+123****7890,+0987654321    # Comma-separated E.164 numbers or UUIDs

# Optional
SIGNAL_GROUP_ALLOWED_USERS=groupId1,groupId2     # Enable groups (omit to disable, * for all)
SIGNAL_HOME_CHANNEL=+123****7890                  # Default delivery target for cron jobs

Затем запустите gateway:

hermes gateway              # Foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

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

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

Доступ в личных сообщениях (DM) работает по тому же принципу, что и на всех остальных платформах Hermes:

  1. SIGNAL_ALLOWED_USERS задан — только эти пользователи могут писать

  2. Белый список не задан — неизвестные пользователи получают код привязки для DM (подтвердите через hermes pairing approve signal CODE)

  3. SIGNAL_ALLOW_ALL_USERS=true — любой пользователь может писать (используйте с осторожностью)

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

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

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

Возможности

Вложения

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Сокрытие номеров телефонов

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

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

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

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

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

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

Мониторинг подключения

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

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

Проблема Решение
«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, используйте привязку DM или явно разрешите всех пользователей через политику gateway, если нужен более широкий доступ.
Дублирующиеся сообщения Убедитесь, что только один экземпляр signal-cli прослушивает ваш номер телефона

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

**Всегда настраивайте контроль доступа.** Бот по умолчанию имеет доступ к терминалу. Без `SIGNAL_ALLOWED_USERS` или привязки DM gateway отклоняет все входящие сообщения в целях безопасности.

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

Переменная Обязательная По умолчанию Описание
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