# 🚀 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. Clone dự án

```bash
git clone https://git.smartgift.io.vn/smartgift/open-claw-team.git open-claw-team
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

### Build & Khởi động

```bash
# Lần đầu: build image và start toàn bộ stack
docker compose up -d --build

# Các lần sau (đã có image): start nhanh
docker compose up -d
```

### Xem logs

```bash
# Log riêng Gateway
docker compose logs -f openclaw-gateway

# 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**.

---

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