자체 호스팅 AI 에이전트에 수신 전화 기능 부여하기 (OpenClaw + Twilio)

Code and Trust 블로그에서 교차 게시되었습니다. 원문: codeandtrust.com/blog/openclaw-phone-calls

자체 호스팅(self-hosted)하는 OpenClaw 에이전트는 이메일에 답장하고, Slack 메시지를 보내며, 캘린더를 조회할 수 있습니다. 하지만 누군가 비즈니스 번호로 전화를 걸면 에이전트는 어디에도 없습니다. 이 가이드는 50줄의 Twilio 웹훅(webhook)과 clawcall (MIT)이라는 오픈 소스 브리지(bridge)를 사용하여 이 문제를 해결하는 방법을 보여줍니다.

문제점: 실시간 음성 모드(realtime voice mode)는 게이트웨이 도구를 사용할 수 없음

OpenClaw의 voice-call 플러그인에는 1초 미만의 지연 시간(latency)과 끼어들기(barge-in) 지원을 통해 뛰어난 대화 느낌을 제공하는 realtime 모드가 있습니다. 하지만 최근까지(#71272), 실시간 모드는 게이트웨이의 도구 레지스트리(tool registry)를 완전히 우회하는 격리된 오디오 세션으로 실행되었습니다. 에이전트에게 캘린더를 확인하거나 메시지를 보내달라고 요청하면, 에이전트는 정중하게 거절할 것입니다.

clawcall은 다른 접근 방식을 취합니다: 오디오를 게이트웨이의 일반적인 에이전트 턴(agent turn) 파이프라인을 통해 라우팅합니다.

수신 전화 → Twilio → STT (음성-텍스트 변환) → chat.send() → 에이전트 (모든 도구 액세스 권한) → TTS (텍스트-음성 변환) → Twilio → 발신자

에이전트 턴은 게이트웨이에 보내는 표준 chat.send 메시지이므로, 모든 스킬(skill), 도구(tool), 메모리 조회(memory lookup)가 Telegram이나 Discord 채널에서 작동하는 것과 정확히 동일하게 작동합니다. 유일한 차이점은 입력이 전사된 오디오(transcribed audio)로 도착하고, 출력이 합성된 음성(synthesized speech)으로 나간다는 점입니다.

필요한 사항

• 실행 중인 OpenClaw 게이트웨이 (Chat API가 포함된 모든 버전)
• 전화번호가 포함된 Twilio 계정
• Node.js 18+ (또는 Bun)
• 로컬 개발을 위한 ngrok 또는 공개 URL

5분 만에 설정하기

1. clawcall 클론하기

git clone https://github.com/CODEANDTRUST/clawcall
cd clawcall
npm install

2. 환경 설정하기

OPENCLAW_GATEWAY_URL=http://localhost:4000
OPENCLAW_API_KEY=your-key
TWILIO_ACCOUNT_SID=ACxxxxxxx
...

3. ngrok으로 노출하기

ngrok http 3000

https://xxxx.ngrok.io URL을 복사합니다.

4. Twilio 연결하기

Twilio 콘솔 → Phone Numbers → 본인의 번호 → Voice Configuration에서 다음을 설정합니다:

• Incoming call webhook: https://xxxx.ngrok.io/call/incoming (HTTP POST)

5. 브리지(bridge) 시작하기

npm start

Twilio 번호로 전화를 겁니다. 브리지가 전화를 받고, Deepgram (또는 Whisper)을 사용하여 음성을 텍스트로 변환(transcribe)한 뒤, 이를 채팅 메시지로서 OpenClaw 게이트웨이(gateway)로 전송합니다. 그 후 TTS(Text-to-Speech) 제공자를 통해 텍스트 응답을 스트리밍하고 오디오를 다시 재생합니다. 에이전트에게 캘린더를 확인하거나 메모리를 검색하도록 요청하면 실제로 수행합니다. 왜냐하면 이것은 실제 게이트웨이 턴(turn)이기 때문입니다.

도구 액세스(tool-access) 문제가 해결되는 방식

핵심은 chat.send가 사이드카(sidecar) 실시간 세션이 아니라 전체 에이전트 런타임(agent runtime)을 통해 전달된다는 점입니다. 게이트웨이는 텍스트 메시지와 정확히 동일하게 턴을 스케줄링하고, 도구 호출(tool calls)을 실행하며, 결과를 기다린 후 응답을 반환합니다. clawcall은 단지 이 과정을 오디오 I/O로 감싸는 역할을 할 뿐입니다.

// 브리지의 핵심 (단순화됨)
app.post('/call/incoming', async (req, res) => {
  const transcript = await stt(req.body.audioUrl);          // STT (Speech-to-Text)
...

프로덕션 체크리스트

• ngrok을 실제 공개 URL로 전환 (Railway, Render, Fly.io — 모두 가능)
• X-Twilio-Signature 검증 추가 (twilio.validateRequest)
• 특정 에이전트 페르소나로 전화를 라우팅하기 위해 OPENCLAW_AGENT_ID 설정
• 대화 메모리를 통화 범위로 제한하고 싶다면 통화당 세션 키(per-call session key) 추가

향후 단계

• GitHub의 clawcall — MIT 라이선스, PR 환영
• 아키텍처 다이어그램이 포함된 전체 가이드
• 관련 항목: openclaw/openclaw#71262 — 이 접근 방식이 해결하고자 하는 업스트림(upstream) 이슈

Built by Code and Trust — 기업을 위한 AI 에이전트 인프라.