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

Nâng cấp OpenClaw an toàn gồm ba việc: sao lưu thư mục ~/.openclaw, chạy đúng lệnh cập nhật cho kiểu cài của bạn, rồi kiểm tra bằng openclaw doctor và openclaw health. Bản cài trực tiếp dùng openclaw update; bản Docker thay image mới và giữ nguyên volume; VPS OpenClaw của Tino nâng cấp bằng một nút trên trang quản trị.

Bài này thuộc nhóm cài đặt và vận hành OpenClaw trên VPS; khái niệm Gateway, agent có ở bài OpenClaw là gì.

Cập nhật 24/10/2026. Tại thời điểm viết, bản stable trên GitHub Releases là 2026.10.6 (22/10/2026). Ảnh chụp trên VPS chạy 2026.9.4 → 2026.9.5; các lệnh vẫn dùng như cũ.

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

OpenClaw không bắt buộc nâng cấp ngay mỗi khi có bản mới, nhưng nên cập nhật định kỳ vì dự án phát hành dày và nhiều bản sửa lỗi bảo mật. Cập nhật mang lại:

• Bản sửa lỗi và cải thiện độ ổn định.
• Tính năng mới cho Gateway và AI Agent.
• Tương thích tốt hơn với model và provider mới.
• Cập nhật plugin chính thức.
• Bản vá bảo mật.
• Giảm rủi ro khi bản đang dùng đã quá cũ.

Nếu OpenClaw phục vụ công việc quan trọng, đọc release notes (docs.openclaw.ai/releases) và sao lưu trước các đợt nâng cấp lớn.

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

Trước khi nâng cấp OpenClaw, kiểm phiên bản hiện tại, phiên bản Node.js và tạo bản sao lưu đã xác minh. Tài liệu OpenClaw lưu ý các tệp phục hồi do OpenClaw tự tạo khi migrate không thay được bản sao lưu đầy đủ (OpenClaw: Updating).

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

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

openclaw --version

Với Docker Compose:

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

So phiên bản đang chạy với bản stable trên GitHub Releases của OpenClaw. OpenClaw đánh số theo lịch YYYY.M.N (ví dụ 2026.10.6), bản beta có hậu tố -beta.N.

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

Với bản OpenClaw cài trực tiếp trên VPS, kiểm tra Node.js:

node -v

Từ OpenClaw 2026.10.6, bản cài yêu cầu Node 24.22.1 trở lên trên nhánh 24, hoặc Node 26.12.1 trở lên; openclaw update từ chối cài trên Node cũ hơn. Ví dụ VPS trong ảnh chạy Node 24.21.0 sẽ phải nâng Node trước khi lên 2026.10.6.

Bài cũ ghi “Node 24.16+ hoặc 26.1+”; mức này đã tăng theo release 2026.10.6 (GitHub Releases, npm engines, truy cập 24/10/2026). Trang cài đặt trong docs có thể vẫn ghi mức cũ.

Nếu Gateway chạy như service và trỏ tới một tệp Node cố định, cập nhật cả định nghĩa service; đổi Node trong shell không tự đổi Node của service.

Sao lưu dữ liệu OpenClaw

Cách sao lưu được khuyến nghị là lệnh tích hợp, tạo tệp lưu trữ rồi kiểm tra ngay tính toàn vẹn (OpenClaw CLI: backup):

openclaw backup create --verify

Lệnh này gom cấu hình, state, cơ sở dữ liệu SQLite của từng agent và workspace. Nếu muốn bản sao thủ công thêm, với cấu hình mặc định trên Linux, dữ liệu nằm trong ~/.openclaw:

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

Nếu đã đổi thư mục lưu OpenClaw, sao lưu đúng thư mục đang dùng. Với Docker, dữ liệu quan trọng thường mount vào /home/node/.openclaw và 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. Lưu bản sao lưu ra ngoài VPS; cách tự động có ở bài tự động backup n8n và OpenClaw lên Google Drive.

Cách nâng cấp OpenClaw trên VPS (cài trực tiếp)

Với OpenClaw cài trực tiếp trên Linux/VPS bằng npm, pnpm, Bun hoặc Git, dùng trình cập nhật tích hợp openclaw update. Lệnh này nhận diện kiểu cài, kiểm bản mới trong khi Gateway cũ vẫn phục vụ, rồi kích hoạt và xác minh (OpenClaw CLI: update).

Bước 1: SSH vào VPS

Đăng nhập VPS bằng Xshell, PuTTY hoặc Terminal (xem SSH là gì), rồi kiểm tra phiên bản bằng openclaw --version.

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

openclaw update status

Lệnh hiển thị kiểu cài, kênh cập nhật và bản mới nếu có.

Muốn kết quả chi tiết hơn:

openclaw update status --json

OpenClaw có bốn kênh: stable, extended-stable, beta, dev. Môi trường đang vận hành nên dùng stable; extended-stable nhận bản theo chu kỳ tháng cho ai muốn cập nhật thưa hơn.

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

openclaw update --dry-run

--dry-run kiểm tra và mô phỏng quy trình nhưng chưa áp dụng, giúp phát hiện trước vấn đề về phiên bản Node.js, cấu hình không hợp lệ, quyền truy cập, plugin, service Gateway và phiên bản đích.

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

openclaw update

OpenClaw chuẩn bị bản mới riêng, để chính bản mới kiểm cấu hình, schema cơ sở dữ liệu, yêu cầu Node và plugin trước khi kích hoạt. Gateway đang chạy tiếp tục phục vụ trong các bước kiểm tra đầu, sau đó mới chuyển sang bản mới và xác minh lại.

Không đóng terminal hay dừng tiến trình khi quá trình cập nhật đang thay gói hoặc dữ liệu. Trên Linux, nếu service Gateway systemd đang bị mask, mở mask trước (systemctl --user unmask openclaw-gateway.service), nếu không trình cập nhật sẽ từ chối.

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

openclaw --version

Sau đó chạy kiểm tra cấu hình và sức khoẻ Gateway:

openclaw doctor
openclaw health

doctor kiểm cấu hình, Gateway và các vấn đề liên quan bản mới; health lấy ảnh chụp tình trạng Gateway qua RPC. Với một lần openclaw update thành công trên Gateway do OpenClaw quản lý, bước restart và xác minh đã chạy tự động; chỉ cần openclaw gateway restart khi bạn tự cập nhật thủ công.

Bản cài trước tháng 7/2026 cần làm gì?

Bản cài trước tháng 7/2026 phải lên 2026.9.5 trước, chạy Doctor migration, rồi mới lên latest (OpenClaw: Upgrading very old versions). Với bản cài npm có service Gateway:

openclaw gateway stop &&
  npm install -g openclaw@2026.9.5 --allow-scripts=openclaw &&
  openclaw --version &&
  openclaw doctor --fix

Xác nhận phiên bản là 2026.9.5 và Doctor đã nhập dữ liệu cũ, rồi cài bản hiện hành:

npm install -g openclaw@latest --allow-scripts=openclaw &&
  openclaw doctor --fix &&
  openclaw gateway start &&
  openclaw gateway status --deep

Cờ --allow-scripts=openclaw dùng cho npm 12 hoặc npm 11.16+; với npm 11.15 trở xuống, bỏ cờ này.

Cách nâng cấp OpenClaw trên Docker

Với OpenClaw chạy bằng Docker, không cập nhật gói bên trong container như bản cài VPS thường. Cách đúng là tải image mới, tạo lại container và dùng tiếp state/config đã mount.

Khi bạn thay image nhưng giữ nguyên volume, entrypoint của image tự chạy openclaw doctor --fix --non-interactive trước khi bật Gateway, nên lần nâng cấp image thường không cần chạy Doctor riêng (OpenClaw: Docker).

Trường hợp 1: Dùng image OpenClaw có sẵn

Vào thư mục chứa docker-compose.yml (hoặc compose.yml) và kiểm tệp .env. Dùng image stable mới:

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest

Hoặc cố định một phiên bản để triển khai dễ kiểm soát, ví dụ:

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:2026.10.6

OpenClaw phát hành image chính thức trên GitHub Container Registry (ghcr.io/openclaw/openclaw) và Docker Hub (openclaw/openclaw); tài liệu khuyên tránh mirror không chính chủ.

Bước 1–3: tải image, dừng container cũ, rồi tạo lại Gateway:

docker compose pull openclaw-gateway openclaw-cli
docker compose stop openclaw-gateway
docker compose up -d openclaw-gateway

Tài liệu yêu cầu dừng container cũ trước khi bật container mới, vì bước sửa dữ liệu lúc khởi động cần độc quyền với state; mỗi volume state chỉ chạy một Gateway. Dữ liệu được giữ nếu state/config đã mount đúng.

Bước 4: kiểm tra container, phiên bản và tình trạng:

docker compose ps
docker compose run --rm openclaw-cli --version
docker compose run --rm openclaw-cli doctor --json
docker compose logs --tail=100 openclaw-gateway

Nếu Gateway chạy ổn và log không có lỗi nghiêm trọng, quá trình nâng cấp đã xong.

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

Nếu bạn clone mã nguồn OpenClaw rồi tự build image, vào thư mục source và cập nhật:

cd openclaw
git pull --ff-only
OPENCLAW_SKIP_ONBOARDING=1 ./scripts/docker/setup.sh
docker compose run --rm openclaw-cli doctor --json

Không xoá thư mục cấu hình hay volume dữ liệu khi build lại.

Cách nâng cấp OpenClaw trên VPS OpenClaw của Tino

Trên VPS OpenClaw của Tino, bạn nâng cấp OpenClaw ngay trên trang quản trị, không cần SSH. Trang quản trị dùng cách thay Docker image như mục trên. Cách vào trang quản trị xem ở hướng dẫn truy cập và cấu hình VPS OpenClaw.

Bước 1: đăng nhập trang quản lý dịch vụ Tino, chọn dịch vụ VPS OpenClaw đang dùng.

Bước 2: chuyển sang tab OpenClaw → Phiên bản & Nâng cấp.

Bước 3: nhấn Nâng cấp OpenClaw.

Bước 4: khi hộp thoại hiện ra, chọn Xác nhận nâng cấp.

Hệ thống tải Docker image mới và tạo lại container OpenClaw; quá trình mất vài phút và dịch vụ tạm gián đoạn. Xong, nhấn Làm mới để xem phiên bản. Nếu có thông báo cập nhật Management API, chọn Cập nhật ngay để nâng thành phần quản lý riêng.

Nên nâng cấp lúc ít người dùng bot, và nhắn thử agent sau khi xong để chắc kênh chat vẫn hoạt động.

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

Lỗi sau nâng cấp OpenClaw thường do cấu hình cũ, plugin, quyền tệp hoặc phiên bản Node. Lệnh đầu tiên nên chạy là openclaw doctor.

OpenClaw Gateway không khởi động

openclaw doctor
openclaw doctor --fix
openclaw gateway restart
openclaw health

Nếu bản mới để lại trạng thái dở dang, openclaw update status sẽ chỉ ra và gợi ý openclaw update repair để tiếp tục hoặc khôi phục (OpenClaw CLI: update).

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

Bản mới có thể phát hiện dữ liệu cũ cần sửa nhưng không tự xử lý an toàn được; OpenClaw không đánh dấu Gateway khoẻ nếu migration chưa xong. Tài liệu khuyên giữ nguyên volume/state rồi chạy image mới một lần với openclaw doctor --fix:

docker run --rm \
  -v <openclaw-state>:/home/node/.openclaw \
  <image> \
  openclaw doctor --fix

Doctor xong, khởi động lại Gateway bằng lệnh mặc định. Nếu Compose có nhiều volume tuỳ chỉnh, container chạy Doctor phải mount đúng state/config như Gateway.

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

Image OpenClaw chạy bằng user node (UID 1000). Nếu thư mục trên VPS không cho UID này ghi, sẽ xuất hiện lỗi permission. Ví dụ sửa:

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

Thay đường dẫn bằng thư mục cấu hình thực tế.

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

openclaw update có thể vẫn cập nhật core khi một plugin lỗi, và thường in lệnh cần làm tiếp, ví dụ:

openclaw plugins update <plugin-id>
openclaw doctor --fix

Lệnh openclaw không hoạt động (command not found)

npm prefix -g
echo "$PATH"

Trên Linux, lỗi openclaw: command not found thường do thư mục global của npm chưa nằm trong PATH.

Lưu ý khi nâng cấp OpenClaw

• Sao lưu trước: openclaw backup create --verify, lưu bản sao ra ngoài VPS.
• Kiểm Node.js: đáp ứng mức yêu cầu của bản đích (24.22.1+ hoặc 26.12.1+ từ 2026.10.6).
• Đọc release notes: xem thay đổi lớn và yêu cầu mới.
• Không xoá volume Docker: giữ nguyên volume hoặc thư mục state/config.
• Mount cả thư mục cấu hình: mount /home/node/.openclaw thay vì chỉ một tệp cấu hình.
• Kiểm tra sau nâng cấp: phiên bản, trạng thái Gateway, log, openclaw doctor.
• Không cần lên ngay: hệ thống đang ổn định có thể chờ vài ngày theo dõi phản hồi; kênh extended-stable dành cho nhu cầu này.
• Hạ cấp thận trọng: sau khi bản mới migrate SQLite, cài lại gói cũ chưa chắc chạy được; cần bản sao lưu từ trước khi nâng cấp.

Nếu sau nâng cấp agent bắt đầu lặp lệnh, xem cách sửa lỗi Tool Loop trong OpenClaw; nếu tự cài ở VPS trống, quy trình từ đầu có ở hướng dẫn cài đặt OpenClaw trên VPS.

Kết luận

Nâng cấp OpenClaw không phức tạp nếu xác định đúng kiểu cài. Bản cài trực tiếp dùng openclaw update; bản Docker thay image rồi tạo lại container, giữ nguyên state; VPS OpenClaw của Tino nâng cấp bằng nút trên trang quản trị. Trong mọi trường hợp, sao lưu trước và kiểm tra bằng doctor, health sau khi xong.

Muốn chạy OpenClaw 24/7 mà không tự cài? VPS OpenClaw của Tino cài sẵn OpenClaw trên VPS NVMe đặt tại Việt Nam; bạn vẫn có quyền root để cấu hình. Xem cấu hình và giá trên trang sản phẩm.

Bài viết liên quan:

• Xoá và lưu trữ session bằng OpenClaw CLI
• Chuyển từ Cron cũ sang Automations trong OpenClaw
• Rủi ro bảo mật khi dùng OpenClaw
• Docker là gì?
• Cài đặt và sử dụng ClawHub CLI trên OpenClaw

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