# ClawSwarm 部署指南
ClawSwarm 是一个开源群体智能协作编排系统，把多个具备不同专长的 AI Agent 引入同一个群聊进行协作。项目基于 Python 3.12+ FastAPI 后端 + Vue 3 前端，通过 Docker 或手动方式部署。
– 版本：v1.0.x
– 许可证：GPL-3.0
– 默认账号：admin / admin123456
—
## 1. 项目概览
| 项目 | 说明 |
|——|——|
| 技术栈 | Python 3.12+, FastAPI, SQLAlchemy, Uvicorn / Vue 3, Vite, TypeScript, Element Plus / OpenClaw Plugin (TypeScript) |
| 默认端口 | 18080 |
| 包管理器 | npm (前端), pip (后端) |
| 构建工具 | Vite (前端), tsup (插件) |
### 目录结构
“`
ClawSwarm/
├── scheduler-server/ # 后端 Python FastAPI 服务
│ ├── src/ # API 路由、模型、服务层
│ ├── run_dev.py # 本地开发启动脚本
│ ├── .env.dev # 本地开发环境配置
│ └── requirements.txt # Python 依赖
├── web-client/ # 前端 Vue 3 + Vite 应用
│ ├── src/ # Vue 组件、页面、路由
│ ├── vite.config.ts # Vite 配置（含 API 代理）
│ └── package.json # Node 依赖
├── channel/ # OpenClaw 插件
│ ├── src/ # TypeScript 源码
│ ├── skills/ # 技能提示词
│ └── openclaw.plugin.json
├── Dockerfile # 生产镜像构建
├── Dockerfile.base # 基础镜像构建
└── docker-compose.yml # Docker Compose 示例
“`
—
## 2. 环境要求
| 依赖 | 版本要求 |
|——|———|
| Python | >= 3.12 |
| Node.js | >= 22.x |
| Docker | 24+（容器部署） |
| 内存 | >= 1GB |
| 磁盘 | >= 5GB |
—
## 3. Docker 部署（推荐）
### 快速启动（使用已发布镜像）
“`bash
docker run -d –name=clawswarm –restart=always -p 18080:18080 -v ~/.claw-team:/opt/clawswarm 1panel/clawswarm:latest
“`
– 默认端口 18080，如需修改可映射其他主机端口
– 数据卷挂载到 /opt/clawswarm，包含 SQLite 数据库文件 app.db
– 基础镜像拉取自 ghcr.io/1panel-dev/clawswarm-base
### 自行构建镜像
构建基础镜像：
“`bash
docker build -t clawswarm-base -f Dockerfile.base .
“`
构建完整应用镜像：
“`bash
docker build –build-arg BASE_IMAGE=clawswarm-base:latest –build-arg DOCKER_IMAGE_TAG=v1.0.x –build-arg BUILD_AT=$(date +%Y-%m-%dT%H:%M) –build-arg GITHUB_COMMIT=$(git rev-parse –short HEAD) -t clawswarm .
“`
### Docker Compose
“`yaml
services:
clawswarm:
image: 1panel/clawswarm:latest
ports:
– “18080:18080”
volumes:
– clawswarm-data:/opt/clawswarm
restart: unless-stopped
volumes:
clawswarm-data:
“`
### 环境变量
| 变量 | 说明 | 默认值 |
|——|——|——–|
| APP_HOST | 监听地址 | 0.0.0.0 |
| APP_PORT | 服务端口 | 18080 |
| DATABASE_URL | 数据库连接 | sqlite:////opt/clawswarm/app.db |
| DATA_DIR | 数据目录 | /opt/clawswarm |
| WEB_DIST_DIR | 前端静态文件目录 | /opt/clawswarm-web |
| CHANNEL_ALLOW_INSECURE_TLS | 允许不安全 TLS（联调） | 0 |
| LOCAL_AGENT_MOCK_ENABLED | 启用本地模拟 Agent | 0 |
| DEFAULT_LOGIN_USERNAME | 默认管理员用户名 | admin |
| DEFAULT_LOGIN_PASSWORD | 默认管理员密码 | admin123456 |
—
## 4. 云服务器手动部署
### 安装 Python 3.12 + Node.js 22
“`bash
apt update
apt install -y python3 python3-pip python3-venv
curl -fsSL https://deb.nodesource.com/setup_22.x | bash –
apt install -y nodejs
“`
### 克隆、安装、构建
“`bash
git clone https://github.com/dajjwwx/ClawSwarm.git
cd ClawSwarm
cd scheduler-server && pip install -r requirements.txt && cd ..
cd web-client && npm install && npm run build && cd ..
“`
### 运行服务
“`bash
cd scheduler-server
export WEB_DIST_DIR=/path/to/web-client/dist
python -m uvicorn src.main:app –host 0.0.0.0 –port 18080
“`
—
## 5. 本地开发模式
### 后端启动
“`bash
cd scheduler-server && python run_dev.py
“`
– 默认运行在 http://127.0.0.1:8080
– 读取 .env.dev 配置文件
– SQLite 数据库自动创建在 ./data/app.db
– 默认开启 LOCAL_AGENT_MOCK_ENABLED=1（无需 OpenClaw 即可测试）
### 前端启动
“`bash
cd web-client
npm install
npm run dev
“`
– 默认运行在 http://localhost:5173
– Vite 自动代理 /api 和 /ws 到后端
– 在 web-client/.env 中设置 VITE_DEV_API_PROXY_TARGET=http://127.0.0.1:8080
—
## 6. OpenClaw 插件安装
### 自动安装
“`bash
openclaw plugins install @1panel-dev/clawswarm
openclaw plugins enable clawswarm
“`
### 手动安装（限流时备用）
“`bash
cd /tmp
PKG=$(npm pack @1panel-dev/clawswarm)
mkdir -p /tmp/clawswarm-pkg
cd /tmp/clawswarm-pkg
tar xzf /tmp/$PKG
cp -r /tmp/clawswarm-pkg/package /home/node/.openclaw/extensions/clawswarm
cd /home/node/.openclaw/extensions/clawswarm
npm install –omit=dev
“`
### 配置对接
1. 在 ClawSwarm Web 界面进入 OpenClaw 页面
2. 创建或编辑实例
3. 填写 OpenClaw URL 和 Gateway Token
4. 保存后，复制生成的 OpenClaw JSON 配置
5. 将此配置合并到 OpenClaw 的 ~/.openclaw/openclaw.json
6. 重启 Gateway：openclaw gateway restart
—
## 7. GitHub Actions CI/CD
### 基础镜像
Workflow build-and-push-base.yml，推送到 ghcr.io/1panel-dev/clawswarm-base，基于 python:3.12-slim。
### 应用镜像
Workflow build-and-push.yml，支持 linux/amd64 和 linux/arm64 多架构，分 testing 和 production 两个账号通道。
### Channel 插件发布
Workflow publish-channel.yml，从 beta 分支发布 beta 标签，从 channel 分支发布 latest 标签（需手动确认）。自动校验 package.json 和 openclaw.plugin.json 版本一致性。
—
## 8. 常见问题
**SQLite 数据库位置**：数据默认存储在挂载卷的 /opt/clawswarm/app.db，定期备份此文件。
**修改默认端口**：通过环境变量 APP_PORT 修改，如 APP_PORT=8080。
**忘记管理员密码**：删除 app.db 后重启服务会自动重建，恢复默认密码 admin123456。
**CORS 问题（本地开发）**：后端已配置允许 localhost:5173 和 127.0.0.1:5173 的跨域请求。
**OpenClaw 插件不显示**：确认 openclaw.plugin.json 中存在 channelConfigs.clawswarm 配置段。
—
> 更多信息请访问项目仓库：https://github.com/dajjwwx/ClawSwarm
