Hướng dẫn nâng cấp OpenClaw trên Docker và VPS an toàn, không lo mất cấu hình 

Bạn vừa thấy OpenClaw có phiên bản mới và muốn nâng cấp ngay, nhưng lo cấu hình, trí nhớ của agent và các kết nối Telegram bị hỏng giữa chừng? Hãy yên tâm! Trong bài viết này, Tino sẽ hướng dẫn bạn nâng cấp OpenClaw trên Docker và VPS an toàn, không sợ mất cấu hình.

OpenClaw có cần nâng cấp thường xuyên không?

Không bắt buộc phải nâng cấp ngay mỗi khi OpenClaw xuất hiện phiên bản mới. Tuy nhiên, cập nhật định kỳ mang lại một số lợi ích như:

• Nhận các bản sửa lỗi và cải thiện độ ổn định.
• Cập nhật tính năng mới cho Gateway và AI Agent.
• Cải thiện khả năng tương thích với model và provider.
• Cập nhật plugin chính thức.
• Nhận các cải tiến liên quan đến bảo mật.
• Giảm nguy cơ gặp lỗi khi phiên bản đang sử dụng đã quá cũ.

Nếu OpenClaw đang phục vụ công việc quan trọng, bạn nên đọc release notes trước và sao lưu dữ liệu trước những đợt nâng cấp lớn.

Cần chuẩn bị gì trước khi nâng cấp OpenClaw?

Dù đang sử dụng Docker hay cài OpenClaw trực tiếp trên VPS, bạn không nên cập nhật ngay khi chưa kiểm tra hệ thống.

Tài liệu OpenClaw khuyến nghị tạo bản sao lưu đã được xác minh trước những lần cập nhật quan trọng. Các file phục hồi được OpenClaw tự tạo trong quá trình migration không được xem là bản backup đầy đủ.

Kiểm tra phiên bản OpenClaw hiện tại

Với OpenClaw cài trực tiếp:

openclaw --version

Nếu sử dụng Docker Compose:

docker compose run --rm openclaw-cli --version

Bạn có thể so sánh phiên bản đang chạy với phiên bản stable hiện tại trên trang Releases chính thức của OpenClaw.

Kiểm tra phiên bản Node.js

Đối với bản OpenClaw cài trực tiếp trên VPS, hãy kiểm tra Node.js:

node -v

Theo tài liệu hiện tại, OpenClaw hỗ trợ: Node.js 24.16+ hoặc Node.js 26.1+

Node.js 26 hiện là runtime được khuyến nghị. Node 22, 23 và 25 không còn nằm trong nhóm runtime được hỗ trợ.

Nếu VPS đang sử dụng Node.js quá cũ, nên nâng cấp Node trước khi tiếp tục cập nhật OpenClaw.

Sao lưu dữ liệu OpenClaw

Với cấu hình mặc định trên Linux, dữ liệu OpenClaw thường nằm trong:

~/.openclaw

Bạn có thể tạo một bản sao trước khi nâng cấp:

cp -a ~/.openclaw ~/.openclaw-backup-$(date +%F-%H%M)

Nếu đã thay đổi thư mục lưu trữ OpenClaw, hãy sao lưu đúng thư mục đang được sử dụng.

Đối với Docker, dữ liệu quan trọng thường được mount vào:

/home/node/.openclaw

Trong cấu hình Docker chính thức, thư mục này được liên kết với OPENCLAW_CONFIG_DIR trên máy chủ. Đây là nơi chứa cấu hình, state, thông tin xác thực, plugin và nhiều dữ liệu cần duy trì qua các lần tạo lại container.

Hướng dẫn nâng cấp OpenClaw trên VPS

Phần này áp dụng cho trường hợp OpenClaw được cài trực tiếp trên Linux/VPS bằng npm, pnpm, Bun hoặc Git, thay vì chạy bên trong container Docker.

OpenClaw hiện có trình cập nhật tích hợp:

openclaw update

Đây cũng là phương pháp được tài liệu chính thức khuyến nghị. Trình cập nhật có thể nhận diện hình thức cài đặt, kiểm tra phiên bản mới, chuẩn bị bản cập nhật và xác minh hệ thống sau khi hoàn tất.

Bước 1: SSH vào VPS

Đăng nhập VPS bằng SSH. Nếu sử dụng Xshell, PuTTY hoặc Terminal khác, chỉ cần kết nối VPS như bình thường.

Sau đó kiểm tra phiên bản:

openclaw --version

Bước 2: Kiểm tra trạng thái cập nhật

Chạy:

openclaw update status

Lệnh này giúp kiểm tra channel và tình trạng cập nhật hiện tại.

Nếu cần kết quả chi tiết hơn:

openclaw update status --json

OpenClaw hỗ trợ nhiều channel, chẳng hạn:

• stable
• extended-stable
• beta
• dev

Với người dùng thông thường hoặc môi trường đang vận hành thực tế, stable thường dễ quản lý hơn beta hoặc dev.

Bước 3: Chạy thử quá trình nâng cấp

Trước khi cập nhật thật, có thể chạy:

openclaw update --dry-run

–dry-run giúp OpenClaw kiểm tra và mô phỏng quy trình cập nhật nhưng chưa áp dụng thay đổi.

Đây là bước hữu ích nếu bạn muốn phát hiện trước các vấn đề liên quan đến:

• Phiên bản Node.js.
• Cấu hình không hợp lệ.
• Quyền truy cập.
• Plugin.
• Service Gateway.
• Phiên bản dự kiến được nâng cấp.

Bước 4: Nâng cấp OpenClaw

Khi mọi kiểm tra đã ổn, chạy:

openclaw update

OpenClaw sẽ thực hiện quy trình cập nhật dựa trên kiểu cài đặt hiện tại. Với những phiên bản OpenClaw mới, quá trình cập nhật còn có cơ chế kiểm tra ứng viên cập nhật trước khi kích hoạt. Gateway đang phục vụ có thể tiếp tục hoạt động trong nhiều bước kiểm tra ban đầu, sau đó OpenClaw mới chuyển sang phiên bản mới và xác minh lại hệ thống. 

Không nên đóng Terminal hoặc dừng tiến trình giữa lúc quá trình cập nhật đang thay đổi package hay dữ liệu.

Bước 5: Kiểm tra OpenClaw sau khi nâng cấp

Kiểm tra phiên bản:

openclaw --version

Sau đó chạy:

openclaw doctor

doctor giúp kiểm tra cấu hình, Gateway và một số vấn đề liên quan đến phiên bản mới.

Nếu cần khởi động lại Gateway thủ công:

openclaw gateway restart

Cuối cùng kiểm tra sức khỏe hệ thống:

openclaw health

Với một lần openclaw update thành công trên Gateway được OpenClaw quản lý, quá trình restart và xác minh thường đã được thực hiện tự động. Các lệnh trên vẫn hữu ích khi muốn kiểm tra lại hệ thống hoặc sau một lần cập nhật thủ công.

Hướng dẫn nâng cấp OpenClaw trên Docker

Nếu OpenClaw đang chạy bằng Docker, không nên áp dụng cách nâng cấp package trực tiếp bên trong container như một bản cài VPS thông thường.

Container có tính chất có thể thay thế. Vì vậy, cách phù hợp là:

Tải image OpenClaw mới → tạo lại container → tiếp tục sử dụng state/config đã mount.

Tài liệu OpenClaw cũng hướng người dùng Docker, Podman và Kubernetes sang quy trình thay thế container image.

Trường hợp 1: Sử dụng image OpenClaw có sẵn

Nếu đang sử dụng Docker Compose với image chính thức, trước tiên hãy vào thư mục chứa:

docker-compose.yml

hoặc:

compose.yml

Kiểm tra file .env.

Bạn có thể sử dụng image stable mới nhất:

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest

Hoặc cố định một phiên bản cụ thể, ví dụ:

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:2026.9.5

Việc cố định phiên bản giúp quá trình triển khai dễ kiểm soát hơn vì image sẽ không tự chuyển sang một phiên bản stable mới khác.

OpenClaw hiện công bố image chính thức trên GitHub Container Registry và Docker Hub. Tài liệu khuyến nghị sử dụng image chính thức thay vì mirror không được dự án quản lý.

Bước 1: Tải image mới

Chạy:

docker compose pull openclaw-gateway openclaw-cli

Docker sẽ tải image được khai báo trong cấu hình.

Bước 2: Tạo lại Gateway

Chạy:

docker compose up -d openclaw-gateway

Container Gateway sẽ được tạo lại từ image mới.

Dữ liệu vẫn được giữ nếu state/config đã được mount đúng cách.

OpenClaw sẽ thực hiện các migration an toàn cần thiết trên dữ liệu đã mount trước khi Gateway chuyển sang trạng thái sẵn sàng.

Bước 3: Kiểm tra container

Chạy:

docker compose ps

Sau đó kiểm tra phiên bản:

docker compose run --rm openclaw-cli --version

Kiểm tra OpenClaw:

docker compose run --rm openclaw-cli doctor --json

Tài liệu chính thức cũng sử dụng doctor –json như bước kiểm tra deployment sau khi thay image.

Nếu cần xem log:

docker compose logs --tail=100 openclaw-gateway

Nếu Gateway hoạt động ổn định và không xuất hiện lỗi nghiêm trọng, quá trình nâng cấp đã hoàn tất.

Trường hợp 2: OpenClaw Docker được build từ source

Một số hệ thống không sử dụng image dựng sẵn mà clone mã nguồn OpenClaw từ GitHub rồi tự build Docker image.

Trong trường hợp này, vào thư mục source:

cd openclaw

Sau đó cập nhật mã nguồn:

git pull --ff-only

Tiếp tục chạy:

OPENCLAW_SKIP_ONBOARDING=1 ./scripts/docker/setup.sh

Cuối cùng kiểm tra:

docker compose run --rm openclaw-cli doctor --json

Đây là quy trình được tài liệu OpenClaw hiện tại đưa ra cho image được build từ source.

Điểm quan trọng là không xóa thư mục cấu hình hoặc volume dữ liệu trong quá trình build lại.

Cách xử lý khi OpenClaw nâng cấp bị lỗi

Dù OpenClaw đã bổ sung nhiều cơ chế kiểm tra và phục hồi, lỗi vẫn có thể xảy ra do cấu hình cũ, plugin, quyền file hoặc phiên bản runtime.

OpenClaw Gateway không khởi động

Với bản cài trực tiếp trên VPS, chạy:

openclaw doctor

Nếu OpenClaw yêu cầu sửa cấu hình:

openclaw doctor --fix

Sau đó:

openclaw gateway restart

Kiểm tra:

openclaw health

Docker liên tục restart sau khi nâng cấp

Trong một số trường hợp, phiên bản mới phát hiện dữ liệu cũ cần sửa nhưng không thể tự xử lý an toàn.

OpenClaw sẽ không đánh dấu Gateway khỏe mạnh nếu migration không thể hoàn tất.

Tài liệu khuyến nghị giữ nguyên volume/state, sau đó chạy image mới một lần với:

openclaw doctor --fix

Ví dụ theo cấu trúc Docker chung:

docker run --rm \

  -v <openclaw-state>:/home/node/.openclaw \

  <image> \

  openclaw doctor --fix

Sau khi Doctor hoàn thành, khởi động lại Gateway bằng command mặc định.

Nếu sử dụng Docker Compose đã tùy chỉnh nhiều volume, cần đảm bảo container chạy Doctor sử dụng đúng state/config mount giống Gateway.

Lỗi quyền truy cập khi chạy Docker

Image Docker OpenClaw mặc định chạy bằng user node, UID 1000.

Nếu thư mục trên VPS không cho phép UID này truy cập, có thể xuất hiện lỗi permission.

Ví dụ:

sudo chown -R 1000:1000 /path/to/openclaw-config

Hãy thay đường dẫn bằng thư mục cấu hình thực tế của hệ thống.

Plugin gặp lỗi sau khi cập nhật

openclaw update có thể tiếp tục cập nhật core ngay cả khi một plugin riêng lẻ gặp lỗi.

OpenClaw thường hiển thị lệnh cần thực hiện tiếp theo.

Ví dụ:

openclaw plugins update <plugin-id>

Nếu plugin không thể load:

openclaw doctor --fix

Sau đó kiểm tra lại Gateway.

Lệnh openclaw không hoạt động

Nếu gặp lỗi openclaw: command not found, hãy kiểm tra npm prefix:

npm prefix -g

Sau đó kiểm tra PATH:

echo "$PATH"

Trên Linux, OpenClaw thường không được tìm thấy khi thư mục global npm chưa nằm trong PATH. Tài liệu OpenClaw cũng lưu ý đây là nguyên nhân phổ biến của lỗi command not found.

Một số lưu ý khi nâng cấp OpenClaw

• Sao lưu trước khi cập nhật: Nên backup thư mục cấu hình, state và dữ liệu quan trọng để có thể khôi phục khi phát sinh lỗi.
• Kiểm tra phiên bản Node.js: Nếu OpenClaw được cài trực tiếp trên VPS, hãy đảm bảo Node.js đáp ứng yêu cầu của phiên bản mới.
• Đọc release notes: Kiểm tra các thay đổi lớn, lỗi đã sửa và yêu cầu mới trước khi nâng cấp.
• Không xóa volume Docker: Khi cập nhật OpenClaw bằng Docker, cần giữ nguyên volume hoặc thư mục chứa state/config.
• Ưu tiên mount toàn bộ thư mục cấu hình: Với Docker, nên mount /home/node/.openclaw thay vì chỉ bind riêng file cấu hình.
• Kiểm tra sau khi nâng cấp: Xác nhận phiên bản mới, trạng thái Gateway, log và chạy openclaw doctor khi cần.
• Không cần cập nhật ngay lập tức: Với hệ thống đang hoạt động ổn định, có thể chờ thêm để theo dõi phản hồi về phiên bản mới trước khi triển khai.

Các bài viết liên quan:

• Hướng dẫn cài đặt và sử dụng ClawHub CLI trên OpenClaw
• Hướng dẫn cài đặt OpenClaw Skills trên ClawHub không cần code
• Hướng dẫn cách lấy API Token Slack để kết nối với OpenClaw
• Hướng dẫn cài đặt OpenClaw trên VPS bằng Docker
• Hướng dẫn cách lấy API Token Telegram để kết nối với OpenClaw
• OpenClaw Skills là gì?
• Hướng dẫn kết nối Zalo với OpenClaw
• Phân biệt Skills và Plugin trong OpenClaw
• Hướng dẫn tạo Custom Skills cho OpenClaw
• Hướng dẫn kết nối Codex (ChatGPT OAuth) với OpenClaw
• Hướng dẫn kết nối Discord với OpenClaw

Kết luận

Nâng cấp OpenClaw không quá phức tạp nếu xác định đúng phương thức cài đặt ngay từ đầu. Với OpenClaw cài trực tiếp trên VPS, cách đơn giản nhất hiện nay là sử dụng openclaw update. Với OpenClaw chạy bằng Docker, quy trình phù hợp là cập nhật image rồi tạo lại container trong khi vẫn giữ nguyên state và cấu hình đã mount.

Những câu hỏi thường gặp