Tích hợp OpenViking vào OpenClaw: Nâng cấp bộ nhớ AI Agent, giảm 83% token cost

Mặc định, OpenClaw lưu memory dưới dạng file Markdown và dùng SQLite vector search. Cách này hoạt động ổn, nhưng khi lượng context lớn lên, token cost tăng và retrieval chưa thật sự thông minh. OpenViking giải quyết đúng vấn đề này, giảm tới 83-96% token cost và tăng task completion rate lên gần 50% theo benchmark chính thức.

Bài này mình sẽ hướng dẫn cài đặt OpenViking và tích hợp vào OpenClaw từ đầu trên cùng một VPS Ubuntu.

OpenViking là gì?

OpenViking là context database mã nguồn mở của Volcengine (ByteDance), thiết kế riêng cho AI Agent. Thay vì dùng vector database truyền thống kiểu RAG flat, OpenViking tổ chức context theo “file system paradigm” với 3 tầng:

• L0 (Abstract): ~100 tokens, dùng cho vector search nhanh
• L1 (Overview): ~2k tokens, dùng cho rerank và hiểu scope
• L2 (Detail): nội dung đầy đủ, load khi cần

Agent chỉ cần L0/L1 trong phần lớn trường hợp, chỉ load L2 khi thực sự cần chi tiết. Đây là lý do token cost giảm mạnh.

Vai trò của OpenViking trong OpenClaw

Nôm na thì:

• OpenClaw = bộ não (reasoning, ra quyết định, chạy tools)
• OpenViking = bộ nhớ (lưu trữ, tìm kiếm, tổ chức context)

OpenClaw vẫn xử lý mọi thứ. Khi cần nhớ lại thông tin, nó gọi OpenViking qua HTTP API. OpenViking trả về đúng context cần thiết với lượng token tối thiểu.

Yêu cầu hệ thống

• VPS Ubuntu 22.04 hoặc 24.04 (bài này dùng 24.04)
• Tối thiểu 2 CPU, 4GB RAM (khuyến nghị 4 CPU, 8GB RAM)
• 40GB+ ổ cứng
• Python 3.10+
• Node.js 18+ (cho OpenClaw)
• API key: OpenAI (cho embedding) và DeepSeek (cho VLM)

Bước 1: Cài đặt prerequisites

SSH vào VPS và cài các gói cơ bản:

apt update && apt install -y build-essential gcc g++ make curl git python3-pip python3-venv

Cài Go

OpenViking cần Go để build AGFS component:

wget -q https://go.dev/dl/go1.23.6.linux-amd64.tar.gz -O /tmp/go.tar.gz
rm -rf /usr/local/go && tar -C /usr/local -xzf /tmp/go.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc
go version

Cài Rust

CLI tool của OpenViking viết bằng Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source ~/.cargo/env
rustc --version

Bước 2: Cài đặt OpenViking

⚠️ Ubuntu 24.04 chặn pip install system-wide (PEP 668). Phải dùng virtual environment, không dùng --break-system-packages.

Cài Python package

# Tạo virtual environment
python3 -m venv /opt/openviking-env
source /opt/openviking-env/bin/activate
# Cài OpenViking
pip install openviking --upgrade --force-reinstall

Cài CLI tool

CLI (ov) giúp quản lý resources, search, và monitor từ terminal:

cargo install --git https://github.com/volcengine/OpenViking ov_cli

ℹ️ Build CLI từ source mất khoảng 2-3 phút. Nếu SSH bị timeout, thêm -o ServerAliveInterval=30 vào lệnh SSH.

Bước 3: Cấu hình OpenViking

OpenViking cần 2 model API: embedding (để vector hóa nội dung) và VLM (để hiểu ngữ nghĩa, tạo L0/L1). Ở đây mình dùng OpenAI cho embedding và DeepSeek cho VLM.

Tạo config server

mkdir -p ~/.openviking /var/lib/openviking

Tạo file ~/.openviking/ov.conf:

{
  "embedding": {
    "dense": {
      "api_base": "https://api.openai.com/v1",
      "api_key": "sk-proj-YOUR_OPENAI_KEY",
      "provider": "openai",
      "dimension": 3072,
      "model": "text-embedding-3-large"
    },
    "max_concurrent": 10
  },
  "vlm": {
    "api_base": "https://api.deepseek.com",
    "api_key": "sk-YOUR_DEEPSEEK_KEY",
    "provider": "litellm",
    "model": "deepseek/deepseek-chat",
    "max_concurrent": 50
  },
  "storage": {
    "workspace": "/var/lib/openviking/data",
    "agfs": { "backend": "local" },
    "vectordb": { "backend": "local" }
  },
  "server": {
    "host": "0.0.0.0",
    "port": 1933,
    "root_api_key": "your-secret-api-key",
    "cors_origins": ["*"]
  }
}

💡 Ngoài OpenAI + DeepSeek, bạn có thể dùng Jina (embedding), Claude, Gemini, hoặc Ollama (VLM local) tùy ý. Xem thêm tại OpenViking Configuration Guide.

Tạo config CLI

Tạo file ~/.openviking/ovcli.conf để CLI kết nối đến server:

{
  "url": "http://localhost:1933",
  "api_key": "your-secret-api-key",
  "output": "table"
}

Bước 4: Chạy OpenViking server

Test nhanh

source /opt/openviking-env/bin/activate
openviking-server

Chạy production với systemd

Tạo file /etc/systemd/system/openviking.service:

[Unit]
Description=OpenViking Context Database Server
After=network.target
[Service]
Type=simple
WorkingDirectory=/var/lib/openviking
ExecStart=/opt/openviking-env/bin/openviking-server
Restart=always
RestartSec=5
Environment="OPENVIKING_CONFIG_FILE=/root/.openviking/ov.conf"
Environment="PATH=/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable openviking
systemctl start openviking

Kiểm tra server

# Health check
curl -s http://localhost:1933/health
# Readiness check
curl -s http://localhost:1933/ready | python3 -m json.tool

Bước 5: Test OpenViking

Trước khi tích hợp với OpenClaw, test OpenViking riêng để đảm bảo mọi thứ hoạt động.

Thêm resource

source /opt/openviking-env/bin/activate
source ~/.cargo/env
# Thêm tài liệu từ URL
ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md
# Xem danh sách resources
ov ls viking://resources/
# Xem trạng thái xử lý
ov observer system

Test semantic search

ov find "what is openviking"

Kết quả trả về đúng nội dung liên quan, kèm score đánh giá mức độ phù hợp. OpenViking cũng tự tạo abstract (L0) và overview (L1) cho mỗi resource.

Bước 6: Cài đặt OpenClaw

Nếu VPS chưa có OpenClaw, cài nhanh (xem chi tiết thêm tại Hướng dẫn cài đặt OpenClaw).

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

Bước 7: Tích hợp OpenViking vào OpenClaw

Chỗ này là phần quan trọng nhất. OpenViking cung cấp sẵn memory plugin cho OpenClaw, thay thế memory-core mặc định.

Cài plugin

# Clone repo OpenViking (lấy plugin files)
cd /tmp
git clone --depth 1 https://github.com/volcengine/OpenViking.git
# Copy plugin vào OpenClaw extensions
mkdir -p ~/.openclaw/extensions/memory-openviking
cp /tmp/OpenViking/examples/openclaw-memory-plugin/{index.ts,config.ts,client.ts,process-manager.ts,memory-ranking.ts,text-utils.ts,openclaw.plugin.json,package.json,.gitignore} \
  ~/.openclaw/extensions/memory-openviking/
# Cài dependencies
cd ~/.openclaw/extensions/memory-openviking && npm install

Cấu hình OpenClaw dùng plugin

# Bật plugin
openclaw config set plugins.enabled true
openclaw config set plugins.allow '["memory-openviking"]' --json
# Chỉ định dùng OpenViking làm memory backend
openclaw config set plugins.slots.memory memory-openviking
# Cấu hình remote mode (trỏ đến OpenViking server)
openclaw config set plugins.entries.memory-openviking.config.mode "remote"
openclaw config set plugins.entries.memory-openviking.config.baseUrl "http://localhost:1933"
openclaw config set plugins.entries.memory-openviking.config.apiKey "your-secret-api-key"
# Bật auto-recall và auto-capture
openclaw config set plugins.entries.memory-openviking.config.autoRecall true --json
openclaw config set plugins.entries.memory-openviking.config.autoCapture true --json

ℹ️ autoRecall: agent tự động search memory khi nhận message. autoCapture: agent tự động lưu thông tin quan trọng từ conversation vào memory.

Cấu hình model cho OpenClaw

# Set API key qua environment variable
export OPENAI_API_KEY="sk-proj-YOUR_OPENAI_KEY"
# Set default model
openclaw config set agents.defaults.model "openai/gpt-4o"
# Set gateway mode
openclaw config set gateway.mode "local"

⚠️ Phải set gateway.mode = "local" trước khi chạy gateway, nếu không sẽ bị block với thông báo “Gateway start blocked”.

Khởi động gateway

openclaw gateway

Trong log, bạn sẽ thấy dòng xác nhận plugin đã kết nối:

[gateway] memory-openviking: initialized (url: http://localhost:1933, targetUri: viking://user/memories, search: hybrid endpoint)

Bước 8: Kiểm tra hoạt động chính thức

Giờ test xem agent có thể lưu và nhớ lại thông tin qua OpenViking không.

Lưu memory

openclaw agent --agent main --message "Please remember that my favorite color is blue and I love Vietnamese coffee."

Recall memory

openclaw agent --agent main --message "What is my favorite color and what drink do I love?"

Xem memory trong OpenViking

ov ls viking://user/default/memories/

Cái hay là OpenViking tự động phân loại memory vào các thư mục: entities (người, project, concept), events (sự kiện), preferences (sở thích), và profile (thông tin cá nhân). Agent không cần lo việc tổ chức data.

So sánh trước và sau

Theo benchmark chính thức của OpenViking (test trên LoCoMo10 dataset, 1540 cases):

Setup	Task Completion	Input Tokens
OpenClaw gốc (memory-core)	35.65%	24.6M
OpenClaw + LanceDB	44.55%	51.6M
OpenClaw + OpenViking	52.08%	4.3M

Tăng gần 50% task completion, giảm 83% token cost. Con số này có ý nghĩa thực tế: agent hiểu context tốt hơn và tốn ít tiền API hơn đáng kể.

Troubleshooting

pip install bị chặn trên Ubuntu 24.04

Lỗi: error: externally-managed-environment

Nguyên nhân: Ubuntu 24.04 áp dụng PEP 668, chặn pip install system-wide.

Cách sửa: Dùng virtual environment:

python3 -m venv /opt/openviking-env
source /opt/openviking-env/bin/activate
pip install openviking

SSH timeout khi build Rust CLI

Lỗi: ssh: connect to host ... Connection timed out

Nguyên nhân: cargo install build mất 2-3 phút, SSH session hết timeout.

Cách sửa: Thêm keepalive vào lệnh SSH:

ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=10 root@your-server

OpenClaw gateway bị block

Lỗi: Gateway start blocked: set gateway.mode=local

Cách sửa:

openclaw config set gateway.mode "local"

Memory hiển thị disabled hoặc memory-core

Nguyên nhân: Plugin chưa được chỉ định làm memory backend.

Cách sửa:

openclaw config set plugins.slots.memory memory-openviking

OpenViking server không tự khởi động sau reboot

Cách sửa: Tạo systemd service như Bước 4 và chạy systemctl enable openviking.

Subscription vs API key: khi nào OpenViking thực sự tiết kiệm

Không phải ai cũng hưởng lợi như nhau từ OpenViking. Tùy cách bạn trả tiền cho LLM mà mức tiết kiệm sẽ khác nhau.

Người dùng API key trả per-token

Đây là đối tượng hưởng lợi lớn nhất. Input tokens giảm 83% (24.6M xuống 4.3M theo benchmark) nghĩa là tiết kiệm tiền thật.

Tính nhanh: Claude Opus input giá $15/M tokens. Với 24.6M tokens, bạn trả $369. Cùng workload đó qua OpenViking chỉ còn 4.3M tokens = $64.50. Tiết kiệm khoảng $300.

Task completion cũng tăng từ 35% lên 52%. Tức là agent vừa rẻ hơn vừa làm việc tốt hơn.

Người dùng subscription (Claude Pro/Max, ChatGPT Pro)

Token input không tính tiền riêng, bạn trả cố định hàng tháng ($20-200/tháng tùy plan). Giảm token không giảm bill trực tiếp.

Nhưng vẫn có lợi gián tiếp:

• Context nhỏ hơn = mỗi turn tốn ít quota, ít bị rate limit hơn
• Ít compaction hơn nên session mượt hơn
• Agent nhớ chính xác hơn (52% vs 35% task completion)

Nếu bạn hay bị “session limit” trên Claude Max, OpenViking giúp giảm context mỗi turn, từ đó kéo dài session trước khi chạm limit.

Chi phí thêm khi dùng OpenViking

OpenViking không miễn phí hoàn toàn. Bạn cần tính thêm:

• Embedding API: OpenAI text-embedding-3-large khoảng $0.13/M tokens
• VLM API: DeepSeek khoảng $0.14/M input tokens
• Với autoRecall + autoCapture bật, mỗi tin nhắn đều gọi 2 API này
• Server resources: 2-4 CPU, 4-8GB RAM

Phù hợp với người dùng có sẵn VPS hoặc cấu hình OpenClaw đủ mạnh để có thể chạy chung OpenClaw và OpenViking, cũng như số tiền tiết kiệm thật sự khác biệt lớn so với chi phí đầu tư OpenViking.

Bảng so sánh nhanh

	API key	Subscription
Giảm chi phí token	✅ Giảm 83% thật	❌ Không giảm bill
Giảm rate limit	✅	✅
Task completion tốt hơn	✅ +50%	✅ +50%
Chi phí thêm (embedding + VLM)	Có, nhưng nhỏ hơn phần tiết kiệm	Có, là chi phí thêm thuần
Nên dùng khi	Token cost > $50/tháng	Hay bị rate limit hoặc cần memory mạnh

Tóm lại: nếu bạn đang trả per-token và token cost đáng kể, OpenViking gần như chắc chắn đáng thử. Nếu dùng subscription, cân nhắc dựa trên nhu cầu memory và mức độ bị rate limit. Với subscription mà không bị limit, các tối ưu cấu hình OpenClaw (heartbeat, cron, compaction) có thể đủ rồi.

💡 Nếu bạn dùng subscription (Claude Pro/Max, ChatGPT Pro), trước khi cài OpenViking hãy thử tối ưu cấu hình OpenClaw trước: heartbeat interval, cron model, compaction, context pruning. Những thay đổi đơn giản này có thể giảm 70% chi phí background tasks mà không cần thêm infra. Xem chi tiết: Tối ưu chi phí OpenClaw: Cách giảm 70% token usage

Tổng kết

Sau bài này bạn đã có:

• OpenViking server chạy ổn định trên cùng VPS với OpenClaw
• OpenClaw dùng OpenViking làm bộ nhớ dài hạn thay cho memory-core mặc định
• Agent có thể lưu, tìm kiếm, và recall memory thông minh hơn với chi phí token thấp hơn nhiều

Stack cuối cùng chạy trên 1 VPS:

• OpenViking: port 1933 (systemd service)
• OpenClaw: port 18789 (gateway)
• Embedding: OpenAI API (text-embedding-3-large)
• VLM: DeepSeek API (deepseek-chat)

Nếu bạn đang dùng OpenClaw và cảm thấy memory chưa đủ thông minh hoặc token cost cao, OpenViking là nâng cấp đáng thử.