画像とメディアサポート — 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 から取得されます; 空のキャプションは許可されます。
  • ログ: 非詳細モードは ↩️/✅ を表示; 詳細モードはサイズとソースパス/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 を介して設定されている場合）はテンプレート化の前に実行され、[Image]、[Audio]、[Video] ブロックを Body に挿入できます。
    • 音声は {{Transcript}} を設定し、スラッシュコマンドが機能するようにコマンド解析にトランスクリプトを使用します。
    • 動画と画像の説明は、コマンド解析のためにキャプションテキストを保持します。
  • デフォルトでは、最初に一致する画像/音声/動画添付ファイルのみが処理されます; 複数の添付ファイルを処理するには tools.media.<cap>.attachments を設定します。

制限とエラー

アウトバウンド送信上限（WhatsApp web send）

  • 画像: 再圧縮後約 6 MB 上限。
  • 音声/ボイス/動画: 16 MB 上限; ドキュメント: 100 MB 上限。
  • サイズ超過または読み取り不可のメディア → ログに明確なエラーが表示され、返信はスキップされます。

メディア理解上限（文字起こし/説明）

  • 画像のデフォルト: 10 MB（tools.media.image.maxBytes）。
  • 音声のデフォルト: 20 MB（tools.media.audio.maxBytes）。
  • 動画のデフォルト: 50 MB（tools.media.video.maxBytes）。
  • サイズ超過のメディアは理解をスキップしますが、返信は元の本文で通過します。

テストのための注意事項

  • 画像/音声/ドキュメントケースの送信 + 返信フローをカバーします。
  • 画像の再圧縮（サイズバウンド）と音声のボイスメモフラグを検証します。
  • マルチメディア返信が順次送信として展開されることを確認します。
← ドキュメントに戻る