Signal

本指南将指导您如何通过 signal-cli 守护进程（daemon）将 Hermes Agent 部署为一个 Signal 消息机器人。该配置允许您的 AI 代理通过 Signal 接收和发送消息，实现端到端加密的私密通信。

📌 前提条件

确保您已满足以下要求：

已安装并配置好 Hermes Agent
一台运行 Linux 的服务器或本地机器（推荐 Ubuntu 20.04+）
已安装 Java 17 或更高版本
已安装 signal-cli（支持守护进程模式）
一个有效的手机号码（用于注册 Signal 账户）
有权限访问命令行终端

🔧 步骤 1：安装 signal-cli

1.1 安装依赖项

sudo apt update
sudo apt install -y openjdk-17-jdk git curl wget

1.2 下载并安装 signal-cli

# 创建工作目录
mkdir -p ~/signal-cli && cd ~/signal-cli

# 下载最新版本的 signal-cli
wget https://github.com/AsamK/signal-cli/releases/latest/download/signal-cli.tar.gz
tar -xzf signal-cli.tar.gz

# 添加到 PATH
echo 'export PATH=$PATH:~/signal-cli/bin' >> ~/.bashrc
source ~/.bashrc

✅ 确保 signal-cli --help 可以正常运行。

📱 步骤 2：注册 Signal 账号（仅首次）

使用 signal-cli 注册一个新账号：

signal-cli register +86XXXXXXXXXX

替换 +86XXXXXXXXXX 为您的手机号（带国家代码）。
您将收到一条短信验证码，请输入以完成注册。

⚙️ 步骤 3：启动 signal-cli 守护进程

创建守护进程配置文件：

mkdir -p ~/.config/signal-cli
nano ~/.config/signal-cli/config

添加以下内容（根据实际情况修改）：

# ~/.config/signal-cli/config
number = +86XXXXXXXXXX
password = your_secure_password_here
bindAddress = 127.0.0.1
port = 9000

number: 您的 Signal 手机号（带国家代码）

password: 用于保护信号账户的密码（建议使用强密码）

bindAddress 和 port: 守护进程监听地址，Hermes Agent 将连接此端口

启动守护进程

signal-cli-daemon --config ~/.config/signal-cli/config

✅ 成功后会看到日志输出，表示服务已启动。

🤖 步骤 4：配置 Hermes Agent 连接 Signal

编辑 Hermes Agent 的配置文件（通常位于 hermes-agent/config.yml）：

messaging:
  enabled: true
  provider: signal
  signal:
    host: localhost
    port: 9000
    number: +86XXXXXXXXXX
    password: your_secure_password_here

host: 守护进程绑定地址（默认 localhost）

port: 守护进程端口（默认 9000）

number: 与 signal-cli 配置一致

password: 与 signal-cli 配置一致

🔄 步骤 5：启动 Hermes Agent

cd /path/to/hermes-agent
./run.sh

如果一切配置正确，Hermes Agent 将自动连接到 signal-cli 守护进程，并开始监听 Signal 消息。

📞 测试通信

在您的手机上向注册的 Signal 号码发送一条消息，例如：

Hello, Hermes!

您应该会在 Hermes Agent 的日志中看到类似输出：

[INFO] Received message from +86XXXXXXXXXX: Hello, Hermes!
[INFO] Sending response...

Hermes Agent 将自动回复（取决于其技能和上下文）。

🔐 安全建议

使用强密码保护 signal-cli 的账户。
不要将密码明文写入配置文件；可使用环境变量：
```
signal:
  password: ${SIGNAL_PASSWORD}
```
然后在启动前设置：
```
export SIGNAL_PASSWORD="your_secure_password"
```
限制 signal-cli-daemon 的网络访问，仅允许本地连接。

🛠 故障排除

问题	解决方案
`Connection refused`	确保 `signal-cli-daemon` 正在运行且监听 `9000` 端口
`Authentication failed`	检查 `number` 和 `password` 是否正确
无法接收消息	确认 Signal 账号已成功注册并登录
日志无输出	检查 `hermes-agent/config.yml` 是否正确加载

📎 参考链接

✅ 完成！现在您已成功将 Hermes Agent 部署为一个安全、私密的 Signal 消息机器人。

如需集成更多平台（如 Telegram、WhatsApp、Discord），请参考 Hermes Agent 多平台支持文档。

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/

caution

signal-cli 不在 apt 或 snap 软件仓库中。上述 Linux 安装方式直接从 GitHub 发布页下载。

第一步：绑定你的 Signal 账号

signal-cli 以 关联设备 方式运行——类似于 WhatsApp Web，但适用于 Signal。你的手机仍为首要设备。

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

在手机上打开 Signal
进入 设置 → 已链接设备
点击 链接新设备
扫描二维码或输入 URI

第二步：启动 signal-cli 守护进程

# Replace +1234567890 with your Signal phone number (E.164 format)
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
# Should return: {"versions":{"signal-cli":...}}

第三步：配置 Hermes

最简单的方式：

hermes gateway setup

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

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

手动配置

将以下内容添加至 ~/.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 其他平台的相同模式：

SIGNAL_ALLOWED_USERS 已设置 → 仅限这些用户可发送消息
未设置允许列表 → 未知用户将收到一条私信配对码（可通过 hermes pairing approve signal CODE 批准）
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 发送 ping 以验证状态）

故障排除

问题	解决方案
“无法连接 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 实例监听你的手机号码

安全性

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`	否	—	定时任务的默认交付目标

📌 前提条件​

🔧 步骤 1：安装 signal-cli​

1.1 安装依赖项​

1.2 下载并安装 signal-cli​

📱 步骤 2：注册 Signal 账号（仅首次）​

⚙️ 步骤 3：启动 signal-cli 守护进程​

启动守护进程​

🤖 步骤 4：配置 Hermes Agent 连接 Signal​

🔄 步骤 5：启动 Hermes Agent​

📞 测试通信​

🔐 安全建议​

🛠 故障排除​

📎 参考链接​

如需集成更多平台（如 Telegram、WhatsApp、Discord），请参考 Hermes Agent 多平台支持文档。​

Signal 设置

先决条件​

安装 signal-cli​

第一步：绑定你的 Signal 账号​

第二步：启动 signal-cli 守护进程​

第三步：配置 Hermes​

手动配置​

访问控制​

私信访问​

群组访问​

功能特性​

附件支持​

输入提示​

电话号码脱敏​

自我笔记（单号码设置）​

健康监测​

故障排除​

安全性​

环境变量参考​