Tổng quan kiến trúc

OpenClaw sử dụng mô hình Gateway + Agent:

• Gateway: Tiến trình trung tâm, quản lý tất cả kết nối messaging (Telegram, WhatsApp, Discord…), routing tin nhắn đến đúng agent.
• Agent: Mỗi agent là một “bộ não” độc lập với workspace riêng, session riêng, và personality riêng.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Telegram    │     │  WhatsApp   │     │  Discord    │
│  Bot/Group   │     │  Account    │     │  Server     │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       └───────────┬───────┘───────────────────┘
                   │
           ┌───────▼───────┐
           │   Gateway     │  ← Routing + Session Management
           │  (Host/VPS)   │
           └───┬───┬───┬───┘
               │   │   │
         ┌─────┘   │   └─────┐
         ▼         ▼         ▼
    ┌─────────┐ ┌─────────┐ ┌─────────┐
    │ Agent A │ │ Agent B │ │ Agent C │
    │(Docker) │ │(Docker) │ │(Docker) │
    │Code Rev │ │DevOps   │ │Writer   │
    └─────────┘ └─────────┘ └─────────┘

Mỗi agent có:

• Workspace riêng (chứa AGENTS.md, SOUL.md, skills, memory…)
• Session store riêng (lịch sử hội thoại độc lập)
• Auth profiles riêng (API keys không shared giữa các agent)
• Tool permissions riêng (agent nào được dùng tool nào)

Bước 1: Cài đặt OpenClaw trên VPS

Yêu cầu

• VPS Ubuntu/Debian (khuyên dùng 2GB RAM trở lên)
• Node.js 22+
• Docker (cho sandbox)

Cài đặt

# Cài OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash

# Cài Docker (nếu chưa có)
curl -fsSL https://get.docker.com | sh

# Build sandbox image (cần cho chế độ Docker sandbox)
cd /usr/lib/node_modules/openclaw
scripts/sandbox-setup.sh

Khởi tạo cấu hình cơ bản

# Chạy wizard
openclaw onboard --install-daemon

File cấu hình nằm tại ~/.openclaw/openclaw.json.

Bước 2: Tạo Telegram Bot cho mỗi Agent

Mỗi agent cần một Telegram Bot riêng. Lý do: mỗi bot có identity riêng, người dùng phân biệt được ai đang trả lời.

Tạo bot với BotFather

Mở Telegram, chat với @BotFather:

/newbot
Name: CodeReviewer Bot
Username: myteam_codereviewer_bot

Lặp lại cho mỗi agent:

• myteam_devops_bot
• myteam_writer_bot

Lưu lại token của mỗi bot.

Cấu hình Privacy Mode

Quan trọng: Nếu muốn bot đọc được tất cả tin nhắn trong group (không chỉ khi mention):

/setprivacy
→ Chọn bot
→ Disable

Hoặc thêm bot làm admin trong group (admin bots nhận tất cả tin nhắn).

Bước 3: Cấu hình Multi-Agent

Tạo workspace cho từng agent

mkdir -p ~/.openclaw/workspace-code-reviewer
mkdir -p ~/.openclaw/workspace-devops
mkdir -p ~/.openclaw/workspace-writer

Tạo personality cho từng agent

Mỗi workspace cần file SOUL.md định nghĩa tính cách:

~/.openclaw/workspace-code-reviewer/SOUL.md:

# Code Reviewer Agent

Bạn là một code reviewer chuyên nghiệp.
- Review code với tiêu chuẩn cao
- Tìm bugs, security issues, performance problems
- Đề xuất cải thiện cụ thể
- Trả lời bằng tiếng Việt
- Format: dùng code blocks và bullet points

~/.openclaw/workspace-devops/SOUL.md:

# DevOps Agent

Bạn là DevOps engineer.
- Quản lý infrastructure, CI/CD, monitoring
- Thực thi các lệnh hệ thống khi được yêu cầu
- Giám sát server health
- Trả lời bằng tiếng Việt

~/.openclaw/workspace-writer/SOUL.md:

# Content Writer Agent

Bạn là content writer chuyên về tech.
- Viết bài blog, documentation
- SEO-friendly
- Chỉ có quyền đọc file, không chạy lệnh
- Trả lời bằng tiếng Việt

Tạo auth cho từng agent

Mỗi agent cần auth riêng (API key cho LLM provider):

# Thêm agent mới bằng wizard
openclaw agents add code-reviewer
openclaw agents add devops
openclaw agents add writer

Wizard sẽ hỏi bạn chọn model provider (Anthropic, OpenAI…) và nhập API key. Mỗi agent lưu auth tại:

~/.openclaw/agents/code-reviewer/agent/auth-profiles.json
~/.openclaw/agents/devops/agent/auth-profiles.json
~/.openclaw/agents/writer/agent/auth-profiles.json

Lưu ý quan trọng: Auth profiles KHÔNG được shared giữa các agent. Nếu muốn dùng chung API key, copy file auth-profiles.json sang agent khác.

Bước 4: Cấu hình Gateway với Docker Sandbox

Đây là phần quan trọng nhất — file ~/.openclaw/openclaw.json:

{
  // === AGENTS ===
  agents: {
    defaults: {
      sandbox: {
        mode: "all",              // Tất cả agent chạy trong Docker
        scope: "agent",           // Mỗi agent = 1 container riêng
        workspaceAccess: "rw",    // Agent đọc/ghi workspace của mình
        docker: {
          network: "bridge",      // Cho phép truy cập mạng
        },
      },
    },
    list: [
      {
        id: "main",
        default: true,
        name: "Team Lead",
        workspace: "~/.openclaw/workspace",
        sandbox: { mode: "off" },  // Agent chính chạy trên host
      },
      {
        id: "code-reviewer",
        name: "Code Reviewer",
        workspace: "~/.openclaw/workspace-code-reviewer",
        tools: {
          allow: ["read", "exec", "write", "edit", "sessions_send",
                  "sessions_list", "sessions_history"],
          deny: ["browser", "gateway"],
        },
      },
      {
        id: "devops",
        name: "DevOps Engineer",
        workspace: "~/.openclaw/workspace-devops",
        tools: {
          allow: ["read", "write", "exec", "process",
                  "sessions_send", "sessions_list"],
          deny: ["browser", "gateway"],
        },
      },
      {
        id: "writer",
        name: "Content Writer",
        workspace: "~/.openclaw/workspace-writer",
        tools: {
          allow: ["read", "web_search", "web_fetch",
                  "sessions_send", "sessions_list"],
          deny: ["exec", "write", "edit", "browser", "gateway"],
        },
      },
    ],
  },

  // === TELEGRAM (Multi-account) ===
  channels: {
    telegram: {
      enabled: true,
      accounts: [
        {
          id: "main",
          botToken: "TOKEN_CUA_BOT_CHINH",
        },
        {
          id: "code-reviewer",
          botToken: "TOKEN_CUA_CODE_REVIEWER_BOT",
        },
        {
          id: "devops",
          botToken: "TOKEN_CUA_DEVOPS_BOT",
        },
        {
          id: "writer",
          botToken: "TOKEN_CUA_WRITER_BOT",
        },
      ],
      groups: {
        "*": { requireMention: false },
      },
    },
  },

  // === BINDINGS (routing tin nhắn) ===
  bindings: [
    // Route DM tới bot code-reviewer → agent code-reviewer
    {
      agentId: "code-reviewer",
      match: {
        channel: "telegram",
        accountId: "code-reviewer",
      },
    },
    // Route DM tới bot devops → agent devops
    {
      agentId: "devops",
      match: {
        channel: "telegram",
        accountId: "devops",
      },
    },
    // Route DM tới bot writer → agent writer
    {
      agentId: "writer",
      match: {
        channel: "telegram",
        accountId: "writer",
      },
    },
  ],
}

Giải thích cấu hình

agents.defaults.sandbox: Mặc định tất cả agent chạy trong Docker container riêng biệt. scope: "agent" nghĩa là mỗi agent = 1 container (thay vì mỗi session = 1 container).

agents.list[].tools: Mỗi agent có quyền truy cập tool khác nhau:

• Code Reviewer: đọc/ghi file, chạy lệnh, giao tiếp với agent khác
• DevOps: đọc/ghi file, chạy lệnh và quản lý process
• Writer: chỉ đọc file và search web, không được chạy lệnh

bindings: Quy tắc routing — tin nhắn đến bot nào thì chuyển cho agent nào.

Bước 5: Thiết lập Telegram Group cho đội ngũ

Tạo group và thêm các bot

1. Tạo Telegram group: “AI Team”
2. Thêm tất cả bot vào group
3. Set mỗi bot làm admin (để nhận tất cả tin nhắn)

Cấu hình Broadcast Group

Để tất cả agent cùng nhận và xử lý tin nhắn trong group:

{
  // Thêm vào openclaw.json
  broadcast: {
    strategy: "parallel",
    // Thay bằng Telegram group chat ID thực
    "-1001234567890": ["code-reviewer", "devops", "writer"],
  },
}

Lưu ý: Feature broadcast hiện mới hỗ trợ WhatsApp. Với Telegram, bạn sẽ sử dụng cách tiếp cận khác — mỗi bot tham gia group và agent tương ứng xử lý tin nhắn gửi qua bot đó.

Cách lấy Group Chat ID

Cách đơn giản nhất: thêm bot @userinfobot vào group, nó sẽ trả về chat ID. Hoặc forward tin nhắn từ group tới bot đó.

Bước 6: Agent giao tiếp với nhau

Đây là phần thú vị nhất — các agent có thể trao đổi thông tin với nhau thông qua sessions_send.

Cơ chế hoạt động

OpenClaw cung cấp các tool cho inter-agent communication:

Ví dụ: Code Reviewer nhờ DevOps deploy

Khi Code Reviewer review xong code và cần deploy, nó có thể:

# Trong SOUL.md của code-reviewer, thêm hướng dẫn:
Khi review xong và code OK, gửi yêu cầu deploy đến DevOps agent:
- Dùng sessions_send với label "devops" 
- Kèm thông tin: branch, commit hash, môi trường deploy

Agent code-reviewer sẽ tự động gọi:

// OpenClaw tự động xử lý, agent chỉ cần gọi tool
sessions_send({
  label: "devops",
  message: "Deploy branch feature/auth lên staging. Commit: abc123. Đã review OK."
})

Ví dụ: Human giao việc qua Group

Trong Telegram group “AI Team”:

Human: @code_reviewer_bot review PR #42 trên repo backend

→ Code Reviewer agent nhận tin, review code, sau đó:

Code Reviewer: Review xong PR #42. Có 2 issues:
1. SQL injection ở line 45
2. Missing error handling ở line 78

@devops_bot giữ lại, chưa deploy PR này nhé.

Lúc này DevOps agent cũng nhận tin trong group và cập nhật trạng thái.

Cấu hình AGENTS.md cho collaboration

Mỗi agent cần biết về các agent khác. Thêm vào AGENTS.md của mỗi workspace:

## Đồng đội

- **code-reviewer**: Review code, tìm bugs. Gửi sessions_send(label: "code-reviewer")
- **devops**: Deploy, monitor server. Gửi sessions_send(label: "devops")  
- **writer**: Viết documentation, blog. Gửi sessions_send(label: "writer")

## Quy trình làm việc
1. Human giao task qua Telegram group hoặc DM
2. Agent thực hiện task
3. Nếu cần agent khác hỗ trợ → dùng sessions_send
4. Báo kết quả về Telegram group

Bước 7: Khởi động và kiểm tra

Start Gateway

# Foreground (debug)
openclaw gateway

# Background (production)
openclaw gateway start

Kiểm tra agents

# Liệt kê agents và bindings
openclaw agents list --bindings

# Kiểm tra container Docker
docker ps --filter "name=openclaw-sbx-"

# Xem logs
tail -f ~/.openclaw/logs/gateway.log | grep -E "routing|sandbox|agent"

Test giao tiếp

1. DM từng bot trên Telegram → Verify mỗi agent trả lời đúng personality
2. Gửi tin trong group → Verify agent nhận đúng tin nhắn
3. Yêu cầu agent A liên lạc agent B → Verify sessions_send hoạt động

Bước 8: Cron Jobs — Tự động hóa công việc

Mỗi agent có thể có scheduled tasks riêng:

// Ví dụ: DevOps agent check server health mỗi sáng
{
  schedule: { kind: "cron", expr: "0 9 * * *", tz: "Asia/Ho_Chi_Minh" },
  sessionTarget: "isolated",
  payload: {
    kind: "agentTurn",
    message: "Check server health: CPU, RAM, disk usage. Report qua Telegram.",
  },
  delivery: { mode: "announce", channel: "telegram" },
}

Ví dụ thực tế: Đội ngũ AI cho dự án phát triển phần mềm

Kịch bản

Bạn quản lý dự án, cần đội ngũ AI hỗ trợ:

Workflow hàng ngày

08:00  DevOps agent tự chạy health check → báo cáo qua Telegram
09:00  Human gửi "Review PR #50" trong group
09:01  Code Reviewer nhận task, clone repo, review
09:15  Code Reviewer gửi kết quả vào group + sessions_send cho DevOps
09:16  DevOps nhận "deploy approved" → chạy CI/CD
09:30  DevOps báo "deployed to staging" trong group
10:00  Human gửi "Writer, viết release notes cho v2.1"
10:01  Writer đọc commit history (sessions_history) → viết release notes
10:30  Writer gửi release notes vào group

Fullstack Station Tips

Tip 1: Dùng model phù hợp cho từng agent

Không phải agent nào cũng cần model đắt tiền:

{
  agents: {
    list: [
      {
        id: "code-reviewer",
        // Cần reasoning mạnh → dùng model tốt nhất
        model: "anthropic/claude-sonnet-4",
      },
      {
        id: "writer",
        // Task đơn giản hơn → model nhẹ, tiết kiệm
        model: "anthropic/claude-haiku-3.5",
      },
    ],
  },
}

Tip 2: Giới hạn tool chặt chẽ

Nguyên tắc least privilege — mỗi agent chỉ có tool cần thiết:

// Writer KHÔNG cần exec → deny nó
tools: {
  allow: ["read", "web_search", "web_fetch"],
  deny: ["exec", "write", "edit", "gateway", "browser"],
}

Dùng tool groups để cấu hình nhanh:

tools: {
  allow: ["group:fs", "group:sessions"],  // fs = read, write, edit
  deny: ["group:runtime"],                // runtime = exec, bash, process
}

Tip 3: Sandbox Docker cho production

Luôn bật sandbox cho agent chạy trong production:

agents: {
  defaults: {
    sandbox: {
      mode: "all",
      scope: "agent",
      workspaceAccess: "rw",
      docker: {
        network: "bridge",
        // Cài thêm tools nếu cần
        setupCommand: "apt-get update && apt-get install -y git python3",
      },
    },
  },
}

Lưu ý: setupCommand chỉ chạy một lần khi container được tạo. Nếu cần internet, phải set network: "bridge" (mặc định là "none" = không có mạng).

Tip 4: Monitor và debug

# Xem agent nào đang active
openclaw agents list --bindings

# Kiểm tra sandbox containers
docker ps --filter "name=openclaw-sbx-"

# Debug routing
tail -f ~/.openclaw/logs/gateway.log | grep routing

# Kiểm tra tại sao tool bị block
openclaw sandbox explain

Kết luận

Thiết kế đội ngũ AI Agent với OpenClaw không phức tạp như bạn nghĩ. Tóm lại 4 bước chính:

1. Tạo agent — mỗi agent có workspace, personality, và permissions riêng
2. Cấu hình routing — bindings quyết định tin nhắn đi đâu
3. Thiết lập communication — sessions_send cho phép agent nói chuyện với nhau
4. Docker sandbox — cô lập mỗi agent trong container riêng

Điểm mạnh lớn nhất của kiến trúc này là mỗi agent hoàn toàn độc lập — bạn có thể thêm, xóa, hoặc sửa một agent mà không ảnh hưởng đến agent khác. Và với Telegram group, bạn có một “phòng họp ảo” nơi cả đội ngũ AI trao đổi và phối hợp.

Hãy bắt đầu với 2-3 agent cho một dự án nhỏ, sau đó mở rộng dần. Đừng quên nguyên tắc: mỗi agent làm một việc, làm cho tốt.

—

Bài viết bổ sung: Trước khi triển khai production, hãy đọc Bảo mật, Giám sát và Governance cho đội ngũ AI Agent — phân tích sâu về rủi ro bảo mật, monitoring, và governance policy.

Bài viết sử dụng OpenClaw — nền tảng mã nguồn mở cho AI Agent. Source code: github.com/openclaw/openclaw

The post Hướng dẫn thực chiến: Thiết kế đội ngũ AI Agent với OpenClaw appeared first on Fullstack Station.