# AI智能体看板管理

`看板` `AI智能体` `任务管理` `实时监控` `MCP`

# 🦞 Claw Control

> **AI 智能体的看板系统** - 优雅地协调你的 AI 团队

🌐 **[www.clawcontrol.xyz](https://www.clawcontrol.xyz)** — 在线演示与文档

[![Skills.sh](https://img.shields.io/badge/npx_skills_add-Install-coral?style=flat-square&logo=npm)](https://skills.sh)
[![GitHub stars](https://img.shields.io/github/stars/adarshmishra07/claw-control?style=flat-square&logo=github)](https://github.com/adarshmishra07/claw-control/stargazers)
[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/deploy/claw-control?referralCode=VsZvQs&utm_medium=integration&utm_source=template&utm_campaign=generic)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://opensource.org/licenses/MIT)
![Status](https://img.shields.io/badge/status-alpha-orange?style=flat-square)

> 🚧 **持续开发中** — 我们正在不断改进此工具！欢迎反馈和贡献。

Claw Control 是一个美观的实时任务控制面板，用于管理 AI 智能体工作流。通过直观的看板界面追踪任务、监控智能体状态，并以实时更新方式协调你的 AI 团队。

<p align="center">
  <img src="docs/images/dashboard.png" alt="控制台概览" width="800">
  <br>
  <em>带有智能体状态和实时活动流的看板</em>
</p>

---

## 🚀 快速开始

### 第一步：安装技能

```bash
npx skills add adarshmishra07/claw-control
```

这将教会你的 AI 智能体如何使用 Claw Control。

### 第二步：让智能体引导你

你的智能体将引导你完成：
- 🚀 **部署** - Railway 一键部署、Docker 或手动设置
- 🎨 **主题选择** - 龙珠Z、海贼王、漫威等多种主题
- ⚙️ **配置** - AGENTS.md 设置、API 连接
- 🧠 **记忆集成** - 可选的 Supermemory + QMD 设置

**就这么简单！** 安装技能，剩下的交给智能体处理。

---

<details>
<summary>📦 <strong>部署选项</strong>（技能将引导你完成这些步骤）</summary>

> **注意：** 部署完成后，你仍需要将技能安装到 AI 智能体：
> ```bash
> npx skills add adarshmishra07/claw-control
> ```
> 该技能会教智能体如何使用 Claw Control。

### Railway（一键部署）

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/deploy/claw-control?referralCode=VsZvQs&utm_medium=integration&utm_source=template&utm_campaign=generic)

**点击 → 等待 2 分钟 → 完成！** Railway 自动配置 PostgreSQL、后端和前端。

---

### Docker Compose

```bash
git clone https://github.com/adarshmishra07/claw-control
cd claw-control
docker compose up -d
```

打开 **http://localhost:5173** 即可使用！

<details>
<summary>💡 使用 SQLite 而非 PostgreSQL？</summary>

```bash
docker compose -f docker-compose.yml -f docker-compose.sqlite.yml up -d --scale db=0
```

</details>

---

### 手动安装

```bash
# 克隆仓库
git clone https://github.com/adarshmishra07/claw-control
cd claw-control

# 后端（终端 1）
cd packages/backend
npm install
echo "DATABASE_URL=sqlite:./data/claw-control.db" > .env
npm run migrate
npm run dev

# 前端（终端 2）
cd packages/frontend
npm install
echo "VITE_API_URL=http://localhost:3001" > .env
npm run dev
```

打开 **http://localhost:5173** 🚀

</details>

---

## 🔧 配置

### 环境变量

**后端（`packages/backend/.env`）**
```env
# 数据库 - SQLite（本地开发）
DATABASE_URL=sqlite:./data/claw-control.db

# 或 PostgreSQL（生产环境）
DATABASE_URL=postgresql://user:pass@localhost:5432/claw_control

# 服务器
PORT=3001

# 认证（可选 - 留空则开放访问）
API_KEY=your-secret-key-here
```

**前端（`packages/frontend/.env`）** ⚠️ **必填**
```env
# 必填：后端 API 的 URL
API_URL=http://localhost:3001

# 生产环境请使用已部署的后端地址：
# API_URL=https://your-backend.railway.app
```

> **注意：** 前端必须设置 `API_URL` 才能连接后端。否则控制台将无法加载数据。

### API 认证（可选）

默认情况下，Claw Control 以**开放模式**运行，非常适合本地开发。

生产环境中，设置 `API_KEY` 以要求写操作进行认证：

| 模式 | API_KEY 值 | 行为 |
|------|-----------|------|
| **开放** | 空/未设置 | 所有操作公开 |
| **受保护** | 已设置 | POST/PUT/DELETE 需要认证 |

---

### 智能体配置

在 `config/agents.yaml` 中定义你的智能体团队：

```yaml
agents:
  - name: "悟空"
    role: "协调者"
    avatar: "🥋"
    description: "主协调者 - 分配任务"

  - name: "贝吉塔"
    role: "后端"
    avatar: "💪"
    description: "后端专家 - API、数据库"

  - name: "布尔玛"
    role: "运维"
    avatar: "🔧"
    description: "运维与前端 - 基础设施、UI"
```

更多示例见 `config/examples/`。

---

## 🤖 连接 AI 智能体

你的 AI 智能体通过 REST API 和 SSE 连接到 Claw Control 以获取实时更新。

### REST API 端点

| 操作 | 方法 | 端点 |
|------|------|------|
| 列出任务 | `GET` | `/api/tasks` |
| 创建任务 | `POST` | `/api/tasks` |
| 更新任务 | `PUT` | `/api/tasks/:id` |
| 列出智能体 | `GET` | `/api/agents` |
| 更新智能体 | `PUT` | `/api/agents/:id` |
| 发布消息 | `POST` | `/api/messages` |

### 示例：智能体报告工作状态

```bash
# 将智能体状态更新为"工作中"
curl -X PUT http://localhost:3001/api/agents/1 \
  -H "Content-Type: application/json" \
  -d '{"status": "working"}'

# 向活动流发布消息
curl -X POST http://localhost:3001/api/messages \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 1,
    "message": "开始任务：部署到生产环境"
  }'
```

### 示例：创建任务

```bash
curl -X POST http://localhost:3001/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "修复登录 Bug",
    "description": "有效 Token 收到 401 错误",
    "status": "todo",
    "priority": "high"
  }'
```

### 带认证的请求

如果设置了 `API_KEY`，写操作需包含认证信息：

```bash
curl -X POST http://localhost:3001/api/tasks \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "新任务"}'
```

### 使用 SSE 获取实时更新

连接到事件流以接收实时更新：

```bash
curl -N http://localhost:3001/api/stream
```

**推送的事件类型：**
- `task-created` / `task-updated` / `task-deleted`
- `agent-updated`
- `message-created`

### JavaScript 示例

```javascript
// 更新智能体状态
await fetch('http://localhost:3001/api/agents/1', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ status: 'working' })
});

// 监听实时更新
const eventSource = new EventSource('http://localhost:3001/api/stream');
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('更新：', data);
};
```

### OpenClaw 集成脚本

对于 OpenClaw/Claude 智能体，复制辅助脚本：

```bash
cp templates/scripts/update_dashboard.js scripts/
export CLAW_CONTROL_URL=https://your-backend.railway.app
```

然后智能体可以通过以下方式更新状态：

```bash
node scripts/update_dashboard.js --agent "布尔玛" --status "working" --message "开始部署"
```

📖 完整指南：[docs/openclaw-integration.md](docs/openclaw-integration.md)

---

## ✨ 功能特性

- **📋 看板** - 支持拖拽的任务管理，实时同步
- **🤖 智能体追踪** - 监控智能体状态（空闲/工作中/错误）
- **💬 活动流** - 智能体消息实时流
- **🔄 SSE 更新** - 无需轮询的实时更新
- **📱 移动端适配** - 支持任意设备
- **🎨 赛博朋克 UI** - 时尚暗色主题与发光效果
- **🔌 MCP 集成** - 原生模型上下文协议支持
- **🗄️ 灵活存储** - SQLite（开发）或 PostgreSQL（生产）

---

## 🏗️ 架构

```
┌─────────────────────────────────────────────────────────────┐
│                           客户端                             │
├───────────┬───────────┬───────────┬────────────────────────┤
│  控制面板  │  AI智能体  │  MCP工具  │     外部 Webhook       │
│  (React)  │ (REST API)│  (stdio)  │  (GitHub 等)           │
└─────┬─────┴─────┬─────┴─────┬─────┴──────────┬─────────────┘
      │           │           │                │
      └───────────┴─────┬─────┴────────────────┘
                        │
                ┌───────▼────────┐
                │    API 服务器   │
                │   (Fastify)    │
                ├────────────────┤
                │ • REST API     │
                │ • SSE 流       │
                │ • 认证层       │
                └───────┬────────┘
                        │
                ┌───────▼────────┐
                │     数据库      │
                ├────────────────┤
                │ SQLite │ Postgres │
                └────────────────┘
```

### 技术栈

| 层级 | 技术 |
|------|------|
| **前端** | React 19、TypeScript、Vite、TailwindCSS |
| **后端** | Node.js、Fastify 5、Server-Sent Events |
| **数据库** | SQLite（开发）/ PostgreSQL（生产）|
| **AI 集成** | MCP Server、REST API |
| **部署** | Docker、Railway |

---

## 📚 完整文档

- **[Railway 部署指南](docs/railway-template.md)** - 详细的 Railway 设置说明
- **[OpenClaw 集成](docs/openclaw-integration.md)** - 连接 AI 智能体
- **[API 参考](http://localhost:3001/documentation)** - Swagger UI（本地运行时可用）
- **[贡献指南](CONTRIBUTING.md)** - 如何参与贡献

---

## 📦 项目结构

```
claw-control/
├── packages/
│   ├── frontend/          # React + Vite + TailwindCSS
│   │   ├── src/
│   │   │   ├── components/  # UI 组件
│   │   │   ├── hooks/       # 自定义 React Hooks
│   │   │   └── types/       # TypeScript 类型定义
│   │   └── package.json
│   │
│   └── backend/           # Fastify + SQLite/PostgreSQL
│       ├── src/
│       │   ├── server.js      # 主 API 服务器
│       │   ├── db-adapter.js  # 数据库抽象层
│       │   ├── mcp-server.js  # MCP 集成
│       │   └── migrate.js     # 数据库迁移
│       └── package.json
│
├── config/                    # 配置文件
│   ├── agents.yaml            # 智能体定义
│   └── examples/              # 示例配置
├── docker-compose.yml         # 完整栈（PostgreSQL）
├── docker-compose.sqlite.yml  # SQLite 覆盖配置
└── templates/scripts/         # 集成脚本
```

---

## 🤝 参与贡献

欢迎贡献！详情请参阅我们的[贡献指南](CONTRIBUTING.md)。

---

## 📄 许可证

MIT 许可证 - 详见 [LICENSE](LICENSE)。

---

<p align="center">
  由 <a href="https://github.com/adarshmishra07">OpenClaw</a> 团队用 🦞 制作
</p>