Cập nhật

Giữ OpenClaw luôn cập nhật.

# Khuyến nghị: openclaw update

Cách cập nhật nhanh nhất. Lệnh này phát hiện kiểu cài đặt của bạn (npm hoặc git), tải phiên bản mới nhất, chạy openclaw doctor, rồi khởi động lại Gateway.

openclaw update

Để chuyển kênh hoặc nhắm tới một phiên bản cụ thể:

openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag main
openclaw update --dry-run   # xem trước mà không áp dụng

openclaw update không chấp nhận --verbose. Để chẩn đoán cập nhật, hãy dùng --dry-run để xem trước các hành động đã lên kế hoạch, --json để nhận kết quả có cấu trúc, hoặc openclaw update status --json để kiểm tra trạng thái kênh và mức độ sẵn có. Trình cài đặt có cờ --verbose riêng, nhưng cờ đó không thuộc openclaw update.

--channel beta ưu tiên beta, nhưng runtime sẽ quay về stable/latest khi thẻ beta bị thiếu hoặc cũ hơn bản phát hành stable mới nhất. Dùng --tag beta nếu bạn muốn dist-tag npm beta thô cho một lần cập nhật gói.

Xem Kênh phát triển để biết ngữ nghĩa của kênh.

# Chuyển đổi giữa cài đặt npm và git

Dùng các kênh khi bạn muốn thay đổi kiểu cài đặt. Trình cập nhật giữ nguyên trạng thái, cấu hình, thông tin xác thực và workspace của bạn trong ~/.openclaw; nó chỉ thay đổi bản cài đặt mã OpenClaw mà CLI và Gateway sử dụng.

# cài đặt gói npm -> checkout git có thể chỉnh sửa
openclaw update --channel dev

# checkout git -> cài đặt gói npm
openclaw update --channel stable

Chạy với --dry-run trước để xem trước chính xác việc chuyển chế độ cài đặt:

openclaw update --channel dev --dry-run
openclaw update --channel stable --dry-run

Kênh dev bảo đảm có checkout git, build checkout đó, rồi cài đặt CLI toàn cục từ checkout đó. Các kênh stable và beta dùng cài đặt gói. Nếu Gateway đã được cài đặt, openclaw update làm mới siêu dữ liệu dịch vụ và khởi động lại dịch vụ, trừ khi bạn truyền --no-restart.

# Cách khác: chạy lại trình cài đặt

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

Thêm --no-onboard để bỏ qua onboarding. Để ép một kiểu cài đặt cụ thể thông qua trình cài đặt, truyền --install-method git --no-onboard hoặc --install-method npm --no-onboard.

Nếu openclaw update thất bại sau giai đoạn cài đặt gói npm, hãy chạy lại trình cài đặt. Trình cài đặt không gọi trình cập nhật cũ; nó chạy trực tiếp cài đặt gói toàn cục và có thể khôi phục một bản cài đặt npm đã cập nhật một phần.

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

Để ghim quá trình khôi phục vào một phiên bản hoặc dist-tag cụ thể, thêm --version:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>

# Cách khác: npm, pnpm hoặc bun thủ công

npm i -g openclaw@latest

Ưu tiên openclaw update cho các bản cài đặt được giám sát vì lệnh này có thể phối hợp việc hoán đổi gói với dịch vụ Gateway đang chạy. Nếu bạn cập nhật thủ công trong khi Gateway được quản lý đang chạy, hãy khởi động lại Gateway ngay sau khi trình quản lý gói hoàn tất để tiến trình cũ không tiếp tục phục vụ từ các tệp gói đã bị thay thế.

Khi openclaw update quản lý một bản cài đặt npm toàn cục, lệnh này trước tiên cài đặt mục tiêu vào một tiền tố npm tạm thời, xác minh inventory dist đã đóng gói, rồi hoán đổi cây gói sạch vào tiền tố toàn cục thật. Điều đó tránh việc npm phủ một gói mới lên các tệp cũ còn sót lại từ gói trước. Nếu lệnh cài đặt thất bại, OpenClaw thử lại một lần với --omit=optional. Lần thử lại đó giúp các máy chủ nơi phụ thuộc tùy chọn native không thể biên dịch, đồng thời vẫn hiển thị lỗi ban đầu nếu phương án dự phòng cũng thất bại.

pnpm add -g openclaw@latest

bun add -g openclaw@latest

# Chủ đề cài đặt npm nâng cao

ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp

# Trình tự động cập nhật

Trình tự động cập nhật mặc định tắt. Bật trong ~/.openclaw/openclaw.json:

{
  update: {
    channel: "stable",
    auto: {
      enabled: true,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}

Gateway cũng ghi log gợi ý cập nhật khi khởi động (tắt bằng update.checkOnStart: false). Để hạ cấp hoặc khôi phục sự cố, đặt OPENCLAW_NO_AUTO_UPDATE=1 trong môi trường Gateway để chặn áp dụng tự động ngay cả khi update.auto.enabled đã được cấu hình. Gợi ý cập nhật khi khởi động vẫn có thể chạy trừ khi update.checkOnStart cũng bị tắt.

Các bản cập nhật trình quản lý gói được yêu cầu thông qua handler control-plane Gateway trực tiếp buộc khởi động lại cập nhật không trì hoãn, không cooldown sau khi hoán đổi gói. Điều đó tránh để một tiến trình cũ trong bộ nhớ tồn tại đủ lâu để lazy-load các chunk từ cây gói đã bị thay thế. Shell openclaw update vẫn là đường dẫn được ưu tiên cho các bản cài đặt được giám sát vì nó có thể dừng và khởi động lại dịch vụ quanh quá trình cập nhật.

# Sau khi cập nhật

openclaw doctor

openclaw gateway restart

openclaw health

# Khôi phục phiên bản trước

# Ghim một phiên bản (npm)

npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart

# Ghim một commit (mã nguồn)

git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
pnpm install && pnpm build
openclaw gateway restart

Để trở về bản mới nhất: git checkout main && git pull.

# Nếu bạn bị kẹt

• Chạy lại openclaw doctor và đọc kỹ đầu ra.
• Với openclaw update --channel dev trên các checkout mã nguồn, trình cập nhật tự động bootstrap pnpm khi cần. Nếu bạn thấy lỗi bootstrap pnpm/corepack, hãy cài đặt pnpm thủ công (hoặc bật lại corepack) rồi chạy lại cập nhật.
• Kiểm tra: Khắc phục sự cố
• Hỏi trong Discord: https://discord.gg/clawd

# Liên quan

• Tổng quan cài đặt: tất cả phương thức cài đặt.
• Doctor: kiểm tra sức khỏe sau cập nhật.
• Di chuyển: hướng dẫn di chuyển phiên bản chính.