Debug OpenClaw: log, lỗi thường gặp khi gateway treo hoặc agent không phản hồi

Tới một lúc nào đó gateway OpenClaw của bạn sẽ treo, agent không trả lời, channel disconnect, hoặc skill bỗng dưng "không tìm thấy". 90% trường hợp không phải bug nghiêm trọng, mà là một trong 6 lỗi điển hình: LLM quota hết, channel token expire, OOM, port conflict, skill load sai folder, hoặc WebSocket 1006 abnormal closure. Bài này là cheatsheet thực tế: chỗ check log, error message thật, root cause, và fix nhanh. In ra dán cạnh bàn càng tốt.

Map mental: gateway OpenClaw có những thành phần gì

Trước khi debug, biết cái mình đang debug gồm gì:

• Gateway daemon (Node.js): long-running process, listen 127.0.0.1:18789.
• Channel adapters: sub-process kết nối với Zalo/Telegram/Discord/Slack qua WebSocket hoặc long-polling.
• Skills: JS/TS module load từ ~/.openclaw/skills/, execute trong vm hoặc child process.
• LLM client: HTTP client gọi OpenAI/Anthropic/Mistral/local Ollama.
• Storage: SQLite hoặc files trong ~/.openclaw/data/.
• Web UI: serve trên cùng port 18789, route /ui.

Khi có lỗi, biết thành phần nào fail giúp giảm 50% thời gian. Log của OpenClaw có tag rõ [gateway], [channel:zalo], [skill:google_calendar], [llm:openai] - chú ý.

Lệnh debug nên thuộc lòng

Câu thần chú đầu tiên khi gateway "đột nhiên không work": openclaw doctor --deep --yes. Theo team OpenClaw, lệnh này resolve khoảng 80% issue mà không cần can thiệp gì. Mất 10 giây, không lý do bỏ qua.

Lỗi 1: WebSocket 1006 abnormal closure

Thấy trong app điện thoại hoặc web UI:

Gateway disconnected. Code 1006 (abnormal closure).
Reconnecting in 5s...

Hoặc trong log:

[gateway] WebSocket closed unexpectedly: code=1006 reason=

Root cause phổ biến (theo thứ tự xác suất):

1. Gateway daemon không chạy. Check: ps aux | grep openclaw. Fix: openclaw start.
2. Reverse proxy (Caddy/Nginx) timeout WebSocket. Caddy default OK; Nginx cần proxy_read_timeout 3600s.
3. Network gián đoạn: 4G chuyển sang Wifi, sleep mode. App tự reconnect, không cần làm gì.
4. OOM gateway bị kill: dmesg | grep -i killed xem có dòng "Out of memory: Killed process ... openclaw" không.

Fix nhanh:

openclaw status
# nếu Gateway: NOT RUNNING
openclaw start
openclaw logs --tail 50

Lỗi 2: EADDRINUSE port 18789 conflict

Khi start gateway thấy:

Error: listen EADDRINUSE: address already in use 127.0.0.1:18789
    at Server.setupListenHandle [as _listen2] (node:net:1815:16)

Có nghĩa port 18789 đã bị process khác chiếm - thường là một instance gateway cũ chưa exit sạch sau crash. Fix:

# Tìm process đang giữ port
sudo lsof -i :18789
# hoặc
sudo ss -tlnp | grep 18789

# Output kiểu: openclaw 12345 user ... TCP 127.0.0.1:18789
# Kill process zombie:
kill 12345
# Nếu không chịu chết:
kill -9 12345

# Start lại:
openclaw start

Lỗi 3: LLM rate-limit hoặc API key 401

Triệu chứng: agent reply "Sorry, I encountered an error" hoặc im lặng. Log gateway:

[llm:openai] Request failed: 429 Too Many Requests
[llm:openai] Retry-After: 60s
[llm:openai] Backoff and retry... (attempt 3/5)

Hoặc:

[llm:openai] Request failed: 401 Unauthorized
[llm:openai] Check OPENAI_API_KEY env or ~/.openclaw/.env

Fix 401: check API key đúng chưa, có expire không.

cat ~/.openclaw/.env | grep OPENAI_API_KEY
# Test key:
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  | head -20
# Phải trả JSON list models, không phải error.

Fix 429: bạn đang dùng quá rate limit của tier. Hoặc tier free vừa cạn $5 credit. Vào https://platform.openai.com/usage kiểm tra. Quick fix: switch tạm sang Anthropic hoặc local Ollama:

{
  "llm": {
    "default": "ollama",
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434",
        "model": "llama3.1:8b"
      }
    }
  }
}

Restart gateway, test lại.

Lỗi 4: Skill silently không load

Triệu chứng: bạn gọi @google_calendar list events nhưng agent reply "Tôi không có skill đó". Trong khi rõ ràng folder ~/.openclaw/skills/google_calendar/ tồn tại. Đây là lỗi xảo quyệt nhất vì không có error message.

Debug:

openclaw skills list
# Output:
# ✓ canvas       core
# ✓ browser      core
# ✗ google_calendar  FAILED: missing dependency "googleapis"
# ✓ shell        core

Đó là dấu hiệu skill load fail. Vào folder skill check:

cd ~/.openclaw/skills/google_calendar
cat package.json
ls node_modules/  # rỗng?
npm install
openclaw skills reload

Lỗi phổ biến hơn: skill nằm sai folder. OpenClaw load từ ~/.openclaw/skills/ chứ không phải ~/.config/openclaw/skills/ hay /opt/openclaw/skills/. Kiểm tra:

echo $OPENCLAW_HOME
# nếu không set, default là ~/.openclaw
ls ~/.openclaw/skills/
# skill phải nằm trực tiếp ở đây mỗi cái 1 folder

Lỗi 5: Channel disconnect liên tục (Zalo, Telegram)

Log:

[channel:zalo] Connection lost. Reconnecting in 10s...
[channel:zalo] Reconnect failed: token expired
[channel:zalo] Re-authentication required

Mỗi channel có pattern fail riêng:

• Zalo: token cookie expire sau 30 ngày hoặc khi bạn login Zalo ở thiết bị mới. Re-pair: openclaw channels pair zalo.
• Telegram: bot token không expire, nhưng nếu bạn revoke trong BotFather thì chết. Lấy token mới và update ~/.openclaw/.env -> TELEGRAM_BOT_TOKEN=....
• Discord: bot token có thể bị reset nếu Discord detect leak. Sinh lại trong Developer Portal.
• WhatsApp: dùng QR pairing, expire sau ~14 ngày offline. Re-pair bằng QR.
• Slack: OAuth token, refresh tự động nếu config đúng refresh_token.

Lệnh chung:

openclaw channels list
openclaw channels reconnect zalo
openclaw channels pair zalo  # nếu reconnect fail

Lỗi 6: OOM (Out of Memory) - gateway bị kill

Triệu chứng: gateway đang chạy ngon rồi đột nhiên biến mất. dmesg cho biết:

[Wed May 28 03:14:22 2026] Out of memory: Killed process 12345 (node) total-vm:3242MB, anon-rss:2891MB

Nguyên nhân thường thấy:

1. Context length đẩy lên LLM quá dài, vài MB JSON, gateway hold buffer trong RAM.
2. Memory leak trong skill custom - thường do quên close stream/handle.
3. Whisper local STT load model lớn (medium, large) ngốn 2-3GB.
4. Quá nhiều canvas session persist - mỗi session ~30MB.

Fix ngắn hạn:

# Restart gateway
openclaw start

# Limit context length
# ~/.openclaw/config.json
{
  "llm": {
    "maxContextTokens": 100000  // thay vì để mặc định 200k
  }
}

# Switch Whisper model nhỏ hơn
# voice.json: "model": "tiny" hoặc "base" thay vì "small"

Fix dài hạn: upgrade RAM. VPS 50 (4GB) đủ chạy gateway + 2-3 skill nhẹ. Khi enable voice STT local + canvas streaming + 4-5 channel, leo lên 5-6GB - cần VPS 80 (6GB) hoặc VPS 160 (8GB).

Lỗi 7: Upgrade gateway xong gãy hết

Triệu chứng: vừa npm update -g @openclaw/cli hoặc openclaw self-update, giờ start không lên.

Error: Cannot find module 'better-sqlite3'
SyntaxError: Unexpected token ?? in ~/.openclaw/skills/foo/index.js

Fix:

# Xem version cũ vs mới
openclaw --version
cat ~/.openclaw/version.lock  # nếu có

# Rebuild native modules
cd $(npm root -g)/@openclaw/cli
npm rebuild

# Nếu vẫn fail, downgrade
npm install -g @openclaw/cli@

# Restore skill nếu skill broken
cd ~/.openclaw/skills/foo
git log  # nếu skill là git repo
git checkout HEAD~1

Khi nào nên gửi issue lên GitHub

Trước khi tạo issue:

1. Chạy openclaw doctor --deep --yes - thường tự fix.
2. Update lên latest: npm install -g @openclaw/cli@latest.
3. Search GitHub issues - 70% lỗi đã có người báo.
4. Collect log: openclaw logs --tail 500 > /tmp/claw.log, redact API key trước khi paste.

Template issue tốt:

**Version:** openclaw 1.x.y, Node v24.x.y, Ubuntu 24.04
**Setup:** Self-hosted VPS, gateway behind Caddy, Whisper local STT
**Steps to reproduce:**
1. ...
2. ...
**Expected:** ...
**Actual:** [paste log]
**Doctor output:** [paste openclaw doctor]

Bảng cheatsheet "lỗi này -> fix này"

Phòng bệnh hơn chữa

Mấy thói quen giúp gateway sống lâu khỏe mạnh:

• Systemd user service: tạo unit ~/.config/systemd/user/openclaw.service, Restart=on-failure. Crash là restart, không phải mỗi sáng mở terminal kiểm tra.
• Monitoring đơn giản: cron mỗi 5 phút curl -sf -u user:pass https://claw.example.com/health || notify-slack.
• Log rotation: ~/.openclaw/logs/ tăng nhanh nếu debug verbose. Logrotate config size 100MB rotate weekly.
• Backup config: push ~/.openclaw/config.json + .env (đã encrypt) lên private git.
• Update theo lịch: không update giữa tuần làm việc. Cuối tuần, backup, update, smoke test.

Đọc thêm về setup ban đầu trong bài giới thiệu OpenClaw self-host trên VPS. Nếu VPS hiện tại 2GB RAM đang nghẹt thở vì gateway, xem qua các cấu hình VPS cho vibe coder để upgrade hợp lý.

Tóm lại

Debug OpenClaw không khác debug bất kỳ Node.js daemon nào - khác duy nhất ở chỗ skill là code chạy với quyền user của bạn, nên một lỗi trong skill có thể trigger OOM, hang gateway, hay ăn quota LLM. Có cheatsheet thuộc lòng + openclaw doctor --deep --yes là first response, 90% case bạn không cần mở Google. Phần còn lại là kinh nghiệm tích lũy - lưu lại mỗi lần fix một lỗi mới để lần sau xử lý trong 30 giây.