Cloudflare Workers AI 图像生成技能

该技能支持两种基于 Cloudflare Workers AI 的图像工作流：

• text2img → 根据提示词生成全新图像
• img2img → 基于源图像和提示词进行图像变换

使用配套脚本执行：

python3 scripts/cf_workers_ai_image.py  "" [options]

脚本从环境变量读取认证凭据，因此该技能可在基于 Docker 的 OpenClaw 部署中无缝运行。

触发指引

当用户通过 Cloudflare Workers AI 提出以下任一需求时，请调用此技能：

• 根据文本提示生成全新图像
• 生成图片、插画、概念艺术、海报、壁纸、头像或封面图
• 将现有图像转换为其他风格或构图
• 以原图作为基础，进行全局性重绘、风格迁移或整体修改
• 在 Cloudflare 上使用 Stable Diffusion 系列模型执行 text2img 或 img2img

典型触发语句包括：

• "用 Cloudflare Workers AI 生成图片"
• "用 Workers AI 做文生图"
• "用 SDXL 生成一张图"
• "把这张图改成水彩风"
• "基于这张图重绘"
• "用 img2img 改图"
• "用 Workers AI 改这张图片风格"

模式选择指引：

• 若无源图像，且用户希望仅凭提示词生成新图像，请选择 text2img 模式。
• 若有源图像，且用户希望进行全局性变换、风格迁移或保持构图的编辑，请选择 img2img 模式。

若用户要求局部区域编辑、对象替换或基于掩码（mask）的重绘，该技能不再支持此类工作流。

必需的环境变量

当用户询问如何通过 Docker Compose 传递凭据时，请参考 references/docker-compose-env-example.md。

必需变量：

• CF_ACCOUNT_ID
• CF_API_TOKEN

任一变量缺失时，脚本将明确报错并退出。

默认模型

脚本默认使用以下 Workers AI 模型标识符：

• text2img → @cf/stabilityai/stable-diffusion-xl-base-1.0
• img2img → @cf/runwayml/stable-diffusion-v1-5-img2img

如 Cloudflare 更改模型命名，或用户需指定其他兼容的 Workers AI 模型，可通过 --model 参数覆盖默认值。

命令示例

1) 文生图（Text to image）

python3 scripts/cf_workers_ai_image.py text2img "a cozy cabin in snowy mountains, cinematic lighting" --output /tmp/openclaw/

可选参数示例：

python3 scripts/cf_workers_ai_image.py text2img "a cozy cabin in snowy mountains, cinematic lighting" 
  --negative-prompt "blurry, low quality, distorted" 
  --num-steps 30 
  --guidance 7.5 
  --width 1024 
  --height 1024 
  --seed 42 
  --output /tmp/openclaw/

2) 图生图（Image to image）

python3 scripts/cf_workers_ai_image.py img2img "turn this into a watercolor illustration" 
  --image ./input/source.png 
  --strength 0.65 
  --output /tmp/openclaw/

配套脚本会将源图像编码为 base64 字符串（字段名：image_b64），以确保与 Workers AI 兼容。

对话工作流

当您请求生成或处理图像时，请按以下步骤执行：

1. 判断模式（text2img 或 img2img），并将用户请求转化为规范提示词。
2. 运行 scripts/cf_workers_ai_image.py，并传入 --output /tmp/openclaw/ 参数。
3. 脚本将图像保存至指定临时目录，并将完整文件路径打印到标准输出（stdout）。
4. 通过当前对话提供方（conversation provider）所要求的图像/文件发送格式，将图像回传给用户。
5. 成功发送后，除非用户明确要求保留，否则立即删除临时图像文件。

提供方特定的图像发送规则

该技能仅负责图像生成与本地保存。不定义通用的图像发送格式。

在聊天中返回生成或编辑后的图像时，必须始终遵循当前会话提供方所要求的出站媒体格式（outbound media format）。不同提供方可能要求不同的发送方式、封装格式或工具。请切勿假设读取本地路径、简单回显文件路径，或依赖某一个提供方的自动路由行为能在所有提供方上通用。

必须遵守的行为规范：

• 发送前，先识别当前会话提供方/渠道。
• 使用该提供方所要求的正确媒体发送路径与语法。
• 若提供方要求特定封装（wrapper）或消息格式用于出站图像，请严格采用。
• 若提供方无法稳定地从本地文件读取并自动发送图像，则不得依赖该降级方案。
• 应将图像发送视为提供方专属行为，而非技能通用能力。

当前聊天会话的自动发送工作流

当运行时环境支持将生成图像自动回传至活跃对话时，推荐采用以下流程：

1. 使用 scripts/cf_workers_ai_image.py --output /tmp/openclaw/ 生成图像。
2. 捕获脚本输出到 stdout 的文件路径。
3. 使用当前活跃提供方所要求的出站媒体格式（而非泛化的仅路径假设）将图像发送至当前聊天会话。
4. 附带简短说明文字，注明结果来自 text2img 还是 img2img。
5. 发送成功后立即删除临时文件。
6. 仅当用户明确要求保存时，才将文件存入持久化位置。

推荐的说明文字：

• text2img → 按你的提示生成好了。
• img2img → 按你的源图和提示改好了。

若为迭代式请求，请在说明中指出新版变化点，例如风格调整、提示词侧重变更或源图像引导增强等。

参数说明

• mode: text2img | img2img
• 位置参数 prompt: 提示词文本
• --image: img2img 模式下为必填项
• --output: 必填项，指定输出文件路径或目录；常规聊天交付请使用临时目录；仅当用户明确要求保存文件时，才使用持久化路径
• --model: 可选，用于覆盖默认模型
• --negative-prompt: 可选，负向提示词
• --num-steps: 可选，采样步数
• --guidance: 可选，引导尺度（guidance scale）
• --strength: 可选，变换强度（仅 img2img）
• --width、--height: 可选，text2img 输出尺寸（取决于模型是否支持）
• --seed: 可选，随机种子
• --timeout: HTTP 请求超时时间（秒）

脚本职责止于生成图像文件并打印其保存路径。调用方须依据当前聊天提供方所要求的图像发送格式，自行完成出站交付。

冒烟测试（Smoke testing）

在修改 API 脚本或凭据后，请运行配套冒烟测试脚本：

python3 scripts/smoke_test.py

该脚本执行以下操作：

• 校验 CF_ACCOUNT_ID 和 CF_API_TOKEN 是否已设置
• 生成本地 PNG 输入文件供 img2img 测试使用
• 执行一次 text2img 请求
• 执行一次 img2img 请求
• 验证每次命令均成功写入图像文件，并输出可用的保存路径
• 输出 JSON 汇总报告；任一模式失败则以非零状态码退出

冒烟测试用于验证连接性及重大回归问题，不用于评估图像质量。

故障排查

凭据缺失

若脚本报错提示缺少必需环境变量，请通过 Docker Compose 注入 CF_ACCOUNT_ID 和 CF_API_TOKEN。参见 references/docker-compose-env-example.md。

返回 JSON 而非图像

Workers AI 在发生错误或校验失败时可能返回 JSON 响应。请完整透出 JSON 响应体内容。

存储策略

默认策略为临时文件交付：

• 常规聊天交付时，生成至本地临时路径
• 返回已保存的文件路径，以便 OpenClaw 将文件发送至当前对话
• 发送成功后立即删除临时文件
• 仅当用户明确要求时，才保留本地持久化副本

401 / 403 错误

API Token 缺失、无效、已过期，或未授予对应 Cloudflare 账户所需的权限。

404 / 模型未找到

Cloudflare 可能已更改模型标识符。请使用当前 Workers AI 模型名称，通过 --model 参数重试。

输入图像问题

建议尽可能使用 PNG 格式作为源图像。

相关资源

scripts/cf_workers_ai_image.py

该脚本用于确定性、可复现的 Cloudflare Workers AI 图像生成与编辑任务。

scripts/smoke_test.py

该脚本用于对所有支持模式进行快速端到端连通性与输出格式冒烟测试。