Bắt Đầu

Mục tiêu: đi từ con số 0 → chat hoạt động đầu tiên (với cấu hình mặc định hợp lý) nhanh nhất có thể.

Cách chat nhanh nhất: mở Control UI (không cần setup channel). Chạy openclaw dashboard và chat trong trình duyệt, hoặc mở http://127.0.0.1:18789/ trên máy chủ gateway. Tài liệu: Dashboard và Control UI.

Cách được khuyên dùng: sử dụng CLI onboarding wizard (openclaw onboard). Nó sẽ thiết lập:

  • model/auth (khuyên dùng OAuth)
  • cài đặt gateway
  • channels (WhatsApp/Telegram/Discord/Mattermost (plugin)/…)
  • pairing mặc định (DM bảo mật)
  • workspace bootstrap + skills
  • dịch vụ chạy nền tùy chọn

Nếu các bạn muốn xem các trang tham khảo chi tiết hơn, nhảy đến: Wizard, Setup, Pairing, Security.

Lưu ý về Sandboxing: agents.defaults.sandbox.mode: "non-main" sử dụng session.mainKey (mặc định "main"), nên các session nhóm/channel sẽ được sandbox. Nếu các bạn muốn agent chính luôn chạy trên host, hãy đặt override rõ ràng cho từng agent:

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

0) Yêu cầu trước khi bắt đầu

  • Node >=22
  • pnpm (tùy chọn; khuyên dùng nếu các bạn build từ source)
  • Khuyên dùng: Brave Search API key cho tìm kiếm web. Cách dễ nhất: openclaw configure --section web (lưu tools.web.search.apiKey). Xem Web tools.

macOS: nếu các bạn định build các app, hãy cài Xcode / CLT. Chỉ dùng CLI + gateway thì Node là đủ. Windows: dùng WSL2 (khuyên dùng Ubuntu). WSL2 được khuyên dùng mạnh mẽ; Windows gốc chưa được test, có nhiều vấn đề hơn, và tương thích công cụ kém hơn. Cài WSL2 trước, sau đó chạy các bước Linux bên trong WSL. Xem Windows (WSL2).

1) Cài đặt CLI (khuyên dùng)

curl -fsSL https://openclaw.ai/install.sh | bash

Các tùy chọn cài đặt (phương thức cài đặt, không tương tác, từ GitHub): Install.

Windows (PowerShell):

iwr -useb https://openclaw.ai/install.ps1 | iex

Cách khác (cài đặt global):

npm install -g openclaw@latest
pnpm add -g openclaw@latest

2) Chạy onboarding wizard (và cài đặt service)

openclaw onboard --install-daemon

Những gì các bạn sẽ chọn:

  • Gateway Local hay Remote
  • Auth: OpenAI Code (Codex) subscription (OAuth) hoặc API keys. Với Anthropic mình khuyên dùng API key; claude setup-token cũng được hỗ trợ.
  • Providers: WhatsApp QR login, Telegram/Discord bot tokens, Mattermost plugin tokens, v.v.
  • Daemon: cài đặt chạy nền (launchd/systemd; WSL2 dùng systemd)
    • Runtime: Node (khuyên dùng; bắt buộc cho WhatsApp/Telegram). Bun không được khuyên dùng.
  • Gateway token: wizard tạo một token mặc định (ngay cả trên loopback) và lưu nó trong gateway.auth.token.

Tài liệu Wizard: Wizard

Auth: nó nằm ở đâu (quan trọng)

  • Cách Anthropic được khuyên dùng: đặt API key (wizard có thể lưu nó để service sử dụng). claude setup-token cũng được hỗ trợ nếu các bạn muốn tái sử dụng credentials của Claude Code.

  • OAuth credentials (import cũ): ~/.openclaw/credentials/oauth.json

  • Auth profiles (OAuth + API keys): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Mẹo cho Headless/server: làm OAuth trên máy bình thường trước, sau đó copy oauth.json sang máy chủ gateway.

3) Khởi động Gateway

Nếu các bạn đã cài service trong quá trình onboarding, Gateway nên đang chạy rồi:

openclaw gateway status

Chạy thủ công (foreground):

openclaw gateway --port 18789 --verbose

Dashboard (local loopback): http://127.0.0.1:18789/ Nếu token được cấu hình, paste nó vào cài đặt Control UI (lưu dưới dạng connect.params.auth.token).

⚠️ Cảnh báo Bun (WhatsApp + Telegram): Bun có các vấn đề đã biết với các channels này. Nếu các bạn dùng WhatsApp hoặc Telegram, hãy chạy Gateway với Node.

3.5) Kiểm tra nhanh (2 phút)

openclaw status
openclaw health
openclaw security audit --deep

4) Pair + kết nối chat surface đầu tiên

WhatsApp (QR login)

openclaw channels login

Quét qua WhatsApp → Settings → Linked Devices.

Tài liệu WhatsApp: WhatsApp

Telegram / Discord / khác

Wizard có thể viết tokens/config cho các bạn. Nếu các bạn thích config thủ công, bắt đầu với:

Mẹo Telegram DM: DM đầu tiên của các bạn trả về một pairing code. Approve nó (xem bước tiếp theo) hoặc bot sẽ không phản hồi.

5) An toàn DM (pairing approvals)

Tư thế mặc định: các DM không xác định nhận một code ngắn và tin nhắn không được xử lý cho đến khi được approve. Nếu DM đầu tiên của các bạn không có phản hồi, hãy approve pairing:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

Tài liệu Pairing: Pairing

Từ source (development)

Nếu các bạn đang hack trên chính OpenClaw, hãy chạy từ source:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # tự động cài UI deps ở lần chạy đầu tiên
pnpm build
openclaw onboard --install-daemon

Nếu các bạn chưa có cài đặt global, hãy chạy bước onboarding qua pnpm openclaw ... từ repo. pnpm build cũng bundle các A2UI assets; nếu các bạn chỉ cần chạy bước đó, dùng pnpm canvas:a2ui:bundle.

Gateway (từ repo này):

node openclaw.mjs gateway --port 18789 --verbose

7) Xác minh end-to-end

Trong terminal mới, gửi một tin nhắn test:

openclaw message send --target +15555550123 --message "Hello from OpenClaw"

Nếu openclaw health hiển thị “no auth configured”, quay lại wizard và đặt OAuth/key auth — agent sẽ không thể phản hồi nếu không có nó.

Mẹo: openclaw status --all là báo cáo debug read-only tốt nhất để paste. Health probes: openclaw health (hoặc openclaw status --deep) hỏi gateway đang chạy để lấy health snapshot.

Các bước tiếp theo (tùy chọn, nhưng tuyệt vời)