hermes教程-SMS (Twilio) - 字节笔记本

SMS 设置 (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]'

步骤 1：获取 Twilio 凭据

前往 Twilio 控制台
从仪表盘复制你的 Account SID 和 Auth Token
前往 Phone Numbers → Manage → Active Numbers — 记下你的电话号码（E.164 格式，例如 +15551234567）

步骤 2：配置 Hermes

交互式设置（推荐）

bash

hermes gateway setup

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

手动设置

添加到 ~/.hermes/.env：

bash

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 控制台中：

前往 Phone Numbers → Manage → Active Numbers
点击你的电话号码
在 Messaging → A MESSAGE COMES IN 下，设置：
- Webhook：https://your-server:8080/webhooks/twilio
- HTTP Method：POST

提示——暴露你的 Webhook

如果你在本地运行 Hermes，请使用隧道暴露 Webhook：
bash
# 使用 cloudflared
cloudflared tunnel --url http://localhost:8080

# 使用 ngrok
ngrok http 8080
将生成的公网 URL 设置为你的 Twilio Webhook。

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

bash

## 必须与 Twilio 控制台中的 Webhook URL 一致
SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twilio

Webhook 端口默认为 8080。可通过以下方式覆盖：

bash

SMS_WEBHOOK_PORT=3000

步骤 4：启动网关

bash

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 控制台中配置的公网 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 绑定地址（默认：`127.0.0.1`）
`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 控制台中配置的公网 URL。适配器在未设置时将拒绝启动。

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

bash

## 仅限本地开发——不可用于生产环境
SMS_INSECURE_NO_SIGNATURE=true

用户白名单

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

bash

## 推荐：限制为特定电话号码
SMS_ALLOWED_USERS=+15559876543,+15551112222
## 或允许所有人（不推荐用于具有终端访问权限的机器人）
SMS_ALLOW_ALL_USERS=true

警告

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

故障排除

消息未到达

检查你的 Twilio Webhook URL 是否正确且可公开访问
验证 TWILIO_ACCOUNT_SID 和 TWILIO_AUTH_TOKEN 是否正确
检查 Twilio 控制台 → Monitor → Logs → Messaging 中的投递错误
确保你的电话号码在 SMS_ALLOWED_USERS 中（或设置了 SMS_ALLOW_ALL_USERS=true）

回复未发送

检查 TWILIO_PHONE_NUMBER 是否正确设置（E.164 格式，带 +）
验证你的 Twilio 账户是否拥有支持短信的号码
检查 Hermes 网关日志中的 Twilio API 错误

Webhook 端口冲突

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

bash

SMS_WEBHOOK_PORT=3001

更新 Twilio 控制台中的 Webhook URL 以匹配。