跳到主要内容

SMS 配置（Twilio）

Hermes 通过 Twilio API 连接到短信。人们向你的 Twilio 手机号发短信，就能获得 AI 回复——与 Telegram 或 Discord 相同的对话体验，但通过标准短信实现。

共享凭证

SMS 网关与可选的电话技能（telephony skill）共享凭证。如果你已经为语音通话或一次性短信设置了 Twilio，网关与相同的 TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN 和 TWILIO_PHONE_NUMBER 一起工作。

前提条件​

  • Twilio 账户——在 twilio.com 注册（提供免费试用）
  • 具有短信功能的 Twilio 手机号
  • 可公开访问的服务器——当短信到达时，Twilio 会向你的服务器发送 Webhook
  • aiohttp——pip install 'hermes-agent[sms]'

步骤 1：获取你的 Twilio 凭证​

  1. 前往 Twilio Console
  2. 从仪表板复制你的 Account SID 和 Auth Token
  3. 前往 Phone Numbers → Manage → Active Numbers——记下你的手机号（E.164 格式，如 +15551234567）

步骤 2：配置 Hermes​

交互式设置（推荐）​

hermes gateway setup

从平台列表中选择 SMS (Twilio)。向导会提示你输入凭证。

手动设置​

添加到 ~/.hermes/.env：

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+15551234567

# 安全：限制特定手机号（推荐）
SMS_ALLOWED_USERS=+15559876543,+15551112222

# 可选：为定时任务设置主频道
SMS_HOME_CHANNEL=+15559876543

步骤 3：配置 Twilio Webhook​

Twilio 需要知道将传入消息发送到哪里。在 Twilio Console 中：

  1. 前往 Phone Numbers → Manage → Active Numbers
  2. 点击你的手机号
  3. 在 Messaging → A MESSAGE COMES IN 下，设置：
    • Webhook：https://your-server:8080/webhooks/twilio
    • HTTP Method：POST
暴露你的 Webhook

如果你在本地运行 Hermes，使用隧道来暴露 Webhook：

# 使用 cloudflared
cloudflared tunnel --url http://localhost:8080

# 使用 ngrok
ngrok http 8080

将生成的公网 URL 设置为你的 Twilio Webhook。

将 SMS_WEBHOOK_URL 设置为与你在 Twilio 中配置的相同 URL。 这是 Twilio 签名验证所必需的——没有它，适配器将拒绝启动：

# 必须与 Twilio Console 中的 Webhook URL 匹配
SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twilio

Webhook 端口默认为 8080。使用以下变量覆盖：

SMS_WEBHOOK_PORT=3000

步骤 4：启动网关​

hermes gateway

你应该看到：

[sms] Twilio webhook server listening on 0.0.0.0:8080, from: +1555***4567

如果你看到 Refusing to start: SMS_WEBHOOK_URL is required，请将 SMS_WEBHOOK_URL 设置为在 Twilio Console 中配置的公网 URL（见步骤 3）。

向你的 Twilio 号码发短信——Hermes 将通过短信回复。

环境变量​

变量是否必需描述
TWILIO_ACCOUNT_SID是Twilio Account SID（以 AC 开头）
TWILIO_AUTH_TOKEN是Twilio Auth Token（也用于 Webhook 签名验证）
TWILIO_PHONE_NUMBER是你的 Twilio 手机号（E.164 格式）
SMS_WEBHOOK_URL是Twilio 签名验证的公网 URL——必须与 Twilio Console 中的 Webhook URL 匹配
SMS_WEBHOOK_PORT否Webhook 监听端口（默认：8080）
SMS_WEBHOOK_HOST否Webhook 绑定地址（默认：0.0.0.0）
SMS_INSECURE_NO_SIGNATURE否设置为 true 可禁用签名验证（仅限本地开发——不适合生产环境）
SMS_ALLOWED_USERS否允许聊天的 E.164 格式手机号（逗号分隔）
SMS_ALLOW_ALL_USERS否设置为 true 以允许任何人（不推荐）
SMS_HOME_CHANNEL否定时任务/通知发送的手机号
SMS_HOME_CHANNEL_NAME否主频道的显示名称（默认：Home）

短信特有行为​

  • 仅纯文本——Markdown 会自动去除，因为短信会将其渲染为字面字符
  • 1600 字符限制——较长的响应在自然边界处（换行符，然后是空格）拆分为多条消息
  • 回声防止——来自你自己 Twilio 号码的消息被忽略以防止循环
  • 手机号脱敏——日志中的手机号经过脱敏以保护隐私

安全​

Webhook 签名验证​

Hermes 通过验证 X-Twilio-Signature 标头（HMAC-SHA1）来验证入站 Webhook 确实来自 Twilio。这可以防止攻击者注入伪造的消息。

SMS_WEBHOOK_URL 是必需的。 将其设置为在 Twilio Console 中配置的公网 URL。没有它，适配器将拒绝启动。

对于没有公网 URL 的本地开发，你可以禁用验证：

# 仅限本地开发——不适合生产环境
SMS_INSECURE_NO_SIGNATURE=true

用户允许列表​

网关默认拒绝所有用户。 配置允许列表：

# 推荐：限制特定手机号
SMS_ALLOWED_USERS=+15559876543,+15551112222

# 或允许所有（不推荐用于有终端访问权限的机器人）
SMS_ALLOW_ALL_USERS=true
注意

短信没有内置加密。除非你了解安全影响，否则不要将短信用于敏感操作。对于敏感用例，首选 Signal 或 Telegram。

故障排除​

消息未到达​

  1. 检查你的 Twilio Webhook URL 是否正确且可公开访问
  2. 验证 TWILIO_ACCOUNT_SID 和 TWILIO_AUTH_TOKEN 是否正确
  3. 在 Twilio Console → Monitor → Logs → Messaging 中检查投递错误
  4. 确保你的手机号在 SMS_ALLOWED_USERS 中（或 SMS_ALLOW_ALL_USERS=true）

回复未发送​

  1. 检查 TWILIO_PHONE_NUMBER 是否正确设置（带 + 的 E.164 格式）
  2. 验证你的 Twilio 账户是否有具备短信功能的号码
  3. 在 Hermes 网关日志中检查 Twilio API 错误

Webhook 端口冲突​

如果 8080 端口已被占用，更改端口：

SMS_WEBHOOK_PORT=3001

在 Twilio Console 中更新 Webhook URL 以匹配。