Windows

OpenClaw hỗ trợ cả Windows gốc và WSL2. WSL2 là hướng ổn định hơn và được khuyến nghị để có trải nghiệm đầy đủ — CLI, Gateway và công cụ chạy bên trong Linux với khả năng tương thích đầy đủ. Windows gốc dùng được cho CLI lõi và Gateway, với một số lưu ý bên dưới.

Ứng dụng đồng hành Windows gốc đang được lên kế hoạch.

WSL2 (khuyến nghị)

• Bắt đầu (dùng bên trong WSL)
• Cài đặt & cập nhật
• Hướng dẫn WSL2 chính thức (Microsoft): https://learn.microsoft.com/windows/wsl/install

Trạng thái Windows gốc

Các luồng CLI Windows gốc đang được cải thiện, nhưng WSL2 vẫn là hướng được khuyến nghị.

Những gì hoạt động tốt trên Windows gốc hiện nay:

• trình cài đặt website qua install.ps1
• dùng CLI cục bộ như openclaw --version, openclaw doctor và openclaw plugins list --json
• kiểm thử smoke local-agent/provider nhúng như:

openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."

Các lưu ý hiện tại:

• openclaw onboard --non-interactive vẫn yêu cầu gateway cục bộ có thể kết nối được, trừ khi bạn truyền --skip-health
• openclaw onboard --non-interactive --install-daemon và openclaw gateway install thử Windows Scheduled Tasks trước
• nếu việc tạo Scheduled Task bị từ chối, OpenClaw chuyển sang mục đăng nhập trong thư mục Startup theo từng người dùng và khởi động gateway ngay lập tức
• nếu chính schtasks bị kẹt hoặc ngừng phản hồi, OpenClaw hiện hủy nhanh hướng đó và chuyển sang dự phòng thay vì treo mãi
• Scheduled Tasks vẫn được ưu tiên khi khả dụng vì cung cấp trạng thái giám sát tốt hơn

Nếu bạn chỉ muốn CLI gốc, không cài đặt dịch vụ gateway, hãy dùng một trong các lệnh này:

openclaw onboard --non-interactive --skip-healthopenclaw gateway run

Nếu bạn muốn khởi động được quản lý trên Windows gốc:

openclaw gateway installopenclaw gateway status --json

Nếu việc tạo Scheduled Task bị chặn, chế độ dịch vụ dự phòng vẫn tự khởi động sau khi đăng nhập thông qua thư mục Startup của người dùng hiện tại.

Gateway

• Runbook Gateway
• Cấu hình

Cài đặt dịch vụ Gateway (CLI)

Bên trong WSL2:

openclaw onboard --install-daemon

Hoặc:

openclaw gateway install

Hoặc:

openclaw configure

Chọn Dịch vụ Gateway khi được nhắc.

Sửa chữa/di chuyển:

openclaw doctor

Gateway tự khởi động trước khi đăng nhập Windows

Với các thiết lập không màn hình, hãy đảm bảo toàn bộ chuỗi khởi động chạy ngay cả khi không có ai đăng nhập vào Windows.

1) Giữ dịch vụ người dùng chạy mà không cần đăng nhập

Bên trong WSL:

sudo loginctl enable-linger "$(whoami)"

2) Cài đặt dịch vụ người dùng Gateway OpenClaw

Bên trong WSL:

openclaw gateway install

3) Tự động khởi động WSL khi Windows khởi động

Trong PowerShell với quyền Administrator:

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM

Thay Ubuntu bằng tên distro của bạn từ:

wsl --list --verbose

Xác minh chuỗi khởi động

Sau khi khởi động lại (trước khi đăng nhập Windows), kiểm tra từ WSL:

systemctl --user is-enabled openclaw-gateway.servicesystemctl --user status openclaw-gateway.service --no-pager

Nâng cao: đưa dịch vụ WSL ra LAN (portproxy)

WSL có mạng ảo riêng. Nếu một máy khác cần truy cập một dịch vụ đang chạy bên trong WSL (SSH, máy chủ TTS cục bộ hoặc Gateway), bạn phải chuyển tiếp một cổng Windows tới IP WSL hiện tại. IP WSL thay đổi sau khi khởi động lại, nên bạn có thể cần làm mới quy tắc chuyển tiếp.

Ví dụ (PowerShell với quyền Administrator):

$Distro = "Ubuntu-24.04"$ListenPort = 2222$TargetPort = 22 $WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]if (-not $WslIp) { throw "WSL IP not found." } netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `  connectaddress=$WslIp connectport=$TargetPort

Cho phép cổng đi qua Windows Firewall (một lần):

New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `  -Protocol TCP -LocalPort $ListenPort -Action Allow

Làm mới portproxy sau khi WSL khởi động lại:

netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Nullnetsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `  connectaddress=$WslIp connectport=$TargetPort | Out-Null

Ghi chú:

• SSH từ máy khác nhắm tới IP máy chủ Windows (ví dụ: ssh user@windows-host -p 2222).
• Các node từ xa phải trỏ tới URL Gateway có thể kết nối được (không phải 127.0.0.1); dùng openclaw status --all để xác nhận.
• Dùng listenaddress=0.0.0.0 để truy cập LAN; 127.0.0.1 chỉ giữ cục bộ.
• Nếu bạn muốn việc này tự động, hãy đăng ký một Scheduled Task để chạy bước làm mới khi đăng nhập.

Cài đặt WSL2 từng bước

1) Cài đặt WSL2 + Ubuntu

Mở PowerShell (Admin):

wsl --install# Or pick a distro explicitly:wsl --list --onlinewsl --install -d Ubuntu-24.04

Khởi động lại nếu Windows yêu cầu.

2) Bật systemd (bắt buộc để cài đặt gateway)

Trong terminal WSL của bạn:

sudo tee /etc/wsl.conf >/dev/null <<'EOF'[boot]systemd=trueEOF

Sau đó từ PowerShell:

wsl --shutdown

Mở lại Ubuntu, rồi xác minh:

systemctl --user status

3) Cài đặt OpenClaw (bên trong WSL)

Để thiết lập lần đầu thông thường bên trong WSL, hãy làm theo luồng Bắt đầu trên Linux:

git clone https://github.com/openclaw/openclaw.gitcd openclawpnpm installpnpm buildpnpm ui:buildpnpm openclaw onboard --install-daemon

Nếu bạn đang phát triển từ mã nguồn thay vì onboarding lần đầu, hãy dùng vòng lặp phát triển từ mã nguồn trong Thiết lập:

pnpm install# First run only (or after resetting local OpenClaw config/workspace)pnpm openclaw setuppnpm gateway:watch

Hướng dẫn đầy đủ: Bắt đầu

Ứng dụng đồng hành Windows

Chúng tôi chưa có ứng dụng đồng hành Windows. Rất hoan nghênh đóng góp nếu bạn muốn giúp biến điều đó thành hiện thực.

Kết nối Git và GitHub (người đóng góp)

Một số mạng chặn hoặc giới hạn HTTPS tới GitHub. Nếu git clone thất bại do hết thời gian chờ hoặc kết nối bị đặt lại, hãy thử mạng khác, VPN hoặc proxy HTTP/HTTPS do tổ chức của bạn cung cấp.

Nếu gh auth login thất bại trong luồng thiết bị qua trình duyệt (ví dụ hết thời gian chờ khi truy cập github.com:443), hãy xác thực bằng personal access token thay thế:

1. Tạo token có ít nhất phạm vi repo (PAT classic) hoặc quyền truy cập fine-grained tương đương.
2. Trong PowerShell cho phiên hiện tại:

$env:GH_TOKEN="<your-token>"gh auth statusgh auth setup-git

3. Nếu gh auth status cảnh báo thiếu read:org, hãy tạo token bao gồm phạm vi đó và gán lại biến:

$env:GH_TOKEN="<your-token-with-repo-and-read:org>"gh auth status

gh auth refresh -s read:org chỉ áp dụng khi bạn đã xác thực qua gh auth login và có thông tin đăng nhập đã lưu để làm mới (không áp dụng khi dùng GH_TOKEN).

Không bao giờ commit token hoặc dán chúng vào issue hay pull request.

Liên quan

• Tổng quan cài đặt
• Nền tảng