Khắc phục sự cố

​

Bậc thang lệnh

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

• openclaw gateway status hiển thị Runtime: running, Connectivity probe: ok, và một dòng Capability: ....
• openclaw doctor báo cáo không có sự cố cấu hình/dịch vụ gây chặn.
• openclaw channels status --probe hiển thị trạng thái truyền tải trực tiếp theo từng tài khoản và, ở nơi được hỗ trợ, kết quả thăm dò/kiểm tra như works hoặc audit ok.

​

Sau một bản cập nhật

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

• Update restart trong openclaw status / openclaw status --all. Các bàn giao đang chờ xử lý hoặc thất bại bao gồm lệnh tiếp theo cần chạy.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix dưới Channels. Điều đó nghĩa là cấu hình kênh vẫn tồn tại, nhưng đăng ký plugin thất bại trước khi kênh có thể tải.
• provider 401s sau khi xác thực lại. openclaw doctor --fix kiểm tra các bóng xác thực OAuth theo từng agent đã cũ và xóa các bản sao cũ để tất cả agent phân giải hồ sơ dùng chung hiện tại.

​

Cài đặt split brain và chốt chặn cấu hình mới hơn

which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion

openclaw gateway install --force
openclaw gateway restart

​

Không khớp giao thức sau khi rollback

openclaw --version
which -a openclaw
openclaw gateway status --deep
openclaw doctor --deep
openclaw logs --follow

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> trong nhật ký Gateway.
• Established clients: trong openclaw gateway status --deep hoặc Gateway clients trong openclaw doctor --deep. Phần này liệt kê các client TCP đang hoạt động được kết nối với cổng Gateway, bao gồm PID và dòng lệnh khi hệ điều hành cho phép.
• Một tiến trình client có dòng lệnh trỏ tới bản cài đặt OpenClaw hoặc wrapper mới hơn mà bạn đã rollback khỏi.

1. Dừng hoặc khởi động lại tiến trình client OpenClaw cũ hiển thị bởi gateway status --deep.
2. Khởi động lại ứng dụng hoặc wrapper nhúng OpenClaw, chẳng hạn như dashboard cục bộ, trình biên tập, helper máy chủ ứng dụng, hoặc các shell openclaw logs --follow chạy lâu.
3. Chạy lại openclaw gateway status --deep hoặc openclaw doctor --deep và xác nhận PID client cũ đã biến mất.

​

Symlink Skill bị bỏ qua vì thoát khỏi đường dẫn

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

ls -l ~/.agents/skills/<name>
realpath ~/.agents/skills/<name>
openclaw config get skills.load

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

• Cấu hình Skills
• Ví dụ cấu hình

​

Anthropic 429 yêu cầu mức sử dụng bổ sung cho ngữ cảnh dài

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

• Mô hình Anthropic được chọn là một mô hình Claude 4.x 1M có khả năng GA, hoặc mô hình có params.context1m: true kế thừa.
• Thông tin xác thực Anthropic hiện tại không đủ điều kiện cho sử dụng ngữ cảnh dài.
• Yêu cầu chỉ thất bại trên các phiên/lần chạy mô hình dài cần đường dẫn ngữ cảnh 1M.

• Anthropic
• Mức dùng token và chi phí
• Vì sao tôi thấy HTTP 429 từ Anthropic?

​

Phản hồi 403 bị chặn từ upstream

openclaw status
openclaw gateway status
openclaw logs --follow

• nhiều mô hình dưới cùng một provider thất bại theo cùng một cách
• HTML hoặc văn bản bảo mật chung thay vì lỗi API provider bình thường
• sự kiện bảo mật phía provider cho cùng thời điểm yêu cầu
• một thăm dò curl trực tiếp rất nhỏ thành công trong khi các yêu cầu dạng SDK bình thường thất bại

• Endpoint tương thích OpenAI
• Cấu hình provider
• Nhật ký

​

Backend cục bộ tương thích OpenAI vượt qua thăm dò trực tiếp nhưng lần chạy agent thất bại

• curl ... /v1/models hoạt động
• lệnh gọi trực tiếp nhỏ /v1/chat/completions hoạt động
• Lần chạy mô hình OpenClaw chỉ thất bại trên lượt agent bình thường

curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow

• các lệnh gọi nhỏ trực tiếp thành công, nhưng lần chạy OpenClaw chỉ thất bại trên prompt lớn hơn
• lỗi model_not_found hoặc 404 dù /v1/chat/completions trực tiếp hoạt động với cùng id mô hình trần
• lỗi backend về việc messages[].content mong đợi một chuỗi
• cảnh báo incomplete turn detected ... stopReason=stop payloads=0 ngắt quãng với backend cục bộ tương thích OpenAI
• backend crash chỉ xuất hiện với số lượng token prompt lớn hơn hoặc prompt runtime agent đầy đủ

• Cấu hình
• Mô hình cục bộ
• Điểm cuối tương thích OpenAI

​

Không có phản hồi

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

• Ghép cặp đang chờ xử lý đối với người gửi DM.
• Chặn theo lượt nhắc trong nhóm (requireMention, mentionPatterns).
• Không khớp danh sách cho phép của kênh/nhóm.

• drop guild message (mention required → tin nhắn nhóm bị bỏ qua cho đến khi có lượt nhắc.
• pairing request → người gửi cần được phê duyệt.
• blocked / allowlist → người gửi/kênh đã bị chính sách lọc.

• Khắc phục sự cố kênh
• Nhóm
• Ghép cặp

​

Kết nối giao diện điều khiển bảng điều khiển

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

• URL thăm dò và URL bảng điều khiển đúng.
• Không khớp chế độ xác thực/token giữa máy khách và gateway.
• Dùng HTTP ở nơi yêu cầu danh tính thiết bị.

openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789

​

Bản đồ nhanh mã chi tiết xác thực

openclaw --version
openclaw doctor
openclaw gateway status

• các phiên token thiết bị đã ghép cặp chỉ có thể quản lý thiết bị của chính chúng trừ khi caller cũng có operator.admin
• openclaw devices rotate --scope ... chỉ có thể yêu cầu các phạm vi operator mà phiên caller đã có

• Cấu hình (chế độ xác thực gateway)
• Giao diện điều khiển
• Thiết bị
• Truy cập từ xa
• Xác thực proxy tin cậy

​

Dịch vụ Gateway không chạy

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # also scan system-level services

• Runtime: stopped với gợi ý mã thoát.
• Không khớp cấu hình dịch vụ (Config (cli) so với Config (service)).
• Xung đột cổng/listener.
• Cài đặt launchd/systemd/schtasks bổ sung khi dùng --deep.
• Gợi ý dọn dẹp Other gateway-like services detected (best effort).

• Exec nền và công cụ tiến trình
• Cấu hình
• Doctor

​

Gateway macOS âm thầm ngừng phản hồi, rồi tiếp tục khi bạn chạm vào bảng điều khiển

ls ~/.openclaw/logs/stability/ | tail -5
openclaw gateway stability --bundle latest
pmset -g log | grep -iE "sleep|wake|maintenance" | tail -50
launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

• Một hoặc nhiều gói *-uncaught_exception.json trong ~/.openclaw/logs/stability/ có error.code được đặt thành mã mạng tạm thời như ENETDOWN, ENETUNREACH, EHOSTUNREACH, hoặc ECONNREFUSED.
• Các dòng pmset -g log như Entering Sleep state due to 'Maintenance Sleep' hoặc en0 driver is slow (msg: WillChangeState to 0) khớp với dấu thời gian sự cố. Power Nap / Maintenance Sleep tạm thời đưa trình điều khiển Wi-Fi về trạng thái 0; bất kỳ connect() đi ra nào rơi vào khoảng thời gian đó đều có thể lỗi với ENETDOWN, ngay cả trên máy chủ vốn có kết nối mạng đầy đủ.
• Đầu ra launchctl print hiển thị state = not running với nhiều runs gần đây và mã thoát, đặc biệt khi khoảng cách giữa sự cố và lần khởi chạy tiếp theo tính bằng khoảng một giờ thay vì vài giây. macOS launchd áp dụng một cổng bảo vệ hồi sinh không được tài liệu hóa sau một loạt sự cố, có thể ngừng tôn trọng KeepAlive=true cho đến khi một tác nhân bên ngoài như đăng nhập tương tác, kết nối bảng điều khiển, hoặc launchctl kickstart kích hoạt lại nó.

• Một gói ổn định có error.code là ENETDOWN hoặc mã cùng nhóm, với call stack trỏ vào Node net lookupAndConnect / Socket.connect. OpenClaw 2026.5.26 và mới hơn phân loại các lỗi này là lỗi mạng tạm thời vô hại, nên chúng không còn lan tới trình xử lý uncaught cấp cao nhất; nếu bạn đang dùng bản phát hành cũ hơn, hãy nâng cấp trước.
• Những khoảng lặng dài kết thúc ngay khi bạn kết nối tới Control UI hoặc SSH vào máy chủ: hoạt động người dùng nhìn thấy là thứ kích hoạt lại cổng hồi sinh của launchd, không phải bất kỳ việc gì bảng điều khiển làm với gateway.
• Số runs tăng trong ngày mà không có dòng received SIG*; shutting down tương ứng trong ~/Library/Logs/openclaw/gateway.log: tắt sạch sẽ ghi log một tín hiệu; sự cố tạm thời thì không.

1. Nâng cấp gateway nếu bạn đang chạy bản phát hành trước 2026.5.26. Sau khi nâng cấp, các lỗi ENETDOWN trong tương lai sẽ được ghi log dưới dạng cảnh báo thay vì chấm dứt tiến trình.
2. Giảm hoạt động maintenance sleep trên máy chủ Mac mini / desktop được dùng như máy chủ luôn bật:
   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0
   
   Điều này giảm đáng kể, nhưng không loại bỏ hoàn toàn, tình trạng driver dao động bên dưới. Hệ thống vẫn có thể thực hiện một số maintenance sleep để duy trì TCP keepalive và mDNS bất kể các cờ này.
3. Thêm watchdog kiểm tra liveness để một loạt sự cố trong tương lai nếu bị launchd giữ lại sẽ được phát hiện nhanh:
   # Example launchd-aware liveness check, suitable for a 5-minute cron or LaunchAgent
   state=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')
   if [ "$state" != "running" ]; then
     launchctl kickstart -k gui/$UID/ai.openclaw.gateway
   fi
   
   Mục tiêu là kích hoạt lại cổng hồi sinh từ bên ngoài; chỉ KeepAlive=true là không đủ trên macOS sau một loạt sự cố.

• Ghi chú nền tảng macOS
• Ghi log
• Doctor

​

Gateway thoát khi sử dụng nhiều bộ nhớ

openclaw gateway status --deep
openclaw logs --follow
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export

• Reason: diagnostic.memory.pressure.critical trong gói ổn định mới nhất.
• Memory pressure: với critical/rss_threshold, critical/heap_threshold, hoặc critical/rss_growth.
• Các giá trị V8 heap: gần giới hạn heap.
• Các mục Largest session files: như agents/<agent>/sessions/<session>.jsonl hoặc sessions/<session>.jsonl.
• Bộ đếm bộ nhớ cgroup của Linux khi gateway chạy trong container hoặc dịch vụ bị giới hạn bộ nhớ.

• critical memory pressure bundle written xuất hiện ngay trước khi khởi động lại → OpenClaw đã thu thập một gói ổn định trước OOM. Kiểm tra bằng openclaw gateway stability --bundle latest.
• memory pressure: level=critical ... memoryPressureSnapshot=disabled xuất hiện trong log gateway → OpenClaw đã phát hiện áp lực bộ nhớ nghiêm trọng, nhưng ảnh chụp ổn định trước OOM đang tắt.
• Largest session files: trỏ tới một đường dẫn bản ghi đã biên tập rất lớn → giảm lịch sử phiên được giữ lại, kiểm tra mức tăng phiên, hoặc chuyển các bản ghi cũ ra khỏi kho hoạt động trước khi khởi động lại.
• Số byte đã dùng trong V8 heap: gần giới hạn heap → giảm áp lực prompt/phiên, giảm công việc đồng thời, hoặc chỉ tăng giới hạn heap của Node sau khi xác nhận workload là dự kiến.
• Memory pressure: critical/rss_growth → bộ nhớ tăng nhanh trong một cửa sổ lấy mẫu. Kiểm tra log mới nhất để tìm import lớn, đầu ra công cụ mất kiểm soát, retry lặp lại, hoặc một lô công việc agent đang xếp hàng.
• Áp lực bộ nhớ nghiêm trọng xuất hiện trong log nhưng không có gói nào → đây là mặc định. Đặt diagnostics.memoryPressureSnapshot: true để thu thập gói ổn định trước OOM trong các sự kiện áp lực bộ nhớ nghiêm trọng sau này.

• Sức khỏe Gateway
• Xuất chẩn đoán
• Phiên

​

Gateway từ chối cấu hình không hợp lệ

openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• Một tệp openclaw.json.rejected.* có dấu thời gian bên cạnh cấu hình đang hoạt động
• Một tệp openclaw.json.clobbered.* có dấu thời gian nếu doctor --fix đã sửa một chỉnh sửa trực tiếp bị hỏng
• OpenClaw giữ 32 tệp .clobbered.* mới nhất cho mỗi đường dẫn cấu hình và xoay vòng các tệp cũ hơn

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

• Cấu hình
• Cấu hình: hot reload
• Cấu hình: xác thực nghiêm ngặt
• Doctor

​

Cảnh báo probe Gateway

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

• warnings[].code và primaryTargetId trong đầu ra JSON.
• Cảnh báo liên quan đến SSH fallback, nhiều gateway, thiếu scope, hay auth ref chưa phân giải.

• SSH tunnel failed to start; falling back to direct probes. → thiết lập SSH thất bại, nhưng lệnh vẫn thử các mục tiêu được cấu hình/local loopback trực tiếp.
• multiple reachable gateway identities detected → các gateway khác nhau đã trả lời, hoặc OpenClaw không thể chứng minh các mục tiêu truy cập được là cùng một gateway. Một SSH tunnel, URL proxy, hoặc URL từ xa được cấu hình tới cùng gateway được xem là một gateway với nhiều transport, ngay cả khi các cổng transport khác nhau.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → kết nối hoạt động, nhưng detail RPC bị giới hạn scope; ghép cặp danh tính thiết bị hoặc dùng thông tin xác thực có operator.read.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → kết nối hoạt động, nhưng toàn bộ tập RPC chẩn đoán đã timeout hoặc thất bại. Xem đây là một Gateway truy cập được với chẩn đoán suy giảm; so sánh connect.ok và connect.rpcOk trong đầu ra --json.
• Capability: pairing-pending hoặc gateway closed (1008): pairing required → gateway đã trả lời, nhưng client này vẫn cần ghép cặp/phê duyệt trước khi có quyền truy cập operator bình thường.
• văn bản cảnh báo SecretRef gateway.auth.* / gateway.remote.* chưa phân giải → vật liệu auth không có sẵn trong đường dẫn lệnh này cho mục tiêu thất bại.

• Gateway
• Nhiều gateway trên cùng một máy chủ
• Truy cập từ xa

​

Kênh đã kết nối, tin nhắn không lưu thông

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

• Chính sách DM (pairing, allowlist, open, disabled).
• Allowlist nhóm và yêu cầu nhắc tên.
• Thiếu quyền/scope API của kênh.

• mention required → tin nhắn bị chính sách nhắc tên trong nhóm bỏ qua.
• Dấu vết pairing / pending approval → người gửi chưa được phê duyệt.
• missing_scope, not_in_channel, Forbidden, 401/403 → vấn đề auth/quyền của kênh.

• Khắc phục sự cố kênh
• Discord
• Telegram
• WhatsApp

​

Phân phối Cron và Heartbeat

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

• Cron đã bật và có thời điểm đánh thức tiếp theo.
• Trạng thái lịch sử chạy tác vụ (ok, skipped, error).
• Lý do bỏ qua Heartbeat (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).

• Heartbeat
• Tác vụ đã lên lịch
• Tác vụ đã lên lịch: khắc phục sự cố

​

Node đã ghép nối, công cụ lỗi

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

• Node trực tuyến với các khả năng mong đợi.
• Các quyền OS đã cấp cho camera/mic/vị trí/màn hình.
• Trạng thái phê duyệt exec và allowlist.

• NODE_BACKGROUND_UNAVAILABLE → ứng dụng node phải ở foreground.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → thiếu quyền OS.
• SYSTEM_RUN_DENIED: approval required → đang chờ phê duyệt exec.
• SYSTEM_RUN_DENIED: allowlist miss → lệnh bị allowlist chặn.

• Phê duyệt exec
• Khắc phục sự cố Node
• Node

​

Công cụ trình duyệt lỗi

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

• plugins.allow có được đặt và có bao gồm browser hay không.
• Đường dẫn thực thi trình duyệt hợp lệ.
• Khả năng truy cập hồ sơ CDP.
• Tính sẵn có của Chrome cục bộ cho các hồ sơ existing-session / user.

• Trình duyệt (do OpenClaw quản lý)
• Khắc phục sự cố trình duyệt

​

Nếu bạn đã nâng cấp và có thứ đột ngột hỏng

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

openclaw gateway install --force
openclaw gateway restart

• Xác thực
• Exec nền và công cụ tiến trình
• Ghép nối do Gateway sở hữu

​

Liên quan

• Doctor
• FAQ
• Runbook Gateway