mirror of
https://github.com/dtzp555-max/ocm.git
synced 2026-07-21 21:15:08 +00:00
325 lines
9.4 KiB
Markdown
325 lines
9.4 KiB
Markdown
# 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
|
||
|
||
保存后，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**：
|
||
|
||
|
||
|
||
步骤：
|
||
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 等均已模糊处理）。
|