Skip to main content

短信设置（Twilio）

Hermes 通过 Twilio API 连接短信服务。用户发送短信至您的 Twilio 号码后，将收到 AI 的回复——与 Telegram 或 Discord 相同的对话体验，但通过标准短信实现。

共享凭证

短信网关与可选的 电话技能 共享凭证。如果您已为语音通话或一次性短信配置了 Twilio，则网关可使用相同的 TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN 和 TWILIO_PHONE_NUMBER。

前提条件​

  • Twilio 账号 — 在 twilio.com 注册（提供免费试用）
  • 一个具备短信功能的 Twilio 号码
  • 一台公网可访问的服务器 — Twilio 在收到短信时会向您的服务器发送 webhook
  • aiohttp — pip install 'hermes-agent[sms]'

第一步：获取您的 Twilio 凭证​

  1. 访问 Twilio 控制台
  2. 从仪表板复制您的 账户 SID 和 认证令牌
  3. 进入 电话号码 → 管理 → 激活号码 — 记下您的号码（E.164 格式，例如 +15551234567）

第二步：配置 Hermes​

交互式设置（推荐）​

hermes gateway setup

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

手动设置​

将以下内容添加至 ~/.hermes/.env：

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+15551234567

# Security: restrict to specific phone numbers (recommended)
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Optional: set a home channel for cron job delivery
SMS_HOME_CHANNEL=+15559876543

第三步：配置 Twilio Webhook​

Twilio 需要知道如何接收传入消息。请在 Twilio 控制台 中进行如下操作：

  1. 进入 电话号码 → 管理 → 激活号码
  2. 点击您的号码
  3. 在 消息 → 有消息到达时 设置：
    • Webhook: https://your-server:8080/webhooks/twilio
    • HTTP 方法: POST
暴露您的 Webhook

如果您本地运行 Hermes，请使用隧道工具暴露 webhook 地址：

# Using cloudflared
cloudflared tunnel --url http://localhost:8080

# Using ngrok
ngrok http 8080

将生成的公共 URL 设置为 Twilio 的 webhook 地址。

将 SMS_WEBHOOK_URL 设置为与 Twilio 控制台中配置的相同 URL。 这是 Twilio 签名验证所必需的——若未设置，适配器将拒绝启动：

# Must match the webhook URL in your Twilio Console
SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twilio

Webhook 端口默认为 8080。如需更改，请使用：

SMS_WEBHOOK_PORT=3000

第四步：启动网关​

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 控制台中配置的公网 URL（参见第 3 步）。

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

环境变量​

变量是否必需描述
TWILIO_ACCOUNT_SID是Twilio 账户 SID（以 AC 开头）
TWILIO_AUTH_TOKEN是Twilio 认证令牌（也用于 webhook 签名验证）
TWILIO_PHONE_NUMBER是您的 Twilio 号码（E.164 格式）
SMS_WEBHOOK_URL是用于 Twilio 签名验证的公网 URL —— 必须与 Twilio 控制台中的 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）

短信特有行为​

  • 仅支持纯文本 — 因为 SMS 不支持 Markdown，系统会自动移除所有格式符号
  • 最大 1600 字符限制 — 超长回复会在自然边界处（换行符优先，其次为空格）拆分为多条短信
  • 防回环机制 — 来自您自己 Twilio 号码的消息会被忽略，防止消息循环
  • 号码脱敏处理 — 日志中会隐藏手机号码以保护隐私

安全性​

Webhook 签名验证​

Hermes 通过验证 X-Twilio-Signature 头部（HMAC-SHA1）来确认传入 webhook 确实来自 Twilio，防止攻击者伪造消息注入。

SMS_WEBHOOK_URL 是必需的。 请将其设置为 Twilio 控制台中配置的公网 URL。若未设置，适配器将拒绝启动。

在本地开发且无公网 URL 时，可临时禁用验证：

# Local dev only — NOT for production
SMS_INSECURE_NO_SIGNATURE=true

用户白名单机制​

网关默认拒绝所有用户。 请配置白名单：

# Recommended: restrict to specific phone numbers
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Or allow all (NOT recommended for bots with terminal access)
SMS_ALLOW_ALL_USERS=true
warning

短信本身不提供加密。除非您了解相关安全风险，否则不要用于敏感操作。对于敏感场景，建议使用 Signal 或 Telegram。

故障排查​

消息未送达​

  1. 检查您的 Twilio webhook URL 是否正确且公网可达
  2. 确认 TWILIO_ACCOUNT_SID 和 TWILIO_AUTH_TOKEN 配置无误
  3. 查看 Twilio 控制台 → 监控 → 日志 → 短信 中是否有投递错误
  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 控制台中的 webhook URL 以匹配新端口。