🏠 Главная › User Guide › signal

sidebar_position: 6 title: "Signal" description: "Set up Hermes Agent as a Signal messenger bot via signal-cli daemon" lang: ru

Настройка сигнала

Hermes подключается к Signal через демон signal-cli, работающий в режиме HTTP. Адаптер передает потоковые сообщения в режиме реального времени через SSE (события, отправленные сервером) и отправляет ответы через 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.

Шаг 1: Привяжите свою учетную запись Signal

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 +1234567890 with your Signal phone number (E.164 format)
signal-cli --account +1234567890 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 gateway setup

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

  1. Проверьте, установлен ли signal-cli.
  2. Запросить URL-адрес HTTP (по умолчанию: http://127.0.0.1:8080)
  3. Test connectivity to the daemon
  4. Ask for your account phone number
  5. Configure allowed users and access policies

Manual Configuration

Add to ~/.hermes/.env:

# Required
SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+1234567890

# Security (recommended)
SIGNAL_ALLOWED_USERS=+1234567890,+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=+1234567890                  # Default delivery target for cron jobs

Then start the gateway:

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

Access Control

DM Access

DM access follows the same pattern as all other Hermes platforms:

  1. SIGNAL_ALLOWED_USERS set → only those users can message
  2. No allowlist set → unknown users get a DM pairing code (approve via hermes сигнал одобрения сопряжения CODE)
  3. SIGNAL_ALLOW_ALL_USERS=true → anyone can message (use with caution)

Group Access

Group access is controlled by the SIGNAL_GROUP_ALLOWED_USERS env var:

Configuration Behavior
Not set (default) All group messages are ignored. The bot only responds to DMs.
Set with group IDs Only listed groups are monitored (e.g., groupId1,groupId 2).
Set to * The bot responds in any group it's a member of.

Features

Attachments

The adapter supports sending and receiving media in both directions.

Incoming (user → agent):

Outgoing (agent → user):

The agent can send media files via MEDIA: tags in responses. The following delivery methods are supported:

All outgoing media goes through Signal's standard attachment API. Unlike some platforms, Signal does not distinguish between voice messages and file attachments at the protocol level.

Attachment size limit: 100 MB (both directions).

⚠️ Warning

**Signal servers will rate-limit attachment uploads**, the adapter uses a scheduler for multiple image sending that batches images in groups of 32 and throttles uploads to match the Signal server policy.

Native Formatting, Reply Quotes, and Reactions

Signal messages render with native formatting instead of literal markdown characters. The adapter converts markdown (**bold**, *italic*, `code `, ~~strike~~, ||спойлер||, headings) into Signal bodyRanges so the text shows up with real styling on the recipient's client rather than as visible ** / ` characters.

Reply quotes. When Hermes replies to a specific message, it now posts a native reply that quotes the original — same UI affordance Signal users see when they use "Reply" themselves. This is automatic for replies generated in response to an inbound message.

Reactions. The agent can react to messages via the standard reaction API; reactions surface in Signal as emoji reactions on the referenced message rather than as extra text.

None of this requires additional config — it ships on by default in recent signal-cli builds. If your signal-cli version is too old, Hermes falls back to plaintext delivery and logs a one-time warning.

Typing Indicators

The bot sends typing indicators while processing messages, refreshing every 8 seconds.

Phone Number Redaction

All phone numbers are automatically redacted in logs: - +15551234567 → +155****4567 - This applies to both Hermes gateway logs and the global redaction system

Note to Self (Single-Number Setup)

If you run signal-cli as a linked secondary device on your own phone number (rather than a separate bot number), you can interact with Hermes through Signal's "Note to Self" feature.

Just send a message to yourself from your phone — signal-cli picks it up and Hermes responds in the same conversation.

How it works: - "Note to Self" messages arrive as syncMessage.sentMessage envelopes - The adapter detects when these are addressed to the bot's own account and processes them as regular inbound messages - Echo-back protection (sent-timestamp tracking) prevents infinite loops — the bot's own replies are filtered out automatically

No extra configuration needed. This works automatically as long as SIGNAL_ACCOUNT matches your phone number.

Health Monitoring

The adapter monitors the SSE connection and automatically reconnects if: - The connection drops (with exponential backoff: 2s → 60s) - No activity is detected for 120 seconds (pings signal-cli to verify)

Troubleshooting

Problem Solution
"Cannot reach signal-cli" during setup Ensure signal-cli daemon is running: signal-cli --account +YOUR_NUMBER daemon --http 127.0.0.1:8080
Messages not received Check that SIGNAL_ALLOWED_USERS includes the sender's number in E.164 format (with + prefix)
"signal-cli not found on PATH" Install signal-cli and ensure it's in your PATH, or use Docker
Connection keeps dropping Check signal-cli logs for errors. Ensure Java 17+ is installed.
Group messages ignored Configure SIGNAL_GROUP_ALLOWED_USERS@@IC0037@ @* to allow all groups.
Bot responds to no one Configure SIGNAL_ALLOWED_USERS, use DM pairing, or explicitly allow all users through gateway policy if you want broader access.
Duplicate messages Ensure only one signal-cli instance is listening on your phone number

Security

⚠️ Warning

**Always configure access controls.** The bot has terminal access by default. Without `SIGNAL_ALLOWED_USERS` or DM pairing, the gateway denies all incoming messages as a safety measure.