メインコンテンツへスキップ

​
画像 & メディアサポート — 2025-12-05

WhatsApp チャンネルは Baileys Web を介して動作します。本ドキュメントでは、送信、ゲートウェイ、エージェント返信における現在のメディア処理ルールをまとめています。 このドキュメントは、送信、ゲートウェイ、エージェントの応答のための現在のメディア処理ルールをキャプチャします。 このドキュメントは、送信、ゲートウェイ、エージェントの応答のための現在のメディア処理ルールをキャプチャします。

​
目標

  • openclaw message send --media を通じて、キャプション付き（任意）でメディアを送信できるようにします。
  • Web インボックスからの自動返信に、テキストと併せてメディアを含められるようにします。
  • 種別ごとの制限を妥当かつ予測可能なものに保ちます。

​
CLI サーフェス

  • openclaw message send --media <path-or-url> [--message <caption>]
    • --media は任意です。メディアのみ送信する場合、キャプションは空にできます。
    • --dry-run は解決後のペイロードを出力し、--json は { channel, to, messageId, mediaUrl, caption } を出力します。

​
WhatsApp Web チャンネルの挙動

  • 入力: ローカルファイルパス または HTTP(S) URL。
  • フロー: Buffer に読み込み、メディア種別を検出し、適切なペイロードを構築します。
    • 画像: JPEG にリサイズおよび再圧縮（最大辺 2048px）、agents.defaults.mediaMaxMb（デフォルト 5 MB）を目標とし、最大 6 MB に制限します。
    • 音声/ボイス/動画: 16 MB までパススルーします。音声はボイスノート（ptt: true）として送信されます。
    • ドキュメント: その他すべて。最大 100 MB までで、可能な場合はファイル名を保持します。
  • WhatsApp の GIF 風再生: モバイルクライアントでインラインループ再生されるよう、gifPlayback: true（CLI: --gif-playback）を付与した MP4 を送信します。
  • MIME 検出は、マジックバイト、次にヘッダー、最後にファイル拡張子の順で優先されます。
  • キャプションは --message または reply.text から取得されます。空のキャプションも許可されます。
  • ログ: 非 verbose では ↩️/✅ を表示し、verbose ではサイズおよびソースパス/URL を含めます。

​
自動返信パイプライン

  • getReplyFromConfig は { text?, mediaUrl?, mediaUrls? } を返します。
  • メディアが存在する場合、Web 送信者は openclaw message send と同じパイプラインを使用してローカルパスまたは URL を解決します。
  • 複数のメディアエントリが指定された場合、それらは順次送信されます。

​
コマンドへのインバウンドメディア（Pi）

  • インバウンドの Web メッセージにメディアが含まれる場合、OpenClaw はそれを一時ファイルにダウンロードし、テンプレート変数を公開します。
    • {{MediaUrl}} はインバウンドメディア用の疑似 URL です。
    • {{MediaPath}} は、コマンド実行前に書き込まれるローカルの一時パスです。
  • セッションごとの Docker サンドボックスが有効な場合、インバウンドメディアはサンドボックスのワークスペースにコピーされ、MediaPath/MediaUrl は media/inbound/<filename> のような相対パスに書き換えられます。
  • メディア理解（tools.media.* または共有の tools.media.models により設定されている場合）はテンプレート適用前に実行され、Body に [Image]、[Audio]、[Video] のブロックを挿入できます。
    • 音声は {{Transcript}} を設定し、文字起こしをコマンド解析に使用するため、スラッシュコマンドは引き続き動作します。
    • 動画および画像の説明では、コマンド解析のためにキャプションテキストが保持されます。
  • デフォルトでは、最初に一致した画像/音声/動画の添付ファイルのみが処理されます。複数の添付ファイルを処理するには tools.media.<cap>.attachments を設定してください。

​
制限およびエラー

アウトバウンド送信の上限（WhatsApp Web 送信）
  • 画像: 再圧縮後で約 6 MB が上限です。
  • 音声/ボイス/動画: 16 MB が上限、ドキュメント: 100 MB が上限です。
  • サイズ超過または読み取り不能なメディア → ログに明確なエラーが記録され、返信はスキップされます。
メディア理解の上限（文字起こし/説明）
  • 画像のデフォルト: 10 MB（tools.media.image.maxBytes）。
  • 音声のデフォルト: 20 MB（tools.media.audio.maxBytes）。
  • 動画のデフォルト: 50 MB（tools.media.video.maxBytes）。
  • サイズ超過のメディアは理解処理をスキップしますが、元の本文を含む返信自体は送信されます。

​
テストに関する注記

  • 画像/音声/ドキュメントのケースについて、送信および返信フローをカバーしてください。
  • 画像の再圧縮（サイズ制約）および音声のボイスノートフラグを検証してください。
  • 複数メディアの返信が順次送信として展開されることを確認してください。