10. Troubleshooting và Tips

Overview

Ngay cả với thiết lập cẩn thận, bạn có thể gặp phải các vấn đề khi sử dụng OpenClaw. Hướng dẫn này cung cấp các bước xử lý sự cố toàn diện và các mẹo thực tế để giải quyết các vấn đề thường gặp và tối ưu hóa hiệu suất.

Công cụ Chẩn đoán

Chẩn đoán Tích hợp

bash

# Kiểm tra sức khỏe toàn diện
openclaw doctor

# Thông tin hệ thống chi tiết
openclaw doctor --verbose

# Kiểm tra thành phần cụ thể
openclaw doctor --gateway
openclaw doctor --channels
openclaw doctor --database
openclaw doctor --security

Chế độ Gỡ lỗi

bash

# Bật ghi nhật ký gỡ lỗi
openclaw config set log.level debug

# Chạy với đầu ra gỡ lỗi
openclaw gateway --debug --verbose

# Gỡ lỗi kênh cụ thể
openclaw debug channel telegram --trace

# Debug AI responses
openclaw debug agent --trace --save debug.json

Lệnh Giám sát

bash

# Giám sát thời gian thực
openclaw monitor --refresh 1s

# Sử dụng tài nguyên
openclaw stats --format table

# Số liệu hiệu suất
openclaw metrics --period 1h

# Phân tích lỗi
openclaw errors --last 100 --group

Các Vấn đề Thường gặp và Giải pháp

1. Vấn đề Cài đặt

Phiên bản Node.js Không tương thích

Problem:

Error: OpenClaw requires Node.js >= 22.12.0
Current version: 18.17.0

Solution:

bash

Sử dụng nvm (khuyến nghị)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22

# Verify
node --version  # Should show v22.x.x

Từ chối Quyền truy cập

Problem:

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/openclaw'

Solution:

bash

Tùy chọn 1: Sửa quyền npm
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Tùy chọn 2: Dùng nvm (tránh vấn đề quyền)
nvm install 22
nvm use 22
npm install -g openclaw

Tùy chọn 3: Dùng pnpm
npm install -g pnpm
pnpm add -g openclaw

2. Vấn đề Gateway

Cổng đã được sử dụng

Problem:

Error: Port 18789 already in use

Solution:

bash

Tìm tiến trình đang sử dụng cổng
lsof -i :18789
# or on Windows
netstat -ano | findstr :18789

Kết thúc tiến trình
kill -9 <PID>
# or on Windows
taskkill /PID <PID> /F

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

Gateway Không khởi động

Problem:

Gateway failed to start: Configuration validation failed

Solution:

bash

Xác thực cấu hình
openclaw config validate

Kiểm tra lỗi cú pháp
cat ~/.openclaw/openclaw.json | jq .

Đặt lại về mặc định
openclaw config reset
openclaw onboard --skip-channels

# Check logs
tail -f ~/.openclaw/logs/gateway.log

Vấn đề Kết nối WebSocket

Problem:

WebSocket connection failed: 401 Unauthorized

Solution:

bash

# Check authentication
openclaw config show gateway.auth

Kiểm tra token
curl -H "X-OpenClaw-Token: your-token" \
     http://localhost:18789/health

Đặt lại token
openclaw config set gateway.auth.token $(openssl rand -hex 32)

Tắt tạm thời xác thực (để kiểm tra)
openclaw config set gateway.auth.mode "none"

3. Vấn đề Kênh

WhatsApp Mất kết nối

Problem:

WhatsApp: Connection lost, attempting to reconnect...

Solution:

bash

Kiểm tra trạng thái WhatsApp
openclaw channels status whatsapp

Liên kết lại WhatsApp
openclaw channels unlink whatsapp
openclaw channels login whatsapp

Kiểm tra thông tin xác thực
ls -la ~/.openclaw/credentials/whatsapp/

Xóa phiên bị hỏng
rm -rf ~/.openclaw/credentials/whatsapp/session*
openclaw channels login whatsapp

Telegram Bot Không phản hồi

Problem:

Telegram: Bot not receiving messages

Solution:

bash

Xác minh bot token
curl https://api.telegram.org/bot<TOKEN>/getMe

Kiểm tra webhook
curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo

Xóa webhook (chuyển sang polling)
curl https://api.telegram.org/bot<TOKEN>/deleteWebhook

Khởi động lại kênh
openclaw channels restart telegram

Kiểm tra giới hạn tốc độ
openclaw debug channel telegram --show-rate-limits

Slack App Thiếu Quyền

Problem:

Slack: Missing required scopes

Solution:

bash

Kiểm tra các phạm vi cần thiết
openclaw slack check-scopes

Cài đặt lại với các phạm vi đúng
openclaw slack install --scopes "app_mentions:read,chat:write,channels:history"

Cập nhật quyền ứng dụng
Vào api.slack.com/apps
Chọn ứng dụng của bạn
Đi đến OAuth & Permissions
Thêm các phạm vi còn thiếu
Cài đặt lại ứng dụng

Kiểm tra kết nối
openclaw test channel slack

4. Vấn đề AI/LLM

API Key Không hợp lệ

Problem:

Anthropic: 401 Invalid API key

Solution:

bash

Kiểm tra API key
openclaw config show agent.apiKey

Kiểm tra API key
curl -X POST https://api.anthropic.com/v1/messages \
     -H "x-api-key: your-key" \
     -H "Content-Type: application/json" \
     -d '{"model": "claude-3-opus-20240229", "messages": [{"role": "user", "content": "test"}]}'

Cập nhật API key
openclaw config set agent.apiKey "sk-ant-xxx"

Sử dụng biến môi trường
export ANTHROPIC_API_KEY="sk-ant-xxx"

Model Không khả dụng

Problem:

Error: Model claude-3-opus-20240229 not found

Solution:

bash

Liệt kê các model khả dụng
openclaw models list

Cập nhật sang model hợp lệ
openclaw config set agent.model "claude-3-sonnet-20240229"

Kiểm tra tính khả dụng của model
openclaw models check claude-3-opus-20240229

Sử dụng model dự phòng
openclaw config set agent.fallback "claude-3-haiku-20240307"

Thời gian Phản hồi Chậm

Problem:

Phản hồi AI mất >30 giây

Solution:

bash

Kiểm tra mức độ suy nghĩ
openclaw config show agent.thinking

Giảm suy nghĩ để phản hồi nhanh hơn
openclaw config set agent.thinking low

Giảm số token tối đa
openclaw config set agent.maxTokens 1000

Kiểm tra độ trễ mạng
ping api.anthropic.com

Sử dụng model nhanh hơn
openclaw config set agent.model "claude-3-haiku-20240307"

Bật streaming
openclaw config set agent.streaming true

5. Vấn đề Hiệu suất

Sử dụng Bộ nhớ Cao

Problem:

Sử dụng bộ nhớ: 8GB / 16GB (50%)

Solution:

bash

Kiểm tra cái gì đang sử dụng bộ nhớ
openclaw debug memory

Giảm lịch sử phiên
openclaw config set sessions.maxHistory 50

Bật cắt tỉa ngữ cảnh
openclaw config set agent.contextPruning true

Giảm số phiên đồng thời
openclaw config set gateway.maxConcurrentSessions 5

Khởi động lại để xóa bộ nhớ
openclaw restart

Truy vấn Cơ sở dữ liệu Chậm

Problem:

Truy vấn cơ sở dữ liệu mất 5.2 giây

Solution:

bash

Bật ghi nhật ký truy vấn
openclaw config set database.logQueries true

Phân tích truy vấn chậm
openclaw debug database --slow-queries

Thêm các chỉ mục
psql $DATABASE_URL -c "CREATE INDEX CONCURRENTLY idx_messages_created ON messages(created_at);"

Dọn dẹp cơ sở dữ liệu
psql $DATABASE_URL -c "VACUUM ANALYZE;"

Tăng connection pool
openclaw config set database.pool.max 20

Vấn đề Giới hạn Tốc độ

Problem:

Vượt quá giới hạn tốc độ cho kênh: telegram

Solution:

bash

Kiểm tra giới hạn hiện tại
openclaw config show channels.telegram.rateLimit

Tăng giới hạn
openclaw config set channels.telegram.rateLimit.messages 100
openclaw config set channels.telegram.rateLimit.per hour

Kiểm tra sử dụng
openclaw stats channel telegram --show-usage

Triển khai bộ nhớ đệm
openclaw config set cache.enabled true

Xử lý Sự cố Nâng cao

Vấn đề Mạng

Vấn đề Phân giải DNS

bash

Kiểm tra phân giải DNS
nslookup api.anthropic.com
dig api.anthropic.com

Sử dụng DNS tùy chỉnh
openclaw config set network.dns.servers "8.8.8.8,1.1.1.1"

Kiểm tra kết nối
curl -v https://api.anthropic.com

Sử dụng proxy nếu cần
openclaw config set network.proxy.http "http://proxy.company.com:8080"

Vấn đề SSL/TLS

bash

Kiểm tra chứng chỉ
openssl s_client -connect api.anthropic.com:443

Cập nhật chứng chỉ CA (Linux)
sudo apt update && sudo apt install ca-certificates

Tắt xác minh SSL (chỉ để kiểm tra)
openclaw config set network.ssl.verify false

Sử dụng CA tùy chỉnh
openclaw config set network.ssl.caFile "/path/to/ca.crt"

Vấn đề Cơ sở dữ liệu

Connection Pool Cạn kiệt

bash

Kiểm tra trạng thái pool
psql $DATABASE_URL -c "SELECT * FROM pg_stat_activity;"

Kết thúc kết nối nhàn rỗi
psql $DATABASE_URL -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'idle' AND query = '<IDLE>';"

Tăng kích thước pool
openclaw config set database.pool.max 30

Bật thoát connection
openclaw config set database.pool.drainTimeout 30000

Cơ sở dữ liệu Bị hỏng

bash

Kiểm tra tính toàn vẹn cơ sở dữ liệu
pg_dump $DATABASE_URL > /dev/null

Sửa chữa nếu bị hỏng
pg_dump $DATABASE_URL | psql $DATABASE_URL_NEW

Xây dựng lại từ sao lưu
psql $DATABASE_URL < backup.sql

Bật WAL cho phục hồi
openclaw config set database.wal.enabled true

Mẹo Hiệu suất

1. Tối ưu hóa Cấu hình

json5

{
  Tối ưu hóa hiệu suất
  performance: {
    Đồng thời
    maxConcurrentRequests: 20,
    maxConcurrentSessions: 10,

    Lưu trữ đệm
    cache: {
      enabled: true,
      ttl: 3600,
      maxSize: "512MB"
    },

    Quản lý ngữ cảnh
    context: {
      maxTokens: 100000,
      pruning: true,
      summaryThreshold: 0.8
    }
  }
}

2. Tối ưu hóa Cơ sở dữ liệu

sql

Tạo các chỉ mục tối ưu
CREATE INDEX CONCURRENTLY idx_messages_session_created
ON messages(session_id, created_at DESC);

Phân vùng các bảng lớn
CREATE TABLE messages_y2024m01 PARTITION OF messages
FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');

Cập nhật số liệu thống kê
ANALYZE messages;

Giám sát hiệu suất truy vấn
SELECT query, mean_exec_time, calls, total_exec_time
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;

3. Quản lý Bộ nhớ

bash

Giám sát sử dụng bộ nhớ
watch -n 5 'ps aux | grep openclaw'

Cấu hình giới hạn bộ nhớ Node.js
export NODE_OPTIONS="--max-old-space-size=4096"

Bật giám sát bộ nhớ
openclaw config set monitoring.memory.enabled true

Thiết lập cảnh báo bộ nhớ
openclaw alert create --name "High Memory" \
  --condition "memory.usage > 80%" \
  --action "notify:slack"

Thực hành Tốt nhất

1. Bảo trì Thường xuyên

bash

#!/bin/bash
# maintenance.sh

Bảo trì Hàng ngày
echo "Daily maintenance..."
openclaw cleanup logs --days 7
openclaw cleanup cache --expired

Bảo trì Hàng tuần
if [ $(date +%u) -eq 1 ]; then
  echo "Weekly maintenance..."
  openclaw update
  openclaw backup full
  psql $DATABASE_URL -c "VACUUM ANALYZE;"
fi

Bảo trì Hàng tháng
if [ $(date +%d) -eq 1 ]; then
  echo "Monthly maintenance..."
  openclaw security audit
  openclaw performance report
  openclaw rotate secrets
fi

2. Thiết lập Giám sát

yaml

# docker-compose.monitoring.yml
services:
  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin123
    volumes:
      - grafana-data:/var/lib/grafana

  alertmanager:
    image: prom/alertmanager
    volumes:
      - ./alertmanager.yml:/etc/alertmanager/alertmanager.yml

3. Security Checklist

bash

#!/bin/bash
# security-check.sh

echo "Security Checklist..."

# Check authentication
if [ "$(openclaw config get gateway.auth.mode)" = "none" ]; then
  echo "⚠️  Cảnh báo: Xác thực bị tắt"
fi

Kiểm tra chính sách DM
if [ "$(openclaw config get security.dmPolicy)" != "pairing" ]; then
  echo "⚠️  Cảnh báo: Ghép nối DM không được bật"
fi

Kiểm tra chứng chỉ SSL
if [ ! -f ~/.openclaw/ssl/cert.pem ]; then
  echo "⚠️  Cảnh báo: Không tìm thấy chứng chỉ SSL"
fi

Kiểm tra các khóa API bị lộ
if grep -r "sk-" ~/.openclaw/ --exclude-dir=.git; then
  echo "❌ Lỗi: Tìm thấy các khóa API bị lộ"
fi

echo "Kiểm tra bảo mật hoàn tất"

Tài nguyên Cộng đồng

Nhận Trợ giúp

Cộng đồng Discord (Khuyến nghị)
- Trợ giúp thời gian thực
- Cộng đồng hoạt động
- Kênh hỗ trợ chính thức
- Link: https://discord.gg/clawd
Vấn đề GitHub
- Báo cáo lỗi
- Yêu cầu tính năng
- Thảo luận kỹ thuật
- Link: https://github.com/openclaw/openclaw/issues
Tài liệu
- Tài liệu chính thức: https://docs.openclaw.ai
- Tham chiếu API
- Hướng dẫn xử lý sự cố

Đóng góp Lại

bash

Báo cáo lỗi hiệu quả
openclaw bug-report --template

Gửi yêu cầu tính năng
openclaw feature-request --template

Đóng góp tài liệu
openclaw docs contribute

Gửi pull request
git clone https://github.com/openclaw/openclaw.git
Tạo thay đổi
git commit -m "Fix: Resolve issue #123"
git push origin fix-issue-123
Tạo PR

Tham chiếu Nhanh

Các Lệnh Thiết yếu

bash

Kiểm tra sức khỏe
openclaw doctor

Khởi động lại dịch vụ
openclaw restart

# Check logs
openclaw logs --tail 100

Kiểm tra các kênh
openclaw test channels

Cập nhật cấu hình
openclaw config set <key> <value>

Sao lưu dữ liệu
openclaw backup create

Giám sát hiệu suất
openclaw monitor

Kiểm tra bảo mật
openclaw security check

Các Sửa chữa Thường gặp

Vấn đề	Sửa chữa Nhanh
Gateway không khởi động `openclaw config validate`
Kênh bị ngắt kết nối `openclaw channels restart <channel>`
Phản hồi chậm `openclaw config set agent.thinking low`
Bộ nhớ cao `openclaw restart`
Lỗi API `openclaw config set agent.apiKey <new-key>`
Từ chối quyền truy cập `sudo chown -R $USER ~/.openclaw`

Mẹo Cuối cùng

Bắt đầu Nhỏ Bắt đầu với 1-2 kênh Sử dụng cài đặt mặc định Thêm tính năng dần dần
Giám sát Thường xuyên Thiết lập cảnh báo Xem xét số liệu Kiểm tra nhật ký hàng tuần
Sao lưu Mọi thứ Cấu hình Cơ sở dữ liệu Thông tin xác thực
Cập nhật Thường xuyên Tham gia Discord Theo dõi các bản phát hành Xem xét nhật ký thay đổi
Tài liệu Thiết lập Lưu cấu hình Tài liệu các tùy chỉnh Tạo runbook

Next Steps

Bạn đã hoàn thành khóa học OpenClaw! Bây giờ bạn đã có:

Hiểu rõ về OpenClaw và kiến trúc Cài đặt và cấu hình thành công Kết nối các kênh cần thiết Sử dụng các tính năng hàng ngày Triển khai trong môi trường production Khắc phục các vấn đề thường gặp

Tiếp tục Hành trình của Bạn

Tham gia Cộng đồng

Discord: https://discord.gg/clawd
GitHub: https://github.com/openclaw/openclaw
Docs: https://docs.openclaw.ai

Khám phá Tính năng Nâng cao Xây dựng các kỹ năng tùy chỉnh Đóng góp cho dự án Chia sẻ các trường hợp sử dụng của bạn

Giữ Liên lạc Theo dõi cập nhật Chia sẻ phản hồi Giúp đỡ người khác

Chúc mừng! Bạn đã làm chủ OpenClaw và sẵn sàng tận dụng sức mạnh của personal AI assistant trong quy trình làm việc hàng ngày. Chúc xây dựng vui vẻ!

10. Troubleshooting và Tips ​

Overview ​

Công cụ Chẩn đoán ​

Chẩn đoán Tích hợp ​

Chế độ Gỡ lỗi ​

Lệnh Giám sát ​

Các Vấn đề Thường gặp và Giải pháp ​

1. Vấn đề Cài đặt ​

Phiên bản Node.js Không tương thích ​

Từ chối Quyền truy cập ​

2. Vấn đề Gateway ​

Cổng đã được sử dụng ​

Gateway Không khởi động ​

Vấn đề Kết nối WebSocket ​

3. Vấn đề Kênh ​

WhatsApp Mất kết nối ​

Telegram Bot Không phản hồi ​

Slack App Thiếu Quyền ​

4. Vấn đề AI/LLM ​

API Key Không hợp lệ ​

Model Không khả dụng ​

Thời gian Phản hồi Chậm ​

5. Vấn đề Hiệu suất ​

Sử dụng Bộ nhớ Cao ​

Truy vấn Cơ sở dữ liệu Chậm ​

Vấn đề Giới hạn Tốc độ ​

Xử lý Sự cố Nâng cao ​

Vấn đề Mạng ​

Vấn đề Phân giải DNS ​

Vấn đề SSL/TLS ​

Vấn đề Cơ sở dữ liệu ​

Connection Pool Cạn kiệt ​

Cơ sở dữ liệu Bị hỏng ​

Mẹo Hiệu suất ​

1. Tối ưu hóa Cấu hình ​

2. Tối ưu hóa Cơ sở dữ liệu ​

3. Quản lý Bộ nhớ ​

Thực hành Tốt nhất ​

1. Bảo trì Thường xuyên ​

2. Thiết lập Giám sát ​

3. Security Checklist ​

Tài nguyên Cộng đồng ​

Nhận Trợ giúp ​

Đóng góp Lại ​

Tham chiếu Nhanh ​

Các Lệnh Thiết yếu ​

Các Sửa chữa Thường gặp ​

Mẹo Cuối cùng ​

Next Steps ​

10. Troubleshooting và Tips

Overview

Công cụ Chẩn đoán

Chẩn đoán Tích hợp

Chế độ Gỡ lỗi

Lệnh Giám sát

Các Vấn đề Thường gặp và Giải pháp

1. Vấn đề Cài đặt

Phiên bản Node.js Không tương thích

Từ chối Quyền truy cập

2. Vấn đề Gateway

Cổng đã được sử dụng

Gateway Không khởi động

Vấn đề Kết nối WebSocket

3. Vấn đề Kênh

WhatsApp Mất kết nối

Telegram Bot Không phản hồi

Slack App Thiếu Quyền

4. Vấn đề AI/LLM

API Key Không hợp lệ

Model Không khả dụng

Thời gian Phản hồi Chậm

5. Vấn đề Hiệu suất

Sử dụng Bộ nhớ Cao

Truy vấn Cơ sở dữ liệu Chậm

Vấn đề Giới hạn Tốc độ

Xử lý Sự cố Nâng cao

Vấn đề Mạng

Vấn đề Phân giải DNS

Vấn đề SSL/TLS

Vấn đề Cơ sở dữ liệu

Connection Pool Cạn kiệt

Cơ sở dữ liệu Bị hỏng

Mẹo Hiệu suất

1. Tối ưu hóa Cấu hình

2. Tối ưu hóa Cơ sở dữ liệu

3. Quản lý Bộ nhớ

Thực hành Tốt nhất

1. Bảo trì Thường xuyên

2. Thiết lập Giám sát

3. Security Checklist

Tài nguyên Cộng đồng

Nhận Trợ giúp

Đóng góp Lại

Tham chiếu Nhanh

Các Lệnh Thiết yếu

Các Sửa chữa Thường gặp

Mẹo Cuối cùng

Next Steps