openviking-token-saver OpenClaw Skill

OpenViking context database for AI agents — layered context loading (L0/L1/L2), semantic search, file-system memory management. Use when: (1) setting up Open...

v2.2.0 Recently Updated Updated Today

Installation

clawhub install openviking-token-saver

Requires npm i -g clawhub

View on ClawHub Download .zip

155

Downloads

0

Stars

0

current installs

0 all-time

4

Versions

EU EU-Hosted Inference API

Power your OpenClaw skills with the best open-source models.

Drop-in OpenAI-compatible API. No data leaves Europe.

Explore Inference API

GLM

GLM 5

$1.00 / $3.20

per M tokens

Kimi

Kimi K2.5

$0.60 / $2.80

per M tokens

MiniMax

MiniMax M2.5

$0.30 / $1.20

per M tokens

Qwen

Qwen3.5 122B

$0.40 / $3.00

per M tokens

OpenViking Context Database

字节跳动开源的 Agent 上下文数据库。通过 viking:// 文件系统协议统一管理记忆、资源和技能，L0/L1/L2 三层按需加载，token 消耗降低 83-96%。

能力 说明
文件系统协议 viking:// 统一管理 resources/user/agent 三类上下文
L0/L1/L2 分层 摘要(100 tokens) / 概览(2k tokens) / 全文，按需加载
语义检索 目录递归检索 + 向量匹配
会话记忆 自动提取长期记忆，跨会话保持
Token 节省 对比全量加载，输入 token 降低 83%~96%

安装到 OpenClaw

bash scripts/install-skill.sh

脚本会将 skill 复制到 OpenClaw 的 skills 目录（自动检测路径），然后在 OpenClaw 中说 "refresh skills" 即可发现。

安装 OpenViking 依赖

skill 安装完成后，运行以下命令安装 OpenViking 本体：

bash scripts/install.sh

自动检测 Python >= 3.10，安装 openviking 包，创建工作目录，可选安装 Rust CLI (ov)。

配置

bash scripts/setup-config.sh

支持的模型提供商：

提供商 VLM 模型 Embedding 模型
openai gpt-4o text-embedding-3-large (dim=3072)
volcengine doubao-seed-2-0-pro-260215 doubao-embedding-vision-250615 (dim=1024)
litellm claude-3-5-sonnet / deepseek-chat —
NVIDIA NIM meta/llama-3.3-70b-instruct nvidia/nv-embed-v1 (dim=4096)

注意：避免使用推理模型 (kimi-k2.5, deepseek-r1)，它们的 reasoning 字段与 OpenViking 不兼容。

第一次使用完整流程

首次安装时，按顺序执行以下步骤：

Step 1 — 安装依赖

bash ~/.openclaw/workspace/skills/openviking-token-saver/scripts/install.sh

自动检测 Python >= 3.10，创建 venv，安装 openviking 包

Step 2 — 配置 API Key

bash ~/.openclaw/workspace/skills/openviking-token-saver/scripts/setup-config.sh

交互式配置 VLM 和 Embedding 的 API Key、模型、API 地址

Step 3 — 验证安装

/Users/wuguanhua/.openviking/venv/bin/python3 ~/.openclaw/workspace/skills/openviking-token-saver/scripts/viking.py info

确认 ov.conf 配置正确，服务可连接

Step 4 — 添加资源

/Users/wuguanhua/.openviking/venv/bin/python3 ~/.openclaw/workspace/skills/openviking-token-saver/scripts/viking.py add ./你的项目文档路径/

Step 5 — 开始搜索

/Users/wuguanhua/.openviking/venv/bin/python3 ~/.openclaw/workspace/skills/openviking-token-saver/scripts/viking.py search "关键词"

⚠️ 所有 viking.py 命令都必须用 ~/.openviking/venv/bin/python3，不能用系统 python3

启动服务器（可选）

scripts/viking.py 支持 direct mode（直接访问数据文件，不需要服务器）。服务器仅在使用 Web UI 时才需要。

# 启动 API 服务器（后台运行）
nohup ~/.openviking/venv/bin/openviking-server > ~/.openviking/server.log 2>&1 &

# 启动 Console Web UI（后台运行）
nohup ~/.openviking/venv/bin/python3 -m openviking.console.bootstrap \
  --host 127.0.0.1 --port 8020 \
  --openviking-url http://127.0.0.1:1933 \
  > ~/.openviking/console.log 2>&1 &

# API 文档地址
open http://localhost:1933/docs

# Console Web UI 地址
open http://localhost:8020

何时需要服务器：

  • 需要 Web UI 管理界面 → 必须启动 API server + Console
  • 只需要 scripts/viking.py 做 search/add/read → 不需要，direct mode 已够用

核心操作

通过 scripts/viking.py 与 OpenViking 交互（direct mode，不需要服务器）：

/Users/wuguanhua/.openviking/venv/bin/python3 scripts/viking.py <command> [args]

⚠️ 重要：必须使用 venv 中的 Python（3.11），系统 Python 3.9 不支持 openviking。

命令 功能 示例
add <path_or_url> 添加资源（文件/URL/目录） viking.py add ./docs/
search <query> 语义搜索 viking.py search "认证逻辑"
ls [uri] 浏览资源目录 viking.py ls viking://resources/
tree [uri] 树形展示 viking.py tree viking://resources/ -L 2
abstract <uri> L0 摘要 (~100 tokens) viking.py abstract viking://resources/proj
overview <uri> L1 概览 (~2k tokens) viking.py overview viking://resources/proj
read <uri> L2 全文 viking.py read viking://resources/proj/api.md
info 检查服务状态 viking.py info
commit 提取当前会话记忆 viking.py commit
stats 查看 token 消耗统计 viking.py stats
stats --reset 重置统计数据 viking.py stats --reset

Token 消耗追踪

每次调用 search、abstract、overview、read 时自动追踪：

  • 实际消耗：本次分层加载实际使用的 token 数
  • 全量假设：如果用传统方式全量加载同一资源需要的 token 数
  • 节省量：两者差值和百分比

每次命令结尾自动输出一行会话累计摘要：

📊 会话累计 | 实际: 2,300 tokens | 全量: 48,000 tokens | 节省: 45,700 (95.2%)

使用 stats 命令查看完整的逐操作明细表：

python3 scripts/viking.py stats

输出示例：

═══ Token 消耗统计 ═══
  会话开始: 2026-03-19 19:30:00
  操作次数: 4

  #    时间       操作       层级  实际     全量     节省     URI
  ──── ────────── ────────── ───── ──────── ──────── ──────── ──────────────────
  1    19:30:05   search     L0        300   48,000   47,700  用户认证 鉴权
  2    19:30:12   overview   L1      1,800   15,000   13,200  viking://resources/auth
  3    19:30:18   abstract   L0         80    8,000    7,920  viking://resources/db
  4    19:30:25   read       L2      3,200    3,200        0  viking://resources/auth/jwt

  ┌─────────────────────────────────────┐
  │  全量加载 (传统方式):     74,200 tokens │
  │  实际消耗 (分层加载):      5,380 tokens │
  │  节省 token 数量:        68,820 tokens │
  │  节省比例:                  92.8%        │
  └─────────────────────────────────────┘

统计数据持久化在 ~/.openviking/session_stats.json，跨命令调用累积。新会话可用 stats --reset 重置。

分层加载工作流

收到开发需求（如"帮我写一个用户认证模块"）时：

Step 1 — L0 快速扫描（~300 tokens）

python3 scripts/viking.py search "用户认证 鉴权 登录"

用 L0 摘要判断哪些资源相关，过滤无关内容。

Step 2 — L1 概览决策（~2k tokens/资源）

python3 scripts/viking.py overview viking://resources/auth-docs

理解架构和技术选型，制定实现计划。

Step 3 — L2 按需深读（仅必要文件）

python3 scripts/viking.py read viking://resources/auth-docs/jwt-config.md

只加载写代码需要的具体文件。

Token 对比演示

python3 scripts/demo-token-compare.py ./your-project-docs/
方案 Token 消耗 说明
全量加载 (传统 RAG) ~50,000 所有文档塞进 prompt
L0 扫描 + L1 概览 ~3,000 分层按需，仅摘要和概览
L0 + L1 + L2 按需 ~8,000 最终只深读 2-3 个必要文件
节省比例 84%~94% 相比全量加载

故障排查

问题 原因 解决
Dense vector dimension mismatch embedding 维度配置错误 检查 ov.conf 中的 dimension 与模型匹配
NoneType is not subscriptable 使用了推理模型 换用 gpt-4o 或 llama-3.3-70b
input_type required 使用了非对称 embedding 换用对称模型如 nvidia/nv-embed-v1
搜索无结果 语义处理未完成 添加资源后等待：viking.py add --wait
服务连接失败 服务器未启动 运行 nohup ~/.openviking/venv/bin/openviking-server > ~/.openviking/server.log 2>&1 &
Embedding failed: No embedding data embedding API 调用失败 确认 ov.conf 中 key 有 embedding 权限；检查余额；确认模型名为 embo-01 且 provider 为 openai
python3: command not found 或 No module named openviking 系统 Python 版本不对 必须用 ~/.openviking/venv/bin/python3，不要用系统 python3

参考

Statistics

Downloads 155
Stars 0
Current installs 0
All-time installs 0
Versions 4
Comments 0
Created Mar 18, 2026
Updated Apr 6, 2026

Latest Changes

v2.2.0 · Mar 27, 2026

修复 Python 路径问题；优化 token 对比输出格式；更新触发词（支持中文）；完善 SKILL.md 文档；Console Web UI 启动说明

Quick Install

clawhub install openviking-token-saver

Related Skills

Other popular skills you might find useful.

MaTriXy

Agent Browser

MaTriXy

Headless browser automation CLI optimized for AI agents with accessibility tree snapshots and ref-based element selection

72.6k 271 v0.1.0
peytoncasper

Browser Automation

peytoncasper

Automate web browser interactions using natural language via CLI commands. Use when the user asks to browse websites, navigate web pages, extract data from websites, take screenshots, fill forms, click buttons, or interact with web applications.

32.4k 46 v1.0.1
Iván

Code

Iván

Coding workflow with planning, implementation, verification, and testing for clean software development.

18.8k 36 v1.0.4
peytoncasper

Agent Browser - Stagehand

peytoncasper

Automate web browser interactions using natural language via CLI commands. Use when the user asks to browse websites, navigate web pages, extract data from websites, take screenshots, fill forms, click buttons, or interact with web applications.

6.4k 4 v1.0.0
Browse all skills →
EU Made in Europe

Chat with 100+ AI Models in one App.

Use Claude, ChatGPT, Gemini alongside with EU-Hosted Models like Deepseek, GLM-5, Kimi K2.5 and many more.

Start for free View pricing