OpenViking 上下文数据库

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

Security Scan

The skill's requirements, scripts, and runtime behavior are generally consistent with its stated purpose (integrating OpenViking for layered context loading), but there are a few implementation quirks and privacy/usability issues you should be aware of before installing.

Purpose & Capability

The name/description (OpenViking context DB, L0/L1/L2, semantic search, token tracking) match the included files (CLI wrapper, installer, config helper, demo). Requested packages (openviking) and runtime behavior (adding/searching/reading resources, embedding/VLM calls) are coherent with the stated purpose.

Instruction Scope

SKILL.md and scripts instruct the agent/user to install openviking, run openviking-server, and use the provided CLI wrapper to add/search/read resources. The scripts read and write files under the user's home (~/.openviking, ~/.openviking/session_stats.json) and will recursively ingest files from directories you point them at — this means sensitive local files could be added if you run 'add' on broad paths. The setup is interactive and explicitly asks for API keys; it persists them to a plain-text config file.

Install Mechanism

No platform install spec in skill metadata (instruction-only), but included scripts call 'pip install openviking' and optionally run cargo or curl to a GitHub raw install script for the Rust CLI. pip and GitHub raw URLs are common for open-source installs, but running curl|bash and forced pip reinstall have moderate risk and should be done only after reviewing the upstream sources.

Credentials

The skill does not declare required env vars up-front, but the interactive setup prompts for a model API Key and writes it into ~/.openviking/ov.conf in plain text. It also appends export lines to shell rc files for OPENVIKING_CONFIG_FILE/OPENVIKING_CLI_CONFIG_FILE. These are expected for a tool that uses remote model APIs, but storing API keys unencrypted in home config files is a privacy risk and should be considered.

Persistence & Privilege

The skill writes files into the user's home (~/.openviking/* and ~/.openviking/session_stats.json) and copies itself into the OpenClaw skills directory on install. It modifies shell rc to export config file paths. always:false and normal autonomous invocation defaults are preserved. These persistence actions are reasonable for this type of integration but they do create persistent local state and stored API credentials.

Assessment

This skill appears to be what it claims (an OpenViking integration), but review and take these precautions before installing: - Inspect the installer scripts and upstream projects: pip install openviking and the optional curl|bash install for the Rust CLI fetch code from external sources (PyPI and GitHub). Confirm you trust the upstream repositories before running them. - Be careful when running 'python3 scripts/viking.py add <dir>': the add command will recurse and add many file types — avoid pointing it at home or other directories that may contain private keys, credentials, or sensitive data. - The setup writes your API key in plaintext to ~/.openviking/ov.conf and appends export lines to your shell rc; if you prefer, set those env vars manually or store secrets in a safer vault and reference them when needed. - Consider running the install/setup in an isolated environment (VM/container) first, or at least inspect ~/.openviking/ov.conf and ~/.openviking/session_stats.json after configuration. - Note a minor bug/inconsistency in scripts: the interactive setup sets some provider variables incorrectly in one branch (e.g., VLM provider selection for the NVIDIA choice). This looks like a scripting bug rather than malicious behavior — review the generated ov.conf before use. If you are comfortable with these tradeoffs and trust the OpenViking upstream, the skill is coherent; if you need stronger assurance, ask the skill author for commit hashes or verify the exact openviking package/source prior to installation.

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 不兼容。

启动服务器

openviking-server
# 或后台运行：
nohup openviking-server > ~/.openviking/server.log 2>&1 &

核心操作

通过 scripts/viking.py 与 OpenViking 交互：

python3 scripts/viking.py <command> [args]

命令	功能	示例
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
服务连接失败	服务器未启动	运行 openviking-server

参考

• OpenViking GitHub
• OpenViking 官网
• LiteLLM 提供商文档
• NVIDIA NIM API