图片处理

使用内置 Agent 执行器处理新消息时，AstrBot 默认会在发送图片给模型前按需处理图片，减少格式不兼容的问题。处理不会覆盖原图。

配置

在管理面板的 配置文件 页面搜索 启用图片压缩。该选项默认开启，关闭后不再缩放、转码或生成动图拼图。

最大边长默认为 1280 像素，静图和动图拼图共用此设置，小图不会放大。压缩质量（1-100，默认 95）控制 JPEG 输出的画质与体积。

TIP

当“电脑使用”运行时为沙箱且沙箱 Booter 为 CUA 时，为避免像素坐标漂移，输入图片不按最大边长缩放，合规图片原样发送（不重新编码，避免 JPEG 变色）；格式转换与动图拼图等其余处理仍然生效。超过约 5 MB 的大图可能超出服务商的图片体积限制，此时日志会给出警告。

处理方式

• 合规静图原样发送：已是 JPEG/PNG、方向正常且未超过最大边长的图片不做任何改动。
• 其余静图按需转换：方向异常、尺寸超限或格式不通用的图片会修正方向、缩放后重新编码。无透明度的图片输出 JPEG（16 位等高位深图片会归一化为 8 位）；含透明度的图片输出 PNG，若 PNG 超过 1 MB 则扁平化为白底 JPEG，控制发送体积。
• 动图：从 GIF、动画 WebP、APNG 等图片中均匀选取最多 9 帧，包含首尾动画帧，生成白底 3×3 拼图；不足 9 帧的格子留白。单帧 GIF 和静态 WebP 按静图处理。
• 无法读取或解码的图片：跳过该图片，其他文字和正常图片继续处理。

TIP

如需更小的请求体积，可调低“最大边长”或“压缩质量”。

文件保留与清理

预处理成功本地化的附件原图，以及请求收集成功接管的原图（含引用图片），不会在事件结束时立即删除，附件说明继续引用这些原图路径。模型使用的派生文件和仅用于请求的下载文件仍随事件清理；请求收集失败或取消时，新生成且尚未接管的原图也会清理。临时目录中的保留文件仍受 temp_dir_max_size 容量清理约束，不属于永久存储。

NOTE

本功能仅适用于经过本地消息流水线的本次输入，包括引用图片。工具回图、第三方 Agent 后端及插件绕过流水线直接调用模型不在处理范围内。会话历史保存模型实际看到的图片内容，不会重新转换旧图片。