# 🚀 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
```

## ⚙️ Cấu trúc Volumes & Dữ liệu

| 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:

**Cách 1: Cấu hình qua Giao diện Web (Khuyên dùng)**
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
```

**Cách 2: Cấu hình qua Terminal (bằng container CLI)**
Hệ thống Gateway mặc định có sẵn thiết lập khởi chạy không cần config, bạn có thể thiết lập trực tiếp trên web bằng cách:
* Mở trình duyệt và truy cập `http://localhost:18789` (Hoặc địa chỉ IP máy chủ của bạn với cổng `18789`).
Tại giao diện Web, hệ thống sẽ tự động hiển thị Wizard Setup để bạn điền các API Key (OpenAI, Anthropic, Gemini...). Các thông tin này sẽ được lưu ngầm tự động xuống thư mục `.openclaw`.

> **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
```