Thiết lập tín hiệu

Hermes kết nối với Signal thông qua daemon signal-cli chạy ở chế độ HTTP. Bộ điều hợp truyền phát tin nhắn trong thời gian thực thông qua SSE (Sự kiện do máy chủ gửi) và gửi phản hồi qua JSON-RPC.

Signal là ứng dụng nhắn tin chính thống tập trung vào quyền riêng tư nhất — được mã hóa hai đầu theo mặc định, giao thức nguồn mở, thu thập siêu dữ liệu ở mức tối thiểu. Điều này khiến nó trở nên lý tưởng cho các quy trình làm việc của tổng đài viên có yêu cầu bảo mật cao.

Không có phụ thuộc Python mới

Bộ điều hợp tín hiệu sử dụng httpx (đã là phần phụ thuộc cốt lõi của Hermes) cho tất cả hoạt động liên lạc. Không cần gói Python bổ sung. Bạn chỉ cần cài đặt signal-cli bên ngoài.

Điều kiện tiên quyết

signal-cli — Ứng dụng khách Tín hiệu dựa trên Java (GitHub)
Thời gian chạy Java 17+ — được yêu cầu bởi signal-cli
Số điện thoại đã cài đặt Signal (để liên kết làm thiết bị phụ)

Cài đặt 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/

cẩn thận

signal-cli không có trong kho apt hoặc snap. Bản cài đặt Linux ở trên được tải xuống trực tiếp từ Bản phát hành GitHub.

Bước 1: Liên kết tài khoản Signal của bạn

Signal-cli hoạt động như một thiết bị được liên kết — giống như WhatsApp Web, nhưng dành cho Signal. Điện thoại của bạn vẫn là thiết bị chính.

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

Mở Tín hiệu trên điện thoại của bạn
Đi tới Cài đặt → Thiết bị được liên kết
Nhấn vào Liên kết thiết bị mới
Quét mã QR hoặc nhập URI

Bước 2: Khởi động Daemon signal-cli

# Replace +1234567890 with your Signal phone number (E.164 format)
signal-cli --account +1234567890 daemon --http 127.0.0.1:8080

mẹo

Giữ cái này chạy ở chế độ nền. Bạn có thể sử dụng systemd , tmux , screen hoặc chạy nó dưới dạng dịch vụ.

Xác minh nó đang chạy:

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

Bước 3: Cấu hình Hermes

Cách dễ nhất:

hermes gateway setup

Chọn Tín hiệu từ menu nền tảng. Trình hướng dẫn sẽ:

Kiểm tra xem signal-cli đã được cài đặt chưa
Nhắc nhập URL HTTP (mặc định: http://127.0.0.1:8080 )
Kiểm tra kết nối với daemon
Hỏi số điện thoại tài khoản của bạn
Cấu hình người dùng được phép và chính sách truy cập

Cấu hình thủ công

Thêm vào ~/.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

Sau đó khởi động cổng:

hermes gateway              

# Foreground
hermes gateway install      

# Install as a user service
sudo hermes gateway install --system   

# Linux only: boot-time system service

Kiểm soát truy cập

Truy cập tin nhắn trực tiếp

Quyền truy cập DM tuân theo mô hình tương tự như tất cả các nền tảng Hermes khác:

** SIGNAL_ALLOWED_USERS set** → chỉ những người dùng đó mới có thể nhắn tin
Chưa đặt danh sách cho phép → người dùng không xác định nhận được mã ghép nối DM (phê duyệt qua hermes pairing approve signal CODE )
** SIGNAL_ALLOW_ALL_USERS=true ** → bất kỳ ai cũng có thể nhắn tin (hãy thận trọng khi sử dụng)

Truy cập nhóm

Quyền truy cập của nhóm được kiểm soát bởi SIGNAL_GROUP_ALLOWED_USERS env var:

Cấu hình	Hành vi
Chưa được đặt (mặc định)	Tất cả các tin nhắn nhóm đều bị bỏ qua. Bot chỉ trả lời DM.
Đặt bằng ID nhóm	Chỉ các nhóm được liệt kê mới được giám sát (ví dụ: `groupId1,groupId2` ).
Đặt thành `*`	Bot sẽ phản hồi trong bất kỳ nhóm nào mà nó là thành viên.

Tính năng

Tệp đính kèm

Bộ điều hợp hỗ trợ gửi và nhận phương tiện theo cả hai hướng.

Đang đến (người dùng → đại lý):- Hình ảnh — PNG, JPEG, GIF, WebP (được tự động phát hiện thông qua byte ma thuật)

Âm thanh — MP3, OGG, WAV, M4A (tin nhắn thoại được chép lại nếu Whisper được định cấu hình)
Tài liệu — PDF, ZIP và các loại tệp khác

Gửi đi (đại lý → người dùng):

Nhân viên hỗ trợ có thể gửi tệp phương tiện qua thẻ MEDIA: trong phản hồi. Các phương thức giao hàng sau được hỗ trợ:

Hình ảnh — send_image_file gửi PNG, JPEG, GIF, WebP dưới dạng tệp đính kèm Tín hiệu gốc
Giọng nói — send_voice gửi tệp âm thanh (OGG, MP3, WAV, M4A, AAC) dưới dạng tệp đính kèm
Video — send_video gửi tệp video MP4
Tài liệu — send_document gửi bất kỳ loại tệp nào (PDF, ZIP, v.v.)

Tất cả phương tiện gửi đi đều đi qua API đính kèm tiêu chuẩn của Signal. Không giống như một số nền tảng, Signal không phân biệt giữa tin nhắn thoại và tệp đính kèm ở cấp độ giao thức.

Giới hạn kích thước tệp đính kèm: 100 MB (cả hai hướng).

Chỉ báo gõ

Bot gửi chỉ báo gõ trong khi xử lý tin nhắn, làm mới sau mỗi 8 giây.

Biên tập số điện thoại

Tất cả các số điện thoại sẽ tự động được sắp xếp lại trong nhật ký:

+15551234567 → +155****4567
Điều này áp dụng cho cả nhật ký cổng Hermes và hệ thống biên tập toàn cầu

Ghi chú cho bản thân (Cài đặt một số)

Nếu bạn chạy signal-cli dưới dạng thiết bị phụ được liên kết trên số điện thoại của chính bạn (chứ không phải số bot riêng), bạn có thể tương tác với Hermes thông qua tính năng "Note to Self" của Signal.

Chỉ cần gửi tin nhắn cho chính bạn từ điện thoại của bạn - signal-cli nhận tin nhắn và Hermes trả lời trong cùng một cuộc trò chuyện.

Cách thức hoạt động:

Tin nhắn "Note to Self" được gửi dưới dạng phong bì syncMessage.sentMessage
Bộ điều hợp phát hiện khi chúng được gửi đến tài khoản của chính bot và xử lý chúng dưới dạng tin nhắn gửi đến thông thường
Bảo vệ phản hồi (theo dõi dấu thời gian đã gửi) ngăn chặn các vòng lặp vô hạn — các câu trả lời của bot sẽ tự động được lọc ra

Không cần cấu hình bổ sung. Tính năng này hoạt động tự động miễn là SIGNAL_ACCOUNT khớp với số điện thoại của bạn.

Theo dõi sức khỏe

Bộ điều hợp giám sát kết nối SSE và tự động kết nối lại nếu:

Kết nối bị rớt (với thời gian chờ theo cấp số nhân: 2 giây → 60 giây)
Không phát hiện hoạt động nào trong 120 giây (ping signal-cli để xác minh)

Khắc phục sự cố

Vấn đề	Giải pháp
"Không thể kết nối với signal-cli" trong khi thiết lập	Đảm bảo daemon signal-cli đang chạy: `signal-cli --account +YOUR_NUMBER daemon --http 127.0.0.1:8080`
Không nhận được tin nhắn	Kiểm tra xem `SIGNAL_ALLOWED_USERS` có bao gồm số người gửi ở định dạng E.164 (với tiền tố `+`)
"không tìm thấy signal-cli trên PATH"	Cài đặt signal-cli và đảm bảo nó nằm trong PATH của bạn hoặc sử dụng Docker
Kết nối liên tục bị rớt	Kiểm tra nhật ký tín hiệu-cli để tìm lỗi. Đảm bảo Java 17+ được cài đặt.
Tin nhắn nhóm bị bỏ qua	Định cấu hình `SIGNAL_GROUP_ALLOWED_USERS` với ID nhóm cụ thể hoặc `*` để cho phép tất cả các nhóm.
Bot không trả lời ai	Định cấu hình `SIGNAL_ALLOWED_USERS` , sử dụng ghép nối DM hoặc cho phép rõ ràng tất cả người dùng thông qua chính sách cổng nếu bạn muốn truy cập rộng hơn.
Tin nhắn trùng lặp	Đảm bảo chỉ có một phiên bản signal-cli đang lắng nghe số điện thoại của bạn

Bảo mật

cảnh báo

Luôn định cấu hình các biện pháp kiểm soát quyền truy cập. Theo mặc định, bot có quyền truy cập terminal. Nếu không ghép nối SIGNAL_ALLOWED_USERS hoặc DM, cổng sẽ từ chối tất cả tin nhắn đến như một biện pháp an toàn.

Số điện thoại được sắp xếp lại trong tất cả đầu ra nhật ký
Sử dụng tính năng ghép nối DM hoặc danh sách cho phép rõ ràng để giới thiệu người dùng mới một cách an toàn
Vô hiệu hóa các nhóm trừ khi bạn đặc biệt cần hỗ trợ nhóm hoặc chỉ đưa những nhóm bạn tin cậy vào danh sách cho phép
Mã hóa đầu cuối của Signal bảo vệ nội dung tin nhắn khi truyền
Dữ liệu phiên signal-cli trong ~/.local/share/signal-cli/ chứa thông tin xác thực tài khoản — bảo vệ dữ liệu đó như mật khẩu

Tham chiếu biến môi trường

Biến	Bắt buộc	Mặc định	Mô tả
`SIGNAL_HTTP_URL`	Có	—	điểm cuối HTTP signal-cli
`SIGNAL_ACCOUNT`	Có	—	Số điện thoại bot (E.164)
`SIGNAL_ALLOWED_USERS`	Không	—	Số điện thoại/UUID được phân tách bằng dấu phẩy
`SIGNAL_GROUP_ALLOWED_USERS`	Không	—	ID nhóm cần giám sát hoặc `*` cho tất cả (bỏ qua để tắt nhóm)
`SIGNAL_ALLOW_ALL_USERS`	Không	`false`	Cho phép bất kỳ người dùng nào tương tác (bỏ qua danh sách cho phép)
`SIGNAL_HOME_CHANNEL`	Không	—	Mục tiêu phân phối mặc định cho công việc định kỳ

Điều kiện tiên quyết

Cài đặt signal-cli​

Bước 1: Liên kết tài khoản Signal của bạn

Bước 2: Khởi động Daemon signal-cli

Bước 3: Cấu hình Hermes

Cấu hình thủ công​

Kiểm soát truy cập

Truy cập tin nhắn trực tiếp​

Truy cập nhóm​

Tính năng

Tệp đính kèm​

Chỉ báo gõ​

Biên tập số điện thoại​

Ghi chú cho bản thân (Cài đặt một số)​

Theo dõi sức khỏe​