OpenClaw+OpenViking + NVIDIA API 配置教程

本教程介绍如何在 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

bash 复制代码

pip install openviking

第二步：创建配置文件

创建目录和配置文件：

bash 复制代码

mkdir -p ~/.openviking

编辑 ~/.openviking/ov.conf：

json 复制代码

{
  "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

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

第三步：设置环境变量

bash 复制代码

export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf

建议添加到 ~/.bashrc：

bash 复制代码

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

第四步：验证安装

创建测试脚本 test_openviking.py：

python 复制代码

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()

运行：

bash 复制代码

python test_openviking.py

第五步：核心 API 用法

添加资源

python 复制代码

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

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

目录浏览

python 复制代码

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

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

语义搜索

python 复制代码

# 搜索相关内容
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]}...")

获取摘要/概览

python 复制代码

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

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

读取内容

python 复制代码

# 读取完整内容（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 文件。这套方案够用，但有几个痛点：

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

OpenViking 的优势

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

集成方式

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

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

python 复制代码

# 把 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 工作流：

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

方式二：完全替代 qmd

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

python 复制代码

# 导入记忆文件
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：

bash 复制代码

# 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 可以直接使用：

bash 复制代码

# 安装 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 测试通过。