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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Trang này là tài liệu tham chiếu đầy đủ cho openclaw onboard. Để xem hướng dẫn ngắn, hãy xem 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 mô hình và xác thực (OAuth đăng ký OpenAI Code, Anthropic Claude CLI hoặc khóa API, cùng các tùy chọn MiniMax, GLM, Ollama, Moonshot, StepFun và AI Gateway)
• Vị trí workspace và các tệp bootstrap
• Thiết lập Gateway (cổng, bind, xác thực, Tailscale)
• Kênh và nhà cung cấp (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles và các plugin kênh đi kèm khác)
• Cài đặt daemon (LaunchAgent, systemd user unit hoặc Windows Scheduled Task gốc với phương án dự phò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 tới một gateway ở nơi khác. Nó không cài đặt hoặc sửa đổi bất cứ 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 tới một gateway ở nơi khác. Những gì bạn thiết lập:

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

​

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

Hành vi 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 thủ công.
• Onboarding nhà cung cấp tùy chỉnh suy luận hỗ trợ hình ảnh cho các ID mô hình phổ biến và chỉ hỏi khi tên mô hình chưa biết.
• Khi onboarding 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 đó. Với Volcengine và BytePlus, cùng ưu tiên đó cũng khớp với các biến thể coding-plan của chúng (volcengine-plan/*, byteplus-plan/*).
• Nếu bộ lọc nhà cung cấp được ưu tiên đó sẽ rỗng, bộ chọn fallback về catalog đầ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 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 onboarding mặc định 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 vì lưu trữ khóa 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 alias nhà cung cấp + id
• Chế độ tham chiếu tương tác chạy xác thực preflight nhanh trước khi lưu.
  • Env refs: xác thực tên biến + giá trị không rỗng trong môi trường onboarding hiện tại.
  • Provider refs: 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 preflight thất bại, onboarding 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ằng env.
  • Đặt biến môi trường của nhà cung cấp trong môi trường tiến trình onboarding.
  • Các cờ khóa inline (ví dụ --openai-api-key) yêu cầu biến môi trường đó phải được đặt; nếu không, onboarding sẽ thất bại nhanh.
  • 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, onboarding sẽ thất bại nhanh.
• 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 dạng văn bản thuần (mặc định) hoặc Dùng SecretRef.
  • Chế độ mật khẩu: 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>.
• Các thiết lập văn bản thuần hiện có tiếp tục hoạt động không thay đổi.

​

Đầu ra và 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 (thiết lập ban đầu 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ế độ, bind, auth, tailscale)
• session.dmScope (thiết lập ban đầu cục bộ đặt mặc định này thành per-channel-peer khi chưa đặt; các giá trị tường minh hiện có được giữ nguyên)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• Danh sách cho phép kênh (Slack, Discord, Matrix, Microsoft Teams) khi bạn chọn tham gia trong lời nhắc (tên sẽ được phân giải thành ID khi có thể)
• 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 đó.
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

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>/. Phiên được lưu trong ~/.openclaw/agents/<agentId>/sessions/. RPC của trình hướng dẫn Gateway:

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

Ứng dụng khách (ứng dụng macOS và 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. Hành vi thiết lập Signal:

• Tải xuống tài nguyên phát hành phù hợp
• Lưu trong ~/.openclaw/tools/signal-cli/<version>/
• Ghi channels.signal.cliPath trong cấu hình
• Các bản dựng JVM yêu cầu Java 21
• Các bản dựng native được dùng khi có
• Windows dùng WSL2 và tuân theo luồng signal-cli của Linux bên trong WSL

​

Tài liệu liên quan

• Trung tâm thiết lập ban đầu: Thiết lập ban đầu (CLI)
• Tự động hóa và script: Tự động hóa CLI
• Tham chiếu lệnh: openclaw onboard