Troubleshooting 🔧

Khi OpenClaw gặp vấn đề, đây là cách khắc phục.

Bắt đầu với phần 60 giây đầu tiên trong FAQ nếu các bạn chỉ cần công thức chẩn đoán nhanh. Trang này đi sâu hơn về các lỗi runtime và chẩn đoán.

Phím tắt theo Provider: /channels/troubleshooting

Status & Diagnostics

Các lệnh chẩn đoán nhanh (theo thứ tự):

LệnhThông tin cung cấpKhi nào dùng
openclaw statusTóm tắt local: OS + update, khả năng kết nối/mode của gateway, service, agents/sessions, trạng thái config providerKiểm tra đầu tiên, tổng quan nhanh
openclaw status --allChẩn đoán local đầy đủ (read-only, có thể paste, khá an toàn) bao gồm log tailKhi cần chia sẻ báo cáo debug
openclaw status --deepChạy health checks của gateway (bao gồm provider probes; cần gateway có thể kết nối)Khi “configured” không có nghĩa là “working”
openclaw gateway probeGateway discovery + khả năng kết nối (local + remote targets)Khi nghi ngờ đang probe nhầm gateway
openclaw channels status --probeHỏi gateway đang chạy về trạng thái channel (và tùy chọn probes)Khi gateway kết nối được nhưng channels gặp vấn đề
openclaw gateway statusTrạng thái supervisor (launchd/systemd/schtasks), runtime PID/exit, lỗi gateway gần nhấtKhi service “trông có vẻ loaded” nhưng không chạy gì
openclaw logs --followLive logs (tín hiệu tốt nhất cho các vấn đề runtime)Khi cần lý do lỗi thực sự

Chia sẻ output: ưu tiên openclaw status --all (nó che token). Nếu paste openclaw status, hãy cân nhắc set OPENCLAW_SHOW_SECRETS=0 trước (token previews).

Xem thêm: Health checks và Logging.

Common Issues

No API key found for provider “anthropic”

Điều này có nghĩa là auth store của agent trống hoặc thiếu credentials Anthropic. Auth là per agent, nên agent mới sẽ không kế thừa keys của main agent.

Các cách khắc phục:

  • Chạy lại onboarding và chọn Anthropic cho agent đó.
  • Hoặc paste setup-token trên gateway host: 
    openclaw models auth setup-token --provider anthropic
  • Hoặc copy auth-profiles.json từ thư mục main agent sang thư mục agent mới.

Xác minh:

openclaw models status

OAuth token refresh failed (Anthropic Claude subscription)

Điều này có nghĩa là Anthropic OAuth token đã lưu hết hạn và refresh thất bại. Nếu các bạn đang dùng Claude subscription (không có API key), cách khắc phục đáng tin cậy nhất là chuyển sang Claude Code setup-token và paste nó trên gateway host.

Khuyến nghị (setup-token):

# Chạy trên gateway host (paste setup-token)
openclaw models auth setup-token --provider anthropic
openclaw models status

Nếu các bạn đã tạo token ở nơi khác:

openclaw models auth paste-token --provider anthropic
openclaw models status

Chi tiết hơn: Anthropic và OAuth.

Control UI fails on HTTP (“device identity required” / “connect failed”)

Nếu các bạn mở dashboard qua plain HTTP (ví dụ http://<lan-ip>:18789/ hoặc http://<tailscale-ip>:18789/), browser chạy trong non-secure context và chặn WebCrypto, nên device identity không thể được tạo.

Khắc phục:

  • Ưu tiên HTTPS qua Tailscale Serve.
  • Hoặc mở locally trên gateway host: http://127.0.0.1:18789/.
  • Nếu phải ở trên HTTP, bật gateway.controlUi.allowInsecureAuth: true và dùng gateway token (chỉ token; không có device identity/pairing). Xem Control UI.

CI Secrets Scan Failed

Điều này có nghĩa là detect-secrets tìm thấy candidates mới chưa có trong baseline. Làm theo Secret scanning.

Service Installed but Nothing is Running

Nếu gateway service đã cài nhưng process thoát ngay lập tức, service có thể trông “loaded” trong khi không có gì chạy.

Kiểm tra:

openclaw gateway status
openclaw doctor

Doctor/service sẽ hiển thị trạng thái runtime (PID/last exit) và gợi ý log.

Logs:

  • Ưu tiên: openclaw logs --follow
  • File logs (luôn luôn): /tmp/openclaw/openclaw-YYYY-MM-DD.log (hoặc logging.file đã config)
  • macOS LaunchAgent (nếu đã cài): $OPENCLAW_STATE_DIR/logs/gateway.log và gateway.err.log
  • Linux systemd (nếu đã cài): journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
  • Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST

Bật thêm logging:

  • Tăng chi tiết file log (persisted JSONL): 
    { "logging": { "level": "debug" } }
  • Tăng console verbosity (chỉ TTY output): 
    { "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } }
  • Mẹo nhanh: --verbose chỉ ảnh hưởng console output. File logs vẫn được kiểm soát bởi logging.level.

Xem /logging để có tổng quan đầy đủ về formats, config và access.

”Gateway start blocked: set gateway.mode=local”

Điều này có nghĩa là config tồn tại nhưng gateway.mode chưa set (hoặc không phải local), nên Gateway từ chối khởi động.

Khắc phục (khuyến nghị):

  • Chạy wizard và set Gateway run mode thành Local: 
    openclaw configure
  • Hoặc set trực tiếp: 
    openclaw config set gateway.mode local

Nếu các bạn muốn chạy remote Gateway thay vì:

  • Set remote URL và giữ gateway.mode=remote: 
    openclaw config set gateway.mode remote
openclaw config set gateway.remote.url "wss://gateway.example.com"

Chỉ ad-hoc/dev: pass --allow-unconfigured để start gateway mà không cần gateway.mode=local.

Chưa có config file? Chạy openclaw setup để tạo starter config, sau đó chạy lại gateway.

Service Environment (PATH + runtime)

Gateway service chạy với minimal PATH để tránh shell/manager cruft:

  • macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
  • Linux: /usr/local/bin, /usr/bin, /bin

Điều này cố ý loại trừ version managers (nvm/fnm/volta/asdf) và package managers (pnpm/npm) vì service không load shell init của các bạn. Runtime variables như DISPLAY nên nằm trong ~/.openclaw/.env (được load sớm bởi gateway). Exec chạy trên host=gateway merge login-shell PATH của các bạn vào exec environment, nên thiếu tools thường có nghĩa là shell init không export chúng (hoặc set tools.exec.pathPrepend). Xem /tools/exec.

WhatsApp + Telegram channels yêu cầu Node; Bun không được hỗ trợ. Nếu service được cài với Bun hoặc version-managed Node path, chạy openclaw doctor để migrate sang system Node install.

Skill missing API key in sandbox

Triệu chứng: Skill hoạt động trên host nhưng thất bại trong sandbox với missing API key.

Tại sao: sandboxed exec chạy bên trong Docker và không kế thừa host process.env.

Khắc phục:

  • set agents.defaults.sandbox.docker.env (hoặc per-agent agents.list[].sandbox.docker.env)
  • hoặc bake key vào custom sandbox image của các bạn
  • sau đó chạy openclaw sandbox recreate --agent <id> (hoặc --all)

Service Running but Port Not Listening

Nếu service báo running nhưng không có gì lắng nghe trên gateway port, Gateway có thể đã từ chối bind.

“running” có nghĩa là gì ở đây

  • Runtime: running có nghĩa là supervisor của các bạn (launchd/systemd/schtasks) nghĩ process đang sống.
  • RPC probe có nghĩa là CLI thực sự có thể kết nối tới gateway WebSocket và gọi status.
  • Luôn tin tưởng Probe target: + Config (service): là các dòng “what did we actually try?”.

Kiểm tra:

  • gateway.mode phải là local cho openclaw gateway và service.
  • Nếu các bạn set gateway.mode=remote, CLI defaults sang remote URL. Service vẫn có thể chạy locally, nhưng CLI có thể đang probe nhầm chỗ. Dùng openclaw gateway status để xem resolved port + probe target của service (hoặc pass --url).
  • openclaw gateway status và openclaw doctor hiển thị last gateway error từ logs khi service trông đang chạy nhưng port đóng.
  • Non-loopback binds (lan/tailnet/custom, hoặc auto khi loopback không khả dụng) yêu cầu auth: gateway.auth.token (hoặc OPENCLAW_GATEWAY_TOKEN).
  • gateway.remote.token chỉ dành cho remote CLI calls; nó không bật local auth.
  • gateway.token bị bỏ qua; dùng gateway.auth.token.

Nếu openclaw gateway status hiển thị config mismatch

  • Config (cli): ... và Config (service): ... thường phải khớp nhau.
  • Nếu không khớp, các bạn gần như chắc chắn đang edit một config trong khi service đang chạy config khác.
  • Khắc phục: chạy lại openclaw gateway install --force từ cùng --profile / OPENCLAW_STATE_DIR mà các bạn muốn service sử dụng.

Nếu openclaw gateway status báo service config issues

  • Supervisor config (launchd/systemd/schtasks) thiếu defaults hiện tại.
  • Khắc phục: chạy openclaw doctor để update nó (hoặc openclaw gateway install --force để rewrite hoàn toàn).

Nếu Last gateway error: đề cập “refusing to bind … without auth”

  • Các bạn đã set gateway.bind sang non-loopback mode (lan/tailnet/custom, hoặc auto khi loopback không khả dụng) nhưng không config auth.
  • Khắc phục: set gateway.auth.mode + gateway.auth.token (hoặc export OPENCLAW_GATEWAY_TOKEN) và restart service.

Nếu openclaw gateway status nói bind=tailnet nhưng không tìm thấy tailnet interface

  • Gateway đã cố bind tới Tailscale IP (100.64.0.0/10) nhưng không phát hiện được trên host.
  • Khắc phục: bật Tailscale trên máy đó (hoặc đổi gateway.bind sang loopback/lan).

Nếu Probe note: nói probe dùng loopback

  • Đó là điều bình thường cho bind=lan: gateway lắng nghe trên 0.0.0.0 (tất cả interfaces), và loopback vẫn nên kết nối được locally.
  • Với remote clients, dùng LAN IP thực (không phải 0.0.0.0) cộng port, và đảm bảo auth đã được config.

Address Already in Use (Port 18789)

Điều này có nghĩa là có thứ gì đó đang lắng nghe trên gateway port.

Kiểm tra:

openclaw gateway status

Nó sẽ hiển thị listener(s) và nguyên nhân có thể (gateway đã chạy, SSH tunnel). Nếu cần, dừng service hoặc chọn port khác.

Extra Workspace Folders Detected

Nếu các bạn upgrade từ bản cài cũ, có thể vẫn còn ~/openclaw trên disk. Nhiều workspace directories có thể gây nhầm lẫn về auth hoặc state drift vì chỉ một workspace đang active.

Khắc phục: giữ một active workspace duy nhất và archive/xóa phần còn lại. Xem Agent workspace.

Main chat running in a sandbox workspace

Triệu chứng: pwd hoặc file tools hiển thị ~/.openclaw/sandboxes/... mặc dù các bạn mong đợi host workspace.

Tại sao: agents.defaults.sandbox.mode: "non-main" dựa vào session.mainKey (mặc định "main"). Group/channel sessions dùng keys riêng của chúng, nên chúng được coi là non-main và nhận sandbox workspaces.

Các cách khắc phục:

  • Nếu muốn host workspaces cho một agent: set agents.list[].sandbox.mode: "off".
  • Nếu muốn truy cập host workspace bên trong sandbox: set workspaceAccess: "rw" cho agent đó.

”Agent was aborted”

Agent bị ngắt giữa chừng response.

Nguyên nhân:

  • User gửi stop, abort, esc, wait, hoặc exit
  • Timeout vượt quá
  • Process crashed

Khắc phục: Chỉ cần gửi tin nhắn khác. Session tiếp tục.

”Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5”

OpenClaw cố ý từ chối các model cũ/không an toàn (đặc biệt là những model dễ bị prompt injection hơn). Nếu thấy lỗi này, tên model không còn được hỗ trợ nữa.

Khắc phục:

  • Chọn model mới nhất cho provider và update config hoặc model alias.
  • Nếu không chắc models nào khả dụng, chạy openclaw models list hoặc openclaw models scan và chọn một model được hỗ trợ.
  • Kiểm tra gateway logs để biết lý do lỗi chi tiết.

Xem thêm: Models CLI và Model providers.

Messages Not Triggering

Kiểm tra 1: Sender có trong allowlist không?

openclaw status

Tìm AllowFrom: ... trong output.

Kiểm tra 2: Với group chats, có yêu cầu mention không?

# Tin nhắn phải khớp mentionPatterns hoặc explicit mentions; defaults nằm trong channel groups/guilds.
# Multi-agent: `agents.list[].groupChat.mentionPatterns` ghi đè global patterns.
grep -n "agents\\|groupChat\\|mentionPatterns\\|channels\\.whatsapp\\.groups\\|channels\\.telegram\\.groups\\|channels\\.imessage\\.groups\\|channels\\.discord\\.guilds" \
  "${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json}"

Kiểm tra 3: Kiểm tra logs

openclaw logs --follow
# hoặc nếu muốn filters nhanh:
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"

Pairing Code Not Arriving

Nếu dmPolicy là pairing, unknown senders sẽ nhận code và tin nhắn của họ bị bỏ qua cho đến khi được approve.

Kiểm tra 1: Có pending request nào đang chờ không?

openclaw pairing list <channel>

Pending DM pairing requests được giới hạn ở 3 per channel theo mặc định. Nếu list đầy, requests mới sẽ không tạo code cho đến khi một request được approve hoặc hết hạn.

Kiểm tra 2: Request có được tạo nhưng không gửi reply?

openclaw logs --follow | grep "pairing request"

Kiểm tra 3: Xác nhận dmPolicy không phải open/allowlist cho channel đó.

Image + Mention Not Working

Vấn đề đã biết: Khi các bạn gửi ảnh với CHỈ mention (không có text khác), WhatsApp đôi khi không bao gồm mention metadata.

Workaround: Thêm text với mention:

  • ❌ @openclaw + image
  • ✅ @openclaw check this + image

Session Not Resuming

Kiểm tra 1: Session file có ở đó không?

ls -la ~/.openclaw/agents/<agentId>/sessions/

Kiểm tra 2: Reset window có quá ngắn không?

{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 10080 // 7 ngày
    }
  }
}

Kiểm tra 3: Có ai gửi /new, /reset, hoặc reset trigger không?

Agent Timing Out

Timeout mặc định là 30 phút. Với các tác vụ dài:

{
  "reply": {
    "timeoutSeconds": 3600 // 1 giờ
  }
}

Hoặc dùng process tool để background các lệnh dài.

WhatsApp Disconnected

# Kiểm tra local status (creds, sessions, queued events)
openclaw status
# Probe gateway + channels đang chạy (WA connect + Telegram + Discord APIs)
openclaw status --deep

# Xem các connection events gần đây
openclaw logs --limit 200 | grep "connection\\|disconnect\\|logout"

Khắc phục: Thường tự động reconnect khi Gateway đang chạy. Nếu bị stuck, restart Gateway process (theo cách các bạn supervise nó), hoặc chạy thủ công với verbose output:

openclaw gateway --verbose

Nếu bị logged out / unlinked:

openclaw channels logout
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials" # nếu logout không thể xóa sạch mọi thứ
openclaw channels login --verbose       # re-scan QR

Media Send Failing

Kiểm tra 1: File path có hợp lệ không?

ls -la /path/to/your/image.jpg

Kiểm tra 2: Có quá lớn không?

  • Images: max 6MB
  • Audio/Video: max 16MB
  • Documents: max 100MB

Kiểm tra 3: Kiểm tra media logs

grep "media\\|fetch\\|download" "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | tail -20

High Memory Usage

OpenClaw giữ conversation history trong memory.

Khắc phục: Restart định kỳ hoặc set session limits:

{
  "session": {
    "historyLimit": 100 // Max messages để giữ
  }
}

Common troubleshooting

”Gateway won’t start — configuration invalid”

OpenClaw giờ từ chối start khi config chứa unknown keys, malformed values, hoặc invalid types. Điều này là cố ý để đảm bảo an toàn.

Khắc phục với Doctor:

openclaw doctor
openclaw doctor --fix

Lưu ý:

  • openclaw doctor báo cáo mọi invalid entry.
  • openclaw doctor --fix áp dụng migrations/repairs và rewrite config.
  • Các lệnh diagnostic như openclaw logs, openclaw health, openclaw status, openclaw gateway status, và openclaw gateway probe vẫn chạy ngay cả khi config invalid.

”All models failed” — nên kiểm tra gì trước?

  • Credentials có cho provider(s) đang được thử (auth profiles + env vars).
  • Model routing: xác nhận agents.defaults.model.primary và fallbacks là các models các bạn có thể truy cập.
  • Gateway logs trong /tmp/openclaw/… để biết provider error chính xác.
  • Model status: dùng /model status (chat) hoặc openclaw models status (CLI).

Mình đang chạy trên WhatsApp number cá nhân — tại sao self-chat lạ?

Bật self-chat mode và allowlist số của chính mình:

{
  channels: {
    whatsapp: {
      selfChatMode: true,
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123"],
    },
  },
}

Xem WhatsApp setup.

WhatsApp logged me out. Làm sao re‑auth?

Chạy lại lệnh login và scan QR code:

openclaw channels login

Build errors trên main — đường khắc phục chuẩn là gì?

  1. git pull origin main && pnpm install
  2. openclaw doctor
  3. Kiểm tra GitHub issues hoặc Discord
  4. Workaround tạm thời: checkout commit cũ hơn

npm install fails (allow-build-scripts / missing tar or yargs). Giờ sao?

Nếu các bạn chạy từ source, dùng package manager của repo: pnpm (ưu tiên). Repo khai báo packageManager: "pnpm@…".

Recovery điển hình:

git status   # đảm bảo đang ở repo root
pnpm install
pnpm build
openclaw doctor
openclaw gateway restart

Tại sao: pnpm là package manager được config cho repo này.

Làm sao chuyển giữa git installs và npm installs?

Dùng website installer và chọn install method với flag. Nó upgrades tại chỗ và rewrites gateway service để trỏ tới install mới.

Chuyển sang git install:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard

Chuyển sang npm global:

curl -fsSL https://openclaw.ai/install.sh | bash

Lưu ý:

  • Git flow chỉ rebase nếu repo sạch. Commit hoặc stash changes trước.
  • Sau khi chuyển, chạy: 
    openclaw doctor
openclaw gateway restart

Telegram block streaming không tách text giữa các tool calls. Tại sao?

Block streaming chỉ gửi completed text blocks. Các lý do thường gặp khi thấy single message:

  • agents.defaults.blockStreamingDefault vẫn là "off".
  • channels.telegram.blockStreaming được set thành false.
  • channels.telegram.streamMode là partial hoặc block và draft streaming đang active (private chat + topics). Draft streaming vô hiệu hóa block streaming trong trường hợp đó.
  • minChars / coalesce settings của các bạn quá cao, nên chunks bị merged.
  • Model phát ra một large text block (không có mid‑reply flush points).

Checklist khắc phục:

  1. Đặt block streaming settings dưới agents.defaults, không phải root.
  2. Set channels.telegram.streamMode: "off" nếu muốn real multi‑message block replies.
  3. Dùng smaller chunk/coalesce thresholds khi debugging.

Xem Streaming.

Discord không reply trong server của mình ngay cả với requireMention: false. Tại sao?

requireMention chỉ kiểm soát mention‑gating sau khi channel pass allowlists. Theo mặc định channels.discord.groupPolicy là allowlist, nên guilds phải được explicitly enabled. Nếu các bạn set channels.discord.guilds.<guildId>.channels, chỉ các channels được liệt kê mới được phép; bỏ qua nó để cho phép tất cả channels trong guild.

Checklist khắc phục:

  1. Set channels.discord.groupPolicy: "open" hoặc thêm guild allowlist entry (và tùy chọn channel allowlist).
  2. Dùng numeric channel IDs trong channels.discord.guilds.<guildId>.channels.
  3. Đặt requireMention: false dưới channels.discord.guilds (global hoặc per‑channel). Top‑level channels.discord.requireMention không phải là supported key.
  4. Đảm bảo bot có Message Content Intent và channel permissions.
  5. Chạy openclaw channels status --probe để có audit hints.

Docs: Discord, Channels troubleshooting.

Cloud Code Assist API error: invalid tool schema (400). Giờ sao?

Đây gần như luôn là vấn đề tool schema compatibility. Cloud Code Assist endpoint chấp nhận một strict subset của JSON Schema. OpenClaw scrubs/normalizes tool schemas trong main hiện tại, nhưng fix chưa có trong release cuối (tính đến ngày 13 tháng 1 năm 2026).

Checklist khắc phục:

  1. Update OpenClaw:
    • Nếu có thể chạy từ source, pull main và restart gateway.
    • Nếu không, đợi release tiếp theo có schema scrubber.
  2. Tránh unsupported keywords như anyOf/oneOf/allOf, patternProperties, additionalProperties, minLength, maxLength, format, v.v.
  3. Nếu định nghĩa custom tools, giữ top‑level schema là type: "object" với properties và simple enums.

Xem Tools và TypeBox schemas.

macOS Specific Issues

App Crashes when Granting Permissions (Speech/Mic)

Nếu app biến mất hoặc hiển thị “Abort trap 6” khi các bạn click “Allow” trên privacy prompt:

Khắc phục 1: Reset TCC Cache

tccutil reset All bot.molt.mac.debug

Khắc phục 2: Force New Bundle ID Nếu resetting không hiệu quả, đổi BUNDLE_ID trong scripts/package-mac-app.sh (ví dụ thêm suffix .test) và rebuild. Điều này buộc macOS coi nó như app mới.

Gateway stuck on “Starting…”

App kết nối tới local gateway trên port 18789. Nếu nó stuck:

Khắc phục 1: Stop supervisor (ưu tiên) Nếu gateway được supervised bởi launchd, killing PID sẽ chỉ respawn nó. Stop supervisor trước:

openclaw gateway status
openclaw gateway stop
# Hoặc: launchctl bootout gui/$UID/bot.molt.gateway (thay bằng bot.molt.<profile>; legacy com.openclaw.* vẫn hoạt động)

Khắc phục 2: Port is busy (tìm listener)

lsof -nP -iTCP:18789 -sTCP:LISTEN

Nếu là unsupervised process, thử graceful stop trước, sau đó leo thang:

kill -TERM <PID>
sleep 1
kill -9 <PID> # phương sách cuối cùng

Khắc phục 3: Kiểm tra CLI install Đảm bảo global openclaw CLI đã cài và khớp với app version:

openclaw --version
npm install -g openclaw@<version>

Debug Mode

Bật verbose logging:

# Bật trace logging trong config:
#   ${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json} -> { logging: { level: "trace" } }
#
# Sau đó chạy verbose commands để mirror debug output ra stdout:
openclaw gateway --verbose
openclaw channels login --verbose

Log Locations

LogVị trí
Gateway file logs (structured)/tmp/openclaw/openclaw-YYYY-MM-DD.log (hoặc logging.file)
Gateway service logs (supervisor)macOS: $OPENCLAW_STATE_DIR/logs/gateway.log + gateway.err.log (mặc định: ~/.openclaw/logs/...; profiles dùng ~/.openclaw-<profile>/logs/...)
Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST
Session files$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/
Media cache$OPENCLAW_STATE_DIR/media/
Credentials$OPENCLAW_STATE_DIR/credentials/

Health Check

# Supervisor + probe target + config paths
openclaw gateway status
# Bao gồm system-level scans (legacy/extra services, port listeners)
openclaw gateway status --deep

# Gateway có thể kết nối được không?
openclaw health --json
# Nếu thất bại, chạy lại với connection details:
openclaw health --verbose

# Có gì đang lắng nghe trên default port không?
lsof -nP -iTCP:18789 -sTCP:LISTEN

# Hoạt động gần đây (RPC log tail)
openclaw logs --follow
# Fallback nếu RPC down
tail -20 /tmp/openclaw/openclaw-*.log

Reset Everything

Phương án hạt nhân:

openclaw gateway stop
# Nếu đã cài service và muốn clean install:
# openclaw gateway uninstall

trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
openclaw channels login         # re-pair WhatsApp
openclaw gateway restart           # hoặc: openclaw gateway

⚠️ Điều này mất tất cả sessions và yêu cầu re-pairing WhatsApp.

Getting Help

  1. Kiểm tra logs trước: /tmp/openclaw/ (mặc định: openclaw-YYYY-MM-DD.log, hoặc logging.file đã config)
  2. Tìm existing issues trên GitHub
  3. Mở issue mới với:
    • OpenClaw version
    • Relevant log snippets
    • Steps để reproduce
    • Config của các bạn (che secrets!)

“Have you tried turning it off and on again?” — Mọi người IT từng nói

🦞🔧

Browser Not Starting (Linux)

Nếu thấy "Failed to start Chrome CDP on port 18800":

Nguyên nhân có thể nhất: Snap-packaged Chromium trên Ubuntu.

Khắc phục nhanh: Cài Google Chrome thay vì:

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

Sau đó set trong config:

{
  "browser": {
    "executablePath": "/usr/bin/google-chrome-stable"
  }
}

Hướng dẫn đầy đủ: Xem browser-linux-troubleshooting