Cách sửa lỗi OpenClaw Gateway connect failed pairing required nhanh chóng

Lỗi “gateway connect failed: pairing required” là một thông báo bảo mật quen thuộc trong hệ sinh thái OpenClaw, xuất hiện khi một client cố gắng kết nối tới gateway nhưng chưa được ghép đôi (pairing) hoặc xác thực. Trong bài viết này, bằng kinh nghiệm làm việc trực tiếp trên hạ tầng AI tại Vietnix mình sẽ cùng bạn tìm hiểu các nguyên nhân phổ biến gây ra lỗi này, từ các vấn đề ở phía client đến cấu hình sai ở gateway, và hướng dẫn các phương pháp khắc phục chi tiết để thiết lập kết nối thành công.

Những điểm chính

• Quan điểm của chuyên gia: Lỗi pairing required thực chất không phải là một lỗi hệ thống phát sinh ngẫu nhiên, mà là một “hàng rào bảo mật” chủ động của OpenClaw nhằm ngăn chặn các kết nối nặc danh độc hại và nguy cơ chiếm quyền điều khiển AI gateway. Việc xử lý lỗi này cần được thực hiện một cách chính thống bằng cách thiết lập lại cơ chế bắt tay (handshake) và đồng bộ token, tuyệt đối không nên tìm cách tắt bỏ hoặc bypass tính năng này để tránh rò rỉ dữ liệu của Agent.
• Định nghĩa lỗi “Pairing Required”: Giúp hiểu đây là lỗi xác thực client với gateway, thường do chưa được ghép đôi hoặc token không hợp lệ.
• Chẩn đoán lỗi kết nối: Hướng dẫn dùng các lệnh status, doctor, logs để kiểm tra và xác định chính xác nguyên nhân gây ra sự cố.
• Sửa lỗi kết nối OpenClaw: Cung cấp 6 cách khắc phục các sự cố kết nối gateway phổ biến, từ lỗi quyền, token, đến cấu hình xác thực và SSH tunnel.
• Lỗi “No Pending Requests”: Giúp hiểu nguyên nhân (chưa có tin nhắn, hết hạn) và cung cấp lệnh để kiểm tra, tạo lại yêu cầu ghép nối.
• Sửa lỗi ghép nối CLI: Hướng dẫn dùng lệnh devices list và approve để cấp quyền cho thiết bị của bạn, cho phép kết nối lại thành công.
• Bảng lỗi tham khảo: Giúp tra cứu nhanh nguyên nhân và cách khắc phục tương ứng cho các thông báo lỗi kết nối OpenClaw phổ biến.
• VPS Vietnix cho OpenClaw: Giới thiệu giải pháp hosting hiệu năng cao, ổn định để triển khai và vận hành gateway OpenClaw một cách hiệu quả, an toàn.
• FAQ về lỗi OpenClaw: Cung cấp câu trả lời nhanh cho các câu hỏi thường gặp về lỗi kết nối, ghép nối và trạng thái gateway của OpenClaw.

Lỗi lỗi OpenClaw Gateway connect failed pairing required là gì?

OpenClaw gateway connect failed: pairing required là lỗi xảy ra khi cổng (gateway) từ chối kết nối từ một máy khách (client), chẳng hạn như giao diện web hoặc TUI, do client này chưa được xác thực.

Theo cơ chế bảo mật của OpenClaw, mọi client phải hoàn tất quá trình “ghép đôi” (pairing) hoặc cung cấp token xác thực hợp lệ để được cấp quyền truy cập. Các nguyên nhân phổ biến gây ra lỗi này bao gồm:

• Kết nối từ xa chưa được ghép đôi: Theo mặc định, OpenClaw chỉ tự động ghép đôi các kết nối từ localhost. Do đó, các kết nối từ máy tính khác, Docker, hoặc thông qua reverse proxy sẽ bị từ chối nếu chưa được ghép đôi thủ công.
• Token xác thực không hợp lệ: Token được sử dụng bởi client (Dashboard, CLI/TUI) không khớp với token do gateway yêu cầu hoặc đã hết hạn.
• Sai quyền truy cập tệp: Tệp cấu hình chứa danh sách các thiết bị đã ghép đôi (~/.openclaw/devices/paired.json) không có quyền đọc/ghi phù hợp, khiến hệ thống không thể xác minh thông tin client.

Các biến thể khác của lỗi này, như unauthorized (không được cấp quyền) hay connect timed out (hết thời gian chờ), đều chỉ ra vấn đề về xác thực hoặc kết nối giữa client (thiết bị của bạn) và gateway. Thông báo lỗi cụ thể sẽ giúp bạn xác định nguyên nhân chính xác hơn.

Cách xác định lỗi OpenClaw Gateway connect failed pairing required nhanh chóng

Để xác định lỗi này, trước tiên bạn hãy thực hiện tuần tự các lệnh kiểm tra chính thức sau:

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

Những gì cần kiểm tra trong kết quả:

• Kết quả của gateway status phải hiển thị Runtime: running (đang chạy) và RPC probe: ok (kiểm tra thành công).
• Lệnh doctor phải báo cáo không có vấn đề nghiêm trọng nào (no blocking issues).
• Nhật ký (logs) không được hiển thị lặp đi lặp lại các dòng lỗi pairing required hoặc unauthorized.

Hướng xử lý dựa trên kết quả:

• Nếu gateway status hiển thị Runtime: stopped (đã dừng), bạn chỉ cần khởi động lại nó bằng lệnh openclaw gateway start.
• Nếu gateway đang chạy (running) nhưng RPC probe lại báo failed (thất bại), điều này có nghĩa là gateway vẫn hoạt động nhưng client của bạn không thể xác thực. Một trong những phương pháp sửa lỗi tiếp theo sẽ giải quyết được vấn đề này.

Cách 1. Khắc phục lỗi thiếu quyền operator.admin trong tệp paired.json

Trên các máy chủ ảo (VPS) mới khởi tạo, lỗi này thường xảy ra do mục nhập thiết bị trong tệp ~/.openclaw/devices/paired.json của OpenClaw chỉ được cấp quyền operator.read trong quá trình cài đặt. Sự cố phân quyền này khiến hệ thống bị giới hạn đặc quyền, dẫn đến việc người dùng không thể thực thi các lệnh điều khiển hoặc tương tác mượt mà thông qua giao diện dòng lệnh (CLI/TUI).

Chạy lệnh sau để xem nội dung tệp cấu hình:

cat ~/.openclaw/devices/paired.json

Nếu mảng scopes trong kết quả hiển thị như thế này, bạn đã tìm đúng lỗi:

"scopes": [ "operator.read" ]

Cách khắc phục (chỉnh sửa thủ công):

1. Mở tệp bằng trình soạn thảo nano: nano ~/.openclaw/devices/paired.json
2. Tìm đến mục "scopes" trong phần thông tin thiết bị của bạn.
3. Thay đổi thành: "scopes": [ "operator.read", "operator.admin" ]
4. Lưu lại và thoát (nhấn Ctrl+O, Enter, rồi Ctrl+X).

Nếu bạn muốn dùng một lệnh duy nhất để hệ thống tự sửa:

python3 -c "import json, os; p = os.path.expanduser('~/.openclaw/devices/paired.json'); d = json.load(open(p)); [v['scopes'].append('operator.admin') for k,v in d.items() if 'scopes' in v and 'operator.admin' not in v['scopes']]; json.dump(d, open(p, 'w'), indent=2)"

Lệnh này sẽ tự động thêm quyền operator.admin vào mọi thiết bị đang bị thiếu trong tệp.

systemctl --user restart openclaw-gateway
openclaw tui

Nếu thành công, bạn sẽ thấy thông báo gateway connected | idle.

Cách 2. Khắc phục lỗi không khớp Token giữa tệp cấu hình và Gateway

Sự cố lệch token giữa tệp cấu hình openclaw.json và gateway thường phát sinh từ việc nâng cấp lỗi, chỉnh sửa file thủ công hoặc chạy lệnh doctor --generate-gateway-token mà quên tái khởi động gateway.

–

Chạy lệnh sau để lấy token từ tệp cấu hình:

openclaw config get gateway.auth.token

Hãy so sánh giá trị token này với token mà gateway đang thực sự sử dụng. Nếu chúng không khớp, đây chính là nguyên nhân gây ra sự cố.

openclaw auth regenerate
openclaw gateway restart

Nếu lệnh auth regenerate không tồn tại trên phiên bản của bạn, hãy sử dụng phương pháp thay thế sau:

openclaw doctor --generate-gateway-token
openclaw gateway restart

Cách 3. Dịch vụ clawdbot-gateway cũ vẫn đang chạy

Khi nâng cấp từ Clawdbot, việc dịch vụ cũ vẫn chiếm giữ cổng 18789 sẽ gây xung đột với gateway mới, dẫn đến vòng lặp khởi động lại liên tục. Tình trạng này thường được nhận diện qua thông báo lỗi another gateway instance is already listening trong nhật ký hệ thống (logs). Để xác minh và xử lý, bạn có thể kiểm tra theo các bước sau:

sudo ss -tlnp | grep 18789

Nếu xác định dịch vụ cũ vẫn đang chiếm dụng cổng, bạn cần giải phóng bằng cách chấm dứt tiến trình đó (sử dụng lệnh kill với PID tìm được) hoặc dừng hẳn dịch vụ Clawdbot cũ. Sau khi cổng 18789 đã trống, hãy tiến hành khởi động lại OpenClaw gateway để kích hoạt hệ thống bình thường.

systemctl --user stop clawdbot-gateway
systemctl --user disable clawdbot-gateway
openclaw gateway start
openclaw gateway status

Các lệnh trên sẽ dừng và vô hiệu hóa dịch vụ cũ, sau đó khởi động lại gateway của OpenClaw và kiểm tra trạng thái của nó.

Cách 4. Chế độ xác thực chưa được cấu hình trên bản cài đặt mới

Trên các bản cài đặt mới, việc chưa thiết lập chế độ xác thực sẽ khiến gateway không thể nhận diện người dùng, thường trả về lỗi gateway password missing hoặc disconnected (1008): unauthorized.

Bạn cần thực thi chuỗi lệnh sau theo đúng thứ tự để khởi tạo lại token, dọn dẹp các khóa lỗi thời, chuyển đổi chế độ xác thực và áp dụng thay đổi:

openclaw doctor --generate-gateway-token
openclaw doctor --fix
openclaw config set gateway.auth.mode token
openclaw gateway restart

• doctor --generate-gateway-token: Tạo thư mục chứa thông tin xác thực và tạo một token bảo mật.
• doctor --fix: Loại bỏ các khóa cấu hình không hợp lệ (ví dụ như gateway.auth.type còn sót lại từ các phiên bản cũ).
• config set gateway.auth.mode token: Yêu cầu gateway sử dụng phương thức xác thực bằng token.
• gateway restart: Áp dụng cấu hình mới.

Chạy lệnh sau để kiểm tra trạng thái:

openclaw gateway status

Kết quả phải hiển thị Auth Mode: token và Runtime: running.

Để truy cập dashboard trên trình duyệt, bạn cần thêm token vào cuối URL theo định dạng sau:

http://127.0.0.1:18789/?token=TOKEN_CỦA_BẠN

Cách 5. Gateway liên kết với mạng LAN nhưng thiếu xác thực

Khi cấu hình gateway hoạt động trên mạng LAN (gắn với một địa chỉ IP cụ thể thay vì localhost), cơ chế xác thực là điều kiện bắt buộc. Nếu thiếu cấu hình này, hệ thống sẽ chặn tiến trình kèm thông báo lỗi refusing to bind gateway ... without auth. Để kiểm tra cấu hình liên kết (bind) hiện tại của gateway, bạn hãy chạy lệnh:

openclaw config get gateway.bind

Trường hợp kết quả trả về hiển thị lan, tailnet hoặc một địa chỉ IP cụ thể, việc bật tính năng xác thực là bắt buộc. Để khắc phục, bạn hãy thực thi các lệnh sau trực tiếp trên máy chủ gateway:

openclaw config set gateway.auth.mode token
openclaw config set gateway.auth.token "$(openssl rand -hex 32)"
openclaw gateway restart

Sau đó, trên mọi máy khách (client) cần kết nối đến gateway, bạn phải khai báo token bằng lệnh:

export OPENCLAW_GATEWAY_TOKEN="your-token-here"

Cách 6. Khắc phục lỗi SSH Tunnel bị hỏng khi truy cập từ xa

Tuy có dấu hiệu rất giống lỗi ghép nối (pairing), sự cố này thực chất bắt nguồn từ SSH Tunnel được cấu hình để truy cập gateway từ xa trên VPS. Nếu kết nối tunnel này bị lỗi, hệ thống sẽ hiển thị trạng thái timeouts, còn nếu bị đứt đột ngột khi đang kết nối, bạn sẽ gặp lỗi disconnected (1000): no reason.

Để thiết lập hoặc khởi tạo lại SSH Tunnel trên máy tính cá nhân (áp dụng cho cả Windows, Mac và Linux), bạn hãy chạy lệnh:

ssh -N -L 19999:127.0.0.1:18789 root@YOUR_SERVER_IP

Để kiểm tra kết nối, bạn hãy mở một cửa sổ terminal mới và chạy lệnh:

curl http://127.0.0.1:19999

Nếu thành công, hệ thống sẽ trả về một phản hồi dạng HTML từ gateway. Lúc này, bạn đã có thể truy cập vào giao diện dashboard bằng trình duyệt qua địa chỉ:

http://127.0.0.1:19999/?token=YOUR_TOKEN

Cách xử lý lỗi: “No Pending Telegram Pairing Requests”

Khi bạn chạy lệnh openclaw pairing pending hoặc openclaw pairing list telegram và nhận được thông báo:

No pending telegram pairing requests

Bạn mong đợi sẽ thấy một yêu cầu ghép nối từ bot hoặc nhóm của mình, nhưng lại không có gì.

Nguyên nhân của tình trạng này:

• Bot chưa nhận được tin nhắn: Yêu cầu ghép nối chỉ được tạo khi có người gửi tin nhắn cho bot hoặc thêm nó vào một nhóm. Nếu chưa có ai nhắn tin cho bot, sẽ không có yêu cầu nào đang chờ.
• Yêu cầu đã hết hạn: Mã ghép nối sẽ hết hạn sau một giờ. Nếu bạn đợi quá lâu, yêu cầu sẽ bị xóa. Hãy gửi một tin nhắn khác để tạo yêu cầu mới.
• Yêu cầu đã được chấp thuận hoặc từ chối: Hãy kiểm tra danh sách các ghép nối đã được duyệt bằng lệnh openclaw pairing list telegram.
• Kiểm tra sai kênh: Bạn đang kiểm tra trên Telegram nhưng bot lại đang hoạt động trên Discord (hoặc ngược lại). Hãy chỉ định rõ kênh khi chạy lệnh: openclaw pairing pending telegram so với openclaw pairing pending discord.
• Gateway không chạy khi tin nhắn được gửi: Bot phải được kết nối với Telegram (thông qua gateway) để có thể nhận tin nhắn và tạo yêu cầu ghép nối.

Với lỗi này bạn chạy thứ tự lệnh sau để khắc phục:

# Đảm bảo gateway đang chạy
openclaw gateway status
 
# Theo dõi nhật ký (logs) trong thời gian thực
openclaw logs --follow
 
# Gửi một tin nhắn cho bot trên Telegram
# Bạn sẽ thấy dòng "Pairing request from..." xuất hiện trong nhật ký
 
# Bây giờ, hãy kiểm tra lại các yêu cầu đang chờ
openclaw pairing pending

Nếu yêu cầu vẫn không xuất hiện, hãy kiểm tra lại xem token của bot đã chính xác chưa và đảm bảo trong nhật ký của gateway có hiển thị dòng Telegram channel started.

Xử lý lỗi “Pairing Required. Run openclaw devices list, Approve Your Request ID, Then Reconnect.”

Khi giao diện dòng lệnh (CLI) hoặc giao diện văn bản (TUI) của hệ thống không thể thiết lập kết nối, người dùng sẽ nhận được thông báo lỗi đầy đủ với nội dung: “Pairing Required. Run openclaw devices list, Approve Your Request ID, Then Reconnect.”, dịch sang tiếng Việt có nghĩa là: “Yêu cầu ghép nối. Hãy chạy lệnh openclaw devices list, phê duyệt ID yêu cầu của bạn, sau đó kết nối lại.”

pairing required. run openclaw devices list, approve your request id, then reconnect.

Lỗi này khác với việc ghép nối ở cấp độ kênh (như với Telegram/Discord). Đây là ghép nối ở cấp độ thiết bị: công cụ CLI của bạn cần phải xác thực với gateway trước khi có thể điều khiển bất kỳ chức năng nào.

Bạn có thể khắc phục từng bước như sau:

# Liệt kê các thiết bị và trạng thái của chúng
openclaw devices list
 
# Tìm mục nhập thiết bị của bạn và ID yêu cầu tương ứng
# Phê duyệt nó
openclaw devices approve <request-id>
 
# Kết nối lại
openclaw tui

Nếu bản thân lệnh openclaw devices list cũng báo lỗi ghép nối, bạn đang gặp phải vấn đề “con gà và quả trứng” (thiết bị cần được xác thực để chạy lệnh, nhưng lại cần chạy lệnh để thiết lập xác thực). Trong trường hợp đó, hãy chuyển thẳng đến Phương pháp 1 (thiếu quyền operator.admin trong paired.json) hoặc Phương pháp 4 (chưa cấu hình chế độ xác thực) đã được đề cập ở trên.

Nếu bạn đang thiết lập một VPS từ xa lần đầu tiên, quá trình ghép nối thiết bị ban đầu sẽ diễn ra trong lúc cài đặt. Nếu quá trình này bị gián đoạn hoặc bỏ qua, bạn sẽ cần chỉnh sửa thủ công tệp ~/.openclaw/devices/paired.json để thêm mục nhập thiết bị của mình với các quyền (scopes) chính xác. Hãy xem lại Phương pháp 1 để biết các bước thực hiện chi tiết.

Bảng tham khảo các thông báo lỗi và cách khắc phục

VPS Vietnix – Lựa chọn tối ưu để vận hành Gateway OpenClaw

Để Gateway OpenClaw của bạn hoạt động liên tục 24/7, xử lý các yêu cầu ghép nối (pairing) và tương tác từ xa một cách ổn định, việc lựa chọn một môi trường hosting chuyên nghiệp là yếu tố then chốt. Vietnix cung cấp dịch vụ cho thuê máy chủ ảo hiệu năng cao, là nền tảng lý tưởng để bạn triển khai và vận hành hệ thống OpenClaw một cách hiệu quả.

Với hạ tầng mạnh mẽ, kết nối Internet tốc độ cao và IP tĩnh, VPS Vietnix đảm bảo gateway của bạn luôn trực tuyến và có thể truy cập từ xa một cách an toàn thông qua các phương thức như SSH tunnel. Khả năng mở rộng tài nguyên linh hoạt cũng giúp hệ thống của bạn dễ dàng đáp ứng khi nhu cầu sử dụng tăng cao.

Bên cạnh đó, đội ngũ kỹ thuật luôn túc trực 24/7 để hỗ trợ, đảm bảo môi trường vận hành cho OpenClaw của bạn luôn thông suốt. Bắt đầu triển khai gateway OpenClaw trên một nền tảng đáng tin cậy ngay hôm nay với Vietnix

Thông tin liên hệ:

• Website: https://vietnix.vn/
• Hotline: 1800 1093
• Email: sales@vietnix.vn
• Địa chỉ: 265 Hồng Lạc, Phường Bảy Hiền, Thành Phố Hồ Chí Minh

Tóm lại, lỗi OpenClaw Gateway connect failed pairing required chủ yếu xuất phát từ việc thiết bị của bạn chưa được xác thực. Để khắc phục, hãy sử dụng lệnh openclaw devices list để lấy ID yêu cầu, sau đó dùng openclaw devices approve để cấp quyền. Một khi thiết bị được phê duyệt, bạn có thể kết nối lại thành công. Đây là bước xác thực cốt lõi để đảm bảo chỉ các thiết bị được tin tưởng mới có thể điều khiển gateway.