Khắc phục sự cố Node

Hãy dùng trang này khi một Node hiển thị trong trạng thái nhưng các công cụ của Node không hoạt động.

​

Trình tự lệnh

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

Sau đó, chạy các bước kiểm tra dành riêng cho Node:

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

Các dấu hiệu hoạt động bình thường:

• Node đã kết nối và ghép đôi cho vai trò node.
• nodes describe bao gồm khả năng mà bạn đang gọi.
• Phê duyệt thực thi hiển thị chế độ/danh sách cho phép như mong đợi.

​

Yêu cầu chạy ở nền trước

canvas.*, camera.* và screen.* chỉ hoạt động ở nền trước trên các Node iOS/Android.

Kiểm tra và khắc phục nhanh:

openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow

Nếu thấy NODE_BACKGROUND_UNAVAILABLE, hãy đưa ứng dụng Node lên nền trước rồi thử lại.

​

Ma trận quyền

Khả năng	iOS	Android	Ứng dụng Node trên macOS	Mã lỗi thường gặp
camera.snap, camera.clip	Camera (+ micrô cho âm thanh của đoạn video)	Camera (+ micrô cho âm thanh của đoạn video)	Camera (+ micrô cho âm thanh đoạn video)	*_PERMISSION_REQUIRED
screen.record	Ghi màn hình (+ micrô tùy chọn)	Lời nhắc chụp màn hình (+ micrô tùy chọn)	Ghi màn hình	*_PERMISSION_REQUIRED
computer.act	không áp dụng	không áp dụng	Trợ năng + Ghi màn hình	COMPUTER_DISABLED, ACCESSIBILITY_REQUIRED
location.get	Khi sử dụng hoặc Luôn luôn (tùy thuộc chế độ)	Vị trí nền trước/nền sau tùy theo chế độ	Quyền truy cập vị trí	LOCATION_PERMISSION_REQUIRED
system.run	không áp dụng (đường dẫn máy chủ Node)	không áp dụng (đường dẫn máy chủ Node)	Cần phê duyệt thực thi	SYSTEM_RUN_DENIED

​

Ghép đôi và phê duyệt

Ba cổng riêng biệt kiểm soát việc một lệnh Node có thành công hay không:

1. Ghép đôi thiết bị: Node này có thể kết nối với Gateway không?
2. Chính sách lệnh Node của Gateway: mã lệnh RPC có được gateway.nodes.allowCommands / denyCommands và các giá trị mặc định của nền tảng cho phép không?
3. Phê duyệt thực thi: Node này có thể chạy cục bộ một lệnh shell cụ thể không?

Ghép đôi Node là một cổng danh tính/tin cậy, không phải giao diện phê duyệt cho từng lệnh. Đối với system.run, chính sách của từng Node nằm trong tệp phê duyệt thực thi của Node đó (openclaw approvals get --node ...), không nằm trong bản ghi ghép đôi của Gateway.

Kiểm tra nhanh:

openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

• Thiếu ghép đôi: trước tiên hãy phê duyệt thiết bị Node.
• nodes describe thiếu một lệnh: hãy kiểm tra chính sách lệnh Node của Gateway và liệu Node có thực sự khai báo lệnh đó khi kết nối hay không.
• Ghép đôi bình thường nhưng system.run thất bại: hãy sửa phê duyệt thực thi/danh sách cho phép trên Node đó.

Đối với các lần chạy host=node dựa trên phê duyệt, Gateway cũng ràng buộc việc thực thi với systemRunPlan chuẩn đã được chuẩn bị. Nếu một bên gọi sau đó sửa đổi lệnh, thư mục làm việc hoặc siêu dữ liệu phiên trước khi lần chạy đã được phê duyệt được chuyển tiếp, Gateway sẽ từ chối lần chạy do phê duyệt không khớp thay vì tin cậy tải trọng đã chỉnh sửa.

​

Các mã lỗi Node phổ biến

Mã	Ý nghĩa
NODE_BACKGROUND_UNAVAILABLE	Ứng dụng đang chạy ở nền sau; hãy đưa ứng dụng lên nền trước.
CAMERA_DISABLED	Nút bật/tắt Camera bị tắt trong cài đặt Node.
*_PERMISSION_REQUIRED	Quyền của hệ điều hành bị thiếu/bị từ chối.
LOCATION_DISABLED	Chế độ vị trí đang tắt.
LOCATION_PERMISSION_REQUIRED	Chế độ vị trí được yêu cầu chưa được cấp quyền.
LOCATION_BACKGROUND_UNAVAILABLE	Ứng dụng đang chạy ở nền sau nhưng chỉ có quyền Khi sử dụng.
COMPUTER_DISABLED	Bật Allow Computer Control trong ứng dụng macOS, sau đó phê duyệt bản cập nhật ghép đôi.
ACCESSIBILITY_REQUIRED	Cấp quyền Trợ năng cho gói ứng dụng OpenClaw hiện tại trong phần Cài đặt hệ thống của macOS.
SYSTEM_RUN_DENIED: approval required	Yêu cầu thực thi cần được phê duyệt rõ ràng.
SYSTEM_RUN_DENIED: allowlist miss	Lệnh bị chặn bởi chế độ danh sách cho phép. Trên các máy chủ Node Windows, các dạng trình bao shell như cmd.exe /c ... được xem là không khớp danh sách cho phép trong chế độ danh sách cho phép, trừ khi được phê duyệt qua luồng yêu cầu.

​

Vòng lặp khôi phục nhanh

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

Nếu vẫn gặp sự cố:

• Phê duyệt lại việc ghép đôi thiết bị.
• Mở lại ứng dụng Node (ở nền trước).
• Cấp lại quyền của hệ điều hành.
• Tạo lại/điều chỉnh chính sách phê duyệt thực thi.

Đối với điều khiển máy tính, cũng hãy xác minh rằng một tác nhân có khả năng thị giác cung cấp công cụ computer, screen.snapshot thành công khi có quyền Ghi màn hình và /phone status hiển thị quyền Gateway tạm thời hoặc lâu dài mà bạn dự định sử dụng. Một mục trong gateway.nodes.denyCommands luôn ghi đè allowCommands.

​

Liên quan

• Tổng quan về Node
• Node Camera
• Lệnh vị trí
• Sử dụng máy tính
• Phê duyệt thực thi
• Ghép đôi Gateway
• Khắc phục sự cố Gateway
• Khắc phục sự cố kênh