Trình hướng dẫn Onboarding (CLI)

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

openclaw onboard

Info: Chat đầu tiên nhanh nhất: mở Control UI (không cần thiết lập kênh). Chạy openclaw dashboard và chat trong trình duyệt. Tài liệu: Dashboard.

Để cấu hình lại sau:

openclaw configure
openclaw agents add <name>

Lưu ý: --json không có nghĩa là chế độ không tương tác. Cho script, dùng --non-interactive.

Mẹo: Trình hướng dẫn onboarding bao gồm bước web search nơi bạn có thể chọn provider (Perplexity, Brave, Gemini, Grok hoặc Kimi) và dán API key để agent có thể dùng web_search. Bạn cũng có thể cấu hình sau bằng openclaw configure --section web. Tài liệu: Công cụ web.

QuickStart vs Nâng cao

Trình hướng dẫn bắt đầu với QuickStart (mặc định) vs Nâng cao (kiểm soát hoàn toàn).

QuickStart (mặc định)

- Gateway cục bộ (loopback)
- Workspace mặc định (hoặc workspace hiện có)
- Port Gateway **18789**
- Xác thực Gateway **Token** (tự tạo, kể cả trên loopback)
- Chính sách công cụ mặc định cho thiết lập cục bộ mới: `tools.profile: "coding"` (profile rõ ràng hiện có được giữ nguyên)
- Mặc định cách ly DM: onboarding cục bộ ghi `session.dmScope: "per-channel-peer"` khi chưa đặt. Chi tiết: [Tham khảo CLI Onboarding](/docs/start/wizard-cli-reference#outputs-and-internals)
- Tailscale **Tắt**
- Telegram + WhatsApp DM mặc định **allowlist** (sẽ hỏi số điện thoại)

Nâng cao (kiểm soát hoàn toàn)

- Hiển thị mọi bước (chế độ, workspace, gateway, kênh, daemon, skills).

Trình hướng dẫn cấu hình những gì

Chế độ cục bộ (mặc định) hướng dẫn bạn qua các bước:

  1. Model/Xác thực — chọn provider/quy trình xác thực được hỗ trợ (API key, OAuth hoặc setup-token), bao gồm Custom Provider (OpenAI-compatible, Anthropic-compatible hoặc Unknown tự phát hiện). Chọn model mặc định. Lưu ý bảo mật: nếu agent này sẽ chạy công cụ hoặc xử lý nội dung webhook/hook, ưu tiên model mạnh nhất thế hệ mới nhất và giữ chính sách công cụ nghiêm ngặt. Các cấp yếu/cũ hơn dễ bị prompt injection hơn. Cho chạy không tương tác, --secret-input-mode ref lưu env-backed ref trong auth profile thay vì giá trị plaintext API key. Trong chế độ ref không tương tác, biến môi trường provider phải được đặt; truyền flag key inline mà không có biến đó sẽ lỗi ngay. Trong chạy tương tác, chọn chế độ secret reference cho phép trỏ đến biến môi trường hoặc ref provider đã cấu hình (file hoặc exec), với kiểm tra preflight nhanh trước khi lưu.
  2. Workspace — Vị trí file agent (mặc định ~/.openclaw/workspace). Tạo file bootstrap.
  3. Gateway — Port, địa chỉ bind, chế độ xác thực, Tailscale. Trong chế độ tương tác token, chọn giữa lưu token plaintext mặc định hoặc opt-in SecretRef. Đường dẫn token SecretRef không tương tác: --gateway-token-ref-env <ENV_VAR>.
  4. Kênh — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles hoặc iMessage.
  5. Daemon — Cài LaunchAgent (macOS) hoặc systemd user unit (Linux/WSL2). Nếu xác thực token yêu cầu token và gateway.auth.token do SecretRef quản lý, cài daemon sẽ kiểm tra nhưng không lưu trữ token đã giải quyết vào metadata môi trường dịch vụ giám sát. Nếu xác thực token yêu cầu token và SecretRef token đã cấu hình chưa được giải quyết, cài daemon bị chặn kèm hướng dẫn hành động. Nếu cả gateway.auth.token và gateway.auth.password đều được cấu hình mà gateway.auth.mode chưa đặt, cài daemon bị chặn cho đến khi đặt mode rõ ràng.
  6. Health check — Khởi động Gateway và xác minh đang chạy.
  7. Skills — Cài skills khuyến nghị và dependency tùy chọn.

Lưu ý: Chạy lại trình hướng dẫn không xóa gì trừ khi bạn chọn rõ Reset (hoặc truyền --reset). CLI --reset mặc định là cấu hình, thông tin đăng nhập và session; dùng --reset-scope full để bao gồm workspace. Nếu cấu hình không hợp lệ hoặc chứa key legacy, trình hướng dẫn yêu cầu chạy openclaw doctor trước.

Chế độ từ xa chỉ cấu hình client cục bộ kết nối đến Gateway ở nơi khác. Nó không cài đặt hoặc thay đổi gì trên host từ xa.

Thêm agent khác

Dùng openclaw agents add <name> để tạo agent riêng với workspace, session và auth profile riêng. Chạy không có --workspace sẽ khởi động trình hướng dẫn.

Nó đặt:

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

Lưu ý:

  • Workspace mặc định theo mẫu ~/.openclaw/workspace-<agentId>.
  • Thêm bindings để định tuyến tin nhắn đến (trình hướng dẫn có thể làm việc này).
  • Flag không tương tác: --model, --agent-dir, --bind, --non-interactive.

Tham khảo đầy đủ

Phân tích chi tiết từng bước và đầu ra cấu hình, xem Tham khảo CLI Onboarding. Ví dụ không tương tác, xem CLI Automation. Tham khảo kỹ thuật sâu hơn, bao gồm chi tiết RPC, xem Tham khảo trình hướng dẫn.

Tài liệu liên quan

arrow_back
Trước
Onboarding Overview
Tiếp
Onboarding
arrow_forward