Cập nhật

OpenClaw đang phát triển rất nhanh (chưa đến “1.0”). Hãy coi việc cập nhật như triển khai hạ tầng: cập nhật → chạy kiểm tra → khởi động lại (hoặc dùng openclaw update, sẽ tự restart) → xác minh.

Khuyên dùng: chạy lại trình cài từ website (nâng cấp tại chỗ)

Cách cập nhật được khuyên dùng là chạy lại trình cài từ website. Nó sẽ phát hiện bản cài đặt hiện có, nâng cấp tại chỗ, và chạy openclaw doctor khi cần.

curl -fsSL https://openclaw.ai/install.sh | bash

Lưu ý:

  • Thêm --no-onboard nếu các bạn không muốn wizard onboarding chạy lại.
  • Với cài từ source, dùng: 
    curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard
    Trình cài sẽ chạy git pull --rebase chỉ khi repo sạch.
  • Với cài global, script dùng npm install -g openclaw@latest bên dưới.
  • Lưu ý legacy: openclaw vẫn có sẵn như một compatibility shim.

Trước khi cập nhật

  • Biết cách mình đã cài: global (npm/pnpm) hay từ source (git clone).
  • Biết Gateway đang chạy thế nào: foreground terminal hay supervised service (launchd/systemd).
  • Backup các tùy chỉnh của các bạn:
    • Config: ~/.openclaw/openclaw.json
    • Credentials: ~/.openclaw/credentials/
    • Workspace: ~/.openclaw/workspace

Cập nhật (cài global)

Cài global (chọn một):

npm i -g openclaw@latest
pnpm add -g openclaw@latest

Mình không khuyên dùng Bun cho Gateway runtime (có bug với WhatsApp/Telegram).

Để chuyển channel cập nhật (cài git + npm):

openclaw update --channel beta
openclaw update --channel dev
openclaw update --channel stable

Dùng --tag <dist-tag|version> để cài một tag/version cụ thể.

Xem Development channels để hiểu về channel và release notes.

Lưu ý: với cài npm, gateway sẽ log gợi ý cập nhật khi khởi động (kiểm tra channel tag hiện tại). Tắt bằng update.checkOnStart: false.

Sau đó:

openclaw doctor
openclaw gateway restart
openclaw health

Lưu ý:

  • Nếu Gateway chạy như service, nên dùng openclaw gateway restart thay vì kill PID.
  • Nếu các bạn đang pin một version cụ thể, xem phần “Rollback / pinning” bên dưới.

Cập nhật (openclaw update)

Với cài từ source (git checkout), nên dùng:

openclaw update

Nó chạy một quy trình cập nhật khá an toàn:

  • Yêu cầu worktree sạch.
  • Chuyển sang channel đã chọn (tag hoặc branch).
  • Fetch + rebase với upstream đã config (dev channel).
  • Cài deps, build, build Control UI, và chạy openclaw doctor.
  • Restart gateway mặc định (dùng --no-restart để bỏ qua).

Nếu các bạn cài qua npm/pnpm (không có git metadata), openclaw update sẽ cố cập nhật qua package manager. Nếu không phát hiện được cách cài, dùng “Cập nhật (cài global)” ở trên.

Cập nhật (Control UI / RPC)

Control UI có nút Update & Restart (RPC: update.run). Nó sẽ:

  1. Chạy quy trình source-update giống openclaw update (chỉ git checkout).
  2. Ghi restart sentinel với báo cáo có cấu trúc (stdout/stderr tail).
  3. Restart gateway và ping session đang active với báo cáo.

Nếu rebase thất bại, gateway sẽ abort và restart mà không áp dụng update.

Cập nhật (từ source)

Từ repo checkout:

Khuyên dùng:

openclaw update

Thủ công (tương đương):

git pull
pnpm install
pnpm build
pnpm ui:build # tự cài UI deps lần đầu chạy
openclaw doctor
openclaw health

Lưu ý:

  • pnpm build quan trọng khi các bạn chạy binary openclaw đã đóng gói (openclaw.mjs) hoặc dùng Node chạy dist/.
  • Nếu chạy từ repo checkout mà không cài global, dùng pnpm openclaw ... cho lệnh CLI.
  • Nếu chạy trực tiếp từ TypeScript (pnpm openclaw ...), thường không cần rebuild, nhưng config migrations vẫn áp dụng → chạy doctor.
  • Chuyển giữa cài global và git rất dễ: cài flavor khác, rồi chạy openclaw doctor để gateway service entrypoint được viết lại theo bản cài hiện tại.

Luôn chạy: openclaw doctor

Doctor là lệnh “cập nhật an toàn”. Nó cố ý đơn giản: sửa + migrate + cảnh báo.

Lưu ý: nếu các bạn dùng cài từ source (git checkout), openclaw doctor sẽ đề nghị chạy openclaw update trước.

Những việc nó thường làm:

  • Migrate các config key đã deprecated / vị trí config file cũ.
  • Audit DM policies và cảnh báo các cài đặt “open” rủi ro.
  • Kiểm tra Gateway health và có thể đề nghị restart.
  • Phát hiện và migrate các gateway service cũ (launchd/systemd; legacy schtasks) sang OpenClaw services hiện tại.
  • Trên Linux, đảm bảo systemd user lingering (để Gateway tồn tại sau khi logout).

Chi tiết: Doctor

Start / stop / restart Gateway

CLI (hoạt động trên mọi OS):

openclaw gateway status
openclaw gateway stop
openclaw gateway restart
openclaw gateway --port 18789
openclaw logs --follow

Nếu các bạn dùng supervised:

  • macOS launchd (app-bundled LaunchAgent): launchctl kickstart -k gui/$UID/bot.molt.gateway (dùng bot.molt.<profile>; legacy com.openclaw.* vẫn hoạt động)
  • Linux systemd user service: systemctl --user restart openclaw-gateway[-<profile>].service
  • Windows (WSL2): systemctl --user restart openclaw-gateway[-<profile>].service
    • launchctl/systemctl chỉ hoạt động nếu service đã cài; nếu không thì chạy openclaw gateway install.

Runbook + service labels chính xác: Gateway runbook

Rollback / pinning (khi có gì đó bị lỗi)

Pin (cài global)

Cài một version đã biết hoạt động tốt (thay <version> bằng version cuối cùng hoạt động):

npm i -g openclaw@<version>
pnpm add -g openclaw@<version>

Mẹo: để xem version đã publish hiện tại, chạy npm view openclaw version.

Sau đó restart + chạy lại doctor:

openclaw doctor
openclaw gateway restart

Pin (source) theo ngày

Chọn một commit từ một ngày (ví dụ: “trạng thái của main tại 2026-01-01”):

git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"

Sau đó cài lại deps + restart:

pnpm install
pnpm build
openclaw gateway restart

Nếu muốn quay lại latest sau này:

git checkout main
git pull

Nếu bị kẹt