OneHammerClaw (Tiếng Việt)

Trợ lý AI hỗ trợ nhiều nhà cung cấp và tích hợp kênh Zalo.

OneHammerClaw là trợ lý AI riêng tư, sẵn sàng triển khai trên máy chủ của bạn. Hỗ trợ nhiều nhà cung cấp AI và tích hợp kênh Zalo của OneHammer — chỉ cần cài đặt, cấu hình nhà cung cấp ưa thích và bắt đầu trò chuyện.

English: See README.md for English version.

Yêu cầu hệ thống

• Máy chủ Linux (Ubuntu, Debian, CentOS) hoặc máy Windows
• Mã truy cập OneHammerClaw (được cung cấp sau khi mua)
• API key từ nhà cung cấp AI bạn muốn sử dụng
• Docker và Docker Compose (khuyến nghị) — hoặc Node.js 22+ và git cho cài đặt không Docker

Các nhà cung cấp AI được hỗ trợ

Cài đặt Docker (nếu chưa có)

curl -fsSL https://get.docker.com | sh

Bắt đầu nhanh

Bước 1 — Chạy trình cài đặt

Linux / macOS (Docker — khuyến nghị):

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

Linux (không Docker — Node.js trực tiếp):

OHCLAW_TOKEN=ghp_your_token_here bash <(curl -fsSL https://openclaw.onehammer.store/install-node.sh)

Windows (PowerShell — Node.js trực tiếp, không Docker):

$env:OHCLAW_TOKEN="ghp_your_token_here"; irm https://openclaw.onehammer.store/install.ps1 | iex

Bước 2 — Nhập thông tin xác thực

Trình cài đặt sẽ yêu cầu bạn nhập:

1. Mã truy cập — mã bạn nhận được sau khi mua OneHammerClaw

Trình cài đặt sẽ tự động:

• Cài đặt các phần phụ thuộc (Node.js, git, pnpm)
• Tạo mã xác thực gateway an toàn
• Tải và build OneHammerClaw
• Khởi động gateway
• Tuỳ chọn thiết lập HTTPS (với Let's Encrypt hoặc chứng chỉ tự ký)

Bước 3 — Mở giao diện quản lý

Sau khi cài đặt xong, bạn sẽ thấy thông báo như sau:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Open the Control UI in your browser:

    https://dia-chi-ip-may-chu

  Gateway Token: a1b2c3d4e5f6...
  (hãy lưu lại — bạn sẽ cần dùng để đăng nhập)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Mở trình duyệt và truy cập đường dẫn hiển thị. Nhập Gateway Token để đăng nhập.

Quan trọng: Hãy lưu gateway token ở nơi an toàn. Bạn sẽ cần nó mỗi khi đăng nhập.

Cấu hình nhà cung cấp AI

OneHammerClaw hỗ trợ nhiều nhà cung cấp AI. Cấu hình nhà cung cấp ưa thích sau khi cài đặt.

Thêm hoặc thay đổi nhà cung cấp

1. Mở giao diện quản lý
2. Vào tab Agents > chọn agent > AI Providers
3. Nhập API key cho nhà cung cấp bạn muốn sử dụng
4. Chọn mô hình mặc định

Bạn có thể cấu hình nhiều nhà cung cấp cùng lúc và chuyển đổi giữa chúng khi cần.

Tìm kiếm Web (SearXNG)

OneHammerClaw tích hợp SearXNG — công cụ tìm kiếm meta tự lưu trữ cho phép AI agent tìm kiếm web mà không cần API key từ bên ngoài.

SearXNG là gì?

SearXNG là công cụ tìm kiếm meta tập trung vào quyền riêng tư, tổng hợp kết quả từ nhiều nguồn tìm kiếm (Google, Bing, DuckDuckGo, v.v.). Nó chạy cục bộ trên máy chủ của bạn và không cần API key.

Cài đặt Docker (Tự động)

SearXNG được tích hợp sẵn trong cấu hình Docker. Dịch vụ khởi động cùng OneHammerClaw và sẵn sàng sử dụng ngay.

Để bật tìm kiếm web:

1. Mở giao diện quản lý
2. Vào tab Config > Tools > Web Search
3. Bật Enable Web Search Tool
4. Trong phần SearXNG, bật Enable SearXNG Search

Xong — AI agent của bạn đã có thể tìm kiếm web. Không cần API key.

Cài đặt Node.js (Thủ công)

Với cài đặt không dùng Docker, SearXNG chạy trong container Docker riêng.

Trong quá trình cài đặt OneHammerClaw

Trình cài đặt Node.js (install-node.sh) sẽ hỏi bạn có muốn cài SearXNG không. Chỉ cần trả lời Y.

Đã cài đặt OneHammerClaw rồi

Nếu đã cài OneHammerClaw, chạy trình cài đặt SearXNG riêng:

curl -fsSL https://openclaw.onehammer.store/install-searxng.sh | bash

Script sẽ:

• Cài Docker nếu chưa có
• Chạy SearXNG trên port 8888
• Tự động cấu hình OneHammerClaw để dùng SearXNG

Cấu hình thủ công

Nếu bạn muốn tự thiết lập:

1. Chạy container SearXNG:

   docker run -d --name searxng --restart unless-stopped -p 8888:8080 searxng/searxng:latest
   

2. Cấu hình OneHammerClaw trong giao diện quản lý:

   • Vào Config > Tools > Web Search
   • Bật Enable Web Search Tool
   • Trong phần SearXNG:
     • Bật Enable SearXNG Search
     • Đặt SearXNG Base URL thành http://localhost:8888

Lệnh quản lý SearXNG

Các tùy chọn cấu hình SearXNG

Sử dụng nhà cung cấp tìm kiếm khác

Nếu bạn muốn dùng các nhà cung cấp tìm kiếm có API thay vì SearXNG:

Cấu hình API key trong Config > Tools > Web Search và chọn Web Search Provider bạn muốn.

Thiết lập kênh nhắn tin

OneHammerClaw hỗ trợ nhiều kênh nhắn tin. Bạn có thể bật một hoặc nhiều kênh cùng lúc.

Telegram Bot

1. Tạo bot với @BotFather trên Telegram và sao chép Bot Token
2. Mở giao diện quản lý > tab Channels > Telegram
3. Vào tab Config > Channels > telegram > dán bot token
4. Nhấn Save — bot sẽ tự động khởi động
5. Nhắn tin cho bot trên Telegram — người dùng lần đầu cần được duyệt qua nút Manage Pairing

Nhóm Telegram

Mặc định, bot chỉ trả lời tin nhắn riêng (DM). Truy cập nhóm sử dụng hai lớp kiểm soát:

1. Nhóm nào được phép — cấu hình qua groups
2. Ai được phép trong nhóm — cấu hình qua groupPolicy và groupAllowFrom

Bước 1: Tìm Group Chat ID

Thêm bot vào nhóm và gửi tin nhắn. Tìm group chat ID bằng một trong các cách sau:

• Kiểm tra tab Logs trong giao diện quản lý
• Chuyển tiếp tin nhắn nhóm đến @userinfobot hoặc @getidsbot trên Telegram
• Chạy: docker compose logs onehammerclaw | grep "group"

Group chat ID là số âm như -1001234567890.

Bước 2: Cấu hình truy cập nhóm

Mở tab Config > Channels > telegram và thêm:

"groupPolicy": "allowlist",
"groups": {
    "-1001234567890": {
        "groupPolicy": "open",
        "requireMention": false
    }
}

Bước 3: Chế độ riêng tư của Bot

Nếu requireMention là false, bot cần xem tất cả tin nhắn (không chỉ @mention). Chọn một trong hai cách:

• Tắt chế độ riêng tư qua @BotFather > /setprivacy > Disable
• Hoặc đặt bot làm admin nhóm

Sau khi thay đổi chế độ riêng tư, xóa và thêm lại bot trong mỗi nhóm để Telegram áp dụng thay đổi.

Bảng tham chiếu cấu hình nhóm

Các cấu hình phổ biến

Mọi thành viên đều chat được trong nhóm cụ thể:

"groupPolicy": "allowlist",
"groups": {
    "-1001234567890": {
        "groupPolicy": "open",
        "requireMention": false
    }
}

Chỉ người dùng cụ thể được chat trong nhóm:

"groupPolicy": "allowlist",
"groups": {
    "-1001234567890": {
        "requireMention": true,
        "allowFrom": ["932131897", "123456789"]
    }
}

Bot chỉ trả lời khi được @mention (mặc định cho nhóm):

"groups": {
    "-1001234567890": {
        "groupPolicy": "open",
        "requireMention": true
    }
}

Mở tất cả nhóm (không khuyến nghị):

"groupPolicy": "open",
"groups": {
    "*": { "requireMention": false }
}

Chủ đề (Forum Topics)

Nếu nhóm bật chế độ chủ đề/forum, mỗi chủ đề có phiên riêng:

"groups": {
    "-1001234567890": {
        "groupPolicy": "open",
        "topics": {
            "1": { "agentId": "main" },
            "3": { "agentId": "coder", "requireMention": false },
            "5": { "agentId": "translator" }
        }
    }
}

Lưu ý quan trọng

• groupAllowFrom kiểm soát người dùng nào được tương tác — không phải nhóm nào. ID nhóm (số âm) đặt trong groups.
• Xác thực người gửi trong nhóm không kế thừa từ phê duyệt DM pairing.
• Khi nhóm được chuyển đổi sang supergroup, gateway tự động cập nhật ID nhóm.
• Giới hạn lịch sử nhóm: mặc định 50 tin nhắn. Thay đổi với messages.groupChat.historyLimit.

Zalo (OneHammer Zalo)

1. Mở giao diện quản lý > tab Channels > OneHammer Zalo
2. Nhấn Show QR — mã QR sẽ hiển thị
3. Quét mã bằng ứng dụng Zalo trên điện thoại
4. Sau khi liên kết, trợ lý AI sẽ tự động trả lời tin nhắn trên tài khoản Zalo của bạn

Các kênh khác

• Discord — Thêm bot vào máy chủ Discord
• Slack — Kết nối với workspace Slack
• Signal — Liên kết tài khoản Signal
• WhatsApp — Kết nối qua WhatsApp Web
• iMessage — Kết nối qua BlueBubbles (chỉ macOS)

Cập nhật

Docker:

cd ~/onehammerclaw
docker compose pull && docker compose up -d

Node.js (không Docker):

# Script cập nhật tự động (khuyến nghị)
# - Pull mã nguồn mới nhất từ onehammer/main
# - Merge cấu hình mới vào config (giữ nguyên giá trị cũ)
# - Build lại ứng dụng
# - Khởi động lại dịch vụ
bash <(curl -fsSL https://openclaw.onehammer.store/onehammerclaw-update.sh)

# Kiểm tra có bản cập nhật không (không thay đổi gì)
bash <(curl -fsSL https://openclaw.onehammer.store/onehammerclaw-update.sh) --check

Cập nhật tự động hàng ngày (cron):

# Tải script về trước (vì repo là private)
cd ~/onehammerclaw && git checkout origin/main -- dist/onehammerclaw-update.sh
chmod +x ~/onehammerclaw/dist/onehammerclaw-update.sh

# Thêm vào crontab (chạy lúc 3h sáng mỗi ngày)
echo "0 3 * * * /root/onehammerclaw/dist/onehammerclaw-update.sh >> /var/log/onehammerclaw-update.log 2>&1" | crontab -

# Kiểm tra crontab
crontab -l

Các lệnh thường dùng

Cài đặt Docker

cd ~/onehammerclaw
docker compose ps          # Kiểm tra trạng thái
docker compose logs -f     # Xem log trực tiếp
docker compose down        # Dừng
docker compose up -d       # Khởi động
docker compose restart     # Khởi động lại

Cài đặt Node.js (không Docker)

sudo systemctl status onehammerclaw      # Kiểm tra trạng thái
sudo journalctl -u onehammerclaw -f    # Xem log trực tiếp
sudo systemctl restart onehammerclaw     # Khởi động lại
sudo systemctl stop onehammerclaw        # Dừng

# Cập nhật
bash <(curl -fsSL https://openclaw.onehammer.store/install-node.sh)

# Gỡ cài đặt
sudo systemctl stop onehammerclaw
sudo rm /etc/systemd/system/onehammerclaw.service
rm -rf ~/onehammerclaw ~/.local/bin/onehammerclaw

Hỗ trợ ngôn ngữ

Giao diện quản lý hỗ trợ nhiều ngôn ngữ:

• English
• Tiếng Việt (Vietnamese)
• 简体中文 (Trung Quốc giản thể)
• 繁體中文 (Trung Quốc phồn thể)
• Português (Bồ Đào Nha - Brazil)
• Deutsch (Đức)

Thay đổi ngôn ngữ tại tab Overview > Gateway Access > Language.

Dữ liệu & Lưu trữ

Docker

Node.js (không Docker)

Dữ liệu lưu tại ~/.openclaw/ — bao gồm cài đặt, phiên chat, và bộ nhớ agent.

Dữ liệu không bao giờ bị mất khi dừng, khởi động lại, hoặc cập nhật.

Xử lý sự cố

Phiên mới không tạo được cron (gateway not connected)

Nếu phiên chat mới không tạo được cron và báo gateway not connected, hãy ép phiên dùng đúng gateway URL/token:

1. Mở dashboard với gateway + token rõ ràng:
   • https://your-server/ui/overview?gatewayUrl=wss://your-gateway-host#token=YOUR_GATEWAY_TOKEN
2. Xác nhận hộp thoại chuyển gateway URL trong UI.
3. Đợi UI hiển thị trạng thái đã kết nối.
4. Tạo phiên mới.

Nếu vẫn lỗi, hãy xóa site data của trình duyệt cho host dashboard, mở lại đúng URL có token như trên, rồi tạo phiên mới.

Với cài đặt Node.js, khi khởi động lại dịch vụ hãy dùng:

sudo systemctl restart onehammerclaw

Trình duyệt không khả dụng (Browser not available)

Docker: Tải image mới nhất:

cd ~/onehammerclaw
docker compose pull && docker compose up -d

Node.js: Với server client không chạy bằng root, cần sudo để cài phụ thuộc hệ điều hành (ví dụ xvfb/thư viện chromium headless), sau đó cài Chromium:

cd ~/onehammerclaw
sudo npx playwright install-deps chromium
npx playwright install chromium

Quên gateway token

cat ~/onehammerclaw/.env

Tìm dòng OPENCLAW_GATEWAY_TOKEN.

HTTPS không hoạt động

sudo nginx -t                    # kiểm tra cấu hình
sudo systemctl status nginx       # kiểm tra trạng thái
sudo journalctl -xeu nginx       # xem log

Xử lý sự cố WhatsApp

Lỗi "Couldn't link device" hoặc "Can't link new devices at this time"

Đây là lỗi phía WhatsApp chặn việc ghép nối, không phải lỗi OpenClaw. Nguyên nhân thường gặp:

1. WhatsApp rate-limit — WhatsApp giới hạn số lần ghép nối. Đợi 30–60 phút trước khi thử lại.

2. Quá nhiều thiết bị đã liên kết — WhatsApp cho phép tối đa ~10 thiết bị.

Cách khắc phục:

# Bước 1: Xóa session WhatsApp cũ
rm -rf ~/.openclaw/credentials/whatsapp/default/

# Bước 2: Đợi 30–60 phút (QUAN TRỌNG)

# Bước 3: Trên điện thoại, vào WhatsApp → Cài đặt → Thiết bị đã liên kết
#          Bỏ liên kết TẤT CẢ các thiết bị cũ (nhất là thiết bị tên "OpenClaw" hoặc "unknown")

# Bước 4: Đăng nhập bằng CLI (không dùng giao diện web)
onehammerclaw channels login --channel whatsapp

# Bước 5: Quét mã QR NGAY LẬP TỨC trong vòng 15 giây

3. Dùng mạng di động thay vì WiFi

Nếu quét QR bằng WiFi vẫn thất bại, thử:

• Tắt WiFi trên điện thoại
• Bật dữ liệu di động (4G/5G)
• Quét mã QR ngay lập tức

4. Kiểm tra DNS

Nếu máy chủ ở Việt Nam và không thể kết nối WhatsApp, thử sửa DNS:

# Thêm DNS resolution cho wweb.whatsapp.com
echo "57.144.65.32 wweb.whatsapp.com" | sudo tee -a /etc/hosts

# Kiểm tra kết nối
node -e "require('dns').lookup('wweb.whatsapp.com', (e,a)=>console.log(e?'FAIL':'OK:'+a))"

5. Kiểm tra chứng chỉ TLS

Nếu gặp lỗi unable to verify the first certificate:

# Cập nhật chứng chỉ CA
sudo apt-get update && sudo apt-get install -y --reinstall ca-certificates
sudo update-ca-certificates

# Khởi động lại dịch vụ
sudo systemctl restart onehammerclaw

Lệnh hữu ích để kiểm tra trạng thái WhatsApp

# Xem log WhatsApp
sudo journalctl -u onehammerclaw | grep -i whatsapp

# Xem trạng thái kênh
onehammerclaw channels status

# Khởi động lại dịch vụ
sudo systemctl restart onehammerclaw

Hỗ trợ

Nếu bạn cần trợ giúp, hãy liên hệ nhà cung cấp OneHammerClaw của bạn để được hỗ trợ.