OpenViking 长篇教程：给 AI Agent 建一个真正可用的上下文数据库

AI Agent 真正进入长期工作流以后，最先暴露的短板往往不是模型能力，而是上下文没有地方安放。项目文档、用户记忆、Agent Skills、历史会话、工具轨迹和 RAG 片段分散在不同系统里，短期能靠 prompt 拼起来，时间一长就会变成不可追踪、不可治理、不可复用的上下文债务。

volcengine/OpenViking 解决的正是这层基础设施问题。它不是普通向量库，也不是单纯的文档问答应用，而是面向 AI Agent 的 Context Database：用 viking:// 文件系统、L0/L1/L2 分层、MCP 接入和会话归档，把 Agent 运行中需要的 memory、resources、skills、sessions、tool traces 统一放进一套可寻址、可检索、可观测的上下文系统里。

先说结论：OpenViking 想做的是 Agent 的上下文硬盘

传统 RAG 的思路通常是：文档切块，生成 embedding，放进向量库，问题来了做 top-k 检索。这条链路能解决很多知识问答，但对 Agent 来说还不够。Agent 不只需要“找一段相似文本”，还需要知道某个资源在哪里、它属于哪个项目、和哪些会话相关、应该先读摘要还是全文、技能和记忆能不能一起检索、检索过程为什么返回这些内容。

OpenViking 的核心设计是文件系统范式。它用 viking:// URI 组织上下文，把资源、用户记忆、Agent 能力、会话记录等都放进统一命名空间。这样 Agent 不再只是在黑盒向量库里捞 chunk，而是可以像浏览目录一样定位上下文。

为什么普通向量库不够用

向量检索的问题不在于它没用，而在于它太“平”。一个公司知识库里可能有产品文档、接口说明、部署记录、事故复盘、客户问答、会议纪要、研发规范。切成 chunk 后，很多层级信息会被削弱：这段话属于哪个项目？是不是旧版本？它和哪个流程相关？是不是只对某个用户有效？

Agent 执行长期任务时，这个问题会更明显。一次任务里产生的工具调用、错误、修复、用户偏好、临时文件和最终结论，如果全部当成普通文本块存起来，下次检索时很容易混在一起。OpenViking 试图用资源路径、上下文层级和会话归档，把这些信息重新变成可管理对象。

核心概念一：viking:// URI

OpenViking 的统一资源标识是 viking://{scope}/{path}。公开作用域主要包括 resources、user、agent。这很像给 Agent 的世界建立一个文件系统：

viking://
├── resources/             # 项目资料、文档、知识库
├── user/                  # 用户画像、记忆、会话
└── agent/                 # Agent 技能、工具、能力配置

例如，一个项目 API 文档可以放在：

viking://resources/my-project/docs/api.md

用户偏好可以放在：

viking://user/memories/preferences/coding

这样的好处是检索结果不再只是“某个 chunk 相似度很高”，而是“这个上下文位于哪个稳定路径”。路径本身成为推理线索，也方便权限、归档和迁移。

核心概念二：L0 / L1 / L2 三层上下文

OpenViking 用三层模型平衡成本和完整性：

L0 Abstract：约 100 tokens 的极短摘要，用于快速感知和向量检索。
L1 Overview：约 1k 到 2k tokens 的导航型概览，告诉 Agent 这个目录/资源里有什么、该读哪里。
L2 Detail：原始全文或子目录，只有确认需要时再读取。

这套设计比“直接把全文塞给模型”稳得多。Agent 可以先用 L0 快速筛选，再用 L1 判断是否值得进入，最后只读取必要 L2。对于长文档、代码库、会议纪要、产品手册，这种分层能显著减少 token 浪费，也更容易解释为什么读了某个资源。

本地部署：先跑通服务再谈集成

OpenViking 支持 Python 包和 Docker 两种路径。试用推荐 Docker，原因是配置和数据都能集中挂载到 ~/.openviking，不污染系统环境。

mkdir -p ~/.openviking
touch ~/.openviking/ov.conf

最小 docker-compose 可以这样写：

services:
  openviking:
    image: ghcr.io/volcengine/openviking:latest
    container_name: openviking
    ports:
      - "1933:1933"
    volumes:
      - ~/.openviking:/app/.openviking
    restart: unless-stopped

启动：

docker compose up -d
curl http://localhost:1933/health

正常情况下会返回 {"status":"ok"}。Web Studio 通常在 http://localhost:1933/studio，用于观察和管理上下文。

macOS 访问坑：localhost 可能被绑定限制影响

官方文档特别提到，OpenViking 默认出于安全考虑可能只监听 127.0.0.1，Docker on Mac 下宿主机访问 localhost:1933 可能遇到 connection reset。官方给的思路是用 socat 做端口转发，把容器里的本地监听转出来。这个点部署时要提前检查，不要把它误判成服务没启动。

模型配置：至少需要 VLM 和 embedding 能力

OpenViking 不是只存字符串。它会处理文档、图片、资源摘要、语义检索，因此需要至少两类模型能力：VLM 用于图片和内容理解，Embedding 用于向量化和语义检索。它支持多种模型服务，包括火山引擎、OpenAI 兼容服务、Ollama 等。生产环境不要把模型配置写死在脚本里，应放在 ~/.openviking/ov.conf 或环境变量里，并区分开发、测试、生产 key。

Server 模式：给其他客户端接入

如果用 pip 安装，也可以直接跑服务：

pip install openviking --upgrade --force-reinstall
openviking-server init
openviking-server doctor
openviking-server

doctor 比 /health 更重要。/health 只能说明进程活着；doctor 会检查本地配置、模型访问和认证准备情况。真正上线前必须跑 doctor，否则很可能服务启动了，但解析和检索链路实际不可用。

MCP 集成：让 Agent 直接访问上下文库

OpenViking 内置 MCP HTTP endpoint，地址通常是：

http://localhost:1933/mcp

这意味着 Claude Code、Cursor、Codex、OpenCode、Manus、Claude Desktop 等 MCP 客户端可以把 OpenViking 当成一个长期上下文工具。通用配置类似：

{
  "mcpServers": {
    "openviking": {
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

Claude Code 需要显式指定 HTTP transport：

claude mcp add --transport http openviking \
  https://your-server.com/mcp \
  --header "Authorization: Bearer ***"

和 Hermes Agent 的关系

OpenViking 文档里专门列了 Hermes Agent 集成：Hermes 有内置 OpenViking memory provider，不需要额外插件。通过 hermes memory setup 指向 OpenViking Server，就可以让 Hermes 把长期记忆、召回和抽取交给 OpenViking。

hermes memory setup
hermes memory status

这个方向很有价值：Agent 的 memory 不再只是本地一份 Markdown 或 SQLite，而是可以成为一个独立的上下文服务。多端、多 Agent、多会话协作时，统一 memory provider 会比各自保存一份记忆更可控。

实践工作流：给一个研发项目建立上下文库

一个现实的用法是把 OpenViking 用作项目上下文层。不要一开始就导入全公司文档，先选一个边界明确的项目：

把 README、架构图、API 文档、部署手册、事故复盘导入 viking://resources/project-x/。
让系统生成 L0/L1，检查摘要是否准确。
把 Agent 常用技能放到 viking://agent/skills/。
把用户偏好、项目约束、命名规则放到 viking://user/memories/。
通过 MCP 接给编码 Agent，让它先检索上下文再动代码。

这样做的目标不是“让 Agent 记住一切”，而是让 Agent 能按路径找到正确上下文，知道什么时候读摘要、什么时候读全文、什么时候需要人工确认。

生产化检查清单

只把明确有长期价值的资料放进上下文库，临时日志不要无脑入库。
给项目、用户、Agent 能力分开 namespace，避免权限混乱。
启用 API key 或 OAuth，不要把远程 MCP 裸露到公网。
定期抽查 L0/L1 摘要质量，摘要错会导致后续检索错。
记录检索轨迹，排查“为什么 Agent 找错资料”。
把读写权限分层：读取资源、写入记忆、修改技能应是不同权限。
备份 ~/.openviking，上下文库一旦成为生产依赖，就不能只当缓存。

什么时候不该用 OpenViking

如果你的需求只是一个小 FAQ，文档少、没有多 Agent、没有长期会话、没有权限隔离，用普通向量库或简单全文搜索就够了。OpenViking 的价值在于长期上下文治理：记忆、资源、技能、会话、工具调用都需要统一管理时，它才真正显出优势。

结论

OpenViking 代表的是 Agent 基础设施的一个重要方向：从“模型 + 工具”走向“模型 + 工具 + 上下文数据库”。Agent 要长期工作，不能每次靠临时 prompt 和散乱文件重建世界。它需要一个能保存、组织、压缩、检索、观测上下文的底座。OpenViking 的文件系统范式、L0/L1/L2 分层、MCP endpoint 和 Hermes 集成，都说明 Agent memory 正在从功能点变成基础设施。