Signal 配置

Hermes 通過運行在 HTTP 模式下的 signal-cli 守護進程連接到 Signal。該適配器通過 SSE（服務器發送事件）實時流式傳輸消息，並通過 JSON-RPC 發送響應。

Signal 是最注重隱私的主流即時通訊工具 —— 默認端到端加密，開源協議，極少收集元數據。這使其非常適合安全敏感的 Agent 工作流。

無需新增 Python 依賴

Signal 適配器使用 httpx（已是 Hermes 的核心依賴）進行所有通信。無需額外安裝 Python 包。您只需在外部安裝 signal-cli。

先決條件

signal-cli — 基於 Java 的 Signal 客戶端 (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 發佈頁下載。

第一步：綁定您的 Signal 賬號

signal-cli 作為 已綁定設備 運行 —— 類似於 WhatsApp Web，但適用於 Signal。您的手機仍為首選設備。

# 生成鏈接 URI（顯示 QR 代碼或鏈接）
signal-cli link -n "Hermes Agent"

在手機上打開 Signal
進入 設置 → 已綁定設備
點擊 綁定新設備
掃描二維碼或輸入 URI

第二步：啟動 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":...}}

第三步：配置 Hermes

最簡單的方式：

hermes gateway setup

從平臺菜單中選擇 Signal。嚮導將執行以下操作：

檢查 signal-cli 是否已安裝
提示輸入 HTTP 地址（默認：http://127.0.0.1:8080）
測試與守護進程的連接
請求您的賬戶手機號碼
配置允許的用戶和訪問策略

手動配置

將以下內容添加至 ~/.hermes/.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 作業的默認交付目標

然後啟動網關：

hermes gateway              # 前景
hermes gateway install      # 安裝為用戶服務
sudo hermes gateway install --system   # 僅限 Linux：啟動時系統服務

訪問控制

私信訪問

私信訪問遵循所有其他 Hermes 平臺的相同模式：

設置了 SIGNAL_ALLOWED_USERS → 僅允許列表中的用戶發送消息
未設置允許列表 → 未知用戶將收到一條私信配對碼（可通過 hermes pairing approve signal CODE 批准）
SIGNAL_ALLOW_ALL_USERS=true → 任何人都可以發送消息（請謹慎使用）

群組訪問

群組訪問由 SIGNAL_GROUP_ALLOWED_USERS 環境變量控制：

配置	行為
未設置（默認）	所有群組消息將被忽略。機器人僅響應私信。
設置幷包含群組 ID	僅監控列出的群組（例如：`groupId1,groupId2`）。
設置為 `*`	機器人在加入的任何群組中均會響應。

功能特性

附件支持

該適配器支持雙向發送和接收媒體文件。

入站（用戶 → Agent）：

圖片 — PNG、JPEG、GIF、WebP（通過魔數自動檢測）
音頻 — MP3、OGG、WAV、M4A（若已配置 Whisper，語音消息將被轉錄）
文檔 — PDF、ZIP 及其他文件類型

出站（Agent → 用戶）：

Agent 可通過在響應中使用 MEDIA: 標籤發送媒體文件。支持以下發送方式：

圖片 — send_image_file 將 PNG、JPEG、GIF、WebP 作為原生 Signal 附件發送
語音 — send_voice 將 OGG、MP3、WAV、M4A、AAC 音頻文件作為附件發送
視頻 — send_video 發送 MP4 視頻文件
文檔 — send_document 發送任意文件類型（PDF、ZIP 等）

所有出站媒體均通過 Signal 的標準附件 API 發送。與某些平臺不同，Signal 在協議層面不區分語音消息和文件附件。

附件大小限制：100 MB（雙向）。

輸入狀態指示

機器人在處理消息時會發送輸入狀態指示，每 8 秒刷新一次。

電話號碼脫敏

所有電話號碼在日誌中均會自動脫敏：

+15551234567 → +155****4567
此規則適用於 Hermes 網關日誌和全局脫敏系統

自我備註（單號碼設置）

如果您將 signal-cli 作為 已綁定的輔助設備 運行在您自己的手機號碼上（而非獨立的機器人號碼），可以通過 Signal 的“自我備註”功能與 Hermes 交互。

只需從您的手機向自己發送一條消息 —— signal-cli 會捕獲該消息，Hermes 會在同一對話中回覆。

工作原理：

“自我備註”消息以 syncMessage.sentMessage 消息包形式到達
適配器檢測到這些消息是發給機器人自身賬戶的，將其作為常規入站消息處理
回聲保護機制（基於發送時間戳追蹤）可防止無限循環 —— 機器人自身的回覆將自動過濾掉

無需額外配置。 只要 SIGNAL_ACCOUNT 與您的手機號碼匹配，此功能即可自動生效。

健康監控

適配器會監控 SSE 連接，並在以下情況下自動重連：

連接中斷（採用指數退避策略：2秒 → 60秒）
120秒內未檢測到活動（通過發送心跳信號通知 signal-cli 進行驗證）

故障排除

問題	解決方案
設置過程中出現“無法連接 signal-cli”	確保 signal-cli 守護進程正在運行：`signal-cli --account +YOUR_NUMBER daemon --http 127.0.0.1:8080`
消息未收到	檢查 `SIGNAL_ALLOWED_USERS` 是否包含發送方號碼（E.164 格式，帶 `+` 前綴）
“signal-cli 未在 PATH 中找到”	安裝 signal-cli 並確保其在系統 PATH 中，或使用 Docker
連接頻繁中斷	檢查 signal-cli 日誌中的錯誤信息。確保已安裝 Java 17 或更高版本。
群組消息被忽略	通過配置 `SIGNAL_GROUP_ALLOWED_USERS` 指定特定群組 ID，或使用 `*` 允許所有群組。
機器人不響應任何人	配置 `SIGNAL_ALLOWED_USERS`，使用私聊配對，或在網關策略中顯式允許所有用戶以獲得更廣泛的訪問權限。
消息重複接收	確保僅有一個 signal-cli 實例在監聽您的手機號碼

安全性

注意

始終配置訪問控制。 默認情況下，該機器人具有終端訪問權限。若未設置 SIGNAL_ALLOWED_USERS 或未進行私聊配對，網關將拒絕所有傳入消息，以確保安全。

所有日誌輸出中手機號碼均已被脫敏
通過私聊配對或顯式允許列表安全地為新用戶開通權限
除非您明確需要群組支持，否則應保持群組功能禁用，或僅允許您信任的群組
Signal 的端到端加密可保護傳輸中的消息內容
~/.local/share/signal-cli/ 中的 signal-cli 會話數據包含賬戶憑據 —— 請像保護密碼一樣保護它

環境變量參考

變量	是否必需	默認值	描述
`SIGNAL_HTTP_URL`	是	—	signal-cli HTTP 端點
`SIGNAL_ACCOUNT`	是	—	機器人手機號碼（E.164 格式）
`SIGNAL_ALLOWED_USERS`	否	—	以逗號分隔的手機號碼/UUID 列表
`SIGNAL_GROUP_ALLOWED_USERS`	否	—	要監控的群組 ID，或使用 `*` 表示所有群組（省略則禁用群組功能）
`SIGNAL_ALLOW_ALL_USERS`	否	`false`	允許任何用戶交互（跳過允許列表）
`SIGNAL_HOME_CHANNEL`	否	—	定時任務的默認消息投遞目標

先決條件​

安裝 signal-cli​

第一步：綁定您的 Signal 賬號​

第二步：啟動 signal-cli 守護進程​

第三步：配置 Hermes​

手動配置​

訪問控制​

私信訪問​

群組訪問​

功能特性​

附件支持​

輸入狀態指示​

電話號碼脫敏​

自我備註（單號碼設置）​

健康監控​

故障排除​

安全性​

環境變量參考​