# ocm

**Repository Path**: bukasi/ocm

## Basic Information

- **Project Name**: ocm
- **Description**: OCM龙虾管理平台，支持脚本上传，openclaw的启动，停止，重启，状态检测，调用技能扩展等功能
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-21
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🦞 OCM - OpenClaw Manager 龙虾管理平台

> 轻量级 OpenClaw 生命周期管理平台 — 用的时候再开，省 Token，省心。脚本智能投喂，让 AI 知道怎么用。

[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=flat&logo=python)](https://python.org/)
[![React](https://img.shields.io/badge/React-18+-61DAFB?style=flat&logo=react)](https://react.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.4+-3178C6?style=flat&logo=typescript)](https://typescriptlang.org/)
[![国密](https://img.shields.io/badge/国密-SM2-red?style=flat)](https://www.oscca.gov.cn/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## 🤔 为什么需要 OCM

[OpenClaw](https://github.com/openclaw/openclaw) 是一款开源的自托管 AI Agent 网关平台，但它长期运行会持续消耗 LLM Token。对于个人用户和小团队，**用的时候再开** 才是经济选择。

OCM 让你：

- 🕹️ **一键启停** — 启动、停止、重启 OpenClaw，手机上也能操作
- 📜 **脚本管理** — 上传 Python/Shell 脚本，编辑功能描述
- 🧠 **智能投喂** — 脚本自动投喂给 OpenClaw，让 AI 知道每个脚本的用法和作用
- 📊 **实时监控** — OpenClaw 状态、健康检查、心跳检测，一目了然
- 📋 **日志查看** — 实时日志流、历史日志、级别过滤、关键词搜索
- ⏱️ **心跳配置** — 自定义状态检测、健康检查间隔时长
- 🔐 **国密安全** — SM2 前端密码加密
- 🐧 **宿主机部署** — 直接部署在 Linux 宿主机，通过 CLI 控制 OpenClaw

## ✨ 核心功能

| 功能 | 描述 |
|------|------|
| 🦞 OpenClaw 生命周期管理 | 启动 / 停止 / 重启 / 状态检测 / 健康检查 (openclaw doctor) |
| ⏱️ 心跳检查（可配置） | 进程/端口/健康检查/资源监控间隔均可自定义 |
| 📜 脚本上传与管理 | 支持 .py / .sh 上传、在线编辑(CodeMirror 6)、功能描述，删除时联动清理 Skills |
| 🧠 智能脚本投喂 | 在线实时投喂 + 离线排队，OpenClaw 启动后自动投喂 |
| 📋 日志查看 | 实时 SSE 日志流 + 历史分页 + 过滤搜索 + 下载 |
| 📊 实时仪表盘 | 运行状态、投喂队列、资源占用 |
| 🔐 国密安全认证 | JWT + SM2 前端密码加密 |
| 📱 移动端适配 | 响应式设计，手机电脑都能用（44px 触摸目标、安全区域适配） |
| 🌓 主题切换 | 亮色 / 暗色 / 跟随系统（玻璃态高端设计） |
| ✨ 微交互动画 | 悬停缩放、Toast 通知、呼吸灯、入场动画 |
| 🐧 宿主机部署 | Nginx (前端) + systemd + gunicorn (后端) |

## 🏗️ 技术架构

```
前后端分离架构
├── 前端 SPA
│   ├── React 18 + TypeScript — 组件化、类型安全
│   ├── Vite 5 — 极速 HMR
│   ├── shadcn/ui + Radix UI — 高端设计感、无障碍
│   ├── Tailwind CSS — 玻璃态 + 微交互
│   ├── Zustand — 轻量状态管理
│   ├── React Query — 数据请求/缓存/轮询
│   ├── CodeMirror 6 — 代码编辑器
│   └── ESLint + Prettier — 代码规范
├── 后端 API
│   ├── Python (Flask) — 轻量 REST API
│   ├── SQLAlchemy — ORM
│   ├── JWT + 国密 SM2 — 认证加密
│   ├── APScheduler — 心跳检查 + 投喂队列
│   ├── gunicorn — 生产 WSGI
│   ├── ruff + mypy — 代码质量
│   └── Google 风格 docstring + 全面类型注解
├── 部署
│   ├── Nginx — 前端静态 + API 反代 + SSE 长连接
│   ├── systemd — 后端服务管理
│   └── subprocess — 调用 openclaw CLI
```

## 🚀 快速开始

### 开发模式

```bash
# 克隆仓库
git clone https://gitee.com/bukasi/ocm.git
cd ocm

# 安装依赖
make install

# 配置环境变量
cp api/.env.example api/.env

# 初始化数据库
make init-db

# 启动后端 (终端 1)
make dev-api    # http://localhost:5001

# 启动前端 (终端 2)
make dev-web    # http://localhost:3210
```

### 生产部署

```bash
# 1. 构建前端
make build

# 2. 配置环境变量
cp api/.env.example api/.env
# 编辑 .env，设置 OCM_SECRET_KEY 和 OCM_JWT_SECRET

# 3. 初始化数据库
cd api && source venv/bin/activate
flask db upgrade
flask seed   # 创建初始管理员

# 4. 配置 Nginx
sudo cp deploy/nginx/ocm.conf /etc/nginx/sites-available/ocm
sudo ln -s /etc/nginx/sites-available/ocm /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

# 5. 配置 systemd
sudo cp deploy/systemd/ocm-api.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable ocm-api
sudo systemctl start ocm-api

# 6. 创建日志目录
sudo mkdir -p /var/log/ocm
sudo chown www-data:www-data /var/log/ocm

# 或者使用一键部署
make deploy
```

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `OCM_SECRET_KEY` | Flask 密钥 | ⚠️ 生产必须修改 |
| `OCM_JWT_SECRET` | JWT 签名密钥 | ⚠️ 生产必须修改 |
| `OCM_ACCESS_TOKEN_EXPIRES` | Access Token 过期(秒) | `900` (15min) |
| `OCM_REFRESH_TOKEN_EXPIRES` | Refresh Token 过期(秒) | `604800` (7d) |
| `OCM_CLAW_PATH` | openclaw 可执行文件路径 | `/usr/local/bin/openclaw` |
| `OCM_CLAW_PORT` | OpenClaw Gateway 端口 | `3000` |
| `OCM_CLAW_CONFIG` | openclaw.json 路径 | `~/.openclaw/openclaw.json` |
| `OCM_CLAW_LOG_PATH` | OpenClaw 日志路径 | `~/.openclaw/logs/` |
| `OCM_SKILLS_PATH` | OpenClaw Skills 目录 | `~/.openclaw/skills` |
| `OCM_SCRIPTS_PATH` | 脚本存储路径 | `/opt/ocm/scripts/` |
| `OCM_CORS_ORIGINS` | 允许的前端域名 | `http://localhost:3210` |
| `OCM_HB_PROCESS_INTERVAL` | 进程检测间隔(秒) | `10` |
| `OCM_HB_PORT_INTERVAL` | 端口检测间隔(秒) | `30` |
| `OCM_HB_HEALTH_INTERVAL` | 健康检查间隔(秒) | `300` |
| `OCM_HB_RESOURCE_INTERVAL` | 资源监控间隔(秒) | `15` |
| `OCM_SM2_PRIVATE_KEY` | SM2 私钥（可选，首次自动生成） | — |
| `OCM_SM2_PUBLIC_KEY` | SM2 公钥（可选，首次自动生成） | — |
| `FLASK_ENV` | Flask 环境 | `development` |

完整环境变量列表见 [api/.env.example](api/.env.example)。

## 📖 文档

- [需求设计说明书](docs/requirements-design.md) — 完整的需求、架构、API 设计
- [开发任务清单](docs/dev-tasks.md) — 69 个开发任务 + 34 个测试任务

## 🗂️ 项目结构

```
ocm/
├── api/                  # 后端 (Flask REST API)
│   ├── app/
│   │   ├── models/       # 数据模型 (SQLAlchemy)
│   │   ├── views/        # API 视图 (Blueprint)
│   │   ├── services/     # 业务逻辑
│   │   │   ├── claw_service.py          # OpenClaw CLI 封装
│   │   │   ├── script_service.py        # 脚本管理
│   │   │   ├── script_feed_service.py   # 🧠 投喂服务
│   │   │   ├── heartbeat_service.py     # ⏱️ 心跳服务
│   │   │   └── log_service.py           # 📋 日志服务
│   │   ├── utils/        # 国密 SM2 + JWT + 安全
│   │   └── middleware/   # JWT 认证中间件
│   ├── migrations/       # 数据库迁移
│   ├── tests/            # 后端测试
│   ├── pyproject.toml    # ruff + mypy 配置
│   └── requirements.txt
│
├── web/                  # 前端 (React SPA)
│   ├── src/
│   │   ├── components/   # UI 组件 (shadcn/ui 风格)
│   │   │   ├── claw/     # OpenClaw 控制面板
│   │   │   ├── layout/   # 侧边栏 + Header + BottomNav
│   │   │   ├── logs/     # 日志流 + 历史日志
│   │   │   └── ui/       # Toast 通知等通用组件
│   │   ├── hooks/        # 自定义 Hooks
│   │   ├── lib/          # 工具 (Axios + SM2)
│   │   ├── stores/       # Zustand Stores (auth/theme)
│   │   ├── types/        # TypeScript 类型定义 (api.ts)
│   │   ├── pages/        # 页面路由
│   │   └── App.tsx
│   ├── public/
│   │   └── logo.svg      # 🦞 龙虾品牌 Logo
│   ├── eslint.config.js  # ESLint 配置
│   ├── .prettierrc       # Prettier 配置
│   └── package.json
│
├── deploy/               # 部署配置
│   ├── nginx/ocm.conf    # Nginx 配置
│   └── systemd/          # systemd 服务文件
├── docs/                 # 项目文档
├── Makefile              # 一键命令
└── README.md
```

## 🧠 脚本投喂 — OCM 的灵魂功能

脚本不仅是文件管理，还要让 OpenClaw "知道"每个脚本是什么、怎么用、什么时候该用。

```
上传脚本 + 填写功能描述
        │
        ├── OpenClaw 在线 → 立即投喂 → 生成 SKILL.md → 通知重载
        │
        └── OpenClaw 离线 → 排队等待 → 启动后自动投喂
```

每个脚本的 SKILL.md 包含：标题、描述、用法说明、参数、返回值、触发词，让 OpenClaw 能准确理解何时、如何使用该脚本。

## 🧭 开发路线

| 阶段 | 内容 | 状态 |
|------|------|------|
| 一 | 项目基础搭建（前后端） | ✅ 已完成 |
| 二 | JWT + 国密 SM2 认证系统 | ✅ 已完成 |
| 三 | OpenClaw CLI 管理 + 心跳检查 | ✅ 已完成 |
| 四 | 日志查看 | ✅ 已完成 |
| 五 | 仪表盘 | ✅ 已完成 |
| 六 | 脚本管理 + 智能投喂 | ✅ 已完成 |
| 七 | 配置与设置 | ✅ 已完成 |
| 八 | UI 精细化 | ✅ 已完成 |
| 九 | 宿主机部署与文档 | ✅ 已完成 |

## 🔄 代码规范

### Python 后端

- **Google 风格 docstring** — Args/Returns/Raises 完整文档
- **全面类型注解** — `Optional`/`dict`/`tuple`/`Callable`
- **双引号统一** — `ruff format` 自动格式化
- **废弃 API 修复** — `datetime.utcnow()` → `datetime.now(timezone.utc)`、`query.get()` → `db.session.get()`
- **代码质量** — `ruff check` + `mypy`

### 前端 TypeScript

- **完整类型定义** — `types/api.ts` 20+ 接口，消除 `any`
- **统一 Token 封装** — `tokenStorage` 工具
- **代码规范** — ESLint (`no-any` / `consistent-type-imports`) + Prettier
- **API 泛型** — `ApiResponse<T>` / `PaginatedData<T>`

### 开发流程

```
开发 → 自测 → 提测 → 测试通过 → 提交代码 → 更新文档 → 标记完成
```

**小步提交**：每个功能点开发完、测试通过后，立即提交到远程仓库。

## 🤝 参与贡献

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码
4. 新建 Pull Request

## 📄 License

[MIT](LICENSE)

---

<p align="center">
  🦞 OCM — 用的时候再开，脚本智能投喂，省 Token 省心
</p>