hal-image

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install hal-image
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 hal-image。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

hal-image 是一项代理安全的图像处理技能，围绕 ImageMagick 的 magick 命令和 oxipng 优化器构建。它支持元数据检查、调整大小、裁剪、旋转、格式转换、图像合成、网格、叠加层和文字水印。
该技能的核心原则是在交付前压缩每张图像，避免泄露本地文件系统路径，并在工具或操作不可用时采取故障开放策略。作为 Openclaw Skills 的一部分，它有助于在保留无损压缩时图像像素的同时，减少传输大小、多模态 token 使用量和上传失败。

应用场景

在处理前检查图像格式、尺寸、色深和文件大小。
在读取或发送大型截图、照片、图表或生成的图像前调整其大小。
为目标格式裁剪、旋转、去饱和、转换或扁平化透明图像。
水平、垂直组合多张图像，或将其拼接成平铺 collage。
添加 logo 叠加层或使用明确字体的文字水印。
在将 PNG 文件附加到消息或上传前进行无损压缩。
在安装可选的格式专用工具后优化 JPEG 和 WebP 资源。
当 ImageMagick、压缩器或处理步骤失败时，继续交付原始资源。

工作原理

检测图像处理请求、生成的资源、传入的图像或待发送的附件。
使用 magick --version 和 oxipng --version 检查工具是否可用。
使用 ImageMagick 元数据命令检查源文件，以确定格式、尺寸、色深和字节大小。
判断图像是否需要调整大小、裁剪、转换、合成、添加水印或执行其他变换。
使用 magick 执行所需操作；使用 montage 创建网格和拼贴图。
选择适当的压缩路径：PNG 使用 oxipng，JPEG 使用 jpegoptim，无损 WebP 输出使用 cwebp。
可选地使用 ImageMagick RMSE 比较源文件和输出，以验证像素一致性。
如果工具或命令失败，则传递原始图像，而不是阻塞任务。
在不暴露本地文件系统路径的情况下交付处理后的资源。

配置指南

通过 Homebrew 在 macOS 或 Linux 上安装 ImageMagick 和 oxipng：
brew install imagemagick oxipng
JPEG 和 WebP 工作流的可选压缩器：
brew install jpegoptim webp
验证所需的二进制文件：
magick --version
oxipng --version
根据其 OpenClaw 元数据，该技能需要 magick 和 oxipng。jpegoptim 和 cwebp 是可选的。处理资源前，使用以下命令检查：
identify -format '%m %wx%h %[bit-depth]-bit %[size] bytes\n' image.png
对于文字水印，请配置有效的系统字体路径。如果不存在可用字体，则跳过水印并继续。发送前始终压缩最终图像：
oxipng -o max --strip safe image.png
如果压缩不可用或发生错误，则原样交付未更改的原始图像。

数据架构

该技能使用本地图像文件作为工作数据模型，不强制要求数据库模式。
数据元素 用途
源图像 选定用于检查或转换的传入、生成或渲染资源。
元数据 使用 identify 读取的格式、宽度、高度、色深和字节大小。
中间资源 可选的调整大小、裁剪、合成、转换或添加水印后的文件。
最终交付资源 在附加或上传前立即压缩的处理后图像。
压缩元数据 例如 -o max 和 --strip safe 等 PNG 优化设置；在可选工具可用时也包括 JPEG 或 WebP 设置。
验证结果 可选的 RMSE 比较，其中 0 表示像素数据完全相同。
常见文件输出包括 PNG、JPEG 和 WebP 资源。操作可能会原地重写文件，或创建 staged.png、out.jpg、grid.png 或 image.small.jpg 等暂存输出。该工作流不会向最终用户暴露本地路径。其元数据分类由技能清单定义：名称 hal-image、MIT 许可证、版本 1.1.0、作者 ofoxai、所需二进制文件、emoji 以及仓库主页。

高级特性

当缺少
magick
、
oxipng
、字体或可选压缩器时，故障开放行为可保持任务连续性。
oxipng -o max --strip safe
进行无损 PNG 优化，在不改变像素的情况下减小文件大小。
格式感知压缩支持 PNG、JPEG 和 WebP 工作流。
RMSE 验证可确认压缩后的 PNG 仍与原图像素完全一致。
多图像合成支持水平排列、垂直堆叠以及可配置的
montage
网格。
logo 叠加层使用 gravity 和 geometry 控制进行精确定位。
明确发现字体可避免因缺少默认字体导致的 ImageMagick 水印失败。
单次变换可组合旋转、灰度转换、调整大小、扁平化和格式更改。
元数据优先处理有助于代理在将超大输入加载到上下文前减小其大小。
该技能的 Openclaw Skills 工作流适用于接收的图像以及必须安全交付的新生成资源。

name: hal-image description: Handle images with ImageMagick (magick) — read metadata, resize, crop, rotate, convert format, combine images (side-by-side or grids with montage), overlay logos/watermarks, and losslessly compress with oxipng before sending. Use when the user sends an image to process, when you produce an image to deliver, or before attaching any image to a message or upload — compressing first keeps transfers fast and tokens low. Core discipline - always compress before delivering, never expose local file paths to the user, and fail open (if a tool is missing or a step errors, pass the original through unchanged; never block the task). license: MIT
version: "1.1.0"
homepage: https://github.com/ofoxai/skills/tree/main/skills/hal-image