OpenViking Context Database

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

能力	说明
文件系统协议	INLINECODE1 统一管理 resources/user/agent 三类上下文
L0/L1/L2 分层

摘要(~100 tokens) / 概览(~2k tokens) / 全文，按需加载 |
| 语义检索 | 目录递归检索 + 向量匹配 |
| 会话记忆 | 自动提取长期记忆，跨会话保持 |
| Token 节省 | 对比全量加载，输入 token 降低 83%~96% |

安装到 OpenClaw

CODEBLOCK0

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

安装 OpenViking 依赖

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

CODEBLOCK1

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

配置

CODEBLOCK2

支持的模型提供商：

提供商	VLM 模型	Embedding 模型
INLINECODE4	gpt-4o	text-embedding-3-large (dim=3072)
INLINECODE5

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 — 添加资源
CODEBLOCK6

Step 5 — 开始搜索
CODEBLOCK7

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

启动服务器（可选）

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

CODEBLOCK8

何时需要服务器：

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

核心操作

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

CODEBLOCK9

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

命令	功能	示例
INLINECODE14	添加资源（文件/URL/目录）	INLINECODE15
INLINECODE16

语义搜索 | 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 数
• 节省量：两者差值和百分比

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

CODEBLOCK10

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

CODEBLOCK11

输出示例：

CODEBLOCK12

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

分层加载工作流

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

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

CODEBLOCK13

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

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

CODEBLOCK14

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

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

CODEBLOCK15

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

Token 对比演示

CODEBLOCK16

方案	Token 消耗	说明
全量加载 (传统 RAG)	~50,000	所有文档塞进 prompt
L0 扫描 + L1 概览

~3,000 | 分层按需，仅摘要和概览 |
| L0 + L1 + L2 按需 | ~8,000 | 最终只深读 2-3 个必要文件 |
| 节省比例 | 84%~94% | 相比全量加载 |

故障排查

问题	原因	解决
INLINECODE43	embedding 维度配置错误	检查 ov.conf 中的 dimension 与模型匹配
INLINECODE44

使用了推理模型 | 换用 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 |

参考

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