create-openclaw-bot 5.4.0 → 5.4.2

package/CHANGELOG.md

@@ -1,170 +1,190 @@
-# Changelog (English)
-
-
-## [5.4.0] — 2026-04-14
-
-### 🗑️ Remove: Telegram + Zalo Combo Channel
-
-- **Deprecated and removed `telegram+zalo-personal` combo mode** from both the Web Wizard and CLI. The channel card is hidden in `index.html`, removed from `channels.js` and `data/index.js`, and all conditional logic has been purged from `controller.js`, `output.js`, `steps.js`, `multi-bot.js`, `win-bat.js`, `macos-sh.js`, `linux-sh.js`, `vps-sh.js`, `native-helpers-gen.js`, and `cli.src.js`. Combo mode will be redesigned in a future release.
-
-### 🏗️ Refactor: Multi-Bot Architecture
-
-- **Unified multi-bot flag** — `isTelegramMultiBot`, `isSharedMultiBot`, and `isMultiBotWizard` have all been merged into a single `isMultiBot` boolean throughout the codebase. Reduces complexity and eliminates divergent code paths.
-- **Fixed `agentDir` path resolution** — `agentDir` in generated `openclaw.json` is now correctly set as `.openclaw/agents/{slug}/agent` (relative to `OPENCLAW_HOME`). Previously used an incorrect project-root-level `agents/{slug}/agent` path that caused double-prefix errors at runtime.
-- **Removed redundant `agents/` root folder creation** — OS scripts no longer attempt to `mkdir agents/` at the project root; all agent files are created under `.openclaw/agents/`.
-
-### 🧹 Config Generation Cleanup
-
-- **Removed per-agent `auth-profiles.json` for 9Router/proxy mode** — When the provider is a proxy (9Router), per-agent `auth-profiles.json` is no longer generated. This file is only created for direct API providers where per-agent authentication is required.
-- **Removed `.env` generation for native deployments** — Bot tokens and API keys for native mode are now managed via `openclaw channels login` / the 9Router dashboard. No `.env` is auto-generated in native scripts to avoid credential sprawl.
-- **Removed per-agent `models.json` for Ollama (CLI)** — Ollama model config is already declared in `openclaw.json → agents.defaults.model`. The redundant per-agent `models.json` in `agents/{id}/agent/` is no longer generated.
-
-### 🤝 Cross-Workspace Rules in AGENTS.md
-
-- **Multi-bot `AGENTS.md` now includes a "Cross-Workspace" section** — In multi-bot (relay) mode, each bot's `AGENTS.md` receives a `🤝 Workspace Chéo (Multi-Agent)` / `🤝 Cross-Workspace (Multi-Agent)` section listing the workspace paths of sibling bots. Rules: bots may read each other's `IDENTITY`, `SOUL`, and `MEMORY` files for shared context; they must not delete or overwrite each other's workspace files without explicit user instruction.
-
-### 🔧 win-bat.js Refactor
-
-- **Extracted `appendGatewayStart()` and `appendDashboardInfo()` helpers** — Repeated PowerShell gateway launch and dashboard URL blocks are now deduplicated into two local helper functions inside `generateWinBat`, reducing the Windows batch generator by ~50 lines.
-
-
-## [5.3.5] — 2026-04-12
-
-### 🐛 Fix: MEMORY.md Syntax Error in Zalo Workspace Files
-
-- **Fix: `SyntaxError: Unexpected token ':'` in `setup.js`** — the previous TOOLS.md patch was inserted after the `vi` ternary arm of MEMORY.md, orphaning the `: en-value` colon arm below it. VS Code showed this as 7 error badges on `setup.js`. Now fixed; both MEMORY.md arms are contiguous, then TOOLS.md follows as a clean separate property.
-
-### 🐟 Improvement: Uninstall Script Written to Project Folder
-
-- **All 4 OS native flows + Docker ZIP** now include the matching `uninstall-*.{bat,sh}` script **in the project folder** during setup. Previously the uninstall was only available as a separate browser download. Pattern mirrors `start-chrome-debug.bat` / `.sh`:
-  - Windows native: `uninstall-openclaw-win.bat` written via `appendBatWriteCommands`
-  - macOS native: `uninstall-openclaw.sh` written via `appendShWriteCommands`
-  - VPS/Ubuntu: `uninstall-openclaw-vps.sh` written via `appendShWriteCommands`
-  - Linux Desktop: `uninstall-openclaw.sh` written via `appendShWriteCommands`
-  - Docker (all OS): uninstall script included in the generatedFiles ZIP
-
-
-
-### 🐛 Windows Native — Gateway & Workspace Stability
-
-- **Fix: Gateway terminal auto-closing** — `call openclaw gateway run` was blocking the setup terminal indefinitely; closing the window killed the gateway process. The gateway is now launched in a **dedicated, visible CMD window** via a PS1 background launcher (same pattern as 9Router), so the setup terminal closes cleanly while the gateway keeps running.
-- **Fix: `call` missing from `openclaw gateway stop`** — The gateway stop command before relaunch was missing the `call` keyword, which could prevent the bat script from returning control after the stop completes. Added `call openclaw gateway stop 2>nul` in all affected paths.
-- **Fix: Workspace naming** — Single-bot deployments previously used a generic `.openclaw/workspace` path. All agents (single-bot and multi-bot) now use a named directory matching their agent ID: `.openclaw/workspace-{agentId}` (e.g. `workspace-williams`, `workspace-luna`). This prevents workspace collisions and aligns the folder structure with the `agents/{agentId}` directory convention.
-- **Improve: TOOLS.md enriched for all bots** — The generated `TOOLS.md` now includes both the custom skills & conventions section AND a "Local Notes" template section adapted from the OpenClaw workspace default, giving users a clear starting point for documenting environment-specific config.
-- **Improve: Zalo bot AGENTS.md now includes security rules** — The generated `AGENTS.md` for Zalo Personal bots (Luna-pattern) now appends the same `🔐 Security Rules — MANDATORY` block that Telegram bots receive (file-system boundaries, credential hygiene, crypto wallet protection, Docker mount rules).
-- **Improve: Zalo bot TOOLS.md added** — Zalo bot workspaces now receive a `TOOLS.md` file with the same skills list and conventions structure as Telegram bots.
-
-
-## [5.3.3] — 2026-04-11
-
-### 🧹 Automated Uninstall Scripts
-
-- **Wizard UI Generation**: The HTML setup wizard now generates a matching `uninstall-openclaw-*.bat/sh` script when downloading the configuration for Native or Docker deployments.
-- **Complete Cleanup**: The generated scripts cleanly kill 9Router/OpenClaw background processes, uninstall global npm packages, and safely remove the project and `.9router` data directories, allowing for a fresh start whenever needed.
-
-
-
-## [5.3.2] — 2026-04-11
-
-### 🐛 Windows Native — 9Router Launch Stability
-
-- **Fix: Remove `-l` (stdin listen) flag from native 9Router launch** — `resolveNative9RouterDesktopLaunch()` previously passed `-l` which puts 9Router into interactive REPL mode. When spawned as a background process (no TTY), this caused the process to hang waiting for stdin input. Removed the flag; 9Router now starts reliably in the background on Windows, macOS desktop, and any non-VPS native flow.
-- **Fix: Pre-seed `DATA_DIR/.9router/db.json` with `requireLogin: false` before 9Router starts** — If `db.json` does not exist when 9Router boots, it uses its own default path (`~/.9router`) and defaults `requireLogin` to `true`, causing the dashboard login wall. The CLI wizard now creates the `.9router` directory and writes a minimal `db.json` (with `requireLogin: false`) **before** spawning 9Router, matching the behavior of the fixed `setup-openclaw-win.bat` batch file.
-- **No change to PM2/VPS flow** — The fix applies only to the desktop/background spawn path (`osChoice !== 'vps'`). VPS users still use the existing PM2-managed `startNative9RouterPm2` flow which is unaffected.
-
-## [5.3.1] — 2026-04-10
-
-### 🌟 Zalo Personal DM Policy
-
-- **Open Zalo Inboxes**: The default `dmPolicy` for Zalo Personal deployments has been changed from `pairing` to `open`. This allows any user on the Zalo network to interact with the AI assistant immediately without requiring explicit device pairing approvals natively.
-
-
-## [5.3.0] — 2026-04-11
-
-### 🆕 Multi-Channel: Telegram + Zalo Personal Simultaneously
-
-- **Combo channel option** — New `telegram+zalo-personal` option in both CLI wizard (`select`) and web wizard (channel card). Selecting it configures a single bot to receive messages from both Telegram and Zalo Personal at the same time.
-- **Auto-inject `plugins.entries.zalouser`** — When any Zalo Personal channel is selected, `openclaw.json` now automatically includes `plugins.entries.zalouser: { enabled: true }`, fixing the root cause of the "not configured" error on Zalo startup.
-- **Docker cold-start fix in Dockerfile CMD** — A background `(sleep 45 && node -e '...touch historyLimit...')` script is now baked into the generated `Dockerfile` CMD. Triggers chokidar → gateway hot-reload → `restartChannel('zalouser')` after Docker network warms up. No more manual `lastTouchedAt` workarounds.
-- **Helper predicates** — Added `hasTelegram(ck)` and `hasZaloPersonal(ck)` functions replacing all literal `channelKey === 'telegram/zalo-personal'` comparisons throughout `cli.js` for cleaner extensibility.
-- **Smoke tests updated** — `tests/smoke-cli-logic.mjs` updated to match the new predicate-based assertions (78 checks passing).
-
-## [5.2.4] — 2026-04-10
-
-### 🐛 Bug Fixes & Developer Tooling
-
-- **Fix: `docker compose build --no-cache` during upgrade** — Removed the `--no-cache` flag from the upgrade flow. Without it, Docker correctly reuses cached layers (including Playwright/Chromium ~300MB) and only rebuilds the `openclaw` layer that changed, making upgrades significantly faster.
-- **UX: Upgrade CLI banner now matches upgrade.ps1/sh style** — `runUpgrade()` in `cli.js` now renders the same ╭╮╰╯ box using visual-width calculation (`vw()`) instead of plain `===` separators.
-- **New: GitHub Actions workflow to auto-detect openclaw updates** — `.github/workflows/check-openclaw-update.yml` runs daily, compares the pinned `OPENCLAW_NPM_SPEC` in `cli.js` with the latest version on npm, and automatically creates a GitHub Issue with upgrade instructions if a new version is available.
-
-## [5.2.3] — 2026-04-10
-
-### 🐛 Bug Fixes & Encoding Improvements
-
-- **Fix: `ReferenceError: projectDir is not defined`** — Crash when clicking "Generate Configs" in multi-bot mode. `nativeProjectOpenClawRoot` in `buildTelegramPostInstallChecklist()` referenced an undefined `projectDir` variable and was dead code (unused in return value). Removed.
-- **Fix: Step 3 "Next" button validation** — `state._activeBotTab` was a typo of `state.activeBotIndex`, causing multi-bot validation to always read the wrong tab index.
-- **Fix: `saveFormData()` always saved bot tab name to `bots[0]`** — In multi-bot mode, the active bot name was always written to `bots[0]` regardless of which tab was active. Now correctly saves to `bots[state.activeBotIndex]`.
-- **UX: Inline hint for disabled "Generate Configs" button** — When the button is blocked, a warning now appears showing exactly which fields are still missing (e.g. "Missing: GOOGLE_API_KEY").
-- **Fix: Vietnamese diacritics in generated `.bat` and `.sh` scripts** — All Vietnamese echo/Write-Host strings in the generated Windows setup script and Linux/macOS bash script have been converted to ASCII (no diacritics) to prevent encoding errors on systems with non-UTF-8 codepages.
-
-## [5.2.2] — 2026-04-10
-
-
-### 🐛 Docker & Native PM2 Bug Fixes
-
-- **Fix Docker crash loop (socat port conflict)**: `socat TCP-LISTEN:18791` was binding `0.0.0.0:18791` before `openclaw gateway run` started, causing `EADDRINUSE` on `127.0.0.1:18791`. Removed the broken gateway bridge from the generated Dockerfile CMD in both `cli.js` and `setup.js`.
-- **Fix Docker dashboard not accessible from host**: Gateway `bind` was set to `'loopback'` — Docker port mapping cannot route to container loopback. Restored the v5.0.9 working pattern: `bind:'custom', customBindHost:'0.0.0.0'`.
-- **Fix `delete c.gateway.customBindHost`**: A stray `delete` statement was erasing the `customBindHost` key right after setting it. Removed.
-- **Fix Docker build re-downloading npm packages on every rebuild**: `ARG CACHEBUST=<epoch>` was cache-busting the `npm install -g openclaw` layer on every build (even config-only changes). Replaced with a version-stable `ARG OPENCLAW_VER` so Docker layer cache is reused between rebuilds.
-- **Fix native PM2 double `.openclaw` nesting**: `ecosystem.config.js` was setting `OPENCLAW_HOME: projectDir/.openclaw`, causing OpenClaw to resolve workspace as `projectDir/.openclaw/.openclaw/workspace`. Removed `OPENCLAW_HOME` from PM2 env; OpenClaw discovers config via `cwd` (matching v5.0.9 behavior).
-
-## [5.2.1] — 2026-04-09
-
-### 🐛 Native Ubuntu/VPS Bug Fixes
-
-- **Fix `Bot-9router errored` (PM2)**: `resolveNative9RouterDesktopLaunch` was trying to locate `9router/app/server.js` inside npm global dirs — a path that doesn't exist after standard `npm install -g 9router`. Now uses the `9router` CLI binary directly with proper args (`-n -l -H 0.0.0.0 -p 20128 --skip-update`), preventing the `↺ 15` restart loop.
-- **Fix double `.openclaw` workspace path**: `workspace` and `agentDir` in generated `openclaw.json` were set as absolute paths (e.g. `/home/user/bot/.openclaw/workspace`). OpenClaw resolves these relative to `OPENCLAW_HOME`, causing a double-prefix (`/home/user/bot/.openclaw/.openclaw/workspace`). Changed to relative paths (`workspace`, `agents/<id>/agent`) matching Docker behavior.
-- **Fix missing runtime packages on native install**: `grammy`, `@grammyjs/runner`, `@grammyjs/transformer-throttler`, `@buape/carbon`, `@larksuiteoapi/node-sdk`, `@slack/web-api` were installed in Docker (Dockerfile) but skipped on native. `installLatestOpenClaw` now installs all `OPENCLAW_RUNTIME_PACKAGES` after the main binary.
-- **Fix `openclaw: command not found` after install**: Post-setup Zalo login instructions now include a `source ~/.bashrc && source ~/.profile` hint for new terminal sessions on Linux.
-- **Fix Zalo session stored in wrong directory**: Manual login hint now includes `OPENCLAW_HOME` and `OPENCLAW_STATE_DIR` env vars so sessions are saved to `<projectDir>/.openclaw/credentials/zalouser/` — the same path the PM2 gateway reads from.
-- **Fix relative project path**: `projectDir` input is now normalized with `path.resolve()` so typing `home/ubuntu/bot` (without leading `/`) correctly resolves to `/home/ubuntu/bot`.
-
-
-## [5.2.0] — 2026-04-09
-
-### One-Command Upgrade (No Wizard Required)
-
-- Added `upgrade` subcommand to the CLI: `npx create-openclaw-bot@latest upgrade`. Detects Docker vs Native mode automatically and updates OpenClaw without re-running the setup wizard.
-- Added `upgrade.ps1` for Windows users — double-click in the bot folder to trigger an upgrade. No terminal knowledge required.
-- Added `upgrade.sh` for Linux / macOS / Ubuntu — run `bash upgrade.sh` locally or pipe via `curl` or `wget` directly from GitHub without cloning the repo.
-- All user data is preserved during upgrade: `.env`, `.openclaw/memory/`, sessions, credentials, and 9Router OAuth tokens are never modified.
-- Docker mode: patching `Dockerfile` (`OPENCLAW_NPM_SPEC` + `CACHEBUST` refresh) then `docker compose build --no-cache` + `docker compose up -d`.
-- Native / PM2 mode: reinstalls `openclaw` + `9router` globals then runs `pm2 restart all`.
+# Changelog (English)
+
 
+## [5.4.2] — 2026-04-14
 
-## [5.1.15] — 2026-04-08
+### 🐛 Native Script Wizard Fixes
 
-### Native Setup Parity & Windows Wizard Fixes
+- **Deduplicate Plugin Installations**: Fixed an issue where the Telegram Multi-Bot Relay plugin was being appended twice to the installation payload in the HTML web wizard (`setup-openclaw-*.bat/sh`). This eliminates the "plugin already exists" crash during `npm exec` plugin installations.
 
-- Fixed the Windows native HTML wizard so downloaded `.bat` files always regenerate from the latest UI state before download.
-- Fixed Windows native runtime paths to stay project-local: `.env`, `.openclaw`, and `.9router` now resolve from the user-selected project directory instead of home/AppData fallbacks.
-- Added `OPENCLAW_STATE_DIR` to native runtime environments so OpenClaw loads the generated config from the project runtime directory.
-- Replaced legacy `gateway.bind: "0.0.0.0"` output with the current `bind: "custom"` plus `customBindHost: "0.0.0.0"` format.
-- Fixed Windows native single-bot generation so selected provider, model, API key, and Telegram bot token are correctly synced into generated `.env` and `openclaw.json`.
-- Fixed native Windows 9Router launch path resolution and updated the embedded smart-route sync helper to use the live `9Router` API provider list, matching Docker behavior.
-- Added native Windows skill/runtime parity improvements: selected skills now install automatically, browser automation installs its required runtime packages, and skill config entries now use the correct slugs.
-- Updated macOS, Linux Desktop, and Ubuntu/VPS native scripts to launch from the chosen `PROJECT_DIR` and export project-local `OPENCLAW_HOME`, `OPENCLAW_STATE_DIR`, and `DATA_DIR`.
+
+## [5.4.1] — 2026-04-14
+
+### 🐛 Docker CLI Generation Fixes
+
+- **Browser Automation Restoration**: Reintroduced `xvfb` APT installation and the background Xvfb frame buffer execution (`Xvfb :99 -screen...`) to the generated Dockerfile `CMD`. This prevents headful Playwright processes from crashing on startup within the container.
+- **REST API CORS Hotfix**: Reintroduced the runtime Internal IP injector script. It correctly patches `openclaw.json` at container startup strictly mapping Docker internal bridge IPs (`172...`) into `allowedOrigins`, eliminating 403 CORS blocks inside Docker Web Control UIs.
+
+### 🧹 Automated Uninstall Scripts
+
+- **Wizard UI Generation**: The HTML setup wizard now generates a matching `uninstall-openclaw-*.bat/sh` script when downloading the configuration for Native or Docker deployments.
+- **Complete Cleanup**: The generated scripts cleanly kill 9Router/OpenClaw background processes, uninstall global npm packages, and safely remove the project and `.9router` data directories, allowing for a fresh start whenever needed.
+
+
+## [5.4.0] — 2026-04-14
+
+### 🗑️ Remove: Telegram + Zalo Combo Channel
+
+- **Deprecated and removed `telegram+zalo-personal` combo mode** from both the Web Wizard and CLI. The channel card is hidden in `index.html`, removed from `channels.js` and `data/index.js`, and all conditional logic has been purged from `controller.js`, `output.js`, `steps.js`, `multi-bot.js`, `win-bat.js`, `macos-sh.js`, `linux-sh.js`, `vps-sh.js`, `native-helpers-gen.js`, and `cli.src.js`. Combo mode will be redesigned in a future release.
+
+### 🏗️ Refactor: Multi-Bot Architecture
+
+- **Unified multi-bot flag** — `isTelegramMultiBot`, `isSharedMultiBot`, and `isMultiBotWizard` have all been merged into a single `isMultiBot` boolean throughout the codebase. Reduces complexity and eliminates divergent code paths.
+- **Fixed `agentDir` path resolution** — `agentDir` in generated `openclaw.json` is now correctly set as `.openclaw/agents/{slug}/agent` (relative to `OPENCLAW_HOME`). Previously used an incorrect project-root-level `agents/{slug}/agent` path that caused double-prefix errors at runtime.
+- **Removed redundant `agents/` root folder creation** — OS scripts no longer attempt to `mkdir agents/` at the project root; all agent files are created under `.openclaw/agents/`.
+
+### 🧹 Config Generation Cleanup
+
+- **Removed per-agent `auth-profiles.json` for 9Router/proxy mode** — When the provider is a proxy (9Router), per-agent `auth-profiles.json` is no longer generated. This file is only created for direct API providers where per-agent authentication is required.
+- **Removed `.env` generation for native deployments** — Bot tokens and API keys for native mode are now managed via `openclaw channels login` / the 9Router dashboard. No `.env` is auto-generated in native scripts to avoid credential sprawl.
+- **Removed per-agent `models.json` for Ollama (CLI)** — Ollama model config is already declared in `openclaw.json → agents.defaults.model`. The redundant per-agent `models.json` in `agents/{id}/agent/` is no longer generated.
+
+### 🤝 Cross-Workspace Rules in AGENTS.md
+
+- **Multi-bot `AGENTS.md` now includes a "Cross-Workspace" section** — In multi-bot (relay) mode, each bot's `AGENTS.md` receives a `🤝 Workspace Chéo (Multi-Agent)` / `🤝 Cross-Workspace (Multi-Agent)` section listing the workspace paths of sibling bots. Rules: bots may read each other's `IDENTITY`, `SOUL`, and `MEMORY` files for shared context; they must not delete or overwrite each other's workspace files without explicit user instruction.
+
+### 🔧 win-bat.js Refactor
+
+- **Extracted `appendGatewayStart()` and `appendDashboardInfo()` helpers** — Repeated PowerShell gateway launch and dashboard URL blocks are now deduplicated into two local helper functions inside `generateWinBat`, reducing the Windows batch generator by ~50 lines.
+
+
+## [5.3.5] — 2026-04-12
+
+### 🐛 Fix: MEMORY.md Syntax Error in Zalo Workspace Files
+
+- **Fix: `SyntaxError: Unexpected token ':'` in `setup.js`** — the previous TOOLS.md patch was inserted after the `vi` ternary arm of MEMORY.md, orphaning the `: en-value` colon arm below it. VS Code showed this as 7 error badges on `setup.js`. Now fixed; both MEMORY.md arms are contiguous, then TOOLS.md follows as a clean separate property.
+
+### 🐟 Improvement: Uninstall Script Written to Project Folder
+
+- **All 4 OS native flows + Docker ZIP** now include the matching `uninstall-*.{bat,sh}` script **in the project folder** during setup. Previously the uninstall was only available as a separate browser download. Pattern mirrors `start-chrome-debug.bat` / `.sh`:
+  - Windows native: `uninstall-openclaw-win.bat` written via `appendBatWriteCommands`
+  - macOS native: `uninstall-openclaw.sh` written via `appendShWriteCommands`
+  - VPS/Ubuntu: `uninstall-openclaw-vps.sh` written via `appendShWriteCommands`
+  - Linux Desktop: `uninstall-openclaw.sh` written via `appendShWriteCommands`
+  - Docker (all OS): uninstall script included in the generatedFiles ZIP
+
+
+
+### 🐛 Windows Native — Gateway & Workspace Stability
+
+- **Fix: Gateway terminal auto-closing** — `call openclaw gateway run` was blocking the setup terminal indefinitely; closing the window killed the gateway process. The gateway is now launched in a **dedicated, visible CMD window** via a PS1 background launcher (same pattern as 9Router), so the setup terminal closes cleanly while the gateway keeps running.
+- **Fix: `call` missing from `openclaw gateway stop`** — The gateway stop command before relaunch was missing the `call` keyword, which could prevent the bat script from returning control after the stop completes. Added `call openclaw gateway stop 2>nul` in all affected paths.
+- **Fix: Workspace naming** — Single-bot deployments previously used a generic `.openclaw/workspace` path. All agents (single-bot and multi-bot) now use a named directory matching their agent ID: `.openclaw/workspace-{agentId}` (e.g. `workspace-williams`, `workspace-luna`). This prevents workspace collisions and aligns the folder structure with the `agents/{agentId}` directory convention.
+- **Improve: TOOLS.md enriched for all bots** — The generated `TOOLS.md` now includes both the custom skills & conventions section AND a "Local Notes" template section adapted from the OpenClaw workspace default, giving users a clear starting point for documenting environment-specific config.
+- **Improve: Zalo bot AGENTS.md now includes security rules** — The generated `AGENTS.md` for Zalo Personal bots (Luna-pattern) now appends the same `🔐 Security Rules — MANDATORY` block that Telegram bots receive (file-system boundaries, credential hygiene, crypto wallet protection, Docker mount rules).
+- **Improve: Zalo bot TOOLS.md added** — Zalo bot workspaces now receive a `TOOLS.md` file with the same skills list and conventions structure as Telegram bots.
+
+
+## [5.3.3] — 2026-04-11
+
+### 🧹 Automated Uninstall Scripts
+
+- **Wizard UI Generation**: The HTML setup wizard now generates a matching `uninstall-openclaw-*.bat/sh` script when downloading the configuration for Native or Docker deployments.
+- **Complete Cleanup**: The generated scripts cleanly kill 9Router/OpenClaw background processes, uninstall global npm packages, and safely remove the project and `.9router` data directories, allowing for a fresh start whenever needed.
+
+
+
+## [5.3.2] — 2026-04-11
+
+### 🐛 Windows Native — 9Router Launch Stability
+
+- **Fix: Remove `-l` (stdin listen) flag from native 9Router launch** — `resolveNative9RouterDesktopLaunch()` previously passed `-l` which puts 9Router into interactive REPL mode. When spawned as a background process (no TTY), this caused the process to hang waiting for stdin input. Removed the flag; 9Router now starts reliably in the background on Windows, macOS desktop, and any non-VPS native flow.
+- **Fix: Pre-seed `DATA_DIR/.9router/db.json` with `requireLogin: false` before 9Router starts** — If `db.json` does not exist when 9Router boots, it uses its own default path (`~/.9router`) and defaults `requireLogin` to `true`, causing the dashboard login wall. The CLI wizard now creates the `.9router` directory and writes a minimal `db.json` (with `requireLogin: false`) **before** spawning 9Router, matching the behavior of the fixed `setup-openclaw-win.bat` batch file.
+- **No change to PM2/VPS flow** — The fix applies only to the desktop/background spawn path (`osChoice !== 'vps'`). VPS users still use the existing PM2-managed `startNative9RouterPm2` flow which is unaffected.
+
+## [5.3.1] — 2026-04-10
+
+### 🌟 Zalo Personal DM Policy
+
+- **Open Zalo Inboxes**: The default `dmPolicy` for Zalo Personal deployments has been changed from `pairing` to `open`. This allows any user on the Zalo network to interact with the AI assistant immediately without requiring explicit device pairing approvals natively.
+
+
+## [5.3.0] — 2026-04-11
+
+### 🆕 Multi-Channel: Telegram + Zalo Personal Simultaneously
+
+- **Combo channel option** — New `telegram+zalo-personal` option in both CLI wizard (`select`) and web wizard (channel card). Selecting it configures a single bot to receive messages from both Telegram and Zalo Personal at the same time.
+- **Auto-inject `plugins.entries.zalouser`** — When any Zalo Personal channel is selected, `openclaw.json` now automatically includes `plugins.entries.zalouser: { enabled: true }`, fixing the root cause of the "not configured" error on Zalo startup.
+- **Docker cold-start fix in Dockerfile CMD** — A background `(sleep 45 && node -e '...touch historyLimit...')` script is now baked into the generated `Dockerfile` CMD. Triggers chokidar → gateway hot-reload → `restartChannel('zalouser')` after Docker network warms up. No more manual `lastTouchedAt` workarounds.
+- **Helper predicates** — Added `hasTelegram(ck)` and `hasZaloPersonal(ck)` functions replacing all literal `channelKey === 'telegram/zalo-personal'` comparisons throughout `cli.js` for cleaner extensibility.
+- **Smoke tests updated** — `tests/smoke-cli-logic.mjs` updated to match the new predicate-based assertions (78 checks passing).
+
+## [5.2.4] — 2026-04-10
+
+### 🐛 Bug Fixes & Developer Tooling
+
+- **Fix: `docker compose build --no-cache` during upgrade** — Removed the `--no-cache` flag from the upgrade flow. Without it, Docker correctly reuses cached layers (including Playwright/Chromium ~300MB) and only rebuilds the `openclaw` layer that changed, making upgrades significantly faster.
+- **UX: Upgrade CLI banner now matches upgrade.ps1/sh style** — `runUpgrade()` in `cli.js` now renders the same ╭╮╰╯ box using visual-width calculation (`vw()`) instead of plain `===` separators.
+- **New: GitHub Actions workflow to auto-detect openclaw updates** — `.github/workflows/check-openclaw-update.yml` runs daily, compares the pinned `OPENCLAW_NPM_SPEC` in `cli.js` with the latest version on npm, and automatically creates a GitHub Issue with upgrade instructions if a new version is available.
+
+## [5.2.3] — 2026-04-10
+
+### 🐛 Bug Fixes & Encoding Improvements
+
+- **Fix: `ReferenceError: projectDir is not defined`** — Crash when clicking "Generate Configs" in multi-bot mode. `nativeProjectOpenClawRoot` in `buildTelegramPostInstallChecklist()` referenced an undefined `projectDir` variable and was dead code (unused in return value). Removed.
+- **Fix: Step 3 "Next" button validation** — `state._activeBotTab` was a typo of `state.activeBotIndex`, causing multi-bot validation to always read the wrong tab index.
+- **Fix: `saveFormData()` always saved bot tab name to `bots[0]`** — In multi-bot mode, the active bot name was always written to `bots[0]` regardless of which tab was active. Now correctly saves to `bots[state.activeBotIndex]`.
+- **UX: Inline hint for disabled "Generate Configs" button** — When the button is blocked, a warning now appears showing exactly which fields are still missing (e.g. "Missing: GOOGLE_API_KEY").
+- **Fix: Vietnamese diacritics in generated `.bat` and `.sh` scripts** — All Vietnamese echo/Write-Host strings in the generated Windows setup script and Linux/macOS bash script have been converted to ASCII (no diacritics) to prevent encoding errors on systems with non-UTF-8 codepages.
+
+## [5.2.2] — 2026-04-10
+
+
+### 🐛 Docker & Native PM2 Bug Fixes
+
+- **Fix Docker crash loop (socat port conflict)**: `socat TCP-LISTEN:18791` was binding `0.0.0.0:18791` before `openclaw gateway run` started, causing `EADDRINUSE` on `127.0.0.1:18791`. Removed the broken gateway bridge from the generated Dockerfile CMD in both `cli.js` and `setup.js`.
+- **Fix Docker dashboard not accessible from host**: Gateway `bind` was set to `'loopback'` — Docker port mapping cannot route to container loopback. Restored the v5.0.9 working pattern: `bind:'custom', customBindHost:'0.0.0.0'`.
+- **Fix `delete c.gateway.customBindHost`**: A stray `delete` statement was erasing the `customBindHost` key right after setting it. Removed.
+- **Fix Docker build re-downloading npm packages on every rebuild**: `ARG CACHEBUST=<epoch>` was cache-busting the `npm install -g openclaw` layer on every build (even config-only changes). Replaced with a version-stable `ARG OPENCLAW_VER` so Docker layer cache is reused between rebuilds.
+- **Fix native PM2 double `.openclaw` nesting**: `ecosystem.config.js` was setting `OPENCLAW_HOME: projectDir/.openclaw`, causing OpenClaw to resolve workspace as `projectDir/.openclaw/.openclaw/workspace`. Removed `OPENCLAW_HOME` from PM2 env; OpenClaw discovers config via `cwd` (matching v5.0.9 behavior).
+
+## [5.2.1] — 2026-04-09
+
+### 🐛 Native Ubuntu/VPS Bug Fixes
+
+- **Fix `Bot-9router errored` (PM2)**: `resolveNative9RouterDesktopLaunch` was trying to locate `9router/app/server.js` inside npm global dirs — a path that doesn't exist after standard `npm install -g 9router`. Now uses the `9router` CLI binary directly with proper args (`-n -l -H 0.0.0.0 -p 20128 --skip-update`), preventing the `↺ 15` restart loop.
+- **Fix double `.openclaw` workspace path**: `workspace` and `agentDir` in generated `openclaw.json` were set as absolute paths (e.g. `/home/user/bot/.openclaw/workspace`). OpenClaw resolves these relative to `OPENCLAW_HOME`, causing a double-prefix (`/home/user/bot/.openclaw/.openclaw/workspace`). Changed to relative paths (`workspace`, `agents/<id>/agent`) matching Docker behavior.
+- **Fix missing runtime packages on native install**: `grammy`, `@grammyjs/runner`, `@grammyjs/transformer-throttler`, `@buape/carbon`, `@larksuiteoapi/node-sdk`, `@slack/web-api` were installed in Docker (Dockerfile) but skipped on native. `installLatestOpenClaw` now installs all `OPENCLAW_RUNTIME_PACKAGES` after the main binary.
+- **Fix `openclaw: command not found` after install**: Post-setup Zalo login instructions now include a `source ~/.bashrc && source ~/.profile` hint for new terminal sessions on Linux.
+- **Fix Zalo session stored in wrong directory**: Manual login hint now includes `OPENCLAW_HOME` and `OPENCLAW_STATE_DIR` env vars so sessions are saved to `<projectDir>/.openclaw/credentials/zalouser/` — the same path the PM2 gateway reads from.
+- **Fix relative project path**: `projectDir` input is now normalized with `path.resolve()` so typing `home/ubuntu/bot` (without leading `/`) correctly resolves to `/home/ubuntu/bot`.
+
+
+## [5.2.0] — 2026-04-09
+
+### One-Command Upgrade (No Wizard Required)
+
+- Added `upgrade` subcommand to the CLI: `npx create-openclaw-bot@latest upgrade`. Detects Docker vs Native mode automatically and updates OpenClaw without re-running the setup wizard.
+- Added `upgrade.ps1` for Windows users — double-click in the bot folder to trigger an upgrade. No terminal knowledge required.
+- Added `upgrade.sh` for Linux / macOS / Ubuntu — run `bash upgrade.sh` locally or pipe via `curl` or `wget` directly from GitHub without cloning the repo.
+- All user data is preserved during upgrade: `.env`, `.openclaw/memory/`, sessions, credentials, and 9Router OAuth tokens are never modified.
+- Docker mode: patching `Dockerfile` (`OPENCLAW_NPM_SPEC` + `CACHEBUST` refresh) then `docker compose build --no-cache` + `docker compose up -d`.
+- Native / PM2 mode: reinstalls `openclaw` + `9router` globals then runs `pm2 restart all`.
+
+
+## [5.1.15] — 2026-04-08
+
+### Native Setup Parity & Windows Wizard Fixes
+
+- Fixed the Windows native HTML wizard so downloaded `.bat` files always regenerate from the latest UI state before download.
+- Fixed Windows native runtime paths to stay project-local: `.env`, `.openclaw`, and `.9router` now resolve from the user-selected project directory instead of home/AppData fallbacks.
+- Added `OPENCLAW_STATE_DIR` to native runtime environments so OpenClaw loads the generated config from the project runtime directory.
+- Replaced legacy `gateway.bind: "0.0.0.0"` output with the current `bind: "custom"` plus `customBindHost: "0.0.0.0"` format.
+- Fixed Windows native single-bot generation so selected provider, model, API key, and Telegram bot token are correctly synced into generated `.env` and `openclaw.json`.
+- Fixed native Windows 9Router launch path resolution and updated the embedded smart-route sync helper to use the live `9Router` API provider list, matching Docker behavior.
+- Added native Windows skill/runtime parity improvements: selected skills now install automatically, browser automation installs its required runtime packages, and skill config entries now use the correct slugs.
+- Updated macOS, Linux Desktop, and Ubuntu/VPS native scripts to launch from the chosen `PROJECT_DIR` and export project-local `OPENCLAW_HOME`, `OPENCLAW_STATE_DIR`, and `DATA_DIR`.
 - Expanded smoke coverage for the native runtime path, 9Router sync, provider/token sync, browser install, and Unix project-local startup flows.
 
 ## [5.1.14] — 2026-04-08
 
 ### OpenClaw stability and Docker fixes
 
-- Pinned OpenClaw back to `openclaw@2026.4.5` because the update published on `April 8, 2026` is currently broken.
-- Fixed Dockerfile generation for Windows Docker setups to avoid startup failures caused by bad command escaping and invalid `allowedOrigins`.
-- Added guidance to use `Node.js 20` through `24`, and to avoid `Node.js 25` for now for better OpenClaw stability.
-
-## [5.1.13] — 2026-04-08
+- Pinned OpenClaw back to `openclaw@2026.4.5` because the update published on `April 8, 2026` is currently broken.
+- Fixed Dockerfile generation for Windows Docker setups to avoid startup failures caused by bad command escaping and invalid `allowedOrigins`.
+- Added guidance to use `Node.js 20` through `24`, and to avoid `Node.js 25` for now for better OpenClaw stability.
+
+## [5.1.13] — 2026-04-08
 
 ### 🐛 macOS Install Fixes & Wizard Stability