OpenClaw cho người mới #2: Pairing node thất bại, unauthorized hoặc token hết hạn

Cập nhật lần cuối: 19/03/2026 | Phiên bản: 1.0

TL;DR: Lỗi pairing và token trong OpenClaw gần như luôn rơi vào một trong ba nhóm: gateway token mismatch, device pairing chưa được duyệt, hoặc token hết hạn sau update/restart. Bài viết này giải thích cơ chế bảo mật ba lớp của OpenClaw và hướng dẫn sửa từng bước — từ pairing required đến device token mismatch cho đến node remote không kết nối được.

Bối cảnh: Mô hình bảo mật ba lớp của OpenClaw

OpenClaw được thiết kế với ba lớp xác thực để bảo vệ hệ thống có quyền truy cập file, lệnh shell và các channel nhắn tin:

• Lớp 1 — Gateway Token Auth: so sánh token client gửi với gateway.auth.token.
• Lớp 2 — Device Token Auth: kiểm tra device identity, nonce và chữ ký của thiết bị.
• Lớp 3 — Device Pairing Approval: thiết bị mới phải được admin approve trước khi dùng.

Hiểu ba lớp này giúp bạn xác định lỗi nhanh thay vì sửa mò.

Chẩn đoán nhanh: Đọc error message

• unauthorized: gateway token missing → lỗi Lớp 1
• unauthorized: gateway token mismatch → lỗi Lớp 1
• unauthorized: device token mismatch → lỗi Lớp 2
• device identity required → lỗi Lớp 2
• disconnected (1008): pairing required → lỗi Lớp 3

Bước đầu tiên luôn nên là chạy openclaw logs --follow rồi thử kết nối lại để xem lỗi thuộc lớp nào.

Lỗi Lớp 1: Gateway Token

Nếu gặp token missing hoặc token mismatch, hãy kiểm tra token hiện tại:

openclaw config get gateway.auth.token
openclaw dashboard --no-open

Nếu token giữa config và service file không khớp, cách sửa nhanh nhất là:

openclaw gateway install --force
openclaw gateway restart
openclaw gateway status

Với remote CLI hoặc node, gateway.remote.token trên máy remote phải giống hệt gateway.auth.token trên máy gateway.

Lỗi Lớp 2: Device Token

Lỗi thường gặp: device token mismatch sau restart hoặc update. Nguyên nhân là credential phía client bị stale.

openclaw devices rotate-token
openclaw doctor --fix
openclaw gateway restart

Nếu vẫn lặp lại, xóa identity cũ và pairing state rồi kết nối lại từ đầu.

Lỗi Lớp 3: Pairing

Nếu gặp pairing required, đây thường không phải bug mà là thiết bị chưa được duyệt:

openclaw devices list
openclaw devices approve <requestId>

Sau khi update phiên bản mới, có thể cần backup rồi reset paired.json, restart gateway, sau đó approve lại device mới.

DM Pairing trên Telegram/WhatsApp/Discord

Với người dùng nhắn DM lần đầu qua bot, admin cần approve pairing request theo channel:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Điều này tách biệt với openclaw devices, vốn dành cho CLI, dashboard và node kỹ thuật.

Node Pairing — Kết nối máy remote vào Gateway

Node là máy khác kết nối vào gateway để thực thi lệnh. Khi pair node:

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw devices list
openclaw devices approve <requestId>

Nếu node báo pairing required nhưng danh sách pending trống, hãy xóa device entry cũ ở gateway lẫn node, rồi kết nối lại từ đầu.

Docker và Reverse Proxy

Trong Docker, cần pin token ổn định qua biến môi trường OPENCLAW_GATEWAY_TOKEN. Sau reverse proxy, cần bảo đảm WebSocket headers được forward đúng; nếu không, gateway có thể hiểu nhầm là token missing hoặc pairing required.

Quản lý device dài hạn

• Chạy openclaw doctor sau mỗi lần update.
• Pin token ổn định thay vì để auto-generate trôi nổi.
• Backup thư mục ~/.openclaw/devices/.
• Không chạy OpenClaw bằng sudo.

Flowchart chẩn đoán

• token missing / mismatch → kiểm tra gateway.auth.token và service file
• device token mismatch → rotate token hoặc xóa identity cũ
• pairing required → approve device đang pending
• device identity required → tạo lại identity hoặc thêm đúng flag khi chạy node
• Node pairing required nhưng pending trống → xóa node cũ hai phía rồi pair lại

Câu hỏi thường gặp

Bài viết cũng giải thích khi nào cần re-approve device, sự khác biệt giữa openclaw devices và openclaw pairing, có nên tắt pairing hoàn toàn hay không, và ý nghĩa của trạng thái paired · disconnected.

Xem thêm

• Tài liệu chính thức — Gateway Troubleshooting
• Tài liệu chính thức — Pairing
• Tài liệu chính thức — Nodes
• GitHub Issue — Pairing required sau update
• GitHub Issue — Node pairing invisible

Nguồn tham khảo: OpenClaw Docs, GitHub openclaw/openclaw và kinh nghiệm triển khai thực tế.