H繁中版
文件訊息平台signal
<!-- Source: https://hermesbible.com/docs/user-guide/messaging/signal -->

Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/signal

Signal 設定

Hermes 透過在 HTTP 模式下運行的 signal-cli 常駐程式連接 Signal。適配器透過 SSE（Server-Sent Events）即時串流訊息，並透過 JSON-RPC 發送回應。

Signal 是最重視隱私的主流即時通訊軟體——預設端對端加密、開源協定、最小化的中繼資料收集。這使其非常適合安全性要求較高的代理工作流程。

INFO — 無需額外的 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/

CAUTION

signal-cli 不在 apt 或 snap 儲存庫中。上方的 Linux 安裝方式是直接從 GitHub releases 下載。

步驟 1：連結你的 Signal 帳號

signal-cli 作為已連結裝置運作——類似 WhatsApp Web，但是用於 Signal。你的手機仍然是主要裝置。

# 產生連結 URI（顯示 QR code 或連結）
signal-cli link -n "HermesAgent"
  1. 在手機上開啟 Signal
  2. 前往設定 → 已連結裝置
  3. 點選連結新裝置
  4. 掃描 QR code 或輸入 URI

步驟 2：啟動 signal-cli 常駐程式

# 將 +1234567890 替換為你的 Signal 電話號碼（E.164 格式）
signal-cli --account +1234567890 daemon --http 127.0.0.1:8080

TIP

讓它在背景持續運行。你可以使用 systemd、tmux、screen，或將其設定為服務。

驗證是否正常運行：

curl http://127.0.0.1:8080/api/v1/check
# 應該回傳：{"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 中加入：

# 必要
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                  # 排程任務的預設傳遞目標

然後啟動閘道器：

hermes gateway              # 前景運行
hermes gateway install      # 安裝為使用者服務
sudo hermes gateway install --system   # 僅限 Linux：開機時啟動的系統服務

存取控制

私訊存取

私訊存取遵循與所有其他 Hermes 平台相同的模式：

  1. 已設定 SIGNAL_ALLOWED_USERS → 只有這些使用者可以發訊息
  2. 未設定允許清單 → 未知使用者會收到一組私訊配對碼（透過 hermes pairing approve signal CODE 批准）
  3. SIGNAL_ALLOW_ALL_USERS=true → 任何人都可以發訊息（請謹慎使用）

群組存取

群組存取由 SIGNAL_GROUP_ALLOWED_USERS 環境變數控制：

設定方式行為
未設定（預設）忽略所有群組訊息。機器人只回覆私訊。
設定群組 ID只監聽列出的群組（例如 groupId1,groupId2）。
設定為 *機器人會在它所屬的任何群組中回覆。

功能

附件

適配器支援雙向傳送和接收媒體。

接收（使用者 → 代理）：

  • 圖片 — PNG、JPEG、GIF、WebP（透過 magic bytes 自動偵測）
  • 音訊 — MP3、OGG、WAV、M4A（如果已設定 Whisper，語音訊息會被轉錄）
  • 文件 — PDF、ZIP 及其他檔案類型

傳送（代理 → 使用者）：

代理可以透過回應中的 MEDIA: 標籤傳送媒體檔案。支援以下傳遞方式：

  • 圖片 — send_multiple_images 和 send_image_file 以原生 Signal 附件形式傳送 PNG、JPEG、GIF、WebP
  • 語音 — send_voice 以附件形式傳送音訊檔案（OGG、MP3、WAV、M4A、AAC）
  • 影片 — send_video 傳送 MP4 影片檔案
  • 文件 — send_document 傳送任何檔案類型（PDF、ZIP 等）

所有傳送的媒體都透過 Signal 的標準附件 API。與某些平台不同，Signal 在協定層級不區分語音訊息和檔案附件。

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

WARNING

Signal 伺服器會對附件上傳進行速率限制，適配器使用排程器進行多圖片傳送，將圖片分批為 32 張一組，並根據 Signal 伺服器策略節流上傳。

原生格式、回覆引述和表情回應

Signal 訊息使用原生格式渲染，而非純文字的 markdown 字元。適配器將 markdown（**粗體**、*斜體*、`程式碼`、~~刪除線~~、||暴雷||、標題）轉換為 Signal bodyRanges，使文字在收件者的用戶端上顯示為真實的樣式，而非可見的 ** / ` 字元。

回覆引述。 當 Hermes 回覆特定訊息時，現在會發送原生回覆來引用原始訊息——與 Signal 使用者使用「回覆」功能時看到的介面相同。這在回覆收到的訊息時會自動生效。

表情回應。 代理可以透過標準 reaction API 對訊息做出表情回應；表情回應會以 emoji 回應的形式顯示在 Signal 中被引用的訊息上，而非額外的文字。

這些功能不需要額外設定——在較新版的 signal-cli 中預設啟用。如果你的 signal-cli 版本太舊，Hermes 會退回純文字傳送，並記錄一次性的警告。

正在輸入指示器

機器人在處理訊息時會傳送正在輸入的指示器，每 8 秒更新一次。

工具進度顯示

Signal 不支援編輯已傳送的訊息。因此 Hermes 在 Signal 上會隱藏閘道器的工具進度氣泡，即使啟用了 /verbose，也為該平台保留非 off 模式。

你仍然可以在 CLI 中看到工具活動，最終的 Signal 回覆可以包含正常的助手輸出。如果你需要在聊天中即時查看每個工具的進度，請使用支援訊息編輯的訊息平台。

電話號碼遮蔽

所有電話號碼在日誌中會自動遮蔽：

  • +15551234567 → +155****4567
  • 這同時適用於 Hermes 閘道器日誌和全域遮蔽系統

備註給自己（單號碼設定）

如果你在自己的電話號碼上以連結的次要裝置運行 signal-cli（而非使用獨立的機器人號碼），你可以透過 Signal 的「備註給自己」功能與 Hermes 互動。

只需從手機向自己發送一條訊息——signal-cli 會接收它，Hermes 會在同一個對話中回覆。

運作原理：

  • 「備註給自己」訊息以 syncMessage.sentMessage 信封形式抵達
  • 偵測到這些訊息是發送給機器人自己的帳號時，會將它們視為一般收到的訊息處理
  • 迴聲防護（已傳送時間戳記追蹤）防止無限迴圈——機器人自己的回覆會被自動過濾掉

不需要額外設定。 只要 SIGNAL_ACCOUNT 與你的電話號碼相符，這就能自動運作。

健康監控

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

  • 連線中斷（使用指數退避：2 秒 → 60 秒）
  • 120 秒內未偵測到活動（向 signal-cli 發送 ping 驗證）

疑難排解

問題解決方案
設定時出現**「無法連線到 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，使用私訊配對，或透過閘道器策略明確允許所有使用者（如果你需要更廣泛的存取）。
訊息重複確保只有一個 signal-cli 實例在監聽你的電話號碼

安全性

WARNING

務必設定存取控制。 機器人預設具有終端機存取權限。沒有 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否—排程任務的預設傳遞目標
qqbotsimplex