release: bump version to v0.9.1 (#6)

Co-authored-by: Tao <dtzp555@gmail.com>

DEVLOG.md

@@ -1,7 +1,349 @@
 # OpenClaw Manager — 开发日志
 
-> 最后更新：2026-02-24
-> 当前版本：v0.5.0
+> 最后更新：2026-03-01
+> 当前版本：v0.9.0
+
+---
+
+
+## v0.9.0 更新日志（2026-03-01）
+
+### New Features
+
+- Agents: Add Agent / Add Sub-Agent 向导支持 Telegram + Discord
+  - Telegram: 传统 group 绑定
+  - Discord: 主 Agent 建议绑定 Channel；Sub-Agent 建议绑定 Thread
+- Routing: 删除绑定提示文案增强（支持“更换 group/thread → 先删旧绑定再加新绑定”）
+
+### UX / UI
+
+- 顶部居中显示醒目的 OCM 版本标识
+- Agents 页面：Agent Tree 支持显示 bindings 概览（Telegram/Discord）并按 parentAgentId 分组
+- Setup Guide：补全 Telegram Allow Groups 步骤；Discord guide 按 channel/thread 经验重写
+
+### Fixes
+
+- 修复 MAIN_HTML_SCRIPT 内联 JS 语法问题（tree toggle / i18n 单引号等），避免启动自检失败
+
+## Unreleased（2026-02-28）
+
+### Dashboard / Layout
+
+- Removed the dashboard `HTTP Ping` field (often misleading in Telegram gateway setups)
+- Expanded dashboard visibility with richer gateway routing metadata:
+  - bind host
+  - telegram account count
+  - group count
+  - binding count
+  - allowFrom count
+- Reordered dashboard cards and made `Agents` / `Gateway` cards wider for denser information display
+
+### Bug Fixes
+
+- Fixed `main` agent workspace file browsing/editing fallback:
+  - when agent-level workspace is empty, it now resolves from defaults or `workspace/<agentId>`
+  - writing files now ensures workspace directory exists before save
+
+### UX Clarification
+
+- Channels page hint text updated to position it as **advanced routing management**
+- Clarifies scope difference from Agents page (daily add/remove should stay in Agents)
+- Navigation label updated from `Channels` to `Routing` to reduce conceptual overlap with Agent lifecycle management
+- Added `Routing` page agent filter (`All Agents` + per-agent quick filter) for easier large-tree inspection
+- Added compact grouped rendering in `Routing`: bindings are grouped by agent with expand/collapse support for denser large-config browsing
+
+### Settings UX
+
+- Merged `Models` and `Auth` pages into a single `Models & Auth` tab
+
+### Stats
+
+- Added daily (`1 day`) range option and set it as default
+
+---
+
+## v0.7.1 更新日志（2026-02-27）
+
+### New Features
+
+**Dashboard Guidance Block (Telegram-first usage + safety)**
+- Added a concise guidance card under Dashboard explaining OCM's intended Telegram workflow
+- Clarifies prerequisites: users should already have basic OpenClaw CLI experience
+- Clarifies purpose: OCM mainly helps visualize and update `openclaw.json` for easier main-agent/sub-agent management and multi-tree structures
+- Added explicit Telegram security checklist:
+  - BotFather `Allow Groups = ON`
+  - BotFather `Group Privacy = OFF`
+  - Keep each group private (only you + agent/sub-agents), do not invite others
+
+### Improvements
+
+**Model Dropdown Source — only `openclaw models list`**
+- Model dropdown options are now sourced from real CLI output (`openclaw models list`) instead of built-in/static lists or config-only additions
+- Applies to all relevant selectors: agent/sub-agent creation forms, agent inline model switcher, primary model selector, and fallback picker
+- Added warning message when model list loading/parsing fails
+
+### Technical Notes
+
+- Added model ID parser for CLI output and short-term cache for model list fetches
+- `GET /api/models` now returns:
+  - `knownModels` from CLI
+  - `modelListError` for UI warning display
+- Startup script banners updated to `v0.7.1` (`start.sh` / `start.bat`)
+
+---
+
+## v0.7.0 更新日志（2026-02-27）
+
+### New Features
+
+**Dashboard Redesign — Circular Gauge System Health**
+- CPU%, RAM%, DISK% displayed as SVG circular gauges with colour-coded arcs (green < 70%, amber < 90%, red ≥ 90%)
+- System info card: hostname, OS, Node.js, CPU model, cores, uptime, load average (1/5/15 min)
+- Agent overview: separate main agent count and sub-agent count (plus total)
+- Auto-refresh toggle: when enabled, dashboard polls `/api/dashboard` every 10 seconds
+- Backend now measures CPU usage via `os.cpus()` delta sampling (200ms interval) and returns `loadAvg` from `os.loadavg()`
+
+**Sub-Agent Creation Flow — Step-by-Step Guide Rewrite**
+- Expanded from 3 steps to 5 detailed steps covering the full BotFather → Telegram Group → OCM workflow
+- Step 1: Create new Bot via `/newbot` in BotFather
+- Step 2: Disable Group Privacy via `/mybots` → Bot Settings → Group Privacy → Turn off
+- Step 3: Create Telegram group, add Bot (with security warning)
+- Step 4: Get Group ID from gateway logs
+- Step 5: Fill in the form
+- New "Your Telegram User ID" input field — auto-writes to `channels.telegram.allowFrom` whitelist on creation
+- Security warning banner: "Do NOT add other people to this group" with explanation about API cost risks
+
+**Setup Page — English Localization**
+- All Chinese text in the initial directory selection page translated to English
+- Includes: title, description, labels, placeholders, error messages, button text
+
+### Bug Fixes
+
+**Agent tree: sub-agents not grouped under main (old config format)**
+- **Symptom**: On machines with openclaw.json created before OCM v0.6 multi-bot support, all sub-agents displayed as independent cards instead of nested under main
+- **Root cause**: Old-format bindings lack `accountId` field in sub-agent entries. The tree builder relied on `parentAccountId` to match sub-agents to roots, but old bindings only had `channel` + `peer` — no `accountId`. So `parentAccountId` was null and no parent match was found
+- **Fix**: Fallback inference — if a sub-agent has a peer binding but no `accountId`, automatically infer `parentAccountId` from main's binding (`accountId`) or fall back to `'default'`
+
+### Technical Notes
+
+- **CPU usage measurement:** Two `os.cpus()` snapshots 200ms apart, calculating idle-to-total ratio across all cores
+- **Gauge rendering:** Pure SVG arcs with `stroke-dasharray` animation, no external libraries. 270° arc (gap at bottom), colour transitions via `gaugeColor()` function
+- **allowFrom auto-config:** `POST /api/agents` now accepts optional `telegramUserId` field (numeric string), appends to `channels.telegram.allowFrom[]` if not already present
+- **Old-config compatibility:** Sub-agent bindings without `accountId` are now auto-assigned to the main agent's bot, maintaining backward compatibility with configs created before multi-bot support
+
+---
+
+## v0.6.6 更新日志（2026-02-27）
+
+### Bug Fixes
+
+**Agent tree: main agent not detected as root**
+- **Symptom**: Sub-agents displayed as independent agents instead of under their parent. All agents appeared as orphan roots.
+- **Root cause**: `main` agent in OpenClaw is the default catch-all and typically has NO explicit binding in `openclaw.json`. The `hasOwnBot` detection required an explicit binding with `accountId && !peer`, so `main` was classified as a non-root. Without `main` being a root, sub-agents' `parentAccountId` had no matching root to link to.
+- **Fix**:
+  - `main` is now always treated as a root agent regardless of binding existence
+  - `main`'s `accountId` is inferred from `channels.telegram.accounts`: first unclaimed account (not explicitly bound to another agent), or first account as fallback
+  - Sub-agents with `parentAccountId` matching `main`'s inferred `accountId` now correctly appear under `main` in the tree
+
+---
+
+## v0.6.5 更新日志（2026-02-26）
+
+### New Features
+
+**Dashboard Tab (🏠 Dashboard)**
+- New default landing tab showing system overview at a glance
+- **System card**: hostname, OS, Node.js version, CPU model/cores, uptime, memory usage with progress bar
+- **Gateway card**: process status indicator (running/stopped/unknown) with coloured dot, port, PID, HTTP ping reachability
+- **Agents card**: total agent count, last session activity timestamp (Brisbane time), OCM version, server time
+- **Storage card**: OpenClaw dir size, disk usage with progress bar, free space
+- New `GET /api/dashboard` endpoint aggregates all info (ps grep + curl ping + fs stat)
+- Lazy-loaded on tab switch; auto-loaded on first page load
+
+**Cache-Control + Version-Based Cache Busting**
+- All HTTP responses now include `Cache-Control: no-store, no-cache, must-revalidate`
+- HTML responses include `ETag: "ocm-<version>"` for version-based cache validation
+- All responses include `X-OCM-Version` header
+- Browser `api()` function checks `X-OCM-Version` against client version; shows toast notification when server has been updated, prompting user to refresh
+- Prevents stale frontend from calling deleted/changed API endpoints after update
+
+### Cleanup
+
+**Old `/api/agents/main` endpoint fully removed** (confirmed via code search — no residual references)
+
+### Technical Notes
+
+- Dashboard gateway detection: `ps aux | grep openclaw.*gateway` for process status, `curl --max-time 2 http://127.0.0.1:<port>` for HTTP ping
+- Disk usage: `df -k` for filesystem stats, `du -sk` for OpenClaw dir size
+- Agent last activity: scans `~/.openclaw/agents/*/sessions/*.jsonl` mtime
+- Version cache busting: `OCM_CLIENT_VERSION` is injected into browser script via template literal `${APP_VERSION}`, compared against `X-OCM-Version` response header on every API call
+
+---
+
+## v0.6.0 更新日志（2026-02-26）
+
+### 重大 Bug 修复
+
+**Add Agent 覆盖已有 Bot Token（数据破坏性 Bug）**
+- **症状**：通过 Add Agent 表单添加新 agent 时，直接覆盖 `channels.telegram.botToken`，导致所有已有 agent（包括 sub-agent）全部失效
+- **根本原因**：`POST /api/agents/main` 端点无条件覆盖 `channels.telegram.botToken` 字段，没有保护已有配置
+- **修复**：
+  - 彻底删除 `POST /api/agents/main` 端点
+  - 新建 `POST /api/agents/bot` 端点，使用 OpenClaw 的 `channels.telegram.accounts` 多 bot 结构
+  - 每个新 agent 获得独立的 `accountId` 和 `botToken`，绝不覆盖已有 token
+  - 自动迁移：首次添加新 bot 时，自动将旧格式（顶层 `botToken`）迁移到 `accounts.default`
+- **数据恢复**：程序在修改前自动创建 `openclaw.json.create.*` 备份，可通过 `cp` 恢复
+
+**浏览器 Popover API 命名冲突**
+- **症状**：点击 "＋ Add Agent" / "＋ Add Sub-Agent" 按钮报错 `NotSupportedError: Failed to execute 'togglePopover' on 'HTMLElement'`
+- **根本原因**：自定义函数 `togglePopover()` 与浏览器原生 Popover API 的 `HTMLElement.togglePopover()` 方法冲突
+- **修复**：函数重命名为 `showConfigPop()`
+
+### 架构变更
+
+**多 Bot 支持（Multi-Account）**
+- 支持 OpenClaw 的 `channels.telegram.accounts` 结构，每个主 agent 可绑定独立的 Telegram bot
+- 配置格式：
+  ```json
+  {
+    "channels": { "telegram": { "accounts": {
+      "default": { "botToken": "TOKEN_A" },
+      "research": { "botToken": "TOKEN_B" }
+    }}}
+  }
+  ```
+- `GET /api/agents` 返回 `hasOwnBot` 字段，标识 agent 是否拥有独立 bot
+- Sub-Agent 表单新增 "Parent Agent" 下拉，选择共享哪个 bot（不再硬编码 "main"）
+
+**去除 Landing Page，直接进入主程序**
+- 移除模式选择首页（Sub-agent / Multi-agent 二选一）
+- 启动后直接进入 Agent 管理页面
+- 移除 landing page 相关 HTML、CSS、JS、i18n keys
+
+**Agent 页面重设计（popover 配置窗口）**
+- 不再使用左右分屏布局
+- "＋ Add Agent" / "＋ Add Sub-Agent" 按钮居中显示在 agent 树上方
+- 点击按钮弹出浮动配置窗口（popover），包含引导步骤和表单
+- Agent 树宽度限制 720px 居中，多个 agent 树纵向排列
+
+### 功能改进
+
+**Stats 重写 — 从 session JSONL 文件解析真实用量**
+- 不再从 `gateway.log` 解析（之前一直是 0 数据）
+- 改为扫描 `~/.openclaw/agents/*/sessions/*.jsonl`
+- 解析 `type: "message"` + `role: "assistant"` 的 `message.usage` 字段
+- 新增维度：By Agent（每个 agent 的用量）、Cache Read tokens
+- 测试验证：成功解析出 990 条请求、6 个 agent、10 个模型的真实数据
+
+**Model 下拉 — 只显示已注册模型**
+- 不再使用硬编码的 KNOWN_MODELS 列表
+- 改为从 `openclaw.json` 的 `agents.defaults.models` 读取实际注册的模型
+
+**Agent 树事件委托**
+- `renderAgents()` 中的按钮不再使用 `onclick="func('escaped-string')"` 内联写法
+- 改用 `data-action` / `data-id` 属性 + 事件委托（`agentTreeAction`），避免 template literal 转义问题
+
+**响应式布局**
+- `main` 容器改为 `max-width:100%`，适配不同屏幕宽度
+- 新增 `@media (max-width: 600px)` 断点：侧边导航折叠、按钮纵向排列
+
+**备份时间戳改为 Brisbane 时区**
+- `brisbaneTimestamp()` 函数，所有备份文件名使用 `Australia/Brisbane` 时区
+- 重要：系统所有时间显示统一按 Brisbane 处理
+
+**启动脚本全面重写**
+- `start.sh` / `start.bat` 全部英文
+- 端口冲突时自动 kill 旧进程，而非报错退出
+- 支持 `--host` 参数
+
+**README 重写**
+- 移除所有空的 screenshot 占位符（含敏感 ID 的截图已删除）
+- 更新功能描述匹配 v0.6
+- 精简结构，保留中英文双语
+
+### 新功能 i18n 策略
+
+- v0.6 新增的所有 UI 文案仅提供英文
+- 中文翻译推迟到 v1.0 正式版
+
+### 技术备忘
+
+- **Template literal 转义规则**：MAIN_HTML_SCRIPT 是反引号模板字符串
+  - `\n` → 真实换行（浏览器 JS 字符串跨行 → SyntaxError），必须写 `\\n`
+  - `\'` → `'`（无法用于 onclick 里的引号转义），改用 data 属性 + 事件委托
+  - `\`` → `` ` ``（嵌套模板字符串在 evaluated output 中正常工作）
+- **`assertBrowserScriptSyntax()`** 在启动时检查 MAIN_HTML_SCRIPT 的 evaluated 值
+- **OpenClaw config 多 bot 格式**：`channels.telegram.accounts.<id>.botToken`，binding 用 `accountId` 路由
+
+### 下一步（v0.7+）
+
+- [x] Dashboard 首页 tab（系统信息 + OpenClaw health 状态）— done in v0.6.5
+- [x] HTTP 响应加 `Cache-Control: no-store` + version-based cache busting — done in v0.6.5
+- [x] 彻底删除旧 `/api/agents/main` 端点残留（确认已清除）— confirmed in v0.6.5
+- [x] Agent tree: independent roots per bot + side-by-side layout — done in v0.6.5
+- [x] Agent tree: expand/collapse toggle for sub-agents — done in v0.6.5
+- [x] Add Agent: creates `agents/<id>/sessions/` runtime dirs + SOUL.md personality — done in v0.6.5
+- [x] Agent tree: main agent always root with inferred accountId — done in v0.6.6
+- [ ] Dashboard: auto-refresh every 30s when tab is active
+- [ ] Dashboard: OpenClaw version display (from `openclaw --version`)
+- [ ] Agent page: edit agent name, purpose, personality inline
+- [ ] Agent page: restart gateway button with status feedback
+- [ ] Settings tab: edit openclaw.json key fields via form (model, workspace defaults)
+- [ ] Telegram bot connectivity test button (ping bot API from server)
+- [ ] DEVLOG.md 中文 → 逐步迁移为英文
+
+---
+
+## v0.5.2 更新日志（2026-02-25）
+
+### 修复
+
+**远程访问无法连接（ERR_CONNECTION_REFUSED）**
+- `server.listen` 原来绑定 `127.0.0.1`（仅本机），远程通过 `http://<IP>:3333` 访问时被直接拒绝
+- 改为默认绑定 `0.0.0.0`（所有网卡），远程设备可通过局域网 IP 访问
+- 新增 `--host` 命令行参数：需要限制仅本机访问时可用 `--host 127.0.0.1` 覆盖
+- 新增 `getLanIP()` 工具函数，自动检测第一个非内部 IPv4 地址
+
+### 改进
+
+**启动日志改为英文**
+- 终端启动信息（目录、地址、提示、错误）全部改为英文
+- 绑定 `0.0.0.0` 时自动显示局域网地址，方便远程复制：`🌐 LAN: http://192.168.x.x:3333`
+- 端口占用、启动失败等错误提示同步改为英文
+
+---
+
+## v0.5.1 更新日志（2026-02-25）
+
+### 修复
+
+**Action 菜单英文模式残留中文**
+- 修复 Action 菜单下多处弹窗在 EN 模式仍显示中文的问题（日志、回滚、目录切换、命令输出）
+- 统一接入 i18n：标题、按钮、说明文案、加载态、空态、确认框、toast 文案
+- 菜单项触发后的交互文案现在与语言切换保持一致
+
+### 工程改进
+
+**1) 嵌入脚本转义/语法防护**
+- 新增启动时预检：对前端嵌入脚本执行 `node --check` 语法校验
+- 若语法异常（常见为 `MAIN_HTML` 内 `\n` 转义写错），启动阶段直接报错并给出修复提示，避免浏览器白屏后才发现问题
+
+**2) 单文件结构化重构（保持零依赖）**
+- 将主页面模板从单一超长 `MAIN_HTML` 拆分为三段常量：
+  - `MAIN_HTML_CSS`
+  - `MAIN_HTML_BODY`
+  - `MAIN_HTML_SCRIPT`
+- 最终由 `MAIN_HTML` 组合输出，保持“单文件 + 零依赖”不变，同时降低维护复杂度
+- 修复拆分过程中的脚本模板转义问题：`MAIN_HTML_SCRIPT` 使用普通模板字符串（非 `String.raw`），确保前端脚本内的反引号模板语法可被正确还原
+
+### 其他
+
+- 程序头部版本与启动日志版本更新为 `v0.5.1`
+- `start.sh` / `start.bat` 启动横幅版本号同步更新为 `v0.5.1`
+- `README` 补充 Git 安装/更新流程（`git clone` / `git pull --ff-only`），并精简中英文功能介绍
+- `README` 首屏改版：增加「1 分钟上手」命令区（安装/更新/运行同屏），并将开场介绍改为精简版
+- `README` 去重：移除中部重复的安装/更新/运行段落，统一引用首屏快速上手
+- `README` 截图区改为首屏精简展示（3 张）+ 折叠更多截图（`<details>`）
 
 ---
 

OpenClaw Manager.app/Contents/Info.plist

@@ -9,9 +9,9 @@
     <key>CFBundleIdentifier</key>
     <string>com.openclaw.manager</string>
     <key>CFBundleVersion</key>
-    <string>0.5.0</string>
+    <string>0.7.1</string>
     <key>CFBundleShortVersionString</key>
-    <string>0.5.0</string>
+    <string>0.7.1</string>
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleIconFile</key>

README.md

@@ -1,115 +1,219 @@
 # OpenClaw Manager (OCM)
 
-> A zero-dependency, single-file web UI for managing [OpenClaw](https://github.com/anthropics/openclaw) AI agents locally.
+A local control panel for [OpenClaw](https://github.com/anthropics/openclaw) that makes setup checks, agent management, health inspection, and recovery much easier — without living in JSON and terminal tabs all day.
 
-[中文说明](#中文说明)
+[中文说明](#中文说明) · [中文使用说明（含截图）](docs/USAGE_GUIDE.zh-CN.md) · [English Guide (with screenshots)](docs/USAGE_GUIDE.en.md)
 
 ---
 
-## What is this?
+## Why OCM exists
 
-OpenClaw Manager is a lightweight local web dashboard that lets you visually manage your OpenClaw AI agents, models, auth, cron jobs, and more — without editing JSON files by hand.
+Running OpenClaw directly is powerful, but the day-to-day workflow can get messy fast:
 
-Everything ships as **a single `.js` file** with zero npm dependencies. Just need Node.js 18+.
+- `openclaw.json` is easy to break by hand
+- agent / bot / channel bindings are hard to visualize
+- health checks, logs, restarts, and rollback are scattered across terminal commands
+- when something goes wrong, recovery is slower than it should be
 
-## Screenshots
+OCM gives you a **local control panel** for the things that become painful first:
+- seeing your current setup clearly
+- operating it more safely
+- recovering faster when something breaks
 
-### Landing Page
-Choose between Sub-agent mode and Multi-agent mode. Switch language (EN / 中文) anytime.
+## Is OCM for you?
 
-![Landing Page](screenshots/landing.png)
+**OCM is a good fit if:**
+- you already run OpenClaw locally
+- you want a visual control panel for agents, routing, logs, health, and backups
+- you are tired of editing nested config by hand
+- you want safer rollback / recovery nearby
 
-### Agent Management
-View all agents (main + sub-agents) at a glance. Each card shows model, group binding, and workspace path. Switch models inline, browse files, or delete with auto-backup.
+**OCM is probably not the best starting point if:**
+- you have not installed OpenClaw yet
+- you expect every OS / channel workflow to be equally mature today
+- you want a hosted cloud dashboard instead of a local tool
 
-![Agents](screenshots/agents.png)
+## What OCM helps you do
 
-### New Subagent Wizard
-4-step guided wizard to create a sub-agent: basic info → model → personality & memory → confirm. Fully bilingual.
+### 1) See your OpenClaw setup clearly
+- inspect agents and sub-agents in a tree
+- verify bindings and routing
+- view models, auth, usage, and health in one place
 
-![New Subagent](screenshots/subagents.png)
+### 2) Operate OpenClaw with less risk
+- restart gateway
+- inspect logs
+- run OpenClaw commands from the built-in terminal
+- make config changes with rollback nearby
 
-### Model Selector
-Rich model dropdown grouped by provider — GitHub Copilot, Anthropic, OpenAI, Google, DeepSeek, Kimi, Groq, Mistral, Together, plus your custom models.
+### 3) Recover faster when things go wrong
+- browse backups / snapshots
+- roll back config safely
+- keep troubleshooting and operational tools close to the same UI
 
-![Models](screenshots/models.png)
+## See it quickly
 
-### Actions Menu
-Quick access to gateway operations, backups, health checks, and directory management. Use **"Switch OpenClaw Dir"** to point OCM to your OpenClaw config on first setup.
+These are the highest-value surfaces for first-time users:
 
-![Actions](screenshots/actions.png)
+<p>
+  <img src="docs/redacted-screenshots-refresh/dashboard-2026-03-07.jpg" width="240" />
+  <img src="docs/redacted-screenshots-refresh/agents-2026-03-07.jpg" width="240" />
+  <img src="docs/redacted-screenshots/actions.jpg" width="240" />
+  <img src="docs/redacted-screenshots-refresh/cli-2026-03-07.jpg" width="240" />
+</p>
 
-### Cron Job Management
-View, add, enable/disable, and manually trigger openclaw-related cron tasks. Integrates with NAS backup schedules.
+More screenshots: see the [full usage guide](docs/USAGE_GUIDE.en.md) or the gallery below.
 
-![Cron](screenshots/cron.png)
+<details>
+<summary><b>Full screenshots gallery</b> (redacted: no personal paths, no Telegram IDs)</summary>
 
-### Built-in CLI Terminal
-Run any openclaw command with real-time streaming output. The terminal panel sits at the bottom of the page and expands on demand.
+<p>
+  <img src="docs/redacted-screenshots/dashboard.jpg" width="240" />
+  <img src="docs/redacted-screenshots/agents.jpg" width="240" />
+  <img src="docs/redacted-screenshots/channels.jpg" width="240" />
+  <img src="docs/redacted-screenshots/models.jpg" width="240" />
+  <img src="docs/redacted-screenshots/auth.jpg" width="240" />
+  <img src="docs/redacted-screenshots/stats.jpg" width="240" />
+  <img src="docs/redacted-screenshots/cron.jpg" width="240" />
+  <img src="docs/redacted-screenshots/actions.jpg" width="240" />
+  <img src="docs/redacted-screenshots/cli.jpg" width="240" />
+  <img src="docs/redacted-screenshots/cli-output.jpg" width="240" />
+  <img src="docs/redacted-screenshots/backup-rollback.jpg" width="240" />
+</p>
 
-![CLI Overview](screenshots/cli1.png)
+</details>
 
-Preset command menu with built-in commands and your personal favorites — one click to run.
+## Quick Start (recommended path)
 
-![CLI Presets](screenshots/cli3.png)
+```bash
+# Clone
+git clone https://github.com/dtzp555-max/ocm.git
+cd ocm
 
-Command output streams in real-time. Star frequently used commands for quick access, or use the Manage button to organize favorites.
+# Run (no npm install needed)
+bash start.sh        # macOS / Linux
+start.bat            # Windows
+```
 
-![CLI Detail](screenshots/cli2.png)
+Then open [http://localhost:3333](http://localhost:3333).
 
-## Features
+For remote access, use:
 
-- **Agent Management** — Create sub-agents (with wizard), switch models inline, browse & edit workspace files, delete with auto-backup
-- **Model Selection** — Change global primary model, edit fallback chain
-- **Auth Guide** — Step-by-step instructions for configuring each provider (Anthropic, OpenAI, DeepSeek, Google, GitHub Copilot, etc.)
-- **Token Usage Stats** — Parse `gateway.log` for token usage, view cost breakdown by model and day
-- **Cron Job Management** — View, add, enable/disable, and trigger openclaw-related cron tasks
-- **Workspace File Browser** — Browse all agent workspace files, read-only by default, editable on demand
-- **Backup & Rollback** — Auto-backup before every write, one-click restore from any snapshot
-- **NAS Backup** — SFTP/rsync backup to NAS with legacy SSH cipher compatibility
-- **Built-in CLI Terminal** — Run openclaw commands with real-time streaming output, presets, tab completion
-- **Health Badge** — Auto-run `openclaw doctor` and show warnings in the header
-- **Bilingual UI** — English / 中文, switchable at runtime
-- **Cross-platform** — macOS / Linux / Windows
+```bash
+bash start.sh --host 0.0.0.0
+```
+
+## First-run checklist
+
+For a good first experience, do these first:
+
+1. Confirm OCM found the correct OpenClaw directory
+2. Open **Dashboard** and check gateway health
+3. Open **Agents** / **Channels** and inspect bindings
+4. Open the built-in **Terminal** and run one OpenClaw command
+5. Check **Actions** / backup / rollback so recovery is nearby before you need it
+
+## Current support status
+
+**Best supported today**
+- macOS / Linux
+- local OpenClaw installations
+- local health / logs / ops / backup workflows
+- Telegram-first agent management workflows
+
+**Supported, but not equally smooth in every case**
+- Discord agent / thread workflows
+- more advanced routing setups
+- mixed environment / service layouts
+
+**Not the primary path today**
+- fully beginner-first OpenClaw onboarding
+- every OS / shell / service combination
+- WhatsApp-heavy sub-agent topology workflows
+
+## Common friction points
+
+The most common reasons OCM feels rough are not usually “the UI is broken”, but environment mismatch:
+
+- OpenClaw itself is not fully healthy yet
+- wrong OpenClaw directory
+- path / permission issues
+- different service/runtime layouts across machines
+- channel workflow differences
+
+That is why OCM should be thought of as a **control panel for an existing OpenClaw setup**, not a magic replacement for all installation complexity.
+
+## Docs
+
+- **Start here**: docs/USAGE_GUIDE.en.md
+- 中文使用说明: docs/USAGE_GUIDE.zh-CN.md
+- FAQ: docs/FAQ.md
+- Security notes: docs/SECURITY.md
+- Changelog: docs/CHANGELOG.md
+
+## Features by area
+
+- **Agent Management** — Add main agents and sub-agents through a guided setup flow. View all agents in a tree structure with model selection, workspace browsing, and inline configuration.
+- **Usage Statistics** — Real token usage data parsed directly from OpenClaw session files. Breakdown by model, agent, and day with a visual chart.
+- **Model & Auth** — Configure models from your registered provider list. Follow built-in guides for provider authentication setup.
+- **Built-in CLI** — Available from any page (top-right **Terminal** + bottom dock). Run OpenClaw commands with **real-time streaming output**, **Tab completion**, built-in presets, and your own saved favorites.
+- **Ops Panel** — Restart gateway, view logs, run health checks, manage backups, **rollback/restore configs**, and handle cron tasks.
+- **Backups / Rollback** — Browse auto-snapshots of `openclaw.json*` and restore any previous version (current config is auto-backed up first).
+- **Bilingual UI** — English and Chinese interface with one-click language switching.
+
+## What's New (v0.9.x)
+
+- **Discord support (v0.9.x)**: add agent/sub-agent flows for Discord (main agent binds channel; sub-agent binds thread).
+- **README screenshots gallery**: screenshots grouped into a collapsible section so the homepage stays shorter.
+- **Built-in CLI terminal**: run OpenClaw commands from any page with streaming output, presets, favorites, and Tab completion.
+- **Ops actions**: restart gateway, view logs, health check, backups (local + NAS), and cron management.
+- **Telegram-first workflow**: safer sub-agent setup flow + allowlist helper + warnings for group privacy.
+
+## Channel Support
+
+OCM is a local UI for OpenClaw. Core features like agent trees, routing, models/auth, ops, backups, and the built-in CLI are channel-agnostic.
+
+Current channel positioning:
+
+- **Telegram** — best supported and most documented today
+- **Discord** — supported; recommended for private channels/threads with strict allowlist
+- **Feishu / Lark** — supported in broader OpenClaw ecosystems, but not a primary OCM workflow today
+- **WhatsApp** — not recommended for sub-agent topology workflows
+
+## Recommended Workflows
+
+OCM is **Telegram-first, not Telegram-only**. Telegram is the smoothest path today, but OCM is also useful for local ops, Discord routing, model/auth management, and backups.
+
+### Telegram Workflow & Safety
+
+OCM is designed primarily for **Telegram-based OpenClaw workflows**:
+
+- Bind Telegram groups to one or more main agents, then create sub-agents under each tree
+- Keep each agent's context isolated via independent `workspace`, `SOUL.md`, and `MEMORY.md`
+- OCM mainly helps you **safely update `openclaw.json`** via UI instead of manual editing
+- Recommended for users who already have basic OpenClaw CLI experience (`onboard`, auth, gateway logs)
+
+Critical Telegram settings:
+
+- In BotFather, keep **Allow Groups = ON**
+- In BotFather, set **Group Privacy = OFF**
+- For each agent group, keep it private: **only you + that agent/sub-agents**
+- Do **not** invite other people to these groups (cost and security risk)
 
 ## Requirements
 
-- Node.js >= 18 ([download](https://nodejs.org/))
+- Node.js 18+ ([download](https://nodejs.org/))
 - A working [OpenClaw](https://github.com/anthropics/openclaw) installation
 
-## Quick Start
-
-```bash
-git clone https://github.com/dtzp555-max/ocm.git
-cd ocm
-# No npm install needed
-
-# macOS / Linux
-bash start.sh
-
-# Windows
-start.bat
-```
-
-Then open http://localhost:3333 in your browser.
-
-### First Run
-
-On first launch, the start script auto-detects `~/.openclaw` and creates a `manager-config.json` for you. If your OpenClaw config is elsewhere, use **Actions → Switch OpenClaw Dir** in the UI to point to the correct path.
-
-### macOS Double-click
-
-Double-click `OpenClaw Manager.app` in Finder. On first launch, you may need to allow it in System Settings → Privacy & Security.
-
-### Custom Port
-
-```bash
-bash start.sh --port 8080
-```
-
 ## Configuration
 
-The app locates your OpenClaw config directory in this order:
+On first launch, OCM auto-detects `~/.openclaw` and creates a local `manager-config.json`. If your OpenClaw config is elsewhere, use **Actions → Switch OpenClaw Dir** or specify it directly:
+
+```bash
+bash start.sh --dir /path/to/.openclaw --port 8080
+```
+
+Detection priority:
 
 | Priority | Method |
 |----------|--------|
@@ -124,9 +228,29 @@ You can also create `manager-config.json` manually:
 { "dir": "~/.openclaw" }
 ```
 
-`~` expands to your home directory on all platforms. `manager-config.json` is in `.gitignore` and won't be committed.
+`manager-config.json` is gitignored and won't be committed.
 
-## Optional: Shell Alias
+## First-Run Experience
+
+The first thing new users need is confidence that OCM is pointed at the right OpenClaw directory and that the gateway is healthy. The Dashboard, built-in CLI, and health/ops actions are intended to make that first-run check fast and visible.
+
+Recommended first demo flow:
+
+1. Start OCM
+2. Open Dashboard and confirm gateway health
+3. Open Agents / Routing and inspect bindings
+4. Run one CLI command from the built-in terminal
+5. Try backup / rollback from Ops
+
+## Remote Access
+
+By default OCM binds to `0.0.0.0` (all interfaces). Access it from another device on your LAN using the IP shown at startup. To restrict to localhost only:
+
+```bash
+bash start.sh --host 127.0.0.1
+```
+
+## Shell Alias (Optional)
 
 ```bash
 # Add to ~/.zshrc or ~/.bashrc
@@ -137,13 +261,11 @@ alias ocm="bash ~/path/to/ocm/start.sh"
 
 ```
 ocm/
-├── openclaw-manager.js          ← The entire app (server + frontend, single file)
-├── start.sh                     ← macOS/Linux start script (auto-detect Node, port, config)
-├── start.bat                    ← Windows start script
+├── openclaw-manager.js    ← Entire app (server + frontend, single file)
+├── start.sh               ← macOS/Linux launcher (auto-detect, port conflict handling)
+├── start.bat              ← Windows launcher
 ├── OpenClaw Manager.app/  ← macOS Finder double-click launcher
-├── screenshots/                 ← README screenshots
 ├── manager-config.json    ← Local config (gitignored)
-├── package.json
 ├── DEVLOG.md              ← Development log
 └── README.md
 ```
@@ -162,89 +284,75 @@ MIT
 
 ## 中文说明
 
-### 简介
+OpenClaw Manager（OCM）是一个本地 OpenClaw 控制面板，用来更直观地管理 Agent、查看绑定关系、做健康检查、运行内置 CLI，并在改配置或排错时少踩坑。
 
-OpenClaw Manager 是一个零依赖的本地 Web 管理界面，用于可视化管理 [OpenClaw](https://github.com/anthropics/openclaw) AI 智能体。所有代码合并在一个 `.js` 文件中，只需要 Node.js 18+，不需要 `npm install`。
+### OCM 解决什么问题
 
-### 界面预览
+直接使用 OpenClaw 很强，但日常维护很容易变成：
+- 改 `openclaw.json` 容易手滑
+- Agent / bot / 群 / 线程绑定关系很难一眼看清
+- 健康检查、日志、重启、回滚散落在多个终端命令里
+- 出问题时恢复链路不够顺手
 
-#### 模式选择
-![Landing](screenshots/landing.png)
+OCM 的定位不是替代 OpenClaw，而是给现有 OpenClaw 环境加一个**本地控制台**。
 
-#### Agent 管理 & 新建向导
-![Agents](screenshots/agents.png)
-![New Subagent](screenshots/subagents.png)
+### 适合谁
 
-#### 模型选择 & 操作菜单
-首次安装后，通过 **Actions → Switch OpenClaw Dir** 指向你的 OpenClaw 配置目录即可开始使用。
+**适合：**
+- 已经在本机跑通 OpenClaw 的用户
+- 想更直观地管理 Agent / Routing / Health / Logs / Backups 的用户
+- 不想频繁手改复杂 JSON 的用户
 
-![Models](screenshots/models.png)
-![Actions](screenshots/actions.png)
+**暂时不太适合：**
+- 还没装好 OpenClaw、希望 OCM 包办全部安装复杂度的新手
+- 默认期待所有平台 / 所有 channel 路线都同样成熟的用户
+- 想要云端托管产品而不是本地工具的用户
 
-#### Cron 定时任务
-![Cron](screenshots/cron.png)
+### OCM 最有价值的三件事
 
-#### 内置 CLI 终端
-底部终端面板，支持实时流式输出、预设命令、收藏夹、Tab 补全。
-
-![CLI](screenshots/cli1.png)
-![CLI Presets](screenshots/cli3.png)
-![CLI Detail](screenshots/cli2.png)
-
-### 功能一览
-
-- **Agent 管理** — 新建子智能体（含向导）、内联切换模型、查看/编辑工作区文件、删除（自动备份）
-- **模型选择** — 修改全局主模型、编辑 Fallback 链
-- **认证引导** — 各 Provider 分步操作指引 + 一键复制 CLI 命令
-- **Token 用量统计** — 解析网关日志，按模型/天汇总 Token 和费用
-- **Cron 任务管理** — 查看、添加、启用/禁用、手动触发 openclaw 相关定时任务
-- **Workspace 文件浏览器** — 查看所有工作区文件，默认只读，可切换编辑
-- **备份 & 回滚** — 每次写入前自动备份，一键回滚
-- **NAS 备份** — SFTP/rsync 远程备份，兼容老设备 SSH 加密
-- **内置 CLI 终端** — 实时流式输出、预设命令、Tab 补全
-- **健康检查** — 自动运行 `openclaw doctor`，Header 显示状态徽章
-- **中英双语** — 运行时随时切换
-- **跨平台** — macOS / Linux / Windows
+1. **看清你的 OpenClaw 结构**
+   - Agent 树、绑定关系、模型、认证、健康状态更直观
+2. **更安全地做运维操作**
+   - 重启 gateway、看日志、跑 CLI、改配置、回滚更顺手
+3. **出问题时恢复更快**
+   - 备份、回滚、排查入口都更近
 
 ### 快速开始
 
 ```bash
 git clone https://github.com/dtzp555-max/ocm.git
 cd ocm
-
-# macOS / Linux
-bash start.sh
-
-# Windows
-start.bat
+bash start.sh        # macOS / Linux
+start.bat            # Windows
 ```
 
-访问 http://localhost:3333
+打开 [http://localhost:3333](http://localhost:3333)。
 
-### 首次运行
+### 第一次使用建议先做这几步
 
-启动脚本会自动检测 `~/.openclaw` 目录并创建 `manager-config.json`。如果你的 OpenClaw 配置在其他位置，进入界面后点击 **Actions → Switch OpenClaw Dir** 切换即可。
+1. 确认 OCM 找到了正确的 OpenClaw 目录
+2. 打开 **Dashboard** 看 gateway 是否健康
+3. 打开 **Agents / Channels** 看绑定是否正确
+4. 打开内置 **Terminal** 跑一条 OpenClaw 命令
+5. 看一眼 **Actions / 备份 / 回滚**，确保恢复路径就在手边
 
-### 指定 OpenClaw 目录
+### 当前支持定位
 
-程序按以下优先级查找配置：
+**目前最好用的场景：**
+- macOS / Linux
+- 本地 OpenClaw 环境
+- 本地 health / logs / ops / backup 工作流
+- Telegram-first 的 Agent 管理方式
 
-1. `--dir` 命令行参数
-2. `OPENCLAW_DIR` 环境变量
-3. 同目录下的 `manager-config.json`
-4. `~/.openclaw`（默认）
+**支持，但不保证同样顺滑：**
+- Discord workflow
+- 更复杂的 routing / service 布局
+- 混合环境
 
-也可以手动创建 `manager-config.json`：
+### 文档
 
-```json
-{ "dir": "~/.openclaw" }
-```
-
-`~` 在所有平台自动展开为用户主目录。
-
-### Shell 别名（可选）
-
-```bash
-# 加到 ~/.zshrc 或 ~/.bashrc
-alias ocm="bash ~/path/to/ocm/start.sh"
-```
+- 英文使用说明：docs/USAGE_GUIDE.en.md
+- 中文使用说明：docs/USAGE_GUIDE.zh-CN.md
+- FAQ：docs/FAQ.md
+- 安全说明：docs/SECURITY.md
+- 更新记录：docs/CHANGELOG.md

docs/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+This is a user-facing summary derived from `DEVLOG.md`.
+
+## v0.9.0
+- Agents: Telegram + Discord support in Add Agent / Add Sub-Agent wizard (main agent binds channel; sub-agent binds thread).
+- UI: top-center OCM version badge; improved Telegram/Discord setup guides.
+
+## v0.8.2
+- Docs: reorganize README screenshots into a collapsible gallery to reduce scroll.
+- Docs: add Backups / Rollback screenshot and README feature blurb.
+- Docs: refresh redacted screenshots (Channels + Actions + Stats) and feature descriptions.
+
+## v0.8.1
+- Docs: add Stats screenshot and expand feature list.
+
+## v0.8.0
+- Docs: bilingual usage guides refreshed (EN + zh-CN) with redacted screenshots.
+
+## v0.7.6
+- Docs: annotated screenshots with arrows for key UI controls.
+
+## v0.7.5
+- Docs: built-in CLI terminal instructions + screenshot (tab completion, favorites, streaming output).
+
+## v0.7.4
+- Docs: English + Chinese usage guides with redacted screenshots.
+
+## v0.7.1
+- Dashboard guidance block for Telegram-first workflow + safety checklist.
+- Model dropdown options sourced from `openclaw models list`.
+
+## v0.7.0
+- Dashboard redesign with circular CPU/RAM/DISK gauges and auto-refresh.
+- Sub-agent creation flow rewritten (BotFather → group → group id → form) including allowlist helper.
+
+## v0.6.6
+- Fix: sub-agents correctly grouped under main for older config formats.
+
+## v0.6.5
+- New Dashboard tab + cache-busting headers and version checks.

docs/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing (OCM)
+
+This repo is optimized for fast iteration and safe maintenance.
+
+## Workflow (PM + Codex)
+
+Default rule:
+
+- Codex implements changes on a **new branch** and opens a **PR**.
+- Xiao Qiang (PM) reviews + runs local smoke tests.
+- Tao approves.
+- Only after explicit approval, we merge.
+
+Fast-path (small changes):
+
+- For small doc/copy/layout fixes, Tao allows **auto-merge after PM verification** (tests/smoke pass).
+- PM must still send Tao a short completion note with the PR link and summary.
+
+
+## Versioning
+
+- Single source of truth:
+  - `package.json#version`
+  - `openclaw-manager.js` → `APP_VERSION`
+- When bumping a version, update **both** in the same commit.
+- Prefer **semver-ish**: `MAJOR.MINOR.PATCH` (e.g. `0.8.2`).
+
+## Language policy (Docs + UI)
+
+- **DEVLOG.md must be English-only.**
+- UI:
+  - English mode should not show Chinese strings (except user-provided content).
+  - Chinese mode can be fully Chinese.
+- When adding new UI strings, ensure both locales are updated.
+
+## README policy
+
+- Keep the README homepage **short**.
+- Screenshots should be grouped (e.g. in a collapsible gallery) to avoid long scroll.
+- The “Features” section should be **complete** and reflect actual UI capabilities.
+
+## Screenshots (redaction)
+
+- Store public screenshots under: `docs/redacted-screenshots/`
+- Redact sensitive info:
+  - local username/path fragments
+  - Telegram peer IDs
+  - any tokens/keys
+- Prefer **English UI** screenshots.
+- Prefer clean crops (avoid arrows/annotations unless truly necessary).
+
+## Text style
+
+- Be concrete and user-focused.
+- Prefer consistent naming:
+  - “Remote backup setup” (not “NAS backup setup”)
+  - “Backups / Rollback” for restore/snapshot functionality
+
+## PR checklist
+
+- [ ] Description includes: what/why/how
+- [ ] If UI changed: include screenshots
+- [ ] Version updated when needed
+- [ ] English UI audited (no stray Chinese)
+- [ ] `DEVLOG.md` updated (English-only)

docs/FAQ.md

@@ -0,0 +1,62 @@
+# OCM FAQ
+
+## Q: Telegram 群里经常显示 typing，但不回消息？
+
+Most common cause is **BotFather Group Privacy** being ON.
+
+Fix:
+- BotFather → Your bot → Bot Settings → **Group Privacy** → **Turn off**
+
+Also check:
+- `openclaw status` (gateway healthy?)
+- provider auth/rate limits (OCM → Auth page, and gateway logs)
+
+## Q: 如何获取 Telegram Group ID（Peer ID / -100...）？
+
+Typical workflow:
+
+```bash
+openclaw gateway logs --follow
+```
+
+Send a message in the target group; the gateway logs usually contain the peer id.
+
+## Q: 模型下拉列表为什么没有我想要的模型？
+
+OCM sources model options from the real CLI output:
+
+```bash
+openclaw models list
+```
+
+So if it doesn't show up in OCM, make sure it's registered/available in your OpenClaw environment.
+
+## Q: Dashboard 里 Gateway HTTP Ping 显示 Unreachable？
+
+Common reasons:
+- Gateway not running
+- Gateway binds to a different interface/port than OCM expects
+- Local firewall/proxy interference
+
+Try:
+- `openclaw status`
+- `openclaw gateway restart`
+
+## Q: OCM 会把我的 token/个人信息上传出去吗？
+
+OCM is designed as a **local** dashboard.
+
+That said, your local OpenClaw config contains sensitive information. Follow the safety guidance:
+- keep agent Telegram groups private
+- don't share raw screenshots without redaction
+
+See: `docs/SECURITY.md`.
+
+
+## Q: 为什么 OCM 暂时不推荐 WhatsApp 的 sub-agent 工作流？
+
+WhatsApp 在 bot / group 自动化、权限边界和稳定路由上限制更多。
+
+OCM 的 sub-agent 模式依赖清晰的会话边界、独立路由和可控权限，因此目前更推荐 Telegram / Discord 这类更容易做隔离的渠道。
+
+如果未来支持 WhatsApp，更可能先从通知或轻量交互开始，而不是多 sub-agent 群聊拓扑。

docs/SCREENSHOT_REFRESH_BRIEF.md

@@ -0,0 +1,79 @@
+# OCM Screenshot Refresh Brief
+
+Goal: refresh only the highest-value README screenshots first, not every screenshot.
+
+## Redaction rules
+Always hide or blur:
+- Telegram / Discord IDs
+- bindings / peer IDs / thread IDs
+- local filesystem paths containing Tao's name
+- account labels if they expose personal identifiers
+- anything that looks like a secret/token
+
+## Priority 1 screenshots
+
+### 1) Dashboard hero
+Purpose:
+- show OCM as a real control panel
+- support the README first-run / health story
+
+Wanted state:
+- Dashboard page open
+- gateway looks healthy if possible
+- cards readable
+- top bar clean
+- no obvious warning/noise unless it helps credibility
+
+Frame guidance:
+- browser window wide enough to show full dashboard naturally
+- keep top navigation visible
+- avoid cropping too tightly
+
+### 2) Agents page
+Purpose:
+- show the core product value: visible agent topology / structure
+
+Wanted state:
+- main agent + several sub-agents visible
+- structure easy to understand at a glance
+- avoid visual clutter where possible
+- keep model selectors/buttons visible, but not the focus
+
+Frame guidance:
+- enough width to show the tree clearly
+- IDs and personal paths redacted
+
+### 3) CLI / Terminal page
+Purpose:
+- show that OCM is not only a viewer; it can operate OpenClaw too
+
+Wanted state:
+- built-in terminal open
+- a real command visible (recommended: `openclaw status` or `openclaw doctor`)
+- real output visible
+- do not use tutorial arrows / annotation bubbles
+
+Frame guidance:
+- include command input and some output
+- avoid empty terminal state
+- redact paths / personal names
+
+## Priority 2 screenshots
+- Actions menu
+- Backup / rollback
+- Channels
+- Models
+- Auth
+- Cron
+- Stats
+
+## Selected refresh set (2026-03-07)
+- Dashboard: `docs/redacted-screenshots-refresh/dashboard-2026-03-07.jpg`
+- Agents: `docs/redacted-screenshots-refresh/agents-2026-03-07.jpg`
+- CLI: `docs/redacted-screenshots-refresh/cli-2026-03-07.jpg`
+- Keep using existing `docs/redacted-screenshots/actions.jpg` for now
+
+## Notes
+- Existing `actions.jpg` is already strong and can stay for now.
+- The new Dashboard and Agents captures are preferred for README hero/overview use.
+- The new CLI capture is preferred because it shows a real command and real output.

docs/SECURITY.md

@@ -0,0 +1,52 @@
+# Security Notes
+
+OCM is a **local web UI** for managing OpenClaw. Security depends heavily on how you run OpenClaw and how you use Telegram.
+
+## Recommended defaults
+
+- **Run locally** and restrict host binding unless you intentionally expose it.
+- Treat OpenClaw config as secrets: tokens, provider keys, account ids.
+- Prefer separate workspaces for each agent/sub-agent.
+
+## Telegram safety
+
+Strongly recommended:
+
+- **One Telegram group = one agent boundary** (context + purpose + workspace)
+- Keep each agent group **private**: only you + the bot (and optionally your second account)
+- Do **not** invite other people (cost + security risk)
+
+Critical BotFather settings:
+- Allow Groups = ON
+- Group Privacy = OFF
+
+## Sharing screenshots
+
+If you share screenshots publicly:
+- blur personal paths (e.g. `/Users/<name>/...`)
+- blur Telegram group/peer IDs (e.g. `-100xxxxxxxxxx`)
+- blur any tokens/keys if visible
+
+This repo contains **redacted + annotated** screenshots under `docs/annotated-screenshots/`.
+
+
+## Discord safety
+
+Recommended defaults (especially for shared/community servers):
+
+- Prefer **private channels / private threads** as agent boundaries
+- Use a strict **allowlist** of channels/threads the bot may respond in
+- Avoid giving memory-enabled or high-privilege agents broad public exposure
+- Prefer least-privilege Discord permissions for the bot
+
+## Feishu / Lark safety
+
+Feishu is more enterprise-oriented and usually needs stricter permission design:
+
+- Request the smallest permission scope possible
+- Treat chat/group visibility as a security boundary
+- Prefer separate chats/spaces for different agents to reduce context bleed
+
+## WhatsApp note
+
+WhatsApp is not a recommended target for sub-agent topology workflows. Constraints in bot/group automation make reliable multi-agent isolation and routing harder.

docs/USAGE_GUIDE.en.md

@@ -0,0 +1,332 @@
+# OCM Usage Guide (with screenshots)
+
+> Audience: People who already have OpenClaw running locally (you can run `openclaw status` and read `openclaw gateway logs`).
+>
+> Goal: Use **OpenClaw Manager (OCM)** as an **OpenClaw control panel** for agent setup, routing, health checks, built-in CLI, and safer config changes.
+
+---
+
+## 0) The pain: why OCM exists
+
+Creating and maintaining OpenClaw agents is powerful, but the “default workflow” is often messy:
+
+1) **Editing `openclaw.json` is risky**
+- Deep/nested config, many fields.
+- One accidental overwrite can break multiple agents (tokens, bindings, accountIds).
+
+2) **Sub-agent topology is hard to see**
+- With multiple bots + multiple groups, it’s not obvious which agent is bound to which Telegram peer.
+
+3) **Model IDs are easy to misconfigure**
+- A wrong `provider/model-id` can silently degrade performance, cause timeouts, or produce “typing…” with no reply.
+
+4) **Usage and troubleshooting take time**
+- Without tooling, you’re digging through JSONL sessions and gateway logs to answer: “who used tokens?”, “what failed?”, “which provider?”
+
+OCM’s role: **a zero-dependency local UI** that helps you view and update OpenClaw configuration safely, keep changes auditable, and centralize common ops.
+
+---
+
+## 1) Why Telegram groups are the best way to build sub-agents
+
+Think of it as:
+
+> **One Telegram group = one agent boundary** (context + purpose + workspace).
+
+### Benefits
+
+1) **Clear isolation**
+- Each agent speaks only inside its own group.
+- Less cross-contamination between tasks.
+
+2) **Controllable context**
+- The group chat is the agent’s input stream.
+- You can keep an agent “clean” by keeping the group focused.
+
+3) **Natural delegation**
+- A main agent can coordinate; sub-agents can specialize (tech / travel / finance / translation, etc.).
+
+4) **Auditable**
+- You can see exactly which message triggered which response.
+
+### Safety / cost: keep groups private
+
+Recommended rule:
+
+- **Each agent group should contain only you + the bot** (and optionally your second account).
+- Don’t invite other people:
+  - cost: anyone can trigger token usage
+  - safety: higher risk of prompt-injection / accidental tool actions
+
+---
+
+## 2) First-run mindset
+
+For new users, the first win is not “configure everything” — it is:
+
+1. Confirm OCM found the right OpenClaw directory
+2. Confirm the gateway is healthy
+3. Confirm you can inspect agents / bindings
+4. Confirm the built-in CLI works
+
+That is why Dashboard + Routing + built-in CLI are the most important first-run surfaces.
+
+## 3) Start OCM (macOS)
+
+From the repo directory:
+
+```bash
+bash start.sh
+```
+
+Then open: <http://localhost:3333>
+
+Restrict to localhost only:
+
+```bash
+bash start.sh --host 127.0.0.1
+```
+
+---
+
+## 4) Dashboard: check health first
+
+The Dashboard is your “sanity check”:
+
+- CPU / RAM / Disk
+- gateway running status
+- agent counts
+
+Screenshot:
+
+![](redacted-screenshots/dashboard.jpg)
+
+---
+
+## 5) Create a main agent (with its own Telegram bot)
+
+> Your `main` agent usually exists already. This section is for creating an additional **root agent** that owns its own Telegram bot/account.
+
+### 5.1 BotFather prerequisites
+
+1) Create a bot
+- In Telegram, open **BotFather**
+- Run `/newbot` → follow prompts → copy the bot token
+
+2) Allow groups
+- BotFather → your bot → Bot Settings
+- **Allow Groups = ON**
+
+3) Disable group privacy (critical)
+- BotFather → your bot → Bot Settings → Group Privacy
+- **Group Privacy = OFF**
+
+If group privacy is ON, the bot can’t see normal group messages. The symptom often looks like:
+- slow replies
+- “typing…” appears frequently
+- sometimes no response at all
+
+### 5.2 Add the agent in OCM
+
+Go to **Agents**:
+
+![](redacted-screenshots/agents.jpg)
+
+Click `+ Add Agent` and fill:
+
+- agent id / name
+- workspace path (recommended: separate folder per agent)
+- model (dropdown is sourced from `openclaw models list`)
+- the BotFather token
+
+OCM writes the agent + Telegram account/binding into `openclaw.json`.
+
+---
+
+## 6) Create a sub-agent (recommended workflow)
+
+### 6.1 Why a new group per sub-agent
+
+- clean context isolation
+- easier debugging
+- easy to “turn off” by muting a group
+
+### 6.2 Step-by-step
+
+In **Agents** → `+ Add Sub-Agent`:
+
+**Step 1 — Create a Telegram group**
+- private group
+- add only: you + the bot
+
+**Step 2 — Get the Group ID (peer id)**
+
+Use gateway logs:
+
+```bash
+openclaw gateway logs --follow
+```
+
+Send a message in the new group. In logs you should see something like:
+
+- `-100xxxxxxxxxx` (Telegram group id)
+
+**Step 3 — Fill the sub-agent form**
+- choose the Parent Agent (which bot/account to share)
+- paste the Group ID
+- set workspace (recommended: its own folder)
+- choose model
+
+**Step 4 — Allowlist (optional but recommended)**
+
+If you use `channels.telegram.allowFrom`, OCM can take “Your Telegram User ID” and append it automatically to the allowlist.
+
+---
+
+
+
+## 6.5) Discord workflow (main agent + sub-agent)
+
+OCM also supports Discord:
+
+- **Main agent**: bind to a dedicated **Channel** (channelId)
+- **Sub-agent**: bind to a dedicated **Thread** under that channel (threadId)
+
+### 6.5.1 Add a Discord main agent
+
+Go to **Agents** → `+ Add Agent` → set **Channel = Discord**:
+
+![](redacted-screenshots/agents-discord-add-agent.png)
+
+Steps:
+1) Create/select a dedicated Discord **channel** (private recommended)
+2) Right-click channel → **Copy Link** → paste into the form (auto-parses channelId)
+
+### 6.5.2 Add a Discord sub-agent (thread-first)
+
+Go to **Agents** → `+ Add Sub-Agent` → set **Channel = Discord (thread only)**:
+
+![](redacted-screenshots/agents-discord-add-subagent.png)
+
+Steps:
+1) Create a **thread** under the main channel (one thread per task)
+2) If it is a private thread, add the bot to the thread
+3) Right-click thread → **Copy Link** → paste into the form (auto-parses threadId)
+
+## 7) Verify bindings (Channels)
+
+Go to **Channels**:
+
+![](redacted-screenshots/channels.jpg)
+
+Here you can quickly validate:
+- which agent is bound to which Telegram peer
+- whether `main` has the catch-all binding (if you use that pattern)
+
+---
+
+## 8) Model settings (Models)
+
+Go to **Models**:
+
+![](redacted-screenshots/models.jpg)
+
+Key idea:
+- OCM uses the real CLI model list (`openclaw models list`) for dropdowns.
+- This reduces “invalid model-id” mistakes.
+
+---
+
+## 8) Credentials (Auth)
+
+Go to **Auth**:
+
+![](redacted-screenshots/auth.jpg)
+
+Use this page to:
+- see which provider profiles exist
+- troubleshoot expired/missing tokens
+
+---
+
+## 9) Usage stats (Stats)
+
+Go to **Stats**:
+
+![](redacted-screenshots/stats.jpg)
+
+You can break down usage by:
+- model
+- agent
+- time window
+
+OCM parses usage from OpenClaw session JSONL files.
+
+---
+
+## 10) Actions menu (ops shortcuts)
+
+The **⚡ Actions** dropdown in the top-right provides common operational shortcuts:
+- Restart Gateway
+- Live Logs
+- Manual Backup / Backups & Rollback
+- NAS Backup Setup
+- Health Check
+- Open Config Dir / Switch OpenClaw Dir
+
+Screenshot:
+
+![](redacted-screenshots/actions.jpg)
+
+## 10) Cron jobs (Cron)
+
+Go to **Cron**:
+
+![](redacted-screenshots/cron.jpg)
+
+You can:
+- see scheduled tasks (backup / update / health)
+- run tasks manually
+- enable/disable entries
+
+---
+
+## 11) Built-in CLI Terminal
+
+OCM includes a built-in terminal panel to run OpenClaw CLI commands directly (for example: `openclaw status`, `openclaw gateway logs --follow`, `openclaw doctor`).
+
+How to open: click **⌨️ Terminal** in the top navigation, or use the bottom CLI panel.
+
+Highlights:
+- **Tab completion** while typing commands
+- **Common commands** dropdown to insert templates quickly
+- **Favorites**: save frequently used commands and run them with one click
+- **Streaming output** (stdout/stderr) for faster debugging
+
+Screenshot:
+
+![](redacted-screenshots/cli.jpg)
+
+![](redacted-screenshots/cli-output.jpg)
+
+## 11) Fast troubleshooting
+
+### “Typing…” but no reply in a Telegram group
+
+Check (in order):
+
+1) BotFather: **Group Privacy = OFF**
+2) `openclaw status` (gateway healthy?)
+3) provider auth / rate limit issues (Auth page + gateway logs)
+
+### Model dropdown doesn’t show a model you expect
+
+- dropdown comes from `openclaw models list`
+- ensure the model is registered/visible in your OpenClaw environment
+
+---
+
+## Notes about screenshots
+
+All screenshots in this guide are **redacted** (no personal paths, no Telegram IDs).
+They live under `docs/redacted-screenshots/`.

docs/USAGE_GUIDE.zh-CN.md

@@ -0,0 +1,324 @@
+# OCM 功能使用说明（含截图）
+
+> 面向：已经在本机安装并跑通 OpenClaw 的用户（至少会用 `openclaw status` / `openclaw gateway logs`）
+>
+> 目标：把 **OpenClaw Manager (OCM)** 当成 **OpenClaw 控制台** 来用：管理 Agent、查看 Routing、做健康检查、运行内置 CLI，并更安全地修改配置。
+
+---
+
+## 0) 先说痛点：为什么要用 OCM
+
+### 0.1 创建/维护 Agent 的典型痛点
+
+1. **改 `openclaw.json` 容易改错**
+   - 字段多、层级深、容易手滑覆盖 token / accountId / bindings。
+   - 一次写错可能导致多个 Agent 全挂。
+
+2. **Sub-Agent 的边界和“谁在用哪个 bot token”不直观**
+   - 多 Bot / 多 agent / 多群组绑定时，光靠肉眼看 JSON 很难确认拓扑结构是否正确。
+
+3. **模型选择很容易“写了一个不存在的 model-id”**
+   - provider/model-id 拼错、或 provider 侧不支持，最后表现就是 Agent 变慢/报错/一直 typing。
+
+4. **统计用量和排查问题耗时**
+   - 需要翻 session JSONL / gateway logs 才能知道谁在烧 token、哪里失败。
+
+OCM 的定位：**把配置变更“可视化 + 可检查 + 可回滚（配合备份）”，并把常用运维入口集中起来。**
+
+---
+
+## 1) 为什么用 Telegram group 来建 Sub-Agent 最合适
+
+> 这里讨论的是 OpenClaw 的一种非常实用的工作方式：**“一个 Telegram 群 = 一个 Agent 的工作空间/人格/上下文边界”**。
+
+### 1.1 Telegram group 方案的优势
+
+1. **边界天然清晰**
+   - 每个 Agent 只在自己的群里说话，和其他 Agent 隔离。
+
+2. **上下文可控**
+   - 一个群的聊天记录就是该 Agent 的输入流；不会和别的任务混在一起。
+
+3. **并发与分工自然**
+   - 主 Agent 负责总控/派工，Sub-Agent 负责专项：技术宅/旅行/理财/翻译……
+
+4. **可审计**
+   - 群里发生了什么一眼可见；出问题也能定位是哪条消息触发。
+
+### 1.2 为什么“群必须私密”（安全与成本）
+
+- 强烈建议：**每个 Agent 群只留你自己 + 对应 bot（+ 必要时的另一个你自己的账号）**。
+- 不要拉别人进来：
+  - 成本：别人一句话就触发 token 消耗
+  - 安全：可能诱导泄露信息/触发危险操作
+
+---
+
+## 2) 第一次使用时最该确认什么
+
+对新用户来说，第一步不是“先把所有配置都改完”，而是先确认四件事：
+
+1. OCM 找到的是正确的 OpenClaw 目录
+2. Gateway 是健康的
+3. Agent / Routing 能正常查看
+4. 内置终端可以正常跑命令
+
+所以第一次使用时，最重要的页面其实是 Dashboard、Routing 和内置终端。
+
+## 3) 启动与进入 OCM
+
+### 3.1 启动（macOS）
+
+在 OCM 目录：
+
+```bash
+bash start.sh
+```
+
+默认访问：<http://localhost:3333>
+
+> 需要限制只能本机访问：`bash start.sh --host 127.0.0.1`
+
+### 3.2 Dashboard（先看健康状态）
+
+建议第一步先看 Dashboard，确认：
+- 机器资源（CPU/RAM/DISK）
+- OpenClaw gateway 是否 Running
+- Agents 数量
+
+截图示例：
+
+![](redacted-screenshots/dashboard.jpg)
+
+---
+
+## 4) 创建主 Agent（Main Agent / 独立 Bot）
+
+> 你的 `main` 一般是默认存在的；这里重点讲“新增一个 **拥有独立 Telegram bot 的主 Agent**”。
+
+### 4.1 BotFather 侧准备（必须）
+
+1) 创建 bot
+- 在 Telegram 找 **BotFather**
+- 发送 `/newbot` → 按提示创建 → 拿到 bot token
+
+2) 允许加群
+- BotFather → 你的 bot → Bot Settings
+- **Allow Groups = ON**
+
+3) 关闭群隐私（非常关键）
+- BotFather → 你的 bot → Bot Settings → Group Privacy
+- **Group Privacy = OFF**
+
+> 如果 Group Privacy 没关，bot 在群里看不到普通消息，会表现成“经常 typing 但没输出 / 没反应”。
+
+### 4.2 在 OCM 添加主 Agent
+
+进入 **Agents** 页面：
+
+![](redacted-screenshots/agents.jpg)
+
+点击 `+ Add Agent`，按表单填写：
+- Agent id / name
+- workspace 路径（建议独立目录）
+- 选择模型（下拉来自 `openclaw models list`，更不容易选错）
+- 填入刚拿到的 bot token
+
+保存后，OCM 会把这颗主 Agent 写进 `openclaw.json`，并把 bot token 绑定到对应 `accountId`。
+
+---
+
+## 5) 创建 Sub-Agent（最常用）
+
+### 5.1 为什么 Sub-Agent 要用“新群”
+
+- 让每个 Sub-Agent 有自己独立的对话上下文、任务边界
+- 出问题直接在该群排查，不污染主 Agent 的对话
+
+### 5.2 Sub-Agent 创建流程（逐步）
+
+进入 **Agents** 页面 → 点击 `+ Add Sub-Agent`，按引导做：
+
+#### Step 1：建 Telegram 群
+- 新建群（私密）
+- 群里只加：你自己 + 对应的 bot
+
+#### Step 2：拿到群 ID（Peer ID / Group ID）
+OpenClaw 通常会在 gateway 日志里打印群的 peer id。
+
+常见拿法：
+```bash
+openclaw gateway logs --follow
+```
+然后在 Telegram 群里随便发一句话，观察日志。
+
+> 你会看到类似 `-100xxxxxxxxxx` 这样的 group id。
+
+#### Step 3：回到 OCM 填表
+- Parent Agent（选择共享哪个 bot/account）
+- 填 Group ID
+- workspace（建议单独目录）
+- 选择模型
+
+#### Step 4：写 allowlist（推荐）
+如果你启用了 Telegram 的 allowlist（例如 `channels.telegram.allowFrom`），
+OCM 的表单里可以填 “Your Telegram User ID”，让它自动把你的 user id 加进去，避免 DM/群消息被拒。
+
+---
+
+
+
+## 6) Discord 工作流（主 Agent + Sub-Agent）
+
+OCM 也支持 Discord：
+
+- **主 Agent**：绑定到一个专用 **Channel**（channelId）
+- **Sub-Agent**：绑定到该 Channel 下的专用 **Thread**（threadId，thread-first）
+
+### 5.1 添加 Discord 主 Agent
+
+进入 **Agents** → `+ Add Agent` → 选择 **渠道 = Discord**：
+
+![](redacted-screenshots/agents-discord-add-agent.png)
+
+步骤：
+1) 创建/选择一个专用 Discord Channel（建议私密）
+2) 右键 Channel → **Copy Link** → 粘贴到表单（自动解析 channelId）
+
+### 5.2 添加 Discord Sub-Agent（Thread 优先）
+
+进入 **Agents** → `+ Add Sub-Agent` → 选择 **渠道 = Discord (thread only)**：
+
+![](redacted-screenshots/agents-discord-add-subagent.png)
+
+步骤：
+1) 在主 Channel 下新建 Thread（建议“一个任务一个 thread”）
+2) 如果是 private thread，需要把 bot 拉进 thread
+3) 右键 Thread → **Copy Link** → 粘贴到表单（自动解析 threadId）
+
+## 7) 绑定检查（Channels 页）
+
+进入 **Channels**：
+
+![](redacted-screenshots/channels.jpg)
+
+这里能一眼看到：
+- 哪个 agent 绑定了哪个 Telegram peer（群）
+- main 的“兜底绑定”（any）是否存在
+
+> 如果某个 Sub-Agent 绑定错群/丢 binding，最直观的就是在这里对不上。
+
+---
+
+## 8) 模型管理（Models 页）
+
+进入 **模型**：
+
+![](redacted-screenshots/models.jpg)
+
+关键点：
+- 主模型（primary）和 fallback 链
+- 下拉列表来自 `openclaw models list`（能减少“选了不存在模型”的问题）
+
+---
+
+## 9) 认证管理（Auth 页）
+
+进入 **认证**：
+
+![](redacted-screenshots/auth.jpg)
+
+这里主要用来：
+- 看当前有哪些 provider profile
+- 排查某个 provider 是否过期/缺 token
+
+---
+
+## 8) 用量统计（Stats 页）
+
+进入 **Stats**：
+
+![](redacted-screenshots/stats.jpg)
+
+你可以按：
+- 按模型聚合
+- 按 Agent 聚合
+- 按天趋势
+
+> OCM 是从 OpenClaw 的 session JSONL 里解析真实 usage（比“看日志猜”靠谱）。
+
+---
+
+## 9) CLI 终端（内置）
+
+OCM 内置一个 CLI 面板，用来直接运行 OpenClaw 命令（例如：`openclaw status`、`openclaw gateway logs --follow`、`openclaw doctor`）。
+
+入口：点击顶部导航栏的 **⌨️ 终端**，或使用页面底部的 CLI 区域。
+
+功能要点：
+- **Tab 补全**：输入命令时按 Tab 进行补全/提示（适合 `openclaw ...` 子命令）
+- **常用命令**：可从下拉选择，一键填充常用命令模板
+- **收藏（Favorites）**：把常用命令保存为收藏，后续一键执行
+- **实时输出**：执行后会流式显示 stdout/stderr，方便排错
+
+截图示例：
+
+![](redacted-screenshots/cli.jpg)
+
+![](redacted-screenshots/cli-output.jpg)
+
+## 9) Actions 菜单（运维快捷入口）
+
+右上角 **⚡ Actions** 下拉菜单提供常用运维操作：
+- Restart Gateway（重启网关）
+- Live Logs（实时日志）
+- Manual Backup / Backups & Rollback（备份/回滚）
+- NAS Backup Setup（NAS 备份配置）
+- Health Check（健康检查）
+- Open Config Dir / Switch OpenClaw Dir（打开/切换配置目录）
+
+截图示例：
+
+![](redacted-screenshots/actions.jpg)
+
+## 9) Cron（定时任务）
+
+进入 **Cron**：
+
+![](redacted-screenshots/cron.jpg)
+
+用途：
+- 查看有哪些健康检查/更新/备份任务
+- 手动运行
+- 观察启用/禁用状态
+
+---
+
+## 10) 常见故障排查（快速）
+
+### 10.1 Telegram 群里“一直 typing 但不回”
+
+优先检查：
+1) BotFather 的 **Group Privacy 是否 OFF**
+2) OpenClaw gateway 是否健康（`openclaw status`）
+3) provider 是否限流/超时（Auth 页 + gateway logs）
+
+### 10.2 模型下拉没有你想要的模型
+
+- 现在下拉是 `openclaw models list` 的真实输出。
+- 先确保你在 OpenClaw 里已经注册/可见该模型。
+
+---
+
+## 11) 推荐的“最佳实践”
+
+- 每个 Agent 都用独立 workspace（隔离文件/记忆）
+- 每个 Sub-Agent 都用独立 Telegram 群（隔离上下文）
+- 群里不要加第三方（成本 + 安全）
+- 任何“改配置的大动作”尽量先备份（OCM/脚本/手工都行）
+
+---
+
+## 附：截图说明
+
+本文截图来自 `docs/redacted-screenshots/`，已做脱敏（路径用户名、Telegram 绑定 ID 等均已模糊处理）。

package.json

@@ -1,7 +1,7 @@
 {
   "name": "openclaw-manager",
-  "version": "0.5.0",
-  "description": "A local web UI for managing OpenClaw AI agents — no npm install required",
+  "version": "0.9.1",
+  "description": "A local web UI for managing OpenClaw AI agents \u2014 no npm install required",
   "main": "openclaw-manager.js",
   "scripts": {
     "start": "node openclaw-manager.js",

start.bat

@@ -1,13 +1,13 @@
 @echo off
 :: ================================================================
-:: OpenClaw Manager v0.5 — Windows 启动脚本
+:: OpenClaw Manager v0.7.1 — Start Script (Windows)
 ::
-:: 特性：
-::   * 自动检测 Node.js，未安装时给出安装指引（winget/scoop/官网）
-::   * 自动检测 %USERPROFILE%\.openclaw 目录
-::   * 首次运行自动创建 manager-config.json
-::   * 自动检测端口占用并建议替代端口
-::   * 支持 --dir / --port / --help 参数
+:: Features:
+::   * Auto-detect Node.js, show install instructions if missing
+::   * Auto-detect %USERPROFILE%\.openclaw directory
+::   * Auto-create manager-config.json on first run
+::   * Auto-kill previous OCM process if port is in use
+::   * Supports --dir / --port / --host / --help
 :: ================================================================
 setlocal enabledelayedexpansion
 chcp 65001 >nul 2>&1
@@ -19,48 +19,47 @@ set "MIN_NODE_MAJOR=18"
 
 echo.
 echo   ===================================
-echo      OpenClaw Manager  v0.5
+echo      OpenClaw Manager  v0.7.1
 echo   -----------------------------------
 echo.
 
-:: ── 检查主文件 ────────────────────────────────────────────────
+:: ── Check main file ─────────────────────────────────────────
 if not exist "%MANAGER_JS%" (
-    echo   [X] 找不到 openclaw-manager.js
-    echo       期望路径: %MANAGER_JS%
+    echo   [X] Cannot find openclaw-manager.js
+    echo       Expected: %MANAGER_JS%
     echo.
     pause
     exit /b 1
 )
 
-:: ── 检查 Node.js ─────────────────────────────────────────────
+:: ── Check Node.js ───────────────────────────────────────────
 where node >nul 2>&1
 if errorlevel 1 (
-    echo   [X] 未找到 Node.js
+    echo   [X] Node.js not found
     echo.
-    echo   安装方式（选一种即可）：
+    echo   Install Node.js (pick one):
     echo.
     echo   1^) winget:   winget install OpenJS.NodeJS.LTS
     echo   2^) scoop:    scoop install nodejs-lts
-    echo   3^) 官网下载: https://nodejs.org/
+    echo   3^) Official: https://nodejs.org/
     echo   4^) nvm-windows: https://github.com/coreybutler/nvm-windows
     echo.
     pause
     exit /b 1
 )
 
-:: 获取主版本号并检查
 for /f "tokens=1 delims=." %%v in ('node -e "process.stdout.write(process.versions.node)"') do (
     set "NODE_MAJOR=%%v"
 )
 
 if !NODE_MAJOR! LSS %MIN_NODE_MAJOR% (
-    echo   [!] Node.js 版本过低（需要 ^>= v%MIN_NODE_MAJOR%）
+    echo   [!] Node.js too old (need ^>= v%MIN_NODE_MAJOR%)
     echo.
-    echo   安装方式（选一种即可）：
+    echo   Install Node.js (pick one):
     echo.
     echo   1^) winget:   winget install OpenJS.NodeJS.LTS
     echo   2^) scoop:    scoop install nodejs-lts
-    echo   3^) 官网下载: https://nodejs.org/
+    echo   3^) Official: https://nodejs.org/
     echo.
     pause
     exit /b 1
@@ -70,9 +69,10 @@ for /f "tokens=*" %%v in ('node -e "process.stdout.write('v'+process.versions.no
     echo   [OK] Node.js %%v
 )
 
-:: ── 解析参数 ─────────────────────────────────────────────────
+:: ── Parse arguments ─────────────────────────────────────────
 set "DIR_ARG="
 set "PORT_ARG="
+set "HOST_ARG="
 set "EXTRA_ARGS="
 
 :parse_args
@@ -89,23 +89,29 @@ if /i "%~1"=="--port" (
     shift & shift
     goto :parse_args
 )
+if /i "%~1"=="--host" (
+    set "HOST_ARG=%~2"
+    shift & shift
+    goto :parse_args
+)
 set "EXTRA_ARGS=!EXTRA_ARGS! %~1"
 shift
 goto :parse_args
 
 :show_help
-echo 用法: start.bat [选项]
+echo Usage: start.bat [options]
 echo.
-echo 选项:
-echo   --dir  ^<路径^>   OpenClaw 配置目录（默认 %%USERPROFILE%%\.openclaw）
-echo   --port ^<端口^>   监听端口（默认 3333）
-echo   --help          显示帮助
+echo Options:
+echo   --dir  ^<path^>   OpenClaw config directory (default: %%USERPROFILE%%\.openclaw)
+echo   --port ^<port^>   Listen port (default: 3333)
+echo   --host ^<addr^>   Bind address (default: 0.0.0.0)
+echo   --help          Show this help
 echo.
 exit /b 0
 
 :after_args
 
-:: ── 检测 OpenClaw 配置目录 ───────────────────────────────────
+:: ── Detect OpenClaw config directory ────────────────────────
 set "OPENCLAW_DIR="
 if defined DIR_ARG (
     set "OPENCLAW_DIR=!DIR_ARG!"
@@ -117,54 +123,48 @@ if defined DIR_ARG (
 if not defined OPENCLAW_DIR set "OPENCLAW_DIR=%USERPROFILE%\.openclaw"
 
 if exist "!OPENCLAW_DIR!" (
-    echo   [OK] 配置目录: !OPENCLAW_DIR!
+    echo   [OK] Config dir: !OPENCLAW_DIR!
 ) else (
-    echo   [!] 配置目录不存在: !OPENCLAW_DIR!
-    echo       首次使用？请先运行 openclaw onboard 初始化。
+    echo   [!] Config dir not found: !OPENCLAW_DIR!
+    echo       First time? Run: openclaw onboard
 )
 
-:: ── 首次运行：自动创建 manager-config.json ────────────────────
+:: ── First run: auto-create manager-config.json ──────────────
 if not exist "%CONFIG_JSON%" (
-    echo   [-^>] 首次运行，创建 manager-config.json
+    echo   [-^>] First run, creating manager-config.json
     node -e "require('fs').writeFileSync('%CONFIG_JSON%',JSON.stringify({dir:'~/.openclaw'},null,2))"
 )
 
-:: ── 检查端口可用性 ───────────────────────────────────────────
+:: ── Port handling: kill old process if occupied ─────────────
 set "PORT=3333"
 if defined PORT_ARG set "PORT=!PORT_ARG!"
 
-netstat -an 2>nul | findstr /r ":%PORT% .*LISTENING" >nul 2>&1
-if not errorlevel 1 (
-    echo   [!] 端口 !PORT! 已被占用
-    for %%p in (3334 3335 3336 8080 8888) do (
-        netstat -an 2>nul | findstr /r ":%%p .*LISTENING" >nul 2>&1
-        if errorlevel 1 (
-            echo       尝试备用端口 %%p...
-            set "PORT=%%p"
-            set "PORT_ARG=%%p"
-            goto :port_ok
+:: Find PID using the port and kill it
+for /f "tokens=5" %%p in ('netstat -ano 2^>nul ^| findstr /r ":!PORT! .*LISTENING"') do (
+    echo   [!] Port !PORT! in use (PID %%p), stopping old process...
+    taskkill /PID %%p /F >nul 2>&1
+    timeout /t 1 /nobreak >nul 2>&1
+    echo   [OK] Old process stopped
 )
-    )
-)
-:port_ok
 
-:: ── 构建启动命令 ─────────────────────────────────────────────
+:: ── Build launch command ────────────────────────────────────
 set "CMD_ARGS="
 if defined DIR_ARG  set "CMD_ARGS=!CMD_ARGS! --dir "!DIR_ARG!""
 if defined PORT_ARG set "CMD_ARGS=!CMD_ARGS! --port !PORT_ARG!"
+if defined HOST_ARG set "CMD_ARGS=!CMD_ARGS! --host !HOST_ARG!"
 if defined EXTRA_ARGS set "CMD_ARGS=!CMD_ARGS! !EXTRA_ARGS!"
 
 echo.
-echo   [^>] 启动中 -^> http://localhost:!PORT!
-echo       Ctrl+C 停止
+echo   [^>] Starting -^> http://localhost:!PORT!
+echo       Ctrl+C to stop
 echo.
 
-:: ── 启动 ─────────────────────────────────────────────────────
+:: ── Launch ──────────────────────────────────────────────────
 node "%MANAGER_JS%"!CMD_ARGS!
 
 if errorlevel 1 (
     echo.
-    echo   [X] 启动失败，请检查上方错误信息。
+    echo   [X] Failed to start. Check errors above.
     pause
 )
 endlocal

start.sh

@@ -1,13 +1,13 @@
 #!/usr/bin/env bash
 # ================================================================
-# OpenClaw Manager v0.5 — 跨平台启动脚本 (macOS / Linux)
+# OpenClaw Manager v0.7.1 — Start Script (macOS / Linux)
 #
-# 特性：
-#   • 自动检测 Node.js，未安装时给出安装指引
-#   • 自动检测 ~/.openclaw 目录，不存在时提示
-#   • 首次运行自动创建 manager-config.json
-#   • 自动检测端口占用并建议替代端口
-#   • 支持 --dir / --port / --help 参数
+# Features:
+#   - Auto-detect Node.js, show install instructions if missing
+#   - Auto-detect ~/.openclaw directory
+#   - Auto-create manager-config.json on first run
+#   - Auto-kill previous OCM process if port is in use
+#   - Supports --dir / --port / --host / --help
 # ================================================================
 set -e
 
@@ -16,62 +16,63 @@ MANAGER_JS="$SCRIPT_DIR/openclaw-manager.js"
 CONFIG_JSON="$SCRIPT_DIR/manager-config.json"
 MIN_NODE_MAJOR=18
 
-# ── 颜色 ─────────────────────────────────────────────────────
+# ── Colors ────────────────────────────────────────────────────
 RED='\033[0;31m'; YELLOW='\033[1;33m'; GREEN='\033[0;32m'
 CYAN='\033[0;36m'; BOLD='\033[1m'; DIM='\033[2m'; RESET='\033[0m'
 
 banner() {
   echo ""
-  echo -e "${CYAN}${BOLD}  🦀 OpenClaw Manager v0.5${RESET}"
+  echo -e "${CYAN}${BOLD}  🦀 OpenClaw Manager v0.7.1${RESET}"
   echo -e "${DIM}  ─────────────────────────────${RESET}"
   echo ""
 }
 
 banner
 
-# ── 检查主文件 ────────────────────────────────────────────────
+# ── Check main file ──────────────────────────────────────────
 if [ ! -f "$MANAGER_JS" ]; then
-  echo -e "${RED}✗ 找不到 openclaw-manager.js${RESET}"
-  echo -e "  期望路径: ${DIM}$MANAGER_JS${RESET}"
+  echo -e "${RED}✗ Cannot find openclaw-manager.js${RESET}"
+  echo -e "  Expected: ${DIM}$MANAGER_JS${RESET}"
   exit 1
 fi
 
-# ── 检查 Node.js ─────────────────────────────────────────────
+# ── Check Node.js ────────────────────────────────────────────
 install_node_hint() {
   echo ""
-  echo -e "  ${BOLD}安装方式（选一种即可）：${RESET}"
+  echo -e "  ${BOLD}Install Node.js (pick one):${RESET}"
   echo ""
   if [[ "$(uname)" == "Darwin" ]]; then
     echo -e "  ${GREEN}1)${RESET} Homebrew:  ${CYAN}brew install node${RESET}"
-    echo -e "  ${GREEN}2)${RESET} 官网下载:  ${CYAN}https://nodejs.org/${RESET}"
+    echo -e "  ${GREEN}2)${RESET} Official:  ${CYAN}https://nodejs.org/${RESET}"
     echo -e "  ${GREEN}3)${RESET} nvm:       ${CYAN}curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash${RESET}"
-    echo -e "                  ${DIM}然后 nvm install --lts${RESET}"
+    echo -e "                  ${DIM}then: nvm install --lts${RESET}"
   else
     echo -e "  ${GREEN}1)${RESET} apt:       ${CYAN}sudo apt install -y nodejs npm${RESET}"
-    echo -e "  ${GREEN}2)${RESET} 官网下载:  ${CYAN}https://nodejs.org/${RESET}"
+    echo -e "  ${GREEN}2)${RESET} Official:  ${CYAN}https://nodejs.org/${RESET}"
     echo -e "  ${GREEN}3)${RESET} nvm:       ${CYAN}curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash${RESET}"
-    echo -e "                  ${DIM}然后 nvm install --lts${RESET}"
+    echo -e "                  ${DIM}then: nvm install --lts${RESET}"
   fi
   echo ""
 }
 
 if ! command -v node &>/dev/null; then
-  echo -e "${RED}✗ 未找到 Node.js${RESET}"
+  echo -e "${RED}✗ Node.js not found${RESET}"
   install_node_hint
   exit 1
 fi
 
 NODE_VER=$(node -e "process.stdout.write(String(process.versions.node.split('.')[0]))")
 if [ "$NODE_VER" -lt "$MIN_NODE_MAJOR" ]; then
-  echo -e "${YELLOW}⚠ Node.js 版本过低（当前 v$(node -v)，需要 >= v${MIN_NODE_MAJOR}）${RESET}"
+  echo -e "${YELLOW}⚠ Node.js too old (current $(node -v), need >= v${MIN_NODE_MAJOR})${RESET}"
   install_node_hint
   exit 1
 fi
 echo -e "  ${GREEN}✓${RESET} Node.js $(node -v)"
 
-# ── 解析参数 ─────────────────────────────────────────────────
+# ── Parse arguments ──────────────────────────────────────────
 DIR_ARG=""
 PORT_ARG=""
+HOST_ARG=""
 EXTRA_ARGS=()
 
 while [[ $# -gt 0 ]]; do
@@ -80,20 +81,22 @@ while [[ $# -gt 0 ]]; do
     --dir=*) DIR_ARG="${1#*=}"; shift;;
     --port)  PORT_ARG="$2"; shift 2;;
     --port=*) PORT_ARG="${1#*=}"; shift;;
+    --host)  HOST_ARG="$2"; shift 2;;
+    --host=*) HOST_ARG="${1#*=}"; shift;;
     --help|-h)
-      echo "用法: $0 [选项]"
+      echo "Usage: $0 [options]"
       echo ""
-      echo "选项:"
-      echo "  --dir  <路径>   OpenClaw 配置目录（默认 ~/.openclaw）"
-      echo "  --port <端口>   监听端口（默认 3333）"
-      echo "  --help          显示帮助"
+      echo "Options:"
+      echo "  --dir  <path>   OpenClaw config directory (default: ~/.openclaw)"
+      echo "  --port <port>   Listen port (default: 3333)"
+      echo "  --host <addr>   Bind address (default: 0.0.0.0)"
+      echo "  --help          Show this help"
       exit 0;;
     *) EXTRA_ARGS+=("$1"); shift;;
   esac
 done
 
-# ── 检测 OpenClaw 配置目录 ───────────────────────────────────
-# 优先级: --dir 参数 > manager-config.json > 环境变量 > 默认
+# ── Detect OpenClaw config directory ─────────────────────────
 OPENCLAW_DIR=""
 if [ -n "$DIR_ARG" ]; then
   OPENCLAW_DIR="${DIR_ARG/#\~/$HOME}"
@@ -106,55 +109,53 @@ fi
 [ -z "$OPENCLAW_DIR" ] && OPENCLAW_DIR="$HOME/.openclaw"
 
 if [ -d "$OPENCLAW_DIR" ]; then
-  echo -e "  ${GREEN}✓${RESET} 配置目录: ${DIM}$OPENCLAW_DIR${RESET}"
+  echo -e "  ${GREEN}✓${RESET} Config dir: ${DIM}$OPENCLAW_DIR${RESET}"
 else
-  echo -e "  ${YELLOW}⚠${RESET} 配置目录不存在: ${DIM}$OPENCLAW_DIR${RESET}"
-  echo -e "    ${DIM}首次使用？请先运行 openclaw onboard 初始化。${RESET}"
+  echo -e "  ${YELLOW}⚠${RESET} Config dir not found: ${DIM}$OPENCLAW_DIR${RESET}"
+  echo -e "    ${DIM}First time? Run: openclaw onboard${RESET}"
 fi
 
-# ── 首次运行：自动创建 manager-config.json ────────────────────
+# ── First run: auto-create manager-config.json ───────────────
 if [ ! -f "$CONFIG_JSON" ]; then
-  echo -e "  ${CYAN}→${RESET} 首次运行，创建 ${DIM}manager-config.json${RESET}"
+  echo -e "  ${CYAN}→${RESET} First run, creating ${DIM}manager-config.json${RESET}"
   node -e "require('fs').writeFileSync('$CONFIG_JSON',JSON.stringify({dir:'~/.openclaw'},null,2))"
 fi
 
-# ── 检查端口可用性 ───────────────────────────────────────────
+# ── Port handling: kill old process if occupied ──────────────
 PORT="${PORT_ARG:-3333}"
 
-check_port() {
+get_port_pid() {
   if command -v lsof &>/dev/null; then
-    lsof -i :"$1" -sTCP:LISTEN >/dev/null 2>&1 && return 1
+    lsof -ti :"$1" -sTCP:LISTEN 2>/dev/null || true
   elif command -v ss &>/dev/null; then
-    ss -tlnp 2>/dev/null | grep -q ":$1 " && return 1
-  elif command -v netstat &>/dev/null; then
-    netstat -tlnp 2>/dev/null | grep -q ":$1 " && return 1
+    ss -tlnp 2>/dev/null | grep ":$1 " | grep -oP 'pid=\K[0-9]+' || true
   fi
-  return 0
 }
 
-if ! check_port "$PORT"; then
-  echo -e "  ${YELLOW}⚠${RESET} 端口 ${PORT} 已被占用"
-  # 尝试找一个可用端口
-  for ALT in 3334 3335 3336 8080 8888; do
-    if check_port "$ALT"; then
-      echo -e "    ${DIM}尝试备用端口 ${ALT}...${RESET}"
-      PORT="$ALT"
-      PORT_ARG="$ALT"
-      break
+PORT_PID=$(get_port_pid "$PORT")
+if [ -n "$PORT_PID" ]; then
+  echo -e "  ${YELLOW}⚠${RESET} Port ${PORT} in use (PID ${PORT_PID}), stopping old process..."
+  kill "$PORT_PID" 2>/dev/null || true
+  sleep 1
+  # Force kill if still alive
+  if kill -0 "$PORT_PID" 2>/dev/null; then
+    kill -9 "$PORT_PID" 2>/dev/null || true
+    sleep 0.5
   fi
-  done
+  echo -e "  ${GREEN}✓${RESET} Old process stopped"
 fi
 
-# ── 构建启动命令 ─────────────────────────────────────────────
+# ── Build launch command ─────────────────────────────────────
 CMD_ARGS=()
 [ -n "$DIR_ARG" ]  && CMD_ARGS+=(--dir "$DIR_ARG")
 [ -n "$PORT_ARG" ] && CMD_ARGS+=(--port "$PORT_ARG")
+[ -n "$HOST_ARG" ] && CMD_ARGS+=(--host "$HOST_ARG")
 CMD_ARGS+=("${EXTRA_ARGS[@]}")
 
 echo ""
-echo -e "  ${CYAN}▶${RESET} 启动中 → ${BOLD}http://localhost:${PORT}${RESET}"
-echo -e "  ${DIM}Ctrl+C 停止${RESET}"
+echo -e "  ${CYAN}▶${RESET} Starting → ${BOLD}http://localhost:${PORT}${RESET}"
+echo -e "  ${DIM}Ctrl+C to stop${RESET}"
 echo ""
 
-# ── 启动 ─────────────────────────────────────────────────────
+# ── Launch ───────────────────────────────────────────────────
 exec node "$MANAGER_JS" "${CMD_ARGS[@]}"