OpenClaw 多媒体处理与文件管理

2026-01-11 · 6 分钟基础配置

多媒体支持概览

OpenClaw 支持跨频道的多媒体消息处理，包括图片、音频、视频、文档等多种格式。不同频道对媒体类型的支持程度有所不同，本文将详细介绍各项配置。

图片处理

图片分析能力

当用户发送图片时，OpenClaw 会自动调用已配置模型的视觉能力进行分析：

{
  model: {
    provider: "anthropic",
    model: "claude-sonnet-4-20250514",
    // 视觉分析自动启用，无需额外配置
  }
}

支持的图片格式包括 JPEG、PNG、GIF、WebP。用户可以直接在聊天中发送图片并附带问题，模型会对图片内容进行分析回答。

图片大小限制

不同频道有不同的图片大小限制，可以在配置中设定处理上限：

{
  media: {
    maxImageSize: "20MB",     // 最大接收图片大小
    imageCompression: true,   // 自动压缩过大的图片
    compressionQuality: 85,   // 压缩质量（1-100）
  }
}

图片生成

通过集成图片生成工具，OpenClaw 可以根据文字描述创建图片：

{
  tools: {
    image_generation: {
      enabled: true,
      provider: "dall-e",
      model: "dall-e-3",
      defaultSize: "1024x1024"
    }
  }
}

语音消息处理

语音转文字

OpenClaw 支持接收语音消息并自动转写为文字进行处理：

{
  media: {
    voice: {
      transcription: {
        enabled: true,
        provider: "whisper",    // 使用 OpenAI Whisper
        model: "whisper-1",
        language: "zh",         // 默认中文转写
      }
    }
  }
}

语音转写钩子

可以配置转写后的处理钩子，实现更灵活的工作流：

{
  media: {
    voice: {
      transcription: {
        enabled: true,
        hooks: {
          // 转写完成后添加前缀标识
          postProcess: "prepend:[语音消息] ",
          // 转写失败时的回退消息
          fallbackMessage: "抱歉，无法识别该语音消息。"
        }
      }
    }
  }
}

文档处理

OpenClaw 可以接收和处理多种文档格式：

{
  media: {
    documents: {
      enabled: true,
      supportedFormats: ["pdf", "docx", "txt", "csv", "xlsx"],
      maxFileSize: "50MB",
      // 文档解析引擎
      parser: {
        pdf: "pdftotext",     // PDF 解析方式
        ocr: false            // 是否启用 OCR
      }
    }
  }
}

用户发送文档后，OpenClaw 会提取文本内容供模型分析：

用户: [发送了一个 PDF 文件]
用户: 帮我总结这份文档的要点

OpenClaw: 这份文档主要包含以下要点：
1. ...
2. ...

移动端特殊工具

从移动节点连接时，OpenClaw 提供额外的媒体捕获工具：

拍照与录屏

{
  tools: {
    camera: {
      enabled: true,
      // 拍照
      snap: true,
      // 视频片段
      clip: {
        enabled: true,
        maxDuration: 30   // 最长 30 秒
      },
      // 屏幕录制
      screen_record: {
        enabled: true,
        maxDuration: 60   // 最长 60 秒
      }
    }
  }
}

这些工具可以通过指令触发：

用户: 拍一张照片
OpenClaw: [调用 camera.snap 工具，返回拍摄的照片]

用户: 录制 10 秒屏幕
OpenClaw: [调用 screen_record 工具，录制并返回视频]

输出格式控制

控制 OpenClaw 回复消息的媒体格式：

{
  output: {
    // 默认输出格式
    format: "markdown",

    // 代码块语法高亮
    codeHighlight: true,

    // 长消息自动分段
    autoSplit: {
      enabled: true,
      maxLength: 4000    // 单条消息最大字符数
    },

    // 媒体输出偏好
    media: {
      preferInline: true,     // 优先内联显示
      imageFormat: "png",     // 默认图片输出格式
    }
  }
}

跨频道媒体兼容性

不同频道对媒体的支持情况：

功能	WhatsApp	Discord	Slack
图片接收	支持	支持	支持
图片发送	支持	支持	支持
语音消息	支持	支持	不支持
文件上传	支持	支持	支持
GIF	支持	支持	支持
视频	有限制	支持	支持

常见问题排查

图片无法接收

# 检查媒体处理服务状态
openclaw doctor --check media

# 验证存储目录权限
ls -la /var/lib/openclaw/media/

语音转写失败

# 检查 Whisper API 连通性
curl -s https://api.openai.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F file=@test.ogg -F model=whisper-1

# 查看转写相关日志
openclaw logs --filter media.voice

文件过大被拒绝

调整配置中的大小限制，同时注意频道本身的限制无法通过配置绕过。建议在系统提示词中告知用户文件大小限制。