diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..c797200
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,36 @@
+# -----------------------------------------------------------------------------
+# GATEWAY AUTH
+# Token để authenticate vào Gateway WebSocket và Control UI
+# Dùng chuỗi ngẫu nhiên dài ít nhất 32 ký tự cho production
+# -----------------------------------------------------------------------------
+OPENCLAW_GATEWAY_TOKEN=team-token
+
+# -----------------------------------------------------------------------------
+# GATEWAY NETWORK
+# Bind mode: loopback | lan | tailnet | auto | custom
+#   loopback  → chỉ localhost (an toàn nhất, không cần port mapping)
+#   lan       → bind 0.0.0.0 (cần thiết khi dùng Docker port mapping)
+# Port WebSocket gateway (mặc định 18789)
+# Port bridge / node (mặc định 18889)
+# -----------------------------------------------------------------------------
+OPENCLAW_GATEWAY_BIND=lan
+OPENCLAW_GATEWAY_PORT=18789
+OPENCLAW_BRIDGE_PORT=18889
+
+# -----------------------------------------------------------------------------
+# CLAUDE / AI SESSION KEYS
+# Lấy từ https://claude.ai (browser DevTools → cookies / session storage)
+# Cần ít nhất một trong hai để agent hoạt động
+# -----------------------------------------------------------------------------
+CLAUDE_AI_SESSION_KEY=
+CLAUDE_WEB_SESSION_KEY=
+CLAUDE_WEB_COOKIE=
+
+# -----------------------------------------------------------------------------
+# OPENCLAW — MISC
+# Cho phép kết nối WebSocket không mã hoá qua private network
+# Timezone container (VD: Asia/Ho_Chi_Minh)
+# -----------------------------------------------------------------------------
+OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=
+OPENCLAW_TZ=Asia/Ho_Chi_Minh
+
diff --git a/.gitignore b/.gitignore
index f3d6c07..ac32804 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,8 @@
 !.openclaw/credentials/.gitkeep
 .openclaw/*.bak*
 .openclaw/*.clobbered*
+.openclaw/exec-approvals.json
+.openclaw/node.json
 
 # ==========================================
 # 2. RUNTIME CACHE & TRASH
diff --git a/README.md b/README.md
index 6f820ff..f0646b0 100644
--- a/README.md
+++ b/README.md
@@ -12,14 +12,148 @@ 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. Chuẩn bị môi trường
-Yêu cầu hệ thống đã cài đặt:
-* **Docker** & **Docker Compose v2.x**
-* Quyền truy cập vào Git nội bộ của công ty.
+### 1. Yêu cầu hệ thống
 
-### 2. Khởi tạo dự án
+- **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
+```