mirror of
https://github.com/dtzp555-max/ocm.git
synced 2026-07-21 21:15:08 +00:00
docs: add detailed zh-CN usage guide
This commit is contained in:
@@ -0,0 +1,251 @@
|
||||
# OCM 功能使用说明（含截图）
|
||||
|
||||
> 面向：已经在本机安装并跑通 OpenClaw 的用户（至少会用 `openclaw status` / `openclaw gateway logs`）
|
||||
>
|
||||
> 目标：用 **OpenClaw Manager (OCM)** 把“创建 Agent / Sub-Agent、绑定 Telegram 群、管理模型/认证、看用量、看 cron”这套流程做成可视化、可回溯、低风险。
|
||||
|
||||
---
|
||||
|
||||
## 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) 启动与进入 OCM
|
||||
|
||||
### 2.1 启动（macOS）
|
||||
|
||||
在 OCM 目录：
|
||||
|
||||
```bash
|
||||
bash start.sh
|
||||
```
|
||||
|
||||
默认访问：<http://localhost:3333>
|
||||
|
||||
> 需要限制只能本机访问：`bash start.sh --host 127.0.0.1`
|
||||
|
||||
### 2.2 Dashboard（先看健康状态）
|
||||
|
||||
建议第一步先看 Dashboard，确认：
|
||||
- 机器资源（CPU/RAM/DISK）
|
||||
- OpenClaw gateway 是否 Running
|
||||
- Agents 数量
|
||||
|
||||
截图示例：
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 3) 创建主 Agent（Main Agent / 独立 Bot）
|
||||
|
||||
> 你的 `main` 一般是默认存在的；这里重点讲“新增一个 **拥有独立 Telegram bot 的主 Agent**”。
|
||||
|
||||
### 3.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 但没输出 / 没反应”。
|
||||
|
||||
### 3.2 在 OCM 添加主 Agent
|
||||
|
||||
进入 **Agents** 页面：
|
||||
|
||||
|
||||
|
||||
点击 `+ Add Agent`，按表单填写：
|
||||
- Agent id / name
|
||||
- workspace 路径（建议独立目录）
|
||||
- 选择模型（下拉来自 `openclaw models list`，更不容易选错）
|
||||
- 填入刚拿到的 bot token
|
||||
|
||||
保存后，OCM 会把这颗主 Agent 写进 `openclaw.json`，并把 bot token 绑定到对应 `accountId`。
|
||||
|
||||
---
|
||||
|
||||
## 4) 创建 Sub-Agent（最常用）
|
||||
|
||||
### 4.1 为什么 Sub-Agent 要用“新群”
|
||||
|
||||
- 让每个 Sub-Agent 有自己独立的对话上下文、任务边界
|
||||
- 出问题直接在该群排查，不污染主 Agent 的对话
|
||||
|
||||
### 4.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/群消息被拒。
|
||||
|
||||
---
|
||||
|
||||
## 5) 绑定检查（Channels 页）
|
||||
|
||||
进入 **Channels**：
|
||||
|
||||
|
||||
|
||||
这里能一眼看到：
|
||||
- 哪个 agent 绑定了哪个 Telegram peer（群）
|
||||
- main 的“兜底绑定”（any）是否存在
|
||||
|
||||
> 如果某个 Sub-Agent 绑定错群/丢 binding，最直观的就是在这里对不上。
|
||||
|
||||
---
|
||||
|
||||
## 6) 模型管理（Models 页）
|
||||
|
||||
进入 **模型**：
|
||||
|
||||
|
||||
|
||||
关键点：
|
||||
- 主模型（primary）和 fallback 链
|
||||
- 下拉列表来自 `openclaw models list`（能减少“选了不存在模型”的问题）
|
||||
|
||||
---
|
||||
|
||||
## 7) 认证管理（Auth 页）
|
||||
|
||||
进入 **认证**：
|
||||
|
||||
|
||||
|
||||
这里主要用来：
|
||||
- 看当前有哪些 provider profile
|
||||
- 排查某个 provider 是否过期/缺 token
|
||||
|
||||
---
|
||||
|
||||
## 8) 用量统计（Stats 页）
|
||||
|
||||
进入 **Stats**：
|
||||
|
||||
|
||||
|
||||
你可以按：
|
||||
- 按模型聚合
|
||||
- 按 Agent 聚合
|
||||
- 按天趋势
|
||||
|
||||
> OCM 是从 OpenClaw 的 session JSONL 里解析真实 usage（比“看日志猜”靠谱）。
|
||||
|
||||
---
|
||||
|
||||
## 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 等均已模糊处理）。
|
||||
Reference in New Issue
Block a user