Cập nhật

Luôn cập nhật OpenClaw lên phiên bản mới nhất.

Đối với việc thay thế ảnh Docker, Podman và Kubernetes, hãy xem Nâng cấp ảnh vùng chứa. Gateway thực hiện công việc nâng cấp an toàn khi khởi động trước khi chuyển sang trạng thái sẵn sàng và sẽ thoát nếu trạng thái được gắn kết cần sửa chữa thủ công.

Khuyến nghị: openclaw update

Phát hiện loại 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 và khởi động lại Gateway.

openclaw update

Chuyển kênh hoặc nhắm đến một phiên bản cụ thể:

openclaw update --channel betaopenclaw update --channel extended-stableopenclaw update --channel devopenclaw update --dry-run   # preview without applying

openclaw update không có cờ --verbose (trình cài đặt thì có). Để chẩn đoán, hãy dùng --dry-run để xem trước các hành động dự kiến, --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à tính khả dụng.

--channel beta ưu tiên dist-tag beta của npm nhưng chuyển về stable/latest khi thiếu thẻ beta hoặc phiên bản của thẻ này cũ hơn bản phát hành ổn định mới nhất. Thay vào đó, hãy dùng --tag beta để cập nhật gói một lần, được ghim vào dist-tag beta nguyên bản của npm.

--channel extended-stable chỉ dành cho gói và quá trình cài đặt vẫn chỉ chạy ở tiền cảnh. OpenClaw đọc bộ chọn extended-stable công khai của npm, xác minh chính xác gói được chọn và cài đặt đúng phiên bản đó. Dữ liệu registry bị thiếu hoặc không nhất quán sẽ khiến thao tác dừng an toàn; hệ thống không bao giờ chuyển về latest. Nếu phiên bản được chọn cũ hơn phiên bản đã cài đặt, yêu cầu xác nhận hạ cấp thông thường vẫn được áp dụng. CLI lưu kênh sau khi cập nhật lõi thành công; lệnh trực tiếp npm install -g openclaw@extended-stable không cập nhật update.channel. Sau khi thay lõi, các Plugin npm chính thức đủ điều kiện có chủ đích để trống/mặc định hoặc latest sẽ hội tụ về đúng phiên bản lõi đó. Các phiên bản ghim chính xác và thẻ khác latest được chỉ định rõ ràng, Plugin bên thứ ba và nguồn không phải npm vẫn giữ nguyên. Các lượt cài đặt từ danh mục được tạo bởi phiên bản OpenClaw hiện tại sẽ giữ lại chủ đích mặc định đó. Những bản ghi cũ chỉ chứa một phiên bản chính xác vẫn được ghim vì OpenClaw không thể phân biệt an toàn giữa một phiên bản ghim tự động cũ và phiên bản do người dùng ghim; hãy chạy openclaw plugins update @openclaw/name một lần trên kênh extended-stable để đưa Plugin đó trở lại chế độ theo dõi chính xác phiên bản lõi.

--channel dev cung cấp một bản checkout GitHub main liên tục dịch chuyển và được duy trì lâu dài. Để cập nhật gói một lần, --tag main ánh xạ đến đặc tả gói github:openclaw/openclaw#main và cài đặt trực tiếp thông qua trình quản lý gói đích (npm/pnpm/bun).

Đối với các Plugin được quản lý, việc thiếu bản phát hành beta chỉ tạo cảnh báo, không phải lỗi: quá trình cập nhật lõi vẫn có thể thành công trong khi Plugin chuyển về bản phát hành mặc định/latest đã ghi nhận.

Xem Các kênh phát hành để biết ngữ nghĩa của từng kênh.

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

Dùng các kênh để thay đổi loại 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à không gian làm việc của bạn trong ~/.openclaw; nó chỉ thay đổi bản cài đặt mã OpenClaw mà CLI và Gateway sử dụng.

# npm package install -> editable git checkoutopenclaw update --channel dev # git checkout -> npm package installopenclaw update --channel stable

Trước tiên, hãy xem trước việc chuyển đổi chế độ cài đặt:

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

dev bảo đảm có một bản checkout git, xây dựng bản đó và cài đặt CLI toàn cục từ bản checkout này. Các kênh stable, extended-stable và beta sử dụng bản cài đặt gói. Extended-stable bị từ chối trên bản checkout git mà không sửa đổi hoặc chuyển đổi bản checkout đó. 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.

Đối với bản cài đặt gói có dịch vụ Gateway được quản lý, openclaw update nhắm đến thư mục gốc của gói mà dịch vụ đó sử dụng. Nếu lệnh openclaw trong shell đến từ một bản cài đặt khác, trình cập nhật sẽ hiển thị cả hai thư mục gốc và đường dẫn Node của dịch vụ được quản lý, đồng thời kiểm tra phiên bản Node đó theo yêu cầu engines.node của bản phát hành đích trước khi thay thế gói.

Phương án 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 quá trình thiết lập ban đầu. Để buộc dùng một loại cài đặt cụ thể, hãy 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 này không gọi trình cập nhật; nó chạy trực tiếp quá trình cài đặt gói toàn cục và có thể khôi phục một bản cài đặt npm mới chỉ được 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ể bằng --version:

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

Phương án khác: dùng npm, pnpm hoặc bun thủ công

npm i -g openclaw@latest

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

Đối với bản cài đặt toàn hệ thống trên Linux do root sở hữu, nếu openclaw update thất bại với EACCES, hãy khôi phục bằng npm hệ thống trong khi vẫn giữ Gateway ở trạng thái dừng để thay thế thủ công. Sử dụng các cờ hồ sơ và môi trường giống như bạn thường dùng cho Gateway đó. Thay /usr/bin/npm bằng npm hệ thống sở hữu tiền tố toàn cục do root quản lý trên máy chủ của bạn:

openclaw gateway stopsudo /usr/bin/npm i -g openclaw@latestopenclaw gateway install --forceopenclaw gateway restart

Sau đó xác minh:

openclaw --versioncurl -fsS http://127.0.0.1:18789/readyzopenclaw plugins list --jsonopenclaw gateway status --deep --jsonopenclaw doctor --lint --json

Khi openclaw update quản lý một bản cài đặt npm toàn cục, trước tiên nó cài đặt đích vào một tiền tố npm tạm thời, xác minh danh mục dist đã đóng gói, rồi thay cây gói sạch vào tiền tố toàn cục thực — tránh việc npm phủ 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, điều này hữu ích trên các máy chủ không thể biên dịch các phần phụ thuộc tùy chọn gốc.

Các lệnh cập nhật npm và cập nhật Plugin do OpenClaw quản lý cũng xóa vùng cách ly chuỗi cung ứng min-release-age của npm (hoặc khóa cấu hình before cũ hơn) cho tiến trình npm con. Chính sách đó tồn tại để bảo vệ chung, nhưng một yêu cầu cập nhật OpenClaw rõ ràng có nghĩa là "cài đặt bản phát hành đã chọn ngay bây giờ".

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 cập nhật tự động

Mặc định bị tắt. Bật trong ~/.openclaw/openclaw.json:

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

Gateway cũng ghi nhật ký gợi ý cập nhật khi khởi động (tắt bằng update.checkOnStart: false). Các lựa chọn extended-stable đã lưu sử dụng đường dẫn gợi ý chỉ đọc này và khoảng thời gian gợi ý 24 giờ hiện có, nhưng không bao giờ kích hoạt quá trình cài đặt tự động, bàn giao, khởi động lại, độ trễ/độ lệch stable hoặc kiểm tra beta. Để hạ cấp hoặc khôi phục sau sự cố, hãy đặt OPENCLAW_NO_AUTO_UPDATE=1 trong môi trường Gateway để chặn việc tự động áp dụ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 bằng trình quản lý gói được yêu cầu thông qua mặt phẳng điều khiển Gateway đang hoạt động (update.run) không thay thế cây gói bên trong tiến trình Gateway đang chạy. Trên các bản cài đặt dịch vụ được quản lý, Gateway khởi chạy một tiến trình bàn giao tách rời, thoát, rồi để luồng CLI openclaw update --yes --json thông thường dừng dịch vụ, thay thế gói, làm mới siêu dữ liệu dịch vụ, khởi động lại, xác minh phiên bản và khả năng truy cập của Gateway, đồng thời khôi phục LaunchAgent macOS đã cài đặt nhưng chưa được tải khi có thể. Nếu Gateway không thể thực hiện việc bàn giao đó một cách an toàn, update.run sẽ báo một lệnh shell an toàn thay vì chạy trình quản lý gói ngay trong tiến trình.

Thẻ cập nhật ở thanh bên của giao diện điều khiển khởi chạy cùng luồng update.run này. Trong ứng dụng macOS đã ký, trước tiên thẻ cập nhật ứng dụng thông qua Sparkle; sau khi khởi chạy lại, ứng dụng đưa Gateway cục bộ được quản lý của mình về phiên bản tương ứng.

Sau khi cập nhật

openclaw doctor

openclaw gateway restart

openclaw health

Quay lui

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

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

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

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

Để trở lại phiên bản mới nhất: git checkout main && git pull.

Nếu bạn gặp khó khăn

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

Liên quan

• Tổng quan cài đặt: tất cả phương thức cài đặt.
• Chẩn đoán: kiểm tra tình trạng hoạt động sau khi cập nhật.
• Di chuyển: hướng dẫn di chuyển giữa các phiên bản lớn.