# openclaw onboard

Thiết lập ban đầu tương tác cho thiết lập Gateway cục bộ hoặc từ xa.

# Hướng dẫn liên quan

# Ví dụ

openclaw onboard
openclaw onboard --modern
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --flow import
openclaw onboard --import-from hermes --import-source ~/.hermes
openclaw onboard --skip-bootstrap
openclaw onboard --mode remote --remote-url wss://gateway-host:18789

--flow import dùng các nhà cung cấp di chuyển do plugin sở hữu, chẳng hạn như Hermes. Nó chỉ chạy trên một thiết lập OpenClaw mới; nếu đã có cấu hình, thông tin xác thực, phiên, hoặc các tệp bộ nhớ/danh tính workspace, hãy đặt lại hoặc chọn một thiết lập mới trước khi nhập.

--modern khởi động bản xem trước thiết lập ban đầu dạng hội thoại Crestodian. Không có --modern, openclaw onboard giữ luồng thiết lập ban đầu cổ điển.

Đối với các đích ws:// dạng văn bản thuần trên mạng riêng tư (chỉ mạng tin cậy), hãy đặt OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 trong môi trường tiến trình thiết lập ban đầu. Không có cấu hình tương đương trong openclaw.json cho cơ chế phá kính truyền tải phía máy khách này.

Nhà cung cấp tùy chỉnh không tương tác:

openclaw onboard --non-interactive \
  --auth-choice custom-api-key \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "foo-large" \
  --custom-api-key "$CUSTOM_API_KEY" \
  --secret-input-mode plaintext \
  --custom-compatibility openai \
  --custom-image-input

--custom-api-key là tùy chọn trong chế độ không tương tác. Nếu bỏ qua, thiết lập ban đầu sẽ kiểm tra CUSTOM_API_KEY. OpenClaw tự động đánh dấu các ID mô hình thị giác phổ biến là có khả năng xử lý hình ảnh. Truyền --custom-image-input cho các ID thị giác tùy chỉnh chưa biết, hoặc --custom-text-input để buộc metadata chỉ văn bản.

LM Studio cũng hỗ trợ cờ khóa dành riêng cho nhà cung cấp trong chế độ không tương tác:

openclaw onboard --non-interactive \
  --auth-choice lmstudio \
  --custom-base-url "http://localhost:1234/v1" \
  --custom-model-id "qwen/qwen3.5-9b" \
  --lmstudio-api-key "$LM_API_TOKEN" \
  --accept-risk

Ollama không tương tác:

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

--custom-base-url mặc định là http://127.0.0.1:11434. --custom-model-id là tùy chọn; nếu bỏ qua, thiết lập ban đầu dùng các mặc định do Ollama đề xuất. Các ID mô hình đám mây như kimi-k2.5:cloud cũng hoạt động ở đây.

Lưu khóa nhà cung cấp dưới dạng tham chiếu thay vì văn bản thuần:

openclaw onboard --non-interactive \
  --auth-choice openai-api-key \
  --secret-input-mode ref \
  --accept-risk

Với --secret-input-mode ref, thiết lập ban đầu ghi các tham chiếu dựa trên env thay vì giá trị khóa dạng văn bản thuần. Đối với các nhà cung cấp dựa trên auth-profile, thao tác này ghi các mục keyRef; đối với nhà cung cấp tùy chỉnh, thao tác này ghi models.providers.<id>.apiKey dưới dạng tham chiếu env (ví dụ { source: "env", provider: "default", id: "CUSTOM_API_KEY" }).

Hợp đồng chế độ ref không tương tác:

• Đặt biến env của nhà cung cấp trong môi trường tiến trình thiết lập ban đầu (ví dụ OPENAI_API_KEY).
• Không truyền cờ khóa nội tuyến (ví dụ --openai-api-key) trừ khi biến env đó cũng được đặt.
• Nếu cờ khóa nội tuyến được truyền mà không có biến env bắt buộc, thiết lập ban đầu sẽ thất bại nhanh kèm hướng dẫn.

Tùy chọn token Gateway trong chế độ không tương tác:

• --gateway-auth token --gateway-token <token> lưu token dạng văn bản thuần.
• --gateway-auth token --gateway-token-ref-env <name> lưu gateway.auth.token dưới dạng SecretRef env.
• --gateway-token và --gateway-token-ref-env loại trừ lẫn nhau.
• --gateway-token-ref-env yêu cầu biến env không rỗng trong môi trường tiến trình thiết lập ban đầu.
• Với --install-daemon, khi xác thực token yêu cầu token, token gateway do SecretRef quản lý được xác thực nhưng không được lưu bền dưới dạng văn bản thuần đã phân giải trong metadata môi trường dịch vụ supervisor.
• Với --install-daemon, nếu chế độ token yêu cầu token và SecretRef token đã cấu hình chưa phân giải được, thiết lập ban đầu sẽ đóng thất bại kèm hướng dẫn khắc phục.
• Với --install-daemon, nếu cả gateway.auth.token và gateway.auth.password đều được cấu hình và gateway.auth.mode chưa được đặt, thiết lập ban đầu chặn cài đặt cho đến khi chế độ được đặt rõ ràng.
• Thiết lập ban đầu cục bộ ghi gateway.mode="local" vào cấu hình. Nếu một tệp cấu hình sau đó thiếu gateway.mode, hãy xem đó là cấu hình bị hỏng hoặc chỉnh sửa thủ công chưa hoàn chỉnh, không phải lối tắt chế độ cục bộ hợp lệ.
• Thiết lập ban đầu cục bộ cài đặt các plugin có thể tải xuống đã chọn khi đường dẫn thiết lập được chọn yêu cầu chúng.
• Thiết lập ban đầu từ xa chỉ ghi thông tin kết nối cho Gateway từ xa và không cài đặt các gói plugin cục bộ.
• --allow-unconfigured là một cửa thoát riêng cho thời gian chạy gateway. Nó không có nghĩa là thiết lập ban đầu có thể bỏ qua gateway.mode.

Ví dụ:

export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
  --accept-risk

Tình trạng Gateway cục bộ không tương tác:

• Trừ khi bạn truyền --skip-health, thiết lập ban đầu sẽ chờ một gateway cục bộ có thể truy cập trước khi thoát thành công.
• --install-daemon khởi động đường dẫn cài đặt gateway được quản lý trước. Nếu không có cờ này, bạn phải có sẵn một gateway cục bộ đang chạy, ví dụ openclaw gateway run.
• Nếu bạn chỉ muốn ghi cấu hình/workspace/bootstrap trong tự động hóa, hãy dùng --skip-health.
• Nếu bạn tự quản lý các tệp workspace, hãy truyền --skip-bootstrap để đặt agents.defaults.skipBootstrap: true và bỏ qua việc tạo AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, và BOOTSTRAP.md.
• Trên Windows gốc, --install-daemon thử Scheduled Tasks trước và rơi về một mục đăng nhập trong thư mục Startup theo người dùng nếu việc tạo tác vụ bị từ chối.

Hành vi thiết lập ban đầu tương tác với chế độ tham chiếu:

• Chọn Dùng tham chiếu bí mật khi được nhắc.
• Sau đó chọn một trong hai:
  • Biến môi trường
  • Nhà cung cấp bí mật đã cấu hình (file hoặc exec)
• Thiết lập ban đầu thực hiện xác thực preflight nhanh trước khi lưu tham chiếu.
  • Nếu xác thực thất bại, thiết lập ban đầu hiển thị lỗi và cho phép bạn thử lại.

# Lựa chọn endpoint Z.AI không tương tác

# Promptless endpoint selection
openclaw onboard --non-interactive \
  --auth-choice zai-coding-global \
  --zai-api-key "$ZAI_API_KEY"

# Other Z.AI endpoint choices:
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn

Ví dụ Mistral không tương tác:

openclaw onboard --non-interactive \
  --auth-choice mistral-api-key \
  --mistral-api-key "$MISTRAL_API_KEY"

# Ghi chú về luồng

# Lệnh tiếp theo thường dùng

openclaw configure
openclaw agents add <name>