비디오 통화 AI 캐릭터
실시간 AI 비디오 아바타로 사용자에게 전화를 겁니다. 에이전트가 통화를 시작하고, 아바타가 컨텍스트를 가지고 먼저 말을 건 후, 통화가 끝나면 전체 대화 기록(transcript)을 에이전트가 후속 조치에 활용할 수 있습니다.
개인정보 보호 및 데이터 처리
- Runway API: 명시적으로 전달하는 데이터(아바타 이미지, 성격 텍스트, 통화 오디오/비디오)만 Runway(dev.runwayml.com)로 전송됩니다. 어떤 것도 자동으로 업로드되지 않습니다. 아바타는
DELETE /v1/avatars/{id}를 통해 언제든지 삭제할 수 있습니다. - 성격(Personality): 아바타의 성격은 에이전트 자신의 정체성(이름, 커뮤니케이션 스타일, 사용자에 대한 지식)을 기반으로 구축됩니다. 로컬 파일을 읽지 않으며, 에이전트는 이미 가지고 있는 컨텍스트를 사용합니다.
- 터널(Tunnel): 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 설치
사용자가 (예: WhatsApp을 통해) 휴대폰으로 전화를 받을 가능성이 있다면 자동 터널링을 위해 cloudflared를 설치하세요:
brew install cloudflared
cloudflared가 없으면 통화는 동일한 머신(localhost)에서만 작동합니다.
비디오 통화 서버 시작하기
에이전트가 통화를 걸기 전에 비디오 통화 서버가 실행 중이어야 합니다. 다음 명령어로 시작하세요:
npx openclaw-video-call
그러면 두 개의 URL이 출력됩니다:
- 로컬(Local):
http://localhost:7891— 동일한 머신에서만 가능 - 터널(Tunnel):
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": "<당신의 이름>",
"personality": "<위에 표시된 대로 자신과 사용자를 설명>",
"voice": { "type": "runway-live-preset", "presetId": "adrian" },
"startScript": "안녕하세요! 간단한 체크인입니다.",
}'
필수 필드:
| 필드 | 유형 | 설명 |
|---|---|---|
name | string | 캐릭터 이름 (1-50자) |
personality | string | 시스템 프롬프트 (1-2000자) |
voice | object | { "type": "runway-live-preset", "presetId": "<음성>" } |
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에서) - Data 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": "<아바타 설명 — 아래 참조>",
"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가 반환됩니다. GET /v1/tasks/{id}를 상태가 SUCCEEDED가 될 때까지 폴링한 다음, 출력 이미지 URL을 referenceImage로 사용하세요.
- 기본값 —
referenceImage를 완전히 생략하면 기본 아바타 얼굴이 사용됩니다.
대형 이미지 업로드
사용자가 큰 base64 이미지(~1MB 초과)를 제공하는 경우, 요청 크기 제한을 피하기 위해 먼저 Runway에 업로드하세요. 이는 2단계 프로세스입니다:
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": "<에이전트 이름>",
"status": "READY",
...
}
기존 아바타 목록 보기
curl http://localhost:7891/api/avatars
통화 걸기
1단계: 통화별 컨텍스트로 아바타 업데이트
각 통화 전에 아바타의 성격과 첫 마디(startScript)를 새로운 컨텍스트로 업데이트하세요. 기본 정체성(초기 생성 시의)을 유지하고 통화 이유와 컨텍스트를 추가하세요:
curl -X PATCH http://local
…
[truncated]