OpenClaw 한국어 문서

Appearance

이미지 및 미디어 지원 (2025-12-05) ​

WhatsApp 채널은 Baileys Web을 통해 실행됩니다. 이 문서는 전송, 게이트웨이, 에이전트 답변에 대한 현재 미디어 처리 규칙을 정리합니다.

목표 ​

  • openclaw message send --media를 통해 선택적 캡션과 함께 미디어를 전송합니다.
  • 웹 받은 편지함의 자동 답변에 텍스트와 함께 미디어를 포함할 수 있습니다.
  • 유형별 제한을 합리적이고 예측 가능하게 유지합니다.

CLI 표면 ​

  • openclaw message send --media <path-or-url> [--message <caption>]
    • --media 선택 사항; 미디어 전용 전송의 경우 캡션은 비워둘 수 있습니다.
    • --dry-run은 확인된 페이로드를 출력합니다. --json은 { channel, to, messageId, mediaUrl, caption }을 내보냅니다.

WhatsApp Web 채널 동작 ​

  • 입력: 로컬 파일 경로 또는 HTTP(S) URL.
  • 흐름: 버퍼에 로드하고, 미디어 종류를 감지하고, 올바른 페이로드를 빌드합니다:
    • 이미지: channels.whatsapp.mediaMaxMb(기본값: 50MB)를 목표로 JPEG로 리사이즈 및 재압축 (최대 2048px).
    • 오디오/보이스/비디오: 16MB까지 패스스루; 오디오는 보이스 노트로 전송됩니다 (ptt: true).
    • 문서: 파일 이름이 가능한 경우 보존된 100MB까지의 기타 항목.
  • WhatsApp GIF 스타일 재생: 모바일 클라이언트가 인라인으로 루프되도록 gifPlayback: true (CLI: --gif-playback)로 MP4를 전송하십시오.
  • MIME 감지는 매직 바이트, 헤더, 파일 확장자 순서를 선호합니다.
  • 캡션은 --message 또는 reply.text에서 가져옵니다; 빈 캡션이 허용됩니다.
  • 로깅: 비상세 모드는 ↩️/✅를 표시합니다; 상세 모드는 크기와 소스 경로/URL을 포함합니다.

자동 답변 파이프라인 ​

  • getReplyFromConfig는 { text?, mediaUrl?, mediaUrls? }를 반환합니다.
  • 미디어가 있는 경우 웹 전송자는 openclaw message send와 동일한 파이프라인을 사용하여 로컬 경로 또는 URL을 확인합니다.
  • 여러 미디어 항목이 제공된 경우 순차적으로 전송됩니다.

수신 미디어에서 명령으로 (Pi) ​

  • 수신 웹 메시지에 미디어가 포함된 경우, OpenClaw는 임시 파일로 다운로드하고 템플릿 변수를 노출합니다:
    • 수신 미디어의 유사 URL.
    • 명령 실행 전에 쓰여진 로컬 임시 경로.
  • 세션별 Docker 샌드박스가 활성화된 경우, 수신 미디어는 샌드박스 워크스페이스에 복사되고 MediaPath/MediaUrl이 media/inbound/<filename>과 같은 상대 경로로 재작성됩니다.
  • 미디어 이해(tools.media.* 또는 공유 tools.media.models를 통해 구성된 경우)는 템플릿화 전에 실행되며 [Image], [Audio], [Video] 블록을 Body에 삽입할 수 있습니다.
    • 오디오는 를 설정하고 명령 파싱에 전사 내용을 사용하므로 슬래시 명령이 계속 작동합니다.
    • 비디오 및 이미지 설명은 명령 파싱을 위해 캡션 텍스트를 보존합니다.
    • 활성 기본 이미지 모델이 이미 기본적으로 비전을 지원하는 경우, OpenClaw는 [Image] 요약 블록을 건너뛰고 원본 이미지를 모델에 직접 전달합니다.
  • 기본적으로 첫 번째 일치하는 이미지/오디오/비디오 첨부 파일만 처리됩니다. 여러 첨부 파일을 처리하려면 tools.media.<cap>.attachments를 설정하십시오.

제한 사항 및 오류 ​

아웃바운드 전송 제한 (WhatsApp 웹 전송)

  • 이미지: 재압축 후 channels.whatsapp.mediaMaxMb까지 (기본값: 50MB).
  • 오디오/보이스/비디오: 16MB 제한; 문서: 100MB 제한.
  • 크기 초과 또는 읽을 수 없는 미디어 → 로그에 명확한 오류 표시 및 답변 건너뜀.

미디어 이해 제한 (전사/설명)

  • 이미지 기본값: 10MB (tools.media.image.maxBytes).
  • 오디오 기본값: 20MB (tools.media.audio.maxBytes).
  • 비디오 기본값: 50MB (tools.media.video.maxBytes).
  • 크기 초과 미디어는 이해를 건너뛰지만, 답변은 여전히 원본 본문으로 처리됩니다.

테스트 참고 사항 ​

  • 이미지/오디오/문서 케이스에 대한 전송 + 답변 흐름을 다룹니다.
  • 이미지(크기 제한)에 대한 재압축과 오디오에 대한 보이스 노트 플래그를 검증합니다.
  • 여러 미디어 답변이 순차적 전송으로 분산되는지 확인합니다.