OpenClaw — Hướng Dẫn Xử Lý Lỗi Toàn Diện (2026)

Lệnh đầu tiên khi gặp bất kỳ lỗi nào:
openclaw status --all
openclaw doctor --fix
Hai lệnh này giải quyết được khoảng 70% vấn đề mà không cần can thiệp thủ công.

Mục lục

Lỗi cài đặt
Lỗi Gateway & Kết nối
Lỗi xác thực (401 Unauthorized)
Lỗi giới hạn tốc độ (429 Rate Limit)
Lỗi Pairing & Device (1008)
Lỗi kênh WhatsApp
Lỗi kênh Telegram & Discord
Lỗi Docker & Container
Lỗi bảo mật (CVE-2026-25253)
Lỗi cấu hình & Config
Lỗi hiệu năng & Memory
Lỗi nâng cấp từ ClawdBot / Moltbot
Lỗi Sandbox & Tool Execution
Lỗi Browser Control
Lỗi Model Failover
Lỗi API & TypeError khi kết nối Provider
Công cụ chẩn đoán tổng hợp

1. Lỗi cài đặt

1.1. `openclaw: command not found`

Nguyên nhân: npm global bin chưa được thêm vào PATH.

Cách sửa:

# Kiểm tra npm global path
npm prefix -g

# Thêm vào PATH (bash/zsh trên macOS/Linux)
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Xác nhận
which openclaw

Trên Windows: thêm %AppData%\npm vào biến môi trường PATH, sau đó khởi động lại PowerShell.

1.2. Node.js version không đúng

Nguyên nhân: OpenClaw yêu cầu Node.js >= 22 (không phải 18 hay 20).

Cách sửa:

# Kiểm tra version hiện tại
node --version

# Cài đặt đúng version qua nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

# Xác nhận
node --version  # Phải là v22.x.x trở lên

1.3. Lỗi build `sharp` (native dependency)

Biểu hiện: Lỗi compilation khi cài đặt, liên quan đến [email protected].

Cách sửa:

# macOS: cài Xcode Command Line Tools
xcode-select --install

# Set biến môi trường để bỏ qua system libvips
export SHARP_IGNORE_GLOBAL_LIBVIPS=1

# Cài lại OpenClaw
npm install -g openclaw@latest

1.4. Lỗi cài đặt chung (npm fails)

Cách sửa:

# Xóa cache npm
npm cache clean --force

# Gỡ cài đặt cũ
npm uninstall -g openclaw

# Cài mới
npm install -g openclaw@latest

# Nếu vẫn lỗi, dùng installer script
curl -fsSL https://openclaw.ai/install.sh | bash

1.5. Lỗi quyền truy cập (Permission denied)

Nguyên nhân: File ownership sai hoặc thiếu quyền trên thư mục .openclaw.

Cách sửa:

# Sửa quyền sở hữu
sudo chown -R $(whoami) ~/.openclaw

# Kiểm tra quyền
ls -la ~/.openclaw/

2. Lỗi Gateway & Kết nối

2.1. Gateway không khởi động được

Biểu hiện: Gateway start blocked: set gateway.mode=local

Cách sửa:

# Bật local gateway mode
openclaw config set gateway.mode "local"

# Hoặc chạy cấu hình lại
openclaw configure

# Kiểm tra trạng thái
openclaw gateway status

Nếu chạy OpenClaw qua Podman với user riêng, config nằm ở ~openclaw/.openclaw/openclaw.json.

2.2. Port conflict — `EADDRINUSE :::18789`

Nguyên nhân: Port 18789 (mặc định) đang bị tiến trình khác chiếm.

Cách sửa:

# Tìm tiến trình đang dùng port
lsof -ti:18789        # macOS/Linux
netstat -ano | findstr :18789  # Windows

# Kill tiến trình
kill -9 <PID>

# Hoặc đổi port
openclaw config set gateway.port 18790

# Restart gateway
openclaw gateway restart

2.3. `Gateway not reachable` hoặc timeout

Cách sửa:

# Kiểm tra trạng thái sâu
openclaw gateway status --deep

# Kiểm tra config
openclaw config get gateway.bind
openclaw config get gateway.auth.token
openclaw config get gateway.remote.url

# Nếu gateway.mode=remote, CLI có thể đang trỏ sang remote
# trong khi local service vẫn chạy bình thường
openclaw config get gateway.mode

# Restart
openclaw gateway restart

# Nếu vẫn lỗi, reinstall gateway service
openclaw gateway install --force

2.4. `gateway already running pid lock timeout`

Nguyên nhân: File PID cũ chưa được dọn dẹp.

Cách sửa:

# Dừng tất cả process openclaw
pkill -f openclaw

# Xóa file lock nếu có
rm -f ~/.openclaw/gateway.pid

# Khởi động lại
openclaw gateway restart

3. Lỗi xác thực (401 Unauthorized)

3.1. API key không hợp lệ hoặc hết hạn

Cách sửa:

# Kiểm tra trạng thái credential
openclaw models status

# Setup lại token cho Anthropic
openclaw models auth setup-token --provider anthropic

# Hoặc cho OpenAI
openclaw models auth setup-token --provider openai

Lưu ý quan trọng: Với Anthropic, bạn phải thêm credit card và nạp ít nhất $5 để dùng API, kể cả khi web chat miễn phí. Trial credits cũng có thể hết hạn đột ngột.

3.2. OAuth token hết hạn

Cách sửa:

# Đăng xuất rồi đăng nhập lại
# Trong chat interface, gõ:
/logout
/login

# Hoặc chuyển sang dùng setup-token (ổn định hơn)
openclaw models auth setup-token --provider anthropic

3.3. Credential sai agent trong multi-agent setup

Nguyên nhân: Mỗi agent có credentials riêng ở ~/.openclaw/agents/<agentId>/agent/auth-profiles.json. Credential của agent này không tự áp dụng cho agent khác.

Cách sửa:

# Kiểm tra agent nào đang active
openclaw agent list

# Kiểm tra credential file cụ thể
cat ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

3.4. Lỗi credential trên từng nền tảng

macOS: Keychain access permissions có thể chặn việc đọc credential. Kiểm tra Keychain Access app.
Linux: Sai quyền file trên thư mục .openclaw. Chạy chmod 700 ~/.openclaw.
Windows: Xung đột biến môi trường giữa system scope và user scope.

4. Lỗi giới hạn tốc độ (429 Rate Limit)

4.1. Hiểu về 429 error

Lỗi 429 không có nghĩa là credential sai — mà là bạn đã vượt quá quota. Rate limit áp dụng đồng thời trên nhiều chiều: requests/phút, input tokens/phút, và output tokens/phút.

4.2. Chẩn đoán nhanh

# Kiểm tra trạng thái provider
openclaw models status

# Kiểm tra sâu
openclaw status --deep

4.3. Sửa nhanh

# Cách 1: Đợi 60 giây (đơn giản nhất)

# Cách 2: Restart gateway để xóa internal cooldown state
openclaw gateway restart

# Cách 3: Chuyển sang provider khác tạm thời
openclaw config set model "openai/gpt-4o"

4.4. Cấu hình fallback model (khuyến nghị)

Thêm fallback models trong config để khi provider chính bị limit, OpenClaw tự chuyển sang provider phụ:

{
  "models": {
    "primary": "anthropic/claude-sonnet-4-6",
    "fallbacks": [
      "openai/gpt-4o",
      "google/gemini-2.5-flash"
    ]
  }
}

4.5. Bug đã biết: Không có exponential backoff (Issue #5159)

Vấn đề: Hệ thống retry liên tục trong vài giây thay vì đợi lâu hơn, gây ra vòng lặp 429 liên tục.

Workaround: Cấu hình fallback model sang provider khác. Khi Claude bị limit, hệ thống sẽ tự chuyển sang GPT-4 hoặc Gemini.

4.6. Bug đã biết: Cooldown toàn provider (Issue #5744)

Vấn đề: Khi 1 model bị rate limit (ví dụ gemini-3.5-flash), toàn bộ provider Google bị cooldown, kể cả model khác có quota riêng.

Workaround: Thêm fallback model từ provider khác (ví dụ Anthropic hoặc OpenRouter).

4.7. Bug: Failover misclassification (Issue #10368)

Vấn đề: Lỗi 429 bị báo nhầm thành context_length_exceeded. Nếu bạn thấy lỗi context overflow xuất hiện đột ngột (không phải tăng dần), hãy kiểm tra rate limit header trước.

5. Lỗi Pairing & Device (1008)

5.1. `disconnected (1008): pairing required`

Nguyên nhân: Gateway yêu cầu device phải được pair trước khi kết nối. Connections từ localhost sẽ tự động được approve, nhưng Docker containers, LAN clients, và remote nodes cần approve thủ công.

Cách sửa:

# Xem danh sách pending pairing requests
openclaw devices list

# Approve device
openclaw devices approve <request-id>

# Client sẽ tự động reconnect sau vài giây

Nếu chạy trong Docker:

# Xem pending requests trong container
docker compose exec openclaw openclaw devices list

# Approve
docker compose exec openclaw openclaw devices approve <request-id>

Từ v2026.2.21, pairing list và pairing approve tự detect channel duy nhất nếu chỉ có một, không cần chỉ định channel argument.

5.2. `unauthorized: gateway token missing`

Cách sửa:

# Tạo gateway token mới
openclaw doctor --generate-gateway-token

# Mở dashboard với token
openclaw dashboard --no-open

# Paste token vào Control UI dashboard settings rồi refresh

Từ v2026.2.19, nếu bạn chưa set gateway auth, OpenClaw sẽ tự động tạo và lưu gateway.auth.token khi khởi động.

5.3. Quản lý paired devices

# Xóa 1 device cụ thể
openclaw devices remove <device-id>

# Xóa tất cả paired entries (và tùy chọn reject pending)
openclaw devices clear --yes --pending

6. Lỗi kênh WhatsApp

6.1. QR code hết hạn / không scan được

Lưu ý: QR code hết hạn sau 60 giây.

# Đăng nhập lại
openclaw channels login --channel whatsapp

# Scan nhanh QR code trong vòng 60 giây
# Trên điện thoại: WhatsApp → Settings → Linked Devices → Link a Device

6.2. WhatsApp bị stuck ở "logging in" sau khi đổi số

Nguyên nhân: Credential cũ bị lỗi, session state bị corrupted.

Cách sửa:

# Xóa credential WhatsApp cũ
rm -rf ~/.openclaw/credentials/whatsapp/

# Đăng nhập lại
openclaw channels login --channel whatsapp

6.3. WhatsApp liên tục reconnect (reconnect loop)

Nguyên nhân phổ biến:

Chạy nhiều OpenClaw instance trên cùng 1 số WhatsApp.
Session bị chia sẻ giữa các Gateway.

Quy tắc: Mỗi số WhatsApp chỉ dùng cho 1 Gateway duy nhất.

# Kiểm tra kết nối
openclaw channels status --probe

# Nếu lỗi, unlink session cũ trên điện thoại
# WhatsApp → Settings → Linked Devices → xóa device cũ

# Reset lại
openclaw channels reset whatsapp
openclaw channels login --channel whatsapp

6.4. Bị WhatsApp rate limit / ban tạm

Nguyên nhân: Gửi quá nhiều tin nhắn (trên 20 tin/phút có thể bị throttle).

Khuyến nghị:

Giữ tốc độ gửi dưới 20 tin/phút.
Dùng số điện thoại riêng cho bot (không dùng số cá nhân).
Bắt đầu với mode allowlist, chuyển sang pairing sau khi đã test kỹ.

6.5. Bug WhatsApp Allowlist Bypass (Issue #22599)

Vấn đề (phát hiện 2026-02-21, severity HIGH): Tin nhắn từ số không nằm trong allowlist vẫn được nhận và xử lý mặc dù đã cấu hình dmPolicy: "allowlist".

Workaround: Kiểm tra file ~/.openclaw/credentials/whatsapp-allowFrom.json và xóa các entry không mong muốn. Theo dõi Issue #22599 để cập nhật bản vá.

7. Lỗi kênh Telegram & Discord

7.1. Telegram bot không nhận tin nhắn

Checklist:

# Kiểm tra trạng thái kênh
openclaw channels list
openclaw channels status --probe

# Kiểm tra bot token
openclaw config get channels.telegram.token

# Đảm bảo đã start chat với bot trên Telegram
# Gửi /start cho bot

7.2. Telegram `setMyCommands` fails

Nguyên nhân: Lỗi mạng hoặc bot token không đúng.

Cách sửa:

# Kiểm tra kết nối mạng
openclaw gateway probe

# Kiểm tra logs
openclaw logs --follow

7.3. Discord bot không nhận tin nhắn (close code 4014)

Nguyên nhân: Thiếu privileged gateway intent.

Cách sửa:

Vào Discord Developer Portal.
Chọn Application → Bot section.
Bật "Message Content Intent".
Restart OpenClaw: openclaw gateway restart.

7.4. Xung đột tài nguyên khi chạy nhiều kênh cùng lúc

Nguyên nhân: WhatsApp (WebSocket persistent), Telegram (long polling), Discord (WebSocket + Intent) cạnh tranh event loop, RAM và file descriptors.

Khuyến nghị:

Đảm bảo VPS có ít nhất 2GB RAM khi chạy 3 kênh.
Monitor bằng openclaw health --watch.
Nếu gặp vấn đề, giảm số kênh hoặc tăng RAM.

8. Lỗi Docker & Container

8.1. Container bị OOM-killed

Nguyên nhân: RAM quá thấp. Container cần ít nhất 512MB RAM.

# Kiểm tra usage
docker stats openclaw

# Tăng memory limit trong docker-compose.yml
services:
  openclaw:
    image: openclaw/openclaw:latest
    deploy:
      resources:
        limits:
          memory: 2G

8.2. Container khởi động lại mất config

Nguyên nhân: Không mount volume config.

Cách sửa (docker-compose.yml):

services:
  openclaw:
    image: openclaw/openclaw:latest
    restart: unless-stopped
    volumes:
      - ./data:/root/.openclaw    # QUAN TRỌNG: mount toàn bộ thư mục
    ports:
      - "3456:3456"
    environment:
      - NODE_ENV=production

Lưu ý: Mount toàn bộ ~/.openclaw/ thay vì từng thư mục con. Nếu mount từng phần, thư mục sessions có thể không tồn tại đúng chỗ.

8.3. `Session file path must be within sessions directory`

Nguyên nhân (từ v2026.2.12):

Docker volume mount thiếu thư mục sessions.
Symlink ~/.openclaw/ không giữ đúng cấu trúc thư mục.
Validation path chặt hơn sau khi upgrade.

Cách sửa:

# Đảm bảo thư mục sessions tồn tại
mkdir -p ~/.openclaw/sessions/

# Mount full directory, không symlink
# Trong docker-compose.yml: dùng ./data:/root/.openclaw

# Kiểm tra quyền user
ls -la ~/.openclaw/sessions/

8.4. Lỗi quyền volume trong Docker

Nguyên nhân: Container user (UID 1000) không truy cập được mounted volumes.

# Fix quyền trên host
sudo chown -R 1000:1000 ~/.openclaw ~/openclaw/workspace

# Restart container
cd ~/openclaw
docker compose restart

8.5. OPENCLAW_GATEWAY_TOKEN env variable override

Nguyên nhân: Biến môi trường OPENCLAW_GATEWAY_TOKEN trong Docker silently override config file.

Cách sửa: Kiểm tra biến môi trường trong docker-compose.yml hoặc .env file và đảm bảo token khớp với config.

9. Lỗi bảo mật (CVE-2026-25253)

9.1. Mô tả lỗ hổng

Mọi OpenClaw version trước v2026.1.29 bị lỗ hổng 1-click RCE qua WebSocket handshake không xác thực. Kẻ tấn công có thể thực thi code ở host-level trong dưới 90 giây mà không cần credentials. Proof-of-concept đã được công bố.

9.2. Cách vá ngay

# Bước 1: Kiểm tra version
openclaw --version
# Bất kỳ version nào dưới v2026.1.29 = ĐANG BỊ LỖ HỔNG

# Bước 2: Update
openclaw update --force

# Bước 3: Tạo gateway token bảo mật
openclaw doctor --generate-gateway-token

# Bước 4: Audit bảo mật
openclaw doctor --security-audit

# Bước 5: Restart tất cả channel adapters
openclaw restart --all-channels

# Bước 6: Rotate tất cả gateway token cũ (coi như đã bị lộ)
openssl rand -base64 48
# Dùng output làm token mới

9.3. Config bảo mật khuyến nghị

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "your-long-random-token"
    }
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

10. Lỗi cấu hình & Config

10.1. Config JSON bị corrupted

# Kiểm tra JSON syntax
cat ~/.openclaw/openclaw.json | jq .

# Chạy doctor để sửa tự động
openclaw doctor --fix

10.2. `openclaw doctor` xóa config keys

Lưu ý: Lệnh openclaw doctor --fix sẽ xóa các config key mà version hiện tại không nhận dạng được. Sau khi upgrade, các key cũ (ví dụ tools.exec.enabled, tools.browser, các pairing key) sẽ bị strip.

Khuyến nghị: Luôn backup config trước khi chạy doctor:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
openclaw doctor --fix

10.3. Legacy config key — key cũ không hoạt động

Ví dụ: gateway.token (cũ) không thay thế gateway.auth.token (mới).

# Kiểm tra config hiện tại
openclaw config get gateway.auth.token
openclaw config get gateway.auth.mode

# Set đúng key mới
openclaw config set gateway.auth.token "your-token"
openclaw config set gateway.auth.mode "token"

10.4. Lỗi Zod validation

Biểu hiện: openclaw doctor báo "Invalid config" với Zod validation errors.

Cách sửa:

# Doctor sẽ strip các key không hợp lệ
openclaw doctor --fix

# Nếu vẫn lỗi, tạo config mới
mv ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.broken
openclaw configure

11. Lỗi hiệu năng & Memory

11.1. Phản hồi chậm (15-30+ giây)

Nguyên nhân và cách sửa:

Nguyên nhân	Giải pháp
Context quá lớn	Giảm memory files và active skills
Model chậm (Opus)	Chuyển sang Sonnet hoặc Haiku
Network latency	Dùng VPS ở US-East (gần Anthropic/OpenAI)
Ollama trên hardware yếu	Nâng cấp hardware hoặc chuyển sang cloud model

11.2. Memory quên liên tục

Nguyên nhân: OpenClaw dùng Markdown files cho memory.

Cách lưu thông tin lâu dài:

Long-term notes: yêu cầu bot ghi vào MEMORY.md.
Short-term context: tự động lưu trong memory/YYYY-MM-DD.md.
Hỏi bot: "Write this to memory: [thông tin cần nhớ]".

11.3. Disk usage cao

# Kiểm tra disk usage
du -sh ~/.openclaw/

# Dọn dẹp sessions cũ
openclaw sessions prune --older-than 30d

# Dọn sandbox workspaces
openclaw sandbox prune

12. Lỗi nâng cấp từ ClawdBot / Moltbot

12.1. Service cũ vẫn chạy

Nguyên nhân: Service clawdbot-gateway.service cũ chưa được dừng, gây conflict port 18789.

# Dừng service cũ
sudo systemctl stop clawdbot-gateway.service
sudo systemctl disable clawdbot-gateway.service

# Kiểm tra port
lsof -ti:18789

# Khởi động OpenClaw mới
openclaw gateway restart

12.2. Credential format không tương thích

Nguyên nhân: Credential format từ ClawdBot/Moltbot có thể không đúng format mới.

# Chạy migration tự động
openclaw doctor --fix

# Nếu lỗi, setup lại credential
openclaw models auth setup-token --provider anthropic

12.3. Di chuyển sang máy mới

# Trên máy mới:
# 1. Cài OpenClaw
npm install -g openclaw@latest

# 2. Copy state directory từ máy cũ
scp -r user@old-machine:~/.openclaw/ ~/.openclaw/

# 3. Copy workspace
scp -r user@old-machine:~/.openclaw/workspace/ ~/.openclaw/workspace/

# 4. Chạy doctor
openclaw doctor

# 5. Restart
openclaw gateway restart

13. Lỗi Sandbox & Tool Execution

13.1. `Docker not available` hoặc sandbox container fails

# Kiểm tra Docker
docker info

# Kiểm tra sandbox status
openclaw doctor --fix

# Nếu Docker không cần thiết, tắt sandbox
# (CẢNH BÁO: giảm bảo mật)
# sandbox.mode: "off" sẽ trigger audit warning

13.2. Tool execution sai scope

Nguyên nhân: Tool chạy ở scope sai (session vs agent vs shared).

Cách sửa: Kiểm tra config agents.defaults.sandbox.scope:

"agent" (mặc định): cách ly theo agent.
"session": cách ly theo session (chặt hơn).
"shared": chia sẻ (ít bảo mật hơn).

13.3. Sandbox registry bị mất state

Nguyên nhân: Concurrent writes không có locking.

Cách sửa: Update lên version mới nhất (đã fix bằng file locks + atomic replacement).

14. Lỗi Browser Control

14.1. Browser control không hoạt động

Checklist:

# Kiểm tra Chrome/Chromium đã cài
google-chrome --version
# hoặc
chromium-browser --version

# Bật browser control trong config
openclaw config set browser.enabled true

# Linux: đảm bảo display available (X11 hoặc Wayland)
echo $DISPLAY

# Restart gateway
openclaw gateway restart

14.2. `Failed to start Chrome CDP on port`

Nguyên nhân: Browser process không khởi động được.

Cách sửa:

Kiểm tra browser.executablePath trong config có đúng path không.
Click vào OpenClaw Chrome extension icon trên tab để attach.
Restart gateway: openclaw gateway restart.

15. Lỗi Model Failover

15.1. Fallback không trigger khi 429 (Issue #11972)

Biểu hiện: All models failed (1) — chỉ thử 1 model dù đã config 4 fallbacks.

Workaround: Dùng primary model từ provider có rate limit cao (ví dụ Anthropic hoặc DeepSeek). Nếu dùng Google free tier làm primary, rất dễ bị limit.

15.2. 502 Bad Gateway từ provider

Nguyên nhân: Provider (Anthropic, OpenAI, Google) tạm thời không khả dụng.

Cách sửa:

# Kiểm tra network
openclaw gateway probe

# Thường tự phục hồi trong vài phút
# Nếu lâu, kiểm tra status page của provider

# Nếu ở sau corporate firewall, set proxy
export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port

16. Lỗi API & TypeError khi kết nối Provider

Đây là nhóm lỗi phổ biến nhất mà người dùng gặp phải khi OpenClaw giao tiếp với các LLM provider (Anthropic, OpenAI, Google, Ollama, OpenRouter, MiniMax...).

16.1. `Cannot read properties of null (reading 'length')`

Nguyên nhân: Response từ API trả về null hoặc undefined thay vì object hợp lệ. Thường xảy ra khi:

Provider trả response format không đúng chuẩn.
Kết nối bị ngắt giữa chừng (timeout, network drop).
Model không tồn tại hoặc không khả dụng.

Cách sửa:

# Kiểm tra model có hoạt động không
openclaw models status

# Kiểm tra kết nối mạng
openclaw gateway probe

# Thử đổi model
openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4-6"

# Restart gateway
openclaw gateway restart

# Nếu dùng custom provider, kiểm tra baseUrl có đúng không
openclaw config get models.providers

16.2. `Cannot read properties of undefined (reading 'replace')`

Nguyên nhân (Issue #21923): Sau khi upgrade lên v2026.2.19, agent task crash ngay lập tức nếu không có embedding provider được cấu hình. Lỗi xảy ra trước khi bất kỳ API call nào được thực hiện.

Điều kiện kích hoạt:

Config có models.providers tùy chỉnh (ví dụ chỉ có Anthropic).
Không cấu hình embedding provider (Gemini/OpenAI cho embeddings).
openclaw doctor báo: "Memory search is enabled but no embedding provider is configured."

Cách sửa:

# Cách 1: Tắt memory search
openclaw config set agents.defaults.memorySearch.enabled false
openclaw gateway restart

# Cách 2: Thêm embedding provider (khuyến nghị)
openclaw models auth setup-token --provider openai
# Hoặc cấu hình trong config thủ công

# Cách 3: Rollback về version trước (tạm thời)
npm install -g [email protected]

16.3. `Cannot read properties of undefined (reading '0')`

Nguyên nhân (Issue #8714, #12196): Xảy ra khi:

Dùng custom OpenAI-compatible provider (BizRouter, LiteLLM...) — response format khác chuẩn.
Plugin state bị corrupted (Discord, Telegram) sau khi thêm provider mới hoặc chạy lâu.

Cách sửa cho custom provider:

# Kiểm tra response format từ provider
# Đảm bảo provider trả đúng OpenAI-compatible format

# Kiểm tra config provider
cat ~/.openclaw/openclaw.json | jq '.models.providers'

# Thử dùng provider chuẩn để xác nhận
openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4-6"

Cách sửa cho plugin state corruption:

# Discord: xóa session file bị corrupted
rm ~/.openclaw/agents/main/agent/sessions/discord-*.json

# Disable rồi re-enable plugin
openclaw config set plugins.entries.discord.enabled false
openclaw gateway restart
# Đợi 30 giây
openclaw config set plugins.entries.discord.enabled true
openclaw gateway restart

# Telegram: xóa data directory
rm -rf ~/.openclaw/telegram/
openclaw gateway restart

Lưu ý: Chỉ disable/enable plugin mà không xóa session file có thể không fix được — session file chứa corrupted state.

16.4. `Cannot read properties of undefined (reading 'includes')`

Nguyên nhân (Issue #5062, #8372): Lỗi trong Ollama model discovery. model.name bị undefined trong một số edge case.

Điều kiện kích hoạt:

Dùng Ollama provider với api: "openai-chat".
Một số model trả model.name là undefined.
Dùng model từ provider không chuẩn (Kimi, Feishu...).

Cách sửa:

# Cập nhật OpenClaw lên version mới nhất (đã patch)
openclaw update --force

# Nếu dùng Ollama, đảm bảo model name đúng
ollama list
# Kiểm tra tên model có trống không

# Cấu hình model rõ ràng trong config
# Thêm "name" field cho mỗi model trong providers config

Config ví dụ cho Ollama:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": "ollama",
      "api": "openai-chat",
      "models": [{
        "id": "llama3.1:8b",
        "name": "Llama 3.1 8B",
        "tools": true,
        "contextWindow": 8192,
        "maxTokens": 4096
      }]
    }
  }
}

16.5. `Cannot read properties of undefined (reading 'padEnd')` — Cron list crash

Nguyên nhân (Issue #4373): Bug trong CLI — code dùng job.id nhưng Gateway trả job.jobId.

Cách sửa:

# Cập nhật lên version mới nhất
openclaw update --force

# Workaround thủ công nếu chưa update:
# Sửa file:
# /opt/homebrew/lib/node_modules/openclaw/dist/cli/cron-cli/shared.js
# hoặc tương đương trên hệ thống của bạn
# Đổi: pad(job.id, CRON_ID_PAD)
# Thành: pad(job.jobId ?? job.id ?? '', CRON_ID_PAD)

16.6. `context_length_exceeded` — Vượt giới hạn context

Nguyên nhân: Tổng token (system prompt + conversation history + message hiện tại) vượt context window của model. System prompt của OpenClaw tiêu tốn khoảng 9,600 token mỗi request.

Sửa ngay:

# Cách 1: Compact conversation (giảm ~60% context)
# Trong chat, gõ:
/compact

# Cách 2: Bắt đầu session mới
/new

# Cách 3: Kiểm tra usage hiện tại
/status

Sửa lâu dài:

# Giới hạn session history
openclaw config set agents.defaults.maxSessionMessages 100

# Dọn memory files
mkdir -p ~/.openclaw/workspace/memory/archive
mv ~/.openclaw/workspace/memory/2025-*.md ~/.openclaw/workspace/memory/archive/

# Giữ MEMORY.md dưới vài KB
# Xóa nội dung cũ không cần thiết trong MEMORY.md

Bug liên quan (Issue #7483): False positive — lỗi context_length_exceeded xảy ra khi context thực ra chưa đầy. Nếu /status vẫn còn dư context, đây là bug.

Bug liên quan (Issue #9986): Fallback model không trigger khi context overflow, chỉ trigger cho API errors (529, timeout). Session bị freeze thay vì chuyển sang model có context lớn hơn.

16.7. `invalid beta flag` — Lỗi beta feature

Nguyên nhân: Config chứa beta header mà provider không hỗ trợ. Phổ biến với AWS Bedrock và Google Vertex AI.

Cách sửa:

# Kiểm tra beta flags trong config
cat ~/.openclaw/openclaw.json | jq '.models'

# Xóa beta flags không cần thiết
# Các beta flag phổ biến:
# - max-tokens-3-5-sonnet-2024-07-15
# - prompt-caching-2024-07-31
# - token-counting-2024-11-01

# Hoặc chuyển sang dùng Anthropic API trực tiếp thay vì Bedrock/Vertex
openclaw models auth setup-token --provider anthropic

16.8. `Connection error` / `ECONNREFUSED` / `ECONNRESET` / `ENOTFOUND`

Nguyên nhân: Kết nối đến provider bị từ chối hoặc timeout.

Bug đã biết (Issue #20931): OpenClaw không nhận dạng connection errors để trigger failover. classifyFailoverReason() trả null khiến hệ thống retry cùng provider thay vì chuyển sang fallback.

Cách sửa:

# Kiểm tra kết nối mạng
openclaw gateway probe
curl -I https://api.anthropic.com  # Test trực tiếp

# Nếu ở sau firewall/VPN
export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port

# Nếu dùng Ollama local, kiểm tra Ollama đang chạy
curl http://localhost:11434/api/tags

# Workaround: thêm fallback provider khác
# Khi provider chính fail, ít nhất có provider phụ

Config fallback nhiều provider:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6",
        "fallbacks": [
          "openai/gpt-4o",
          "google/gemini-2.5-flash",
          "openrouter/anthropic/claude-sonnet-4-6"
        ]
      }
    }
  }
}

16.9. SSL Certificate Errors

Nguyên nhân: Phổ biến trong:

Môi trường corporate có proxy server.
Hệ thống có certificate store cũ.
Docker container thiếu CA certificates.

Cách sửa:

# Cập nhật CA certificates
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y ca-certificates
sudo update-ca-certificates

# macOS
# Thường tự cập nhật qua Keychain

# Docker: thêm vào Dockerfile
# RUN apt-get update && apt-get install -y ca-certificates

# Bỏ qua SSL verify (CHỈ dùng khi debug, KHÔNG dùng production)
export NODE_TLS_REJECT_UNAUTHORIZED=0

16.10. `(no output)` — Model request fail không hiển thị lỗi

Nguyên nhân (Issue #4418): Khi model request fail (API key sai, rate limit, model không tồn tại), TUI và webchat hiển thị "(no output)" thay vì thông báo lỗi thực sự.

Cách sửa:

# Kiểm tra logs để thấy lỗi thật
openclaw logs --follow

# Trong một terminal khác, gửi message để trigger lỗi
# Logs sẽ hiện lỗi chi tiết (401, 429, model not found...)

# Kiểm tra API key
openclaw models status

# Kiểm tra config
openclaw doctor --fix

16.11. Billing / Quota Errors

Từ v2026.2.19+, khi provider trả lỗi billing/quota, OpenClaw hiển thị tên model trong thông báo lỗi (ví dụ: OpenAI (gpt-5.3)) để biết key/account nào cần nạp credits.

Cách sửa:

# Kiểm tra trạng thái billing
openclaw models status

# Nạp credit vào provider tương ứng
# Anthropic: console.anthropic.com
# OpenAI: platform.openai.com/account/billing
# Google: console.cloud.google.com

# Hoặc chuyển sang provider có credit
openclaw config set agents.defaults.model.primary "openai/gpt-4o"

16.12. Bảng tổng hợp TypeError thường gặp

Lỗi	Issue #	Nguyên nhân	Fix nhanh
`reading 'length'`	—	API response null/undefined	Kiểm tra model + network
`reading 'replace'`	#21923	Thiếu embedding provider sau upgrade	Tắt `memorySearch.enabled`
`reading '0'`	#8714, #12196	Custom provider / plugin corrupted	Xóa session file + restart
`reading 'includes'`	#5062, #8372	Ollama model.name undefined	Update OpenClaw + đặt name rõ ràng
`reading 'padEnd'`	#4373	Bug CLI job.id vs jobId	Update OpenClaw
`reading 'filter'`	—	Plugin init race condition	Restart gateway

16.13. Quy trình debug API errors tổng quát

# Bước 1: Xem lỗi chi tiết
openclaw logs --follow

# Bước 2: Kiểm tra provider
openclaw models status

# Bước 3: Test kết nối trực tiếp
curl -H "x-api-key: YOUR_KEY" https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# Bước 4: Nếu curl thành công nhưng OpenClaw fail → vấn đề ở config
openclaw doctor --fix

# Bước 5: Nếu curl cũng fail → vấn đề ở network/credentials
# Kiểm tra firewall, proxy, API key validity

17. Công cụ chẩn đoán tổng hợp

Bảng lệnh chẩn đoán nhanh

Lệnh	Mục đích
`openclaw status --all`	Báo cáo tổng quan toàn bộ hệ thống
`openclaw doctor --fix`	Tự động sửa lỗi cấu hình phổ biến
`openclaw doctor --security-audit`	Kiểm tra bảo mật
`openclaw doctor --generate-gateway-token`	Tạo token mới
`openclaw gateway status --deep`	Kiểm tra gateway chi tiết
`openclaw gateway probe`	Test network connectivity
`openclaw channels status --probe`	Test kết nối từng kênh
`openclaw channels list`	Liệt kê trạng thái kênh
`openclaw models status`	Kiểm tra provider/model
`openclaw logs --follow`	Xem log realtime
`openclaw health --watch`	Dashboard health realtime
`openclaw devices list`	Xem pending device pairing
`openclaw config get <key>`	Đọc giá trị config cụ thể

Script chẩn đoán tự động

#!/bin/bash
echo "=== OpenClaw Diagnostic ==="
echo ""
echo "--- Version ---"
openclaw --version
echo ""
echo "--- Status ---"
openclaw status --all
echo ""
echo "--- Gateway ---"
openclaw gateway status
echo ""
echo "--- Channels ---"
openclaw channels list
echo ""
echo "--- Models ---"
openclaw models status
echo ""
echo "--- Doctor ---"
openclaw doctor
echo ""
echo "=== Done ==="

Quy trình xử lý lỗi 60 giây

Chạy openclaw status --all → Xem tổng quan.
Chạy openclaw doctor --fix → Sửa tự động.
Nếu vẫn lỗi, chạy openclaw logs --follow → Xem log khi tái tạo lỗi.
Bấm Ctrl+C khi đã thu thập đủ thông tin.
Tra cứu lỗi cụ thể trong tài liệu này.

Kênh hỗ trợ

Docs chính thức: https://docs.openclaw.ai
GitHub Issues: https://github.com/openclaw/openclaw/issues
Discord community: Tìm trên trang chủ OpenClaw

Cập nhật lần cuối: Tháng 2/2026 Phiên bản OpenClaw tham chiếu: v2026.2.19+

OpenClaw — Hướng Dẫn Xử Lý Lỗi Toàn Diện (2026)

Lệnh đầu tiên khi gặp bất kỳ lỗi nào:
openclaw status --all
openclaw doctor --fix
Hai lệnh này giải quyết được khoảng 70% vấn đề mà không cần can thiệp thủ công.

Mục lục

Lỗi cài đặt
Lỗi Gateway & Kết nối
Lỗi xác thực (401 Unauthorized)
Lỗi giới hạn tốc độ (429 Rate Limit)
Lỗi Pairing & Device (1008)
Lỗi kênh WhatsApp
Lỗi kênh Telegram & Discord
Lỗi Docker & Container
Lỗi bảo mật (CVE-2026-25253)
Lỗi cấu hình & Config
Lỗi hiệu năng & Memory
Lỗi nâng cấp từ ClawdBot / Moltbot
Lỗi Sandbox & Tool Execution
Lỗi Browser Control
Lỗi Model Failover
Lỗi API & TypeError khi kết nối Provider
Công cụ chẩn đoán tổng hợp

1. Lỗi cài đặt

1.1. `openclaw: command not found`

Nguyên nhân: npm global bin chưa được thêm vào PATH.

Cách sửa:

# Kiểm tra npm global path
npm prefix -g

# Thêm vào PATH (bash/zsh trên macOS/Linux)
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Xác nhận
which openclaw

Trên Windows: thêm %AppData%\npm vào biến môi trường PATH, sau đó khởi động lại PowerShell.

1.2. Node.js version không đúng

Nguyên nhân: OpenClaw yêu cầu Node.js >= 22 (không phải 18 hay 20).

Cách sửa:

# Kiểm tra version hiện tại
node --version

# Cài đặt đúng version qua nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

# Xác nhận
node --version  # Phải là v22.x.x trở lên

1.3. Lỗi build `sharp` (native dependency)

Biểu hiện: Lỗi compilation khi cài đặt, liên quan đến [email protected].

Cách sửa:

# macOS: cài Xcode Command Line Tools
xcode-select --install

# Set biến môi trường để bỏ qua system libvips
export SHARP_IGNORE_GLOBAL_LIBVIPS=1

# Cài lại OpenClaw
npm install -g openclaw@latest

1.4. Lỗi cài đặt chung (npm fails)

Cách sửa:

# Xóa cache npm
npm cache clean --force

# Gỡ cài đặt cũ
npm uninstall -g openclaw

# Cài mới
npm install -g openclaw@latest

# Nếu vẫn lỗi, dùng installer script
curl -fsSL https://openclaw.ai/install.sh | bash

1.5. Lỗi quyền truy cập (Permission denied)

Nguyên nhân: File ownership sai hoặc thiếu quyền trên thư mục .openclaw.

Cách sửa:

# Sửa quyền sở hữu
sudo chown -R $(whoami) ~/.openclaw

# Kiểm tra quyền
ls -la ~/.openclaw/

2. Lỗi Gateway & Kết nối

2.1. Gateway không khởi động được

Biểu hiện: Gateway start blocked: set gateway.mode=local

Cách sửa:

# Bật local gateway mode
openclaw config set gateway.mode "local"

# Hoặc chạy cấu hình lại
openclaw configure

# Kiểm tra trạng thái
openclaw gateway status

Nếu chạy OpenClaw qua Podman với user riêng, config nằm ở ~openclaw/.openclaw/openclaw.json.

2.2. Port conflict — `EADDRINUSE :::18789`

Nguyên nhân: Port 18789 (mặc định) đang bị tiến trình khác chiếm.

Cách sửa:

# Tìm tiến trình đang dùng port
lsof -ti:18789        # macOS/Linux
netstat -ano | findstr :18789  # Windows

# Kill tiến trình
kill -9 <PID>

# Hoặc đổi port
openclaw config set gateway.port 18790

# Restart gateway
openclaw gateway restart

2.3. `Gateway not reachable` hoặc timeout

Cách sửa:

# Kiểm tra trạng thái sâu
openclaw gateway status --deep

# Kiểm tra config
openclaw config get gateway.bind
openclaw config get gateway.auth.token
openclaw config get gateway.remote.url

# Nếu gateway.mode=remote, CLI có thể đang trỏ sang remote
# trong khi local service vẫn chạy bình thường
openclaw config get gateway.mode

# Restart
openclaw gateway restart

# Nếu vẫn lỗi, reinstall gateway service
openclaw gateway install --force

2.4. `gateway already running pid lock timeout`

Nguyên nhân: File PID cũ chưa được dọn dẹp.

Cách sửa:

# Dừng tất cả process openclaw
pkill -f openclaw

# Xóa file lock nếu có
rm -f ~/.openclaw/gateway.pid

# Khởi động lại
openclaw gateway restart

3. Lỗi xác thực (401 Unauthorized)

3.1. API key không hợp lệ hoặc hết hạn

Cách sửa:

# Kiểm tra trạng thái credential
openclaw models status

# Setup lại token cho Anthropic
openclaw models auth setup-token --provider anthropic

# Hoặc cho OpenAI
openclaw models auth setup-token --provider openai

3.2. OAuth token hết hạn

Cách sửa:

# Đăng xuất rồi đăng nhập lại
# Trong chat interface, gõ:
/logout
/login

# Hoặc chuyển sang dùng setup-token (ổn định hơn)
openclaw models auth setup-token --provider anthropic

3.3. Credential sai agent trong multi-agent setup

Nguyên nhân: Mỗi agent có credentials riêng ở ~/.openclaw/agents/<agentId>/agent/auth-profiles.json. Credential của agent này không tự áp dụng cho agent khác.

Cách sửa:

# Kiểm tra agent nào đang active
openclaw agent list

# Kiểm tra credential file cụ thể
cat ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

3.4. Lỗi credential trên từng nền tảng

macOS: Keychain access permissions có thể chặn việc đọc credential. Kiểm tra Keychain Access app.
Linux: Sai quyền file trên thư mục .openclaw. Chạy chmod 700 ~/.openclaw.
Windows: Xung đột biến môi trường giữa system scope và user scope.

4. Lỗi giới hạn tốc độ (429 Rate Limit)

4.1. Hiểu về 429 error

4.2. Chẩn đoán nhanh

# Kiểm tra trạng thái provider
openclaw models status

# Kiểm tra sâu
openclaw status --deep

4.3. Sửa nhanh

# Cách 1: Đợi 60 giây (đơn giản nhất)

# Cách 2: Restart gateway để xóa internal cooldown state
openclaw gateway restart

# Cách 3: Chuyển sang provider khác tạm thời
openclaw config set model "openai/gpt-4o"

4.4. Cấu hình fallback model (khuyến nghị)

Thêm fallback models trong config để khi provider chính bị limit, OpenClaw tự chuyển sang provider phụ:

{
  "models": {
    "primary": "anthropic/claude-sonnet-4-6",
    "fallbacks": [
      "openai/gpt-4o",
      "google/gemini-2.5-flash"
    ]
  }
}

4.5. Bug đã biết: Không có exponential backoff (Issue #5159)

Vấn đề: Hệ thống retry liên tục trong vài giây thay vì đợi lâu hơn, gây ra vòng lặp 429 liên tục.

Workaround: Cấu hình fallback model sang provider khác. Khi Claude bị limit, hệ thống sẽ tự chuyển sang GPT-4 hoặc Gemini.

4.6. Bug đã biết: Cooldown toàn provider (Issue #5744)

Vấn đề: Khi 1 model bị rate limit (ví dụ gemini-3.5-flash), toàn bộ provider Google bị cooldown, kể cả model khác có quota riêng.

Workaround: Thêm fallback model từ provider khác (ví dụ Anthropic hoặc OpenRouter).

4.7. Bug: Failover misclassification (Issue #10368)

5. Lỗi Pairing & Device (1008)

5.1. `disconnected (1008): pairing required`

Cách sửa:

# Xem danh sách pending pairing requests
openclaw devices list

# Approve device
openclaw devices approve <request-id>

# Client sẽ tự động reconnect sau vài giây

Nếu chạy trong Docker:

# Xem pending requests trong container
docker compose exec openclaw openclaw devices list

# Approve
docker compose exec openclaw openclaw devices approve <request-id>

Từ v2026.2.21, pairing list và pairing approve tự detect channel duy nhất nếu chỉ có một, không cần chỉ định channel argument.

5.2. `unauthorized: gateway token missing`

Cách sửa:

# Tạo gateway token mới
openclaw doctor --generate-gateway-token

# Mở dashboard với token
openclaw dashboard --no-open

# Paste token vào Control UI dashboard settings rồi refresh

Từ v2026.2.19, nếu bạn chưa set gateway auth, OpenClaw sẽ tự động tạo và lưu gateway.auth.token khi khởi động.

5.3. Quản lý paired devices

# Xóa 1 device cụ thể
openclaw devices remove <device-id>

# Xóa tất cả paired entries (và tùy chọn reject pending)
openclaw devices clear --yes --pending

6. Lỗi kênh WhatsApp

6.1. QR code hết hạn / không scan được

Lưu ý: QR code hết hạn sau 60 giây.

# Đăng nhập lại
openclaw channels login --channel whatsapp

# Scan nhanh QR code trong vòng 60 giây
# Trên điện thoại: WhatsApp → Settings → Linked Devices → Link a Device

6.2. WhatsApp bị stuck ở "logging in" sau khi đổi số

Nguyên nhân: Credential cũ bị lỗi, session state bị corrupted.

Cách sửa:

# Xóa credential WhatsApp cũ
rm -rf ~/.openclaw/credentials/whatsapp/

# Đăng nhập lại
openclaw channels login --channel whatsapp

6.3. WhatsApp liên tục reconnect (reconnect loop)

Nguyên nhân phổ biến:

Chạy nhiều OpenClaw instance trên cùng 1 số WhatsApp.
Session bị chia sẻ giữa các Gateway.

Quy tắc: Mỗi số WhatsApp chỉ dùng cho 1 Gateway duy nhất.

# Kiểm tra kết nối
openclaw channels status --probe

# Nếu lỗi, unlink session cũ trên điện thoại
# WhatsApp → Settings → Linked Devices → xóa device cũ

# Reset lại
openclaw channels reset whatsapp
openclaw channels login --channel whatsapp

6.4. Bị WhatsApp rate limit / ban tạm

Nguyên nhân: Gửi quá nhiều tin nhắn (trên 20 tin/phút có thể bị throttle).

Khuyến nghị:

Giữ tốc độ gửi dưới 20 tin/phút.
Dùng số điện thoại riêng cho bot (không dùng số cá nhân).
Bắt đầu với mode allowlist, chuyển sang pairing sau khi đã test kỹ.

6.5. Bug WhatsApp Allowlist Bypass (Issue #22599)

Vấn đề (phát hiện 2026-02-21, severity HIGH): Tin nhắn từ số không nằm trong allowlist vẫn được nhận và xử lý mặc dù đã cấu hình dmPolicy: "allowlist".

Workaround: Kiểm tra file ~/.openclaw/credentials/whatsapp-allowFrom.json và xóa các entry không mong muốn. Theo dõi Issue #22599 để cập nhật bản vá.

7. Lỗi kênh Telegram & Discord

7.1. Telegram bot không nhận tin nhắn

Checklist:

# Kiểm tra trạng thái kênh
openclaw channels list
openclaw channels status --probe

# Kiểm tra bot token
openclaw config get channels.telegram.token

# Đảm bảo đã start chat với bot trên Telegram
# Gửi /start cho bot

7.2. Telegram `setMyCommands` fails

Nguyên nhân: Lỗi mạng hoặc bot token không đúng.

Cách sửa:

# Kiểm tra kết nối mạng
openclaw gateway probe

# Kiểm tra logs
openclaw logs --follow

7.3. Discord bot không nhận tin nhắn (close code 4014)

Nguyên nhân: Thiếu privileged gateway intent.

Cách sửa:

Vào Discord Developer Portal.
Chọn Application → Bot section.
Bật "Message Content Intent".
Restart OpenClaw: openclaw gateway restart.

7.4. Xung đột tài nguyên khi chạy nhiều kênh cùng lúc

Nguyên nhân: WhatsApp (WebSocket persistent), Telegram (long polling), Discord (WebSocket + Intent) cạnh tranh event loop, RAM và file descriptors.

Khuyến nghị:

Đảm bảo VPS có ít nhất 2GB RAM khi chạy 3 kênh.
Monitor bằng openclaw health --watch.
Nếu gặp vấn đề, giảm số kênh hoặc tăng RAM.

8. Lỗi Docker & Container

8.1. Container bị OOM-killed

Nguyên nhân: RAM quá thấp. Container cần ít nhất 512MB RAM.

# Kiểm tra usage
docker stats openclaw

# Tăng memory limit trong docker-compose.yml
services:
  openclaw:
    image: openclaw/openclaw:latest
    deploy:
      resources:
        limits:
          memory: 2G

8.2. Container khởi động lại mất config

Nguyên nhân: Không mount volume config.

Cách sửa (docker-compose.yml):

services:
  openclaw:
    image: openclaw/openclaw:latest
    restart: unless-stopped
    volumes:
      - ./data:/root/.openclaw    # QUAN TRỌNG: mount toàn bộ thư mục
    ports:
      - "3456:3456"
    environment:
      - NODE_ENV=production

Lưu ý: Mount toàn bộ ~/.openclaw/ thay vì từng thư mục con. Nếu mount từng phần, thư mục sessions có thể không tồn tại đúng chỗ.

8.3. `Session file path must be within sessions directory`

Nguyên nhân (từ v2026.2.12):

Docker volume mount thiếu thư mục sessions.
Symlink ~/.openclaw/ không giữ đúng cấu trúc thư mục.
Validation path chặt hơn sau khi upgrade.

Cách sửa:

# Đảm bảo thư mục sessions tồn tại
mkdir -p ~/.openclaw/sessions/

# Mount full directory, không symlink
# Trong docker-compose.yml: dùng ./data:/root/.openclaw

# Kiểm tra quyền user
ls -la ~/.openclaw/sessions/

8.4. Lỗi quyền volume trong Docker

Nguyên nhân: Container user (UID 1000) không truy cập được mounted volumes.

# Fix quyền trên host
sudo chown -R 1000:1000 ~/.openclaw ~/openclaw/workspace

# Restart container
cd ~/openclaw
docker compose restart

8.5. OPENCLAW_GATEWAY_TOKEN env variable override

Nguyên nhân: Biến môi trường OPENCLAW_GATEWAY_TOKEN trong Docker silently override config file.

Cách sửa: Kiểm tra biến môi trường trong docker-compose.yml hoặc .env file và đảm bảo token khớp với config.

9. Lỗi bảo mật (CVE-2026-25253)

9.1. Mô tả lỗ hổng

9.2. Cách vá ngay

# Bước 1: Kiểm tra version
openclaw --version
# Bất kỳ version nào dưới v2026.1.29 = ĐANG BỊ LỖ HỔNG

# Bước 2: Update
openclaw update --force

# Bước 3: Tạo gateway token bảo mật
openclaw doctor --generate-gateway-token

# Bước 4: Audit bảo mật
openclaw doctor --security-audit

# Bước 5: Restart tất cả channel adapters
openclaw restart --all-channels

# Bước 6: Rotate tất cả gateway token cũ (coi như đã bị lộ)
openssl rand -base64 48
# Dùng output làm token mới

9.3. Config bảo mật khuyến nghị

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "your-long-random-token"
    }
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

10. Lỗi cấu hình & Config

10.1. Config JSON bị corrupted

# Kiểm tra JSON syntax
cat ~/.openclaw/openclaw.json | jq .

# Chạy doctor để sửa tự động
openclaw doctor --fix

10.2. `openclaw doctor` xóa config keys

Khuyến nghị: Luôn backup config trước khi chạy doctor:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
openclaw doctor --fix

10.3. Legacy config key — key cũ không hoạt động

Ví dụ: gateway.token (cũ) không thay thế gateway.auth.token (mới).

# Kiểm tra config hiện tại
openclaw config get gateway.auth.token
openclaw config get gateway.auth.mode

# Set đúng key mới
openclaw config set gateway.auth.token "your-token"
openclaw config set gateway.auth.mode "token"

10.4. Lỗi Zod validation

Biểu hiện: openclaw doctor báo "Invalid config" với Zod validation errors.

Cách sửa:

# Doctor sẽ strip các key không hợp lệ
openclaw doctor --fix

# Nếu vẫn lỗi, tạo config mới
mv ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.broken
openclaw configure

11. Lỗi hiệu năng & Memory

11.1. Phản hồi chậm (15-30+ giây)

Nguyên nhân và cách sửa:

Nguyên nhân	Giải pháp
Context quá lớn	Giảm memory files và active skills
Model chậm (Opus)	Chuyển sang Sonnet hoặc Haiku
Network latency	Dùng VPS ở US-East (gần Anthropic/OpenAI)
Ollama trên hardware yếu	Nâng cấp hardware hoặc chuyển sang cloud model

11.2. Memory quên liên tục

Nguyên nhân: OpenClaw dùng Markdown files cho memory.

Cách lưu thông tin lâu dài:

Long-term notes: yêu cầu bot ghi vào MEMORY.md.
Short-term context: tự động lưu trong memory/YYYY-MM-DD.md.
Hỏi bot: "Write this to memory: [thông tin cần nhớ]".

11.3. Disk usage cao

# Kiểm tra disk usage
du -sh ~/.openclaw/

# Dọn dẹp sessions cũ
openclaw sessions prune --older-than 30d

# Dọn sandbox workspaces
openclaw sandbox prune

12. Lỗi nâng cấp từ ClawdBot / Moltbot

12.1. Service cũ vẫn chạy

Nguyên nhân: Service clawdbot-gateway.service cũ chưa được dừng, gây conflict port 18789.

# Dừng service cũ
sudo systemctl stop clawdbot-gateway.service
sudo systemctl disable clawdbot-gateway.service

# Kiểm tra port
lsof -ti:18789

# Khởi động OpenClaw mới
openclaw gateway restart

12.2. Credential format không tương thích

Nguyên nhân: Credential format từ ClawdBot/Moltbot có thể không đúng format mới.

# Chạy migration tự động
openclaw doctor --fix

# Nếu lỗi, setup lại credential
openclaw models auth setup-token --provider anthropic

12.3. Di chuyển sang máy mới

# Trên máy mới:
# 1. Cài OpenClaw
npm install -g openclaw@latest

# 2. Copy state directory từ máy cũ
scp -r user@old-machine:~/.openclaw/ ~/.openclaw/

# 3. Copy workspace
scp -r user@old-machine:~/.openclaw/workspace/ ~/.openclaw/workspace/

# 4. Chạy doctor
openclaw doctor

# 5. Restart
openclaw gateway restart

13. Lỗi Sandbox & Tool Execution

13.1. `Docker not available` hoặc sandbox container fails

# Kiểm tra Docker
docker info

# Kiểm tra sandbox status
openclaw doctor --fix

# Nếu Docker không cần thiết, tắt sandbox
# (CẢNH BÁO: giảm bảo mật)
# sandbox.mode: "off" sẽ trigger audit warning

13.2. Tool execution sai scope

Nguyên nhân: Tool chạy ở scope sai (session vs agent vs shared).

Cách sửa: Kiểm tra config agents.defaults.sandbox.scope:

"agent" (mặc định): cách ly theo agent.
"session": cách ly theo session (chặt hơn).
"shared": chia sẻ (ít bảo mật hơn).

13.3. Sandbox registry bị mất state

Nguyên nhân: Concurrent writes không có locking.

Cách sửa: Update lên version mới nhất (đã fix bằng file locks + atomic replacement).

14. Lỗi Browser Control

14.1. Browser control không hoạt động

Checklist:

# Kiểm tra Chrome/Chromium đã cài
google-chrome --version
# hoặc
chromium-browser --version

# Bật browser control trong config
openclaw config set browser.enabled true

# Linux: đảm bảo display available (X11 hoặc Wayland)
echo $DISPLAY

# Restart gateway
openclaw gateway restart

14.2. `Failed to start Chrome CDP on port`

Nguyên nhân: Browser process không khởi động được.

Cách sửa:

Kiểm tra browser.executablePath trong config có đúng path không.
Click vào OpenClaw Chrome extension icon trên tab để attach.
Restart gateway: openclaw gateway restart.

15. Lỗi Model Failover

15.1. Fallback không trigger khi 429 (Issue #11972)

Biểu hiện: All models failed (1) — chỉ thử 1 model dù đã config 4 fallbacks.

Workaround: Dùng primary model từ provider có rate limit cao (ví dụ Anthropic hoặc DeepSeek). Nếu dùng Google free tier làm primary, rất dễ bị limit.

15.2. 502 Bad Gateway từ provider

Nguyên nhân: Provider (Anthropic, OpenAI, Google) tạm thời không khả dụng.

Cách sửa:

# Kiểm tra network
openclaw gateway probe

# Thường tự phục hồi trong vài phút
# Nếu lâu, kiểm tra status page của provider

# Nếu ở sau corporate firewall, set proxy
export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port

16. Lỗi API & TypeError khi kết nối Provider

Đây là nhóm lỗi phổ biến nhất mà người dùng gặp phải khi OpenClaw giao tiếp với các LLM provider (Anthropic, OpenAI, Google, Ollama, OpenRouter, MiniMax...).

16.1. `Cannot read properties of null (reading 'length')`

Nguyên nhân: Response từ API trả về null hoặc undefined thay vì object hợp lệ. Thường xảy ra khi:

Provider trả response format không đúng chuẩn.
Kết nối bị ngắt giữa chừng (timeout, network drop).
Model không tồn tại hoặc không khả dụng.

Cách sửa:

# Kiểm tra model có hoạt động không
openclaw models status

# Kiểm tra kết nối mạng
openclaw gateway probe

# Thử đổi model
openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4-6"

# Restart gateway
openclaw gateway restart

# Nếu dùng custom provider, kiểm tra baseUrl có đúng không
openclaw config get models.providers

16.2. `Cannot read properties of undefined (reading 'replace')`

Điều kiện kích hoạt:

Config có models.providers tùy chỉnh (ví dụ chỉ có Anthropic).
Không cấu hình embedding provider (Gemini/OpenAI cho embeddings).
openclaw doctor báo: "Memory search is enabled but no embedding provider is configured."

Cách sửa:

# Cách 1: Tắt memory search
openclaw config set agents.defaults.memorySearch.enabled false
openclaw gateway restart

# Cách 2: Thêm embedding provider (khuyến nghị)
openclaw models auth setup-token --provider openai
# Hoặc cấu hình trong config thủ công

# Cách 3: Rollback về version trước (tạm thời)
npm install -g [email protected]

16.3. `Cannot read properties of undefined (reading '0')`

Nguyên nhân (Issue #8714, #12196): Xảy ra khi:

Dùng custom OpenAI-compatible provider (BizRouter, LiteLLM...) — response format khác chuẩn.
Plugin state bị corrupted (Discord, Telegram) sau khi thêm provider mới hoặc chạy lâu.

Cách sửa cho custom provider:

# Kiểm tra response format từ provider
# Đảm bảo provider trả đúng OpenAI-compatible format

# Kiểm tra config provider
cat ~/.openclaw/openclaw.json | jq '.models.providers'

# Thử dùng provider chuẩn để xác nhận
openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4-6"

Cách sửa cho plugin state corruption:

# Discord: xóa session file bị corrupted
rm ~/.openclaw/agents/main/agent/sessions/discord-*.json

# Disable rồi re-enable plugin
openclaw config set plugins.entries.discord.enabled false
openclaw gateway restart
# Đợi 30 giây
openclaw config set plugins.entries.discord.enabled true
openclaw gateway restart

# Telegram: xóa data directory
rm -rf ~/.openclaw/telegram/
openclaw gateway restart

Lưu ý: Chỉ disable/enable plugin mà không xóa session file có thể không fix được — session file chứa corrupted state.

16.4. `Cannot read properties of undefined (reading 'includes')`

Nguyên nhân (Issue #5062, #8372): Lỗi trong Ollama model discovery. model.name bị undefined trong một số edge case.

Điều kiện kích hoạt:

Dùng Ollama provider với api: "openai-chat".
Một số model trả model.name là undefined.
Dùng model từ provider không chuẩn (Kimi, Feishu...).

Cách sửa:

# Cập nhật OpenClaw lên version mới nhất (đã patch)
openclaw update --force

# Nếu dùng Ollama, đảm bảo model name đúng
ollama list
# Kiểm tra tên model có trống không

# Cấu hình model rõ ràng trong config
# Thêm "name" field cho mỗi model trong providers config

Config ví dụ cho Ollama:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": "ollama",
      "api": "openai-chat",
      "models": [{
        "id": "llama3.1:8b",
        "name": "Llama 3.1 8B",
        "tools": true,
        "contextWindow": 8192,
        "maxTokens": 4096
      }]
    }
  }
}

16.5. `Cannot read properties of undefined (reading 'padEnd')` — Cron list crash

Nguyên nhân (Issue #4373): Bug trong CLI — code dùng job.id nhưng Gateway trả job.jobId.

Cách sửa:

# Cập nhật lên version mới nhất
openclaw update --force

# Workaround thủ công nếu chưa update:
# Sửa file:
# /opt/homebrew/lib/node_modules/openclaw/dist/cli/cron-cli/shared.js
# hoặc tương đương trên hệ thống của bạn
# Đổi: pad(job.id, CRON_ID_PAD)
# Thành: pad(job.jobId ?? job.id ?? '', CRON_ID_PAD)

16.6. `context_length_exceeded` — Vượt giới hạn context

Sửa ngay:

# Cách 1: Compact conversation (giảm ~60% context)
# Trong chat, gõ:
/compact

# Cách 2: Bắt đầu session mới
/new

# Cách 3: Kiểm tra usage hiện tại
/status

Sửa lâu dài:

# Giới hạn session history
openclaw config set agents.defaults.maxSessionMessages 100

# Dọn memory files
mkdir -p ~/.openclaw/workspace/memory/archive
mv ~/.openclaw/workspace/memory/2025-*.md ~/.openclaw/workspace/memory/archive/

# Giữ MEMORY.md dưới vài KB
# Xóa nội dung cũ không cần thiết trong MEMORY.md

Bug liên quan (Issue #7483): False positive — lỗi context_length_exceeded xảy ra khi context thực ra chưa đầy. Nếu /status vẫn còn dư context, đây là bug.

16.7. `invalid beta flag` — Lỗi beta feature

Nguyên nhân: Config chứa beta header mà provider không hỗ trợ. Phổ biến với AWS Bedrock và Google Vertex AI.

Cách sửa:

# Kiểm tra beta flags trong config
cat ~/.openclaw/openclaw.json | jq '.models'

# Xóa beta flags không cần thiết
# Các beta flag phổ biến:
# - max-tokens-3-5-sonnet-2024-07-15
# - prompt-caching-2024-07-31
# - token-counting-2024-11-01

# Hoặc chuyển sang dùng Anthropic API trực tiếp thay vì Bedrock/Vertex
openclaw models auth setup-token --provider anthropic

16.8. `Connection error` / `ECONNREFUSED` / `ECONNRESET` / `ENOTFOUND`

Nguyên nhân: Kết nối đến provider bị từ chối hoặc timeout.

Cách sửa:

# Kiểm tra kết nối mạng
openclaw gateway probe
curl -I https://api.anthropic.com  # Test trực tiếp

# Nếu ở sau firewall/VPN
export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port

# Nếu dùng Ollama local, kiểm tra Ollama đang chạy
curl http://localhost:11434/api/tags

# Workaround: thêm fallback provider khác
# Khi provider chính fail, ít nhất có provider phụ

Config fallback nhiều provider:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6",
        "fallbacks": [
          "openai/gpt-4o",
          "google/gemini-2.5-flash",
          "openrouter/anthropic/claude-sonnet-4-6"
        ]
      }
    }
  }
}

16.9. SSL Certificate Errors

Nguyên nhân: Phổ biến trong:

Môi trường corporate có proxy server.
Hệ thống có certificate store cũ.
Docker container thiếu CA certificates.

Cách sửa:

# Cập nhật CA certificates
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y ca-certificates
sudo update-ca-certificates

# macOS
# Thường tự cập nhật qua Keychain

# Docker: thêm vào Dockerfile
# RUN apt-get update && apt-get install -y ca-certificates

# Bỏ qua SSL verify (CHỈ dùng khi debug, KHÔNG dùng production)
export NODE_TLS_REJECT_UNAUTHORIZED=0

16.10. `(no output)` — Model request fail không hiển thị lỗi

Nguyên nhân (Issue #4418): Khi model request fail (API key sai, rate limit, model không tồn tại), TUI và webchat hiển thị "(no output)" thay vì thông báo lỗi thực sự.

Cách sửa:

# Kiểm tra logs để thấy lỗi thật
openclaw logs --follow

# Trong một terminal khác, gửi message để trigger lỗi
# Logs sẽ hiện lỗi chi tiết (401, 429, model not found...)

# Kiểm tra API key
openclaw models status

# Kiểm tra config
openclaw doctor --fix

16.11. Billing / Quota Errors

Cách sửa:

# Kiểm tra trạng thái billing
openclaw models status

# Nạp credit vào provider tương ứng
# Anthropic: console.anthropic.com
# OpenAI: platform.openai.com/account/billing
# Google: console.cloud.google.com

# Hoặc chuyển sang provider có credit
openclaw config set agents.defaults.model.primary "openai/gpt-4o"

16.12. Bảng tổng hợp TypeError thường gặp

Lỗi	Issue #	Nguyên nhân	Fix nhanh
`reading 'length'`	—	API response null/undefined	Kiểm tra model + network
`reading 'replace'`	#21923	Thiếu embedding provider sau upgrade	Tắt `memorySearch.enabled`
`reading '0'`	#8714, #12196	Custom provider / plugin corrupted	Xóa session file + restart
`reading 'includes'`	#5062, #8372	Ollama model.name undefined	Update OpenClaw + đặt name rõ ràng
`reading 'padEnd'`	#4373	Bug CLI job.id vs jobId	Update OpenClaw
`reading 'filter'`	—	Plugin init race condition	Restart gateway

16.13. Quy trình debug API errors tổng quát

# Bước 1: Xem lỗi chi tiết
openclaw logs --follow

# Bước 2: Kiểm tra provider
openclaw models status

# Bước 3: Test kết nối trực tiếp
curl -H "x-api-key: YOUR_KEY" https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# Bước 4: Nếu curl thành công nhưng OpenClaw fail → vấn đề ở config
openclaw doctor --fix

# Bước 5: Nếu curl cũng fail → vấn đề ở network/credentials
# Kiểm tra firewall, proxy, API key validity

17. Công cụ chẩn đoán tổng hợp

Bảng lệnh chẩn đoán nhanh

Lệnh	Mục đích
`openclaw status --all`	Báo cáo tổng quan toàn bộ hệ thống
`openclaw doctor --fix`	Tự động sửa lỗi cấu hình phổ biến
`openclaw doctor --security-audit`	Kiểm tra bảo mật
`openclaw doctor --generate-gateway-token`	Tạo token mới
`openclaw gateway status --deep`	Kiểm tra gateway chi tiết
`openclaw gateway probe`	Test network connectivity
`openclaw channels status --probe`	Test kết nối từng kênh
`openclaw channels list`	Liệt kê trạng thái kênh
`openclaw models status`	Kiểm tra provider/model
`openclaw logs --follow`	Xem log realtime
`openclaw health --watch`	Dashboard health realtime
`openclaw devices list`	Xem pending device pairing
`openclaw config get <key>`	Đọc giá trị config cụ thể

Script chẩn đoán tự động

#!/bin/bash
echo "=== OpenClaw Diagnostic ==="
echo ""
echo "--- Version ---"
openclaw --version
echo ""
echo "--- Status ---"
openclaw status --all
echo ""
echo "--- Gateway ---"
openclaw gateway status
echo ""
echo "--- Channels ---"
openclaw channels list
echo ""
echo "--- Models ---"
openclaw models status
echo ""
echo "--- Doctor ---"
openclaw doctor
echo ""
echo "=== Done ==="

Quy trình xử lý lỗi 60 giây

Chạy openclaw status --all → Xem tổng quan.
Chạy openclaw doctor --fix → Sửa tự động.
Nếu vẫn lỗi, chạy openclaw logs --follow → Xem log khi tái tạo lỗi.
Bấm Ctrl+C khi đã thu thập đủ thông tin.
Tra cứu lỗi cụ thể trong tài liệu này.

Kênh hỗ trợ

Docs chính thức: https://docs.openclaw.ai
GitHub Issues: https://github.com/openclaw/openclaw/issues
Discord community: Tìm trên trang chủ OpenClaw

Cập nhật lần cuối: Tháng 2/2026 Phiên bản OpenClaw tham chiếu: v2026.2.19+

OpenClaw — Hướng Dẫn Xử Lý Lỗi Toàn Diện (2026)

Mục lục

1. Lỗi cài đặt

1.1. openclaw: command not found

1.2. Node.js version không đúng

1.3. Lỗi build sharp (native dependency)

1.4. Lỗi cài đặt chung (npm fails)

1.5. Lỗi quyền truy cập (Permission denied)

2. Lỗi Gateway & Kết nối

2.1. Gateway không khởi động được

2.2. Port conflict — EADDRINUSE :::18789

2.3. Gateway not reachable hoặc timeout

2.4. gateway already running pid lock timeout

3. Lỗi xác thực (401 Unauthorized)

3.1. API key không hợp lệ hoặc hết hạn

3.2. OAuth token hết hạn

3.3. Credential sai agent trong multi-agent setup

3.4. Lỗi credential trên từng nền tảng

4. Lỗi giới hạn tốc độ (429 Rate Limit)

4.1. Hiểu về 429 error

4.2. Chẩn đoán nhanh

4.3. Sửa nhanh

4.4. Cấu hình fallback model (khuyến nghị)

4.5. Bug đã biết: Không có exponential backoff (Issue #5159)

4.6. Bug đã biết: Cooldown toàn provider (Issue #5744)

4.7. Bug: Failover misclassification (Issue #10368)

5. Lỗi Pairing & Device (1008)

5.1. disconnected (1008): pairing required

5.2. unauthorized: gateway token missing

5.3. Quản lý paired devices

6. Lỗi kênh WhatsApp

6.1. QR code hết hạn / không scan được

6.2. WhatsApp bị stuck ở "logging in" sau khi đổi số

6.3. WhatsApp liên tục reconnect (reconnect loop)

6.4. Bị WhatsApp rate limit / ban tạm

6.5. Bug WhatsApp Allowlist Bypass (Issue #22599)

7. Lỗi kênh Telegram & Discord

7.1. Telegram bot không nhận tin nhắn

7.2. Telegram setMyCommands fails

7.3. Discord bot không nhận tin nhắn (close code 4014)

7.4. Xung đột tài nguyên khi chạy nhiều kênh cùng lúc

8. Lỗi Docker & Container

8.1. Container bị OOM-killed

8.2. Container khởi động lại mất config

8.3. Session file path must be within sessions directory

8.4. Lỗi quyền volume trong Docker

8.5. OPENCLAW_GATEWAY_TOKEN env variable override

9. Lỗi bảo mật (CVE-2026-25253)

9.1. Mô tả lỗ hổng

9.2. Cách vá ngay

9.3. Config bảo mật khuyến nghị

10. Lỗi cấu hình & Config

10.1. Config JSON bị corrupted

10.2. openclaw doctor xóa config keys

10.3. Legacy config key — key cũ không hoạt động

10.4. Lỗi Zod validation

11. Lỗi hiệu năng & Memory

11.1. Phản hồi chậm (15-30+ giây)

11.2. Memory quên liên tục

11.3. Disk usage cao

12. Lỗi nâng cấp từ ClawdBot / Moltbot

12.1. Service cũ vẫn chạy

12.2. Credential format không tương thích

12.3. Di chuyển sang máy mới

13. Lỗi Sandbox & Tool Execution

13.1. Docker not available hoặc sandbox container fails

13.2. Tool execution sai scope

13.3. Sandbox registry bị mất state

14. Lỗi Browser Control

14.1. Browser control không hoạt động

14.2. Failed to start Chrome CDP on port

15. Lỗi Model Failover

15.1. Fallback không trigger khi 429 (Issue #11972)

15.2. 502 Bad Gateway từ provider

16. Lỗi API & TypeError khi kết nối Provider

16.1. Cannot read properties of null (reading 'length')

16.2. Cannot read properties of undefined (reading 'replace')

16.3. Cannot read properties of undefined (reading '0')

16.4. Cannot read properties of undefined (reading 'includes')

16.5. Cannot read properties of undefined (reading 'padEnd') — Cron list crash

1.1. `openclaw: command not found`

1.3. Lỗi build `sharp` (native dependency)

2.2. Port conflict — `EADDRINUSE :::18789`

2.3. `Gateway not reachable` hoặc timeout

2.4. `gateway already running pid lock timeout`

5.1. `disconnected (1008): pairing required`

5.2. `unauthorized: gateway token missing`

7.2. Telegram `setMyCommands` fails

8.3. `Session file path must be within sessions directory`

10.2. `openclaw doctor` xóa config keys

13.1. `Docker not available` hoặc sandbox container fails

14.2. `Failed to start Chrome CDP on port`

16.1. `Cannot read properties of null (reading 'length')`

16.2. `Cannot read properties of undefined (reading 'replace')`

16.3. `Cannot read properties of undefined (reading '0')`

16.4. `Cannot read properties of undefined (reading 'includes')`

16.5. `Cannot read properties of undefined (reading 'padEnd')` — Cron list crash

16.6. `context_length_exceeded` — Vượt giới hạn context

16.7. `invalid beta flag` — Lỗi beta feature

16.8. `Connection error` / `ECONNREFUSED` / `ECONNRESET` / `ENOTFOUND`

16.10. `(no output)` — Model request fail không hiển thị lỗi

1.1. `openclaw: command not found`

1.3. Lỗi build `sharp` (native dependency)

2.2. Port conflict — `EADDRINUSE :::18789`

2.3. `Gateway not reachable` hoặc timeout

2.4. `gateway already running pid lock timeout`

5.1. `disconnected (1008): pairing required`

5.2. `unauthorized: gateway token missing`

7.2. Telegram `setMyCommands` fails

8.3. `Session file path must be within sessions directory`

10.2. `openclaw doctor` xóa config keys