本教程介绍如何在 OpenClaw 环境中配置 OpenViking，使用 NVIDIA NIM API 作为 Embedding 和 VLM 后端。

什么是 OpenViking？

OpenViking 是火山引擎开源的 AI Agent 上下文数据库。它用"虚拟文件系统"的方式管理 Agent 的记忆、资源和技能，提供：

• 分层上下文：L0摘要 / L1概览 / L2全文，按需加载节省 Token
• 语义搜索：融合目录定位与向量检索
• 自动摘要：VLM 自动生成文档摘要和概览
• 会话记忆：自动提取对话中的长期记忆

GitHub: https://github.com/volcengine/OpenViking

前置条件

• Python 3.9+
• NVIDIA NIM API Key（免费注册）
• 稳定的网络连接

---

第一步：安装 OpenViking

pip install openviking

---

第二步：创建配置文件

创建目录和配置文件：

mkdir -p ~/.openviking

编辑 ~/.openviking/ov.conf：

{
  "embedding": {
    "dense": {
      "api_base": "https://integrate.api.nvidia.com/v1",
      "api_key": "你的NVIDIA_API_KEY",
      "provider": "openai",
      "dimension": 4096,
      "model": "nvidia/nv-embed-v1"
    }
  },
  "vlm": {
    "api_base": "https://integrate.api.nvidia.com/v1",
    "api_key": "你的NVIDIA_API_KEY",
    "provider": "openai",
    "model": "meta/llama-3.3-70b-instruct"
  }
}

配置说明

参数	说明
api_base	NVIDIA NIM API 端点
api_key	从 NVIDIA Build 平台获取
dimension	Embedding 维度，nv-embed-v1 固定为 4096
embedding.model	推荐使用 nvidia/nv-embed-v1（对称模型，不需要 input_type 参数）
vlm.model	用于生成摘要的语言模型，推荐 meta/llama-3.3-70b-instruct

为什么不用 kimi-k2.5？

NVIDIA 上的推理模型（如 kimi-k2.5）返回的 content 字段为空，内容在 reasoning 字段里。OpenViking 期望标准的 message.content 格式，所以要用非推理模型。

如何获取 NVIDIA API Key

1. 访问 https://build.nvidia.com/
2. 登录/注册账号
3. 点击右上角用户名 → API Keys → Generate Key
4. 复制保存（只显示一次）

---

第三步：设置环境变量

export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf

建议添加到 ~/.bashrc：

echo 'export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf' >> ~/.bashrc
source ~/.bashrc

---

第四步：验证安装

创建测试脚本 test_openviking.py：

import openviking as ov

# 初始化客户端，数据存储在当前目录的 openviking_data 文件夹
client = ov.SyncOpenViking(path="./openviking_data")

try:
    client.initialize()
    print("✅ OpenViking 初始化成功！")
    
    # 添加一个测试文件
    result = client.add_resource(path="./your_file.md")
    print(f"添加文件: {result}")
    
    # 等待处理完成
    print("等待处理...")
    client.wait_processed()
    print("✅ 处理完成！")
    
    # 搜索测试
    results = client.find("测试关键词", limit=3)
    print(f"\n搜索结果:")
    for r in results.resources:
        print(f"  {r.uri} (score: {r.score:.4f})")
    
    client.close()
    print("\n🎉 OpenViking 配置成功！")

except Exception as e:
    print(f"错误: {e}")
    import traceback
    traceback.print_exc()

运行：

python test_openviking.py

---

第五步：核心 API 用法

添加资源

# 添加单个文件
result = client.add_resource(path="./docs/readme.md")

# 添加 URL
result = client.add_resource(path="https://example.com/article.html")

目录浏览

# 列出根目录
ls_result = client.ls("viking://resources")

# 列出子目录
ls_result = client.ls("viking://resources/my_project")

语义搜索

# 搜索相关内容
results = client.find("如何配置 embedding", limit=5)

for r in results.resources:
    print(f"URI: {r.uri}")
    print(f"Score: {r.score}")
    print(f"Content: {client.read(r.uri)[:200]}...")

获取摘要/概览

# L0 层：一句话摘要
abstract = client.abstract("viking://resources/my_project")

# L1 层：详细概览
overview = client.overview("viking://resources/my_project")

读取内容

# 读取完整内容（L2 层）
content = client.read("viking://resources/my_project/readme.md")

---

常见问题

Q: Embedding 维度不匹配

错误: Dense vector dimension mismatch: expected 2048, got 4096

解决: 在配置文件中明确指定 dimension: 4096，匹配 nvidia/nv-embed-v1 的输出维度。

Q: VLM 返回 NoneType 错误

错误: 'NoneType' object is not subscriptable

原因: 使用了推理模型（如 kimi-k2.5），其返回格式与 OpenViking 不兼容。

解决: 换用标准模型如 meta/llama-3.3-70b-instruct。

Q: NVIDIA API 报错 input_type required

错误: 'input_type' parameter is required for asymmetric models

原因: 某些 Embedding 模型（如 nv-embedqa-e5-v5）是非对称模型，需要指定 query 或 document。

解决: 使用对称模型 nvidia/nv-embed-v1，不需要 input_type。

Q: 文件名冲突

错误: directory already exists: /resources/第01章

原因: OpenViking 用文件名（不含路径）作为 URI，不同目录下的同名文件会冲突。

解决:

• 方案一：重命名文件，使用唯一名称
• 方案二：分批导入，避免同时添加同名文件
• 方案三：等待官方修复此设计问题

---

为什么用 OpenViking？——替代 OpenClaw 默认的 qmd 记忆后端

OpenClaw 现有记忆方案的局限

OpenClaw 默认使用 qmd 作为记忆后端，配合手动维护的 MEMORY.md 和 memory/*.md 文件。这套方案够用，但有几个痛点：

1. 搜索精度有限 — qmd 基于简单向量匹配，缺乏层次化理解
2. 手动维护成本高 — 记忆文件需要人工整理，容易遗漏
3. 缺乏自动摘要 — Agent 需要读取整个文件才能了解内容
4. 无法管理大量文档 — 当 workspace 文件很多时，qmd 不够用

OpenViking 的优势

能力	qmd	OpenViking
语义搜索	✅ 基础	✅ 目录递归 + 语义融合
自动摘要	❌	✅ L0/L1/L2 三层
结构化浏览	❌	✅ 虚拟文件系统
Token 节省	❌	✅ 按需加载
会话记忆自动提取	❌	✅ 自动提取长期记忆

集成方式

方式一：作为 OpenClaw 的补充记忆（推荐）

保留 qmd 作为日常轻量记忆，用 OpenViking 管理大型文档库：

# 把 workspace 里的书籍、项目文档等大型资源导入 OpenViking
import glob, openviking as ov

client = ov.SyncOpenViking(path="./openviking_data")
client.initialize()

for f in glob.glob("./books/**/*.md", recursive=True):
    client.add_resource(path=f)

for f in glob.glob("./docs/**/*.md", recursive=True):
    client.add_resource(path=f)

client.wait_processed()
client.close()

Agent 工作流：

1. 日常对话 → qmd 记忆（轻量、快速）
2. 需要查阅文档 → OpenViking 语义搜索（精准、分层）
3. Sub-agent 写作/研究 → OpenViking 提供上下文（节省 Token）

方式二：完全替代 qmd

将 OpenClaw 的所有记忆文件也导入 OpenViking：

# 导入记忆文件
for f in glob.glob("./memory/*.md"):
    client.add_resource(path=f)

# 导入 workspace 所有 markdown
for f in glob.glob("./**/*.md", recursive=True):
    client.add_resource(path=f)

⚠️ 目前 OpenViking 还不能直接作为 OpenClaw 的 memory.backend 配置项。需要通过 skill 的 CLI 工具间接调用。未来如果 OpenClaw 支持自定义记忆后端插件，可以更深度集成。

方式三：给 Sub-agent 提供上下文

写书、做研究等任务时，sub-agent 可以先搜索 OpenViking 获取相关上下文，而不是把整本书塞进 prompt：

# Sub-agent 先搜索相关内容
python3 scripts/viking.py search "武松的性格分析" --limit 3

# 然后只读取最相关的段落
python3 scripts/viking.py read viking://resources/第01章/张三的叙事.md

这样一个 sub-agent 只需要加载几千 token 的相关内容，而不是整本书的 10 万+ token。

已封装的 OpenClaw Skill

我们已经把 OpenViking 封装为 OpenClaw skill，安装后 Agent 可以直接使用：

# 安装 skill
git clone https://github.com/swizardlv/openclaw_openviking_skill.git
cp -r openclaw_openviking_skill/openviking ~/.openclaw/workspace/skills/

Skill 提供的命令：

命令	功能
viking.py add <file>	索引文件
viking.py add-dir <dir>	批量索引目录
viking.py search <query>	语义搜索
viking.py ls [uri]	浏览资源
viking.py abstract <uri>	获取摘要
viking.py overview <uri>	获取概览
viking.py read <uri>	读取全文
viking.py info	查看配置状态

---

附录：可用的 NVIDIA Embedding 模型

模型	维度	类型	说明
nvidia/nv-embed-v1	4096	对称	✅ 推荐，无需 input_type
nvidia/nv-embedqa-e5-v5	1024	非对称	需要 input_type 参数
nvidia/llama-3.2-nv-embedqa-1b-v2	2048	非对称	需要 input_type 参数
nvidia/nv-embedcode-7b-v1	4096	对称	适合代码

---

附录：可用的 NVIDIA Chat 模型（用于 VLM）

模型	说明
meta/llama-3.3-70b-instruct	✅ 推荐，标准格式
meta/llama-3.1-70b-instruct	稳定版本
meta/llama-3.1-8b-instruct	轻量版
mistralai/mistral-large	Mistral 系列

⚠️ 避免使用推理模型（如 kimi-k2.5、deepseek-r1），它们返回的格式与 OpenViking 不兼容。

---

参考链接

• OpenViking 官网: https://www.openviking.ai
• OpenViking GitHub: https://github.com/volcengine/OpenViking
• NVIDIA NIM API: https://build.nvidia.com/
• NVIDIA API 文档: https://docs.api.nvidia.com/nim/

---

本教程基于 OpenViking 0.1.17 和 NVIDIA NIM API 测试通过。