Onboarding Wizard (CLI)

Onboarding wizard là cách được khuyên dùng để thiết lập OpenClaw trên macOS, Linux, hoặc Windows (qua WSL2; rất khuyên dùng). Nó cấu hình Gateway local hoặc kết nối Gateway từ xa, cùng với channels, skills, và các thiết lập workspace mặc định trong một quy trình hướng dẫn duy nhất.

Lệnh chính để bắt đầu:

openclaw onboard

Cách nhanh nhất để chat lần đầu: mở Control UI (không cần setup channel). Chạy openclaw dashboard và chat trong trình duyệt. Tài liệu: Dashboard.

Cấu hình lại sau này:

openclaw configure

Khuyên dùng: thiết lập Brave Search API key để Agent có thể dùng web_search (web_fetch hoạt động mà không cần key). Cách dễ nhất: openclaw configure --section web để lưu tools.web.search.apiKey. Tài liệu: Web tools.

QuickStart vs Advanced

Wizard bắt đầu với QuickStart (mặc định) hoặc Advanced (toàn quyền kiểm soát).

QuickStart giữ các thiết lập mặc định:

• Gateway local (loopback)
• Workspace mặc định (hoặc workspace hiện có)
• Gateway port 18789
• Gateway auth Token (tự động tạo, ngay cả trên loopback)
• Tailscale exposure Off
• Telegram + WhatsApp DMs mặc định là allowlist (các bạn sẽ được hỏi số điện thoại)

Advanced cho phép tùy chỉnh từng bước (mode, workspace, gateway, channels, daemon, skills).

Wizard làm những gì

Local mode (mặc định) hướng dẫn các bạn qua:

• Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (khuyên dùng) hoặc setup-token (paste), cùng với các tùy chọn MiniMax/GLM/Moonshot/AI Gateway)
• Vị trí Workspace + bootstrap files
• Cài đặt Gateway (port/bind/auth/tailscale)
• Providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost (plugin), Signal)
• Cài đặt Daemon (LaunchAgent / systemd user unit)
• Kiểm tra sức khỏe
• Skills (khuyên dùng)

Remote mode chỉ cấu hình client local để kết nối tới Gateway ở nơi khác. Nó không cài đặt hoặc thay đổi gì trên remote host.

Để thêm các agent độc lập (workspace + sessions + auth riêng), dùng:

openclaw agents add <name>

Mẹo: --json không có nghĩa là chế độ non-interactive. Dùng --non-interactive (và --workspace) cho scripts.

Chi tiết quy trình (local)

1. Phát hiện config hiện có

   • Nếu ~/.openclaw/openclaw.json tồn tại, chọn Keep / Modify / Reset.
   • Chạy lại wizard không xóa gì trừ khi các bạn chọn Reset rõ ràng (hoặc truyền --reset).
   • Nếu config không hợp lệ hoặc chứa legacy keys, wizard dừng lại và yêu cầu các bạn chạy openclaw doctor trước khi tiếp tục.
   • Reset dùng trash (không bao giờ dùng rm) và cung cấp các phạm vi:
     • Chỉ Config
     • Config + credentials + sessions
     • Full reset (cũng xóa workspace)

2. Model/Auth

   • Anthropic API key (khuyên dùng): dùng ANTHROPIC_API_KEY nếu có hoặc hỏi key, sau đó lưu nó cho daemon dùng.
   • Anthropic OAuth (Claude Code CLI): trên macOS wizard kiểm tra Keychain item “Claude Code-credentials” (chọn “Always Allow” để launchd khởi động không bị chặn); trên Linux/Windows nó dùng lại ~/.claude/.credentials.json nếu có.
   • Anthropic token (paste setup-token): chạy claude setup-token trên bất kỳ máy nào, sau đó paste token (các bạn có thể đặt tên; để trống = default).
   • OpenAI Code (Codex) subscription (Codex CLI): nếu ~/.codex/auth.json tồn tại, wizard có thể dùng lại.
   • OpenAI Code (Codex) subscription (OAuth): browser flow; paste code#state.
     • Đặt agents.defaults.model thành openai-codex/gpt-5.2 khi model chưa được đặt hoặc là openai/*.
   • OpenAI API key: dùng OPENAI_API_KEY nếu có hoặc hỏi key, sau đó lưu vào ~/.openclaw/.env để launchd có thể đọc.
   • OpenCode Zen (multi-model proxy): hỏi OPENCODE_API_KEY (hoặc OPENCODE_ZEN_API_KEY, lấy tại https://opencode.ai/auth).
   • API key: lưu key cho các bạn.
   • Vercel AI Gateway (multi-model proxy): hỏi AI_GATEWAY_API_KEY.
   • Chi tiết thêm: Vercel AI Gateway
   • MiniMax M2.1: config được tự động ghi.
   • Chi tiết thêm: MiniMax
   • Synthetic (Anthropic-compatible): hỏi SYNTHETIC_API_KEY.
   • Chi tiết thêm: Synthetic
   • Moonshot (Kimi K2): config được tự động ghi.
   • Kimi Coding: config được tự động ghi.
   • Chi tiết thêm: Moonshot AI (Kimi + Kimi Coding)
   • Skip: chưa cấu hình auth.
   • Chọn model mặc định từ các tùy chọn được phát hiện (hoặc nhập provider/model thủ công).
   • Wizard chạy kiểm tra model và cảnh báo nếu model được cấu hình không xác định hoặc thiếu auth.

• OAuth credentials nằm trong ~/.openclaw/credentials/oauth.json; auth profiles nằm trong ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (API keys + OAuth).
• Chi tiết thêm: /concepts/oauth

3. Workspace

   • Mặc định ~/.openclaw/workspace (có thể cấu hình).
   • Tạo các workspace files cần thiết cho agent bootstrap ritual.
   • Layout workspace đầy đủ + hướng dẫn backup: Agent workspace

4. Gateway

   • Port, bind, auth mode, tailscale exposure.
   • Khuyến nghị auth: giữ Token ngay cả cho loopback để các WS clients local phải xác thực.
   • Chỉ tắt auth nếu các bạn hoàn toàn tin tưởng mọi process local.
   • Non-loopback binds vẫn yêu cầu auth.

5. Channels

   • WhatsApp: QR login tùy chọn.
   • Telegram: bot token.
   • Discord: bot token.
   • Google Chat: service account JSON + webhook audience.
   • Mattermost (plugin): bot token + base URL.
   • Signal: cài đặt signal-cli tùy chọn + account config.
   • iMessage: local imsg CLI path + DB access.
   • Bảo mật DM: mặc định là pairing. DM đầu tiên gửi một code; phê duyệt qua openclaw pairing approve <channel> <code> hoặc dùng allowlists.

6. Cài đặt Daemon

   • macOS: LaunchAgent
     • Yêu cầu user session đã đăng nhập; cho headless, dùng LaunchDaemon tùy chỉnh (không được cung cấp).
   • Linux (và Windows qua WSL2): systemd user unit
     • Wizard cố gắng bật lingering qua loginctl enable-linger <user> để Gateway vẫn chạy sau khi logout.
     • Có thể hỏi sudo (ghi /var/lib/systemd/linger); nó thử không dùng sudo trước.
   • Lựa chọn Runtime: Node (khuyên dùng; bắt buộc cho WhatsApp/Telegram). Bun không được khuyên dùng.

7. Kiểm tra sức khỏe

   • Khởi động Gateway (nếu cần) và chạy openclaw health.
   • Mẹo: openclaw status --deep thêm gateway health probes vào status output (yêu cầu gateway có thể truy cập).

8. Skills (khuyên dùng)

   • Đọc các skills có sẵn và kiểm tra yêu cầu.
   • Cho phép các bạn chọn node manager: npm / pnpm (bun không được khuyên dùng).
   • Cài đặt các dependencies tùy chọn (một số dùng Homebrew trên macOS).

9. Hoàn thành

   • Tóm tắt + các bước tiếp theo, bao gồm các ứng dụng iOS/Android/macOS cho thêm tính năng.

• Nếu không phát hiện GUI, wizard in hướng dẫn SSH port-forward cho Control UI thay vì mở trình duyệt.
• Nếu thiếu Control UI assets, wizard cố gắng build chúng; fallback là pnpm ui:build (tự động cài UI deps).

Remote mode

Remote mode cấu hình client local để kết nối tới Gateway ở nơi khác.

Các bạn sẽ thiết lập:

• Remote Gateway URL (ws://...)
• Token nếu remote Gateway yêu cầu auth (khuyên dùng)

Lưu ý:

• Không thực hiện cài đặt từ xa hoặc thay đổi daemon.
• Nếu Gateway chỉ loopback, dùng SSH tunneling hoặc tailnet.
• Gợi ý Discovery:
  • macOS: Bonjour (dns-sd)
  • Linux: Avahi (avahi-browse)

Thêm agent khác

Dùng openclaw agents add <name> để tạo agent riêng biệt với workspace, sessions, và auth profiles riêng. Chạy không có --workspace sẽ khởi động wizard.

Nó thiết lập:

• agents.list[].name
• agents.list[].workspace
• agents.list[].agentDir

Lưu ý:

• Workspaces mặc định theo ~/.openclaw/workspace-<agentId>.
• Thêm bindings để route inbound messages (wizard có thể làm điều này).
• Non-interactive flags: --model, --agent-dir, --bind, --non-interactive.

Chế độ Non-interactive

Dùng --non-interactive để tự động hóa hoặc script onboarding:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

Thêm --json cho tóm tắt machine-readable.

Ví dụ Gemini:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Ví dụ Z.AI:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice zai-api-key \
  --zai-api-key "$ZAI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Ví dụ Vercel AI Gateway:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice ai-gateway-api-key \
  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Ví dụ Moonshot:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice moonshot-api-key \
  --moonshot-api-key "$MOONSHOT_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Ví dụ Synthetic:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice synthetic-api-key \
  --synthetic-api-key "$SYNTHETIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Ví dụ OpenCode Zen:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice opencode-zen \
  --opencode-zen-api-key "$OPENCODE_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Ví dụ thêm agent (non-interactive):

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

Gateway wizard RPC

Gateway expose wizard flow qua RPC (wizard.start, wizard.next, wizard.cancel, wizard.status). Clients (macOS app, Control UI) có thể render các bước mà không cần implement lại onboarding logic.

Thiết lập Signal (signal-cli)

Wizard có thể cài đặt signal-cli từ GitHub releases:

• Download release asset phù hợp.
• Lưu nó dưới ~/.openclaw/tools/signal-cli/<version>/.
• Ghi channels.signal.cliPath vào config của các bạn.

Lưu ý:

• JVM builds yêu cầu Java 21.
• Native builds được dùng khi có sẵn.
• Windows dùng WSL2; cài đặt signal-cli theo quy trình Linux bên trong WSL.

Wizard ghi những gì

Các trường điển hình trong ~/.openclaw/openclaw.json:

• agents.defaults.workspace
• agents.defaults.model / models.providers (nếu chọn Minimax)
• gateway.* (mode, bind, auth, tailscale)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) khi các bạn chọn trong các prompts (names resolve thành IDs khi có thể).
• skills.install.nodeManager
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add ghi agents.list[] và bindings tùy chọn.

WhatsApp credentials nằm dưới ~/.openclaw/credentials/whatsapp/<accountId>/. Sessions được lưu dưới ~/.openclaw/agents/<agentId>/sessions/.

Một số channels được cung cấp dưới dạng plugins. Khi các bạn chọn một trong quá trình onboarding, wizard sẽ hỏi để cài đặt nó (npm hoặc local path) trước khi có thể cấu hình.

Tài liệu liên quan

• macOS app onboarding: Onboarding
• Config reference: Gateway configuration
• Providers: WhatsApp, Telegram, Discord, Google Chat, Signal, iMessage
• Skills: Skills, Skills config