# CommanderClaw

**Repository Path**: darrenhoo/commander-claw

## Basic Information

- **Project Name**: CommanderClaw
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-17
- **Last Updated**: 2026-05-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CommanderClaw

[English](README.md) | [中文](README_zh.md)

多设备 Agent 协同框架，支持节点发现、Commander 选举、任务分发和 King 指令系统。

## 特性

- 🔌 **自动节点发现** - 自动注册和邻居同步
- 🗳️ **Bully 选举算法** - 分布式 Commander 选举
- 📋 **任务分发** - 任务分配与传承机制
- ⏱️ **通信限制** - 轮次/时间限制，循环检测
- 👑 **King 指令系统** - 实时干预能力
- 🔐 **Token 认证** - 安全的节点和 API 认证
- 🌐 **Web 控制台** - React 监控面板
- 🤖 **OpenClaw 集成** - 原生插件支持多 Agent 协同

## 快速开始

### 环境要求

- Go 1.21+
- Node.js 18+ (Web 控制台)

### 1. 配置服务端

在 `.commander-claw/config.yaml` 创建配置文件：

```yaml
server:
  host: "0.0.0.0"
  port: 8080

auth:
  enabled: true
  token: "your-secret-token"

logging:
  level: "info"
```

### 2. 启动服务端

```bash
# 编译运行
go build -o bin/server ./cmd/coordination-server
./bin/server

# 或直接运行
go run ./cmd/coordination-server
```

服务启动地址：`http://localhost:8080`

### 3. 启动 Web 控制台

```bash
cd web
npm install
npm run dev
```

控制台地址：`http://localhost:5173`

## 架构

```
┌─────────────────────────────────────┐
│            UI 层                    │  ← React 组件
├─────────────────────────────────────┤
│         运行时层                    │  ← WebSocket 处理器
├─────────────────────────────────────┤
│         服务层                      │  ← 业务逻辑
├─────────────────────────────────────┤
│         存储层                      │  ← 数据访问
├─────────────────────────────────────┤
│         配置层                      │  ← 配置管理
├─────────────────────────────────────┤
│         类型层                      │  ← 类型定义
└─────────────────────────────────────┘
```

## 认证

### Token 配置

单 Token 模式（简单）：

```yaml
auth:
  enabled: true
  token: "your-secret-token"
```

多 Token 模式（高级）：

```yaml
auth:
  enabled: true
  mode: "multi"
  tokens:
    - name: "openclaw-main"
      token: "token-for-main-agent"
      capabilities: ["ai-agent", "task-execution"]
    - name: "openclaw-worker"
      token: "token-for-worker"
      capabilities: ["task-execution"]
```

### WebSocket 认证

在 HELLO 消息中包含 token：

```json
{
  "type": "HELLO",
  "payload": {
    "name": "My Agent",
    "capabilities": ["coding"],
    "token": "your-secret-token"
  }
}
```

### REST API 认证

在 Authorization 头中包含 token：

```bash
curl -H "Authorization: Bearer your-secret-token" \
  http://localhost:8080/api/nodes
```

## OpenClaw 集成

CommanderClaw 提供原生 OpenClaw 插件，支持多 Agent 协同。

### 安装插件

```bash
openclaw plugins install @openclaw/commanderclaw
```

### 配置插件

添加到 `~/.openclaw/openclaw.json`：

```json
{
  "plugins": {
    "entries": {
      "commanderclaw": {
        "enabled": true,
        "config": {
          "serverUrl": "ws://localhost:8080/ws",
          "token": "your-secret-token",
          "deviceName": "OpenClaw Agent"
        }
      }
    }
  }
}
```

### 可用工具

| 工具 | 描述 |
|------|------|
| `commanderclaw_nodes` | 列出集群节点 |
| `commanderclaw_task` | 创建/管理任务 |
| `commanderclaw_status` | 检查连接状态 |
| `commanderclaw_command` | 发送 King 指令 |

详见 [OpenClaw 集成指南](docs/openclaw-integration.md)。

## WebSocket API

### 连接地址

```
ws://localhost:8080/ws
```

### 消息格式

```json
{
  "type": "HELLO",
  "id": "msg-uuid",
  "from": "node-id",
  "payload": {...},
  "timestamp": 1234567890000
}
```

### 消息类型

| 类型 | 方向 | 说明 |
|------|------|------|
| `HELLO` | 客户端 → 服务端 | 节点注册 |
| `HELLO_ACK` | 服务端 → 客户端 | 注册确认 |
| `HEARTBEAT` | 双向 | 心跳保活 |
| `PEER_LIST` | 服务端 → 客户端 | 节点列表同步 |
| `PEER_UPDATE` | 服务端 → 客户端 | 节点状态变更 |
| `TASK_NEW` | 客户端 → 服务端 | 创建任务 |
| `TASK_ASSIGN` | 服务端 → 客户端 | 任务分配 |
| `TASK_UPDATE` | 客户端 → 服务端 | 进度更新 |
| `TASK_RESULT` | 客户端 → 服务端 | 任务完成 |
| `KING_COMMAND` | King → 服务端 | King 干预指令 |
| `KING_REQUEST` | 服务端 → King | 请求 King 决策 |

## REST API

| 接口 | 方法 | 认证 | 说明 |
|------|------|------|------|
| `/api/health` | GET | 否 | 健康检查 |
| `/api/nodes` | GET | 是 | 节点列表 |
| `/api/tasks` | GET | 是 | 任务列表 |
| `/api/tasks` | POST | 是 | 创建任务 |
| `/api/tasks/{id}` | GET | 是 | 任务详情 |
| `/api/tasks/{id}/abort` | POST | 是 | 终止任务 |
| `/api/tasks/{id}/pause` | POST | 是 | 暂停任务 |
| `/api/tasks/{id}/resume` | POST | 是 | 恢复任务 |
| `/api/commander` | POST | 是 | 指定 Commander |

## 开发

### 运行测试

```bash
go test ./... -cover
```

### 编译

```bash
go build ./...
```

### 代码检查

```bash
golangci-lint run
```

## Docker 部署

```bash
docker-compose up -d
```

## 部署

- [Linux 部署指南](docs/deploy-linux.md) - systemd 原生部署
- [配置参考](docs/configuration.md) - 完整配置选项

## 文档

- [快速开始](docs/quick-start.md)
- [API 文档](docs/api.md)
- [架构设计](docs/ARCHITECTURE.md)
- [配置指南](docs/configuration.md)
- [OpenClaw 集成](docs/openclaw-integration.md)

## 项目结构

```
commander-claw/
├── cmd/
│   └── coordination-server/    # 服务端入口
├── internal/
│   ├── auth/                   # 认证
│   ├── config/                 # 配置
│   ├── election/               # 选举模块
│   ├── king/                   # King 指令系统
│   ├── node/                   # 节点管理
│   ├── server/                 # HTTP 服务
│   ├── task/                   # 任务模块
│   └── transport/              # 传输层
├── pkg/
│   └── protocol/               # 公共协议
├── plugins/
│   └── commanderclaw/          # OpenClaw 插件
├── web/                        # Web 控制台
├── docs/                       # 文档
└── .commander-claw/            # 配置
```

## 贡献

欢迎贡献！提交 PR 前请阅读贡献指南。

## 许可证

MIT