OpenClaw lỗi dù chạy openclaw docker --fix: Hướng dẫn debug bằng Claude Code

Nếu bạn đang ở tình huống này thì mình hiểu cảm giác đó rất rõ: chạy openclaw docker --fix nhiều lần, copy cấu hình từ nơi khác, cuối cùng OpenClaw vẫn fail hoặc tệ hơn là không khởi động được.

Bài này là quy trình mình đã làm để gỡ lỗi theo hướng có kiểm chứng bằng log, không đoán mò.

Khi nào nên áp dụng quy trình này?

Dùng ngay khi bạn gặp 1 trong các dấu hiệu sau:

• openclaw docker --fix chạy xong nhưng service vẫn không lên.
• Container lên rồi down ngay.
• Agent chạy nhưng phản hồi thất thường, routing model lúc được lúc không.
• Chỉnh thêm config xong thì OpenClaw lỗi nặng hơn trước.

Nguyên tắc trước khi sửa

Trước khi bắt đầu, giữ 3 nguyên tắc này để tránh “càng sửa càng hỏng”:

1. Không sửa hàng loạt cùng lúc.
2. Mỗi thay đổi đều phải có lý do từ log.
3. Sửa xong phải verify ngay bằng test cơ bản.

Bước 1: Mở Claude Code đúng chỗ

Khởi chạy Claude Code ngay trong thư mục cài OpenClaw (nơi chứa file cấu hình và log runtime).

Mục tiêu: để Claude đọc đúng ngữ cảnh local của máy bạn, thay vì suy đoán từ mô tả chung chung.

Bước 2: Gom đủ dữ liệu lỗi trước khi fix

Đừng sửa ngay. Hãy yêu cầu Claude làm 3 việc trước:

• Liệt kê các file cấu hình đang được dùng thực tế.
• Đọc log khởi động gần nhất, nhóm lỗi theo mức độ lặp lại.
• Chỉ ra lỗi gốc khả dĩ cao nhất (root cause), không chỉ lỗi bề mặt.

Prompt mẫu:

“Hãy đọc toàn bộ log và file cấu hình OpenClaw trong thư mục hiện tại. Nhóm lỗi lặp lại, xác định root cause gây fail khởi động, và đề xuất thứ tự kiểm tra từ khả năng cao xuống thấp.”

Bước 3: So khớp với tài liệu chính thức

Sau khi có giả thuyết lỗi, yêu cầu Claude đối chiếu lại với hướng dẫn chính thức tương ứng phiên bản bạn đang chạy.

Mục tiêu của bước này:
- phát hiện key config sai tên,
- phát hiện field đã đổi theo version,
- phát hiện cấu hình hợp lệ cú pháp nhưng sai ngữ nghĩa runtime.

Prompt mẫu:

“Đối chiếu cấu hình hiện tại với hướng dẫn chính thức theo phiên bản đang dùng. Chỉ ra điểm lệch và mức độ ảnh hưởng của từng điểm.”

Bước 4: Sửa theo hướng tối thiểu (minimal change)

Đây là chỗ cực quan trọng. Đừng yêu cầu “tự tối ưu toàn bộ”.

Hãy yêu cầu Claude:
- ưu tiên chỉnh những phần gây fail khởi động trước,
- mỗi thay đổi phải kèm lý do,
- không đụng phần đang chạy ổn nếu chưa cần.

Prompt mẫu:

“Chỉ áp dụng thay đổi tối thiểu để khôi phục khả năng khởi động ổn định. Mỗi thay đổi ghi rõ: sửa gì, vì sao sửa, rủi ro nếu không sửa.”

Bước 5: Cấu hình fallback model để tránh tắc việc

Sau khi service ổn định, cấu hình thêm fallback model để khi model chính lỗi bạn vẫn làm việc liên tục trên chat channel.

Checklist fallback nên có:

• Có model chính + ít nhất 1-2 model dự phòng.
• Có thứ tự ưu tiên fallback rõ ràng.
• Có mô tả điều kiện fallback (timeout, quota, provider error...).
• Có test gọi thử từng model sau khi cấu hình.

Bước 6: Tối ưu mô tả agent.md / AGENTS.md

Rất nhiều case fail không nằm ở Docker, mà nằm ở cách mô tả vai trò agent quá mơ hồ.

Bạn nên yêu cầu Claude chuẩn hóa rule vận hành như sau:

• Main agent làm orchestrator, luôn trực để nhận yêu cầu user.
• Task dài/chậm thì tách sub-agent xử lý.
• Sub-agent phải báo checkpoint theo từng mốc.
• Main agent tổng hợp kết quả và phản hồi nhất quán.

Cách này giúp giảm tình trạng main session bị block và hạn chế mất ngữ cảnh khi xử lý task dài.

Bước 7: Verify sau sửa (bắt buộc)

Sau mỗi vòng sửa, chạy checklist kiểm thử tối thiểu:

• Service khởi động ổn định sau restart.
• Không còn lỗi khởi động lặp trong log mới.
• Model chính gọi được.
• Model fallback gọi được.
• Flow main agent → sub-agent chạy đúng vai trò.

Nếu fail, quay lại bước 2 và tiếp tục dựa trên log mới, không rollback cảm tính.

Lỗi mình từng gặp và bài học rút ra

Sai lầm lớn nhất của mình trước đây là mô tả quá chung để OpenClaw “tự cấu hình”. Kết quả có lần nó sửa quá tay và làm hỏng cấu hình tới mức không khởi động được.

Sau khi chuyển sang quy trình trên (log-first, minimal-change, verify liên tục), hệ thống ổn định hơn hẳn.

Prompt tổng hợp có thể copy dùng ngay

“Mục tiêu: sửa lỗi OpenClaw không khởi động được dù đã chạy openclaw docker --fix.

Hãy thực hiện theo thứ tự:
1) Đọc log và config hiện tại, xác định root cause.
2) Đối chiếu với tài liệu chính thức đúng phiên bản.
3) Đề xuất thay đổi tối thiểu để khôi phục khởi động.
4) Áp dụng sửa đổi có giải thích từng thay đổi.
5) Thiết lập fallback model (primary + backup).
6) Chuẩn hóa mô tả agent.md/AGENTS.md để main agent orchestrate và tách sub-agent cho task dài.
7) Chạy checklist verify sau sửa và báo cáo kết quả theo từng mục.”

Kết luận

Khi openclaw docker --fix không còn giúp được nữa, hướng hiệu quả nhất là chuyển sang debug có hệ thống:

• đọc log,
• sửa tối thiểu,
• kiểm thử theo checklist,
• rồi mới tối ưu thêm fallback model và mô tả agent.

Làm vậy bạn sẽ thoát vòng lặp sửa-sai và đưa OpenClaw về trạng thái chạy ổn định nhanh hơn rất nhiều.