bf9cb52e25
用户反馈 0.13.3 版本有三个共性 bug：
1. 手动装 Node.js → 装完 panel 不识别，必须重启客户端
2. 一键装 Git → 装完 panel 不识别，必须重启客户端
3. 一键装 OpenClaw → 装完 panel 不识别，必须重启客户端
## 根因
Tauri 进程的 `std::env::var("PATH")` 是启动时快照，不会随系统 PATH 更
新。`enhanced_path()` 虽然扫描了常见安装目录，但**不存在的目录不会被
加入缓存**（line 828 `std::path::Path::new(p).exists()` 过滤）。装完
新程序后，新路径不在 enhanced_path 缓存里，CLI 检测又依赖子进程的
PATH，导致「找不到刚装的二进制」。
三个 bug 各有其子因：
### Bug 1: Git 检测 `find_git_path` 不用 enhanced_path
对比 `find_node_path` 显式 `cmd.env("PATH", enhanced_path)`，
`find_git_path` 里的 `where git` / `which git` 子进程继承的是 Tauri
启动时快照的老 PATH。即使 `refresh_enhanced_path()` 刷了缓存，子进
程也看不到新路径。`check_git` 后续调 `Command::new("git")` 同理，且
拿到 `git_path` 绝对路径后也没用。
### Bug 2: `auto_install_git` 三平台都不刷缓存
winget/xcode-select/apt 安装成功后直接 return，没有
`refresh_enhanced_path()` / `invalidate_cli_detection_cache()`。前端
`runDetect` 虽然会调 `invalidatePathCache`，但 Bug 1 让刷缓存也白刷。
### Bug 3: `upgrade_openclaw` npm 首装分支不刷缓存
npm 分支里只有 `if need_uninstall_old`（切换源场景）分支末尾刷了
PATH 缓存。**首次安装** `need_uninstall_old == false`，if 块整个跳
过，函数直接返回，CLI 检测缓存（60s TTL）和 PATH 缓存都是旧的。前
端 `setTimeout(reload, 1500)` 触发 SPA 重建，但 Tauri 进程没重启，
缓存没刷 → `is_cli_installed()` 返回 false。
### Bug 4: 手动装 Node.js 没有 hook 点
用户点「下载 Node.js」跳浏览器，装完回到 panel，panel 不知道用户装
了。虽然顶部有「重新检测」按钮，但 UX 上容易错过。`runDetect` 里虽
然会 `await api.invalidatePathCache()`，但需要用户主动触发。
## 修复
### Rust 端
1. **`find_git_path`**：子进程 `where`/`which` 显式 `env("PATH",
enhanced_path)`，对齐 `find_node_path` 的做法。
2. **`check_git`**：优先用 `find_git_path` 返回的绝对路径执行
`--version`；fallback 到 `"git"` 时也注入 enhanced_path 到子进程
PATH，确保刚装完的场景能识别。
3. **`auto_install_git`**：winget/xcode-select/apt 三个平台的成功分
支都调 `super::refresh_enhanced_path()` +
`invalidate_cli_detection_cache()`。
4. **`upgrade_openclaw`**：npm 分支末尾（if need_uninstall_old 块之
后、`get_local_version` 之前）无条件刷缓存，覆盖首装场景。切换源
场景虽然前面已刷过一次，这里重刷无害（几十 ms 文件系统扫描开销
可接受）。
### 前端
5. **`setup.js::render`**：注册 `visibilitychange` + window `focus`
监听器，用户从浏览器装完 Node.js 切回 panel 时自动 `runDetect`。
handler 自带 guard（`page.isConnected` 检查），页面切走后监听器
自动卸载，防止泄漏。加 3 秒节流，避免 focus + visibilitychange
同时连发触发重复检测。
## 验证
- `cargo fmt --check` 通过
- `cargo clippy --all-targets -- -D warnings` 通过
- `npm run build` 通过（setup chunk 未变，setup.js 新增 ~22 行）
- 本地需要用户验证：
- [ ] 手动装完 Node.js → 切回 panel 自动识别
- [ ] 一键装 Git → 装完立刻识别（无需重启）
- [ ] 一键装 OpenClaw（首次 npm 安装）→ 装完立刻识别
- [ ] 一键装 OpenClaw（切换源）→ 装完立刻识别（原本就工作，不回归）
Refs: 0.13.3 用户实测反馈
OpenClaw & Hermes Agent Management Panel with Built-in AI Assistant — Multi-Engine AI Framework Management
🇨🇳 中文 | 🇺🇸 English | 🇹🇼 繁體中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇻🇳 Tiếng Việt | 🇪🇸 Español | 🇧🇷 Português | 🇷🇺 Русский | 🇫🇷 Français | 🇩🇪 Deutsch
ClawPanel is a visual management panel supporting multiple AI Agent frameworks, currently with OpenClaw and Hermes Agent dual-engine support. It features a built-in intelligent AI assistant that helps you install, auto-diagnose configurations, troubleshoot issues, and fix errors. 8 tools + 4 modes + interactive Q&A — easy to manage for beginners and experts alike.
🌐 Website: claw.qt.cool | 📦 Download: GitHub Releases
🎁 QingchenCloud AI API
Internal technical testing platform, open for selected users. Sign in daily to earn credits.
- Daily Sign-in Credits — Sign in daily + invite friends to earn test credits
- OpenAI-Compatible API — Seamless integration with OpenClaw, plug and play
- Resource Policy — Rate limiting + request caps, may queue during peak hours
- Model Availability — Models/APIs subject to actual page display, may rotate versions
⚠️ Compliance: This platform is for technical testing only. Illegal use or circumventing security mechanisms is prohibited. Keep your API Key secure. Rules subject to latest platform policies.
🔥 Dev Board / Embedded Device Support
ClawPanel provides a pure Web deployment mode (zero GUI dependency), natively compatible with ARM64 boards:
- Orange Pi / Raspberry Pi / RK3588 —
npm run serveto 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
📖 See Armbian Deployment Guide | Web Dev Mode
Community
A community of passionate AI Agent developers and enthusiasts — join us!
Discord · Discussions · Report Issue
Features
- 🤖 AI Assistant (New) — Built-in AI assistant, 4 modes + 8 tools + interactive Q&A. See AI Assistant Highlights
- 🧩 Multi-Engine Architecture — Supports both OpenClaw and Hermes Agent dual engines, freely switchable, independently managed
- 🤖 Hermes Agent Chat — Built-in Hermes Agent chat interface with tool call visualization, file system access toggle, SSE streaming output
- 🖼️ Image Recognition — Paste screenshots or drag images, AI auto-analyzes, multimodal conversations
- Dashboard — System overview, real-time service monitoring, quick actions
- Service Management — OpenClaw / Hermes Gateway start/stop, version detection & one-click upgrade, config backup & restore
- Model Configuration — Multi-provider management, model CRUD, batch connectivity tests, latency detection, drag-to-reorder, auto-save + undo
- Gateway Configuration — Port, access scope (localhost/LAN), auth Token, Tailscale networking
- Messaging Channels — Unified Telegram, Discord, Feishu, DingTalk, QQ management, multi-Agent binding per platform
- Communication & Automation — Message settings, broadcast strategies, slash commands, Webhooks, execution approval
- Usage Analytics — Token usage, API costs, model/provider/tool rankings, daily usage charts
- Agent Management — Agent CRUD, identity editing, model config, workspace management
- Chat — Streaming, Markdown rendering, session management, /fast /think /verbose /reasoning commands
- Cron Jobs — Cron-based scheduled execution, multi-channel delivery
- Log Viewer — Multi-source real-time logs with keyword search
- Memory Management — Memory file view/edit, categorized management, ZIP export, Agent switching
- QingchenCloud AI API — Internal testing platform, OpenAI-compatible, daily sign-in credits
- Extensions — cftunnel tunnel management, ClawApp status monitoring
- About — Version info, community links, related projects, one-click upgrade
Download & Install
Go to Releases for the latest version:
macOS
| Chip | Installer | Notes |
|---|---|---|
| Apple Silicon (M1/M2/M3/M4) | ClawPanel_x.x.x_aarch64.dmg |
Macs from late 2020+ |
| Intel | ClawPanel_x.x.x_x64.dmg |
Macs 2020 and earlier |
⚠️ "Damaged" or "unverified developer"? App is unsigned. Run:
sudo xattr -rd com.apple.quarantine /Applications/ClawPanel.app
Windows
| Format | Installer | Notes |
|---|---|---|
| EXE | ClawPanel_x.x.x_x64-setup.exe |
Recommended |
| MSI | ClawPanel_x.x.x_x64_en-US.msi |
Enterprise / silent install |
Linux
| Format | Installer | Notes |
|---|---|---|
| AppImage | ClawPanel_x.x.x_amd64.AppImage |
No install, chmod +x and run |
| DEB | ClawPanel_x.x.x_amd64.deb |
sudo dpkg -i *.deb |
| RPM | ClawPanel-x.x.x-1.x86_64.rpm |
sudo rpm -i *.rpm |
Linux Server (Web Version)
curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | bash
Visit http://YOUR_SERVER_IP:1420 after deployment. 📖 Linux Deployment Guide
Docker
docker run -d --name clawpanel --restart unless-stopped \
-p 1420:1420 -v clawpanel-data:/root/.openclaw \
node:22-slim \
sh -c "apt-get update && apt-get install -y git && \
npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com && \
git clone https://github.com/qingchencloud/clawpanel.git /app && \
cd /app && npm install && npm run build && npm run serve"
Quick Start
- Initial Setup — First launch auto-detects Node.js, Git, OpenClaw. One-click install if missing.
- Configure Models — Add AI providers (DeepSeek, MiniMax, OpenAI, Ollama, etc.) with API keys. Test connectivity.
- Start Gateway — Go to Service Management, click Start. Green status = ready.
- Start Chatting — Go to Live Chat, select model, start conversation with streaming & Markdown.
🤖 AI Assistant Highlights
Built-in AI assistant that can directly operate your system — diagnose, fix, even submit PRs.
Four Modes
| Mode | Icon | Tools | Write | Confirm | Use Case |
|---|---|---|---|---|---|
| Chat | 💬 | ❌ | ❌ | — | Pure Q&A |
| Plan | 📋 | ✅ | ❌ | ✅ | Read configs/logs, output plans |
| Execute | ⚡ | ✅ | ✅ | ✅ | Normal work, dangerous ops need confirm |
| Unlimited | ∞ | ✅ | ✅ | ❌ | Full auto, no prompts |
Eight Tools
| Tool | Function |
|---|---|
ask_user |
Ask user questions (single/multi/text) |
get_system_info |
Get OS, architecture, home directory |
run_command |
Execute shell commands |
read_file / write_file |
Read/write files |
list_directory |
Browse directories |
list_processes |
View processes |
check_port |
Check port usage |
Tech Architecture
| Layer | Technology | Description |
|---|---|---|
| Frontend | Vanilla JS + Vite | Zero framework, lightweight |
| Backend | Rust + Tauri v2 | Native performance, cross-platform |
| Communication | Tauri IPC + Shell Plugin | Frontend-backend bridge |
| Styling | Pure CSS (CSS Variables) | Dark/Light themes, glassmorphism |
Build from Source
git clone https://github.com/qingchencloud/clawpanel.git
cd clawpanel && npm install
# Desktop (requires Rust + Tauri v2)
npm run tauri dev # Development
npm run tauri build # Production
# Web only (no Rust needed)
npm run dev # Dev with hot reload
npm run build && npm run serve # Production
Related Projects
| Project | Description |
|---|---|
| OpenClaw | AI Agent Framework |
| ClawApp | Cross-platform mobile chat client |
| cftunnel | Cloudflare Tunnel tool |
Contributing
Issues and Pull Requests are welcome. See CONTRIBUTING.md for guidelines.
Acknowledgements
ClawPanel keeps growing because of every contributor in the community. Thank you for helping make the project better.
Code Contributors
Thanks to these developers for submitting Pull Requests and contributing directly to the codebase:
 liucong2013 #88 |
 axdlee #58 |
 ATGCS #107 |
 livisun #106 |
 kiss-kedaya #101 #94 |
 wzh4869 #82 |
 0xsline #15 |
 jonntd #18 |
Community Reporters
Thanks to community members who opened issues, reported bugs, and suggested features:
If we missed your contribution, please open an issue and we will add it promptly.
Sponsor
If you find this project useful, consider supporting us via USDT (BNB Smart Chain):
0xbdd7ebdf2b30d873e556799711021c6671ffe88f
Contact
- Email: support@qctx.net
- Website: qingchencloud.com
- Product: claw.qt.cool
License
This project is licensed under AGPL-3.0. For commercial/proprietary use without open-source requirements, contact us for a commercial license.
© 2026 QingchenCloud (武汉晴辰天下网络科技有限公司) | claw.qt.cool