# openclaw-manager

**Repository Path**: sunjmj/openclaw-manager

## Basic Information

- **Project Name**: openclaw-manager
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🦞 OpenClaw Manager

<div align="center">

![OpenClaw Manager](https://img.shields.io/badge/OpenClaw-Manager-blue?style=for-the-badge)
![React](https://img.shields.io/badge/React-18-61dafb?style=for-the-badge&logo=react)
![Tailwind CSS](https://img.shields.io/badge/Tailwind-CSS-38bdf8?style=for-the-badge&logo=tailwind-css)
![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)

**现代化的 OpenClaw 多 Gateway 管理界面**

[功能特性](#-功能特性) • [快速开始](#-快速开始) • [使用说明](#-使用说明) • [API 文档](#-api-文档)

</div>

---

## 📖 简介

OpenClaw Manager 是一个基于 React + Tailwind CSS 的现代化 Web 管理界面，用于管理多个 OpenClaw Gateway 实例。它提供了直观的可视化界面，让你可以轻松监控和控制所有 Gateway 服务。

### 为什么需要这个工具？

当你使用 OpenClaw 的多 Gateway 架构（每个飞书机器人对应一个独立的 Gateway 实例）时，需要一个统一的管理界面来：
- 📊 实时监控所有 Gateway 的运行状态
- 🎮 一键启动/停止/重启服务
- ⚙️ 配置 launchd 保活服务
- 📝 查看服务日志
- 💻 美观的现代化界面

## ✨ 功能特性

### 核心功能

- ✅ **自动发现 Gateway** - 自动扫描 `~/.openclaw-*` 目录，无需手动配置
- ✅ **Gateway CRUD 管理** - 创建、编辑、删除 Gateway 实例
- ✅ **实时状态监控** - 自动检测所有 Gateway 的运行状态（每 10 秒刷新）
- ✅ **服务控制** - 一键启动/停止/重启所有或单个服务
- ✅ **保活配置** - 一键配置 launchd 保活，支持开机自启和崩溃重启
- ✅ **实时日志查看器** - 黑色终端风格，自动刷新，支持自动滚动
- ✅ **自定义模型配置** - 支持配置任意 OpenAI-compatible API
- ✅ **SOUL.md 人格编辑** - 可视化编辑 Agent 人格设定
- ✅ **飞书账号管理** - 配置飞书 App ID 和 Secret
- ✅ **美观界面** - 现代化设计，响应式布局，支持移动端

### 技术亮点

- ⚡️ **快速开发** - Vite 提供极速的开发体验
- 🎨 **现代设计** - Tailwind CSS 打造精美界面
- 🔄 **前后端分离** - React 前端 + Express 后端
- 📱 **响应式布局** - 完美支持桌面和移动设备
- 🚀 **高性能** - 异步 API 调用，并行状态检测
- 🔍 **智能发现** - 自动扫描配置，支持缓存机制

## 🖼️ 界面预览

### 主界面
- 顶部操作栏：配置保活、启动/停止/重启所有服务
- 服务卡片：显示每个 Gateway 的状态、端口、模型信息
- 系统信息：内存占用、运行服务数、自动刷新状态

### 服务卡片
每个服务卡片包含：
- 🟢 运行状态指示灯
- 📝 服务名称和 ID
- 🔌 端口号
- 🤖 使用的 AI 模型
- 🎛️ 快捷操作按钮

## 🚀 快速开始

### 前置要求

- Node.js >= 16
- npm 或 yarn
- OpenClaw 已安装并配置好多 Gateway

### 安装

```bash
# 克隆项目
git clone https://github.com/xianyu110/openclaw-manager.git
cd openclaw-manager

# 安装依赖
npm install
```

### 配置

无需手动配置！应用会自动发现所有 `~/.openclaw-*` 目录下的 Gateway 实例。

如果你还没有配置 Gateway，可以通过界面直接创建：
1. 启动应用
2. 点击"➕ 新建 Gateway"按钮
3. 填写配置信息
4. 保存即可

### 启动

```bash
# 启动开发服务器（前端 + 后端）
npm start
```

应用将在以下地址启动：
- 前端: http://localhost:3000
- 后端 API: http://localhost:3001

## 📚 使用说明

### 首次使用

1. **启动应用**
   ```bash
   npm start
   ```

2. **打开浏览器**
   访问 http://localhost:3000

3. **配置保活服务**
   - 点击"⚙️ 配置保活"按钮
   - 等待配置完成
   - 服务将自动开机启动并在崩溃后重启

### 日常操作

#### 创建新 Gateway
1. 点击"➕ 新建 Gateway"按钮
2. 填写基本信息：
   - Profile ID（唯一标识）
   - 机器人名称
   - 端口号
   - Agent ID
3. 配置模型：
   - 选择预设模型，或
   - 使用自定义模型（需填写 Provider、模型 ID、Base URL、API Key）
4. 配置飞书账号：
   - App ID
   - App Secret
5. （可选）编辑 SOUL.md 人格设定
6. 点击"创建"

#### 编辑 Gateway
1. 点击服务卡片中的"✏️ 编辑"按钮
2. 修改配置信息
3. 点击"保存"

#### 删除 Gateway
1. 点击服务卡片中的"🗑️ 删除"按钮
2. 确认删除
3. 配置目录和 launchd 服务将被完全移除

#### 查看服务状态
- 界面会自动每 10 秒刷新状态
- 点击"🔍 重新扫描"按钮手动刷新并重新发现 Gateway
- 绿色指示灯表示运行中，红色表示已停止

#### 控制服务
- **启动所有**: 一键启动所有 Gateway
- **停止所有**: 一键停止所有 Gateway
- **重启所有**: 一键重启所有 Gateway
- **单个控制**: 在服务卡片中点击"▶️ 启动"、"⏹️ 停止"或"🔄 重启"按钮

#### 查看日志
1. 点击服务卡片中的"📝 日志"按钮
2. 黑色终端风格界面显示最近 100 行日志
3. 每 2 秒自动刷新
4. 支持自动滚动到底部
5. 点击"清空显示"清除当前显示

## 🔧 开发

### 项目结构

```
openclaw-manager/
├── src/
│   ├── App.jsx              # 主应用组件
│   ├── GatewayModal.jsx     # Gateway 创建/编辑对话框
│   ├── LogViewer.jsx        # 日志查看器组件
│   ├── main.jsx             # React 入口
│   └── index.css            # 全局样式
├── server.js                # Express 后端 API
├── index.html               # HTML 模板
├── vite.config.js           # Vite 配置
├── tailwind.config.js       # Tailwind 配置
├── postcss.config.js        # PostCSS 配置
├── package.json             # 项目配置
├── FEATURES.md              # 功能详细说明
└── README.md                # 项目文档
```

### 开发模式

```bash
# 只启动前端（需要手动启动后端）
npm run dev

# 只启动后端
npm run server

# 同时启动前后端（推荐）
npm start
```

### 构建生产版本

```bash
# 构建前端
npm run build

# 预览构建结果
npm run preview
```

## 📡 API 文档

### 自动发现

- `GET /api/status` - 获取所有服务的状态信息（自动发现）
- `POST /api/refresh-discovery` - 刷新服务发现缓存

### Gateway CRUD

- `GET /api/gateway/:serviceId` - 获取单个 Gateway 配置
- `GET /api/gateway/:serviceId/soul` - 获取 Gateway 的 SOUL.md 内容
- `POST /api/gateway` - 创建新的 Gateway
- `PUT /api/gateway/:serviceId` - 更新 Gateway 配置
- `DELETE /api/gateway/:serviceId` - 删除 Gateway

**创建 Gateway 请求示例:**
```json
{
  "profileId": "my-bot",
  "botName": "我的机器人",
  "port": 18793,
  "agentId": "my-agent",
  "modelId": "Claude Sonnet 4.5",
  "appId": "cli_xxxxx",
  "appSecret": "xxxxx",
  "soulContent": "# Agent 人格设定\n..."
}
```

**自定义模型请求示例:**
```json
{
  "profileId": "my-bot",
  "botName": "我的机器人",
  "port": 18793,
  "agentId": "my-agent",
  "useCustomModel": true,
  "customProvider": "my-provider",
  "customModel": "my-model-id",
  "customBaseUrl": "https://api.example.com/v1",
  "customApiKey": "sk-xxxxx",
  "appId": "cli_xxxxx",
  "appSecret": "xxxxx"
}
```

### 批量操作

- `POST /api/start-all` - 启动所有 Gateway 服务
- `POST /api/stop-all` - 停止所有 Gateway 服务
- `POST /api/restart-all` - 重启所有 Gateway 服务
- `POST /api/setup-launchd` - 配置 launchd 保活服务

### 单个服务操作

- `POST /api/start/:serviceId` - 启动指定的 Gateway 服务
- `POST /api/stop/:serviceId` - 停止指定的 Gateway 服务
- `POST /api/restart/:serviceId` - 重启指定的 Gateway 服务
- `GET /api/logs/:serviceId` - 获取指定服务的日志（最近 100 行）

### 辅助接口

- `GET /api/agents` - 获取可用的 Agent 列表
- `GET /api/models` - 获取可用的模型列表

## 🛠️ 故障排查

### 后端无法连接

```bash
# 检查端口占用
lsof -i :3001

# 手动启动后端
npm run server
```

### 前端无法访问

```bash
# 检查端口占用
lsof -i :3000

# 清除缓存重新启动
rm -rf node_modules/.vite
npm start
```

### 服务控制失败

确保管理脚本存在并有执行权限：

```bash
# 检查脚本
ls -la ~/your-openclaw-scripts/*.sh

# 添加执行权限
chmod +x ~/your-openclaw-scripts/*.sh

# 更新 server.js 中的脚本路径
```

## 🎯 高级配置

### 自定义模型配置

支持任意 OpenAI-compatible API：

1. 在创建/编辑 Gateway 时选择"使用自定义模型"
2. 填写以下信息：
   - **Provider 名称**: 自定义的 provider ID（如 `my-api`）
   - **模型 ID**: 模型的标识符（如 `gpt-4`）
   - **Base URL**: API 端点（如 `https://api.example.com/v1`）
   - **API Key**: 你的 API 密钥

系统会自动在 `openclaw.json` 的 `models.providers` 中创建配置。

### SOUL.md 人格编辑

SOUL.md 文件定义了 Agent 的人格特征：

```markdown
# Agent 人格设定

## 角色定位
你是一个专业的 AI 助手。

## 性格特点
- 友好、专业
- 乐于助人
- 思维清晰

## 工作方式
- 认真倾听用户需求
- 提供准确的信息
- 保持礼貌和耐心
```

文件保存在 `~/.openclaw-{profile}/agent-configs/{agentId}/SOUL.md`

### 修改刷新间隔

编辑 `src/App.jsx` 中的刷新间隔（毫秒）：

```javascript
const interval = setInterval(checkStatus, 10000) // 状态刷新间隔
```

编辑 `src/LogViewer.jsx` 中的日志刷新间隔：

```javascript
const interval = setInterval(fetchLogs, 2000) // 日志刷新间隔
```

### 修改发现缓存时间

编辑 `server.js` 中的缓存 TTL：

```javascript
const DISCOVERY_CACHE_TTL = 60000 // 1 分钟，改为你想要的时间
```

## 🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

### 如何贡献

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📝 更新日志

### v1.2.0 (2026-02-13)

- ✨ 新增实时日志查看器（黑色终端风格）
- ✨ 新增单个 Gateway 控制功能
- 🐛 修复配置文件更新逻辑
- 🐛 修复模型显示问题（支持对象格式）

### v1.1.0 (2026-02-13)

- ✨ 新增 Gateway CRUD 管理功能
- ✨ 新增自定义模型配置
- ✨ 新增 SOUL.md 人格编辑器
- ✨ 新增飞书账号配置
- 🔍 新增自动发现 Gateway 功能
- ⚡️ 添加发现缓存机制

### v1.0.0 (2026-02-13)

- ✨ 初始版本发布
- ✅ 实时状态监控
- ✅ 服务控制功能
- ✅ 保活配置
- ✅ 响应式界面

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 🙏 致谢

- [OpenClaw](https://github.com/openclaw/openclaw) - 强大的 AI Agent 框架
- [React](https://react.dev/) - 用户界面库
- [Tailwind CSS](https://tailwindcss.com/) - CSS 框架
- [Vite](https://vitejs.dev/) - 前端构建工具
- [Express](https://expressjs.com/) - Node.js Web 框架

## 📮 联系方式

- 作者: Maynor
- GitHub: [@xianyu110](https://github.com/xianyu110)
- 项目地址: [openclaw-manager](https://github.com/xianyu110/openclaw-manager)

---

<div align="center">

**[⬆ 回到顶部](#-openclaw-manager)**

Made with ❤️ by Maynor

</div>