본문으로 건너뛰기

SMS 설정 (Twilio)

Hermes는 Twilio API를 통해 SMS에 연결됩니다. 사용자가 Twilio 전화번호로 문자를 보내면 AI 응답을 받습니다 — Telegram이나 Discord와 동일한 대화 경험이지만 표준 문자 메시지로 이루어집니다.

Shared Credentials

SMS 게이트웨이는 선택적 telephony skill과 자격 증명을 공유합니다. 음성 통화나 일회성 SMS용으로 이미 Twilio를 설정했다면, 게이트웨이는 동일한 TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER로 작동합니다.

사전 요구사항​

  • Twilio 계정 — twilio.com에서 가입 (무료 평가판 제공)
  • SMS 기능이 있는 Twilio 전화번호
  • 공개적으로 접근 가능한 서버 — SMS가 도착하면 Twilio가 서버로 webhook을 전송합니다
  • aiohttp — pip install 'hermes-agent[sms]'

1단계: Twilio 자격 증명 받기​

  1. Twilio Console로 이동
  2. 대시보드에서 Account SID와 Auth Token을 복사
  3. Phone Numbers → Manage → Active Numbers로 이동 — E.164 형식의 전화번호 확인 (예: +15551234567)

2단계: Hermes 설정​

hermes gateway setup

플랫폼 목록에서 **SMS (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

3단계: 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
Exposing Your Webhook

Hermes를 로컬에서 실행 중이라면 터널을 사용해 webhook을 노출:

# Using cloudflared
cloudflared tunnel --url http://localhost:8080

# Using ngrok
ngrok http 8080

생성된 공개 URL을 Twilio webhook으로 설정합니다.

SMS_WEBHOOK_URL를 Twilio에 설정한 URL과 동일하게 설정하세요. Twilio 서명 검증에 필요합니다 — 이 값 없이는 adapter가 시작되지 않습니다:

# Must match the webhook URL in your Twilio Console
SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twilio

Webhook 포트는 기본값이 8080입니다. 변경하려면:

SMS_WEBHOOK_PORT=3000

4단계: 게이트웨이 시작​

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로 설정하세요 (3단계 참조).

Twilio 번호로 문자 전송 — Hermes가 SMS로 응답합니다.

---

## 환경 변수 \{#environment-variables}

| 변수 | 필수 | 설명 |
|----------|----------|-------------|
| `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` | No | Webhook listener 포트 (기본값: `8080`) |
| `SMS_WEBHOOK_HOST` | No | Webhook 바인드 주소 (기본값: `0.0.0.0`) |
| `SMS_INSECURE_NO_SIGNATURE` | No | 서명 검증 비활성화하려면 `true`로 설정 (로컬 개발 전용 — **프로덕션 금지**) |
| `SMS_ALLOWED_USERS` | No | 채팅 허용된 E.164 전화번호 (쉼표 구분) |
| `SMS_ALLOW_ALL_USERS` | No | 모두 허용하려면 `true`로 설정 (권장하지 않음) |
| `SMS_HOME_CHANNEL` | No | Cron 작업 / 알림 전송용 전화번호 |
| `SMS_HOME_CHANNEL_NAME` | No | 홈 채널 표시 이름 (기본값: `Home`) |

---

## SMS 고유 동작 \{#sms-specific-behavior}

- **텍스트 전용** — SMS는 Markdown을 문자 그대로 표시하므로 자동으로 제거됩니다
- **1600자 제한** — 긴 응답은 자연스러운 경계(개행, 그다음 공백)에서 여러 메시지로 분할됩니다
- **에코 방지** — 루프 방지를 위해 자체 Twilio 번호에서 온 메시지는 무시됩니다
- **전화번호 마스킹** — 개인정보 보호를 위해 로그에서 전화번호가 마스킹됩니다

---

## 보안 \{#security}

### Webhook 서명 검증 \{#webhook-signature-validation}

Hermes는 `X-Twilio-Signature` 헤더(HMAC-SHA1)를 검증하여 인바운드 webhook이 실제로 Twilio에서 발생했는지 확인합니다. 공격자가 위조된 메시지를 주입하는 것을 방지합니다.

**`SMS_WEBHOOK_URL`는 필수입니다.** Twilio Console에 설정된 공개 URL로 설정하세요. 이 값 없이는 adapter가 시작되지 않습니다.

공개 URL 없이 로컬 개발하는 경우, 검증을 비활성화할 수 있습니다:

```bash
# Local dev only — NOT for production
SMS_INSECURE_NO_SIGNATURE=true

사용자 허용 목록​

게이트웨이는 기본적으로 모든 사용자를 거부합니다. 허용 목록을 설정:

# 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
경고

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. Twilio API 오류는 Hermes 게이트웨이 로그 확인

Webhook 포트 충돌​

포트 8080이 이미 사용 중이면 변경:

SMS_WEBHOOK_PORT=3001

일치하도록 Twilio Console의 webhook URL을 업데이트합니다.