OpenClaw + OpenViking 多 Agent 记忆系统架构实践

[Clivilwalker]

OpenClaw + OpenViking 多 Agent 记忆系统架构实践

🎯 项目背景

在构建多 Agent AI 系统时，我们面临一个核心挑战：如何让每个 Agent 拥有独立的记忆空间，同时又能共享团队知识？

本分享记录了我们从 LanceDB-Pro 迁移到 OpenViking 的完整过程，包括踩过的坑和最终解决方案。

---

🤔 为什么选择 OpenViking？

背景：OpenViking 的设计定位

OpenViking 是字节跳动开源的个人知识库系统，设计初衷是：

• 单用户个人知识管理
• 统一的记忆空间（viking://resources/）
• 基于会话（session）的记忆提取

我们的场景：多 Agent 企业系统

我们的需求与 OpenViking 原始设计存在差异：

维度	OpenViking 原始设计	我们的需求
用户模型	单用户个人使用	多 Agent 协作
记忆隔离	无隔离，统一空间	Agent 间需要隔离
存储方式	Session-based（调用 VLM）	直接存储（避免超时）
共享需求	无	需要 Global 共享空间

为什么仍选择 OpenViking？

尽管存在差异，OpenViking 仍是最优选择：

1. 字节跳动官方维护：持续更新，稳定性有保障
2. 任务完成率提升 49%（相比 LanceDB-Pro）
3. Token 成本降低 83%
4. 无 Registry 状态隔离问题（LanceDB-Pro 的 bug）
5. HTTP API 灵活：可以通过二次开发满足多 Agent 需求

核心思路：利用 OpenViking 的 HTTP API，在其之上构建多 Agent 隔离层。

---

🖥️ 部署环境

服务器配置

- OS: Linux (OpenCloudOS 9)
- CPU: x86_64
- OpenViking: v0.2.6
- OpenClaw: 2026.3.12
- Node.js: v22.22.0

服务架构

┌─────────────────────────────────────────┐
│           OpenClaw Gateway              │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐  │
│  │ Agent 1 │ │ Agent 2 │ │ Agent N │  │
│  └────┬────┘ └────┬────┘ └────┬────┘  │
│       └─────────────┼─────────────┘    │
│                     ↓                   │
│         memory-openviking Plugin        │
└─────────────────────┬───────────────────┘
                      ↓ HTTP API
┌─────────────────────────────────────────┐
│           OpenViking Server             │
│  ┌─────────────────────────────────┐    │
│  │  viking://resources/            │    │
│  │  ├── agents/{id}/memories/  ←───┼────┤
│  │  └── global/memories/       ←───┼────┤
│  └─────────────────────────────────┘    │
│                                         │
│  - Embedding: {EMBEDDING_PROVIDER} / Ollama     │
│  - VLM: {VLM_MODEL} (optional)     │
│  - Vector DB: VikingDB                  │
└─────────────────────────────────────────┘

关键配置

OpenViking 配置 (~/.openviking/ov.conf):

{
  "embedding": {
    "dense": {
      "provider": "openai",
      "api_base": "{API_BASE_URL}",
      "api_key": "YOUR_API_KEY",
      "model": "{EMBEDDING_MODEL}",
      "dimension": {EMBEDDING_DIMENSION}
    }
  },
  "vlm": {
    "provider": "openai",
    "api_base": "{API_BASE_URL}",
    "api_key": "YOUR_API_KEY",
    "model": "{VLM_MODEL}"
  }
}

OpenClaw 配置 (~/.openclaw/openclaw.json):

{
  "plugins": {
    "entries": {
      "memory-openviking": {
        "config": {
          "mode": "remote",
          "baseUrl": "http://127.0.0.1:1933",
          "timeoutMs": 60000,
          "autoCapture": false,
          "autoRecall": false
        }
      }
    }
  }
}

---

🏗️ 架构设计

目标架构

viking://resources/
├── agents/                    # 各 Agent 独立空间
│   ├── main/memories/         # 主 Agent
│   ├── writer/memories/       # 写作 Agent
│   ├── researcher/memories/   # 研究 Agent
│   └── ...                    # 其他 Agents
└── global/memories/           # 团队共享空间

核心需求

1. 物理隔离：每个 Agent 的记忆存储在独立路径
2. 逻辑隔离：Agent 只能搜索自己的记忆 + 共享记忆
3. 自动路由：根据 Agent ID 自动选择存储位置
4. 无 VLM 依赖：存储记忆时不调用 VLM（避免超时）

---

🛠️ 技术栈对比

迁移前后对比

组件	之前 (LanceDB-Pro)	之后 (OpenViking)	原因
向量数据库	LanceDB-Pro	OpenViking (VikingDB)	避免 Registry bug
Embedding	本地	{EMBEDDING_PROVIDER} / Ollama	质量更好
VLM	无	{VLM_MODEL}	可选，用于 session extract
存储方式	直接存储	直接 HTTP API	绕过 VLM 超时
Agent 隔离	无	路径隔离	自定义实现

为什么选择放弃 LanceDB-Pro？

致命问题：OpenClaw Core 的 Registry 状态隔离 bug

• LanceDB-Pro 是 slot 插件
• 工具注册到错误的 registry 实例
• 导致 memory_store/memory_recall 无法调用

OpenViking 优势：

• 非 slot 插件，无 Registry 问题
• 字节跳动官方维护
• 更好的性能和稳定性

---

🚀 实施步骤

1. 安装 OpenViking

# 安装 OpenViking
pip install openviking

# 配置服务
systemctl enable --user openviking
systemctl start --user openviking

2. 配置 OpenClaw Plugin

{
  "plugins": {
    "entries": {
      "memory-openviking": {
        "config": {
          "mode": "remote",
          "baseUrl": "http://127.0.0.1:1933",
          "timeoutMs": 60000,
          "autoCapture": false,
          "autoRecall": false
        }
      }
    }
  }
}

3. 创建目录结构

# 创建各 Agent 的记忆目录
ov mkdir viking://resources/agents/main/memories
ov mkdir viking://resources/agents/writer/memories
ov mkdir viking://resources/agents/researcher/memories

# 创建共享空间
ov mkdir viking://resources/global/memories

4. 修改 Plugin 源码

关键修改 1：绕过 VLM 超时

原始代码使用 session extract（会调用 VLM），改为直接 HTTP API：

// 改为直接 HTTP API 存储
const response = await fetch(`${cfg.baseUrl}/api/v1/resources`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ 
    path: tmpFile, 
    to: targetUri,        // 注意：使用 "to" 而不是 "target"
    reason: `Memory from agent ${agentId}`,
  }),
});

关键修改 2：动态路径构建

const agentId = c.getAgentId() || "main";
const targetUri = `viking://resources/agents/${agentId}/memories/memory_${Date.now()}.md`;

关键修改 3：搜索范围限定

// 只搜索当前 Agent + Global + User
const [agentSettled, globalSettled, userSettled] = await Promise.allSettled([
  client.find(query, {
    targetUri: `viking://resources/agents/${agentId}/memories`,
  }),
  client.find(query, {
    targetUri: "viking://resources/global/memories",
  }),
  client.find(query, {
    targetUri: "viking://user/memories",
  }),
]);

---

😭 踩过的坑

坑 1：VLM 超时

现象：memory_store 调用 60 秒后超时

原因：OpenViking 默认使用 session extract，会调用 VLM 生成摘要

解决：改为直接 HTTP API 存储，不经过 session extract

坑 2：参数名不一致

现象：指定了 target 参数，但存储路径不符合预期

原因：OpenViking 文档声明使用 target，但实际代码使用 to

// 文档说用 "target"
// 实际代码用 "to"
let body = serde_json::json!({
    "temp_path": temp_path,
    "to": to,  // ← 实际用的是这个
    ...
});

解决：使用 "to" 参数

坑 3：Plugin 语法错误

现象：修改后 Plugin 加载失败，提示 Unexpected token

原因：替换代码时括号不匹配

解决：使用行号精确替换，仔细验证语法

---

✅ 验证结果

测试 1：Main Agent 存储

输入："Main Agent 测试记忆"
输出：Stored memory to viking://resources/agents/main/memories/memory_xxx.md
✅ 成功存储到 main 空间

测试 2：Writer Agent 存储

输入："Writer Agent 测试记忆"
输出：Stored memory to viking://resources/agents/writer/memories/memory_xxx.md
✅ 成功存储到 writer 空间

测试 3：隔离验证

# Main Agent 只能搜索到 main + global 的记忆
# Writer Agent 只能搜索到 writer + global 的记忆
✅ 隔离机制正常工作

---

📊 最终架构

OpenClaw Gateway
    │
    ├── Agent: main
    │   └── memory_store → viking://resources/agents/main/memories/
    │
    ├── Agent: writer
    │   └── memory_store → viking://resources/agents/writer/memories/
    │
    ├── Agent: researcher
    │   └── memory_store → viking://resources/agents/researcher/memories/
    │
    └── Global Space
        └── viking://resources/global/memories/

---

🎁 关键代码片段

存储记忆（HTTP API）

async function storeMemory(text: string, agentId: string) {
  const tmpFile = `/tmp/memory_${Date.now()}.txt`;
  fs.writeFileSync(tmpFile, text, "utf-8");
  
  const targetUri = `viking://resources/agents/${agentId}/memories/memory_${Date.now()}.md`;
  
  const response = await fetch("http://127.0.0.1:1933/api/v1/resources", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ 
      path: tmpFile, 
      to: targetUri,  // 关键：使用 "to" 而不是 "target"
      reason: `Memory from agent ${agentId}`,
    }),
  });
  
  fs.unlinkSync(tmpFile);
  return response.json();
}

搜索记忆

async function recallMemory(query: string, agentId: string) {
  const results = await Promise.allSettled([
    // Agent 私人空间
    client.find(query, {
      targetUri: `viking://resources/agents/${agentId}/memories`,
    }),
    // Global 共享空间
    client.find(query, {
      targetUri: "viking://resources/global/memories",
    }),
    // User 空间
    client.find(query, {
      targetUri: "viking://user/memories",
    }),
  ]);
  
  return mergeResults(results);
}

---

💡 经验总结

1. 文档不一定对：OpenViking 文档说用 target，实际要用 to
2. 看源码最靠谱：遇到参数问题，直接看 CLI 源码确认
3. 语法要小心：TypeScript 的括号匹配容易出错，建议用工具验证
4. 测试要完整：不仅要测试存储，还要测试隔离性