Doctor

openclaw doctor là công cụ sửa chữa và di chuyển dữ liệu cho OpenClaw. Nó sửa các config/state cũ, kiểm tra sức khỏe hệ thống, và đưa ra các bước sửa chữa cụ thể.

Bắt đầu nhanh

openclaw doctor

Chế độ tự động (headless/automation)

openclaw doctor --yes

Chấp nhận các giá trị mặc định mà không hỏi (bao gồm cả các bước restart/service/sandbox khi cần).

openclaw doctor --repair

Áp dụng các sửa chữa được khuyến nghị mà không hỏi (sửa chữa + restart khi an toàn).

openclaw doctor --repair --force

Áp dụng cả các sửa chữa mạnh tay (ghi đè các config supervisor tùy chỉnh).

openclaw doctor --non-interactive

Chạy không hỏi và chỉ áp dụng các migration an toàn (chuẩn hóa config + di chuyển state trên đĩa). Bỏ qua các hành động restart/service/sandbox cần xác nhận từ người dùng. Các migration state cũ sẽ tự động chạy khi phát hiện.

openclaw doctor --deep

Quét các service hệ thống để tìm các cài đặt gateway thừa (launchd/systemd/schtasks).

Nếu các bạn muốn xem lại các thay đổi trước khi ghi, hãy mở file config trước:

cat ~/.openclaw/openclaw.json

Chức năng tổng quan

  • Cập nhật tùy chọn trước khi chạy cho các bản cài từ git (chỉ ở chế độ tương tác).
  • Kiểm tra độ mới của giao thức UI (rebuild Control UI khi schema giao thức mới hơn).
  • Kiểm tra sức khỏe + nhắc restart.
  • Tóm tắt trạng thái Skill (đủ điều kiện/thiếu/bị chặn).
  • Chuẩn hóa config cho các giá trị cũ.
  • Cảnh báo ghi đè provider OpenCode Zen (models.providers.opencode).
  • Di chuyển state cũ trên đĩa (sessions/agent dir/WhatsApp auth).
  • Kiểm tra tính toàn vẹn và quyền của state (sessions, transcripts, state dir).
  • Kiểm tra quyền file config (chmod 600) khi chạy local.
  • Sức khỏe xác thực model: kiểm tra OAuth hết hạn, có thể refresh token sắp hết hạn, và báo cáo trạng thái cooldown/disabled của auth-profile.
  • Phát hiện thư mục workspace thừa (~/openclaw).
  • Sửa chữa Sandbox image khi sandboxing được bật.
  • Di chuyển service cũ và phát hiện gateway thừa.
  • Kiểm tra runtime Gateway (service đã cài nhưng không chạy; cached launchd label).
  • Cảnh báo trạng thái Channel (probe từ gateway đang chạy).
  • Kiểm tra config supervisor (launchd/systemd/schtasks) với tùy chọn sửa chữa.
  • Kiểm tra best practice cho Gateway runtime (Node vs Bun, đường dẫn version-manager).
  • Chẩn đoán xung đột port Gateway (mặc định 18789).
  • Cảnh báo bảo mật cho các policy DM mở.
  • Cảnh báo xác thực Gateway khi không có gateway.auth.token (chế độ local; đề xuất tạo token).
  • Kiểm tra systemd linger trên Linux.
  • Kiểm tra cài đặt từ source (pnpm workspace không khớp, thiếu UI assets, thiếu tsx binary).
  • Ghi config đã cập nhật + metadata wizard.

Chi tiết hoạt động và lý do

0) Cập nhật tùy chọn (cài đặt từ git)

Nếu đây là bản git checkout và doctor đang chạy ở chế độ tương tác, nó sẽ đề xuất cập nhật (fetch/rebase/build) trước khi chạy doctor.

1) Chuẩn hóa config

Nếu config chứa các cấu trúc giá trị cũ (ví dụ messages.ackReaction không có override theo channel cụ thể), doctor sẽ chuẩn hóa chúng vào schema hiện tại.

2) Di chuyển các key config cũ

Khi config chứa các key đã deprecated, các lệnh khác sẽ từ chối chạy và yêu cầu các bạn chạy openclaw doctor.

Doctor sẽ:

  • Giải thích các key cũ nào được tìm thấy.
  • Hiển thị migration đã áp dụng.
  • Ghi lại ~/.openclaw/openclaw.json với schema đã cập nhật.

Gateway cũng tự động chạy các migration của doctor khi khởi động nếu phát hiện format config cũ, nên các config cũ sẽ được sửa mà không cần can thiệp thủ công.

Các migration hiện tại:

  • routing.allowFrom → channels.whatsapp.allowFrom
  • routing.groupChat.requireMention → channels.whatsapp/telegram/imessage.groups."*".requireMention
  • routing.groupChat.historyLimit → messages.groupChat.historyLimit
  • routing.groupChat.mentionPatterns → messages.groupChat.mentionPatterns
  • routing.queue → messages.queue
  • routing.bindings → top-level bindings
  • routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
  • routing.agentToAgent → tools.agentToAgent
  • routing.transcribeAudio → tools.media.audio.models
  • bindings[].match.accountID → bindings[].match.accountId
  • identity → agents.list[].identity
  • agent.* → agents.defaults + tools.* (tools/elevated/exec/sandbox/subagents)
  • agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks → agents.defaults.models + agents.defaults.model.primary/fallbacks + agents.defaults.imageModel.primary/fallbacks

2b) Ghi đè provider OpenCode Zen

Nếu các bạn đã thêm models.providers.opencode (hoặc opencode-zen) thủ công, nó sẽ ghi đè catalog OpenCode Zen tích hợp từ @mariozechner/pi-ai. Điều này có thể buộc mọi model vào một API duy nhất hoặc đặt chi phí về 0. Doctor sẽ cảnh báo để các bạn có thể xóa override và khôi phục routing API + chi phí theo từng model.

3) Di chuyển state cũ (cấu trúc đĩa)

Doctor có thể di chuyển các cấu trúc đĩa cũ vào cấu trúc hiện tại:

  • Sessions store + transcripts:
    • từ ~/.openclaw/sessions/ sang ~/.openclaw/agents/<agentId>/sessions/
  • Agent dir:
    • từ ~/.openclaw/agent/ sang ~/.openclaw/agents/<agentId>/agent/
  • WhatsApp auth state (Baileys):
    • từ ~/.openclaw/credentials/*.json cũ (trừ oauth.json)
    • sang ~/.openclaw/credentials/whatsapp/<accountId>/... (account id mặc định: default)

Các migration này là best-effort và idempotent; doctor sẽ phát ra cảnh báo khi nó để lại các thư mục cũ làm backup. Gateway/CLI cũng tự động di chuyển sessions + agent dir cũ khi khởi động để history/auth/models nằm trong đường dẫn theo agent mà không cần chạy doctor thủ công. WhatsApp auth chỉ được di chuyển qua openclaw doctor.

4) Kiểm tra tính toàn vẹn state (session persistence, routing và an toàn)

Thư mục state là trung tâm điều hành. Nếu nó mất, các bạn sẽ mất sessions, credentials, logs và config (trừ khi có backup ở nơi khác).

Doctor kiểm tra:

  • State dir bị thiếu: cảnh báo về mất state nghiêm trọng, nhắc tạo lại thư mục, và nhắc nhở rằng nó không thể khôi phục dữ liệu đã mất.
  • Quyền state dir: xác minh khả năng ghi; đề xuất sửa quyền (và đưa ra gợi ý chown khi phát hiện owner/group không khớp).
  • Session dirs bị thiếu: sessions/ và thư mục session store là bắt buộc để lưu lịch sử và tránh crash ENOENT.
  • Transcript không khớp: cảnh báo khi các entry session gần đây có file transcript bị thiếu.
  • Main session “1-line JSONL”: đánh dấu khi transcript chính chỉ có một dòng (lịch sử không tích lũy).
  • Nhiều state dir: cảnh báo khi có nhiều thư mục ~/.openclaw tồn tại ở các home directory khác nhau hoặc khi OPENCLAW_STATE_DIR trỏ đến nơi khác (lịch sử có thể bị tách giữa các bản cài).
  • Nhắc nhở chế độ remote: nếu gateway.mode=remote, doctor nhắc các bạn chạy nó trên remote host (state nằm ở đó).
  • Quyền file config: cảnh báo nếu ~/.openclaw/openclaw.json có thể đọc được bởi group/world và đề xuất thắt chặt về 600.

5) Sức khỏe xác thực model (OAuth hết hạn)

Doctor kiểm tra các OAuth profile trong auth store, cảnh báo khi token sắp hết hạn/đã hết hạn, và có thể refresh chúng khi an toàn. Nếu profile Anthropic Claude Code cũ, nó gợi ý chạy claude setup-token (hoặc paste setup-token). Các nhắc refresh chỉ xuất hiện khi chạy ở chế độ tương tác (TTY); --non-interactive bỏ qua các lần thử refresh.

Doctor cũng báo cáo các auth profile tạm thời không sử dụng được do:

  • cooldown ngắn (rate limits/timeouts/auth failures)
  • disable lâu hơn (billing/credit failures)

6) Xác thực model Hooks

Nếu hooks.gmail.model được đặt, doctor xác thực tham chiếu model với catalog và allowlist và cảnh báo khi nó không resolve được hoặc bị disallow.

7) Sửa chữa Sandbox image

Khi sandboxing được bật, doctor kiểm tra Docker images và đề xuất build hoặc chuyển sang tên cũ nếu image hiện tại bị thiếu.

8) Di chuyển Gateway service và gợi ý dọn dẹp

Doctor phát hiện các gateway service cũ (launchd/systemd/schtasks) và đề xuất xóa chúng và cài service OpenClaw sử dụng port gateway hiện tại. Nó cũng có thể quét các service giống gateway thừa và in gợi ý dọn dẹp. Các OpenClaw gateway service có tên theo profile được coi là first-class và không bị đánh dấu là “thừa”.

9) Cảnh báo bảo mật

Doctor phát ra cảnh báo khi một provider mở cho DM mà không có allowlist, hoặc khi một policy được cấu hình theo cách nguy hiểm.

10) systemd linger (Linux)

Nếu chạy như systemd user service, doctor đảm bảo lingering được bật để gateway vẫn hoạt động sau khi logout.

11) Trạng thái Skill

Doctor in tóm tắt nhanh về các skill đủ điều kiện/thiếu/bị chặn cho workspace hiện tại.

12) Kiểm tra xác thực Gateway (local token)

Doctor cảnh báo khi gateway.auth bị thiếu trên local gateway và đề xuất tạo token. Dùng openclaw doctor --generate-gateway-token để buộc tạo token trong automation.

13) Kiểm tra sức khỏe Gateway + restart

Doctor chạy kiểm tra sức khỏe và đề xuất restart gateway khi nó trông không khỏe.

14) Cảnh báo trạng thái Channel

Nếu gateway khỏe mạnh, doctor chạy probe trạng thái channel và báo cáo cảnh báo với các sửa chữa được đề xuất.

15) Kiểm tra config supervisor + sửa chữa

Doctor kiểm tra config supervisor đã cài (launchd/systemd/schtasks) để tìm các giá trị mặc định bị thiếu hoặc lỗi thời (ví dụ: systemd network-online dependencies và restart delay). Khi tìm thấy không khớp, nó khuyến nghị cập nhật và có thể ghi lại service file/task về các giá trị mặc định hiện tại.

Lưu ý:

  • openclaw doctor nhắc trước khi ghi lại config supervisor.
  • openclaw doctor --yes chấp nhận các nhắc sửa chữa mặc định.
  • openclaw doctor --repair áp dụng các sửa chữa được khuyến nghị mà không nhắc.
  • openclaw doctor --repair --force ghi đè các config supervisor tùy chỉnh.
  • Các bạn luôn có thể buộc ghi lại hoàn toàn qua openclaw gateway install --force.

16) Chẩn đoán Gateway runtime + port

Doctor kiểm tra service runtime (PID, trạng thái exit cuối) và cảnh báo khi service đã cài nhưng không thực sự chạy. Nó cũng kiểm tra xung đột port trên gateway port (mặc định 18789) và báo cáo các nguyên nhân có thể (gateway đã chạy, SSH tunnel).

17) Best practice cho Gateway runtime

Doctor cảnh báo khi gateway service chạy trên Bun hoặc đường dẫn Node được quản lý bởi version-manager (nvm, fnm, volta, asdf, v.v.). Các channel WhatsApp + Telegram yêu cầu Node, và các đường dẫn version-manager có thể bị hỏng sau khi nâng cấp vì service không load shell init của các bạn. Doctor đề xuất di chuyển sang cài đặt Node hệ thống khi có sẵn (Homebrew/apt/choco).

18) Ghi config + metadata wizard

Doctor lưu mọi thay đổi config và đóng dấu metadata wizard để ghi lại lần chạy doctor.

19) Gợi ý Workspace (backup + memory system)

Doctor gợi ý một memory system cho workspace khi thiếu và in gợi ý backup nếu workspace chưa được đặt dưới git.

Xem /concepts/agent-workspace để có hướng dẫn đầy đủ về cấu trúc workspace và backup git (khuyến nghị dùng GitHub hoặc GitLab private).