openclaw/translation/vietnamese/docs/start/wizard.vi.md

summary	read_when
Trình hướng dẫn thiết lập CLI (CLI onboarding wizard): hướng dẫn thiết lập gateway, không gian làm việc, các kênh và kỹ năng	Chạy hoặc cấu hình trình hướng dẫn thiết lập ban đầu Thiết lập trên một máy mới

Trình hướng dẫn Thiết lập (CLI Wizard)

Trình hướng dẫn thiết lập (onboarding wizard) là cách được khuyên dùng để cài đặt Moltbot trên macOS, Linux, hoặc Windows (thông qua WSL2; cực kỳ khuyến khích). Nó sẽ giúp cấu hình Gateway cục bộ hoặc kết nối Gateway từ xa, cùng với các kênh, kỹ năng và không gian làm việc mặc định trong một quy trình hướng dẫn duy nhất.

Lối vào chính:

moltbot onboard

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

Tái cấu hình sau này:

moltbot configure

Khuyên dùng: thiết lập API key của Brave Search để agent có thể dùng lệnh web_search (web_fetch vẫn hoạt động mà không cần key). Cách dễ nhất: moltbot configure --section web, lệnh này sẽ lưu vào tools.web.search.apiKey. Tài liệu: Công cụ Web.

QuickStart (Bắt đầu nhanh) vs Advanced (Nâng cao)

Trình hướng dẫn bắt đầu bằng việc chọn QuickStart (dùng mặc định) vs Advanced (toàn quyền kiểm soát).

QuickStart sẽ giữ các mặc định sau:

• Gateway cục bộ (loopback)
• Không gian làm việc mặc định (hoặc không gian hiện có)
• Cổng Gateway 18789
• Xác thực Gateway dùng Token (tự động tạo, kể cả trên loopback)
• Công khai qua Tailscale: Tắt
• Tin nhắn DM trên Telegram + WhatsApp mặc định là danh sách phê duyệt (allowlist) (bạn sẽ được hỏi số điện thoại)

Advanced sẽ hiển thị mọi bước (chế độ, không gian làm việc, gateway, các kênh, dịch vụ chạy ngầm, kỹ năng).

Trình hướng dẫn làm những gì?

Chế độ Local (mặc định) sẽ dẫn dắt bạn qua:

• Model/Auth (Xác thực): Đăng ký OpenAI Code (Codex) OAuth, Anthropic API key (khuyên dùng) hoặc setup-token (dán mã), cùng các lựa chọn MiniMax/GLM/Moonshot/AI Gateway.
• Vị trí không gian làm việc (Workspace) + các file khởi tạo ban đầu.
• Thiết lập Gateway (cổng/bind/xác thực/tailscale).
• Nhà cung cấp (Providers): Telegram, WhatsApp, Discord, Google Chat, Mattermost (plugin), Signal.
• Cài đặt dịch vụ chạy ngầm (LaunchAgent / systemd user unit).
• Kiểm tra sức khỏe hệ thống.
• Kỹ năng (Khuyên dùng).

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

Để thêm các agent riêng biệt khác (không gian làm việc + phiên làm việc + xác thực riêng), hãy dùng:

moltbot agents add <tên>

Mẹo: cờ --json không có nghĩa là chế độ không tương tác. Hãy dùng --non-interactive (và --workspace) cho các kịch bản script.

Chi tiết quy trình (Bản cục bộ)

1. Phát hiện cấu hình hiện có

   • Nếu file ~/.clawdbot/moltbot.json đã tồn tại, hãy chọn Keep (Giữ) / Modify (Sửa) / Reset (Đặt lại).
   • Chạy lại trình hướng dẫn sẽ không xóa gì trừ khi bạn chọn Reset rõ ràng (hoặc dùng cờ --reset).
   • Nếu cấu hình không hợp lệ hoặc chứa các khóa cũ, trình hướng dẫn sẽ dừng lại và yêu cầu bạn chạy moltbot doctor trước khi tiếp tục.
   • Reset sử dụng lệnh trash (thùng rác) thay vì rm và cung cấp các phạm vi:
     • Chỉ cấu hình
     • Cấu hình + thông tin đăng nhập + các phiên làm việc
     • Đặt lại hoàn toàn (xóa cả không gian làm việc)

2. Model/Auth (Mô hình/Xác thực)

   • Anthropic API key (khuyên dùng): dùng biến ANTHROPIC_API_KEY nếu có hoặc yêu cầu nhập key, sau đó lưu lại để dịch vụ chạy ngầm sử dụng.
   • Anthropic OAuth (Claude Code CLI): trên macOS, wizard kiểm tra mục Keychain "Claude Code-credentials"; trên Linux/Windows, nó dùng lại ~/.claude/.credentials.json nếu có.
   • Mã Anthropic (Dán setup-token): chạy claude setup-token trên bất kỳ máy nào, sau đó dán mã vào.
   • OpenAI Code (Codex) (OAuth): quy trình qua trình duyệt; dán mã code#state.
     • Thiết lập agents.defaults.model thành openai-codex/gpt-5.2.
   • OpenAI API key: dùng biến OPENAI_API_KEY nếu có hoặc yêu cầu nhập key, sau đó lưu vào ~/.clawdbot/.env.
   • Skip (Bỏ qua): chưa thiết lập xác thực.
   • Chọn một mô hình mặc định từ các tùy chọn được phát hiện.
   • Wizard sẽ kiểm tra mô hình và cảnh báo nếu mô hình không xác định hoặc thiếu xác thực.
   • Thông tin OAuth nằm ở ~/.clawdbot/credentials/oauth.json; hồ sơ xác thực nằm ở ~/.clawdbot/agents/<agentId>/agent/auth-profiles.json.
   • Chi tiết: Khái niệm OAuth

3. Không gian làm việc (Workspace)

   • Mặc định là ~/clawd (có thể cấu hình).
   • Khởi tạo các file cần thiết cho nghi thức khởi động agent.
   • Sơ đồ không gian làm việc + hướng dẫn sao lưu: Workspace của Agent

4. Gateway

   • Cổng (Port), bind, chế độ xác thực, công khai tailscale.
   • Khuyến nghị xác thực: hãy giữ chế độ Token kể cả trên loopback để các client WebSocket cục bộ bắt buộc phải xác thực.

5. Kênh (Channels)

   • WhatsApp: đăng nhập tùy chọn qua QR.
   • Telegram/Discord: mã Token của bot.
   • Google Chat: file JSON tài khoản dịch vụ.
   • An toàn DM: mặc định là ghép nối (pairing). Tin nhắn DM đầu tiên sẽ gửi một mã; phê duyệt qua lệnh moltbot pairing approve <kênh> <mã>.

6. Cài đặt dịch vụ chạy ngầm (Daemon)

   • macOS: LaunchAgent.
   • Linux (và Windows qua WSL2): systemd user unit.
     • Wizard sẽ cố gắng kích hoạt tính năng duy trì (lingering) qua loginctl enable-linger <user> để Gateway vẫn chạy sau khi bạn đăng xuất.
   • 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 (Health check)

   • Khởi động Gateway (nếu cần) và chạy moltbot health.

8. Kỹ năng (Skills - khuyên dùng)

   • Đọc các kỹ năng có sẵn và kiểm tra yêu cầu.
   • Cho phép bạn chọn trình quản lý node: npm / pnpm.

9. Hoàn tất

   • Tóm tắt + các bước tiếp theo, bao gồm link tải app iOS/Android/macOS.

Chế độ Remote (Từ xa)

Chế độ Remote cấu hình client cục bộ để kết nối đến một Gateway ở nơi khác. Những gì bạn sẽ thiết lập:

• URL Gateway từ xa (ws://...)
• Token nếu Gateway yêu cầu xác thực (khuyên dùng)

Lưu ý:

• Không có việc cài đặt hay thay đổi dịch vụ nào được thực hiện từ xa.
• Nếu Gateway chỉ cho phép loopback, hãy dùng SSH tunneling hoặc tailnet.

Thêm agent khác

Dùng moltbot agents add <tên> để tạo một agent riêng biệt với không gian làm việc, các phiên và hồ sơ xác thực riêng. Chạy mà không có cờ --workspace sẽ khởi chạy wizard.

Chế độ không tương tác (Non‑interactive)

Sử dụng --non-interactive để tự động hóa việc thiết lập:

moltbot onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --install-daemon \
  --daemon-runtime node

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

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

• Tải về bản phát hành phù hợp.
• Lưu vào ~/.clawdbot/tools/signal-cli/<phiên_bản>/.
• Ghi khóa channels.signal.cliPath vào cấu hình của bạn.

---

Tài liệu liên quan: Cấu hình Gateway, WhatsApp, Kỹ năng.