SMS（Twilio）

SMS 设置（Twilio）

Hermes 通过 Twilio API 连接到 SMS。人们向您的 Twilio 电话号码发送短信，并收到 AI 回复——与 Telegram 或 Discord 相同的对话体验，但通过标准短信进行。

:::info 共享凭证 SMS 网关与可选的电话技能共享凭证。如果您已经为语音通话或单次 SMS 设置了 Twilio，网关可以使用相同的 TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN 和 TWILIO_PHONE_NUMBER。 :::

---

前提条件

• Twilio 账户 — 在 twilio.com 注册（提供免费试用）
• 一个支持 SMS 功能的 Twilio 电话号码
• 一个可公开访问的服务器 — Twilio 在 SMS 到达时向您的服务器发送 webhook
• aiohttp — pip install 'hermes-agent[sms]'

---

第一步：获取您的 Twilio 凭证

1. 前往 Twilio Console
2. 从仪表板复制您的 Account SID 和 Auth Token
3. 进入 Phone Numbers → Manage → Active Numbers — 记下您使用 E.164 格式的电话号码（例如 +155****4567）

---

第二步：配置 Hermes

交互式设置（推荐）

hermes gateway setup

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

手动设置

添加到 ~/.hermes/.env：

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+155****4567
 
# 安全：限制到特定电话号码（推荐）
SMS_ALLOWED_USERS=+155****6543,+155****2222
 
# 可选：设置用于定时任务投递的家聊
SMS_HOME_CHANNEL=+155****6543

---

第三步：配置 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

:::tip 暴露您的 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

---

第四步：启动网关

hermes gateway

您应该看到：

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

如果您看到 Refusing to start: SMS_WEBHOOK_URL is required，请将 SMS_WEBHOOK_URL 设置为在 Twilio Console 中配置的公共 URL（参见第三步）。

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

---

环境变量

变量	必填	描述
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）

---

SMS 特定行为

• 仅纯文本 — Markdown 会被自动去除，因为 SMS 将其渲染为原义字符
• 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=+155****6543,+155****2222
 
# 或允许所有人（对于具有终端访问权限的机器人不推荐）
SMS_ALLOW_ALL_USERS=true

:::warning SMS 没有内置加密。除非您了解安全影响，否则不要将 SMS 用于敏感操作。对于敏感用例，优选 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 账户有支持 SMS 的号码
3. 检查 Hermes 网关日志中的 Twilio API 错误

Webhook 端口冲突

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

SMS_WEBHOOK_PORT=3001

更新 Twilio Console 中的 webhook URL 以匹配。