8.1 KiB
OCM 功能使用说明（含截图）
面向：已经在本机安装并跑通 OpenClaw 的用户（至少会用
openclaw status/openclaw gateway logs）目标：用 OpenClaw Manager (OCM) 把“创建 Agent / Sub-Agent、绑定 Telegram 群、管理模型/认证、看用量、看 cron”这套流程做成可视化、可回溯、低风险。
0) 先说痛点：为什么要用 OCM
0.1 创建/维护 Agent 的典型痛点
-
改
openclaw.json容易改错- 字段多、层级深、容易手滑覆盖 token / accountId / bindings。
- 一次写错可能导致多个 Agent 全挂。
-
Sub-Agent 的边界和“谁在用哪个 bot token”不直观
- 多 Bot / 多 agent / 多群组绑定时，光靠肉眼看 JSON 很难确认拓扑结构是否正确。
-
模型选择很容易“写了一个不存在的 model-id”
- provider/model-id 拼错、或 provider 侧不支持，最后表现就是 Agent 变慢/报错/一直 typing。
-
统计用量和排查问题耗时
- 需要翻 session JSONL / gateway logs 才能知道谁在烧 token、哪里失败。
OCM 的定位：把配置变更“可视化 + 可检查 + 可回滚（配合备份）”，并把常用运维入口集中起来。
1) 为什么用 Telegram group 来建 Sub-Agent 最合适
这里讨论的是 OpenClaw 的一种非常实用的工作方式：“一个 Telegram 群 = 一个 Agent 的工作空间/人格/上下文边界”。
1.1 Telegram group 方案的优势
-
边界天然清晰
- 每个 Agent 只在自己的群里说话，和其他 Agent 隔离。
-
上下文可控
- 一个群的聊天记录就是该 Agent 的输入流；不会和别的任务混在一起。
-
并发与分工自然
- 主 Agent 负责总控/派工，Sub-Agent 负责专项：技术宅/旅行/理财/翻译……
-
可审计
- 群里发生了什么一眼可见；出问题也能定位是哪条消息触发。
1.2 为什么“群必须私密”（安全与成本）
- 强烈建议：每个 Agent 群只留你自己 + 对应 bot（+ 必要时的另一个你自己的账号）。
- 不要拉别人进来：
- 成本：别人一句话就触发 token 消耗
- 安全：可能诱导泄露信息/触发危险操作
2) 启动与进入 OCM
2.1 启动（macOS）
在 OCM 目录：
bash start.sh
需要限制只能本机访问：
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 侧准备（必须）
- 创建 bot
- 在 Telegram 找 BotFather
- 发送
/newbot→ 按提示创建 → 拿到 bot token
- 允许加群
- BotFather → 你的 bot → Bot Settings
- Allow Groups = ON
- 关闭群隐私（非常关键）
- 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。
常见拿法：
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) 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 但不回”
优先检查：
- BotFather 的 Group Privacy 是否 OFF
- OpenClaw gateway 是否健康（
openclaw status） - provider 是否限流/超时（Auth 页 + gateway logs）
10.2 模型下拉没有你想要的模型
- 现在下拉是
openclaw models list的真实输出。 - 先确保你在 OpenClaw 里已经注册/可见该模型。
11) 推荐的“最佳实践”
- 每个 Agent 都用独立 workspace（隔离文件/记忆）
- 每个 Sub-Agent 都用独立 Telegram 群（隔离上下文）
- 群里不要加第三方（成本 + 安全）
- 任何“改配置的大动作”尽量先备份（OCM/脚本/手工都行）
附：截图说明
本文截图来自 docs/redacted-screenshots/，已做脱敏（路径用户名、Telegram 绑定 ID 等均已模糊处理）。