短信（Twilio）

本指南将指导您如何通过 Twilio 将 Hermes Agent 部署为一个可接收和回复短信的聊天机器人。

注意：此功能需要您的 Hermes Agent 支持通过 HTTP 端点接收消息，并能处理来自 Twilio 的 POST 请求。

1. 准备工作

✅ 前提条件

• 已部署并运行的 Hermes Agent（支持 HTTP API）
• 一个 Twilio 账户
• 一个可用的 Twilio 手机号码（用于接收短信）
• 一个公网可访问的 HTTPS URL（用于接收 Twilio 回调）

---

2. 获取 Twilio 凭证

1. 登录 Twilio Console
2. 导航至 Phone Numbers > Manage > Active Numbers
3. 购买或选择一个已有的短信号码（例如：+1234567890）
4. 记下以下信息：
   • Account SID
   • Auth Token
   • Twilio Phone Number（如 +1234567890）

---

3. 设置 Webhook 回调端点

Hermes Agent 必须提供一个 HTTPS 可访问的端点来接收 Twilio 发送的短信。

示例：使用 Express.js 创建 webhook 服务

// server.js
const express = require('express');
const bodyParser = require('body-parser');
const app = express();

app.use(bodyParser.raw({ type: 'application/x-www-form-urlencoded' }));

app.post('/sms', (req, res) => {
  const { From, Body } = req.body;

  console.log(`收到短信 from ${From}: ${Body}`);

  // 将消息转发给 Hermes Agent
  fetch('https://your-hermes-agent-api.com/api/chat', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sender: From,
      message: Body,
      channel: 'sms',
    }),
  })
  .then(response => response.json())
  .then(data => {
    const reply = data.reply || "抱歉，我无法理解您的消息。";
    
    // 使用 Twilio Send SMS API 回复
    const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
    const authToken = 'your-auth-token';
    const client = require('twilio')(accountSid, authToken);

    client.messages.create({
      body: reply,
      from: '+1234567890', // 您的 Twilio 号码
      to: From,
    }).catch(err => console.error(err));

    res.status(200).send('OK');
  })
  .catch(err => {
    console.error(err);
    res.status(500).send('Error');
  });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook 服务运行在 http://localhost:${PORT}/sms`);
});

⚠️ 请确保：

• 替换 your-hermes-agent-api.com 为实际的 Hermes Agent API 地址。
• 替换 ACXXXXXXXX... 和 your-auth-token 为您的 Twilio 凭据。
• 使用 HTTPS（如通过 Let's Encrypt 或 Cloudflare Tunnel）部署。

---

4. 在 Twilio 中配置 Webhook

1. 进入 Twilio Console
2. 选择您的手机号码 → 点击 "Messaging" 标签页
3. 在 "A Message Comes In" 部分，设置：
   • Message Request URL: https://yourdomain.com/sms
   • Method: POST
4. 保存更改。

现在，当有人向您的 Twilio 号码发送短信时，Twilio 会将消息 POST 到您的 webhook 端点。

---

5. 测试与调试

测试步骤：

1. 向您的 Twilio 号码发送一条短信，例如：“你好，Hermes！”
2. 查看您的服务器日志，确认是否收到请求。
3. 检查 Hermes Agent 是否正确处理了消息并返回响应。
4. 确认 Twilio 是否成功发送回复短信。

调试技巧：

• 使用 Twilio Debugger 查看请求详情。
• 在本地测试时，可使用 ngrok 创建临时 HTTPS 隧道：

  ngrok http 3000

  然后将 https://xxxxx.ngrok.io/sms 作为 webhook URL。

---

6. 安全建议

• 使用 HTTPS 保护通信。
• 验证 Twilio 请求签名（参考文档）。
• 限制允许的来源 IP（Twilio 的 IP 列表可在 Twilio 官方文档 查看）。
• 使用环境变量存储敏感信息（如 TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN）。

---

7. 扩展功能（可选）

功能	实现方式
多语言支持	在 Hermes Agent 中集成多语言模型
消息历史记录	在数据库中存储对话记录
语音转文字	使用 Twilio Voice + Whisper API
用户身份识别	通过 From 号码关联用户档案

---

8. 参考资源

• Twilio SMS API 文档
• Hermes Agent API 文档
• Hermes Agent GitHub 仓库
• OpenRouter / Nous Research 模型集成指南

---

✅ 完成！您现在已经成功将 Hermes Agent 配置为一个可通过短信交互的智能聊天机器人。

如需进一步集成 Telegram、WhatsApp、Discord 等平台，请参阅 MCP 协议文档 或访问 agentskills.io 获取更多模板。

📌 提示：您可以使用 Modal 或 Daytona 快速部署此服务，支持一键部署和自动 HTTPS。

---

---

短信设置（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

从平台列表中选择 短信（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 地址。

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）

---

短信特有行为

• 仅支持纯文本 — Markdown 会自动被移除，因为短信会将其渲染为原始字符
• 1600 字符限制 — 更长的回复会在自然断点处（换行后，再按空格）拆分为多条消息
• 防回环机制 — 来自你自身 Twilio 号码的消息会被忽略，防止循环
• 号码脱敏处理 — 为保护隐私，日志中会隐藏手机号码

---

安全性

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

# 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 以匹配新端口。