画布工作区

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

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

步骤 1：启动画布工作区

CODEBLOCK0

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

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

如需指定端口：INLINECODE1

重要：

• - 服务启动后保持终端运行
• 后续的 gen/edit/push 命令需要在新终端中执行
• 如果服务端口不是默认的 39301，执行脚本时需指定：INLINECODE5

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

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

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

对用户这样说：

画布的图片能力需要两类模型：文生图模型 和 编辑图模型，请分别提供对应的 API Key。
目前项目内置了 Qwen 的案例脚本，可以直接使用。如果你有 Qwen（通义万象 / DashScope）的 API Key，只需提供一个 Key 即可同时用于文生图和编辑图。
如果你想接入其他模型，可以参考内置脚本的写法，新写一个独立 Python 脚本。内置脚本在 npm 包内的 skills/canvas-workspace/scripts/ 目录。
如果暂时没有 API Key，画布基础能力（查看状态、推送已有图片）仍可使用，但无法生成或编辑新图片。

步骤 3：设置环境变量

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

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

使用 Qwen 案例脚本（默认）

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

CODEBLOCK1

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

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

CODEBLOCK2

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

使用自定义模型

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

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

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

CODEBLOCK3

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

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

决策指引

能力边界

Qwen 案例脚本

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

如果未来要接别的模型：

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

工具模块

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

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

CODEBLOCK4

1) 文生图脚本

CODEBLOCK5

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

2) 编辑图脚本

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

CODEBLOCK6

3) 推送图片脚本

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

CODEBLOCK7

输出约定

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

CODEBLOCK8

说明：

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

画布操作 API

API 详情

POST /api/canvas/sync/gen_image

推送图片到画布。

CODEBLOCK9

GET /api/canvas/sync/debug

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

CODEBLOCK10

画布图片协议

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

消息示例：

CODEBLOCK11

文件结构

CODEBLOCK12

处理规则

1. 1. 从消息末尾提取画布图片文件 URL
2. 消息中有「画布图片文件」URL → 直接传给 edit --markers-file <URL>，脚本内部会自动下载和解析
3. 消息中只有普通图片 URL（无标记） → 调用 INLINECODE43
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。