diff --git a/README.md b/README.md index f0acd5d..06395d4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # OpenClaw Manager (OCM) -A zero-dependency, single-file web dashboard for [OpenClaw](https://github.com/anthropics/openclaw). Manage agents, monitor token usage, and run commands — all from your browser, no `npm install` required. +A zero-dependency local control panel for [OpenClaw](https://github.com/anthropics/openclaw). Manage agents, bindings, logs, commands, and rollback from your browser — no `npm install` required. [中文说明](#中文说明) · [中文使用说明(含截图)](docs/USAGE_GUIDE.zh-CN.md) · [English Guide (with screenshots)](docs/USAGE_GUIDE.en.md) @@ -31,6 +31,16 @@ Open [http://localhost:3333](http://localhost:3333) in your browser. For remote - Changelog: docs/CHANGELOG.md +## Why OCM + +OCM is best thought of as an **OpenClaw control panel**, not just a config editor. + +It helps with three things that become painful fast in raw JSON / terminal workflows: + +- **Agent topology** — see which agent is bound to which chat/channel/thread +- **Everyday operations** — run CLI commands, inspect health/logs, restart gateway +- **Safer changes** — update config with backups and rollback nearby + ## Features
@@ -67,7 +77,22 @@ Open [http://localhost:3333](http://localhost:3333) in your browser. For remote - **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. -## Telegram Workflow & Safety +## 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**: @@ -113,6 +138,18 @@ You can also create `manager-config.json` manually: `manager-config.json` is gitignored and won't be committed. +## 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: diff --git a/docs/FAQ.md b/docs/FAQ.md index 6d61bdc..3b09487 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -51,3 +51,12 @@ That said, your local OpenClaw config contains sensitive information. Follow the - 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 群聊拓扑。 diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 1d9495d..e04d785 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -28,3 +28,25 @@ If you share screenshots publicly: - 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. diff --git a/docs/USAGE_GUIDE.en.md b/docs/USAGE_GUIDE.en.md index f803c55..ef0d8d8 100644 --- a/docs/USAGE_GUIDE.en.md +++ b/docs/USAGE_GUIDE.en.md @@ -2,7 +2,7 @@ > Audience: People who already have OpenClaw running locally (you can run `openclaw status` and read `openclaw gateway logs`). > -> Goal: Use **OpenClaw Manager (OCM)** to make agent/sub-agent setup and day-to-day ops **visual, safer, and easier to audit**. +> Goal: Use **OpenClaw Manager (OCM)** as an **OpenClaw control panel** for agent setup, routing, health checks, built-in CLI, and safer config changes. --- @@ -60,7 +60,18 @@ Recommended rule: --- -## 2) Start OCM (macOS) +## 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: @@ -78,7 +89,7 @@ bash start.sh --host 127.0.0.1 --- -## 3) Dashboard: check health first +## 4) Dashboard: check health first The Dashboard is your “sanity check”: @@ -92,11 +103,11 @@ Screenshot: --- -## 4) Create a main agent (with its own Telegram bot) +## 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. -### 4.1 BotFather prerequisites +### 5.1 BotFather prerequisites 1) Create a bot - In Telegram, open **BotFather** @@ -115,7 +126,7 @@ If group privacy is ON, the bot can’t see normal group messages. The symptom o - “typing…” appears frequently - sometimes no response at all -### 4.2 Add the agent in OCM +### 5.2 Add the agent in OCM Go to **Agents**: @@ -132,15 +143,15 @@ OCM writes the agent + Telegram account/binding into `openclaw.json`. --- -## 5) Create a sub-agent (recommended workflow) +## 6) Create a sub-agent (recommended workflow) -### 5.1 Why a new group per sub-agent +### 6.1 Why a new group per sub-agent - clean context isolation - easier debugging - easy to “turn off” by muting a group -### 5.2 Step-by-step +### 6.2 Step-by-step In **Agents** → `+ Add Sub-Agent`: @@ -174,14 +185,14 @@ If you use `channels.telegram.allowFrom`, OCM can take “Your Telegram User ID -## 5) Discord workflow (main agent + sub-agent) +## 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) -### 5.1 Add a Discord main agent +### 6.5.1 Add a Discord main agent Go to **Agents** → `+ Add Agent` → set **Channel = Discord**: @@ -191,7 +202,7 @@ Steps: 1) Create/select a dedicated Discord **channel** (private recommended) 2) Right-click channel → **Copy Link** → paste into the form (auto-parses channelId) -### 5.2 Add a Discord sub-agent (thread-first) +### 6.5.2 Add a Discord sub-agent (thread-first) Go to **Agents** → `+ Add Sub-Agent` → set **Channel = Discord (thread only)**: @@ -202,7 +213,7 @@ Steps: 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) -## 6) Verify bindings (Channels) +## 7) Verify bindings (Channels) Go to **Channels**: @@ -214,7 +225,7 @@ Here you can quickly validate: --- -## 7) Model settings (Models) +## 8) Model settings (Models) Go to **Models**: diff --git a/docs/USAGE_GUIDE.zh-CN.md b/docs/USAGE_GUIDE.zh-CN.md index 7c2cd15..b19588a 100644 --- a/docs/USAGE_GUIDE.zh-CN.md +++ b/docs/USAGE_GUIDE.zh-CN.md @@ -2,7 +2,7 @@ > 面向:已经在本机安装并跑通 OpenClaw 的用户(至少会用 `openclaw status` / `openclaw gateway logs`) > -> 目标:用 **OpenClaw Manager (OCM)** 把“创建 Agent / Sub-Agent、绑定 Telegram 群、管理模型/认证、看用量、看 cron”这套流程做成可视化、可回溯、低风险。 +> 目标:把 **OpenClaw Manager (OCM)** 当成 **OpenClaw 控制台** 来用:管理 Agent、查看 Routing、做健康检查、运行内置 CLI,并更安全地修改配置。 --- @@ -54,9 +54,20 @@ OCM 的定位:**把配置变更“可视化 + 可检查 + 可回滚(配合 --- -## 2) 启动与进入 OCM +## 2) 第一次使用时最该确认什么 -### 2.1 启动(macOS) +对新用户来说,第一步不是“先把所有配置都改完”,而是先确认四件事: + +1. OCM 找到的是正确的 OpenClaw 目录 +2. Gateway 是健康的 +3. Agent / Routing 能正常查看 +4. 内置终端可以正常跑命令 + +所以第一次使用时,最重要的页面其实是 Dashboard、Routing 和内置终端。 + +## 3) 启动与进入 OCM + +### 3.1 启动(macOS) 在 OCM 目录: @@ -68,7 +79,7 @@ bash start.sh > 需要限制只能本机访问:`bash start.sh --host 127.0.0.1` -### 2.2 Dashboard(先看健康状态) +### 3.2 Dashboard(先看健康状态) 建议第一步先看 Dashboard,确认: - 机器资源(CPU/RAM/DISK) @@ -81,11 +92,11 @@ bash start.sh --- -## 3) 创建主 Agent(Main Agent / 独立 Bot) +## 4) 创建主 Agent(Main Agent / 独立 Bot) > 你的 `main` 一般是默认存在的;这里重点讲“新增一个 **拥有独立 Telegram bot 的主 Agent**”。 -### 3.1 BotFather 侧准备(必须) +### 4.1 BotFather 侧准备(必须) 1) 创建 bot - 在 Telegram 找 **BotFather** @@ -101,7 +112,7 @@ bash start.sh > 如果 Group Privacy 没关,bot 在群里看不到普通消息,会表现成“经常 typing 但没输出 / 没反应”。 -### 3.2 在 OCM 添加主 Agent +### 4.2 在 OCM 添加主 Agent 进入 **Agents** 页面: @@ -117,14 +128,14 @@ bash start.sh --- -## 4) 创建 Sub-Agent(最常用) +## 5) 创建 Sub-Agent(最常用) -### 4.1 为什么 Sub-Agent 要用“新群” +### 5.1 为什么 Sub-Agent 要用“新群” - 让每个 Sub-Agent 有自己独立的对话上下文、任务边界 - 出问题直接在该群排查,不污染主 Agent 的对话 -### 4.2 Sub-Agent 创建流程(逐步) +### 5.2 Sub-Agent 创建流程(逐步) 进入 **Agents** 页面 → 点击 `+ Add Sub-Agent`,按引导做: @@ -157,7 +168,7 @@ OCM 的表单里可以填 “Your Telegram User ID”,让它自动把你的 us -## 5) Discord 工作流(主 Agent + Sub-Agent) +## 6) Discord 工作流(主 Agent + Sub-Agent) OCM 也支持 Discord: @@ -185,7 +196,7 @@ OCM 也支持 Discord: 2) 如果是 private thread,需要把 bot 拉进 thread 3) 右键 Thread → **Copy Link** → 粘贴到表单(自动解析 threadId) -## 5) 绑定检查(Channels 页) +## 7) 绑定检查(Channels 页) 进入 **Channels**: @@ -199,7 +210,7 @@ OCM 也支持 Discord: --- -## 6) 模型管理(Models 页) +## 8) 模型管理(Models 页) 进入 **模型**: @@ -211,7 +222,7 @@ OCM 也支持 Discord: --- -## 7) 认证管理(Auth 页) +## 9) 认证管理(Auth 页) 进入 **认证**: diff --git a/openclaw-manager.js b/openclaw-manager.js index eb50824..6fd8659 100644 --- a/openclaw-manager.js +++ b/openclaw-manager.js @@ -1979,7 +1979,7 @@ const MAIN_HTML_BODY = String.raw`
- 连接中... +