視訊通話代理
使用即時 AI 頭像發起視訊通話。代理會向使用者發送通話邀請連結,頭像將根據上下文率先發言,通話結束後,代理可取得完整的通話記錄並據此採取行動。
隱私與資料處理
- Runway API:僅傳送您明確提供的資料(頭像影像、個性設定文字、通話音訊/視訊)至 Runway (dev.runwayml.com)。不會自動上傳任何內容。可隨時透過
DELETE /v1/avatars/{id}刪除頭像。 - 個性設定:頭像的個性基於代理自身的身份——其名稱、溝通風格以及對使用者的了解。不會讀取任何本地檔案;代理僅使用其已擁有的上下文。
- 隧道:cloudflared 隧道為可選項,僅當使用者可能從其他裝置接聽通話時才需要。若不使用,所有流量都會保留在本地主機上。除非您明確安裝並執行 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 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 - 貓:
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 Lobster 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 動畫、皮克斯風格、水彩畫
- 銳利 / 專業 → 乾淨的插圖、風格化肖像、低多邊形
- 混亂 / 好玩 → 糖果質感、黏土動畫、布偶、普普藝術
- 神秘 / 黑暗 → 黑色電影、賽博龐克、抽象生物、故障藝術
- 可愛 / 治癒 → 小可愛(Q版)、絨毛玩具、動物角色、卡哇伊
提示詞範例:
"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,以避免請求大小限制。這是一個兩步驟的過程:
步驟 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
...
[翻譯截斷]