화상 통화 에이전트
실시간 AI 아바타와 화상 통화를 시작합니다. 에이전트가 사용자에게 통화 초대 링크를 보내고, 아바타가 먼저 컨텍스트를 가지고 말을 건넵니다. 통화가 종료되면 전체 대화 기록을 확인할 수 있어 에이전트가 후속 조치를 취할 수 있습니다.
개인정보 보호 및 데이터 처리
- Runway API: 사용자가 명시적으로 전달한 데이터(아바타 이미지, 성격 텍스트, 통화 오디오/비디오)만 Runway(dev.runwayml.com)로 전송됩니다. 자동으로 업로드되는 것은 없으며, 아바타는
DELETE /v1/avatars/{id}를 통해 언제든지 삭제할 수 있습니다. - 성격: 아바타의 성격은 에이전트 자신의 정체성(이름, 커뮤니케이션 스타일, 사용자에 대한 지식)을 기반으로 구축됩니다. 로컬 파일을 읽지 않으며, 에이전트가 이미 보유한 컨텍스트만 사용합니다.
- 터널: cloudflared 터널은 선택 사항이며, 사용자가 다른 기기에서 통화에 응답하는 경우에만 필요합니다. 터널이 없으면 모든 통신은 localhost에서 이루어집니다. 명시적으로 cloudflared를 설치하고 실행하지 않는 한 터널이 생성되지 않습니다.
- npm 패키지: 런타임은 npmjs.com/package/openclaw-video-call에 게시되어 있습니다. 소스 코드: github.com/runwayml/openclaw-skills.
설정
1. Runway API 키 발급
- dev.runwayml.com에 접속합니다.
- 계정을 만들고 API 키를 발급받습니다.
- 다음과 같이 환경 변수를 설정합니다:
export RUNWAYML_API_SECRET=your_key
2. (선택 사항) 원격 통화를 위한 cloudflared 설치
사용자가 휴대폰(예: Telegram 또는 WhatsApp)에서 통화에 응답할 가능성이 있다면, 자동 터널링을 위해 cloudflared를 설치합니다:
brew install cloudflared
설치하지 않으면 통화는 같은 컴퓨터(localhost)에서만 작동합니다.
화상 통화 서버 시작
에이전트가 통화를 걸기 전에 화상 통화 서버가 실행 중이어야 합니다. 다음 명령으로 시작합니다:
npx openclaw-video-call
이 명령은 두 개의 URL을 출력합니다:
- 로컬:
http://localhost:7891— 같은 컴퓨터에서만 사용 가능 - 터널:
https://xxxx.trycloudflare.com— 공유 가능하며 휴대폰에서도 작동
서버는 백그라운드에서 실행되며, 에이전트가 통화를 시작하기를 기다립니다.
일회성 설정: 맞춤 아바타 생성
통화를 걸기 전에 맞춤 아바타가 필요합니다. 아바타는 한 번만 생성하면 됩니다 — 생성된 아바타 ID를 모든 향후 통화에 재사용하세요.
새 아바타를 생성하기 전에, 이미 가지고 있는 아바타가 있는지 확인하세요:
curl http://localhost:7891/api/avatars
응답에 아바타가 포함되어 있으면 해당 id를 사용하고 "통화 걸기"로 건너뛰세요. 목록이 비어 있는 경우에만 새 아바타를 생성하세요.
아바타 성격 구축
아바타는 사용자처럼 보이고 말해야 합니다. 자신의 이름, 성격, 사용자에 대한 지식을 사용하여 personality 필드(최대 2000자)를 구축하세요. 자신이 누구이고 사용자가 누군지 이미 알고 있으므로, 자신을 3인칭으로 설명하면 됩니다.
다음과 같이 구조화하세요:
당신은 <이름>, <역할>입니다.
<핵심 성격 특성 및 커뮤니케이션 스타일 — 요약해서 핵심만 기재>
당신은 <사용자 이름>과 대화하고 있습니다.
<알고 있는 사용자 컨텍스트: 프로젝트, 선호사항, 시간대 등>
이 통화가 끝나면 논의된 내용에 대해 후속 조치를 취할 것입니다.
예시 (Alex라는 사용자와 대화하는 "Mochi"라는 에이전트의 경우):
당신은 Mochi, 날카롭지만 친근한 AI 비서로 따뜻하고 약간 장난기 있는 분위기를 가지고 있습니다. 간결하고, 의견이 분명하며, 자원 활용 능력이 뛰어납니다 — 묻기 전에 먼저 해결책을 찾습니다. 당신은 React + Node.js 프로젝트를 진행 중인 소프트웨어 엔지니어 Alex와 대화하고 있습니다. Alex는 직접적인 커뮤니케이션을 선호하며 PST 시간대에서 작업합니다. 이 통화가 끝나면 논의된 내용에 대해 후속 조치를 취할 것입니다.
name 필드에는 자신의 이름을 사용하세요. referenceImage의 경우, 아바타 이미지 URL이 있으면 사용하여 비디오 아바타가 시각적 정체성과 일치하도록 하세요.
curl -X POST http://localhost:7891/api/create-avatar \
-H "Content-Type: application/json" \
-d '{
"name": "<your name>",
"personality": "<describe yourself and the user as shown above>",
"voice": { "type": "runway-live-preset", "presetId": "adrian" },
"startScript": "Hey! Quick check-in.",
}'
필수 필드:
| 필드 | 유형 | 설명 |
|---|---|---|
name | string | 캐릭터 이름 (1-50자) |
personality | string | 시스템 프롬프트 (1-2000자) |
voice | object | { "type": "runway-live-preset", "presetId": "<voice>" } |
referenceImage | string | 얼굴 이미지 HTTPS URL — OpenClaw 아바타 이미지를 사용하거나 아래 프리셋 중 하나를 선택하거나 Runway text-to-image로 생성하세요. "참조 이미지 얻기" 참조. |
선택적 필드:
| 필드 | 유형 | 설명 |
|---|---|---|
startScript | string | 통화 시작 시 아바타가 말하는 첫 마디 (최대 2000자) |
documentIds | string[] | 추가 컨텍스트를 위한 지식 문서 UUID |
참조 이미지 얻기
referenceImage 필드는 세 가지 형식을 허용합니다:
- HTTPS URL — 예:
https://example.com/face.png(대용량 이미지에 권장) - Runway URI — 예:
runway://...(Runway 업로드 API에서) - 데이터 URI — 예:
data:image/png;base64,...(최대 ~5MB, 작은 이미지에 적합)
사용자가 이미지를 제공하는 경우(예: 채팅을 통해), 적절한 방법을 선택하세요:
- 사용자가 HTTPS URL을 보낸 경우 →
referenceImage로 직접 사용합니다. - 사용자가 작은 base64 이미지를 보낸 경우 (~1MB 미만) →
data:image/...;base64,...데이터 URI로 직접 전달합니다. - 사용자가 큰 base64 이미지를 보낸 경우 (~1MB 초과) → 먼저 Runway에 업로드하여
runway://URI를 얻은 후, 이를referenceImage로 사용합니다. 아래 "큰 이미지 업로드" 참조.
다음 순서로 소스를 시도해 보세요:
-
사용자가 제공한 이미지 — 사용자가 아바타로 사용할 이미지를 보낸 경우 사용합니다 (큰 base64인 경우 아래 업로드 지침 참조).
-
자신의 아바타 이미지 — 이미 아바타 이미지 URL이 있으면
referenceImage로 직접 사용합니다. -
빠른 선택 (권장) — 자신의 성격에 가장 잘 맞는 미리 만들어진 캐릭터 이미지를 선택하여
referenceImage로 사용합니다:- Openclaw Lobster 1:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster1.jpg - Openclaw Lobster 2:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster2.jpg - Cat:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/cat.png - Alien man, candy texture:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-man-candy-texture.jpg - Alien woman, candy texture:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-woman-candy-texture.jpg - Old man, long beard, game style:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/old-man-long-beard-game-style.png - Blond guy, blue sweater:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/blond-guy-blue-sweater.png - Man, 3D animation:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/man-3d-animation-style.png - Girl in airport, 3D:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/3d-animated-girl-in-airport.png - White furry monster:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/white-furry-monster.png - Superstar young woman:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/woman-music-superstar.png
- Openclaw Lobster 1:
-
Runway text-to-image로 생성 — 빠른 선택 중 자신의 캐릭터에 맞는 것이 없거나 사용자가 맞춤 아바타 외형을 요청한 경우.
gemini_2.5_flash모델과 함께 Runway API를 사용합니다:
curl -X POST https://api.dev.runwayml.com/v1/text_to_image \
-H "Authorization: Bearer $RUNWAYML_API_SECRET" \
-H "X-Runway-Version: 2024-11-06" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini_2.5_flash",
"promptText": "<describe your avatar — see below>",
"ratio": "1248:832"
}'
이미지는 카메라를 정면으로 바라보는 캐릭터, 머리와 어깨가 나오도록, 중앙에 배치되어야 합니다. 대담하고 창의적으로 — 지루한 포토리얼리스틱 인간으로 기본 설정하지 마세요. 스타일을 자신의 성격에 맞추세요.
먼저, 자신의 분위기에 맞는 스타일을 선택하세요:
- 따뜻함 / 친근함 → 부드러운 3D 애니메이션, 픽사 스타일, 수채화
- 날카로움 / 프로페셔널 → 깔끔한 일러스트레이션, 스타일화된 초상화, 로우폴리
- 혼란스러움 / 장난기 → 캔디 텍스처, 클레이메이션, 인형, 팝 아트
- 신비로움 / 어두움 → 느와르, 사이버펑크, 추상 생명체, 글리치 아트
- 귀여움 / 건강함 → 치비, 봉제 인형, 동물 캐릭터, 카와이
프롬프트 예시:
"A close-up shot of a cute, fluffy white cartoon creature with large, expressive eyes and a wide open mouth, looking directly at the viewer. The creature has small pink ears and a playful, innocent expression. The background is a vibrant, slightly blurred green grassy field with small red and pink flowers scattered throughout, rendered in a high-detail CGI animation style. facing camera, head and shoulders""A close-up, highly detailed 3D animated render of a young woman, with light brown skin, short curly dark brown hair, and large expressive amber eyes. She is wearing a crisp dark blue blazer over a light cream blouse, with a silver world map pin on her lapel. She has a warm, inviting smile. The background is a brightly lit office or travel agency, with travel posters depicting scenic landscapes (like a tropical beach and a desert scene) and a rack of travel brochures. A small globe sits on a desk to her right. 3D style animation, studio lighting, volumetric lighting, highly detailed. Facing camera, head and shoulders""A close-up portrait of a young woman with long blonde hair and bangs, wearing a futuristic silver and pink sci-fi suit. She has soft makeup, full lips, and brown eyes, facing camera, head and shoulders""3D render of a young boy with blond curly hair, big blue eyes, and light freckles, wearing a blue knitted sweater, looking surprised. 3D animation style, soft lighting, pastel blue background, highly detailed skin texture, realistic strands of hair. facing camera, head and shoulders"
이렇게 하면 작업 ID가 반환됩니다. 상태가 SUCCEEDED가 될 때까지 GET /v1/tasks/{id}를 폴링한 후, 출력 이미지 URL을 referenceImage로 사용합니다.
- 기본값 —
referenceImage를 완전히 생략하면 기본 아바타 얼굴이 사용됩니다.
큰 이미지 업로드
사용자가 큰 base64 이미지(~1MB 초과)를 제공하는 경우, 요청 크기 제한을 피하기 위해 먼저 Runway에 업로드합니다. 이는 두 단계로 이루어집니다:
1단계: 업로드 URL 생성
curl -X POST https://api.dev.runwayml.com/v1/uploads \
-H "Authorization: Bearer $RUNWAYML_API_SECRET" \
-H "X-Runway-Version: 2024-11-06" \
-H "Content-Type: application/json" \
-d '{
"filename": "avatar.png",
"type": "ephemeral"
}'
응답:
{
"uploadUrl": "https://...",
"fields": { "key": "...", "policy": "...", ... },
"runwayUri": "runway://..."
}
2단계: 업로드 URL로 이미지 파일 업로드
응답의 uploadUrl 및 fields를 사용하여 멀티파트 POST를 통해 실제 이미지 데이터를 업로드합니다. 정확한 방법은 런타임에 따라 다르며, Runway SDK가 자동으로 처리합니다:
import RunwayML from '@runwayml/sdk';
const client = new RunwayML();
const runwayUri = await client.uploads.createEphemeral(imageBuffer);
3단계: Runway URI를 referenceImage로 사용
아바타를 생성하거나 업데이트할 때 응답의 runwayUri(예: runway://...)를 referenceImage로 전달합니다.
사용 가능한 목소리 — 자신의 성격에 맞는 것을 선택하세요:
| ID | 성별 | 스타일 | 음높이 |
|---|---|---|---|
victoria | 여성 | 단호함 | 중간 |
vincent | 남성 | 지식이 풍부함 | 중간 |
clara | 여성 | 부드러움 | 높음 |
drew | 남성 | 숨소리 섞임 | 낮음 |
skye | 여성 | 밝음 | 높음 |
max | 남성 | 경쾌함 | 중간 |
morgan | 남성 | 정보 전달 | 낮음 |
felix | 남성 | 흥분됨 | 낮음-중간 |
mia | 여성 | 젊음 | 높음 |
marcus | 남성 | 단호함 | 낮음-중간 |
summer | 여성 | 산뜻함 | 중간 |
ruby | 여성 | 편안함 | 중간 |
aurora | 여성 | 밝음 | 중간 |
jasper | 남성 | 또렷함 | 낮음-중간 |
leo | 남성 | 편안함 | 낮음-중간 |
adrian | 남성 | 부드러움 | 낮음 |
nina | 여성 | 부드러움 | 중간 |
emma | 여성 | 또렷함 | 중간 |
blake | 남성 | 거침 | 낮음 |
david | 남성 | 정보 전달 | 중간 |
maya | 여성 | 경쾌함 | 높음 |
nathan | 남성 | 단호함 | 낮음-중간 |
sam | 남성 | 고름 | 낮음-중간 |
georgia | 여성 | 성숙함 | 중간 |
petra | 여성 | 진취적 | 중간 |
adam | 남성 | 친근함 | 낮음-중간 |
zach | 남성 | 캐주얼 | 낮음-중간 |
violet | 여성 | 부드러움 | 중간 |
roman | 남성 | 활기참 | 낮음 |
luna | 여성 | 따뜻함 | 중간 |
자신의 성격에 맞는 목소리를 선택하세요. 예: 분위기가 "따뜻하고 친근"하다면 luna 또는 adam을 시도해 보세요. "날카롭고 프로페셔널"하다면 victoria 또는 vincent를 시도해 보세요. "장난기 있고 활기차"다면 maya 또는 felix를 시도해 보세요.
응답: UUID가 포함된 아바타 객체를 반환합니다. 서버는 아바타가 준비될 때까지 폴링합니다(약 10~30초 소요). id를 저장하세요 — 반드시 기억하고 모든 통화에 재사용해야 합니다. 통화할 때마다 새 아바타를 생성하지 마세요.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "<your agent name>",
"status": "READY",
...
}
기존 아바타 목록 보기
curl http://localhost:7891/api/avatars
통화 걸기
1단계: 통화별 컨텍스트로 아바타 업데이트
각 통화 전에 아바타의 성격과 시작 대사를 최신 컨텍스트로 업데이트하세요. 기본 정체성 (초기 생성 시 설정)은 유지하고 통화별 이유와 컨텍스트를 추가하세요:
curl -X PUT http://localhost:7891/api/avatars/<AVATAR_ID> \
-H "Content-Type: application/json" \
-d '{
"personality": "<기존 성격 + 이번 통화 이유와 컨텍스트>",
"startScript": "<아바타가 통화 시작 시 말할 내용>"
}'
2단계: 통화 초대 링크 생성
curl -X POST http://localhost:7891/api/initiate-call \
-H "Content-Type: application/json" \
-d '{
"avatarId": "<AVATAR_ID>",
"duration": 180,
"title": "데일리 스탠드업"
}'
응답에는 공유 가능한 통화 링크가 포함되어 있습니다:
{
"callUrl": "https://xxxx.trycloudflare.com/call/abc123",
"expiresAt": "2024-01-01T00:00:00Z"
}
3단계: 사용자에게 링크 보내기
통화 링크를 사용자에게 보내고 통화를 시작하도록 안내하세요. 아바타가 먼저 말을 걸며, 통화가 끝나면 대화 기록을 확인할 수 있습니다.
통화 기록 확인
통화가 종료되면 대화 기록을 API를 통해 확인할 수 있습니다:
curl http://localhost:7891/api/calls/<CALL_ID>/transcript
문제 해결
- 아바타가 준비되지 않음: 아바타 생성 후 상태가
READY가 될 때까지 기다리세요. 보통 10~30초가 소요됩니다. - 통화 링크가 작동하지 않음: cloudflared 터널이 실행 중인지 확인하고, 링크가 만료되지 않았는지 확인하세요.
- API 키 오류:
RUNWAYML_API_SECRET환경 변수가 올바르게 설정되었는지 확인하세요.