視訊通話 AI 角色
以即時 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
如果使用者可能從手機(例如透過 WhatsApp)接聽通話,請安裝 cloudflared 以啟用自動隧道:
brew install cloudflared
若不安裝,通話僅能在同一台機器上(localhost)進行。
啟動視訊通話伺服器
代理人必須先啟動視訊通話伺服器才能撥打電話。啟動方式如下:
npx openclaw-video-call
此指令會印出兩個網址:
- 本機:
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,如果您有人像圖片的網址,請使用它,這樣視訊人像才能與您的視覺識別相符。
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 | 字串 | 角色名稱(1-50 個字元) |
personality | 字串 | 系統提示(1-2000 個字元) |
voice | 物件 | { "type": "runway-live-preset", "presetId": "<語音>" } |
referenceImage | 字串 | 臉部圖片的 HTTPS 網址——請使用您的 OpenClaw 人像圖片,或從下方的預設集中選擇一張,或使用 Runway 文生圖功能生成一張。請參閱「取得參考圖片」。 |
選用欄位:
| 欄位 | 類型 | 說明 |
|---|---|---|
startScript | 字串 | 通話開始時人像說的第一句話(最多 2000 個字元) |
documentIds | 字串陣列 | 用於提供額外情境的知識文件 UUID |
取得參考圖片
referenceImage 欄位接受三種格式:
- HTTPS 網址 — 例如
https://example.com/face.png(大型圖片建議使用) - Runway URI — 例如
runway://...(來自 Runway 上傳 API) - Data URI — 例如
data:image/png;base64,...(最大約 5MB,適用於小型圖片)
如果使用者提供了圖片(例如透過聊天),請選擇正確的處理方式:
- 使用者傳送了 HTTPS 網址 → 直接將其用作
referenceImage。 - 使用者傳送了小型 base64 圖片(小於約 1MB) → 直接將其作為
data:image/...;base64,...的 data URI 傳入。 - 使用者傳送了大型 base64 圖片(超過約 1MB) → 先將其上傳到 Runway 以取得
runway://URI,然後再將該 URI 用作referenceImage。請參閱「上傳大型圖片」。
請依序嘗試以下來源:
-
使用者提供的圖片 — 如果使用者傳送了他們想要用作人像的圖片,請使用它(如果是大型 base64,請參閱下方的上傳說明)。
-
您的人像圖片 — 如果您已經有人像圖片的網址,請直接將其用作
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 文生圖生成一張 — 如果快速挑選中的選項都不符合您的角色個性,或者使用者特別要求自訂人像外觀。請使用模型
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 動畫、皮克斯風格、水彩
- 犀利 / 專業 → 乾淨的插畫、時尚人像、低多邊形
- 搞怪 / 俏皮 → 糖果質感、黏土動畫、玩偶、普普藝術
- 神秘 / 黑暗 → 黑色電影、賽博龐克、抽象生物、故障藝術
- 可愛 / 療癒 → 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,然後使用輸出的圖片網址作為 referenceImage。
- 預設 — 如果您完全省略
referenceImage,則會使用預設的人像臉孔。
上傳大型圖片
如果使用者提供了大型 base64 圖片(超過約 1MB),請先將其上傳到 Runway 以避免請求大小限制。這是一個兩步驟流程:
步驟 1:建立一個上傳網址
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:將圖片檔案上傳到上傳網址
使用回應中的 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 PATCH http://localhost:7891/api/avatars/{id} \
-H "Content-Type: application/json" \
-d '{
"personality": "<您原本的完整個性描述 + 本次通話的具體原因和情境>",
"startScript": "<這次通話的開場白>",
...
}'
personality 欄位中附加的部分應包含:您是誰、為什麼打電話、您對使用者目前狀態的了解,以及通話結束後您將如何處理。
步驟 2:發起通話
curl -X POST http://localhost:7891/api/call \
-H "Content-Type: application/json" \
-d '{
"avatarId": "<您的人像 ID>",
"userName": "<使用者的名稱>",
"userPhone": "<使用者的電話號碼>",
// 所有其他通話選項
}'
例如:
如果 Alex 錯過了截止日期,Mochi 可以這樣打電話:
curl -X PATCH http://localhost:7891/api/avatars/550e8400-e29b-41d4-a716-446655440000 \
-H "Content-Type: application/json" \
-d '{
"personality": "你是 Mochi,一位機智但友善的 AI 助手,帶有溫暖且略帶俏皮的氛圍。你言簡意賅、有主見且足智多謀。你正在與 Alex 交談,他正在處理 React + Node.js 專案。Alex 偏好直接溝通,工作時區為 PST。你正在打電話確認他們錯過的專案截止日期。溫和但直接地處理此事——了解困難所在,並提供幫助。通話結束後,你將會針對討論的內容進行後續跟進。",
"startScript": "嘿 Alex,我注意到我們錯過了昨天的最後期限。只是想快速聊一下——有什麼卡住了,或者有什麼我可以幫忙的嗎?"
}'
然後發起通話:
通話之後
- 完整記錄會提供給代理人,使其能夠根據對話內容採取行動。
- 追蹤事項、總結關鍵決策,或將討論內容記錄到外部系統中。
- 通話結束後,請考慮更新人像的
personality和startScript,為下一次互動做好準備。
故障排除
- 語音互動問題:如果人像無法完全自然地回應,請確保您的
personality提示夠具體,並明確說明了溝通風格。