SMS 设置（Twilio）

Hermes 通过 Twilio API 接入 SMS。用户向你的 Twilio 电话号码发送短信，即可获得 AI 回复——与 Telegram 或 Discord 的对话体验相同，但通过标准短信进行。

共享凭据

SMS gateway（网关）与可选的 telephony skill 共享凭据。如果你已为语音通话或单次 SMS 配置了 Twilio，该 gateway 可直接使用相同的 TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN 和 TWILIO_PHONE_NUMBER。

前提条件

Twilio 账户 — 在 twilio.com 注册（提供免费试用）

具备 SMS 功能的 Twilio 电话号码

可公开访问的服务器 — Twilio 在收到 SMS 时会向你的服务器发送 webhook

aiohttp — pip install 'hermes-agent[sms]'

第一步：获取 Twilio 凭据

前往 Twilio 控制台

从仪表板复制你的 Account SID 和 Auth Token

前往 Phone Numbers → Manage → Active Numbers，记录 E.164 格式的电话号码（例如 +15551234567）

第二步：配置 Hermes

交互式设置（推荐）

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

手动设置

在 ~/.hermes/.env 中添加：

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

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

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

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

第四步：启动 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（参见第三步）。

向你的 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 控制台中的 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`	否	用于 cron 任务／通知投递的电话号码
`SMS_HOME_CHANNEL_NAME`	否	主频道的显示名称（默认：`Home`）

SMS 特有行为

纯文本 — Markdown 会被自动剥离，因为 SMS 会将其渲染为字面字符

1600 字符限制 — 较长的回复会在自然边界处（换行符，其次是空格）拆分为多条消息

防回声 — 来自你自己 Twilio 号码的消息将被忽略，以防止循环

电话号码脱敏 — 日志中的电话号码会被脱敏处理以保护隐私

安全

Webhook 签名验证

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

SMS_WEBHOOK_URL 为必填项。 将其设置为你在 Twilio 控制台中配置的公网 URL，否则适配器将拒绝启动。

如需在本地开发时不使用公网 URL，可禁用验证：

用户白名单

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

警告

SMS 没有内置加密。除非你了解相关安全风险，否则不要通过 SMS 进行敏感操作。对于敏感场景，请优先使用 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 账户是否有支持 SMS 的号码

查看 Hermes gateway 日志中的 Twilio API 错误

Webhook 端口冲突

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

并在 Twilio 控制台中更新 webhook URL 以匹配新端口。

"SMS (Twilio)"

SMS 设置（Twilio）#

前提条件#

第一步：获取 Twilio 凭据#

第二步：配置 Hermes#

交互式设置（推荐）#

手动设置#

第三步：配置 Twilio Webhook#

第四步：启动 Gateway#

环境变量#

SMS 特有行为#

安全#

Webhook 签名验证#

用户白名单#

故障排查#

消息未到达#

回复未发送#

Webhook 端口冲突#

SMS 设置（Twilio）

前提条件

第一步：获取 Twilio 凭据

第二步：配置 Hermes

交互式设置（推荐）

手动设置

第三步：配置 Twilio Webhook

第四步：启动 Gateway

环境变量

SMS 特有行为

安全

Webhook 签名验证

用户白名单

故障排查

消息未到达

回复未发送

Webhook 端口冲突