画布工作区#

!! 激活后立即执行以下流程#

当此 skill 被激活时，你必须按顺序执行以下步骤，不要跳过任何一步。

步骤 1：启动画布工作区#

bash

npx deepminer-claw-canvas@latest

启动过程说明（告知用户）：

1. 首次运行会自动安装 Python 依赖（可能需要 1-2 分钟）
2. 依赖安装完成后启动服务（可能需要 10-30 秒）
3. 看到 Application startup complete 才表示启动成功
4. 启动成功后会自动打开浏览器
5. 默认地址： http://localhost:39301/claw
6. 如果端口被占用会自动切换到下一个可用端口， 以终端输出的实际地址为准

如需指定端口： CLAW_PORT=8080 npx deepminer-claw-canvas@latest

重要：

• 服务启动后保持终端运行
• 后续的 gen/ edit/ push 命令需要 在新终端中执行
• 如果服务端口不是默认的 39301，执行脚本时需指定： CLAW_PORT=实际端口 npx deepminer-claw-canvas@latest gen ...

步骤 2：收集图片模型环境变量#

主动向用户询问 图片模型配置。必须明确说明： 生图模型 和 编辑图模型 是两种用途，建议分开配置。

同时提醒用户： 如果 Claw Agent 所用底模具备多模态能力（能看图），处理图片编辑、标记理解、附件理解时效果通常更好；但这不是强制要求，是否切换模型由用户自行决定。

对用户这样说：

画布的图片能力需要两类模型： 文生图模型 和 编辑图模型，请分别提供对应的 API Key。

目前项目内置了 Qwen 的案例脚本，可以直接使用。如果你有 Qwen（通义万象 / DashScope）的 API Key，只需提供一个 Key 即可同时用于文生图和编辑图。

如果你想接入其他模型，可以参考内置脚本的写法，新写一个独立 Python 脚本。内置脚本在 npm 包内的 skills/canvas-workspace/scripts/ 目录。

如果暂时没有 API Key，画布基础能力（查看状态、推送已有图片）仍可使用，但无法生成或编辑新图片。

步骤 3：设置环境变量#

用户提供变量后， 必须设置为系统永久环境变量，不要设置临时变量（临时变量关闭终端后就失效）。

每类模型需要三个变量： API_KEY（必填）、 MODEL（模型名）、 BASE_URL（API 地址）。

使用 Qwen 案例脚本（默认）

Windows（设置永久用户环境变量）：

powershell

[Environment]::SetEnvironmentVariable("QWEN_TEXT_IMAGE_API_KEY", "用户提供的值", "User")
[Environment]::SetEnvironmentVariable("QWEN_TEXT_IMAGE_MODEL", "qwen-image-2.0-pro", "User")
[Environment]::SetEnvironmentVariable("QWEN_BASE_URL", "https://dashscope.aliyuncs.com/api/v1", "User")

[Environment]::SetEnvironmentVariable("QWEN_EDIT_IMAGE_API_KEY", "用户提供的值", "User")
[Environment]::SetEnvironmentVariable("QWEN_EDIT_IMAGE_MODEL", "qwen-image-edit", "User")

设置后需要 重启终端 才能生效。

Mac/Linux（追加到 ~/.bashrc 或 ~/.zshrc）：

bash

echo 'export QWEN_TEXT_IMAGE_API_KEY="用户提供的值"' >> ~/.bashrc
echo 'export QWEN_TEXT_IMAGE_MODEL="qwen-image-2.0-pro"' >> ~/.bashrc
echo 'export QWEN_BASE_URL="https://dashscope.aliyuncs.com/api/v1"' >> ~/.bashrc

echo 'export QWEN_EDIT_IMAGE_API_KEY="用户提供的值"' >> ~/.bashrc
echo 'export QWEN_EDIT_IMAGE_MODEL="qwen-image-edit"' >> ~/.bashrc

source ~/.bashrc

如果文生图和编辑图使用同一个 Qwen Key，两个 API_KEY 填同一个值即可。 QWEN_BASE_URL 有默认值，不设也行；如果用新加坡地域需改成 https://dashscope-intl.aliyuncs.com/api/v1。

使用自定义模型

如果用户要接入其他生图/编辑图模型，需要：

1. 参考内置 Qwen 脚本（npm 包内 skills/canvas-workspace/scripts/ 目录），新写一个 Python 脚本；
2. 在脚本中定义该模型自己的环境变量（命名建议： {PROVIDER}_TEXT_IMAGE_API_KEY、 {PROVIDER}_TEXT_IMAGE_MODEL、 {PROVIDER}_BASE_URL 等）；
3. 设置永久环境变量。

示例（假设接入 Gemini 文生图，Windows）：

powershell

[Environment]::SetEnvironmentVariable("GEMINI_TEXT_IMAGE_API_KEY", "用户提供的值", "User")
[Environment]::SetEnvironmentVariable("GEMINI_TEXT_IMAGE_MODEL", "gemini-3.1-flash-image", "User")
[Environment]::SetEnvironmentVariable("GEMINI_BASE_URL", "https://api.example.com/v1", "User")

设置完成后告知用户画布已就绪，可以开始使用。

以上 3 步完成后，画布工作区已就绪。后续用户发送的生图/编辑请求，按下方「决策指引」处理。

---

决策指引#

用户意图操作文生图（Qwen）npx deepminer-claw-canvas gen --prompt "..."文生图（Gemini）npx deepminer-claw-canvas gen --prompt "..." --provider gemini标记编辑（消息含画布图片文件 URL）npx deepminer-claw-canvas edit --prompt "..." --markers-file "<画布图片文件URL>"自由编辑 / 图生图 / 多图融合npx deepminer-claw-canvas edit --prompt "..." --raw-image <图片URL>推送已有图片到画布npx deepminer-claw-canvas push --url "..."查看画布当前状态Invoke-RestMethod -Uri "http://localhost:<端口>/api/canvas/sync/debug"

能力边界#

允许禁止生成/编辑图片删除画布上的图片查看画布状态移动、缩放、旋转画布上的图片用 Qwen 案例脚本作为其他模型接入模板在画布上添加标记（仅用户可操作）

Qwen 案例脚本#

Qwen 脚本是 MVP 样板，不是统一 provider 框架。

如果未来要接别的模型：

1. 复制 Qwen 脚本结构；
2. 使用目标模型自己的 SDK；
3. 定义该模型自己的 ENV；
4. 保持相同的调用风格与输出 JSON（尽量一致）。

工具模块#

脚本目录下提供了可复用的工具模块，用户构建自定义脚本时可直接导入使用：

模块用途image_to_base64.py将图片地址（网络 URL 或本地路径）转为 base64 data URLpush_to_canvas.py将图片推送到画布（远程 URL 会自动下载转为本地 URL）

使用示例（在自定义脚本中）：

python

from image_to_base64 import image_to_base64
from push_to_canvas import push_to_canvas

# 图片转 base64，用于传给 AI 模型
base64_url = image_to_base64("https://example.com/image.png")

# 推送图片到画布（远程 URL 自动转本地，避免跨域问题）
element_id, local_url = push_to_canvas("https://example.com/result.png")

1) 文生图脚本#

bash

# 使用 Qwen（默认）
npx deepminer-claw-canvas gen --prompt "一张极简海报，蓝白配色"

# 使用 Gemini
npx deepminer-claw-canvas gen --prompt "一张极简海报" --provider gemini

参数必填说明--prompt是文生图提示词--size否输出尺寸，如 1024*1024``--provider否模型提供商（qwen/gemini），默认 qwen

生成的图片默认推送到画布。

2) 编辑图脚本#

两种调用方式（互斥），生成的图片默认推送到画布：

bash

# 标记编辑：从画布图片文件读取原图/标记图（URL 从用户消息中获取）
npx deepminer-claw-canvas edit --prompt "把<<标记点1>>修改为蓝色" --markers-file "<画布图片文件URL>"

# 自由编辑：直接传原图（URL 从用户消息中获取）
npx deepminer-claw-canvas edit --prompt "变成卡通风格" --raw-image "<图片URL>"

# 自由编辑（多图）
npx deepminer-claw-canvas edit --prompt "把图一的人物放到图二的背景上" --raw-image "img1.png" --raw-image "img2.png"

参数必填说明--prompt是编辑指令--markers-file与 --raw-image 二选一画布图片文件 URL 或本地路径（标记编辑模式）--raw-image与 --markers-file 二选一原图 URL 或本地路径，可多次传入（自由编辑模式）

3) 推送图片脚本#

直接将已有图片 URL 推送到画布：

bash

npx deepminer-claw-canvas push --url "https://example.com/image.png"

输出约定#

脚本输出 JSON，格式尽量一致：

json

{"status":"ok","url":"https://...","local_url":"http://localhost:39301/uploads/...","element_id":"gen_xxx","pushed":true}

说明：

• url：AI 模型返回的原始图片 URL（可能是远程 OSS 地址）
• local_url：推送到画布的本地 URL（远程图片会自动下载转存）
• element_id：画布上的元素 ID
• pushed：是否成功推送到画布， false 表示推送失败但图片生成/编辑本身已成功

画布操作 API#

接口用途POST /api/canvas/sync/gen_image推送图片到画布GET /api/canvas/sync/debug查看画布状态POST /api/canvas/sync/inject_image批量注入图片

API 详情#

POST /api/canvas/sync/gen_image

推送图片到画布。

bash

curl -X POST http://localhost:<端口>/api/canvas/sync/gen_image \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/image.png"}'

GET /api/canvas/sync/debug

查看画布当前状态（图片列表、标记等）。

bash

curl http://localhost:<端口>/api/canvas/sync/debug

画布图片协议#

用户在画布上选择图片或标记图片后发消息，消息末尾附带画布图片文件 URL。文件中包含所有与画布相关的图片信息。

消息示例：

text

请把 <<标记点1>> 修改为蓝色，参考我选中的那张图片的配色

画布图片文件: http://localhost:<端口>/uploads/canvas_images_xxx.json

文件结构#

json

{
  "canvas_markers": [
    {
      "id": "img_B",
      "raw_image": "http://localhost:<端口>/uploads/original_B.png",
      "marked_image": "http://localhost:<端口>/uploads/marked_B.png",
      "markers": [1, 2]
    }
  ],
  "selected_images": [
    {
      "id": "img_A",
      "raw_image": "http://localhost:<端口>/uploads/selected_A.png"
    }
  ]
}

字段含义canvas_markers有标记的图片列表（原图 + 标记图 + 标记点编号）selected_images用户选中但未标记的图片列表（仅原图）raw_image无标记的原始图 URLmarked_image带彩色标记框的合成图 URLmarkers标记点编号列表，对应消息中的 <<标记点N>>

处理规则#

1. 从消息末尾提取画布图片文件 URL
2. 消息中有「画布图片文件」URL → 直接传给 edit --markers-file <URL>，脚本内部会自动下载和解析
3. 消息中只有普通图片 URL（无标记） → 调用 edit --raw-image <URL>
4. 两者都有 → 根据用户意图决定调用方式

环境变量参考#

Qwen 文生图#

环境变量何时必填默认值QWEN_TEXT_IMAGE_API_KEY使用 Qwen 文生图时—QWEN_TEXT_IMAGE_MODEL否qwen-image-2.0-pro``QWEN_BASE_URL否https://dashscope.aliyuncs.com/api/v1

Qwen 编辑图#

环境变量何时必填默认值QWEN_EDIT_IMAGE_API_KEY使用 Qwen 编辑图时—QWEN_EDIT_IMAGE_MODEL否qwen-image-edit

Gemini 文生图#

环境变量何时必填默认值GEMINI_TEXT_IMAGE_API_KEY使用 Gemini 文生图时—GEMINI_TEXT_IMAGE_MODEL否gemini-3.1-flash-image``GEMINI_BASE_URL否https://api.mmw.ink

公共配置#

环境变量何时必填默认值CANVAS_SERVER否http://localhost:<端口>（默认 39301）

Windows 环境注意事项#

• curl 在 PowerShell 中是 Invoke-WebRequest 的别名，参数不兼容。获取 HTTP 数据请使用 Invoke-RestMethod -Uri "<URL>"，不要用 curl。
• web_fetch 等 MCP 工具无法访问 localhost 地址，获取本地服务数据必须用命令行。
• 执行 shell 命令时使用 PowerShell 语法，不要使用 cmd 语法（ & 串联命令在 PowerShell 中报错）。
• PowerShell 中文错误输出可能显示为乱码（GBK/UTF-8 编码冲突），遇到乱码时根据上下文推断含义，不要将乱码原文展示给用户。

External Endpoints#

URL发送的数据https://dashscope.aliyuncs.com/api/v1Qwen 文生图/编辑图请求（prompt、图片 URL）https://api.mmw.inkGemini 文生图请求（prompt）http://localhost:<端口>/api/canvas/sync/*本地画布服务（图片推送、状态查询）

Security & Privacy#

• 会离开本机的数据：用户输入的 prompt、待编辑图片的 URL（发送至 Qwen/Gemini API）
• 不会离开本机的数据：本地文件内容、环境变量值、画布状态数据
• 所有对外网络请求均通过 HTTPS 加密传输
• 本地画布服务仅监听 localhost，不暴露到外网

Model Invocation Note#

本 Skill 可能由 OpenClaw 在对话中自主调用，属正常行为。 如不希望自动调用，可在 OpenClaw 设置中关闭该 Skill 的自动触发权限。

Trust Statement#

使用本 Skill 时，您的 prompt 和图片 URL 将发送至阿里云 DashScope（Qwen）或第三方 Gemini 代理服务。 请仅在信任这些服务的前提下安装和使用本 Skill。