Chuyển đến nội dung chính
Đây là tài liệu tham khảo đầy đủ cho openclaw onboard. Để xem tổng quan cấp cao, hãy xem Onboarding (CLI). Để biết hành vi và đầu ra theo từng bước, hãy xem Tài liệu tham khảo thiết lập CLI.

​
Chi tiết luồng (chế độ cục bộ)

1

Đặt lại (không bắt buộc)

  • --reset đặt lại trạng thái trước khi chạy thiết lập; nếu không có tùy chọn này, việc chạy lại quy trình onboarding sẽ giữ cấu hình hiện có và tái sử dụng cấu hình đó làm giá trị mặc định.
  • --reset-scope kiểm soát những gì --reset xóa: config (chỉ tệp cấu hình ), config+creds+sessions (mặc định), hoặc full (cũng xóa workspace).
  • Nếu tệp cấu hình không hợp lệ, quy trình onboarding sẽ dừng và yêu cầu bạn chạy openclaw doctor trước, sau đó chạy lại thiết lập.
  • Thao tác đặt lại chuyển trạng thái vào Thùng rác (không bao giờ xóa trực tiếp).
2

Xác nhận rủi ro

  • Lần chạy đầu tiên (hoặc bất kỳ lần chạy nào trước khi wizard.securityAcknowledgedAt được đặt) yêu cầu bạn xác nhận rằng bạn hiểu các agent rất mạnh và việc cấp toàn quyền truy cập hệ thống tiềm ẩn rủi ro.
  • --non-interactive yêu cầu chỉ định rõ --accept-risk; nếu không có tùy chọn này, quy trình onboarding sẽ thoát với lỗi thay vì hiển thị lời nhắc.
  • Các lần chạy tương tác sẽ hiển thị lời nhắc xác nhận thay cho cờ này; nếu từ chối, quá trình thiết lập sẽ bị hủy.
3

Mô hình/Xác thực

  • Khóa API Anthropic: sử dụng ANTHROPIC_API_KEY nếu có hoặc yêu cầu nhập khóa, sau đó lưu khóa để daemon sử dụng.
  • Anthropic Claude CLI: đường dẫn cục bộ ưu tiên khi đã có phiên đăng nhập Claude CLI; OpenClaw vẫn hỗ trợ xác thực bằng setup-token của Anthropic như một phương án thay thế.
  • Gói đăng ký OpenAI Code (Codex) (OAuth): luồng trình duyệt; dán code#state.
    • Trong thiết lập mới chưa có mô hình chính, đặt agents.defaults.model thành openai/gpt-5.6-sol thông qua runtime Codex.
  • Gói đăng ký OpenAI Code (Codex) (ghép nối thiết bị): luồng ghép nối trong trình duyệt bằng mã thiết bị có thời hạn ngắn.
    • Trong thiết lập mới chưa có mô hình chính, đặt agents.defaults.model thành openai/gpt-5.6-sol thông qua runtime Codex.
  • Khóa API OpenAI: sử dụng OPENAI_API_KEY nếu có hoặc yêu cầu nhập khóa, sau đó lưu khóa trong các hồ sơ xác thực.
    • Trong thiết lập mới chưa có mô hình chính, đặt agents.defaults.model thành openai/gpt-5.6; ID mô hình API trực tiếp không có tiền tố được phân giải sang tầng Sol.
  • Việc thêm hoặc xác thực lại OpenAI giữ nguyên mô hình chính đã được chỉ định rõ, bao gồm openai/gpt-5.5. Nếu tài khoản không cung cấp GPT-5.6, hãy chọn rõ openai/gpt-5.5; OpenClaw không âm thầm hạ cấp mô hình.
  • OAuth xAI: đăng nhập trong trình duyệt bằng mã thiết bị mà không cần callback localhost, vì vậy cũng hoạt động qua SSH/Docker/VPS (--auth-choice xai-oauth).
  • Khóa API xAI: yêu cầu nhập XAI_API_KEY (--auth-choice xai-api-key).
  • --auth-choice xai-device-code vẫn hoạt động như một bí danh tương thích chỉ dùng thủ công cho cùng luồng mã thiết bị OAuth xAI; hãy dùng xai-oauth cho các script mới.
  • OpenCode: yêu cầu nhập OPENCODE_API_KEY (hoặc OPENCODE_ZEN_API_KEY, lấy tại https://opencode.ai/auth) và cho phép bạn chọn danh mục Zen hoặc Go.
  • Ollama: trước tiên cung cấp Đám mây + Cục bộ, Chỉ đám mây hoặc Chỉ cục bộ. Cloud only yêu cầu nhập OLLAMA_API_KEY và sử dụng https://ollama.com; các chế độ dựa trên máy chủ yêu cầu URL cơ sở Ollama (mặc định http://127.0.0.1:11434), khám phá các mô hình khả dụng và tự động pull mô hình cục bộ đã chọn khi cần; Cloud + Local cũng kiểm tra xem máy chủ Ollama đó đã đăng nhập để truy cập đám mây hay chưa.
  • Chi tiết hơn: Ollama
  • Khóa API: lưu khóa cho bạn.
  • Vercel AI Gateway (proxy đa mô hình): yêu cầu nhập AI_GATEWAY_API_KEY.
  • Chi tiết hơn: Vercel AI Gateway
  • Cloudflare AI Gateway: yêu cầu nhập ID tài khoản, ID Gateway và CLOUDFLARE_AI_GATEWAY_API_KEY.
  • Chi tiết hơn: Cloudflare AI Gateway
  • MiniMax: cấu hình được tự động ghi; giá trị mặc định được lưu trữ là MiniMax-M3. Thiết lập bằng khóa API sử dụng minimax/..., còn thiết lập OAuth sử dụng minimax-portal/....
  • Chi tiết hơn: MiniMax
  • StepFun: cấu hình được tự động ghi cho StepFun tiêu chuẩn hoặc Step Plan trên các endpoint tại Trung Quốc hoặc toàn cầu.
  • Chế độ tiêu chuẩn hiện mặc định là step-3.5-flash; Step Plan cũng bao gồm step-3.5-flash-2603.
  • Chi tiết hơn: StepFun
  • Synthetic (tương thích Anthropic): yêu cầu nhập SYNTHETIC_API_KEY.
  • Chi tiết hơn: Synthetic
  • Moonshot (Kimi K2): cấu hình được tự động ghi.
  • Kimi Coding: cấu hình được tự động ghi.
  • Chi tiết hơn: Moonshot AI (Kimi + Kimi Coding)
  • Nhà cung cấp tùy chỉnh: hoạt động với các endpoint tương thích OpenAI, tương thích OpenAI Responses hoặc tương thích Anthropic. Các cờ không tương tác: --auth-choice custom-api-key, --custom-base-url, --custom-model-id, --custom-api-key (không bắt buộc; dự phòng về CUSTOM_API_KEY), --custom-provider-id (không bắt buộc; tự động suy ra từ URL cơ sở), --custom-compatibility openai|openai-responses|anthropic (mặc định openai), --custom-image-input / --custom-text-input (ghi đè việc phát hiện mô hình thị giác được suy ra).
  • Bỏ qua: chưa cấu hình 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 (hoặc nhập thủ công nhà cung cấp/mô hình). Để có chất lượng tốt nhất và giảm rủi ro chèn prompt, hãy chọn mô hình thế hệ mới nhất mạnh nhất có trong ngăn xếp nhà cung cấp của bạn.
  • Quy trình onboarding chạy kiểm tra mô hình và cảnh báo nếu mô hình đã cấu hình không xác định hoặc thiếu xác thực.
  • Chế độ lưu trữ khóa API mặc định dùng các giá trị hồ sơ xác thực dạng văn bản thuần. Sử dụng --secret-input-mode ref để lưu các tham chiếu dựa trên biến môi trường thay thế (ví dụ keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }); biến môi trường được tham chiếu phải được đặt sẵn, nếu không quy trình onboarding sẽ thất bại ngay.
  • Các hồ sơ xác thực nằm trong ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (khóa API + OAuth). ~/.openclaw/credentials/oauth.json là nguồn cũ chỉ dùng để nhập.
  • Chi tiết hơn: OAuth
Mẹo cho máy không giao diện/máy chủ: hoàn tất OAuth trên máy có trình duyệt, sau đó sao chép auth-profiles.json của agent đó (ví dụ ~/.openclaw/agents/<agentId>/agent/auth-profiles.json, hoặc đường dẫn $OPENCLAW_STATE_DIR/... tương ứng) sang máy chủ Gateway. credentials/oauth.json chỉ là nguồn nhập cũ.
4

Workspace

  • Mặc định ~/.openclaw/workspace (có thể cấu hình).
  • Khởi tạo các tệp workspace cần thiết cho quy trình bootstrap agent.
  • Bố cục workspace đầy đủ + hướng dẫn sao lưu: Workspace của agent
5

Gateway

  • Cổng (mặc định 18789), địa chỉ liên kết, chế độ xác thực, khả năng truy cập qua Tailscale.
  • Khuyến nghị xác thực: giữ Token ngay cả với loopback để các máy khách WS cục bộ phải xác thực.
  • Ở chế độ token, thiết lập tương tác cung cấp:
    • Tạo/lưu token dạng văn bản thuần (mặc định)
    • Sử dụng SecretRef (chủ động chọn)
    • Quickstart tái sử dụng các SecretRef gateway.auth.token hiện có trên các nhà cung cấp env, file và exec để thăm dò trong quy trình onboarding/bootstrap bảng điều khiển.
    • Nếu SecretRef đó đã được cấu hình nhưng không thể phân giải, quy trình onboarding sẽ thất bại sớm với thông báo khắc phục rõ ràng thay vì âm thầm làm suy giảm xác thực runtime.
  • Ở chế độ mật khẩu, thiết lập tương tác cũng hỗ trợ lưu trữ dạng văn bản thuần hoặc SecretRef.
  • Đường dẫn SecretRef token không tương tác: --gateway-token-ref-env <ENV_VAR>.
    • Yêu cầu một biến môi trường không rỗng trong môi trường của tiến trình onboarding.
    • Không thể kết hợp với --gateway-token.
  • Chỉ tắt xác thực nếu bạn hoàn toàn tin cậy mọi tiến trình cục bộ.
  • Các địa chỉ liên kết không phải loopback vẫn yêu cầu xác thực.
6

Kênh

  • WhatsApp: đăng nhập QR không bắt buộc.
  • Telegram: token bot.
  • Discord: token bot.
  • Google Chat: JSON tài khoản dịch vụ + đối tượng Webhook.
  • Mattermost (Plugin): token bot + URL cơ sở.
  • Signal (Plugin): cài đặt signal-cli không bắt buộc + cấu hình tài khoản.
  • iMessage: đường dẫn CLI imsg + quyền truy cập cơ sở dữ liệu Messages; sử dụng trình bao bọc SSH khi Gateway chạy ngoài máy Mac.
  • Discord, Feishu, Microsoft Teams, QQ Bot, Slack và các kênh khác được phân phối dưới dạng Plugin mà quy trình onboarding có thể cài đặt giúp bạn. Danh mục đầy đủ: Kênh.
  • Bảo mật tin nhắn trực tiếp: mặc định là ghép nối. Tin nhắn trực tiếp đầu tiên gửi một mã; phê duyệt qua openclaw pairing approve <channel> <code> hoặc sử dụng danh sách cho phép.
7

Tìm kiếm web

  • Chọn một nhà cung cấp được hỗ trợ như Brave, Codex (Tìm kiếm được lưu trữ), DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Parallel, Perplexity, SearXNG hoặc Tavily (hoặc bỏ qua).
  • Các nhà cung cấp dựa trên API có thể sử dụng biến môi trường hoặc cấu hình hiện có để thiết lập nhanh; các nhà cung cấp không cần khóa sử dụng các điều kiện tiên quyết riêng của từng nhà cung cấp.
  • Bỏ qua bằng --skip-search.
  • Cấu hình sau: openclaw configure --section web.
8

Cài đặt daemon

  • macOS: LaunchAgent
    • Yêu cầu phiên người dùng đã đăng nhập; đối với máy không giao diện, hãy sử dụng LaunchDaemon tùy chỉnh (không được phân phối kèm).
  • Linux (và Windows qua WSL2): đơn vị người dùng systemd
    • Quy trình onboarding cố gắng bật lingering qua loginctl enable-linger <user> để Gateway tiếp tục chạy sau khi đăng xuất.
    • Có thể yêu cầu sudo (ghi /var/lib/systemd/linger); trước tiên, quy trình sẽ thử không dùng sudo.
  • Windows gốc: ưu tiên Scheduled Task; nếu việc tạo tác vụ bị từ chối, OpenClaw dự phòng sang một mục đăng nhập trong thư mục Startup dành cho từng người dùng và khởi động Gateway ngay lập tức.
  • Lựa chọn runtime: Node là bắt buộc vì kho lưu trữ trạng thái runtime chuẩn sử dụng node:sqlite. Các dịch vụ Bun cũ được di chuyển sang Node trong quá trình sửa chữa.
  • Nếu xác thực token yêu cầu token và gateway.auth.token được SecretRef quản lý, quá trình cài đặt daemon sẽ xác thực nó nhưng không lưu các giá trị token dạng văn bản thuần đã phân giải vào siêu dữ liệu môi trường dịch vụ của trình 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 phân giải, quá trình cài đặt daemon sẽ bị chặn với hướng dẫn có thể thực hiện.
  • Nếu cả gateway.auth.token và gateway.auth.password đều được cấu hình nhưng gateway.auth.mode chưa được đặt, quá trình cài đặt daemon sẽ bị chặn cho đến khi chế độ được đặt rõ ràng.
9

Kiểm tra tình trạng

  • Khởi động Gateway (nếu cần) và chạy openclaw health.
  • Mẹo: openclaw status --deep thêm bước thăm dò tình trạng Gateway trực tiếp vào đầu ra trạng thái, bao gồm các bước thăm dò kênh khi được hỗ trợ (yêu cầu Gateway có thể truy cập).
10

Skills (khuyên dùng)

  • Đọc các skill khả dụng và kiểm tra yêu cầu.
  • Cho phép bạn chọn trình quản lý Node: npm / pnpm / bun.
  • Tự động cài đặt các phần phụ thuộc không bắt buộc cho các skill tích hợp đáng tin cậy (một số skill sử dụng Homebrew trên macOS).
  • Bỏ qua các skill không có điều kiện tiên quyết về trình cài đặt Homebrew, uv hoặc Go, nhóm chúng cùng hướng dẫn thiết lập thủ công và chỉ bạn đến openclaw doctor sau khi điều kiện tiên quyết được cài đặt.
11

Hoàn tất

  • Tóm tắt + các bước tiếp theo, bao gồm lời nhắc Bạn muốn cho agent của mình nở như thế nào? dành cho Terminal, Trình duyệt hoặc để sau.
Nếu không phát hiện thấy GUI, quy trình thiết lập ban đầu sẽ in hướng dẫn chuyển tiếp cổng SSH cho Control UI thay vì mở trình duyệt. Nếu thiếu các tài nguyên Control UI, quy trình thiết lập ban đầu sẽ thử xây dựng chúng; phương án dự phòng là pnpm ui:build (tự động cài đặt các phần phụ thuộc của UI).

​
Chế độ không tương tác

Sử dụng --non-interactive --accept-risk để tự động hóa hoặc tạo tập lệnh cho quy trình thiết lập ban đầu (cờ này là xác nhận rủi ro bắt buộc; quy trình thiết lập ban đầu sẽ thoát với lỗi nếu không có cờ này):
Thêm --json để nhận bản tóm tắt có thể đọc bằng máy. SecretRef của token Gateway trong chế độ không tương tác:
--gateway-token và --gateway-token-ref-env loại trừ lẫn nhau.
--json không đồng nghĩa với chế độ không tương tác. Sử dụng --non-interactive --accept-risk (và --workspace) cho các tập lệnh.
Các ví dụ lệnh dành riêng cho nhà cung cấp có trong Tự động hóa CLI. Sử dụng trang tham chiếu này để xem ngữ nghĩa của các cờ và thứ tự các bước.

​
Thêm tác tử (không tương tác)

main là mã định danh tác tử dành riêng và không thể dùng cho openclaw agents add.

​
RPC của trình hướng dẫn Gateway

Gateway cung cấp luồng thiết lập ban đầu qua RPC (wizard.start, wizard.next, wizard.cancel, wizard.status). Các ứng dụng khách (ứng dụng macOS, Control UI) có thể hiển thị các bước mà không cần triển khai lại logic thiết lập ban đầu.

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

Quy trình thiết lập ban đầu phát hiện xem signal-cli có nằm trong PATH hay không và nếu thiếu, sẽ đề nghị cài đặt:
  • Linux x86-64: tải bản dựng GraalVM gốc chính thức từ các bản phát hành GitHub của signal-cli và lưu tại ~/.openclaw/tools/signal-cli/<version>/.
  • macOS và các kiến trúc khác: thay vào đó cài đặt qua Homebrew.
  • Windows nguyên bản: chưa được hỗ trợ; hãy chạy quy trình thiết lập ban đầu bên trong WSL2 để sử dụng đường dẫn cài đặt Linux.
  • Trong cả hai trường hợp, ghi channels.signal.cliPath vào cấu hình của bạn.

​
Nội dung trình hướng dẫn ghi

Các trường điển hình trong ~/.openclaw/openclaw.json:
  • agents.defaults.workspace
  • agents.defaults.skipBootstrap khi truyền --skip-bootstrap
  • agents.defaults.model / models.providers (nếu chọn Minimax)
  • tools.profile (quy trình thiết lập ban đầu cục bộ mặc định là "coding" khi chưa đặt; các giá trị hiện có được đặt rõ ràng sẽ được giữ nguyên)
  • gateway.* (chế độ, liên kết, xác thực, Tailscale)
  • session.dmScope (quy trình thiết lập ban đầu giữ nguyên các giá trị được đặt rõ ràng và nếu không thì để trống, nhờ đó giá trị mặc định "main" giữ tất cả tin nhắn trực tiếp trên các kênh trong phiên chính cuốn chiếu của tác tử—mặc định dành cho tác tử cá nhân. Đối với hộp thư đến dùng chung hoặc nhiều người dùng, hãy sử dụng "per-channel-peer"; openclaw security audit khuyến nghị cô lập khi phát hiện lưu lượng DM từ nhiều người dùng. Chi tiết: Tham chiếu thiết lập CLI)
  • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
  • Danh sách cho phép DM của kênh khi bạn chọn tham gia trong các lời nhắc của kênh. Discord, Matrix, Microsoft Teams và Slack phân giải tên thành mã định danh khi có thể; các kênh khác nhận trực tiếp mã định danh (ví dụ: mã định danh số của người gửi Telegram hoặc số điện thoại WhatsApp).
  • skills.install.nodeManager
    • setup --node-manager chấp nhận npm, pnpm hoặc bun.
    • Cấu hình thủ công vẫn có thể sử dụng yarn bằng cách đặt trực tiếp skills.install.nodeManager.
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode
  • wizard.securityAcknowledgedAt
openclaw agents add ghi agents.list[] và bindings tùy chọn. Thông tin xác thực WhatsApp nằm trong ~/.openclaw/credentials/whatsapp/<accountId>/. Các phiên hoạt động và bản chép lời được lưu trong ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Thư mục ~/.openclaw/agents/<agentId>/sessions/ được dùng cho dữ liệu đầu vào của quá trình di chuyển cũ và các tài liệu lưu trữ/hỗ trợ. Một số kênh được cung cấp dưới dạng plugin. Khi bạn chọn một kênh trong quá trình thiết lập, quy trình thiết lập ban đầu sẽ nhắc cài đặt kênh đó (npm hoặc đường dẫn cục bộ) trước khi có thể cấu hình.

​
Tài liệu liên quan