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.
No New Python Dependencies
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 %\&#123;url_effective&#125; \
  https://GitHub.com/AsamK/Signal-CLI/releases/latest | sed 's/^.*\/v//')
curl -L -O "https://GitHub.com/AsamK/Signal-CLI/releases/download/v$\&#123;VERSION&#125;/Signal-CLI-$\&#123;VERSION&#125;.tar.gz"
sudo tar xf "Signal-CLI-$\&#123;VERSION&#125;.tar.gz" -C /opt
sudo ln -sf "/opt/Signal-CLI-$\&#123;VERSION&#125;/bin/Signal-CLI" /usr/local/bin/

`

:::caution
Signal-CLI **không** có trong kho apt hoặc snap. Bản cài đặt Linux ở trên tải xuống trực tiếp từ [GitHub releases](https://GitHub.com/AsamK/Signal-CLI/releases).
:::

---

## 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.

``` bash

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

`

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

---

## Bước 2: Khởi động Daemon Signal-CLI

``` bash

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

`

:::tip
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:

``` bash
curl http://127.0.0.1:8080/API/v1/check

# Should return: \&#123;"versions":\&#123;"Signal-CLI":...&#125;&#125;

`

---

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

Cách dễ nhất:

``` bash
Hermes gateway setup

`
``Chọn **Tín hiệu** từ menu nền tảng. Trình hướng dẫn sẽ:
1. Kiểm tra xem Signal-CLI đã được cài đặt chưa

2. Nhắc URL HTTP (mặc định: 
`http://127.0.0.1:8080

)
3. Kiểm tra kết nối với daemon
4. Hỏi số điện thoại tài khoản của bạn
5. 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

:

``` bash

# 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:

``` bash
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:
1. **Bộ 
`Signal_ALLOWED_USERS

`
** → chỉ những người dùng đó mới có thể nhắn tin
2. **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

)
3. **
`Signal_ALLOW_ALL_USERS=true

** → bất kỳ ai cũng có thể nhắn tin (sử dụng thận trọng)

### Truy cập nhóm

Quyền truy cập 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):

Tác nhân có thể gửi các 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_multiple_images
` và 
`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 các 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).
:::warning
**Các máy chủ Signal sẽ tải lên tệp đính kèm có giới hạn tốc độ**, bộ điều hợp sử dụng bộ lập lịch gửi nhiều hình ảnh để phân nhóm các hình ảnh theo nhóm 32 và điều chỉnh tải lên để phù hợp với chính sách của máy chủ Signal.
:::

### Định dạng gốc, trích dẫn trả lời và phản ứngThông báo tín hiệu hiển thị với **định dạng gốc** thay vì các ký tự đánh dấu theo nghĩa đen. Bộ chuyển đổi chuyển đổi đánh dấu (

**bold**

, 

*italic*

, 

` 
`code
` 

`
, 

~~ đình công~~

, 

||spoiler||

, headings) into Signal 
`bodyRanges
` so the text shows up with real styling on the recipient's CLIent rather than as visible 

**
` / 

` 
` 

` ký tự.

**Trả lời các câu trích dẫn.** Khi Hermes trả lời một tin nhắn cụ thể, giờ đây Hermes sẽ đăng một câu trả lời gốc trích dẫn câu trả lời gốc — giao diện người dùng tương tự mà người dùng Signal thấy khi họ tự sử dụng "Trả lời". Điều này là tự động đối với các câu trả lời được tạo để phản hồi một tin nhắn gửi đến.

**Phản ứng.** Tác nhân có thể phản ứng với tin nhắn thông qua API phản ứng tiêu chuẩn; các phản ứng xuất hiện trong Signal dưới dạng các phản ứng biểu tượng cảm xúc trên tin nhắn được tham chiếu chứ không phải dưới dạng văn bản bổ sung.

Không có điều nào trong số này yêu cầu cấu hình bổ sung - nó được vận chuyển theo mặc định trong các bản dựng Signal-CLI gần đây. Nếu phiên bản 
`Signal-CLI
` của bạn quá cũ, Hermes sẽ quay lại phân phối văn bản thuần túy và ghi lại cảnh báo một lần.

### 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" đến 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 (có 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

:::warning
**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ả cá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ệ nó 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 để 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​

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

Cài đặt Signal-CLI
