0. 前言

随着大型语言模型 (LLM) 的普及，隐私保护和长期记忆能力成为个人 AI 助理（Personal Agent）发展的关键瓶颈。如果将所有对话历史和私有文档都通过 API 上传给云端模型，不仅存在隐私风险，还会带来高昂的 API 调用成本。

本文将分享一套零隐私泄漏、全链路本地化推理与存储的 AI Agent 架构最佳实践。我们将充分利用 Mac mini (M系列芯片) 强大的统一内存架构 (UMA)，部署 OpenClaw 网关、Ollama 本地向量库以及 OpenViking 智能记忆引擎，构建一个懂你、听话且永远不会忘记的本地“第二大脑”。

---

1. 深度原理解析：双脑混合架构

1.1 组件职能划分

• 大脑 (VLM - 推理层)：负责逻辑推理和对话生成。本方案选用内网服务器运行 MiniMax-m2.5。
• 小脑 (Embedding - 向量化层)：负责将非结构化文本转化为向量。部署在 Mac mini 本地，由 Ollama (bge-m3) 驱动，利用 Metal 算力实现极低延迟。
• 海马体 (Storage & Management - 记忆层)：核心组件 OpenViking。它摒弃了传统的碎片化向量切片，采用 Agent-native 文件系统范式，将记忆结构化为 Markdown 文件。

1.2 高层技术架构图

---

2. 交互时序图：一问一答背后的记忆检索

为了实现“跨会话”记忆，Bot 在回复前会经历一次隐性的“预检索”：

---

3. 记忆管理解析：OpenViking 的“文件系统”范式

OpenViking 将所有记忆视为磁盘上的文件，分为三层级联（L0/L1/L2）：

• L0 Session (缓冲区)：实时的 JSONL 对话记录，用于维持瞬时对话连贯性。
• L1 Knowledge (提炼区)：通过 commit 操作，Agent 会自动将对话总结成 Markdown 格式，按 entities（实体）、events（事件）、preferences（偏好）归类。
• L2 Disk (落盘区)：真正的物理存储。修改磁盘上的 Markdown，就等于直接修改 Bot 的记忆。

---

4. 最佳实践配置部署

4.1 环境准备

使用 pyenv 隔离 Python 3.11 环境，防止 macOS 系统版本干扰：

pyenv which python
# 获取绝对路径: /Users/david/.pyenv/versions/3.11.12/bin/python

4.2 深度调优配置 (ov.conf)

修改 ~/.openviking/ov.conf，将本地 Ollama 与内网 VLM 结合。注意：务必调大超时时间以适应本地向量化耗时。

{
  "embedding": {
    "dense": {
      "backend": "openai",
      "api_key": "ollama",
      "model": "bge-m3",
      "api_base": "http://127.0.0.1:11434/v1",
      "dimension": 1024
    }
  },
  "vlm": {
    "backend": "openai",
    "api_key": "sk-local",
    "model": "minimax-m2.5",
    "api_base": "http://10.10.x.x:8000/v1"
  },
  "storage": {
    "agfs": {
      "timeout": 60 // 最佳实践：调大至 60s 防止自动捕获超时
    }
  }
}

4.3 环境变量“天坑”修复

由于后台服务 LaunchAgent 读不到用户环境变量，需强制指定插件 Python 路径：

echo 'export OPENVIKING_PYTHON="/Users/david/.pyenv/versions/3.11.12/bin/python"' > ~/.openclaw/openviking.env
echo 'export OPENVIKING_EXECUTABLE="/Users/david/.pyenv/versions/3.11.12/bin/openviking-server"' >> ~/.openclaw/openviking.env

---

5. 效果验证与可视化运维

5.1 查看记忆目录树

运行 ov tree 命令，查看 Agent 自动生成的结构化记忆：

ov tree viking://user/default/memories -L 2

预期输出：

viking://user/default/memories/
├── entities/ (项目/人名/地点)
│   └── mem_b708...md (OpenViking 项目简介)
├── events/ (发生的事件)
│   └── mem_2a6c...md (用户正在进行部署测试)
└── preferences/ (沟通偏好)
    └── mem_6f38...md (用户偏好简短的中文回复)

5.2 使用 TUI 进行图形化管理 (推荐)

OpenViking 提供了一个极具极客感的 TUI (Terminal User Interface) 界面，可直接在终端里预览和搜索记忆：

ov tui viking://user/default/memories

• 操作流：使用方向键移动，Enter 预览，q 退出。
• 分层预览：右侧会显示 AI 自动生成的 Abstract (摘要) 和 Overview (概览)，帮助你在不读取全文的情况下快速定位记忆点。

5.3 自动化交互测试

• 输入：钉钉发送“我最近在研究什么项目？”
• 响应：Bot 通过 AutoRecall 命中 entities/mem_b708...md。
• 回复：“记得，你正在研究 OpenViking 系统，这是一个专门为我设计的长期记忆管理方案。”

---

6. 进阶 Tip：安全与优化

1. 权限控制：OpenClaw 默认群权限为 open。为保护 AGFS 文件系统，建议在 Dashboard 中修改为 allowlist 模式。
2. 强制持久化：如果 Bot 记忆反应迟钝，可手动执行：ov session commit <SESSION_ID>。
3. 自愈能力：通过 openclaw gateway install 注册为服务，确保 Mac mini 重启后 Agent 自动拉起。

---