chore: release v0.18.2

.github/workflows/release.yml

@@ -374,7 +374,7 @@ jobs:
             echo "3. 如未安装 OpenClaw，按提示一键安装即可"
             echo "4. 安装完成后自动跳转仪表盘，开始使用"
             echo ""
-            echo '> **系统要求**：Node.js 18+（推荐 22 LTS）'
+            echo '> **系统要求**：ClawPanel Web 后端需要 Node.js 18+；运行 OpenClaw Gateway 会按当前 OpenClaw 的 engines.node 自动检测，建议 Node.js 22.19.0+。'
             echo ""
             echo "---"
             echo ""
@@ -382,7 +382,7 @@ jobs:
             echo "${CHANGELOG_BODY}"
             echo "---"
             echo ""
-            echo "📖 [项目主页](https://github.com/${REPO}) · 💬 [反馈问题](https://github.com/${REPO}/issues) · 📣 [QQ 群](https://qt.cool/c/OpenClaw)"
+            echo "📖 [项目主页](https://github.com/${REPO}) · 💬 [反馈问题](https://github.com/${REPO}/issues) · 📣 [QQ 群](https://qt.cool/c/OpenClaw) · Telegram: https://t.me/clawpanel"
           } > release_body.md
 
           gh release edit "$TAG_NAME" --notes-file release_body.md

CHANGELOG.md

@@ -5,6 +5,33 @@
 格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.18.2] - 2026-06-08
+
+### 修复 (Fixes)
+
+- **Node.js 版本过低导致 Gateway 启动失败** — 启动 Gateway 前会读取当前 OpenClaw 安装包的 `engines.node` 要求，发现 Node.js 不兼容时提前阻断并给出可执行提示，不再让用户看到后端崩溃日志
+- **Windows Node.js 版本过低时升级引导不足** — 设置向导在检测到 Node.js 过低时提供一键升级入口，通过 `winget upgrade/install OpenJS.NodeJS.LTS` 安装或升级 Node.js LTS，并在升级后刷新 PATH 检测
+- **自定义 Node.js 路径可选中旧版本** — 扫描和手动保存 Node.js 路径时会同步校验版本兼容性，版本不满足当前 OpenClaw 要求的路径不再允许保存
+- **macOS / Linux / Web 模式缺少同等保护** — 桌面端 macOS 启动链路、Web/headless 后端 `start_service`、路径扫描和自定义路径保存均补齐 Node.js 兼容检测
+- **新手引导误导用户创建 Agent** — 默认 `main` Agent 已内置可用；仪表盘新手步骤改为“确认默认 Agent”，有任意 Agent 即视为完成，不再要求用户创建第一个 Agent
+
+### 改进 (Improvements)
+
+- **升级弹窗体验优化** — 自动过滤 winget 进度块和旋转符号噪音；升级成功后按钮改为“完成”，并提示回到仪表盘或服务页启动 Gateway
+- **跨端 Node.js 升级提示更清晰** — Windows 显示一键升级，macOS / Linux 显示各自的手动升级建议和重启/重新检测提示
+- **Gateway 错误更用户友好** — 服务页会把 Node.js 版本过低错误转成普通用户能理解的升级提示
+- **发布文案口径统一** — Release Notes、README、多语言 README 与部署文档统一说明 Node.js 要求，避免把 ClawPanel Web 后端的 Node.js 18+ 误读为当前 OpenClaw Gateway 的完整运行要求
+
+### 测试与验证 (Testing)
+
+- 已通过 `npm run build`
+- 已通过 `node -e "import('./scripts/dev-api.js').then(()=>console.log('dev-api import ok'))"`
+- 已通过 `cd src-tauri && cargo fmt --check`
+- 已通过 `cd src-tauri && cargo check`
+- 已通过 `cd src-tauri && cargo test node_requirement --lib`
+- 已通过 `git diff --check`
+- 已通过 `npm run tauri build`（Windows NSIS / MSI 本地打包）
+
 ## [0.18.1] - 2026-06-07
 
 ### 修复 (Fixes)

CONTRIBUTING.md

@@ -31,7 +31,7 @@
 
 | 依赖 | 最低版本 | 说明 |
 |------|----------|------|
-| Node.js | 18+ | 前端构建（推荐 22 LTS） |
+| Node.js | 18+ | 前端构建与 Web 后端（推荐 22 LTS）；运行 OpenClaw Gateway 时按当前 OpenClaw 的 `engines.node` 检测 |
 | Rust | stable | Tauri 后端编译 |
 | Tauri CLI | v2 | `cargo install tauri-cli --version "^2"` |
 

README.de.md

@@ -52,7 +52,7 @@ ClawPanel ist ein visuelles Verwaltungspanel, das mehrere AI-Agent-Frameworks un
 - **Orange Pi / Raspberry Pi / RK3588** — `npm run serve` zum Ausführen
 - **Docker ARM64** — `docker run ghcr.io/qingchencloud/openclaw:latest`
 - **Armbian / Debian / Ubuntu Server** — Automatische Architekturerkennung
-- Kein Rust / Tauri / GUI erforderlich — **nur Node.js 18+**
+- Kein Rust / Tauri / GUI erforderlich. ClawPanel Web benötigt **Node.js 18+**; OpenClaw Gateway wird gegen die `engines.node`-Anforderung der installierten OpenClaw-Version geprüft, empfohlen ist **Node.js 22.19.0+**.
 
 ## Community
 

README.en.md

@@ -57,7 +57,7 @@ ClawPanel provides a **pure Web deployment mode** (zero GUI dependency), nativel
 - **Orange Pi / Raspberry Pi / RK3588** — `npm run serve` to run
 - **Docker ARM64** — `docker run ghcr.io/qingchencloud/openclaw:latest`
 - **Armbian / Debian / Ubuntu Server** — Auto-detect architecture
-- No Rust / Tauri / GUI needed — **only Node.js 18+ required**
+- No Rust / Tauri / GUI needed. ClawPanel Web requires **Node.js 18+**; OpenClaw Gateway is checked against the installed OpenClaw `engines.node` requirement, with **Node.js 22.19.0+** recommended.
 
 > 📖 See [Armbian Deployment Guide](docs/armbian-deploy.md) | [Web Dev Mode](#web-version-no-rusttauri-required)
 

README.es.md

@@ -52,7 +52,7 @@ ClawPanel es un panel de gestión visual que soporta múltiples frameworks de AI
 - **Orange Pi / Raspberry Pi / RK3588** — `npm run serve` para ejecutar
 - **Docker ARM64** — `docker run ghcr.io/qingchencloud/openclaw:latest`
 - **Armbian / Debian / Ubuntu Server** — Detección automática de arquitectura
-- Sin necesidad de Rust / Tauri / GUI — **solo Node.js 18+**
+- Sin necesidad de Rust / Tauri / GUI. ClawPanel Web requiere **Node.js 18+**; OpenClaw Gateway se valida según el `engines.node` de la versión instalada de OpenClaw, recomendado **Node.js 22.19.0+**.
 
 ## Comunidad
 

README.fr.md

@@ -52,7 +52,7 @@ ClawPanel est un panneau de gestion visuel supportant plusieurs frameworks d'age
 - **Orange Pi / Raspberry Pi / RK3588** — `npm run serve` pour exécuter
 - **Docker ARM64** — `docker run ghcr.io/qingchencloud/openclaw:latest`
 - **Armbian / Debian / Ubuntu Server** — Détection automatique d'architecture
-- Sans Rust / Tauri / GUI — **seulement Node.js 18+**
+- Sans Rust / Tauri / GUI. ClawPanel Web nécessite **Node.js 18+** ; OpenClaw Gateway est vérifié selon le `engines.node` de la version OpenClaw installée, avec **Node.js 22.19.0+** recommandé.
 
 ## Communauté
 

README.ja.md

@@ -52,7 +52,7 @@ ClawPanel は複数の AI Agent フレームワークをサポートするビジ
 - **Orange Pi / Raspberry Pi / RK3588** — `npm run serve` で実行
 - **Docker ARM64** — `docker run ghcr.io/qingchencloud/openclaw:latest`
 - **Armbian / Debian / Ubuntu Server** — アーキテクチャ自動検出
-- Rust / Tauri / GUI 不要 — **Node.js 18+ のみで動作**
+- Rust / Tauri / GUI 不要。ClawPanel Web は **Node.js 18+** が必要です。OpenClaw Gateway はインストール済み OpenClaw の `engines.node` 要件に従って検出され、**Node.js 22.19.0+** を推奨します。
 
 ## コミュニティ
 

README.ko.md

@@ -52,7 +52,7 @@ ClawPanel은 여러 AI Agent 프레임워크를 지원하는 시각적 관리
 - **Orange Pi / Raspberry Pi / RK3588** — `npm run serve`로 실행
 - **Docker ARM64** — `docker run ghcr.io/qingchencloud/openclaw:latest`
 - **Armbian / Debian / Ubuntu Server** — 아키텍처 자동 감지
-- Rust / Tauri / GUI 불필요 — **Node.js 18+만 있으면 실행 가능**
+- Rust / Tauri / GUI 불필요. ClawPanel Web은 **Node.js 18+**가 필요하며, OpenClaw Gateway는 설치된 OpenClaw의 `engines.node` 요구사항에 따라 검사됩니다. **Node.js 22.19.0+**를 권장합니다.
 
 ## 커뮤니티
 

README.md

@@ -110,7 +110,7 @@ ClawPanel 提供**纯 Web 版部署模式**（零 GUI 依赖），天然兼容 A
 - **Orange Pi / 树莓派 / RK3588** 等 ARM64 板子 — `npm run serve` 即可运行
 - **Docker ARM64 镜像** — `docker run ghcr.io/qingchencloud/openclaw:latest` 开箱即用
 - **Armbian / Debian / Ubuntu Server** — 一键部署脚本自动检测架构
-- 无需 Rust / Tauri / 图形界面，**只要有 Node.js 18+ 就能跑**
+- 无需 Rust / Tauri / 图形界面；ClawPanel Web 后端需要 **Node.js 18+**，运行 OpenClaw Gateway 时会按当前 OpenClaw 的 `engines.node` 自动检测，建议 **Node.js 22.19.0+**
 
 > 📖 详见 [Armbian 部署指南](docs/armbian-deploy.md) | [Web 版开发说明](#web-开发版无需-rusttauri)
 
@@ -617,7 +617,7 @@ clawpanel/
 
 ### 前置条件
 
-- [Node.js](https://nodejs.org/) >= 18
+- [Node.js](https://nodejs.org/) >= 18（从源码构建 ClawPanel；运行 OpenClaw Gateway 建议 22.19.0+）
 - [Rust](https://www.rust-lang.org/tools/install) (stable)
 - Tauri v2 系统依赖（参考 [Tauri 官方文档](https://v2.tauri.app/start/prerequisites/)）
 
@@ -751,7 +751,7 @@ Web 版适用于 Linux 服务器（无桌面环境），通过浏览器远程管
 
 ### 环境要求
 
-- **Node.js** >= 18（推荐 22 LTS）
+- **Node.js** >= 18（ClawPanel Web 后端）；运行 OpenClaw Gateway 建议 **22.19.0+**，面板会按当前 OpenClaw 要求自动检测
 - **Git**（用于 OpenClaw 依赖安装）
 - **端口** 1420（ClawPanel）+ 18789（Gateway）
 
@@ -900,9 +900,9 @@ npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.
 
 ### 安装后 Node.js 检测不到（Windows）
 
-安装 Node.js 后需要**重启 ClawPanel**，新的 PATH 环境变量才能生效。
+安装 Node.js 后点击「重新检测」即可；如果仍显示旧版本，再重启 ClawPanel 或检查 PATH 优先级。
 
-如果安装在非默认路径（如 `D:\nodejs`、`F:\AI\Node`），请确认该目录已加入系统 PATH 环境变量。**v0.4.2+ 已自动扫描常见安装路径。**
+如果安装在非默认路径（如 `D:\nodejs`、`F:\AI\Node`），可以在设置向导中使用「自动扫描」或手动填写 Node.js 安装目录。面板会校验该 Node.js 是否满足当前 OpenClaw 要求，版本过低的路径不会保存。
 
 ### Gateway 启动失败
 

README.pt.md

@@ -52,7 +52,7 @@ ClawPanel é um painel de gestão visual que suporta múltiplos frameworks de AI
 - **Orange Pi / Raspberry Pi / RK3588** — `npm run serve` para executar
 - **Docker ARM64** — `docker run ghcr.io/qingchencloud/openclaw:latest`
 - **Armbian / Debian / Ubuntu Server** — Detecção automática de arquitetura
-- Sem necessidade de Rust / Tauri / GUI — **apenas Node.js 18+**
+- Sem necessidade de Rust / Tauri / GUI. O ClawPanel Web requer **Node.js 18+**; o OpenClaw Gateway é validado conforme o `engines.node` do OpenClaw instalado, com **Node.js 22.19.0+** recomendado.
 
 ## Comunidade
 

README.ru.md

@@ -52,7 +52,7 @@ ClawPanel — это визуальная панель управления, п
 - **Orange Pi / Raspberry Pi / RK3588** — `npm run serve` для запуска
 - **Docker ARM64** — `docker run ghcr.io/qingchencloud/openclaw:latest`
 - **Armbian / Debian / Ubuntu Server** — Автоопределение архитектуры
-- Без Rust / Tauri / GUI — **только Node.js 18+**
+- Без Rust / Tauri / GUI. ClawPanel Web требует **Node.js 18+**; OpenClaw Gateway проверяется по `engines.node` установленной версии OpenClaw, рекомендуется **Node.js 22.19.0+**.
 
 ## Сообщество
 

README.vi.md

@@ -52,7 +52,7 @@ ClawPanel là bảng quản lý trực quan hỗ trợ nhiều AI Agent framewor
 - **Orange Pi / Raspberry Pi / RK3588** — `npm run serve` để chạy
 - **Docker ARM64** — `docker run ghcr.io/qingchencloud/openclaw:latest`
 - **Armbian / Debian / Ubuntu Server** — Tự động phát hiện kiến trúc
-- Không cần Rust / Tauri / GUI — **chỉ cần Node.js 18+**
+- Không cần Rust / Tauri / GUI. ClawPanel Web cần **Node.js 18+**; OpenClaw Gateway được kiểm tra theo `engines.node` của bản OpenClaw đã cài, khuyến nghị **Node.js 22.19.0+**.
 
 ## Cộng đồng
 

README.zh-TW.md

@@ -52,7 +52,7 @@ ClawPanel 是支援多 AI Agent 框架的視覺化管理面板，目前支援 [O
 - **Orange Pi / 樹莓派 / RK3588** — `npm run serve` 即可執行
 - **Docker ARM64** — `docker run ghcr.io/qingchencloud/openclaw:latest`
 - **Armbian / Debian / Ubuntu Server** — 自動偵測架構
-- 無需 Rust / Tauri / GUI — **只要有 Node.js 18+ 就能跑**
+- 無需 Rust / Tauri / GUI；ClawPanel Web 後端需要 **Node.js 18+**，執行 OpenClaw Gateway 時會按目前 OpenClaw 的 `engines.node` 自動檢測，建議 **Node.js 22.19.0+**
 
 ## 社群
 

docs/armbian-deploy.md

@@ -10,7 +10,7 @@ ClawPanel 支持在 ARM 开发板（如 Orange Pi、Raspberry Pi、RK3588 等）
 | 内存 | 1GB | 2GB+ |
 | 存储 | 2GB 可用空间 | 4GB+ |
 | 系统 | Armbian / Debian / Ubuntu | Armbian 24+ |
-| Node.js | 18+ | 22 LTS |
+| Node.js | 18+ | ClawPanel Web 后端；运行 OpenClaw Gateway 建议 22.19.0+ |
 
 > ⚠️ 当前不支持 ARM 32 位 (armv7) 的 Docker 镜像。Web 模式在 armv7 上可用（只要 Node.js 支持）。
 
@@ -130,7 +130,7 @@ docker run -d \
 A: 不建议。Tauri 需要 WebKitGTK + 图形界面，ARM 板通常是 headless 环境。请使用 Web 模式。
 
 **Q: armv7 (32位) 板子能用吗？**
-A: Web 模式可以（只要能装 Node.js 18+）。Docker 模式目前只提供 arm64 镜像。
+A: Web 模式可以（ClawPanel Web 后端需要 Node.js 18+；运行 OpenClaw Gateway 建议 Node.js 22.19.0+）。Docker 模式目前只提供 arm64 镜像。
 
 **Q: 树莓派 Zero / Pi 1 能跑吗？**
 A: 这些是 armv6，内存也只有 256-512MB，不推荐。建议至少树莓派 3B+ 或更新的 ARM64 板子。

docs/linux-deploy.md

@@ -49,7 +49,7 @@
 
 | 依赖 | 最低版本 | 说明 |
 |------|----------|------|
-| Node.js | 18+ | 推荐 22 LTS |
+| Node.js | 18+ | ClawPanel Web 后端；运行 OpenClaw Gateway 建议 22.19.0+，实际要求按当前 OpenClaw `engines.node` 检测 |
 | npm | 随 Node.js | 包管理器 |
 | Git | 任意 | 克隆仓库 |
 | OpenClaw | 最新 | ClawPanel 管理的对象 |

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "clawpanel",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "clawpanel",
-      "version": "0.18.1",
+      "version": "0.18.2",
       "license": "AGPL-3.0",
       "dependencies": {
         "@tauri-apps/api": "^2.5.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawpanel",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "private": true,
   "description": "ClawPanel - OpenClaw 可视化管理面板，基于 Tauri v2 的跨平台桌面应用",
   "type": "module",

src-tauri/Cargo.lock

@@ -366,7 +366,7 @@ dependencies = [
 
 [[package]]
 name = "clawpanel"
-version = "0.18.1"
+version = "0.18.2"
 dependencies = [
  "base64 0.22.1",
  "chrono",

src-tauri/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "clawpanel"
-version = "0.18.1"
+version = "0.18.2"
 edition = "2021"
 description = "ClawPanel - OpenClaw 可视化管理面板"
 authors = ["qingchencloud"]

src-tauri/tauri.conf.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/tauri-apps/tauri/dev/crates/tauri-config-schema/schema.json",
   "productName": "ClawPanel",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "identifier": "ai.openclaw.clawpanel",
   "build": {
     "frontendDist": "../dist",