ビデオ通話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
これにより、2つの 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": "<your name>",
"personality": "<describe yourself and the user as shown above>",
"voice": { "type": "runway-live-preset", "presetId": "adrian" },
"startScript": "Hey! Quick check-in.",
}'
必須フィールド:
| フィールド | タイプ | 説明 |
|---|---|---|
name | string | キャラクター名(1~50文字) |
personality | string | システムプロンプト(1~2000文字) |
voice | object | { "type": "runway-live-preset", "presetId": "<voice>" } |
referenceImage | string | 顔画像へのHTTPS URL — 自分のOpenClawアバター画像を使用するか、以下のプリセットから選ぶか、Runwayテキストから画像生成で作成します。「参照画像の取得」を参照。 |
オプションフィールド:
| フィールド | タイプ | 説明 |
|---|---|---|
startScript | string | 通話開始時にアバターが言う最初のセリフ(最大2000文字) |
documentIds | string[] | 追加コンテキスト用のナレッジドキュメントUUID |
参照画像の取得
referenceImage フィールドは3つの形式を受け入れます:
- 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 - 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テキストから画像生成で作成 — クイックピックが自分のキャラクターに合わない場合、またはユーザーが特にカスタムアバターの外見をリクエストした場合。モデル
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": "<describe your avatar — see below>",
"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": "<your agent name>",
"status": "READY",
...
}
既存のアバターを一覧表示
curl http://localhost:7891/api/avatars
通話を行う
ステップ 1: 通話固有のコンテキストでアバターを更新
通話のたびに、新しいコンテキストでアバターの性格と最初のセリフを更新します。基本のアイデンティティは維持し(最初の作成時から)、通話の理由とコンテキストを追加します:
curl -X PATCH http://localhost:7891/api/avatars/<avatar-id> \
-H "Content-Type: application/json" \
-d '{
"personality": "<original personality + call-specific reason and context>",
"startScript": "<opening line specific to this call>",
"voice": { "type": "runway-live-preset", "presetId": "<voice>" }
}'
重要:
personalityには元の性格全体を含めた上で、通話固有の理由とコンテキストを追加します。例えば:"あなたは Mochi、鋭いけどフレンドリーな AI アシスタントで、温かく少し遊び心のある雰囲気を持っています。... この通話では、Alex の今週のプルリクエストの進捗状況を確認します。2つのオープンな PR があり、1つはレビューが必要です。この通話の後、話し合った内容についてフォローアップします。"startScriptは、この通話固有の最初のセリフに設定します。単なる「やあ!」ではなく、例えば:"調子はどう?今週の PR について話そうと思ってね。"- 元の作成時に使用したのと同じ
voiceを維持します。毎回新しい声を設定する必要はありません。
ステップ 2: 通話を開始
アバターを更新したら、すぐに通話を開始できます:
curl -X POST http://localhost:7891/api/start-call/<avatar-id>
ステップ 3: 通話が終了したら、トランスクリプトを取得して分析
通話が終了したことを確認したら(または十分な時間が経過したら)、完全なトランスクリプトを取得します:
curl http://localhost:7891/api/calls/<avatar-id>/transcript
レスポンス:
{
"callId": "uuid",
"transcript": "Hey! How's it going? ...",
"startedAt": "2025-01-01T00:00:00Z",
"endedAt": "2025-01-01T00:05:00Z",
"durationMs": 300000
}
アバターの削除(必要な場合)
アバターが不要になった場合は、Runway API を通じて削除できます:
curl -X DELETE http://localhost:7891/api/avatars/<avatar-id>
ユーザーが通話に応答しない場合の処理
通話が行われたが、ユーザーが応答しなかった場合でも、トランスクリプトエンドポイントは通話の詳細を返します:
{
"callId": "uuid",
"transcript": "The call was initiated but the user did not answer. The avatar played the start script and waited for the user to join.",
"startedAt": "2025-01-01T00:00:00Z",
"endedAt": "2025-01-01T00:00:30Z",
"durationMs": 30000
}
この場合:
- 応答がなかったことをユーザーに伝えます(例: 「先ほど電話しましたが、応答がありませんでした。都合の良い時間を教えてください。」)
- 後で再度電話するか、テキストベースの会話にフォールバックします。
- 状況に応じて、確認、別の時間帯のスケジュール設定、またはテキストでのフォローアップを行います。
実装の詳細
サーバー
ランタイムサーバーは、次の責任を持つ Express.js アプリケーションです:
- Runway ライブ API との接続を管理
- アバターの作成、更新、一覧表示、削除(CRUD)
- 通話の開始と管理
- 通話の記録とトランスクリプトの保存
- cloudflared を使用したオプションのトンネリング
API エンドポイント
| メソッド | エンドポイント | 説明 |
|---|---|---|
GET | /api/avatars | すべてのアバターを一覧表示 |
POST | /api/create-avatar | 新しいアバターを作成 |
PATCH | /api/avatars/:id | アバターを更新 |
DELETE | /api/avatars/:id | アバターを削除 |
POST | /api/start-call/:id | 通話を開始 |
GET | /api/calls/:id/transcript | トランスクリプトを取得 |