Chuyển đến nội dung chính

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Luôn cập nhật OpenClaw.

​
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 và 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   # preview without applying
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 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à khả dụng. 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 beta thô của npm cho một lần cập nhật gói riêng lẻ. Với Plugin được quản lý, việc quay về từ kênh beta là một cảnh báo: bản cập nhật lõi vẫn có thể thành công trong khi Plugin dùng bản phát hành default/latest đã ghi nhận vì không có bản beta của Plugin. 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 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. 
# npm package install -> editable git checkout
openclaw update --channel dev

# git checkout -> npm package install
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ó một git checkout, build nó và 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 metadata của dịch vụ và khởi động lại dịch vụ trừ khi bạn truyền --no-restart.

​
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 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 dở. 
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>

​
Phương án 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ì nó 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 đã được thay thế. Khi openclaw update quản lý một bản cài đặt npm toàn cục, nó cài đặt mục tiêu vào một tiền tố npm tạm thời trước, 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. Cách này 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 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 đó hữu ích với các máy chủ nơi các dependency tùy chọn native không thể biên dịch, đồng thời vẫn giữ lỗi ban đầu hiển thị 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ủ đề nâng cao về cài đặt npm

OpenClaw xem các bản cài đặt toàn cục đã đóng gói là chỉ đọc ở runtime, ngay cả khi thư mục gói toàn cục có thể ghi bởi người dùng hiện tại. Các bản cài đặt gói Plugin nằm trong các root npm/git do OpenClaw sở hữu bên dưới thư mục cấu hình người dùng, và quá trình khởi động Gateway không sửa đổi cây gói OpenClaw.Một số thiết lập npm trên Linux cài đặt gói toàn cục dưới các thư mục thuộc sở hữu root như /usr/lib/node_modules/openclaw. OpenClaw hỗ trợ bố cục đó vì các lệnh cài đặt/cập nhật Plugin ghi ra ngoài thư mục gói toàn cục đó.
Cấp quyền ghi cho OpenClaw vào các root cấu hình/trạng thái của nó để các lượt cài đặt Plugin rõ ràng, cập nhật Plugin và dọn dẹp doctor có thể lưu thay đổi:
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
Trước các bản cập nhật gói và lượt cài đặt Plugin rõ ràng, OpenClaw cố gắng kiểm tra dung lượng đĩa theo khả năng tốt nhất cho volume mục tiêu. Dung lượng thấp tạo ra cảnh báo kèm đường dẫn đã kiểm tra, nhưng không chặn bản cập nhật vì quota hệ thống tệp, snapshot và volume mạng có thể thay đổi sau khi kiểm tra. Lượt cài đặt thực tế của trình quản lý gói và xác minh sau cài đặt vẫn là căn cứ có thẩm quyền.

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

Trình tự động cập nhật mặc định tắt. Bật nó trong ~/.openclaw/openclaw.json: 
{
  update: {
    channel: "stable",
    auto: {
      enabled: true,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}
KênhHành vi
stableChờ stableDelayHours, rồi áp dụng với jitter xác định trên stableJitterHours (triển khai phân tán).
betaKiểm tra mỗi betaCheckIntervalHours (mặc định: hằng giờ) và áp dụng ngay.
devKhông tự động áp dụng. Dùng openclaw update thủ công.
Gateway cũng ghi log một 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 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 trình quản lý gói được yêu cầu thông qua handler control-plane Gateway trực tiếp ép 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 ư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

1
Chạy doctor
2
openclaw doctor
3
Di chuyển cấu hình, kiểm tra chính sách DM và kiểm tra sức khỏe Gateway. Chi tiết: Doctor
4
Khởi động lại Gateway
5
openclaw gateway restart
6
Xác minh
7
openclaw health

​
Rollback

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

npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart
npm view openclaw version hiển thị phiên bản đã phát hành hiện tại.

​
Ghim một commit (source)

git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
pnpm install && pnpm build
openclaw gateway restart
Để quay lại 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 source checkout, 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) và chạy lại bản cập nhật.
  • Kiểm tra: Khắc phục sự cố
  • Hỏi trong Discord: https://discord.gg/clawd

​
Liên quan