SMS 设置（Twilio）

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

共享凭证

SMS 网关与可选的 电话技能 共享凭证。如果你已为语音通话或一次性短信配置了 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. 从仪表板复制你的 Account SID 和 Auth Token
3. 进入 Phone Numbers → Manage → Active Numbers — 注意你的电话号码的 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

# 安全性：仅限特定电话号码（推荐）
SMS_ALLOWED_USERS=+15559876543,+15551112222

# 可选：设置 cron 作业交付的主通道
SMS_HOME_CHANNEL=+15559876543

---

第三步：配置 Twilio Webhook

Twilio 需要知道在收到短信时应发送到何处。在 Twilio 控制台 中：

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。

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

SMS_WEBHOOK_PORT=3000

---

第四步：启动网关

hermes gateway

你应该会看到：

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

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

---

环境变量

变量	是否必需	描述
TWILIO_ACCOUNT_SID	是	Twilio 账户 SID（以 AC 开头）
TWILIO_AUTH_TOKEN	是	Twilio 认证令牌
TWILIO_PHONE_NUMBER	是	你的 Twilio 电话号码（E.164 格式）
SMS_WEBHOOK_PORT	否	Webhook 监听端口（默认：8080）
SMS_ALLOWED_USERS	否	允许聊天的 E.164 格式电话号码，用逗号分隔
SMS_ALLOW_ALL_USERS	否	设置为 true 以允许所有人（不推荐）
SMS_HOME_CHANNEL	否	定时任务 / 通知投递的电话号码
SMS_HOME_CHANNEL_NAME	否	主频道的显示名称（默认：Home）

---

SMS 特定行为

• 仅支持纯文本 —— Markdown 会自动被移除，因为 SMS 会将其渲染为原始字符
• 1600 字符限制 —— 更长的回复会在自然边界（换行符，然后是空格）处拆分为多条消息
• 防止回声 —— 来自你自己的 Twilio 号码的消息会被忽略，以防止循环
• 电话号码脱敏 —— 为保护隐私，日志中会脱敏电话号码

---

安全性

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

# 建议：限制特定电话号码
SMS_ALLOWED_USERS=+15559876543,+15551112222

# 或者允许全部（对于具有终端访问权限的机器人，建议使用 NOT）
SMS_ALLOW_ALL_USERS=true

注意

SMS 无内置加密。除非你了解安全影响，否则不要用于敏感操作。对于敏感场景，建议使用 Signal 或 Telegram。

---

故障排除

消息未到达

1. 检查你的 Twilio Webhook URL 是否正确且公网可访问
2. 确认 TWILIO_ACCOUNT_SID 和 TWILIO_AUTH_TOKEN 是否正确
3. 在 Twilio 控制台 → 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 控制台中更新 Webhook URL 以匹配新端口。