mirror of
https://github.com/dtzp555-max/ocm.git
synced 2026-07-21 21:15:08 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 
|
3d58bfc8af | ||
|
|
d3fdbcef6a | ||
|
|
16a080e0b2 | ||
|
|
69258d8428 | ||
|
|
a371ba6f7c | ||
|
|
8ae5fdb20c | ||
|
|
c3ed4c9c8f | ||
|
|
0a5f963b14 | ||
|
|
9e3ec7b616 | ||
|
|
55bfdcdbc8 | ||
|
|
c6da627fed | ||
|
|
743b8acea1 | ||
|
|
e0ebe68fb5 | ||
|
|
1c894d4ee7 | ||
|
taodeng
|
bfbc4e76da | ||
|
taodeng
|
0a8779b790 | ||
|
taodeng
|
c006b2f8fb | ||
|
taodeng
|
80e6532ca2 | ||
|
dtzp555-maxandGitHub
|
f67d9d2991 | ||
|
taodeng
|
474f62a4c7 | ||
|
taodeng
|
fb5ea6bc84 | ||
|
taodeng
|
6c789e3471 | ||
|
taodeng
|
85a2178a80 | ||
|
taodeng
|
532a605e58 | ||
|
taodeng
|
149620dc1a | ||
|
taodeng
|
ba3ef27766 | ||
|
taodeng
|
373d8bda27 | ||
|
taodeng
|
d7274f6c88 | ||
|
taodeng
|
f9375ebf89 | ||
|
taodeng
|
79fa8b35ca | ||
|
taodeng
|
3bd82c5892 | ||
|
taodeng
|
18b1b9529b | ||
|
taodeng
|
428e92baa6 | ||
|
taodeng
|
e08c782559 | ||
|
taodeng
|
8e9b07a01e | ||
|
taodeng
|
8c20735ff5 | ||
|
taodeng
|
25d8b94209 | ||
|
taodeng
|
45e63f7440 | ||
|
taodeng
|
bd5c3f32ca | ||
|
taodeng
|
f1bdf702ad | ||
|
taodeng
|
78cb04931d |
@@ -1,7 +1,89 @@
|
||||
# OpenClaw Manager — 开发日志
|
||||
|
||||
> 最后更新：2026-02-27
|
||||
> 当前版本：v0.7.1
|
||||
> 最后更新：2026-03-17
|
||||
> 当前版本：v0.9.4
|
||||
|
||||
---
|
||||
|
||||
## v0.9.4 更新日志（2026-03-17）
|
||||
|
||||
### New Features
|
||||
|
||||
- **Skills & Tools 自动配置**：创建 Agent / Sub-Agent 时自动加载默认 Skills 和 Tool Groups
|
||||
- 默认 Skills：`memory-continuity`, `agent-workflow`, `execution-agent-dispatch`, `session-logs`
|
||||
- 默认 Tool Groups：`group:fs`, `group:runtime`, `group:memory`, `sessions_spawn`, `subagents`
|
||||
- 创建表单新增可折叠的 Skills & Tools 选择面板，支持 checkbox 多选
|
||||
- 提供「仅默认」「全选」「清空」快捷按钮
|
||||
- 不展开 / 不修改则自动使用默认预设，开箱即用
|
||||
- 支持的可选 Skills：browser-use, github, gh-issues, coding-agent, execution-agent-planner, discord, weather, summarize, healthcheck
|
||||
- 四个创建端点（Telegram Agent/Sub、Discord Agent/Sub）均支持 `skills` + `toolGroups` 字段
|
||||
|
||||
### Backend
|
||||
|
||||
- 新增 `applySkillsTools()` 服务端辅助函数，统一处理 skills/tools 的默认值回退逻辑
|
||||
- `POST /api/agents/bot`、`POST /api/agents/discord`、`POST /api/agents/discord-sub`、`POST /api/agents` 均已适配
|
||||
|
||||
### UI
|
||||
|
||||
- Skills & Tools Picker：深色风格 checkbox 网格，嵌入创建表单底部
|
||||
- 新增专用 CSS 样式（`.skills-picker`、`.sp-grid`、`.sp-item`、`.sp-actions`）
|
||||
- 新增 i18n 字符串支持中英文标签
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,12 +1,92 @@
|
||||
# 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 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)
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
## Why OCM exists
|
||||
|
||||
Running OpenClaw directly is powerful, but the day-to-day workflow can get messy fast:
|
||||
|
||||
- `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
|
||||
|
||||
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
|
||||
|
||||
## Is OCM for you?
|
||||
|
||||
**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
|
||||
|
||||
**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
|
||||
|
||||
## What OCM helps you do
|
||||
|
||||
### 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
|
||||
|
||||
### 2) Operate OpenClaw with less risk
|
||||
- restart gateway
|
||||
- inspect logs
|
||||
- run OpenClaw commands from the built-in terminal
|
||||
- make config changes with rollback nearby
|
||||
|
||||
### 3) Recover faster when things go wrong
|
||||
- browse backups / snapshots
|
||||
- roll back config safely
|
||||
- keep troubleshooting and operational tools close to the same UI
|
||||
|
||||
## See it quickly
|
||||
|
||||
These are the highest-value surfaces for first-time users:
|
||||
|
||||
<p>
|
||||
<img src="docs/redacted-screenshots-refresh/dashboard-2026-03-07.jpg" width="860" />
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<img src="docs/redacted-screenshots-refresh/agents-2026-03-07.jpg" width="280" />
|
||||
<img src="docs/redacted-screenshots-refresh/cli-2026-03-07.jpg" width="280" />
|
||||
<img src="docs/redacted-screenshots/actions.jpg" width="180" />
|
||||
</p>
|
||||
|
||||
More screenshots: see the [full usage guide](docs/USAGE_GUIDE.en.md) or the gallery below.
|
||||
|
||||
<details>
|
||||
<summary><b>Full screenshots gallery</b> (redacted: no personal paths, no Telegram IDs)</summary>
|
||||
|
||||
<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>
|
||||
|
||||
</details>
|
||||
|
||||
## Quick Start (recommended path)
|
||||
|
||||
```bash
|
||||
# Clone
|
||||
@@ -16,45 +96,99 @@ cd ocm
|
||||
# Run (no npm install needed)
|
||||
bash start.sh # macOS / Linux
|
||||
start.bat # Windows
|
||||
|
||||
# Update
|
||||
git pull --ff-only
|
||||
```
|
||||
|
||||
Open [http://localhost:3333](http://localhost:3333) in your browser. For remote access, use `bash start.sh --host 0.0.0.0`.
|
||||
Then open [http://localhost:3333](http://localhost:3333).
|
||||
|
||||
## Features
|
||||
For remote access, use:
|
||||
|
||||
**Screenshots** — Redacted UI walkthrough (no personal paths, no Telegram IDs):
|
||||
```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
|
||||
|
||||
**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.
|
||||
The most common reasons OCM feels rough are not usually “the UI is broken”, but environment mismatch:
|
||||
|
||||
**Usage Statistics** — Real token usage data parsed directly from OpenClaw session files. Breakdown by model, agent, and day with a visual chart.
|
||||
- OpenClaw itself is not fully healthy yet
|
||||
- wrong OpenClaw directory
|
||||
- path / permission issues
|
||||
- different service/runtime layouts across machines
|
||||
- channel workflow differences
|
||||
|
||||
**Model & Auth** — Configure models from your registered provider list. Follow built-in guides for provider authentication setup.
|
||||
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.
|
||||
|
||||
**Built-in CLI** — Run any `openclaw` command with real-time streaming output. Preset commands, favorites, and tab completion included.
|
||||
## Docs
|
||||
|
||||
**Ops Panel** — Restart gateway, view logs, run health checks, manage backups (local + NAS via SFTP/rsync), and handle cron tasks.
|
||||
- **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
|
||||
|
||||
**Bilingual UI** — English and Chinese interface with one-click language switching.
|
||||
## Features by area
|
||||
|
||||
## Telegram Workflow & Safety
|
||||
- **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. New agents automatically get default Skills and Tool Groups, or you can customize them via the built-in Skills & Tools picker.
|
||||
- **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)
|
||||
|
||||
- **Skills & Tools auto-config**: new agents/sub-agents automatically get default Skills (`memory-continuity`, `session-logs`) and Tool Groups (`fs`, `runtime`, `memory`, `sessions_spawn`, `subagents`). A collapsible Skills & Tools picker in the creation form lets you customize per agent.
|
||||
- **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**:
|
||||
|
||||
@@ -100,6 +234,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:
|
||||
@@ -134,6 +280,12 @@ ocm/
|
||||
- **Frontend**: Vanilla HTML/CSS/JS embedded in a template literal — no build step, no framework
|
||||
- **Architecture**: Single-file, zero-dependency, runs anywhere Node.js runs
|
||||
|
||||
## Related Projects
|
||||
|
||||
- [clawkeeper](https://github.com/dtzp555-max/clawkeeper) — OpenClaw memory operations kit for doctor / provider switch / backup / restore workflows. *(archived)*
|
||||
- [execution-agent-planner](https://github.com/dtzp555-max/execution-agent-planner) — archived planning skill for deciding when work should stay with one execution agent or split across specialized workers.
|
||||
- [gh-pr-release-flow](https://github.com/dtzp555-max/gh-pr-release-flow) — skill for PR-first GitHub repos where release work should happen after merge.
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
@@ -142,7 +294,38 @@ MIT
|
||||
|
||||
## 中文说明
|
||||
|
||||
OpenClaw Manager 是一个零依赖的本地 Web 管理界面，用于可视化管理 [OpenClaw](https://github.com/anthropics/openclaw) AI 智能体。所有代码在一个 `.js` 文件中，只需 Node.js 18+，不需要 `npm install`。
|
||||
OpenClaw Manager（OCM）是一个本地 OpenClaw 控制面板，用来更直观地管理 Agent、查看绑定关系、做健康检查、运行内置 CLI，并在改配置或排错时少踩坑。
|
||||
|
||||
### OCM 解决什么问题
|
||||
|
||||
直接使用 OpenClaw 很强，但日常维护很容易变成：
|
||||
- 改 `openclaw.json` 容易手滑
|
||||
- Agent / bot / 群 / 线程绑定关系很难一眼看清
|
||||
- 健康检查、日志、重启、回滚散落在多个终端命令里
|
||||
- 出问题时恢复链路不够顺手
|
||||
|
||||
OCM 的定位不是替代 OpenClaw，而是给现有 OpenClaw 环境加一个**本地控制台**。
|
||||
|
||||
### 适合谁
|
||||
|
||||
**适合：**
|
||||
- 已经在本机跑通 OpenClaw 的用户
|
||||
- 想更直观地管理 Agent / Routing / Health / Logs / Backups 的用户
|
||||
- 不想频繁手改复杂 JSON 的用户
|
||||
|
||||
**暂时不太适合：**
|
||||
- 还没装好 OpenClaw、希望 OCM 包办全部安装复杂度的新手
|
||||
- 默认期待所有平台 / 所有 channel 路线都同样成熟的用户
|
||||
- 想要云端托管产品而不是本地工具的用户
|
||||
|
||||
### OCM 最有价值的三件事
|
||||
|
||||
1. **看清你的 OpenClaw 结构**
|
||||
- Agent 树、绑定关系、模型、认证、健康状态更直观
|
||||
2. **更安全地做运维操作**
|
||||
- 重启 gateway、看日志、跑 CLI、改配置、回滚更顺手
|
||||
3. **出问题时恢复更快**
|
||||
- 备份、回滚、排查入口都更近
|
||||
|
||||
### 快速开始
|
||||
|
||||
@@ -153,43 +336,33 @@ bash start.sh # macOS / Linux
|
||||
start.bat # Windows
|
||||
```
|
||||
|
||||
访问 [http://localhost:3333](http://localhost:3333)。远程访问请使用 `bash start.sh --host 0.0.0.0`。
|
||||
打开 [http://localhost:3333](http://localhost:3333)。
|
||||
|
||||
### 功能
|
||||
### 第一次使用建议先做这几步
|
||||
|
||||
- **Agent 管理** — 添加主 Agent 和子 Agent，树状结构查看，内联切换模型，浏览工作区文件
|
||||
- **使用统计** — 从 OpenClaw 会话文件解析真实 Token 用量，按模型/Agent/日期维度展示
|
||||
- **模型与认证** — 管理注册模型列表，内置 Provider 认证引导
|
||||
- **内置终端** — 实时流式输出，预设命令，收藏夹，Tab 补全
|
||||
- **运维面板** — 重启网关、查看日志、健康检查、本地/NAS 备份、Cron 任务管理
|
||||
- **双语界面** — 中英文一键切换
|
||||
1. 确认 OCM 找到了正确的 OpenClaw 目录
|
||||
2. 打开 **Dashboard** 看 gateway 是否健康
|
||||
3. 打开 **Agents / Channels** 看绑定是否正确
|
||||
4. 打开内置 **Terminal** 跑一条 OpenClaw 命令
|
||||
5. 看一眼 **Actions / 备份 / 回滚**，确保恢复路径就在手边
|
||||
|
||||
### Telegram 场景与安全提示
|
||||
### 当前支持定位
|
||||
|
||||
OCM 主要面向 **Telegram 场景**：
|
||||
**目前最好用的场景：**
|
||||
- macOS / Linux
|
||||
- 本地 OpenClaw 环境
|
||||
- 本地 health / logs / ops / backup 工作流
|
||||
- Telegram-first 的 Agent 管理方式
|
||||
|
||||
- 通过群组绑定主 Agent，并在每条树下管理多个 Sub-Agent
|
||||
- 让每个 Agent 拥有独立 `workspace`、`SOUL.md`、`MEMORY.md`
|
||||
- 通过可视化方式更新 `openclaw.json`，减少手动改配置风险
|
||||
- 建议使用者已具备基础 OpenClaw CLI 操作经验（如 `onboard`、认证、查看网关日志）
|
||||
**支持，但不保证同样顺滑：**
|
||||
- Discord workflow
|
||||
- 更复杂的 routing / service 布局
|
||||
- 混合环境
|
||||
|
||||
关键安全设置（务必确认）：
|
||||
### 文档
|
||||
|
||||
- BotFather 里 **Allow Groups = ON**
|
||||
- BotFather 里 **Group Privacy = OFF**
|
||||
- 每个 Agent 群组只保留“你自己 + 对应 Agent/Sub-Agent”
|
||||
- 不要邀请其他人进组（会带来安全和 API 费用风险）
|
||||
|
||||
### 配置
|
||||
|
||||
启动脚本自动检测 `~/.openclaw` 目录。如需指定其他路径：
|
||||
|
||||
```bash
|
||||
bash start.sh --dir /path/to/.openclaw --port 8080
|
||||
```
|
||||
|
||||
也可手动创建 `manager-config.json`：
|
||||
|
||||
```json
|
||||
{ "dir": "~/.openclaw" }
|
||||
```
|
||||
- 英文使用说明：docs/USAGE_GUIDE.en.md
|
||||
- 中文使用说明：docs/USAGE_GUIDE.zh-CN.md
|
||||
- FAQ：docs/FAQ.md
|
||||
- 安全说明：docs/SECURITY.md
|
||||
- 更新记录：docs/CHANGELOG.md
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
# Changelog
|
||||
|
||||
This is a user-facing summary derived from `DEVLOG.md`.
|
||||
|
||||
## v0.9.4
|
||||
- **Skills & Tools auto-config**: New agents/sub-agents now automatically get default Skills (memory-continuity, agent-workflow, execution-agent-dispatch, session-logs) and Tool Groups (fs, runtime, memory, sessions_spawn, subagents).
|
||||
- Agent creation forms include a collapsible Skills & Tools picker with checkbox multi-select and quick-action buttons (Default / All / None).
|
||||
- All 4 creation endpoints (Telegram/Discord × Agent/Sub-Agent) support `skills` and `toolGroups` fields.
|
||||
|
||||
## 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.
|
||||
@@ -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)
|
||||
+62
@@ -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 群聊拓扑。
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,334 @@
|
||||
# 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:
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 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**:
|
||||
|
||||
|
||||
|
||||
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
|
||||
- **Skills & Tools** (optional): expand the collapsible picker at the bottom to customize. By default, new agents get: `memory-continuity`, `session-logs` as Skills, and `group:fs`, `group:runtime`, `group:memory`, `sessions_spawn`, `subagents` as Tool Groups. Use the quick-action buttons (Default / All / None) to adjust.
|
||||
|
||||
OCM writes the agent + Telegram account/binding + skills + tool groups 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
|
||||
- **Skills & Tools** (optional): same picker as Add Agent — defaults are pre-selected, expand to customize
|
||||
|
||||
**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**:
|
||||
|
||||
|
||||
|
||||
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)**:
|
||||
|
||||
|
||||
|
||||
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**:
|
||||
|
||||
|
||||
|
||||
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**:
|
||||
|
||||
|
||||
|
||||
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**:
|
||||
|
||||
|
||||
|
||||
Use this page to:
|
||||
- see which provider profiles exist
|
||||
- troubleshoot expired/missing tokens
|
||||
|
||||
---
|
||||
|
||||
## 9) Usage stats (Stats)
|
||||
|
||||
Go to **Stats**:
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
## 10) Cron jobs (Cron)
|
||||
|
||||
Go to **Cron**:
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 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/`.
|
||||
@@ -0,0 +1,326 @@
|
||||
# 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 数量
|
||||
|
||||
截图示例：
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 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** 页面：
|
||||
|
||||
|
||||
|
||||
点击 `+ Add Agent`，按表单填写：
|
||||
- Agent id / name
|
||||
- workspace 路径（建议独立目录）
|
||||
- 选择模型（下拉来自 `openclaw models list`，更不容易选错）
|
||||
- 填入刚拿到的 bot token
|
||||
- **Skills & Tools**（可选）：展开表单底部的折叠面板可自定义。默认预设：Skills 包含 `memory-continuity`、`session-logs`；Tool Groups 包含 `group:fs`、`group:runtime`、`group:memory`、`sessions_spawn`、`subagents`。提供「仅默认 / 全选 / 清空」快捷按钮。
|
||||
|
||||
保存后，OCM 会把主 Agent + skills + tools 写进 `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（建议单独目录）
|
||||
- 选择模型
|
||||
- **Skills & Tools**（可选）：和 Add Agent 相同的选择器，默认预设已勾选，展开可自定义
|
||||
|
||||
#### 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**：
|
||||
|
||||
|
||||
|
||||
步骤：
|
||||
1) 创建/选择一个专用 Discord Channel（建议私密）
|
||||
2) 右键 Channel → **Copy Link** → 粘贴到表单（自动解析 channelId）
|
||||
|
||||
### 5.2 添加 Discord Sub-Agent（Thread 优先）
|
||||
|
||||
进入 **Agents** → `+ Add Sub-Agent` → 选择 **渠道 = Discord (thread only)**：
|
||||
|
||||
|
||||
|
||||
步骤：
|
||||
1) 在主 Channel 下新建 Thread（建议“一个任务一个 thread”）
|
||||
2) 如果是 private thread，需要把 bot 拉进 thread
|
||||
3) 右键 Thread → **Copy Link** → 粘贴到表单（自动解析 threadId）
|
||||
|
||||
## 7) 绑定检查（Channels 页）
|
||||
|
||||
进入 **Channels**：
|
||||
|
||||
|
||||
|
||||
这里能一眼看到：
|
||||
- 哪个 agent 绑定了哪个 Telegram peer（群）
|
||||
- main 的“兜底绑定”（any）是否存在
|
||||
|
||||
> 如果某个 Sub-Agent 绑定错群/丢 binding，最直观的就是在这里对不上。
|
||||
|
||||
---
|
||||
|
||||
## 8) 模型管理（Models 页）
|
||||
|
||||
进入 **模型**：
|
||||
|
||||
|
||||
|
||||
关键点：
|
||||
- 主模型（primary）和 fallback 链
|
||||
- 下拉列表来自 `openclaw models list`（能减少“选了不存在模型”的问题）
|
||||
|
||||
---
|
||||
|
||||
## 9) 认证管理（Auth 页）
|
||||
|
||||
进入 **认证**：
|
||||
|
||||
|
||||
|
||||
这里主要用来：
|
||||
- 看当前有哪些 provider profile
|
||||
- 排查某个 provider 是否过期/缺 token
|
||||
|
||||
---
|
||||
|
||||
## 8) 用量统计（Stats 页）
|
||||
|
||||
进入 **Stats**：
|
||||
|
||||
|
||||
|
||||
你可以按：
|
||||
- 按模型聚合
|
||||
- 按 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，方便排错
|
||||
|
||||
截图示例：
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 9) Actions 菜单（运维快捷入口）
|
||||
|
||||
右上角 **⚡ Actions** 下拉菜单提供常用运维操作：
|
||||
- Restart Gateway（重启网关）
|
||||
- Live Logs（实时日志）
|
||||
- Manual Backup / Backups & Rollback（备份/回滚）
|
||||
- NAS Backup Setup（NAS 备份配置）
|
||||
- Health Check（健康检查）
|
||||
- Open Config Dir / Switch OpenClaw Dir（打开/切换配置目录）
|
||||
|
||||
截图示例：
|
||||
|
||||
|
||||
|
||||
## 9) Cron（定时任务）
|
||||
|
||||
进入 **Cron**：
|
||||
|
||||
|
||||
|
||||
用途：
|
||||
- 查看有哪些健康检查/更新/备份任务
|
||||
- 手动运行
|
||||
- 观察启用/禁用状态
|
||||
|
||||
---
|
||||
|
||||
## 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 等均已模糊处理）。
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 126 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 142 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 182 KiB After Width: | Height: | Size: 24 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 164 KiB After Width: | Height: | Size: 162 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 71 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 177 KiB After Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 177 KiB After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 228 KiB After Width: | Height: | Size: 226 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 131 KiB After Width: | Height: | Size: 129 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 207 KiB After Width: | Height: | Size: 29 KiB |
+799
-173
File diff suppressed because it is too large
Load Diff
+2
-2
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "openclaw-manager",
|
||||
"version": "0.7.1",
|
||||
"description": "A local web UI for managing OpenClaw AI agents — no npm install required",
|
||||
"version": "1.0.0-rc1",
|
||||
"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",
|
||||
|
||||
Reference in New Issue
Block a user