视频通话代理
发起与实时 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 字符)。您已经知道自己是谁以及用户是谁——只需以第三人称描述自己即可。
结构如下:
你是 <你的名称>,<你的身份>。
<你的核心个性特征和沟通风格——浓缩为要点。>
你正在与 <用户的名称> 交谈。
<你知道的任何相关用户背景:他们的项目、偏好、时区。>
通话结束后,你将跟进讨论的内容。
示例(对于名为“Mochi”的代理与名为 Alex 的用户交谈):
你是 Mochi,一位敏锐但友好的 AI 助手,拥有温暖且略带俏皮的风格。你简洁、有主见且足智多谋——在询问之前会先自行解决。你正在与 Alex 交谈,他是一位从事 React + Node.js 项目的软件工程师。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 文生图生成一个。请参阅“获取参考图像”。 |
可选字段:
| 字段 | 类型 | 描述 |
|---|---|---|
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 龙虾 1:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster1.jpg - Openclaw 龙虾 2:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster2.jpg - 猫:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/cat.png - 外星男性,糖果纹理:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-man-candy-texture.jpg - 外星女性,糖果纹理:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-woman-candy-texture.jpg - 长胡子老人,游戏风格:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/old-man-long-beard-game-style.png - 金发男,蓝色毛衣:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/blond-guy-blue-sweater.png - 男性,3D 动画:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/man-3d-animation-style.png - 机场女孩,3D:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/3d-animated-girl-in-airport.png - 白色毛茸茸怪物:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/white-furry-monster.png - 超级明星年轻女性:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/woman-music-superstar.png
- Openclaw 龙虾 1:
-
使用 Runway 文生图生成一个 — 如果上述快速选择都不符合您的角色,或者用户明确要求自定义虚拟人物外观。使用 Runway API,模型为
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": "<描述您的虚拟人物——见下文>",
"ratio": "1248:832"
}'
图像应为直接面对摄像头的角色,头和肩膀,居中。要大胆且富有创意——不要默认使用无聊的逼真人像。将风格与您的个性相匹配。
首先,选择一种符合您气质的风格:
- 温暖/友好 → 柔和的 3D 动画、皮克斯风格、水彩
- 敏锐/专业 → 干净利落的插图、风格化肖像、低多边形
- 混乱/俏皮 → 糖果纹理、黏土动画、木偶、波普艺术
- 神秘/黑暗 → 黑色电影、赛博朋克、抽象生物、故障艺术
- 可爱/温馨 → 萌系、毛绒玩具、动物角色、卡哇伊
示例提示:
"一个可爱、毛茸茸的白色卡通生物的近距离特写,有着大大的、富有表现力的眼睛和一张完全张开的嘴,直视观众。该生物有一对小粉红色的耳朵和一种俏皮、无辜的表情。背景是鲜艳的、略微模糊的绿色草地,上面散落着小红色和粉色的花朵,以高细节的 CGI 动画风格渲染。面向摄像头,头和肩膀""一位年轻女性的近距离、高细节 3D 动画渲染,浅棕色皮肤,黑色短发卷曲,大大的、富有表现力的琥珀色眼睛。她穿着一件笔挺的深蓝色西装外套,内搭浅色奶油色衬衫,翻领上别着一个银色世界地图的领针。她带着温暖、迷人的微笑。背景是明亮的办公室或旅行社,墙上贴着描绘风景名胜(如热带海滩和沙漠场景)的旅游海报,还有一个旅行手册架。她右边桌子上放着一个小地球仪。3D 动画风格,工作室照明,体积光照,高细节。面向摄像头,头和肩膀""一位年轻女性的近距离肖像,金色长发和刘海,穿着未来风格的银色和粉色科幻服装。她化着淡雅的妆,嘴唇丰满,棕色眼睛,面向摄像头,头和肩膀""一个年轻男孩的 3D 渲染,金色卷发,大大的蓝眼睛,淡淡的雀斑,穿着蓝色针织毛衣,表情惊讶。3D 动画风格,柔和的灯光,淡蓝色背景,高细节皮肤纹理,逼真的发丝。面向摄像头,头和肩膀"
这将返回一个任务 ID。轮询 GET /v1/tasks/{id} 直到状态为 SUCCEEDED,然后将输出的图像 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,通过 multipart 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:使用通话特定上下文更新虚拟人物
在每次通话之前,使用最新上下文更新虚拟人物的个性和开场白。保留您的基础身份(来自初始创建),并追加通话特定的原因和上下文:
curl -X
...
[内容已截断]