9. Multi-Instance

Mục tiêu: Hiểu khi nào và cách chạy nhiều Gateway instance độc lập.

Khi nào cần Multi-Instance?

Hầu hết setups chỉ cần 1 Gateway - một Gateway có thể:

• Phục vụ nhiều channels (Telegram, WhatsApp, Discord...)
• Chạy nhiều agents khác nhau
• Xử lý nhiều users đồng thời

Chạy nhiều instances khi cần:

Trường hợp	Lý do
Strong isolation	Tách biệt hoàn toàn giữa production và staging
Rescue bot	Backup instance khi main bị lỗi
Different configs	Cấu hình khác biệt hoàn toàn
Resource limits	Giới hạn tài nguyên cho từng instance
Security zones	Tách DMZ và internal network

Kiến trúc Multi-Instance

┌─────────────────────────────────────────────────────────┐
│                    Same Host                              │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────────┐    ┌─────────────────┐               │
│  │  Gateway A      │    │  Gateway B      │               │
│  │  (Main)         │    │  (Rescue)       │               │
│  │                 │    │                 │               │
│  │  Port: 18789    │    │  Port: 18790    │               │
│  │  Config: main   │    │  Config: rescue │               │
│  │  Telegram bot A │    │  Telegram bot B │               │
│  │  WhatsApp A     │    │                 │               │
│  └─────────────────┘    └─────────────────┘               │
├─────────────────────────────────────────────────────────┤
│  Profiles:                                               │
│  ~/.openclaw/     ~/.openclaw-rescue/                    │
│  ├── openclaw.json  ├── openclaw.json                     │
│  ├── sessions/      ├── sessions/                         │
│  └── credentials/   └── credentials/                      │
└─────────────────────────────────────────────────────────┘

Isolation Requirements

Khi chạy nhiều instances, cần đảm bảo:

Resource	Isolation	Cách làm
Config	Tách biệt	Dùng --profile hoặc OPENCLAW_CONFIG_PATH
Port	Khác nhau	Port khác cho mỗi instance
Data	Tách biệt	Thư mục data riêng
Logs	Tách biệt	Log files riêng

Cách 1: Profiles (Khuyến nghị)

Dùng flag --profile để tạo instance riêng biệt.

Tạo Rescue Instance

# 1. Tạo profile mới
openclaw --profile rescue onboard

# 2. Cấu hình port khác
openclaw --profile rescue config set gateway.port 18790

# 3. Khởi động
openclaw --profile rescue gateway --port 18790

Cấu trúc thư mục

~/.openclaw/              # Default profile (main)
├── openclaw.json
├── sessions/
└── credentials/

~/.openclaw-rescue/       # Rescue profile
├── openclaw.json
├── sessions/
└── credentials/

Commands với profile

# Tất cả commands đều hỗ trợ --profile
openclaw --profile rescue status
openclaw --profile rescue config set agent.model "..."
openclaw --profile rescue channels login telegram
openclaw --profile rescue logs --tail 100

Cách 2: Manual Environment

Dùng environment variables để tách instance.

# Instance 1 (Main)
export OPENCLAW_CONFIG_PATH="~/.openclaw-main/openclaw.json"
export OPENCLAW_HOME="~/.openclaw-main"
openclaw gateway --port 18789

# Instance 2 (Staging)
export OPENCLAW_CONFIG_PATH="~/.openclaw-staging/openclaw.json"
export OPENCLAW_HOME="~/.openclaw-staging"
openclaw gateway --port 18790

Cách 3: Docker (Production)

# docker-compose.yml
version: "3.8"
services:
  openclaw-main:
    image: openclaw:latest
    ports:
      - "18789:18789"
    volumes:
      - ./main-config:/root/.openclaw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - GATEWAY_PORT=18789

  openclaw-rescue:
    image: openclaw:latest
    ports:
      - "18790:18790"
    volumes:
      - ./rescue-config:/root/.openclaw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - GATEWAY_PORT=18790

Rescue Bot Guide

Mục tiêu: Có backup instance khi main gateway lỗi.

Setup Rescue Instance

# 1. Tạo profile rescue
openclaw --profile rescue onboard

# 2. Cấu hình khác biệt
openclaw --profile rescue config set gateway.port 18790

# 3. Setup Telegram bot khác
openclaw --profile rescue channels login telegram

# 4. Test
openclaw --profile rescue gateway --port 18790

# 5. Cài đặt daemon
openclaw --profile rescue service install

Switching Strategy

# Khi main bị lỗi
# 1. Kiểm tra main
openclaw status
# 2. Nếu main down, rescue vẫn chạy
openclaw --profile rescue status

# 3. Người dùng chuyển sang bot rescue
# (Cần 2 Telegram bot khác nhau)

Port Mapping

Instance	Port	Use case
Main	18789	Production chính
Rescue	18790	Backup khi main lỗi
Staging	18791	Test config mới
Dev	18792	Development

Browser/CDP Considerations

Khi dùng browser automation với nhiều instances:

# Mỗi instance cần CDP port riêng
openclaw config set tools.browser.cdpPort 9222  # Instance 1
openclaw --profile rescue config set tools.browser.cdpPort 9223  # Instance 2

Best Practices

1. Đặt tên profile rõ ràng

openclaw --profile main ...
openclaw --profile staging ...
openclaw --profile rescue ...

2. Dùng port cố định cho mỗi profile

main:     18789
staging:  18790
rescue:   18791
dev:      18792

3. Backup config mỗi profile

# Script backup
for profile in main staging rescue; do
  openclaw --profile $profile config export > backup-$profile.json
done

4. Giám sát tất cả instances

# Kiểm tra tất cả
openclaw status
openclaw --profile rescue status
openclaw --profile staging status

5. Không dùng multi-instance nếu không cần

Hầu hết cases chỉ cần 1 Gateway với:

• Nhiều channels (Telegram + WhatsApp + Discord)
• Nhiều agents (routing khác nhau)
• Per-sender sessions (tự động cô lập)

Commands tham khảo

Command	Mô tả
openclaw --profile <name> ...	Chạy với profile cụ thể
openclaw gateway --port 18789	Chỉ định port
openclaw --profile rescue status	Check status rescue

Troubleshooting

"Another gateway instance is already listening"

# Kiểm tra port đã dùng
lsof -i :18789

# Dùng port khác
openclaw gateway --port 18790

"Cannot create profile directory"

# Kiểm tra quyền
ls -la ~/.openclaw-rescue

# Sửa quyền
chmod 755 ~/.openclaw-rescue

"Config file not found"

# Chạy onboard cho profile
openclaw --profile <name> onboard

Tiếp theo?

• Bài 10: Troubleshooting - Xử lý sự cố