Chuyển OpenClaw sang máy mới

Hướng dẫn này giúp các bạn chuyển OpenClaw Gateway từ máy này sang máy khác mà không cần làm lại onboarding.

Về mặt khái niệm thì migration khá đơn giản:

  • Copy state directory ($OPENCLAW_STATE_DIR, mặc định: ~/.openclaw/) — bao gồm config, auth, sessions và channel state.
  • Copy workspace của bạn (mặc định ~/.openclaw/workspace/) — bao gồm các file agent (memory, prompts, v.v.).

Nhưng có một số lỗi phổ biến liên quan đến profiles, permissions và partial copies.

Trước khi bắt đầu (những gì bạn đang migrate)

1) Xác định state directory của bạn

Hầu hết các cài đặt dùng mặc định:

  • State dir: ~/.openclaw/

Nhưng có thể khác nếu bạn dùng:

  • --profile <name> (thường trở thành ~/.openclaw-<profile>/)
  • OPENCLAW_STATE_DIR=/some/path

Nếu không chắc, chạy lệnh này trên máy cũ:

openclaw status

Tìm các thông tin về OPENCLAW_STATE_DIR / profile trong output. Nếu bạn chạy nhiều gateways, lặp lại cho từng profile.

2) Xác định workspace của bạn

Các giá trị mặc định phổ biến:

  • ~/.openclaw/workspace/ (workspace được khuyên dùng)
  • một thư mục tùy chỉnh bạn đã tạo

Workspace là nơi chứa các file như MEMORY.md, USER.md và memory/*.md.

3) Hiểu những gì bạn sẽ giữ lại

Nếu copy cả hai state dir và workspace, bạn sẽ giữ:

  • Cấu hình Gateway (openclaw.json)
  • Auth profiles / API keys / OAuth tokens
  • Lịch sử session + trạng thái agent
  • Trạng thái channel (ví dụ: đăng nhập WhatsApp/session)
  • Các file workspace của bạn (memory, skills notes, v.v.)

Nếu chỉ copy workspace (ví dụ: qua Git), bạn sẽ không giữ:

  • sessions
  • credentials
  • channel logins

Những thứ đó nằm trong $OPENCLAW_STATE_DIR.

Các bước migration (khuyên dùng)

Bước 0 — Tạo backup (máy cũ)

Trên máy cũ, dừng gateway trước để các file không thay đổi giữa chừng:

openclaw gateway stop

(Tùy chọn nhưng khuyên dùng) nén state dir và workspace:

# Điều chỉnh đường dẫn nếu bạn dùng profile hoặc vị trí tùy chỉnh
cd ~
tar -czf openclaw-state.tgz .openclaw

tar -czf openclaw-workspace.tgz .openclaw/workspace

Nếu có nhiều profiles/state dirs (ví dụ: ~/.openclaw-main, ~/.openclaw-work), nén từng cái.

Bước 1 — Cài OpenClaw trên máy mới

Trên máy mới, cài CLI (và Node nếu cần):

Ở bước này, không sao nếu onboarding tạo một ~/.openclaw/ mới — bạn sẽ ghi đè nó ở bước tiếp theo.

Bước 2 — Copy state dir + workspace sang máy mới

Copy cả hai:

  • $OPENCLAW_STATE_DIR (mặc định ~/.openclaw/)
  • workspace của bạn (mặc định ~/.openclaw/workspace/)

Các cách phổ biến:

  • scp các file nén và giải nén
  • rsync -a qua SSH
  • ổ đĩa ngoài

Sau khi copy, đảm bảo:

  • Các thư mục ẩn đã được bao gồm (ví dụ: .openclaw/)
  • Quyền sở hữu file đúng với user đang chạy gateway

Bước 3 — Chạy Doctor (migrations + service repair)

Trên máy mới:

openclaw doctor

Doctor là lệnh “an toàn và đáng tin cậy”. Nó sửa services, áp dụng config migrations và cảnh báo về các sự không khớp.

Sau đó:

openclaw gateway restart
openclaw status

Các lỗi phổ biến (và cách tránh)

Lỗi: profile / state-dir không khớp

Nếu bạn chạy gateway cũ với một profile (hoặc OPENCLAW_STATE_DIR), và gateway mới dùng một cái khác, bạn sẽ thấy các triệu chứng như:

  • thay đổi config không có hiệu lực
  • channels bị mất / đăng xuất
  • lịch sử session trống

Cách khắc phục: chạy gateway/service với cùng profile/state dir mà bạn đã migrate, sau đó chạy lại:

openclaw doctor

Lỗi: chỉ copy openclaw.json

openclaw.json là không đủ. Nhiều providers lưu state trong:

  • $OPENCLAW_STATE_DIR/credentials/
  • $OPENCLAW_STATE_DIR/agents/<agentId>/...

Luôn migrate toàn bộ thư mục $OPENCLAW_STATE_DIR.

Lỗi: permissions / ownership

Nếu bạn copy với quyền root hoặc đổi users, gateway có thể không đọc được credentials/sessions.

Cách khắc phục: đảm bảo state dir + workspace thuộc sở hữu của user đang chạy gateway.

Lỗi: migrate giữa remote/local modes

  • Nếu UI của bạn (WebUI/TUI) trỏ đến một gateway remote, remote host sở hữu session store + workspace.
  • Migrate laptop của bạn sẽ không chuyển state của remote gateway.

Nếu bạn đang ở remote mode, hãy migrate gateway host.

Lỗi: secrets trong backups

$OPENCLAW_STATE_DIR chứa secrets (API keys, OAuth tokens, WhatsApp creds). Xử lý backups như production secrets:

  • lưu trữ được mã hóa
  • tránh chia sẻ qua các kênh không an toàn
  • rotate keys nếu nghi ngờ bị lộ

Checklist xác minh

Trên máy mới, xác nhận:

  • openclaw status hiển thị gateway đang chạy
  • Các channels của bạn vẫn kết nối (ví dụ: WhatsApp không yêu cầu re-pair)
  • Dashboard mở và hiển thị các sessions hiện có
  • Các file workspace của bạn (memory, configs) có mặt

Liên quan