canvas-workspace（画布工作区）

画布工作区

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

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

步骤 1：启动画布工作区

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（设置永久用户环境变量）：

[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）：

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）：

[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 案例脚本

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

如果未来要接别的模型：

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

工具模块

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

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

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) 文生图脚本

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

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

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

2) 编辑图脚本

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

# 标记编辑：从画布图片文件读取原图/标记图（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"

3) 推送图片脚本

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

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

输出约定

脚本输出 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

API 详情

POST /api/canvas/sync/gen_image

推送图片到画布。

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

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

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

画布图片协议

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

消息示例：

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

画布图片文件: http://localhost:<端口>/uploads/canvas_images_xxx.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"
    }
  ]
}

处理规则

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

环境变量参考

Qwen 文生图

Qwen 编辑图

Gemini 文生图

公共配置

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

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。