217 lines
9.0 KiB
Markdown
217 lines
9.0 KiB
Markdown
# 🚀 Open-Claw-Team-Superpowers
|
|
|
|
**Open-Claw-Team-Superpowers** là sự kết hợp sức mạnh điều phối của **OpenClaw**, khả năng làm việc bầy đàn (Swarm) của **ClawTeam**, và bộ skills, tri thức lập trình chuyên sâu từ **Superpowers**.
|
|
|
|
Đã được tinh chỉnh để ngăn chặn deadlock và sẵn sàng cho các task lập trình phức tạp.
|
|
|
|
---
|
|
|
|
## 🏗️ Kiến trúc Hệ thống (Architecture)
|
|
|
|
Hệ thống chạy trên **Docker** với 2 dịch vụ cốt lõi:
|
|
1. **Gateway (`openclaw-gateway`)**: Trái tim xử lý API, Web UI và quản lý các luồng kết nối LLM (Claude, GPT, Gemini).
|
|
2. **CLI/Bastion (`openclaw-cli`)**: Trạm điều khiển cho phép kỹ sư truy cập trực tiếp (interactive shell) để điều phối ClawTeam và Superpowers thủ công.
|
|
|
|
Cả hai container dùng chung một image `openclaw-clawteam:latest` được build từ `Dockerfile` của dự án.
|
|
|
|
---
|
|
|
|
## 🛠️ Hướng dẫn Cài đặt (Installation)
|
|
|
|
### 1. Yêu cầu hệ thống
|
|
|
|
- **Docker Engine** >= 24.x
|
|
- **Docker Compose** >= v2.x (`docker compose` — không phải `docker-compose`)
|
|
- Quyền truy cập vào Git repository nội bộ
|
|
|
|
### 2. Tải Mã nguồn (Clone Repository)
|
|
Mở Terminal của bạn và thực hiện kéo mã nguồn mới nhất từ kho lưu trữ của công ty về máy cục bộ.
|
|
|
|
Tải toàn bộ dự án về máy:
|
|
```bash
|
|
git clone [https://git.smartgift.io.vn/smartgift/open-claw-team.git](https://git.smartgift.io.vn/smartgift/open-claw-team.git)
|
|
```
|
|
|
|
Di chuyển vào thư mục dự án vừa tải:
|
|
```bash
|
|
cd open-claw-team
|
|
```
|
|
|
|
|
|
### 3. Cấu hình biến môi trường
|
|
|
|
Mở và chỉnh sửa file `.env`:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
vi .env
|
|
```
|
|
|
|
Các biến quan trọng cần chú ý:
|
|
|
|
| Biến | Mặc định | Mô tả |
|
|
|------|----------|-------|
|
|
| `OPENCLAW_GATEWAY_TOKEN` | `team-token` | ⚠️ Token xác thực WebSocket & Web UI — **bắt buộc đổi trên production** |
|
|
| `OPENCLAW_GATEWAY_BIND` | `lan` | Bind mode: `loopback` \| `lan` \| `tailnet`. Dùng `lan` khi chạy Docker |
|
|
| `OPENCLAW_GATEWAY_PORT` | `18789` | Port WebSocket Gateway |
|
|
| `OPENCLAW_BRIDGE_PORT` | `18889` | Port Bridge / Node-to-node |
|
|
| `CLAUDE_AI_SESSION_KEY` | _(trống)_ | Session key từ claude.ai (cần ít nhất 1 key) |
|
|
| `CLAUDE_WEB_SESSION_KEY` | _(trống)_ | Session key thay thế |
|
|
| `CLAUDE_WEB_COOKIE` | _(trống)_ | Cookie raw nếu dùng Web API |
|
|
| `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS` | _(trống)_ | Đặt `1` để cho phép WS không mã hoá trên mạng nội bộ |
|
|
| `OPENCLAW_TZ` | `Asia/Ho_Chi_Minh` | Timezone container |
|
|
|
|
> **Lấy Claude session keys:** Mở https://claude.ai trên trình duyệt → F12 → tab **Application** → **Cookies** hoặc **Session Storage**.
|
|
|
|
---
|
|
|
|
## 🐳 Hướng dẫn Sử dụng Docker
|
|
|
|
Sau khi mã nguồn đã sẵn sàng, chúng ta sẽ tiến hành build docker và chạy nền các Container. Lệnh này sẽ kéo `node:24-slim` về, cài đặt tự động OpenClaw, ClawTeam và Superpowers.
|
|
|
|
### Build & Khởi động
|
|
|
|
```bash
|
|
# Lần đầu: build image và start toàn bộ stack
|
|
docker compose up -d --build
|
|
```
|
|
|
|
```bash
|
|
# Các lần sau (đã có image): start nhanh
|
|
docker compose up -d
|
|
```
|
|
|
|
**Giải thích cờ (flags):**
|
|
* `-d` (detached): Chạy ngầm trong background để không chiếm dụng Terminal của bạn.
|
|
* `--build`: Ép hệ thống đóng gói lại kiến trúc mới nhất từ Dockerfile thay vì dùng cache cũ.
|
|
|
|
Quá trình này có thể mất vài phút. Để kiểm tra xem hệ thống đã lên ổn định chưa, hãy gõ:
|
|
```bash
|
|
docker ps
|
|
```
|
|
|
|
Nếu bạn thấy cả 2 container `openclaw-gateway` và `openclaw-cli` đều hiển thị trạng thái **Up**, hệ thống đã chạy thành công!
|
|
|
|
### Xem logs
|
|
|
|
```bash
|
|
# Log riêng Gateway
|
|
docker compose logs -f openclaw-gateway
|
|
```
|
|
|
|
```bash
|
|
# Log riêng CLI (thường ít output)
|
|
docker compose logs -f openclaw-cli
|
|
```
|
|
|
|
### Truy cập CLI (Bastion Shell)
|
|
|
|
Container `openclaw-cli` là môi trường interactive để thao tác trực tiếp với OpenClaw:
|
|
|
|
```bash
|
|
# Mở bash shell vào CLI container
|
|
docker compose exec openclaw-cli bash
|
|
|
|
# Chạy lệnh openclaw trực tiếp từ host
|
|
docker compose exec openclaw-cli openclaw --help
|
|
docker compose exec openclaw-cli openclaw status
|
|
|
|
# Kiểm tra version OpenClaw đang dùng
|
|
docker compose exec openclaw-cli openclaw --version
|
|
```
|
|
|
|
## ⚙️ Setup để bắt đầu sử dụng
|
|
|
|
| Host Path (mặc định) | Mount trong container | Mục đích |
|
|
|----------------------|-----------------------|----------|
|
|
| `./.openclaw` | `/home/node/.openclaw` | Config, credentials OpenClaw |
|
|
| `./.openclaw/workspace` | `/home/node/.openclaw/workspace` | Workspace làm việc của agents |
|
|
|
|
> Thư mục `.openclaw/` được tạo tự động khi gateway khởi động lần đầu. Tất cả cấu hình (token, origins, …) lưu tại đây và **persist qua các lần restart**.Nói cách khác, thư mục `.openclaw` chính là "bộ não" chứa dữ liệu của hệ thống. Để AI có thể hoạt động, bạn cần cấp "chìa khóa" (API Keys). Có 2 cách để thực hiện:
|
|
|
|
Truy cập trực tiếp vào Terminal hệ thống `cli` (đây là nơi được tạo ra để kỹ sư có thể thao tác tương tác):
|
|
```bash
|
|
docker exec -it openclaw-team-repo-openclaw-cli-1 bash
|
|
```
|
|
Sau đó, trong container hãy thực thi lệnh thiết lập:
|
|
```bash
|
|
openclaw setup
|
|
```
|
|
|
|
Sau đó chạy lệnh
|
|
```bash
|
|
openclaw configure
|
|
```
|
|
|
|
Các phần bạn cần config trước khi bắt đầu sử dụng:
|
|
- Channels:
|
|
Telegram (recommend):
|
|
Chọn Enter Telegram bot token (Cách lấy token có thể tham khảo ở `https://help.superchat.com/en/articles/14901-how-do-i-get-the-telegram-token-or-bot-id`)
|
|
Sau khi nhập xong token thì sẽ hỏi "Config DM access policies now?" -> (chọn `No`)
|
|
Sau khi config xong thì vào chat với bot, nó sẽ yêu cầu chạy lệnh `openclaw pairing approve telegram [id]` trong terminal thì hãy chạy để xác nhận kết nối.
|
|
- Model:
|
|
Nếu mọi người sử dụng API có trả phí thì có thể chọn `OpenAI` hoặc `Anthropic`.
|
|
Còn nếu mọi người sử dụng API free thì có thể chọn:
|
|
- `OpenRouter` (recommend): Các model em thấy sử dụng tốt gồm `Qwen3.6 Plus (free)` (đặt làm primary), `Step 3.5 Flash (free)` và `NVIDIA-Nemotron-3-Super-120B-A12B: free` (đặt làm fallback). Lưu ý: Không nên để auto vì đôi khi sẽ chọn những model không có khả năng suy luận hoặc model phải có suy luận.
|
|
- `Copilot` (Github Copilot Oauth): Sẽ được free model `GPT-5.1 mini` và `GPT-4.1`
|
|
|
|
**Lưu ý: khi chúng ta sử dụng model free thì đồng nghĩa mình đồng ý gửi cho họ dữ liệu mình sử dụng để họ huấn luyện model nên hãy cân nhắc kỹ khi sử dụng cho các thông tin bảo mật**
|
|
|
|
Sau khi config xong, mọi người hãy chạy lệnh `openclaw dashboard` và mở link Dashboard Url `http://localhost:18789` để kiểm tra.
|
|
Nếu nó báo lỗi `unauthorized: need pairing` thì mọi người vào chạy lệnh `openclaw devices list` để kiểm tra device đang request pairing và dùng `openclaw devices approve` để approve (không cần thêm id cũng được). Sau đó mọi người vào lại `http:localhost:18789` để kiểm tra lại thì sẽ được.
|
|
|
|
|
|
> **Cảnh báo:** Mọi tệp cấu hình bảo mật sẽ nằm ở thư mục `.openclaw` trên máy tính tải về. Thư mục này đã có trong `.gitignore`. Tuyệt đối KHÔNG sử dụng lệnh ép buộc (force add) để đẩy các tệp thuộc `.openclaw` lên Github nhằm tránh rò rỉ thông tin bảo mật.
|
|
|
|
---
|
|
|
|
## 🌐 Cổng kết nối (Ports)
|
|
|
|
| Port | Biến | Mô tả |
|
|
|------|------|-------|
|
|
| `18789` | `OPENCLAW_GATEWAY_PORT` | WebSocket Gateway + **Web Control UI** |
|
|
| `18889` | `OPENCLAW_BRIDGE_PORT` | Bridge / Node-to-node communication |
|
|
|
|
Sau khi khởi động, mở trình duyệt:
|
|
|
|
```
|
|
http://localhost:18789
|
|
```
|
|
|
|
Đăng nhập bằng giá trị `OPENCLAW_GATEWAY_TOKEN` trong `.env`.
|
|
|
|
|
|
## 🔧 Troubleshooting
|
|
|
|
### Gateway không start — lỗi "non-loopback Control UI"
|
|
|
|
Nguyên nhân: `OPENCLAW_GATEWAY_BIND` đang là `loopback`, không tương thích với Docker port mapping.
|
|
|
|
**Sửa:**
|
|
|
|
```env
|
|
# .env
|
|
OPENCLAW_GATEWAY_BIND=lan
|
|
```
|
|
|
|
### Lỗi WebSocket kết nối qua mạng nội bộ
|
|
|
|
```env
|
|
# .env
|
|
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1
|
|
```
|
|
|
|
---
|
|
|
|
## 📁 Cấu trúc Dự án
|
|
|
|
```
|
|
open-claw-team/
|
|
├── Dockerfile # Image: Node 24 + OpenClaw + ClawTeam + Superpowers
|
|
├── docker-compose.yml # 2 services: openclaw-gateway + openclaw-cli
|
|
├── .env # Biến môi trường (⚠️ KHÔNG commit lên Git)
|
|
├── .gitignore
|
|
└── .openclaw/ # Auto-generated — gitignored
|
|
├── openclaw.json # Config gateway (sau lần setup đầu)
|
|
└── workspace/ # Workspace của agents
|
|
``` |