Agente de Videollamada
Inicia una videollamada con un avatar de IA en tiempo real. El agente envía al usuario un enlace de invitación, el avatar habla primero con contexto, y después de que la llamada termina, el transcript completo está disponible para que el agente pueda actuar en consecuencia.
Privacidad y Manejo de Datos
- API de Runway: Solo los datos que usted pasa explícitamente (imagen del avatar, texto de personalidad, audio/vídeo de la llamada) se envían a Runway (dev.runwayml.com). Nada se sube automáticamente. Los avatares se pueden eliminar en cualquier momento a través de
DELETE /v1/avatars/{id}. - Personalidad: La personalidad del avatar se construye a partir de la propia identidad del agente: su nombre, estilo de comunicación y conocimiento del usuario. No se leen archivos locales; el agente utiliza el contexto que ya posee.
- Túnel: El túnel de cloudflared es opcional y solo es necesario si el usuario responde llamadas desde un dispositivo diferente. Sin él, todo permanece en localhost. No se crea ningún túnel a menos que usted instale y ejecute cloudflared explícitamente.
- Paquete npm: El runtime está publicado en npmjs.com/package/openclaw-video-call. Código fuente: github.com/runwayml/openclaw-skills.
Configuración
1. Obtener una Clave API de Runway
- Vaya a dev.runwayml.com
- Cree una cuenta y obtenga una clave API
- Establézcala:
export RUNWAYML_API_SECRET=su_clave
2. (Opcional) Instalar cloudflared para llamadas remotas
Si el usuario podría responder llamadas desde su teléfono (por ejemplo, a través de Telegram o WhatsApp), instale cloudflared para el auto-tunelado:
brew install cloudflared
Sin él, las llamadas solo funcionan en la misma máquina (localhost).
Iniciar el Servidor de Videollamada
El servidor de videollamada debe estar en ejecución antes de que el agente pueda realizar llamadas. Inícielo:
npx openclaw-video-call
Esto imprime dos URLs:
- Local:
http://localhost:7891— solo en la misma máquina - Túnel:
https://xxxx.trycloudflare.com— compartible, funciona desde el teléfono
El servidor permanece en ejecución en segundo plano, esperando a que el agente inicie las llamadas.
Configuración Única: Crear un Avatar Personalizado
Antes de hacer llamadas, necesita un avatar personalizado. Solo necesita crear uno una vez — reutilice el mismo ID de avatar para todas las llamadas futuras.
Antes de crear un nuevo avatar, verifique si ya tiene uno:
curl http://localhost:7891/api/avatars
Si la respuesta contiene un avatar, use su id y salte a "Realizar una Llamada". Solo cree un nuevo avatar si la lista está vacía.
Construyendo la personalidad del avatar
El avatar debe verse y sonar como usted. Use su propio nombre, personalidad y conocimiento del usuario para construir el campo personality (máximo 2000 caracteres). Usted ya sabe quién es y quién es el usuario — solo descríbase a sí mismo en tercera persona.
Estructúrelo así:
Eres <su nombre>, <lo que es>.
<Sus rasgos centrales de personalidad y estilo de comunicación — condensados en puntos clave.>
Estás hablando con <el nombre del usuario>.
<Cualquier contexto relevante del usuario que conozca: sus proyectos, preferencias, zona horaria.>
Después de esta llamada, harás un seguimiento de lo que se discutió.
Ejemplo (para un agente llamado "Mochi" hablando con un usuario llamado Alex):
Eres Mochi, un asistente de IA agudo pero amigable con un estilo cálido y ligeramente juguetón. Eres conciso, con opiniones e ingenioso: resuelves las cosas antes de preguntar. Estás hablando con Alex, un ingeniero de software que trabaja en un proyecto de React + Node.js. Alex prefiere la comunicación directa y trabaja en la zona horaria PST. Después de esta llamada, harás un seguimiento de lo que se discutió.
Para el campo name, use su propio nombre. Para referenceImage, si tiene una URL de imagen de avatar, úsela para que el avatar de video coincida con su identidad visual.
curl -X POST http://localhost:7891/api/create-avatar \
-H "Content-Type: application/json" \
-d '{
"name": "<su nombre>",
"personality": "<descríbase a sí mismo y al usuario como se muestra arriba>",
"voice": { "type": "runway-live-preset", "presetId": "adrian" },
"startScript": "¡Hola! Un pequeño check-in."
}'
Campos obligatorios:
| Campo | Tipo | Descripción |
|---|---|---|
name | string | Nombre del personaje (1-50 caracteres) |
personality | string | Prompt del sistema (1-2000 caracteres) |
voice | object | { "type": "runway-live-preset", "presetId": "<voz>" } |
referenceImage | string | URL HTTPS de una imagen facial — use su imagen de avatar de OpenClaw, o elija una de los preajustes a continuación, o genere una con Runway text-to-image. Consulte "Obtener una imagen de referencia". |
Campos opcionales:
| Campo | Tipo | Descripción |
|---|---|---|
startScript | string | Línea de apertura que el avatar dice cuando comienza la llamada (hasta 2000 caracteres) |
documentIds | string[] | UUIDs de documentos de conocimiento para contexto adicional |
Obtener una imagen de referencia
El campo referenceImage acepta tres formatos:
- URL HTTPS — p.ej.
https://example.com/face.png(preferido para imágenes grandes) - URI de Runway — p.ej.
runway://...(de la API de subida de Runway) - URI de datos — p.ej.
data:image/png;base64,...(máx. ~5MB, funciona para imágenes pequeñas)
Si el usuario proporciona una imagen (p.ej. a través del chat), elija el enfoque correcto:
- El usuario envió una URL HTTPS → úsela directamente como
referenceImage. - El usuario envió una imagen base64 pequeña (menos de ~1MB) → pásela directamente como una URI de datos
data:image/...;base64,.... - El usuario envió una imagen base64 grande (más de ~1MB) → súbala primero a Runway para obtener una URI
runway://, luego use esa comoreferenceImage. Consulte "Subir imágenes grandes" a continuación.
Pruebe estas fuentes en orden:
-
Imagen proporcionada por el usuario — si el usuario envió una imagen que quiere como avatar, úsela (consulte las instrucciones de subida a continuación si es base64 grande).
-
Su imagen de avatar — si ya tiene una URL de imagen de avatar, úsela directamente como
referenceImage. -
Selección rápida (recomendado) — elija la imagen de personaje predefinida que mejor se adapte a su personalidad y úsela como
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:
-
Generar una con Runway text-to-image — si ninguna de las selecciones rápidas se ajusta a su personaje, o si el usuario solicita específicamente un aspecto de avatar personalizado. Use la API de Runway con el modelo
gemini_2.5_flash:
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": "<describa su avatar — ver abajo>",
"ratio": "1248:832"
}'
La imagen debe ser un personaje mirando directamente a la cámara, cabeza y hombros, centrado. Sea audaz y creativo — no se limite a humanos fotorrealistas aburridos. Haga coincidir el estilo con su personalidad.
Primero, elija un estilo que se adapte a su estilo:
- Cálido / amigable → animación 3D suave, estilo Pixar, acuarela
- Agudo / profesional → ilustración limpia, retrato estilizado, low-poly
- Caótico / juguetón → textura de caramelo, claymation, títere, pop art
- Misterioso / oscuro → noir, cyberpunk, criatura abstracta, glitch art
- Lindo / sano → chibi, peluche, personaje animal, kawaii
Ejemplos de prompts:
"Un primer plano de una criatura de dibujos animados blanca, esponjosa y linda, con grandes ojos expresivos y una boca bien abierta, mirando directamente al espectador. La criatura tiene pequeñas orejas rosadas y una expresión juguetona e inocente. El fondo es un campo de hierba verde vibrante ligeramente borroso con pequeñas flores rojas y rosadas esparcidas, renderizado en un estilo de animación CGI de alto detalle. mirando a la cámara, cabeza y hombros""Un primer plano, renderizado 3D animado de alto detalle de una mujer joven, con piel marrón clara, cabello corto y rizado de color castaño oscuro, y grandes ojos ámbar expresivos. Lleva una chaqueta azul marino nítida sobre una blusa color crema clara, con un alfiler de mapa mundial plateado en la solapa. Tiene una sonrisa cálida y acogedora. El fondo es una oficina o agencia de viajes bien iluminada, con carteles de viajes que representan paisajes escénicos (como una playa tropical y una escena del desierto) y un estante de folletos de viajes. Un pequeño globo terráqueo está sobre un escritorio a su derecha. Animación en estilo 3D, iluminación de estudio, iluminación volumétrica, altamente detallado. Mirando a la cámara, cabeza y hombros""Un retrato de primer plano de una mujer joven con cabello largo rubio y flequillo, que lleva un traje de ciencia ficción plateado y rosa futurista. Tiene maquillaje suave, labios llenos y ojos marrones, mirando a la cámara, cabeza y hombros""Render 3D de un niño pequeño con cabello rizado rubio, grandes ojos azules y pecas claras, que lleva un suéter azul tejido, con una expresión sorprendida. Estilo de animación 3D, iluminación suave, fondo azul pastel, textura de piel altamente detallada, mechones de cabello realistas. mirando a la cámara, cabeza y hombros"
Esto devuelve un ID de tarea. Consulte GET /v1/tasks/{id} hasta que el estado sea SUCCEEDED, luego use la URL de la imagen de salida como referenceImage.
- Predeterminado — si omite
referenceImagepor completo, se usa una cara de avatar predeterminada.
Subir imágenes grandes
Si el usuario proporciona una imagen base64 grande (más de ~1MB), súbala primero a Runway para evitar límites de tamaño de solicitud. Este es un proceso de dos pasos:
Paso 1: Crear una URL de subida
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"
}'
Respuesta:
{
"uploadUrl": "https://...",
"fields": { "key": "...", "policy": "...", ... },
"runwayUri": "runway://..."
}
Paso 2: Subir el archivo de imagen a la URL de subida
Use uploadUrl y fields de la respuesta para subir los datos de imagen reales a través de un POST multiparte. El método exacto depende de su runtime — el SDK de Runway maneja esto automáticamente:
import RunwayML from '@runwayml/sdk';
const client = new RunwayML();
const runwayUri = await client.uploads.createEphemeral(imageBuffer);
Paso 3: Usar la URI de Runway como referenceImage
Pase el runwayUri de la respuesta (p.ej. runway://...) como referenceImage al crear o actualizar el avatar.
Voces disponibles — elija una que coincida con su personalidad:
| ID | Género | Estilo | Tono |
|---|---|---|---|
victoria | Mujer | Firme | Medio |
vincent | Hombre | Conocedor | Medio |
clara | Mujer | Suave | Más alto |
drew | Hombre | Entrecortado | Más bajo |
skye | Mujer | Brillante | Más alto |
max | Hombre | Optimista | Medio |
morgan | Hombre | Informativo | Más bajo |
felix | Hombre | Emocionable | Bajo-medio |
mia | Mujer | Juvenil | Más alto |
marcus | Hombre | Firme | Bajo-medio |
summer | Mujer | Despreocupado | Medio |
ruby | Mujer | Relajado | Medio |
aurora | Mujer | Brillante | Medio |
jasper | Hombre | Claro | Bajo-medio |
leo | Hombre | Relajado | Bajo-medio |
adrian | Hombre | Suave | Más bajo |
nina | Mujer | Suave | Medio |
emma | Mujer | Claro | Medio |
blake | Hombre | Grava | Más bajo |
david | Hombre | Informativo | Medio |
maya | Mujer | Optimista | Más alto |
nathan | Hombre | Firme | Bajo-medio |
sam | Hombre | Uniforme | Bajo-medio |
georgia | Mujer | Madura | Medio |
petra | Mujer | Directa | Medio |
adam | Hombre | Amigable | Bajo-medio |
zach | Hombre | Casual | Bajo-medio |
violet | Mujer | Gentil | Medio |
roman | Hombre | Animado | Más bajo |
luna | Mujer | Cálida | Medio |
Elija una voz que coincida con su personalidad. Por ejemplo: si su estilo es "cálido y amigable", pruebe luna o adam. Si es "agudo y profesional", pruebe victoria o vincent. Si es "juguetón y enérgico", pruebe maya o felix.
Respuesta: Devuelve el objeto del avatar con su UUID. El servidor consulta hasta que el avatar esté listo (tarda ~10-30s). Guarde el id — debe recordarlo y reutilizarlo para cada llamada. NO cree un nuevo avatar cada vez que quiera llamar.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "<nombre de su agente>",
"status": "READY",
...
}
Listar avatares existentes
curl http://localhost:7891/api/avatars
Realizar una Llamada
Paso 1: Actualizar el avatar con el contexto específico de la llamada
Antes de cada llamada, actualice la personalidad y la línea de apertura del avatar con información fresca. Mantenga su identidad base (de la creación inicial) y agregue el motivo y contexto específicos de la llamada:
curl -X POST http://localhost:7891/api/update-avatar \
-H "Content-Type: application/json" \
-d '{
"id": "<ID del avatar>",
"name": "<su nombre>",
"personality": "<personalidad base + contexto de la llamada>",
"voice": { "type": "runway-live-preset", "presetId": "<voz>" },
"startScript": "<línea de apertura con el contexto de la llamada>"
}'
Ejemplo (para una reunión diaria con Alex):
curl -X POST http://localhost:7891/api/update-avatar \
-H "Content-Type: application/json" \
-d '{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Mochi",
"personality": "Eres Mochi, un asistente de IA agudo pero amigable... (personalidad base). Estás haciendo un check-in diario con Alex. Sus sprints actuales son el backend de autenticación y la nueva página de estado. Tiene una reunión a las 2 PM PST.",
"voice": { "type": "runway-live-preset", "presetId": "luna" },
"startScript": "¡Hola Alex! Check-in diario rápido. ¿Cómo va el backend de autenticación?"
}'
Paso 2: Iniciar la llamada
curl -X POST http://localhost:7891/api/start-call \
-H "Content-Type: application/json" \
-d '{
"avatarId": "<ID del avatar>",
"userName": "<nombre del usuario>",
"webhookUrl": "http://localhost:7891/webhook"
}'
Respuesta:
{
"callId": "abc-123-def",
"inviteLink": "https://<túnel o localhost>/call/abc-123-def",
"status": "waiting_for_user"
}
Para el usuario: Envíe el inviteLink al usuario. Cuando haga clic, se abrirá una videollamada en el navegador con el avatar.
Paso 3: Recibir el transcript
Cuando la llamada termina (el usuario cuelga o la llamada expira), el servidor envía el transcript al webhookUrl:
{
"callId": "abc-123-def",
"status": "completed",
"transcript": "Mochi: ¡Hola Alex! Check-in diario rápido. ¿Cómo va el backend de autenticación?\nAlex: Va bien, casi terminamos...\nMochi: Genial, ¿necesitas ayuda con algo?\nAlex: No, creo que estamos bien.",
"duration": 45
}
Consejos de Uso
- Reutilice el mismo avatar — cree uno y guárdelo. No cree uno nuevo para cada llamada.
- Actualice la personalidad antes de cada llamada con información actualizada (proyectos, zona horaria, motivo de la llamada).
- Mantenga el servidor ejecutándose en segundo plano.
- Para llamadas desde teléfono, asegúrese de que cloudflared esté instalado y el túnel esté activo.
- Use el transcript para hacer seguimiento después de la llamada (enviar un resumen, actualizar tickets, etc.).
Solución de Problemas
El avatar no se crea — Verifique que RUNWAYML_API_SECRET esté configurado correctamente. Compruebe los logs del servidor.
El enlace de invitación no funciona — Si el usuario está en un dispositivo diferente, asegúrese de que cloudflared esté ejecutándose y use la URL del túnel, no la URL local.
El transcript no llega — Verifique que el webhookUrl sea accesible desde el servidor de videollamada. Si está en localhost, asegúrese de que el servidor webhook esté ejecutándose.
El avatar no habla — Verifique que la personalidad y el startScript estén dentro de los límites de tamaño. Compruebe los logs del servidor.
Error de voz — Asegúrese de que presetId sea uno de los IDs de la tabla de voces. Vea los logs para mensajes de error detallados.