跳到主要内容

Signal 配置

Hermes 通过运行在 HTTP 模式下的 signal-cli 守护进程连接到 Signal。该适配器通过 SSE（服务器发送事件）实时流式传输消息，并通过 JSON-RPC 发送响应。

Signal 是最注重隐私的主流即时通讯工具 —— 默认端到端加密，开源协议，极少收集元数据。这使其非常适合安全敏感的代理工作流。

无需新增 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 (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 发布页 下载。

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. 扫描二维码或输入 URI

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

第三步：配置 Hermes​

最简单的方式：

hermes gateway setup

从平台菜单中选择 Signal。向导将执行以下操作：

  1. 检查 signal-cli 是否已安装
  2. 提示输入 HTTP 地址（默认：http://127.0.0.1:8080）
  3. 测试与守护进程的连接
  4. 请求您的账户手机号码
  5. 配置允许的用户和访问策略

手动配置​

将以下内容添加至 ~/.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

然后启动网关：

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

访问控制​

私信访问​

私信访问遵循所有其他 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（通过魔数自动检测）
  • 音频 — MP3、OGG、WAV、M4A（若已配置 Whisper，语音消息将被转录）
  • 文档 — PDF、ZIP 及其他文件类型

出站（代理 → 用户）：

代理可通过在响应中使用 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否—定时任务的默认消息投递目标