Khắc phục sự cố

• model_not_found với máy chủ cục bộ kiểu MLX/vLLM → xác minh baseUrl bao gồm /v1, api là "openai-completions" cho các backend /v1/chat/completions, và models.providers.<provider>.models[].id là id cục bộ của provider ở dạng trần. Chọn nó với tiền tố provider một lần, ví dụ mlx/mlx-community/Qwen3-30B-A3B-6bit; giữ mục catalog là mlx-community/Qwen3-30B-A3B-6bit.
• messages[...].content: invalid type: sequence, expected a string → backend từ chối các phần nội dung Chat Completions có cấu trúc. Cách sửa: đặt models.providers.<provider>.models[].compat.requiresStringContent: true.
• incomplete turn detected ... stopReason=stop payloads=0 → backend đã hoàn tất yêu cầu Chat Completions nhưng không trả về văn bản assistant hiển thị cho người dùng trong lượt đó. OpenClaw thử lại một lần các lượt trống tương thích OpenAI an toàn khi phát lại; thất bại kéo dài thường có nghĩa là backend đang phát ra nội dung trống/không phải văn bản hoặc đang chặn văn bản câu trả lời cuối.
• yêu cầu trực tiếp nhỏ thành công, nhưng các lần chạy agent OpenClaw thất bại do backend/mô hình sập (ví dụ Gemma trên một số bản dựng inferrs) → lớp truyền tải OpenClaw có khả năng đã đúng; backend đang thất bại với dạng prompt runtime agent lớn hơn.
• lỗi giảm sau khi tắt công cụ nhưng không biến mất → schema công cụ là một phần áp lực, nhưng vấn đề còn lại vẫn là dung lượng mô hình/máy chủ upstream hoặc lỗi backend.

1. Đặt compat.requiresStringContent: true cho các backend Chat Completions chỉ nhận chuỗi.
2. Đặt compat.supportsTools: false cho các mô hình/backend không thể xử lý đáng tin cậy bề mặt schema công cụ của OpenClaw.
3. Giảm áp lực prompt khi có thể: bootstrap workspace nhỏ hơn, lịch sử phiên ngắn hơn, mô hình cục bộ nhẹ hơn, hoặc backend có hỗ trợ ngữ cảnh dài mạnh hơn.
4. Nếu các yêu cầu trực tiếp nhỏ vẫn thành công trong khi lượt agent OpenClaw vẫn sập bên trong backend, hãy xem đó là giới hạn của máy chủ/mô hình upstream và gửi bản tái hiện ở đó với dạng payload đã được chấp nhận.

• device identity required → ngữ cảnh không bảo mật hoặc thiếu xác thực thiết bị.
• origin not allowed → Origin của trình duyệt không nằm trong gateway.controlUi.allowedOrigins (hoặc bạn đang kết nối từ origin trình duyệt không phải loopback mà không có danh sách cho phép rõ ràng).
• device nonce required / device nonce mismatch → client không hoàn tất luồng xác thực thiết bị dựa trên thử thách (connect.challenge + device.nonce).
• device signature invalid / device signature expired → client đã ký sai payload (hoặc dấu thời gian cũ) cho lần bắt tay hiện tại.
• AUTH_TOKEN_MISMATCH với canRetryWithDeviceToken=true → client có thể thực hiện một lần thử lại đáng tin cậy bằng token thiết bị đã lưu trong cache.
• Lần thử lại bằng token cache đó dùng lại tập scope cache được lưu cùng token thiết bị đã ghép nối. Các caller dùng deviceToken rõ ràng / scopes rõ ràng giữ nguyên tập scope đã yêu cầu của họ.
• Bên ngoài đường dẫn thử lại đó, thứ tự ưu tiên xác thực kết nối là token/mật khẩu chia sẻ rõ ràng trước, rồi deviceToken rõ ràng, rồi token thiết bị đã lưu, rồi token bootstrap.
• Trên đường dẫn giao diện điều khiển Tailscale Serve bất đồng bộ, các lần thử thất bại cho cùng {scope, ip} được tuần tự hóa trước khi bộ giới hạn ghi nhận thất bại. Vì vậy, hai lần thử lại sai đồng thời từ cùng một client có thể hiển thị retry later ở lần thử thứ hai thay vì hai lỗi không khớp đơn thuần.
• too many failed authentication attempts (retry later) từ client loopback có origin trình duyệt → các lần thất bại lặp lại từ cùng Origin đã chuẩn hóa đó bị khóa tạm thời; origin localhost khác dùng một bucket riêng.
• unauthorized lặp lại sau lần thử lại đó → token chia sẻ/token thiết bị bị lệch; làm mới cấu hình token và phê duyệt lại/xoay token thiết bị nếu cần.
• gateway connect failed: → sai đích host/cổng/url.

• Gateway start blocked: set gateway.mode=local hoặc existing config is missing gateway.mode → chế độ Gateway cục bộ chưa được bật, hoặc tệp cấu hình đã bị ghi đè và mất gateway.mode. Cách sửa: đặt gateway.mode="local" trong cấu hình của bạn, hoặc chạy lại openclaw onboard --mode local / openclaw setup để đóng dấu lại cấu hình chế độ cục bộ mong đợi. Nếu bạn đang chạy OpenClaw qua Podman, đường dẫn cấu hình mặc định là ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → liên kết non-loopback không có đường dẫn xác thực Gateway hợp lệ (mã thông báo/mật khẩu, hoặc trusted-proxy khi được cấu hình).
• another gateway instance is already listening / EADDRINUSE → xung đột cổng.
• Other gateway-like services detected (best effort) → tồn tại các đơn vị launchd/systemd/schtasks cũ hoặc song song. Hầu hết thiết lập nên giữ một Gateway trên mỗi máy; nếu bạn cần nhiều hơn một, hãy tách biệt cổng + cấu hình/trạng thái/workspace. Xem /gateway#multiple-gateways-same-host.
• System-level OpenClaw gateway service detected từ doctor → tồn tại một đơn vị systemd cấp hệ thống trong khi thiếu dịch vụ cấp người dùng. Gỡ bỏ hoặc vô hiệu hóa bản trùng lặp trước khi cho phép doctor cài đặt dịch vụ người dùng, hoặc đặt OPENCLAW_SERVICE_REPAIR_POLICY=external nếu đơn vị hệ thống là supervisor dự định dùng.
• Gateway service port does not match current gateway config → supervisor đã cài đặt vẫn ghim --port cũ. Chạy openclaw doctor --fix hoặc openclaw gateway install --force, rồi khởi động lại dịch vụ Gateway.

• Cấu hình không vượt qua xác thực trong khi khởi động, hot reload, hoặc một lần ghi do OpenClaw sở hữu.
• Khởi động Gateway thất bại đóng thay vì ghi lại openclaw.json.
• Hot reload bỏ qua các chỉnh sửa bên ngoài không hợp lệ và giữ cấu hình runtime hiện tại hoạt động.
• Các lần ghi do OpenClaw sở hữu từ chối payload không hợp lệ/phá hủy trước khi commit và lưu .rejected.*.
• openclaw doctor --fix sở hữu việc sửa chữa. Nó có thể xóa tiền tố không phải JSON hoặc khôi phục bản sao last-known-good trong khi vẫn giữ payload bị từ chối dưới dạng .clobbered.*.

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

• .clobbered.* tồn tại → doctor đã giữ lại một chỉnh sửa bên ngoài bị hỏng trong khi sửa cấu hình đang hoạt động.
• .rejected.* tồn tại → một lần ghi cấu hình do OpenClaw sở hữu đã thất bại kiểm tra schema hoặc clobber trước khi commit.
• Config write rejected: → lần ghi đã cố loại bỏ cấu trúc bắt buộc, làm tệp nhỏ đi rõ rệt, hoặc lưu cấu hình không hợp lệ.
• config reload skipped (invalid config): → một chỉnh sửa trực tiếp thất bại xác thực và đã bị Gateway đang chạy bỏ qua.
• Invalid config at ... → khởi động thất bại trước khi các dịch vụ Gateway được boot.
• missing-meta-vs-last-good, gateway-mode-missing-vs-last-good, hoặc size-drop-vs-last-good:* → một lần ghi do OpenClaw sở hữu đã bị từ chối vì mất trường hoặc kích thước so với bản sao lưu last-known-good.
• Config last-known-good promotion skipped → ứng viên chứa các placeholder bí mật đã che như ***.

1. Chạy openclaw doctor --fix để doctor sửa cấu hình có tiền tố/bị clobber hoặc khôi phục last-known-good.
2. Chỉ sao chép các khóa mong muốn từ .clobbered.* hoặc .rejected.*, rồi áp dụng chúng bằng openclaw config set hoặc config.patch.
3. Chạy openclaw config validate trước khi khởi động lại.
4. Nếu bạn chỉnh sửa thủ công, hãy giữ cấu hình JSON5 đầy đủ, không chỉ đối tượng một phần mà bạn muốn thay đổi.

• cron: scheduler disabled; jobs will not run automatically → cron bị tắt.
• cron: timer tick failed → tick của bộ lập lịch thất bại; kiểm tra lỗi tệp/nhật ký/runtime.
• heartbeat skipped với reason=quiet-hours → nằm ngoài khung giờ hoạt động.
• heartbeat skipped với reason=empty-heartbeat-file → HEARTBEAT.md tồn tại nhưng chỉ chứa dòng trống / tiêu đề markdown, nên OpenClaw bỏ qua lệnh gọi mô hình.
• heartbeat skipped với reason=no-tasks-due → HEARTBEAT.md chứa một khối tasks:, nhưng không có tác vụ nào đến hạn ở tick này.
• heartbeat: unknown accountId → id tài khoản không hợp lệ cho mục tiêu phân phối heartbeat.
• heartbeat skipped với reason=dm-blocked → mục tiêu heartbeat được phân giải thành đích kiểu DM trong khi agents.defaults.heartbeat.directPolicy (hoặc ghi đè theo từng agent) được đặt thành block.

• unknown command "browser" hoặc unknown command 'browser' → Plugin trình duyệt đi kèm bị loại trừ bởi plugins.allow.
• công cụ trình duyệt bị thiếu / không khả dụng trong khi browser.enabled=true → plugins.allow loại trừ browser, nên Plugin không bao giờ được tải.
• Failed to start Chrome CDP on port → tiến trình trình duyệt không khởi chạy được.
• browser.executablePath not found → đường dẫn đã cấu hình không hợp lệ.
• browser.cdpUrl must be http(s) or ws(s) → URL CDP đã cấu hình dùng scheme không được hỗ trợ như file: hoặc ftp:.
• browser.cdpUrl has invalid port → URL CDP đã cấu hình có cổng sai hoặc ngoài phạm vi.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → bản cài đặt gateway hiện tại thiếu phụ thuộc runtime trình duyệt lõi; cài đặt lại hoặc cập nhật OpenClaw, rồi khởi động lại gateway. Ảnh chụp nhanh ARIA và ảnh chụp màn hình trang cơ bản vẫn có thể hoạt động, nhưng điều hướng, ảnh chụp nhanh AI, ảnh chụp màn hình phần tử bằng bộ chọn CSS và xuất PDF vẫn không khả dụng.

• Could not find DevToolsActivePort for chrome → phiên hiện có Chrome MCP chưa thể gắn vào thư mục dữ liệu trình duyệt đã chọn. Mở trang kiểm tra trình duyệt, bật gỡ lỗi từ xa, giữ trình duyệt mở, phê duyệt lời nhắc gắn đầu tiên, rồi thử lại. Nếu không cần trạng thái đã đăng nhập, hãy ưu tiên hồ sơ openclaw được quản lý.
• No Chrome tabs found for profile="user" → hồ sơ gắn Chrome MCP không có tab Chrome cục bộ nào đang mở.
• Remote CDP for profile "<name>" is not reachable → điểm cuối CDP từ xa đã cấu hình không thể truy cập từ máy chủ gateway.
• Browser attachOnly is enabled ... not reachable hoặc Browser attachOnly is enabled and CDP websocket ... is not reachable → hồ sơ chỉ gắn không có mục tiêu có thể truy cập, hoặc điểm cuối HTTP đã phản hồi nhưng CDP WebSocket vẫn không mở được.

• fullPage is not supported for element screenshots → yêu cầu ảnh chụp màn hình đã trộn --full-page với --ref hoặc --element.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → các lệnh gọi ảnh chụp màn hình Chrome MCP / existing-session phải dùng chụp trang hoặc --ref từ ảnh chụp nhanh, không dùng CSS --element.
• existing-session file uploads do not support element selectors; use ref/inputRef. → hook tải tệp lên Chrome MCP cần ref ảnh chụp nhanh, không phải bộ chọn CSS.
• existing-session file uploads currently support one file at a time. → gửi một lượt tải lên cho mỗi lệnh gọi trên hồ sơ Chrome MCP.
• existing-session dialog handling does not support timeoutMs. → hook hộp thoại trên hồ sơ Chrome MCP không hỗ trợ ghi đè timeout.
• existing-session type does not support timeoutMs overrides. → bỏ qua timeoutMs cho act:type trên hồ sơ profile="user" / Chrome MCP existing-session, hoặc dùng hồ sơ trình duyệt được quản lý/CDP khi cần timeout tùy chỉnh.
• existing-session evaluate does not support timeoutMs overrides. → bỏ qua timeoutMs cho act:evaluate trên hồ sơ profile="user" / Chrome MCP existing-session, hoặc dùng hồ sơ trình duyệt được quản lý/CDP khi cần timeout tùy chỉnh.
• response body is not supported for existing-session profiles yet. → responsebody vẫn yêu cầu trình duyệt được quản lý hoặc hồ sơ CDP thô.
• ghi đè viewport / dark-mode / locale / offline cũ trên hồ sơ chỉ gắn hoặc CDP từ xa → chạy openclaw browser stop --browser-profile <name> để đóng phiên điều khiển đang hoạt động và giải phóng trạng thái mô phỏng Playwright/CDP mà không cần khởi động lại toàn bộ gateway.

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

Cần kiểm tra:

• Nếu gateway.mode=remote, các lệnh gọi CLI có thể đang nhắm đến remote trong khi dịch vụ cục bộ của bạn vẫn ổn.
• Các lệnh gọi --url tường minh không rơi lại về thông tin xác thực đã lưu.

Chữ ký phổ biến:

• gateway connect failed: → mục tiêu URL sai.
• unauthorized → điểm cuối có thể truy cập nhưng xác thực sai.

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

Cần kiểm tra:

• Các bind không phải loopback (lan, tailnet, custom) cần đường dẫn xác thực gateway hợp lệ: xác thực bằng token/mật khẩu dùng chung, hoặc triển khai trusted-proxy không phải loopback được cấu hình đúng.
• Các khóa cũ như gateway.token không thay thế gateway.auth.token.

Chữ ký phổ biến:

• refusing to bind gateway ... without auth → bind không phải loopback không có đường dẫn xác thực gateway hợp lệ.
• Connectivity probe: failed trong khi runtime đang chạy → gateway còn sống nhưng không thể truy cập với auth/url hiện tại.

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

Cần kiểm tra:

• Phê duyệt thiết bị đang chờ cho dashboard/Node.
• Phê duyệt ghép đôi DM đang chờ sau thay đổi chính sách hoặc danh tính.

Chữ ký phổ biến:

• device identity required → xác thực thiết bị chưa được đáp ứng.
• pairing required → người gửi/thiết bị phải được phê duyệt.