{"id":48748448,"url":"https://github.com/randychen1985/openclaw-buddy","last_synced_at":"2026-04-26T13:01:30.188Z","repository":{"id":347561154,"uuid":"1193615077","full_name":"RandyChen1985/openclaw-buddy","owner":"RandyChen1985","description":"让 OpenClaw 的运维从此优雅，让每一个 AI 代理都有不灭的灯塔。| Openclaw 可视化管理，Web 在线聊天，embed 嵌入小龙虾， 自愈恢复管理。 基于 openclaw 指令级管理，不依赖 gateway 网关是否启动。","archived":false,"fork":false,"pushed_at":"2026-04-19T14:21:25.000Z","size":326581,"stargazers_count":25,"open_issues_count":0,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T14:42:21.395Z","etag":null,"topics":["ai","openclaw","openclaw-agent","openclaw-manager","openclaw-plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RandyChen1985.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-27T12:11:21.000Z","updated_at":"2026-04-19T12:33:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/RandyChen1985/openclaw-buddy","commit_stats":null,"previous_names":["randychen1985/openclaw-buddy"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/RandyChen1985/openclaw-buddy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RandyChen1985%2Fopenclaw-buddy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RandyChen1985%2Fopenclaw-buddy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RandyChen1985%2Fopenclaw-buddy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RandyChen1985%2Fopenclaw-buddy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RandyChen1985","download_url":"https://codeload.github.com/RandyChen1985/openclaw-buddy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RandyChen1985%2Fopenclaw-buddy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32297900,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","openclaw","openclaw-agent","openclaw-manager","openclaw-plugin"],"created_at":"2026-04-12T14:13:34.853Z","updated_at":"2026-04-26T13:01:30.182Z","avatar_url":"https://github.com/RandyChen1985.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🦞 OpenClaw Buddy 宣言\n\n![Banner](docs/images/banner.png)\n\n\u003e [🌈!NOTE💗]\n\u003e “我听人说，如果连咖啡都没有伴侣，那它就不叫咖啡，叫苦水。在这个习惯了礼貌拒绝的时代，连空气中都带着独身的湿气。但我始终觉得，即使是代码堆砌的小龙虾，也该有个依靠。\n\u003e\n\u003e **OpenClaw Buddy**，它就在离你 0.01 公分的地方。它不说话，只是陪你守着那些虾宝宝。希望有一天，你也能找到那个让你不再需要‘监控哨兵’的人。” [简体中文] | [English](README_en.md)\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/yovole/openclaw-monitor)](https://goreportcard.com/report/github.com/yovole/openclaw-monitor) [![Go Version](https://img.shields.io/github/go-mod/go-version/yovole/openclaw-monitor?color=blue)](https://github.com/yovole/openclaw-monitor) [![Build Status](https://img.shields.io/badge/Build-Success-brightgreen)](https://github.com/yovole/openclaw-monitor) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-orange.svg)](https://github.com/yovole/openclaw-monitor/pulls) [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/yovole/openclaw-monitor/graphs/commit-activity) [![License: MIT](https://img.shields.io/badge/License-MIT-purple.svg)](https://opensource.org/licenses/MIT)\n\n**OpenClaw Buddy** 是一款专为 **OpenClaw (小龙虾 AI Agent)** 打造的专业级带外管理 (Out-of-band Management) 与自愈伴侣系统。\n\n面对 AI 代理由于配置误改、插件冲突导致的“失联”风险，Buddy 作为独立运行的“监控哨兵”，提供了极佳的实时监控、流式登录捕获及自动化故障恢复能力，是每一位 OpenClaw 深度用户的必备运维利器。\n\n---\n\n## 📸 功能预览\n\n|    **系统概览 (Dashboard)**    |    **审计大屏 (Audit)**    |\n| :----------------------------------: | :-------------------------------: |\n| ![Dashboard](docs/images/overview.png) |   ![Audit](docs/images/audit.png)   |\n|    **专家模板( Template)**    |    **渠道绑定(Channel)**    |\n| ![Template](docs/images/template.png) | ![Channel](docs/images/channel.png) |\n|  **虾兵蟹将 (Bots \u0026 Models)**  | **对话聊天 (Online Chat)** |\n|     ![Bots](docs/images/bots.png)     |    ![Chat](docs/images/chat.png)    |\n\n---\n\n## ✨ 核心亮点\n\n- **🛡️ 独立哨兵 (OOB)**：独立进程运行，即使 OpenClaw 网关崩溃，也能通过 Buddy 远程重启、回滚并救回系统。\n- **⚡ 极速登录**：深度集成微信插件，流式响应登录二维码，扫码授权“秒级”完成。\n- **🤖 虾兵蟹将管理**：可视化管理所有 Bot 及模型映射，支持资产强制刷新与实时同步。\n- **🩺 智能自愈**：内置心跳探针与多阶段自愈机制，检测到异常自动执行配置回滚与备份快照。\n- **📊 运维看板**：实时追踪 CPU、内存负载、API 延迟与系统日志，掌握 AI 代理的每一滴跳动。\n- **🔔 飞书全能报警**：实时推送故障、自愈及登录交互式卡片消息。\n\n## ✨ 核心特性\n\n- **🖥️ 现代 Web 控制面板**：基于 React + Ant Design + Lucide 开发，支持响应式布局与 **WebSocket 实时日志追踪**。\n- **🧪 对话实验室 (Online Chat)**：集成流式对话测试界面，支持一键开启/配置、快捷指令管理及 Markdown 渲染。\n- **🛡️ 智能自愈系统 (Self-Healing)**：\n  - **多级回滚**：优先从 `backups/` 目录恢复已知健康的配置快照。\n  - **全量持久化**：巡检历史与自愈事件通过 SQLite 持久化存储，支持审计与趋势分析。\n- **📱 设备中心与授权**：\n  - **双态管理**：清晰区分“待处理连接请求”与“已配对合规设备”。\n  - **在线批准**：直接通过 Web 界面批准新设备的接入请求。\n- **🤖 虾兵蟹将 (Bots/Models)**：自动解析 `openclaw.json`，直观展示机器人架构，支持手动强制刷新同步。\n- **📺 微信插件深度管理**：自动化执行插件下载与启用配置，监听 `openclaw` 输出并实时捕获登录二维码。\n- **📊 运行指标可视化**：实时查看 CPU、内存、磁盘负载及响应延迟趋势图。\n- **🔄 异步任务管理**：关键操作（如重启）采用异步任务模式，支持任务状态追踪 (Task ID)。\n- **🔗 龙虾面板透传**：集成 Reverse Proxy，支持通过 `EXTERNAL_DASHBOARD_URL` 在公网安全访问原生 UI。\n\n## 🏗️ 系统架构\n\nOpenClaw Buddy 采用非侵入式的“侧挂”架构，通过监控回路与管理链路实现对 OpenClaw 的全方位加固。\n\n```text\n       [ 现代浏览器 / 移动端 ]\n                 │\n       [ OpenClaw Buddy Server ] (Go + Gin + React)\n                 │\n    ┌────────────┼────────────┐\n    │            │            │\n[ 监控自愈 ]   [ 资产管理 ]   [ 插件/授权 ]\n    │            │            │\n- 端口探针 (TCP)  - 模型直连测试  - 微信登录流捕获\n- 心跳/故障分析   - 资产强制同步  - 设备连接联机批准\n- 自动备份/回滚   - 默认模型分发  - 反向代理 (Native UI)\n- 趋势报表/入库   - 自定义渠道路由 - SQLite 状态持久化\n```\n\n## 🚀 快速开始\n\n### 前提条件\n\n- **Go 1.22+**\n- **Node.js 18+** (用于前端编译)\n- **OpenClaw** 环境已就绪\n\n### 快速开发与预览\n\n项目提供了一键开发脚本 `dev.sh`：\n\n```bash\n# 进入隔离开发模式（编译前端、构建后端、并在独立的 ./temp-dev-test 目录运行）\n./dev.sh\n```\n\n### 生产部署 (Release)\n\n1. **执行构建**: `./build_linux.sh` (交叉编译为 Linux)\n2. **获取产物**: 预编译包见 [GitHub Releases](https://github.com/RandyChen1985/openclaw-buddy/releases)；自行构建时产物位于 `release/` 目录，解压后上传至服务器。\n3. **参数配置**: 修改 `env` 文件（首次启动会自动生成 16 位随机 `BUDDY_TOKEN`）。\n4. **启动服务**: `./start.sh`\n\n## 📂 目录结构\n\nOpenClaw Buddy 采用标准的模块化设计，确保监控与被监控逻辑解耦。\n\n```text\n.\n├── cmd/monitor/             # [入口层] 程序主启动入口，负责加载配置、初始化日志与信号监控\n├── internal/\n│   ├── api/                 # [服务层] 核心 Web API 实现 (Gin)，包含权限验证与静态资源分包\n│   ├── guardian/            # [守护层] 哨兵核心逻辑，执行周期性健康检查与故障自愈流程\n│   ├── process/             # [进程层] 封装 openclaw 命令行交互及微信/机器人状态管理\n│   ├── config/              # [配置层] 环境变量解析与全局配置参数管理\n│   └── utils/               # [工具层] 共用工具类 (SQLite 初始化、文件锁、日志轮转)\n├── web/                     # [前端工程] 基于 React + Antd + Lucide 的后台管理面板\n├── tests/                   # [测试集]   包含集成测试脚本、飞书模拟器及核心自愈逻辑验证 (含 CHECKLIST.md 自动化清单)\n├── docs/                    # [文档集]   存放项目相关图片 (images) 及补充说明文档 (md)\n├── openspec/                # [规格集]   存放项目设计规范、功能定义 (specs) 及详细变更记录\n├── release/                 # [发布层]   生产环境的最终部署包所在地（包含二进制、静态资源、管理脚本及文档）\n├── dev.sh                   # [开发脚本] 一键式全栈开发脚本（隔离运行、自动编译、日志追踪）\n├── Makefile                 # [构建脚本] 用于交叉编译、清理产物及快速执行发布流程\n├── Embedding.md             # [文档]     对话实验室 (Online Chat) 嵌入集成开发指南\n├── API.md                   # [文档]     详尽的 RESTful 接口定义说明\n└── README.md                # [文档]     本自愈伴侣系统的核心宣言指南\n```\n\n## 🔌 API 接口说明\n\nOpenClaw Buddy 提供了一套标准的 RESTful API 供外部系统集成或移动端调用。\n\n\u003e [!TIP]\n\u003e 完整的 API 接口定义、请求参数及响应示例，请参考项目的 [API.md](file:///Users/chenxiaolong/资料/有孚网络/1云枢中台/yovole-openclaw-monitor/API.md) 文档。\n\n### 认证方式\n\n所有 V1 接口均需通过 HTTP Header 进行认证：\n\n- **Header**: `Authorization`\n- **Value**: `Bearer \u003cYOUR_BUDDY_TOKEN\u003e`\n\n### 核心接口说明 (By Module)\n\n#### 📊 运行状态 (Dashboard \u0026 System)\n\n| 路径                           | 方法 | 功能说明                                                      |\n| :----------------------------- | :--- | :------------------------------------------------------------ |\n| `/v1/openclaw/status`        | GET  | 获取网关核心运行状态、版本及运行时长                          |\n| `/v1/openclaw/version`       | GET  | 获取 OpenClaw 二进制版本号                                    |\n| `/v1/openclaw/dashboard-url` | GET  | **计算并返回** 龙虾面板 (External Dashboard) 的访问地址 |\n| `/v1/gateway/start`          | POST | 启动小龙虾网关进程                                            |\n| `/v1/gateway/stop`           | POST | 停止小龙虾网关进程                                            |\n| `/v1/gateway/restart`        | POST | 重启网关 (**异步接口**，返回 `taskId`)                |\n| `/v1/tasks/status`           | GET  | 查询异步任务执行进度 (Query:`?taskId=...`)                  |\n| `/v1/stats/health`           | GET  | 获取近 24 小时心跳延迟统计数据                                |\n| `/v1/system/info`            | GET  | 获取服务器 CPU、内存、磁盘负载及系统信息                      |\n| `/v1/system/events`          | GET  | 获取 Buddy 系统级审计日志与操作事件                           |\n\n#### 💬 在线聊天 (Online Chat)\n\n| 路径                                 | 方法         | 功能说明                                    |\n| :----------------------------------- | :----------- | :------------------------------------------ |\n| `/v1/openclaw/chat/completions`    | POST         | **OpenAI 兼容流式对话服务**           |\n| `/v1/openclaw/chat/status`         | GET          | 检查网关是否已开启 `chatCompletions` 配置 |\n| `/v1/openclaw/chat/enable`         | POST         | 一键开启网关的 Chat Completions 支持        |\n| `/v1/openclaw/chat/quick-commands` | GET/POST/DEL | 管理对话实验室的快捷指令话术                |\n| `/v1/openclaw/sessions`            | GET          | 获取当前网关活跃的会话详情与上下文使用情况  |\n\n#### 🤖 虾兵蟹将 (Bots \u0026 Models)\n\n| 路径                                   | 方法     | 功能说明                                                |\n| :------------------------------------- | :------- | :------------------------------------------------------ |\n| `/v1/openclaw/bots-models`           | GET      | 获取机器人/模型资产清单 (`?refresh=true` 强制同步)    |\n| `/v1/openclaw/bots/add`              | POST     | 在线创建并初始化新的小龙虾机器人 (隔离工作区)           |\n| `/v1/openclaw/bots/update`           | POST     | 批量更新现有机器人的详细配置参数                        |\n| `/v1/openclaw/bots/delete`           | POST     | 彻底移除机器人并清理相关数据目录                        |\n| `/v1/openclaw/bots/top`              | GET      | 获取当前活跃度最高的机器人排行清单                      |\n| `/v1/openclaw/bots/set-identity`     | POST     | 修改机器人的显示名称 (Identity Name)                    |\n| `/v1/openclaw/bots/set-model`        | POST     | 在线修改并覆盖指定机器人的默认模型分配                  |\n| `/v1/openclaw/bots/file`             | GET/POST | **直接读写** 机器人的原始配置文件内容 (`.json`) |\n| `/v1/openclaw/experts`               | GET      | 访问专家市场，获取官方预设的 Bot 模板                   |\n| `/v1/openclaw/bots/template`         | POST     | 基于专家模板快速克隆并创建一个新 Bot                    |\n| `/v1/openclaw/models/config`         | GET      | 获取当前所有已配置的模型渠道及其详情                    |\n| `/v1/openclaw/models/test-direct`    | POST     | **连通性测试**：后端直连模型渠道测试延迟 (TTFT)   |\n| `/v1/openclaw/models/provider`       | POST     | 动态添加 API 提供商配置 (BaseURL/ApiKey/API型)          |\n| `/v1/openclaw/models/provider/model` | POST/DEL | 向特定渠道追加或删除模型定义                            |\n| `/v1/openclaw/models/set-default`    | POST     | 设定系统全局默认模型                                    |\n\n#### 🕹️ 技能与插件 (Skills \u0026 Plugins)\n\n| 路径                            | 方法   | 功能说明                                            |\n| :------------------------------ | :----- | :-------------------------------------------------- |\n| `/v1/openclaw/skills`         | GET    | 获取已安装的技能列表与详情 (`?refresh=true` 同步) |\n| `/v1/openclaw/skills/:name`   | DELETE | 卸载特定的小龙虾技能插件                            |\n| `/v1/openclaw/skills/reload`  | POST   | 重新加载系统规则与所有技能插件                      |\n| `/v1/openclaw/plugins`        | GET    | 获取底层功能插件 (如 WeChat, Telegram) 状态清单     |\n| `/v1/openclaw/plugins/enable` | POST   | 启用特定的底层功能插件                              |\n| `/v1/openclaw/plugins/reload` | POST   | 热重载插件配置而无需重启网关                        |\n| `/v1/openclaw/plugins/:id`    | DELETE | 卸载或禁用指定的底层插件                            |\n\n#### 🔌 渠道绑定与实时流 (Channels \u0026 Streams)\n\n| 路径                         | 方法 | 功能说明                                                 |\n| :--------------------------- | :--- | :------------------------------------------------------- |\n| `/v1/wechat/config/status` | GET  | 获取当前微信渠道的绑定状态与配置                         |\n| `/v1/wechat/install`       | POST | 触发微信控制插件的自动化下载与安装                       |\n| `/v1/wechat/qrcode`        | GET  | **流式获取** 微信插件登录二维码 (支持实时捕获)     |\n| `/v1/ws/logs`              | WS   | **WebSocket 日志流**：实时追踪系统运行日志 (Xterm) |\n| `/v1/ws/tui`               | WS   | **远程终端 (PTY)**：接管网关交互式控制台交互       |\n| `/v1/proxy/*path`          | Any  | **反向代理**：透传并解开原生 UI 的安全策略限制     |\n\n#### 📱 设备中心 (Devices)\n\n| 路径                             | 方法 | 功能说明                                  |\n| :------------------------------- | :--- | :---------------------------------------- |\n| `/v1/openclaw/devices`         | GET  | 获取设备列表 (包含待处理请求与已配对设备) |\n| `/v1/openclaw/devices/approve` | POST | 在线批准新设备的接入请求                  |\n\n#### 🩺 自愈管理 (Self-Healing)\n\n| 路径                          | 方法     | 功能说明                                |\n| :---------------------------- | :------- | :-------------------------------------- |\n| `/v1/heal/events`           | GET      | 查询历史自愈事件、原因及处置结果        |\n| `/v1/settings/self-healing` | GET/POST | 开启或禁用 Buddy 自动巡检与故障恢复功能 |\n\n### ⚙️ 配置文件说明 (env)\n\n```env\nWEB_PORT=3000                 # Guardian 面板端口\nBUDDY_TOKEN=\"sk-xxx\"       # 访问面板所需的令牌\nHEALTH_PORT=18789             # 小龙虾 (OpenClaw) 监听的地址\nOPENCLAW_CONFIG_DIR=\"~/.openclaw\" # 配置目录\nCHECK_INTERVAL_SECONDS=30     # 监控扫描频率 (秒)\nEXTERNAL_DASHBOARD_URL=\"https://claw.yourdomain.com\" # 外部访问前缀 (用于透传 UI)\n```\n\n## 🔌 外部集成与嵌入 (Embed Support)\n\n**OpenClaw Buddy** 支持高度灵活的外部系统集成，您可以将特定的功能模块（如在线聊天）以 **Standalone (独立模式)** 嵌入到您的业务系统、大屏或其他 Iframe 容器中。\n\n### 核心参数 (Query Parameters)\n\n通过 URL 参数，您可以精确控制嵌入页面的行为，而无需手动登录或导航：\n\n| 参数      | 必填 | 功能说明                                                                                                                                            | 示例                        |\n| :-------- | :---: | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------- |\n| `embed` |  是  | 设为 `true` 开启**纯净模式**，隐藏侧边栏与页头，仅保留核心业务区                                                                            | `?embed=true`             |\n| `page`  |  否  | 指定进入的页面，目前支持 `chat` (在线聊天)                                                                                                        | `?page=chat`              |\n| `token` | 是/否 | **URL 自动鉴权**。传入后系统自动记录并登录，解决跨域/嵌入后的鉴权问题                                                                         | `?token=YOUR_BUDDY_TOKEN` |\n| `bot`   |  否  | 在聊天页自动选择指定的**Bot ID**                                                                                                              | `?bot=my_gpt4_bot`        |\n| `user`  |  否  | 在界面上标识当前对话用户的身份，用于辅助上下文追踪，\u003cbr /\u003e如果你要一个用户不同的会话，你可以设计为 user-sessionid 格式，\u003cbr /\u003e比如： randy-sidxxxxx | `?user=Randy`             |\n\n### 嵌入示例 (Iframe)\n\n要在您的网页中嵌入一个“预设了机器人、自动登录且隐藏侧边栏”的聊天窗口，可以使用如下代码：\n\n```html\n\u003ciframe \n  src=\"http://your-buddy-ip:3000/?page=chat\u0026embed=true\u0026token=sk-xxx\u0026bot=my-bot-id\" \n  width=\"100%\" \n  height=\"600\" \n  frameborder=\"0\"\n\u003e\u003c/iframe\u003e\n```\n\n\u003e [!TIP]\n\u003e 您也可以直接在 **在线聊天** 页面的右上角点击 **“获取嵌入代码”** 按钮，系统会自动为您生成包含当前 Token 与已选 Bot 的完整 `\u003ciframe\u003e` 代码。\n\n## 📄 开源协议\n\n本项目基于 **MIT License** 开源，由 randychen 维护。联系我：[cexlong@gmail.com](mailto:cexlong@gmail.com)\n\n---\n\n### 💬 联系与交流\n\n如果您在使用过程中有任何疑问、功能建议，或者想要获取更多关于 OpenClaw 的技术资讯，欢迎扫码关注我们的 **微信公众号**：\n\n\u003cimg src=\"docs/images/%20gzh.png\" width=\"200\" alt=\"微信公众号\" /\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frandychen1985%2Fopenclaw-buddy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frandychen1985%2Fopenclaw-buddy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frandychen1985%2Fopenclaw-buddy/lists"}