omni-flow-canvas

画布编辑器 + OpenClaw 聊天工作台。

环境要求

| 工具 | 版本 | |------|------| | Node.js | >= 22 | | Python | >= 3.11 | | OpenClaw CLI | 已安装且在 PATH 中 |

启动前先消除命令差异

不同机器上的命令名可能不一样，先确认这几个 GAP：

1. pnpm 可能不存在

先检查：

pnpm -v

如果提示找不到命令，先安装：

npm install -g pnpm

2. Python 命令可能是 py、python 或 python3

按下面顺序检查，能返回版本号的那个就是你本机可用命令：

py --version
python --version
python3 --version

3. pip 也可能需要挂在 Python 命令后面执行

优先尝试：

py -m pip --version
python -m pip --version
python3 -m pip --version

后面安装依赖时，使用你本机实际可用的那套命令。

快速启动

推荐启动方式：安装完依赖后，直接执行项目根目录的 start.js。

原因：

1. 这个项目需要同时启动前端和后端；
2. 执行环境在命令完成后会回收当前 shell；
3. 如果直接在 bash 里启动前端/后端，进程容易被 shell 一起带掉；
4. start.js 会用 Node 异步拉起前后端，更适合当前使用方式。

当前固定端口：

• 前端：http://localhost:39300
• 后端：http://localhost:39301

1. 安装前端依赖

pnpm install

2. 安装 Python 依赖

根据你本机可用命令选择一种：

# Windows 常见
py -m pip install -r requirements.txt

# Linux / 部分 Windows
python -m pip install -r requirements.txt

# macOS 常见
python3 -m pip install -r requirements.txt

3. 使用 start.js 启动画布前后端

node start.js

它会异步启动：

• Python/FastAPI 后端：39301
• webpack dev server 前端：39300

前端所有 /api/ 和 /uploads/ 请求会自动代理到后端 localhost:39301。

4. 访问

浏览器打开 http://localhost:39300 即可，根路径 / 会自动跳转到 /claw。

页面路由

| 路径 | 页面 | |------|------| | / | 自动跳转到 /claw | | /canvas | 画布编辑器 | | /claw | OpenClaw 聊天工作台 |

环境变量（可选）

| 变量 | 默认值 | 说明 | |------|--------|------| | OPENCLAW_STATE_DIR | ~/.openclaw | OpenClaw 会话数据目录 | | OPENCLAW_GATEWAY_HOST | 127.0.0.1 | Gateway 主机 | | OPENCLAW_GATEWAY_PORT | 18789 | Gateway 端口 | | CANVAS_PORT | 39301 | 后端端口（用于 Gateway Origin 注册） | | OPENCLAW_GATEWAY_TOKEN | 从配置文件读取 | Gateway 认证 token |

OpenClaw Skills

skills/ 目录存放 OpenClaw Agent 的技能包，Agent 根据用户意图自动激活对应技能。

| Skill | 说明 | |-------|------| | canvas-workspace | 画布工作区能力：Qwen 文生图/编辑图案例脚本、画布操作 API、标记协议解析 |

技能包结构遵循 SKILL.md + scripts/ + references/ 规范，详见各技能的 SKILL.md。

项目结构

src/
├── Pages/
│   ├── TestPage33/          # 画布编辑器
│   │   ├── CanvasEditor/    # 编辑器组件
│   │   ├── core/            # 编辑器内核
│   │   └── plugins/         # 插件
│   └── ClawWorkspace/       # OpenClaw 工作台
│       ├── SessionList/     # 会话列表
│       ├── ChatPanel/       # 聊天面板
│       │   ├── hooks/       # useChat / useClawSSE / usePolling
│       │   ├── SlotInput/   # Slate 富文本输入
│       │   ├── Markdown/    # Markdown 渲染
│       │   └── MessageBubble.tsx
│       └── CanvasPanel/     # 画布面板
skills/
└── canvas-workspace/        # OpenClaw 画布技能包
    ├── SKILL.md             # 技能说明
    ├── scripts/             # 生图脚本
    └── references/          # API 参考文档
server/
├── app.py                   # FastAPI 入口
├── config.py                # 端口、上传配置
├── gateway/                 # Gateway WS 客户端 + 认证 + SSE
├── routers/
│   ├── claw.py              # OpenClaw API
│   ├── sync.py              # 画布同步
│   ├── upload.py            # 图片上传
│   └── gaoding.py           # 稿定授权
└── services/
    ├── sessions.py          # 会话扫描
    └── transcript.py        # JSONL 消息解析

常见问题

pnpm 命令不存在

先执行：

npm install -g pnpm

然后重新运行：

pnpm install

不确定该用 py、python 还是 python3

直接依次执行：

py --version
python --version
python3 --version

哪个能成功返回版本号，就用哪个来执行 Python 和 pip 命令。

Gateway 连接失败

1. 确认 openclaw gateway 进程在运行：curl http://127.0.0.1:18789/health
2. 确认 ~/.openclaw/openclaw.json 中有正确的 auth 配置
3. 后端启动日志会打印 [Gateway] handshake OK 表示连接成功

没有会话数据

确认 ~/.openclaw/agents/ 目录下有 agent 子目录，且包含 sessions/sessions.json 和 .jsonl 文件。如果是新环境需要先用 OpenClaw 创建至少一个会话。

环境诊断

遇到问题时运行诊断脚本，会逐项检查工具、依赖、服务状态并给出修复建议。

根据你本机可用命令选择一种：

# Windows 常见
py scripts/doctor.py

# Linux / 部分 Windows
python scripts/doctor.py

# macOS 常见
python3 scripts/doctor.py