第 24 章:多模态与媒体处理

难度: ⭐⭐⭐ 进阶 | 预计阅读: 24 分钟 | 前置章节: [第 3-4 章](03-Skills 插件体系与批量开发.md)、[第 16 章](16-MCP 工具协议与自定义集成.md)

OpenClaw 不仅处理文本,还支持图片、文件、网页内容等多种模态的输入和输出。本章将介绍多模态处理的完整方案,包括媒体文件管理、图片处理 Skill、网页抓取与内容提取,以及与小红书等第三方平台的集成。

24.1 多模态处理概述

传统的 CLI Agent 主要处理文本输入和输出。OpenClaw 通过 Skills 和 MCP 工具扩展了多模态能力:

模态输入支持输出支持典型 Skill
文本✅ 完整支持✅ 完整支持内置
图片✅ 上传/URL✅ 下载/保存image-processor
网页✅ URL 抓取✅ HTML 生成browser-relay
文件✅ 读取/解析✅ 创建/修改内置文件工具
音频⚠️ 需要 Skill⚠️ 需要 Skillwhisper-transcribe
视频❌ 暂不支持❌ 暂不支持规划中

多模态数据流

多模态数据在 OpenClaw 系统中的流转路径如下:

阶段动作存储位置
接收通过飞书/CLI/API 接收媒体media/inbound/
解析Skill 或 MCP 工具处理内存/临时文件
存储结果保存到指定位置media/ 或用户指定目录
引用在记忆或文档中引用Markdown 链接

所有接收的媒体文件默认保存在 ~/.openclaw/media/inbound/ 目录下,Agent 可以按需处理或归档。


24.2 媒体文件管理

OpenClaw 提供了统一的媒体文件管理体系。

媒体目录结构

~/.openclaw/media/
├── inbound/          # 接收的媒体文件(飞书、API 等来源)
│   ├── img_20260306_001.png
│   ├── doc_20260306_002.pdf
│   └── audio_20260306_003.mp3
├── processed/        # 处理后的文件
│   ├── resized_img_001.png
│   └── extracted_doc_002.txt
└── archive/          # 归档的旧媒体
    └── 2026-02/

媒体管理命令

# 查看当前媒体文件统计
openclaw media stats

# 列出最近接收的文件
ls -lt ~/.openclaw/media/inbound/ | head -10

# 查看各目录占用空间
du -sh ~/.openclaw/media/*/

# 清理超过 30 天的入站媒体
find ~/.openclaw/media/inbound/ -mtime +30 -type f -exec rm {} \;

# 归档旧文件到按月目录
MONTH=$(date -d "30 days ago" +%Y-%m)
mkdir -p ~/.openclaw/media/archive/$MONTH
find ~/.openclaw/media/inbound/ -mtime +30 -exec mv {} \
     ~/.openclaw/media/archive/$MONTH/ \;

媒体文件元数据

每个媒体文件可通过 sidecar JSON 记录元数据:

{
  "filename": "img_20260306_001.png",
  "source": "feishu",
  "sourceMessageId": "om_abc123",
  "receivedAt": "2026-03-06T10:00:00Z",
  "mimeType": "image/png",
  "size": 245760,
  "processed": true,
  "processedAt": "2026-03-06T10:01:00Z",
  "tags": ["screenshot", "error-log"]
}

24.3 图片处理与识别

图片是最常见的非文本模态。OpenClaw 支持通过多种方式处理图片。

使用 AI 视觉模型

当使用支持视觉的 AI 模型(如 GPT-4V、Claude 3)时,Agent 可以直接理解图片内容:

# 在 Agent 对话中发送图片进行分析
# 飞书中直接发送图片后,Agent 会自动识别并分析

# 通过 CLI 传入图片 URL
openclaw chat --image "https://example.com/screenshot.png" \
  "这张截图中的错误信息是什么?请给出解决方案"

# 传入本地图片文件
openclaw chat --image ~/.openclaw/media/inbound/error-screenshot.png \
  "请分析这个错误截图"

图片处理 Skill

安装图片处理 Skill 可以执行更多操作:

# 安装图片处理技能
npx skills install image-processor

# 安装后可用的工具
# - image_resize: 调整图片尺寸
# - image_compress: 压缩图片
# - image_convert: 格式转换
# - image_metadata: 读取 EXIF 信息

批量图片处理脚本

#!/bin/bash
# batch-image-process.sh — 批量处理入站图片
INBOUND=~/.openclaw/media/inbound
PROCESSED=~/.openclaw/media/processed

mkdir -p "$PROCESSED"

for img in "$INBOUND"/*.{png,jpg,jpeg}; do
  [[ -f "$img" ]] || continue
  filename=$(basename "$img")

  # 压缩图片(需要 ImageMagick)
  if command -v convert &>/dev/null; then
    convert "$img" -resize "1920x1080>" -quality 85 "$PROCESSED/opt_$filename"
    echo "✅ 优化: $filename → opt_$filename"
  else
    cp "$img" "$PROCESSED/$filename"
    echo "⚠️ 复制: $filename (ImageMagick 未安装)"
  fi
done

echo "处理完成: $(ls "$PROCESSED" | wc -l) 个文件"

24.4 网页内容抓取与提取

OpenClaw 通过 Browser Relay 和 MCP 工具支持网页内容的抓取和提取。

Browser Relay 抓取

# 使用内置的 fetch_webpage 能力获取网页内容
openclaw chat "请获取 https://docs.openclaw.ai 的首页内容并总结"

# 查看 Browser Relay 状态
ls ~/.openclaw/browser-relay/

网页内容提取策略

策略适用场景优势限制
直接 HTTP 请求静态页面快速、轻量无法处理 JavaScript
Browser Relay动态页面完整渲染资源消耗较高
API 调用有公开 API 的平台结构化数据需要 API Key
RSS/Atom博客/新闻标准格式内容可能不完整

网页监控 Cron 任务

{
  "name": "网页变更监控",
  "schedule": {"kind": "cron", "expr": "0 */6 * * *"},
  "enabled": true,
  "payload": {
    "kind": "agentTurn",
    "message": "请检查以下网页是否有更新,如有变更则通知我:\n1. https://docs.openclaw.ai/changelog\n2. https://github.com/OpenClaw/OpenClaw/releases"
  }
}

24.5 第三方平台媒体集成

OpenClaw 可以与多种第三方平台进行媒体内容交互。

飞书媒体消息处理

飞书是 OpenClaw 最主要的消息通道,支持多种媒体类型:

消息类型Agent 处理方式示例场景
图片消息下载到 media/inbound 并分析用户发送截图请求帮助
文件消息下载并按类型解析用户发送 Excel 请求数据分析
富文本消息提取文本和嵌入媒体包含格式的长消息
链接卡片提取 URL 并抓取内容用户分享文章请求总结
# 查看飞书接收的媒体文件
ls -la ~/.openclaw/media/inbound/

# 检查飞书消息处理日志
grep "media" ~/.openclaw/logs/gateway.log | tail -5

小红书 MCP 集成

通过小红书 MCP Skill 可以实现内容创作和发布自动化:

# ~/.openclaw/workspace/skills/xiaohongshu-mcp/config.yaml
name: xiaohongshu-mcp
version: 1.0.0
tools:
  - name: xhs_search
    description: 搜索小红书笔记
  - name: xhs_create_note
    description: 创建小红书笔记草稿
  - name: xhs_upload_image
    description: 上传图片到小红书

内容创作工作流

# 示例: 使用 Agent 辅助创建小红书内容
openclaw chat "请帮我创建一篇关于 OpenClaw 入门的小红书笔记:
1. 生成标题和正文(加 emoji)
2. 推荐相关话题标签
3. 建议配图方向"

# 将 Agent 生成的内容通过 MCP 工具发布
# Agent 会自动调用 xhs_create_note 工具

进阶:多模态处理架构原理

理解多模态处理的内部架构有助于优化处理效率和排查问题。

媒体处理管线

阶段组件职责
接收层Channel Adapter从各通道接收媒体(飞书、API、CLI)
存储层Media Store持久化到 media/ 目录,生成元数据
处理层Skill/MCP Tool执行具体的处理操作(识别、转换等)
输出层Response Builder将处理结果格式化返回给用户

大文件处理策略

核心原则是避免在 LLM 上下文中传递大量二进制数据:

文件大小策略说明
< 1MB直接处理图片可直接传给视觉模型
1-10MB预处理先压缩/裁剪,再传给模型
10-100MB分块处理分段提取关键内容
> 100MB摘要处理仅提取元数据和摘要

注意事项与常见错误

多模态处理中以下问题值得警惕:

常见错误后果正确做法
不清理入站媒体media/inbound 目录膨胀配置 Cron 定期归档清理
图片未压缩直接传入 LLMToken 浪费,响应变慢先压缩到合理尺寸再处理
假设所有模型支持视觉不支持视觉的模型无法处理图片先检查模型能力再调用
网页抓取不设超时Agent 长时间卡在等待设置合理的超时参数(建议 15s)

实操练习

练习 1:查看媒体文件管理

目标:了解当前环境的媒体文件状态。

# Step 1: 查看媒体目录结构
echo "=== 媒体目录结构 ==="
find ~/.openclaw/media/ -type d 2>/dev/null | head -10

# Step 2: 统计各类型文件数量
echo "=== 文件类型统计 ==="
find ~/.openclaw/media/ -type f 2>/dev/null | \
  sed 's/.*\.//' | sort | uniq -c | sort -rn

# Step 3: 查看总占用空间
echo "=== 空间占用 ==="
du -sh ~/.openclaw/media/ 2>/dev/null || echo "media 目录不存在"

# Step 4: 查看最近的入站文件
echo "=== 最近 5 个入站文件 ==="
ls -lt ~/.openclaw/media/inbound/ 2>/dev/null | head -6

练习 2:配置媒体自动清理

目标:设置自动归档和清理旧媒体文件。

# 创建媒体清理脚本
cat > /tmp/media-cleanup.sh << 'SCRIPT'
#!/bin/bash
# media-cleanup.sh — 媒体文件自动归档清理
MEDIA=~/.openclaw/media
ARCHIVE=$MEDIA/archive/$(date +%Y-%m)
DAYS=30

echo "=== 媒体清理开始 ==="
mkdir -p "$ARCHIVE"

# 归档超过 30 天的入站文件
COUNT=$(find "$MEDIA/inbound/" -mtime +$DAYS -type f 2>/dev/null | wc -l)
if [[ $COUNT -gt 0 ]]; then
  find "$MEDIA/inbound/" -mtime +$DAYS -type f -exec mv {} "$ARCHIVE/" \;
  echo "✅ 归档 $COUNT 个文件到 $ARCHIVE/"
else
  echo "ℹ️ 无需归档的文件"
fi

# 统计清理后的状态
echo "=== 清理后状态 ==="
echo "入站: $(find "$MEDIA/inbound/" -type f 2>/dev/null | wc -l) 个文件"
echo "归档: $(find "$MEDIA/archive/" -type f 2>/dev/null | wc -l) 个文件"
echo "总大小: $(du -sh "$MEDIA" 2>/dev/null | cut -f1)"
SCRIPT
chmod +x /tmp/media-cleanup.sh
echo "✅ 清理脚本已创建,可通过 Cron 定期执行"

练习 3:网页内容提取

目标:练习从网页中提取结构化内容。

# 使用 curl 获取网页并提取关键信息
URL="https://github.com/OpenClaw/OpenClaw"

echo "=== 获取网页标题 ==="
curl -s "$URL" | grep -oP '(?<=<title>).*(?=</title>)' | head -1

echo "=== 获取外部链接 ==="
curl -s "$URL" | grep -oP 'href="https?://[^"]+' | sed 's/href="//' | \
  sort -u | head -10

echo "=== 统计页面大小 ==="
SIZE=$(curl -s "$URL" | wc -c)
echo "页面大小: $((SIZE/1024)) KB"

常见问题 (FAQ)

Q1:哪些 AI 模型支持图片输入?

A:目前支持视觉输入的主流模型包括 GPT-4V/GPT-4o、Claude 3 系列、Gemini Pro Vision 等。在 openclaw.json 中配置的模型需要确认是否支持多模态。不支持视觉的模型会忽略图片输入。

Q2:飞书发送的文件能自动处理吗?

A:Agent 会将飞书发送的文件保存到 media/inbound/,但自动处理需要安装对应的 Skill。例如,处理 Excel 需要 excel-parser Skill,处理 PDF 需要 pdf-extractor Skill。

Q3:如何限制媒体文件的存储空间?

A:可以通过 Cron 任务定期清理,或在 openclaw.json 中配置 media.maxStorageSize

{
  "media": {
    "maxStorageSize": "500MB",
    "autoCleanupDays": 30
  }
}

Q4:网页抓取被目标网站封禁了怎么办?

A:设置合理的抓取间隔(建议 >=5 秒),使用恰当的 User-Agent,遵守网站的 robots.txt 规则。频繁抓取时考虑使用代理服务。


参考来源

来源链接说明
OpenClaw 官方文档https://docs.OpenClaw.ai多模态功能文档
OpenClaw GitHubhttps://github.com/OpenClaw/OpenClaw源码与 Issue
ImageMagick 文档https://imagemagick.org/script/command-line-processing.php图片处理参考
Puppeteer 文档https://pptr.dev浏览器自动化参考

本章小结

  • 多模态概述:OpenClaw 通过 Skills 和 MCP 扩展了文本之外的处理能力,支持图片、网页、文件等多种模态。
  • 媒体管理:统一的 media/ 目录结构和元数据管理,配合 Cron 自动清理旧文件。
  • 图片处理:支持 AI 视觉模型直接分析图片,也可通过 Skill 执行批量处理。
  • 网页抓取:Browser Relay 处理动态页面,HTTP 请求处理静态页面,配合 Cron 实现定期监控。
  • 平台集成:通过 MCP Skill 与小红书等第三方平台进行媒体内容交互。
  • 大文件处理遵循"先压缩/分块/摘要,再传入模型"的原则,避免浪费计算资源。

下一章:25-进阶开发实践