Tham khảo CLI Onboarding

Trang này là tham khảo đầy đủ cho openclaw onboard. Hướng dẫn ngắn xem Trình hướng dẫn Onboarding (CLI).

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

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

• Thiết lập model và xác thực (OpenAI Code subscription OAuth, Anthropic API key hoặc setup token, cùng tùy chọn MiniMax, GLM, Ollama, Moonshot và AI Gateway)
• Vị trí workspace và file bootstrap
• Thiết lập Gateway (port, bind, auth, tailscale)
• Kênh và provider (Telegram, WhatsApp, Discord, Google Chat, Mattermost plugin, Signal)
• Cài daemon (LaunchAgent hoặc systemd user unit)
• Health check
• Thiết lập skills

Chế độ từ xa cấu hình máy này kết nối đến gateway ở nơi khác. Không cài đặt hoặc thay đổi gì trên host từ xa.

Chi tiết quy trình cục bộ

Bước 1: Phát hiện cấu hình hiện có

- Nếu `~/.openclaw/openclaw.json` tồn tại, chọn Giữ, Sửa đổi hoặc Reset.
- Chạy lại trình hướng dẫn không xóa gì trừ khi bạn chọn Reset rõ ràng (hoặc truyền `--reset`).
- CLI `--reset` mặc định là `config+creds+sessions`; dùng `--reset-scope full` để xóa cả workspace.
- Nếu cấu hình không hợp lệ hoặc chứa key legacy, trình hướng dẫn dừng và yêu cầu chạy `openclaw doctor` trước.
- Reset dùng `trash` và cung cấp phạm vi:
  - Chỉ cấu hình
  - Cấu hình + thông tin đăng nhập + session
  - Reset hoàn toàn (xóa cả workspace)

Bước 2: Model và xác thực

- Ma trận tùy chọn đầy đủ tại [Tùy chọn xác thực và model](#tùy-chọn-xác-thực-và-model).

Bước 3: Workspace

- Mặc định `~/.openclaw/workspace` (có thể cấu hình).
- Tạo file workspace cần cho quy trình bootstrap lần đầu.
- Cấu trúc workspace: [Workspace của agent](/docs/concepts/agent-workspace).

Bước 4: Gateway

- Hỏi port, bind, chế độ xác thực và Tailscale.
- Khuyến nghị: giữ xác thực token bật kể cả cho loopback để client WS cục bộ phải xác thực.
- Trong chế độ token, onboarding tương tác cung cấp:
  - **Tạo/lưu token plaintext** (mặc định)
  - **Dùng SecretRef** (opt-in)
- Trong chế độ password, onboarding tương tác cũng hỗ trợ plaintext hoặc SecretRef.
- Đường dẫn token SecretRef không tương tác: `--gateway-token-ref-env <ENV_VAR>`.
  - Yêu cầu biến env không rỗng trong môi trường tiến trình onboarding.
  - Không thể kết hợp với `--gateway-token`.
- Chỉ tắt xác thực khi bạn hoàn toàn tin tưởng mọi tiến trình cục bộ.
- Bind không phải loopback vẫn yêu cầu xác thực.

Bước 5: Kênh

- [WhatsApp](/docs/channels/whatsapp): đăng nhập QR tùy chọn
- [Telegram](/docs/channels/telegram): bot token
- [Discord](/docs/channels/discord): bot token
- [Google Chat](/docs/channels/googlechat): service account JSON + webhook audience
- [Mattermost](/docs/channels/mattermost) plugin: bot token + base URL
- [Signal](/docs/channels/signal): cài `signal-cli` tùy chọn + cấu hình tài khoản
- [BlueBubbles](/docs/channels/bluebubbles): khuyến nghị cho iMessage; server URL + password + webhook
- [iMessage](/docs/channels/imessage): đường dẫn CLI `imsg` legacy + truy cập DB
- Bảo mật DM: mặc định là ghép nối. DM đầu tiên gửi mã; phê duyệt qua
  `openclaw pairing approve <channel> <code>` hoặc dùng allowlist.

Bước 6: Cài daemon

- macOS: LaunchAgent
  - Yêu cầu session người dùng đã đăng nhập; cho headless, dùng LaunchDaemon tùy chỉnh (không đi kèm).
- Linux và Windows qua WSL2: systemd user unit
  - Trình hướng dẫn cố `loginctl enable-linger <user>` để gateway tiếp tục chạy sau khi đăng xuất.
  - Có thể yêu cầu sudo (ghi vào `/var/lib/systemd/linger`); thử không sudo trước.
- Lựa chọn runtime: Node (khuyến nghị; bắt buộc cho WhatsApp và Telegram). Bun không khuyến nghị.

Bước 7: Health check

- Khởi động gateway (nếu cần) và chạy `openclaw health`.
- `openclaw status --deep` thêm health probe gateway vào đầu ra trạng thái.

Bước 8: Skills

- Đọc skills có sẵn và kiểm tra yêu cầu.
- Cho chọn trình quản lý node: npm hoặc pnpm (bun không khuyến nghị).
- Cài dependency tùy chọn (một số dùng Homebrew trên macOS).

Bước 9: Hoàn tất

- Tóm tắt và bước tiếp theo, bao gồm tùy chọn iOS, Android và macOS app.

Lưu ý: Nếu không phát hiện GUI, trình hướng dẫn in hướng dẫn SSH port-forward cho Control UI thay vì mở trình duyệt. Nếu thiếu asset Control UI, trình hướng dẫn cố build; phương án dự phòng là pnpm ui:build (tự cài dependency UI).

Chi tiết chế độ từ xa

Chế độ từ xa cấu hình máy này kết nối đến gateway ở nơi khác.

Info: Chế độ từ xa không cài đặt hoặc thay đổi gì trên host từ xa.

Bạn đặt:

• URL gateway từ xa (ws://...)
• Token nếu xác thực gateway từ xa yêu cầu (khuyến nghị)

Lưu ý:

• Nếu gateway chỉ loopback, dùng SSH tunneling hoặc tailnet.
• Gợi ý discovery:
  • macOS: Bonjour (dns-sd)
  • Linux: Avahi (avahi-browse)

Tùy chọn xác thực và model

Dùng `ANTHROPIC_API_KEY` nếu có hoặc hỏi key, rồi lưu cho daemon dùng.

- macOS: kiểm tra mục Keychain "Claude Code-credentials"
- Linux và Windows: tái sử dụng `~/.claude/.credentials.json` nếu có

Trên macOS, chọn "Always Allow" để khởi chạy launchd không bị chặn.

Chạy `claude setup-token` trên bất kỳ máy nào, rồi dán token.
Có thể đặt tên; để trống dùng mặc định.

Nếu `~/.codex/auth.json` tồn tại, trình hướng dẫn có thể tái sử dụng.

Quy trình trình duyệt; dán `code#state`.

Đặt `agents.defaults.model` thành `openai-codex/gpt-5.4` khi model chưa đặt hoặc là `openai/*`.

Dùng `OPENAI_API_KEY` nếu có hoặc hỏi key, rồi lưu credential vào auth profile.

Đặt `agents.defaults.model` thành `openai/gpt-5.1-codex` khi model chưa đặt, là `openai/*` hoặc `openai-codex/*`.

Hỏi `XAI_API_KEY` và cấu hình xAI làm model provider.

Hỏi `OPENCODE_API_KEY` (hoặc `OPENCODE_ZEN_API_KEY`) và cho chọn danh mục Zen hoặc Go.
URL thiết lập: [opencode.ai/auth](https://opencode.ai/auth).

Lưu key cho bạn.

Hỏi `AI_GATEWAY_API_KEY`.
Chi tiết: [Vercel AI Gateway](/docs/providers/vercel-ai-gateway).

Hỏi account ID, gateway ID và `CLOUDFLARE_AI_GATEWAY_API_KEY`.
Chi tiết: [Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway).

Cấu hình được tự động ghi.
Chi tiết: [MiniMax](/docs/providers/minimax).

Hỏi `SYNTHETIC_API_KEY`.
Chi tiết: [Synthetic](/docs/providers/synthetic).

Hỏi base URL (mặc định `http://127.0.0.1:11434`), rồi cung cấp chế độ Cloud + Local hoặc Local.
Tự phát hiện model có sẵn và gợi ý mặc định.
Chi tiết: [Ollama](/docs/providers/ollama).

Cấu hình Moonshot (Kimi K2) và Kimi Coding được tự động ghi.
Chi tiết: [Moonshot AI (Kimi + Kimi Coding)](/docs/providers/moonshot).

Hoạt động với endpoint OpenAI-compatible và Anthropic-compatible.

Onboarding tương tác hỗ trợ cùng lựa chọn lưu trữ API key như các quy trình API key provider khác:
- **Dán API key ngay** (plaintext)
- **Dùng secret reference** (env ref hoặc ref provider đã cấu hình, có kiểm tra preflight)

Flag không tương tác:
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (tùy chọn; dự phòng `CUSTOM_API_KEY`)
- `--custom-provider-id` (tùy chọn)
- `--custom-compatibility <openai|anthropic>` (tùy chọn; mặc định `openai`)

Xác thực giữ nguyên chưa cấu hình.

Hành vi model:

• Chọn model mặc định từ tùy chọn phát hiện được, hoặc nhập provider và model thủ công.
• Trình hướng dẫn chạy kiểm tra model và cảnh báo nếu model đã cấu hình không xác định hoặc thiếu xác thực.

Đường dẫn credential và profile:

• Credential OAuth: ~/.openclaw/credentials/oauth.json
• Auth profile (API key + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Chế độ lưu trữ credential:

• Hành vi onboarding mặc định lưu API key dưới dạng giá trị plaintext trong auth profile.
• --secret-input-mode ref bật chế độ tham chiếu thay vì lưu key plaintext. Trong onboarding tương tác, bạn có thể chọn:
  • ref biến môi trường (ví dụ keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • ref provider đã cấu hình (file hoặc exec) với alias provider + id
• Chế độ tham chiếu tương tác chạy kiểm tra preflight nhanh trước khi lưu.
  • Env ref: kiểm tra tên biến + giá trị không rỗng trong môi trường onboarding hiện tại.
  • Provider ref: kiểm tra cấu hình provider và giải quyết id yêu cầu.
  • Nếu preflight thất bại, onboarding hiển thị lỗi và cho thử lại.
• Trong chế độ không tương tác, --secret-input-mode ref chỉ hỗ trợ env.
  • Đặt biến env provider trong môi trường tiến trình onboarding.
  • Flag key inline (ví dụ --openai-api-key) yêu cầu biến env đó đã được đặt; nếu không onboarding lỗi ngay.
  • Cho custom provider, chế độ ref không tương tác lưu models.providers.<id>.apiKey dưới dạng { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • Trong trường hợp custom provider đó, --custom-api-key yêu cầu CUSTOM_API_KEY đã đặt; nếu không onboarding lỗi ngay.
• Credential xác thực Gateway hỗ trợ lựa chọn plaintext và SecretRef trong onboarding tương tác:
  • Chế độ token: Tạo/lưu token plaintext (mặc định) hoặc Dùng SecretRef.
  • Chế độ password: plaintext hoặc SecretRef.
• Đường dẫn token SecretRef không tương tác: --gateway-token-ref-env <ENV_VAR>.
• Thiết lập plaintext hiện có tiếp tục hoạt động bình thường.

Lưu ý: Mẹo cho headless và server: hoàn thành OAuth trên máy có trình duyệt, rồi copy ~/.openclaw/credentials/oauth.json (hoặc $OPENCLAW_STATE_DIR/credentials/oauth.json) sang host gateway.

Đầu ra và cơ chế nội bộ

Các trường thường gặp trong ~/.openclaw/openclaw.json:

• agents.defaults.workspace
• agents.defaults.model / models.providers (khi chọn Minimax)
• tools.profile (onboarding cục bộ mặc định "coding" khi chưa đặt; giá trị rõ ràng hiện có được giữ)
• gateway.* (mode, bind, auth, tailscale)
• session.dmScope (onboarding cục bộ mặc định per-channel-peer khi chưa đặt; giá trị rõ ràng hiện có được giữ)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• Allowlist kênh (Slack, Discord, Matrix, Microsoft Teams) khi bạn opt-in trong prompt (tên được giải quyết thành ID 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.

Credential WhatsApp nằm ở ~/.openclaw/credentials/whatsapp/<accountId>/. Session lưu ở ~/.openclaw/agents/<agentId>/sessions/.

Lưu ý: Một số kênh được cung cấp dưới dạng plugin. Khi chọn trong onboarding, trình hướng dẫn hỏi cài plugin (npm hoặc đường dẫn cục bộ) trước khi cấu hình kênh.

Gateway wizard RPC:

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

Client (ứng dụng macOS và Control UI) có thể render các bước mà không cần cài lại logic onboarding.

Hành vi thiết lập Signal:

• Tải asset release phù hợp
• Lưu ở ~/.openclaw/tools/signal-cli/<version>/
• Ghi channels.signal.cliPath trong cấu hình
• Bản JVM yêu cầu Java 21
• Bản native được dùng khi có sẵn
• Windows dùng WSL2 và theo quy trình Linux signal-cli trong WSL

Tài liệu liên quan

• Hub onboarding: Trình hướng dẫn Onboarding (CLI)
• Tự động hóa và script: CLI Automation
• Tham khảo lệnh: openclaw onboard