openclaw update

Cập nhật OpenClaw một cách an toàn và chuyển đổi giữa các kênh stable/beta/dev.

Nếu bạn đã cài đặt qua npm/pnpm/bun (cài đặt global, không có siêu dữ liệu git), việc cập nhật diễn ra qua luồng trình quản lý gói trong Cập nhật.

Cách sử dụng

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw update --channel betaopenclaw update --channel devopenclaw update --tag betaopenclaw update --tag mainopenclaw update --dry-runopenclaw update --no-restartopenclaw update --yesopenclaw update --acknowledge-clawhub-riskopenclaw update --jsonopenclaw --update

Tùy chọn

• --no-restart: bỏ qua việc khởi động lại dịch vụ Gateway sau khi cập nhật thành công. Các bản cập nhật qua trình quản lý gói có khởi động lại Gateway sẽ xác minh rằng dịch vụ đã khởi động lại báo cáo đúng phiên bản đã cập nhật như mong đợi trước khi lệnh thành công.
• --channel <stable|beta|dev>: đặt kênh cập nhật (git + npm; được lưu trong cấu hình).
• --tag <dist-tag|version|spec>: ghi đè mục tiêu gói chỉ cho lần cập nhật này. Với các bản cài đặt bằng gói, main ánh xạ tới github:openclaw/openclaw#main; các đặc tả nguồn GitHub/git được đóng gói vào một tarball tạm thời trước khi cài đặt npm global theo giai đoạn.
• --dry-run: xem trước các hành động cập nhật dự kiến (luồng channel/tag/target/restart) mà không ghi cấu hình, cài đặt, đồng bộ Plugin hoặc khởi động lại.
• --json: in JSON UpdateRunResult để máy đọc được, bao gồm postUpdate.plugins.warnings khi các Plugin được quản lý bị hỏng hoặc không thể tải cần sửa chữa sau khi cập nhật lõi thành công, chi tiết fallback Plugin của kênh beta khi một Plugin không có bản phát hành beta, và postUpdate.plugins.integrityDrifts khi phát hiện sai lệch hiện vật Plugin npm trong quá trình đồng bộ Plugin sau cập nhật.
• --timeout <seconds>: thời gian chờ cho mỗi bước (mặc định là 1800 giây).
• --yes: bỏ qua lời nhắc xác nhận (ví dụ xác nhận hạ cấp).
• --acknowledge-clawhub-risk: sau khi xem lại cảnh báo độ tin cậy của ClawHub cộng đồng, cho phép đồng bộ Plugin sau cập nhật tiếp tục mà không cần lời nhắc tương tác. Nếu không có tùy chọn này, các bản phát hành Plugin ClawHub cộng đồng có rủi ro sẽ bị bỏ qua và giữ nguyên khi OpenClaw không thể nhắc. Các gói ClawHub chính thức và nguồn Plugin OpenClaw đi kèm bỏ qua lời nhắc độ tin cậy bản phát hành này.

openclaw update không có cờ --verbose. Dùng --dry-run để xem trước các hành động channel/tag/install/restart dự kiến, --json để lấy kết quả máy đọc được, và openclaw update status --json khi bạn chỉ cần chi tiết kênh và khả dụng. Nếu bạn đang gỡ lỗi log Gateway quanh một lần cập nhật, độ chi tiết console và cấp độ log tệp là riêng biệt: Gateway --verbose ảnh hưởng đến đầu ra terminal/WebSocket, còn log tệp yêu cầu logging.level: "debug" hoặc "trace" trong cấu hình. Xem log Gateway.

update status

Hiển thị kênh cập nhật đang hoạt động + thẻ/nhánh/SHA git (đối với checkout từ nguồn), cùng khả dụng cập nhật.

openclaw update statusopenclaw update status --jsonopenclaw update status --timeout 10

Tùy chọn:

• --json: in JSON trạng thái để máy đọc được.
• --timeout <seconds>: thời gian chờ cho các kiểm tra (mặc định là 3 giây).

update repair

Chạy lại bước hoàn tất cập nhật sau khi gói lõi đã thay đổi nhưng công việc sửa chữa sau đó không hoàn tất sạch sẽ. Đây là đường dẫn khôi phục được hỗ trợ khi openclaw update đã cài đặt gói lõi mới nhưng đồng bộ Plugin sau lõi, siêu dữ liệu Plugin npm được quản lý, làm mới registry, hoặc sửa chữa doctor vẫn cần hội tụ.

openclaw update repairopenclaw update repair --channel betaopenclaw update repair --acknowledge-clawhub-riskopenclaw update repair --json

Tùy chọn:

• --channel <stable|beta|dev>: lưu kênh cập nhật trước khi sửa chữa và chạy hội tụ Plugin theo kênh đó.
• --json: in JSON hoàn tất để máy đọc được.
• --timeout <seconds>: thời gian chờ cho các bước sửa chữa (mặc định 1800).
• --yes: bỏ qua lời nhắc xác nhận.
• --acknowledge-clawhub-risk: sau khi xem lại cảnh báo độ tin cậy của ClawHub cộng đồng, cho phép hội tụ Plugin trong lúc sửa chữa tiếp tục mà không cần lời nhắc tương tác. Các gói ClawHub chính thức và nguồn Plugin OpenClaw đi kèm bỏ qua lời nhắc độ tin cậy bản phát hành này.
• --no-restart: được chấp nhận để tương đồng với lệnh update; repair không bao giờ khởi động lại Gateway.

openclaw update repair chạy openclaw doctor --fix, tải lại cấu hình và bản ghi cài đặt đã sửa, đồng bộ các Plugin được theo dõi cho kênh cập nhật đang hoạt động, cập nhật các bản cài đặt Plugin npm được quản lý, sửa các payload Plugin đã cấu hình bị thiếu, làm mới registry Plugin, và ghi siêu dữ liệu bản ghi cài đặt đã hội tụ. Nó không cài đặt gói lõi mới và không khởi động lại Gateway.

update wizard

Luồng tương tác để chọn kênh cập nhật và xác nhận có khởi động lại Gateway sau khi cập nhật hay không (mặc định là khởi động lại). Nếu bạn chọn dev mà không có checkout git, nó đề nghị tạo một checkout.

Tùy chọn:

• --timeout <seconds>: thời gian chờ cho từng bước cập nhật (mặc định 1800)

Lệnh này làm gì

Khi bạn chuyển kênh một cách rõ ràng (--channel ...), OpenClaw cũng giữ cho phương thức cài đặt được đồng bộ:

• dev → bảo đảm có một checkout git (mặc định: ~/openclaw, hoặc $OPENCLAW_HOME/openclaw khi OPENCLAW_HOME được đặt; ghi đè bằng OPENCLAW_GIT_DIR), cập nhật nó, và cài đặt CLI global từ checkout đó.
• stable → cài đặt từ npm bằng latest.
• beta → ưu tiên dist-tag npm beta, nhưng fallback về latest khi beta bị thiếu hoặc cũ hơn bản phát hành stable hiện tại.

Trình tự cập nhật lõi tự động của Gateway (khi được bật qua cấu hình) khởi chạy đường dẫn cập nhật CLI bên ngoài trình xử lý yêu cầu Gateway đang chạy. Các bản cập nhật qua trình quản lý gói của control plane update.run và các bản cập nhật checkout git có giám sát cũng dùng một bàn giao dịch vụ được quản lý thay vì thay thế cây gói hoặc dựng lại dist/ bên trong tiến trình Gateway đang chạy. Gateway khởi động một helper tách rời, thoát, và helper chạy đường dẫn CLI openclaw update --yes --json bình thường từ bên ngoài cây tiến trình Gateway. Nếu bàn giao đó không khả dụng, update.run trả về phản hồi có cấu trúc cùng lệnh shell an toàn để chạy thủ công.

Đối với bản cài đặt qua trình quản lý gói, openclaw update phân giải phiên bản gói mục tiêu trước khi gọi trình quản lý gói. Cài đặt npm global dùng quy trình cài đặt theo giai đoạn: OpenClaw cài gói mới vào một prefix npm tạm thời, xác minh bảng kê dist đã đóng gói ở đó, rồi hoán đổi cây gói sạch đó vào prefix global thật. Nếu xác minh thất bại, doctor sau cập nhật, đồng bộ Plugin, và công việc khởi động lại sẽ không chạy từ cây đáng ngờ. Ngay cả khi phiên bản đã cài đặt đã khớp với mục tiêu, lệnh vẫn làm mới bản cài đặt gói global, sau đó chạy đồng bộ Plugin, làm mới hoàn thành lệnh lõi, và công việc khởi động lại. Điều này giữ các sidecar đã đóng gói và bản ghi Plugin do kênh sở hữu đồng bộ với bản dựng OpenClaw đã cài đặt, trong khi để các lần dựng lại hoàn thành lệnh Plugin đầy đủ cho các lần chạy openclaw completion --write-state rõ ràng.

Khi dịch vụ Gateway được quản lý cục bộ đã được cài đặt và khởi động lại được bật, các bản cập nhật qua trình quản lý gói và checkout git dừng dịch vụ đang chạy trước khi thay thế cây gói hoặc thay đổi đầu ra checkout/build. Trình cập nhật sau đó làm mới siêu dữ liệu dịch vụ từ bản cài đặt đã cập nhật, khởi động lại dịch vụ, và xác minh Gateway đã khởi động lại trước khi báo cáo Gateway: restarted and verified.. Các bản cập nhật qua trình quản lý gói còn xác minh Gateway đã khởi động lại báo cáo phiên bản gói mong đợi; các bản cập nhật checkout git xác minh tình trạng Gateway và mức sẵn sàng dịch vụ sau khi dựng lại. Trên macOS, kiểm tra sau cập nhật cũng xác minh LaunchAgent đã được tải/đang chạy cho hồ sơ đang hoạt động và cổng loopback đã cấu hình hoạt động tốt. Nếu plist đã được cài đặt nhưng launchd không giám sát nó, OpenClaw tự động bootstrap lại LaunchAgent, sau đó chạy lại các kiểm tra tình trạng/phiên bản/kênh sẵn sàng. Một lần bootstrap mới tải trực tiếp job RunAtLoad, nên khôi phục cập nhật không kickstart -k ngay Gateway vừa được sinh ra. Nếu Gateway vẫn không trở nên khỏe mạnh, lệnh thoát khác không và in đường dẫn log khởi động lại cùng hướng dẫn khởi động lại, cài đặt lại, và rollback gói rõ ràng. Nếu không thể khởi động lại, lệnh in Gateway: restart skipped (...) hoặc Gateway: restart failed: ... với gợi ý thủ công openclaw gateway restart. Với --no-restart, việc thay thế gói hoặc dựng lại git vẫn chạy nhưng dịch vụ được quản lý không bị dừng hoặc khởi động lại, nên Gateway đang chạy có thể tiếp tục dùng mã cũ cho đến khi bạn khởi động lại thủ công.

Dạng phản hồi control plane

Khi update.run được gọi qua control plane của Gateway trên một bản cài đặt qua trình quản lý gói hoặc checkout git có giám sát, trình xử lý báo cáo việc khởi tạo bàn giao riêng biệt với lần cập nhật CLI tiếp tục sau khi Gateway thoát:

• ok: true, result.status: "skipped", result.reason: "managed-service-handoff-started", và handoff.status: "started" nghĩa là Gateway đã tạo bàn giao dịch vụ được quản lý và lên lịch tự khởi động lại để helper tách rời có thể chạy openclaw update --yes --json bên ngoài tiến trình dịch vụ đang chạy.
• ok: false, result.reason: "managed-service-handoff-unavailable", và handoff.status: "unavailable" nghĩa là OpenClaw không tìm thấy ranh giới dịch vụ giám sát và danh tính dịch vụ bền vững để bàn giao an toàn. Ví dụ, bàn giao systemd yêu cầu danh tính unit OpenClaw (OPENCLAW_SYSTEMD_UNIT), không chỉ các dấu hiệu tiến trình systemd xung quanh. Phản hồi bao gồm handoff.command, lệnh shell để chạy từ bên ngoài Gateway.
• ok: false, result.reason: "managed-service-handoff-failed" nghĩa là Gateway đã cố tạo bàn giao nhưng không thể sinh helper tách rời.

Payload sentinel vẫn được ghi trước khi Gateway thoát, và bàn giao CLI cập nhật cùng sentinel khởi động lại sau khi các kiểm tra tình trạng khởi động lại dịch vụ hoàn tất. Trong lúc bàn giao, sentinel có thể mang stats.reason: "restart-health-pending" mà không có continuation thành công; Gateway đã khởi động lại tiếp tục polling nó và chỉ kích hoạt continuation sau khi CLI đã xác minh tình trạng dịch vụ và ghi lại sentinel với kết quả ok cuối cùng. openclaw status và openclaw status --all hiển thị một hàng Update restart khi sentinel đó đang chờ hoặc thất bại, và update.status làm mới rồi trả về sentinel mới nhất.

Luồng checkout git

Chọn kênh

• stable: checkout thẻ non-beta mới nhất, rồi build và doctor.
• beta: ưu tiên thẻ -beta mới nhất, nhưng fallback về thẻ stable mới nhất khi beta bị thiếu hoặc cũ hơn.
• dev: checkout main, rồi fetch và rebase.

Các bước cập nhật

Trên kênh cập nhật beta, các bản cài Plugin npm và ClawHub đang được theo dõi theo nhánh mặc định/latest sẽ thử bản phát hành Plugin @beta trước. Nếu Plugin không có bản phát hành beta, OpenClaw fallback về spec mặc định/latest đã ghi lại và báo cáo điều đó dưới dạng cảnh báo. Với Plugin npm, OpenClaw cũng fallback khi package beta tồn tại nhưng không vượt qua xác thực cài đặt. Các cảnh báo fallback Plugin này không làm bản cập nhật lõi thất bại. Phiên bản chính xác và tag tường minh sẽ không bị viết lại.

Cách viết tắt --update

openclaw --update được viết lại thành openclaw update (hữu ích cho shell và script launcher).

Liên quan

• openclaw doctor (đề nghị chạy cập nhật trước trên các checkout git)
• Kênh phát triển
• Cập nhật
• Tham chiếu CLI