360 Secure SkillHub
360 安全技能中心

OpenViking 上下文数据库

为 AI Agent 提供 OpenViking 上下文数据库能力：安装脚本部署 OpenViking 与模型提供商配置，通过 viking:// 文件系统管理资源、用户与 Agent 记忆，支持 L0/L1/L2 分层按需加载、语义检索、会话记忆提取以及 token 消耗统计对比。主要面向 OpenClaw 宿主。

onlyonepice
onlyonepice
热度 70.51
最近更新 2026-05-17 15:36:37
分类：知识依赖：代码执行 / 读写文件 / 第三方 API / 内部调用大模型应用场景：研究 / 笔记整理 / 工作流 / API 集成 ...

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add openviking-context
Metadata
name
openviking-context
description
OpenViking context database for AI agents — layered context loading (L0/L1/L2), semantic search, file-system memory management. Use when setting up OpenViking, managing agent memory/resources, performing semantic search, browsing context filesystem, or comparing token consumption. Triggers on: 'openviking', 'context database', 'viking memory', 'layered context', 'token saving', 'L0/L1/L2', 'viking://', 'memsearch', 'memread', 'context setup'.

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

参考