blog.dopana

Back

4 min
Vietnamese
nullclaw/
tutorial/
zig/
devops/
guide

Hướng Dẫn Cài Đặt Và Sử Dụng NullClaw Từ A-Z

Hướng dẫn chi tiết cài đặt NullClaw qua Homebrew, Docker, build từ source, cấu hình provider, channels, và chạy gateway.

Hướng dẫn này sẽ đưa bạn từ chưa biết gì đến chạy được NullClaw đầy đủ — từ cài đặt, cấu hình, đến vận hành.

1. Cài Đặt#

Option A: Homebrew (Khuyên Dùng)#

brew install nullclaw
nullclaw --help
bash

Option B: Docker#

docker run --rm -it \
  -v nullclaw-data:/nullclaw-data \
  ghcr.io/nullclaw/nullclaw:latest status
bash

Hoặc dùng Docker Compose có sẵn trong repo:

git clone https://github.com/nullclaw/nullclaw.git
cd nullclaw
make build
make config
make up
bash

Option C: Build Từ Source#

Yêu cầu Zig 0.16.0 chính xác:

git clone https://github.com/nullclaw/nullclaw.git
cd nullclaw
zig build -Doptimize=ReleaseSmall
zig build test --summary all
# 5,300+ tests passed
bash

Thêm vào PATH:

zig build -Doptimize=ReleaseSmall -p "$HOME/.local"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
bash

2. Onboarding — Thiết Lập Lần Đầu#

Quick Setup#

nullclaw onboard --api-key sk-or-... --provider openrouter
bash

Interactive Wizard (Khuyên Dùng)#

nullclaw onboard --interactive
bash

Wizard sẽ hướng dẫn bạn qua từng bước:

  1. Chọn AI provider và nhập API key
  2. Cấu hình model mặc định
  3. Thiết lập channels (Telegram, Discord, …)
  4. Cấu hình memory backend
  5. Thiết lập mức độ tự động (autonomy level)
  6. Cấu hình security (sandbox, pairing)
  7. (Optional) Thiết lập Nostr

3. Cấu Hình provider#

File config nằm ở ~/.nullclaw/config.json:

Hỗ trợ 50+ provider — từ cloud (OpenRouter, Anthropic, OpenAI) đến local (Ollama, custom endpoint).

4. Kết Nối Channels#

Telegram#

{
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "123456:ABC-DEF...",
          "allow_from": ["YOUR_USER_ID"],
          "reply_in_private": true
        }
      }
    }
  }
}
json

Discord#

{
  "channels": {
    "discord": {
      "accounts": {
        "main": {
          "token": "disc-token",
          "guild_id": "12345",
          "allow_from": ["user1"]
        }
      }
    }
  }
}
json

Nostr (Phi Tập Trung)#

{
  "channels": {
    "nostr": {
      "private_key": "enc2:...",
      "owner_pubkey": "hex-pubkey-cua-ban",
      "relays": ["wss://relay.damus.io", "wss://nos.lol"],
      "dm_allowed_pubkeys": ["*"]
    }
  }
}
json

5. Memory — Bộ Nhớ Cho Agent#

NullClaw hỗ trợ hybrid search (vector + keyword):

{
  "memory": {
    "backend": "sqlite",
    "auto_save": true,
    "embedding_provider": "openai",
    "vector_weight": 0.7,
    "keyword_weight": 0.3
  }
}
json

Các backend có sẵn: SQLite (mặc định), PostgreSQL, Redis, ClickHouse, LanceDB, Markdown, v.v.

6. Security — Bảo Mật#

Cấu hình bảo mật khuyên dùng:

7. Chạy Và Sử Dụng#

CLI#

# Chat một lần
nullclaw agent -m "Xin chào!"

# Interactive mode
nullclaw agent

# Check status
nullclaw status
nullclaw doctor
bash

Gateway Mode#

nullclaw gateway
# Mặc định: http://127.0.0.1:3000

curl http://127.0.0.1:3000/health
bash

Service Mode#

nullclaw service install
nullclaw service start
nullclaw service status
bash

Quản Lý Channels#

nullclaw channel status
nullclaw channel start telegram
nullclaw channel start discord
bash

8. Telegram Forum Topics — Multi-Agent#

Bind agent khác nhau cho từng topic trong group:

{
  "agents": {
    "list": [
      { "id": "coder", "model": "ollama/qwen2.5-coder:14b" },
      { "id": "writer", "model": "openrouter/anthropic/claude-sonnet-4" }
    ]
  },
  "bindings": [
    { "agent_id": "coder", "match": { "channel": "telegram", "peer": { "id": "-100123:thread:42" } } },
    { "agent_id": "writer", "match": { "channel": "telegram", "peer": { "id": "-100123" } } }
  ]
}
json

Hoặc dùng lệnh /bind trong Telegram để gán nhanh.

9. A2A — Kết Nối Agent Với Agent#

NullClaw hỗ trợ Google A2A Protocol v0.3.0:

{
  "a2a": { "enabled": true, "name": "nullclaw", "description": "AI assistant", "url": "https://example.com" }
}
json
# Lấy token
TOKEN=$(curl -s -X POST -H "X-Pairing-Code: $CODE" http://localhost:3000/pair | jq -r .token)

# Gọi A2A
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"parts":[{"text":"Hello"}]}}}' \
  http://localhost:3000/a2a
bash

10. Troubleshooting#

# Kiểm tra lỗi config
nullclaw doctor

# Xem status chi tiết
nullclaw status --json

# Restart service sau khi thay đổi config
nullclaw service stop && nullclaw service start

# Nếu model gọi thất bại
nullclaw onboard --interactive
bash

Kết Luận#

NullClaw là một trong những AI infrastructure nhẹ nhất, nhanh nhất, và linh hoạt nhất hiện nay. Chỉ với 678 KB, bạn có toàn bộ sức mạnh của một AI agent hiện đại — từ cloud provider đến local LLM, từ Telegram đến Nostr, từ SQLite đến PostgreSQL.

Tài nguyên:

Tài liệu tham khảo#

NullClaw Cho IoT và Edge Computing — AI Trên Phần Cứng $5

Giới Thiệu NullClaw — AI Infrastructure Nhỏ Nhất Thế Giới