Tài liệu tham khảo về thiết lập CLI

Trang này trình bày từng bước về hành vi, đầu ra và cơ chế nội bộ của quy trình thiết lập ban đầu. Để xem hướng dẫn từng bước, hãy xem Thiết lập ban đầu (CLI). Để xem tài liệu tham khảo đầy đủ về các cờ CLI (mọi --flag, ví dụ phi tương tác, lệnh dành riêng cho từng nhà cung cấp), hãy xem openclaw onboard.

Trình hướng dẫn thực hiện những gì

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

• Thiết lập mô hình và xác thực (Anthropic, OAuth cho gói đăng ký OpenAI Code, xAI, OpenCode, điểm cuối tùy chỉnh và các luồng xác thực khác do nhà cung cấp sở hữu)
• Vị trí không gian làm việc và các tệp khởi tạo
• Cài đặt Gateway (cổng, địa chỉ liên kết, xác thực, Tailscale)
• Kênh và nhà cung cấp (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp và các kênh đi kèm hoặc kênh Plugin khác)
• Nhà cung cấp tìm kiếm web (tùy chọn)
• Cài đặt daemon (LaunchAgent, đơn vị người dùng systemd hoặc Tác vụ Theo lịch gốc của Windows với phương án dự phòng bằng thư mục Startup)
• Kiểm tra tình trạng
• Thiết lập Skills

Chế độ từ xa cấu hình máy này để kết nối với một Gateway ở nơi khác. Chế độ này không cài đặt hoặc sửa đổi bất kỳ thứ gì trên máy chủ từ xa.

Chi tiết luồng cục bộ

Chi tiết chế độ từ xa

Chế độ từ xa cấu hình máy này để kết nối với một Gateway ở nơi khác. Chế độ này không cài đặt hoặc sửa đổi bất kỳ thứ gì trên máy chủ từ xa.

Nội dung bạn thiết lập:

• URL Gateway từ xa (ws://... hoặc wss://...)
• Token, mật khẩu hoặc không xác thực, khớp với cấu hình của Gateway từ xa

Các tùy chọn xác thực và mô hình

Nếu một bước thiết lập nhà cung cấp thất bại trong quá trình thiết lập ban đầu tương tác (ví dụ: tùy chọn tái sử dụng CLI khi chưa đăng nhập cục bộ), trình hướng dẫn sẽ hiển thị lỗi và quay lại trình chọn nhà cung cấp thay vì thoát. Các lần chạy --auth-choice rõ ràng vẫn dừng ngay khi gặp lỗi để phục vụ tự động hóa.

Hành vi của mô hình:

• Chọn mô hình mặc định từ các tùy chọn được phát hiện hoặc nhập nhà cung cấp và mô hình theo cách thủ công.
• Khi quy trình làm quen bắt đầu từ một lựa chọn xác thực nhà cung cấp, bộ chọn mô hình tự động ưu tiên nhà cung cấp đó. Đối với Volcengine và BytePlus, tùy chọn ưu tiên này cũng khớp với các biến thể gói lập trình của chúng (volcengine-plan/*, byteplus-plan/*).
• Nếu bộ lọc nhà cung cấp ưu tiên đó không có kết quả, bộ chọn sẽ quay lại danh mục đầy đủ thay vì không hiển thị mô hình nào.
• Trình hướng dẫn 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 thông tin xác thực.

Đường dẫn thông tin xác thực và hồ sơ:

• Hồ sơ xác thực (khóa API + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Nhập OAuth cũ: ~/.openclaw/credentials/oauth.json

Chế độ lưu trữ thông tin xác thực:

• Hành vi mặc định của quy trình làm quen lưu khóa API dưới dạng giá trị văn bản thuần trong hồ sơ xác thực.
• --secret-input-mode ref bật chế độ tham chiếu thay cho việc lưu khóa dưới dạng văn bản thuần. Trong thiết lập tương tác, bạn có thể chọn một trong hai:
  • tham chiếu biến môi trường (ví dụ: keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • tham chiếu nhà cung cấp đã cấu hình (file hoặc exec) với bí danh nhà cung cấp + ID
• Chế độ tham chiếu tương tác chạy bước xác thực nhanh trước khi lưu.
  • Tham chiếu biến môi trường: xác thực tên biến + giá trị không rỗng trong môi trường quy trình làm quen hiện tại.
  • Tham chiếu nhà cung cấp: xác thực cấu hình nhà cung cấp và phân giải ID được yêu cầu.
  • Nếu bước xác thực trước khi chạy thất bại, quy trình làm quen hiển thị lỗi và cho phép bạn thử lại.
• Ở chế độ không tương tác, --secret-input-mode ref chỉ được hỗ trợ bởi biến môi trường.
  • Đặt biến môi trường của nhà cung cấp trong môi trường tiến trình làm quen.
  • Các cờ khóa nội tuyến (ví dụ: --openai-api-key) yêu cầu biến môi trường đó phải được đặt; nếu không, quy trình làm quen sẽ nhanh chóng thất bại.
  • Đối với nhà cung cấp tùy chỉnh, 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 nhà cung cấp tùy chỉnh đó, --custom-api-key yêu cầu CUSTOM_API_KEY phải được đặt; nếu không, quy trình làm quen sẽ nhanh chóng thất bại.
• Thông tin xác thực Gateway hỗ trợ lựa chọn văn bản thuần và SecretRef trong thiết lập tương tác:
  • Chế độ token: Tạo/lưu token văn bản thuần (mặc định) hoặc Sử dụng SecretRef.
  • Chế độ mật khẩu: văn bản thuần hoặc SecretRef.
• Đường dẫn SecretRef của token không tương tác: --gateway-token-ref-env <ENV_VAR>.
• Các thiết lập văn bản thuần hiện có tiếp tục hoạt động mà không thay đổi.

Đầu ra và thành phần nội bộ

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 làm quen cục bộ mặc định là "coding" khi chưa đặt; các giá trị tường minh hiện có được giữ nguyên)
• gateway.* (chế độ, liên kết, xác thực, tailscale)
• session.dmScope (quy trình làm quen giữ nguyên các giá trị tường minh và nếu không thì để chưa đặt, vì vậy 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 luân phiên của agent—giá trị mặc định cho agent 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 tin nhắn trực tiếp từ nhiều người dùng)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• Danh sách cho phép của kênh (Discord, iMessage, Signal, Slack, Telegram, WhatsApp) khi bạn chọn tham gia trong các lời nhắc; Discord và Slack cũng phân giải tên đã nhập thành ID
• skills.install.nodeManager
  • Cờ setup --node-manager chấp nhận npm, pnpm hoặc bun.
  • Cấu hình thủ công vẫn có thể đặt skills.install.nodeManager: "yarn" sau này.
• 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 đang 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 sử dụng cho đầu vào di chuyển dữ liệu cũ và các hiện vật lưu trữ/hỗ trợ.

Đề xuất ứng dụng đã cài đặt

Sau khi kiểm tra quyền truy cập mô hình thành công, quy trình làm quen tương tác cổ điển trên macOS quét tên ứng dụng và ID gói mà không yêu cầu quyền riêng tư của macOS. Quy trình này tìm kiếm trong các danh mục plugin chính thức và ClawHub, sau đó yêu cầu mô hình đã cấu hình loại bỏ các kết quả khớp tên sai và đề xuất các plugin hoặc kỹ năng phù hợp. Các kết quả khớp được đề xuất được chọn theo mặc định; các kết quả khớp tùy chọn yêu cầu lựa chọn tường minh.

Màn hình kết quả liệt kê các ứng dụng được phát hiện và hiển thị: "Tên ứng dụng được đối sánh bằng mô hình đã cấu hình của bạn và tìm kiếm ClawHub." Đặt wizard.appRecommendations thành false để tắt cả bước làm quen này lẫn quyền truy cập của Gateway vào danh sách ứng dụng của node. Quá trình quét không được sử dụng trong quy trình bắt đầu nhanh hoặc quy trình làm quen không phải macOS.

Thiết lập không tương tác

--non-interactive yêu cầu --accept-risk (xác nhận rằng agent rất mạnh và quyền truy cập toàn hệ thống tiềm ẩn rủi ro):

openclaw onboard --non-interactive --accept-risk \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY"

Tài liệu tham khảo đầy đủ về cờ và các ví dụ dành riêng cho nhà cung cấp: openclaw onboard, Tự động hóa CLI.

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

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

Các máy khách (ứng dụng macOS và giao diện điều khiển) có thể hiển thị các bước mà không cần triển khai lại logic làm quen.

Hành vi thiết lập Signal

• Tải xuống hiện vật bản phát hành phù hợp từ các bản phát hành GitHub chính thức của signal-cli (bản dựng gốc, chỉ Linux x86-64)
• Trên các nền tảng khác (macOS, Linux không phải x64), cài đặt qua Homebrew
• Lưu bản cài đặt từ hiện vật phát hành trong ~/.openclaw/tools/signal-cli/<version>/
• Ghi channels.signal.cliPath vào cấu hình
• Windows gốc chưa được hỗ trợ; hãy chạy quy trình làm quen trong WSL2 để nhận đường dẫn cài đặt Linux

Tài liệu liên quan

• Trung tâm làm quen: Làm quen (CLI)
• Tự động hóa và tập lệnh: Tự động hóa CLI
• Tài liệu tham khảo lệnh: openclaw onboard