fix(deploy): improve first-time deployment experience

- Fix release asset naming: add arona-webui-latest.tar.gz/zip aliases
  so README curl commands don't 404
- Enhance .env.example with all config vars and grouped comments
- Add auto npm install to start.sh/start.bat for git clone users
- Enhance docker-compose.yml with healthcheck, extra_hosts, env params
- Update README with first-run setup guide and gateway-side preparation
- Add quick start template to GitHub Release body

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lingshichat

.env.example

@@ -1,18 +1,29 @@
-# OpenClaw WebUI local development template
-# Copy this file to .env and fill real values.
+# Arona WebUI Configuration
+# Copy to .env.local and edit:  cp .env.example .env.local
+# Or use the Setup Wizard:      http://localhost:18790/setup.html
 
-# Login credentials for WebUI
-GATEWAY_USERNAME=admin
-GATEWAY_PASSWORD=
-
-# Optional: token-based auth (if your gateway uses token instead of password)
-GATEWAY_TOKEN=
+# ─── Gateway Connection ───
 
-# OpenClaw gateway websocket URL
+# OpenClaw gateway WebSocket URL
 GATEWAY_URL=ws://127.0.0.1:18789
 
-# Allowed origin for browser access to WebUI
+# Authentication — choose ONE (leave both empty if gateway has no auth)
+GATEWAY_PASSWORD=
+# GATEWAY_TOKEN=
+
+# Browser origin for WebSocket handshake (must match how you access the WebUI)
 GATEWAY_ORIGIN=http://localhost:18790
 
-# WebUI server port
+# Override the WebSocket URL the browser uses to connect to gateway directly.
+# Leave empty for auto-detection. Useful for reverse proxy setups.
+# GATEWAY_PUBLIC_WS_URL=
+
+# ─── WebUI Auth ───
+
+# Login username
+GATEWAY_USERNAME=admin
+
+# ─── Server ───
+
+# HTTP listen port
 PORT=18790

.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+
+      - run: npm ci --production
+
+      - name: Package release archives
+        run: |
+          VERSION="${GITHUB_REF_NAME}"
+          STAGING="arona-webui-${VERSION}"
+
+          mkdir "$STAGING"
+          cp -r src public node_modules "$STAGING/"
+          cp package.json start.bat start.sh .env.example README.md LICENSE "$STAGING/" 2>/dev/null || true
+          cp -r scripts "$STAGING/" 2>/dev/null || true
+          chmod +x "$STAGING/start.sh" "$STAGING/scripts/install.sh" 2>/dev/null || true
+
+          zip -r "arona-webui-${VERSION}.zip" "$STAGING"
+          tar czf "arona-webui-${VERSION}.tar.gz" "$STAGING"
+
+          # Fixed-name aliases so README curl commands always work
+          cp "arona-webui-${VERSION}.zip" "arona-webui-latest.zip"
+          cp "arona-webui-${VERSION}.tar.gz" "arona-webui-latest.tar.gz"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          body: |
+            ## Quick Start / 快速开始
+
+            **Windows**: Download `.zip` → Extract → Double-click `start.bat`
+
+            **macOS / Linux**:
+            ```bash
+            curl -fsSL https://github.com/lingshichat/Arona_WebUI/releases/latest/download/arona-webui-latest.tar.gz | tar xz
+            cd arona-webui-*/
+            ./start.sh
+            ```
+
+            **Docker**:
+            ```bash
+            GATEWAY_URL=ws://your-gateway:18789 GATEWAY_PASSWORD=xxx docker compose up -d
+            ```
+
+            首次启动浏览器会自动打开配置向导，按提示填入网关地址和密码即可。
+
+            详见 [README](https://github.com/lingshichat/Arona_WebUI#readme)。
+          files: |
+            arona-webui-*.zip
+            arona-webui-*.tar.gz

README.md

@@ -50,26 +50,146 @@ Monitor, configure, and interact with your OpenClaw instance from the browser.
 
 ## Quick Start / 快速开始
 
+### Windows
+
+1. Install [Node.js](https://nodejs.org/) 18+ (if not already) / 安装 [Node.js](https://nodejs.org/) 18+
+2. Download `arona-webui-latest.zip` from [Latest Release](https://github.com/lingshichat/Arona_WebUI/releases/latest) / 从 [最新发行版](https://github.com/lingshichat/Arona_WebUI/releases/latest) 下载 `.zip`
+3. Extract the zip / 解压
+4. Double-click **`start.bat`** / 双击 **`start.bat`**（首次会自动安装依赖）
+5. Browser opens automatically → Setup Wizard / 浏览器自动打开 → 配置向导
+
+### macOS / Linux
+
+```bash
+# 1. Install Node.js 18+ (if not already)
+#    macOS: brew install node
+#    Ubuntu: sudo apt install -y nodejs
+
+# 2. Download & extract latest release / 下载解压最新发行包
+curl -fsSL https://github.com/lingshichat/Arona_WebUI/releases/latest/download/arona-webui-latest.tar.gz \
+  | tar xz
+cd arona-webui-*/
+
+# 3. Start (auto-installs dependencies on first run) / 启动（首次自动安装依赖）
+./start.sh
+```
+
+### First-run Setup / 首次配置
+
+On first launch, the browser will open the **Setup Wizard** automatically:
+
+首次启动时，浏览器会自动打开**配置向导**：
+
+1. **Fill in your gateway info / 填写网关信息** — Gateway URL (`ws://127.0.0.1:18789`), password or token, username
+2. **Test connection / 测试连接** — Click "测试连接" to verify
+3. **Save & restart / 保存重启** — WebUI restarts and connects to your gateway
+4. **(Optional) Patch gateway / 配置网关** — Set `allowedOrigins` and `dangerouslyDisableDeviceAuth` on your gateway
+
+> You can also skip the wizard and configure manually: `cp .env.example .env.local` then edit.
+>
+> 也可以跳过向导手动配置：`cp .env.example .env.local` 然后编辑。
+
+### Gateway-side preparation / 网关侧准备
+
+If your gateway uses **non-loopback** access (e.g. LAN or Docker), you may need to configure it:
+
+如果网关不是 loopback 访问（如局域网或 Docker），可能需要在网关侧配置：
+
+```json5
+// ~/.openclaw/openclaw.json
+{
+  gateway: {
+    controlUi: {
+      allowedOrigins: ["http://localhost:18790"],
+      dangerouslyDisableDeviceAuth: true  // required for Arona WebUI
+    }
+  }
+}
+```
+
+Or use `openclaw config set` / 或通过命令设置：
+
+```bash
+openclaw config set gateway.controlUi.allowedOrigins '["http://localhost:18790"]'
+openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth true
+```
+
+> The Setup Wizard (Step 3) can also apply these settings automatically via WebSocket.
+>
+> 配置向导第 3 步也可以通过 WebSocket 自动应用这些设置。
+
+> Default port is `18790`. To change it, edit `PORT=<your-port>` in `.env.local`.
+>
+> 默认端口 `18790`。如需修改，在 `.env.local` 中设置 `PORT=<端口号>`。
+
+---
+
+## Other Install Methods / 其他安装方式
+
+<details>
+<summary><b>One-line Install Script / 一键安装脚本</b></summary>
+
 ```bash
-git clone https://github.com/nicepkg/arona-webui.git
-cd arona-webui
-npm install
+bash <(curl -fsSL https://raw.githubusercontent.com/lingshichat/Arona_WebUI/main/scripts/install.sh)
 ```
 
-Create `.env.local` with your gateway connection info / 创建 `.env.local` 填写网关连接信息：
+Downloads the latest release, extracts it, and walks you through configuring `.env.local` interactively.
+
+下载最新发行包、解压、交互式配置 `.env.local`。
+
+</details>
 
-```env
-GATEWAY_URL=ws://127.0.0.1:18789
-GATEWAY_PASSWORD=your-gateway-password
+<details>
+<summary><b>Docker</b></summary>
+
+```bash
+git clone https://github.com/lingshichat/Arona_WebUI.git
+cd Arona_WebUI
+docker compose up -d
+# Open http://localhost:18790 → Setup Wizard
+```
+
+Gateway on another machine / 网关在其他机器上：
+
+```bash
+GATEWAY_URL=ws://192.168.1.100:18789 GATEWAY_PASSWORD=xxx docker compose up -d
 ```
 
-Start the server / 启动服务：
+> **Linux host gateway / Linux 宿主机网关**: Uncomment `extra_hosts` in `docker-compose.yml`, or use `network_mode: host`.
+>
+> **Linux 宿主机网关**: 取消 `docker-compose.yml` 中 `extra_hosts` 的注释，或使用 `network_mode: host`。
+
+</details>
+
+<details>
+<summary><b>Manual / 手动安装（开发者）</b></summary>
 
 ```bash
-npm start
-# Open / 打开 http://localhost:18790
+git clone https://github.com/lingshichat/Arona_WebUI.git
+cd Arona_WebUI
+./start.sh        # auto-installs deps + starts server / 自动安装依赖并启动
+# Or: npm install && npm start
+# Open http://localhost:18790 → Setup Wizard
 ```
 
+</details>
+
+## Setup Wizard / 配置向导
+
+On first launch, the browser auto-redirects to the Setup Wizard. You can also open it manually:
+
+首次启动时浏览器会自动跳转到配置向导，也可以手动访问：
+
+```
+http://localhost:18790/setup.html
+```
+
+The wizard guides you through: WebUI config → connection check → gateway config.
+
+向导流程：WebUI 配置 → 连接检测 → 网关配置（bind / allowedOrigins / disableDeviceAuth）。
+
+> Setup APIs are localhost-only (403 from remote). / Setup API 仅限本机访问。
+
 ## Configuration / 配置项
 
 | Variable / 变量 | Default / 默认值 | Description / 说明 |

docker-compose.yml

@@ -0,0 +1,38 @@
+# Arona WebUI — Docker Compose
+#
+# Quick start:
+#   docker compose up -d
+#
+# With custom env:
+#   cp .env.example .env.local
+#   # edit .env.local, then:
+#   docker compose --env-file .env.local up -d
+#
+# Linux host gateway:
+#   If OpenClaw gateway runs on the Docker host (Linux), uncomment
+#   extra_hosts below, or use network_mode: host instead.
+
+services:
+  arona-webui:
+    build: .
+    ports:
+      - "${PORT:-18790}:18790"
+    environment:
+      - GATEWAY_URL=${GATEWAY_URL:-ws://host.docker.internal:18789}
+      - GATEWAY_ORIGIN=${GATEWAY_ORIGIN:-http://localhost:18790}
+      - GATEWAY_USERNAME=${GATEWAY_USERNAME:-admin}
+      # Auth — uncomment one:
+      # - GATEWAY_PASSWORD=your-password
+      # - GATEWAY_TOKEN=your-token
+      # Browser WS override (for reverse proxy):
+      # - GATEWAY_PUBLIC_WS_URL=
+    # Linux: enable host.docker.internal
+    # extra_hosts:
+    #   - "host.docker.internal:host-gateway"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:18790/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s

start.bat

@@ -0,0 +1,40 @@
+@echo off
+chcp 65001 >nul 2>&1
+title Arona WebUI
+
+:: Check Node.js
+where node >nul 2>&1
+if %errorlevel% neq 0 (
+    echo.
+    echo  [ERROR] Node.js is not installed or not in PATH.
+    echo.
+    echo  Please download and install Node.js 18+ from:
+    echo    https://nodejs.org/
+    echo.
+    pause
+    exit /b 1
+)
+
+:: Auto-install dependencies if missing
+if not exist "node_modules" (
+    echo  Installing dependencies...
+    npm install --production
+)
+
+:: Read PORT from .env.local (default 18790)
+set PORT=18790
+if exist .env.local (
+    for /f "tokens=1,* delims==" %%A in (.env.local) do (
+        if "%%A"=="PORT" set PORT=%%B
+    )
+)
+
+:: Start server
+echo  Starting Arona WebUI on port %PORT% ...
+start "" "http://localhost:%PORT%"
+node src/server.mjs
+if %errorlevel% neq 0 (
+    echo.
+    echo  [ERROR] Server exited with an error.
+    pause
+)

start.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")"
+
+# Check Node.js
+if ! command -v node &>/dev/null; then
+  echo ""
+  echo "  [ERROR] Node.js is not installed."
+  echo ""
+  echo "  macOS:   brew install node"
+  echo "  Ubuntu:  sudo apt install -y nodejs"
+  echo "  Windows: https://nodejs.org/"
+  echo ""
+  exit 1
+fi
+
+# Auto-install dependencies if missing
+if [ ! -d "node_modules" ]; then
+  echo "  Installing dependencies..."
+  npm install --production
+fi
+
+# Read PORT from .env.local (default 18790)
+PORT=18790
+if [ -f .env.local ]; then
+  _p=$(grep '^PORT=' .env.local 2>/dev/null | cut -d= -f2)
+  [ -n "$_p" ] && PORT="$_p"
+fi
+
+echo "  Starting Arona WebUI on port ${PORT} ..."
+
+# Start server in background
+node src/server.mjs &
+SERVER_PID=$!
+
+# Wait briefly then open browser
+sleep 1
+URL="http://localhost:${PORT}"
+if command -v xdg-open &>/dev/null; then
+  xdg-open "$URL" 2>/dev/null || true
+elif command -v open &>/dev/null; then
+  open "$URL" 2>/dev/null || true
+fi
+
+# Wait for server process
+wait $SERVER_PID