# https://github.com/volcengine/OpenViking 项目说明书 生成时间：2026-06-22 15:39:03 UTC ## 目录 - [OpenViking 概览：上下文数据库与五大核心概念](#page-1) - [系统架构、C++ 索引内核与存储层](#page-2) - [Agent 集成生态：OpenClaw、Claude Code、Codex、OpenCode、LangChain 与 VikingBot](#page-3) - [部署、运维可观测性及社区热点议题](#page-4) ## OpenViking 概览：上下文数据库与五大核心概念 ### 相关页面 相关主题：[系统架构、C++ 索引内核与存储层](#page-2), [Agent 集成生态：OpenClaw、Claude Code、Codex、OpenCode、LangChain 与 VikingBot](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [openviking/parse/parsers/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/README.md) - [openviking/parse/parsers/code/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/code/README.md) - [bot/vikingbot/openviking_mount/README.md](https://github.com/volcengine/OpenViking/blob/main/bot/vikingbot/openviking_mount/README.md) - [examples/basic-usage/README.md](https://github.com/volcengine/OpenViking/blob/main/examples/basic-usage/README.md) - [crates/ov_cli/README.md](https://github.com/volcengine/OpenViking/blob/main/crates/ov_cli/README.md) - [bot/README.md](https://github.com/volcengine/OpenViking/blob/main/bot/README.md) - [sdk/python/README.md](https://github.com/volcengine/OpenViking/blob/main/sdk/python/README.md) - [examples/openclaw-plugin/README.md](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/README.md)
# OpenViking 概览：上下文数据库与五大核心概念 OpenViking 是一个面向 AI Agent 的开源**上下文数据库（Context Database）**，定位为"Agent 时代的文件系统 + 长期记忆 + 语义检索引擎"。它通过统一协议 `viking://` 暴露资源（Resources）、会话（Session）、用户（User）三类上下文，配合模块化解析、分层信息模型和语义队列，使 Agent 能够按需加载不同粒度的信息，而不是一次性将全部上下文塞入提示词窗口。 ## 一、上下文数据库的角色 OpenViking 不是一个传统 RAG 库，也不是单纯的向量数据库，而是一套**自包含的上下文引擎**： - **统一寻址**：通过 `viking://` URI 把本地文件、远程仓库、对话记忆纳入同一棵虚拟文件系统树 [`openviking/parse/parsers/README.md`](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/README.md)。 - **多模态解析**：支持 Markdown、PDF、HTML、Word、PPT、Excel、EPUB、图像、音视频以及主流编程语言代码 [`examples/openclaw-plugin/README.md`](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/README.md)。 - **多客户端接入**：提供 Embedded SDK、HTTP Server、CLI（`ov` 命令）、MCP 端点，以及与 Codex、Claude Code、OpenClaw、OpenCode 等 IDE/Agent 的官方插件 [`examples/basic-usage/README.md`](https://github.com/volcengine/OpenViking/blob/main/examples/basic-usage/README.md)。 - **轻量 HTTP SDK**：通过 `openviking-sdk` 可直接调用远端服务，避免引入本地运行时依赖 [`sdk/python/README.md`](https://github.com/volcengine/OpenViking/blob/main/sdk/python/README.md)。 ## 二、五大核心概念 ### 概念一：三层信息模型（L0 / L1 / L2） OpenViking 把任意上下文拆成三层，让 Agent 按场景读取合适粒度 [`openviking/parse/parsers/README.md`](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/README.md)： | 层级 | 文件 | 体积 | 用途 | |------|------|------|------| | **L0 Abstract** | `.abstract.md` | <200 token | 摘要，支撑向量化检索与目录快速浏览 | | **L1 Overview** | `.overview.md` | <1000 token | 决策参考，章节导览 | | **L2 Detail** | `content.md` 或原始文件 | 完整内容 | 仅在遍历到终点时按需读取 | 代码资源同样遵循这一分层：每层目录都有 `.abstract.md` 与 `.overview.md`，但 L2 层直接保存原始源文件而不拆解 [`openviking/parse/parsers/code/README.md`](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/code/README.md)。 ### 概念二：Viking URI 统一寻址 所有内容都以 `viking://` 开头寻址，常见前缀包括 `viking://resources/`、`viking://session/`、`viking://user/`。例如把仓库导入后会生成 `viking://resources/github/volcengine/OpenViking/...` 这样可递归到任意深度的目录树 [`openviking/parse/parsers/code/README.md`](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/code/README.md)。CLI 也以这套 URI 为入口：`ov ls`、`ov read`、`ov abstract`、`ov overview`、`ov find` 等 [`crates/ov_cli/README.md`](https://github.com/volcengine/OpenViking/blob/main/crates/ov_cli/README.md)。 ### 概念三：三种上下文类型 - **Resources**：用户导入的静态知识（文件、目录、仓库、网页）。 - **Session**：单次对话或任务产生的临时上下文。 - **User**：跨 Session 沉淀的长期记忆（偏好、实体、事件）。 Vikingbot 提供 7 个 OpenViking 专用工具（`openviking_read / list / search / add_resource / grep / glob / memory_commit`）来操作这三类上下文 [`bot/README.md`](https://github.com/volcengine/OpenViking/blob/main/bot/README.md)。 ### 概念四：模块化解析与 SemanticQueue 解析器按文件扩展名自动路由（Markdown、PDF、代码、媒体等），输出统一 `ResourceNode` 树。每个解析器先在临时目录内构建结构，再由 `TreeBuilder` 移入 AGFS 并按自底向上顺序入队 `SemanticQueue`，支持并发解析且不冲突 [`openviking/parse/parsers/README.md`](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/README.md)。 ### 概念五：分层存储与按需加载 存储分为对象存储（向量 + 元数据）与文件系统（`viking://` 目录树）。`Context` 对象只保存 URI 与元数据，内容按 `get_abstract / get_overview / get_detail` 懒加载并在内存中缓存，避免重复 IO [`openviking/parse/parsers/README.md`](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/README.md)。`OpenVikingMount` 还可将 `viking://` 映射到本地路径直接以文件系统范式访问 [`bot/vikingbot/openviking_mount/README.md`](https://github.com/volcengine/OpenViking/blob/main/bot/vikingbot/openviking_mount/README.md)。 ## 三、系统数据流 ```mermaid flowchart LR A[原始资源
URL/文件/仓库] --> B[Parser 路由
按扩展名选择] B --> C[临时目录构建
ResourceNode 树] C --> D[移入 AGFS
viking:// 树] D --> E[SemanticQueue
自底向上] E --> F[生成 L0/L1/L2
+ 向量索引] F --> G[Agent 通过
find/read/abstract 取用] ``` ## 四、社区共识与延伸阅读 - 社区在 #744 中集中追踪 **Token 消耗与 Embedding 成本** 优化，而 L0/L1 分层正是官方推荐的节流手段。 - #394 讨论 "Zero-Knowledge Context Proofs" 上下文完整性标准，与 `Context` 对象的元数据/URI 分离设计直接相关。 - #1082 的维护者地图与 #55 的 Memex 演示，展示了 VikingBot + Resources + Session 的组合用法。 ## See Also - [OpenViking 解析系统](openviking-parse-system.md) - [Vikingbot 架构与 OpenViking 工具](vikingbot-architecture.md) - [Viking URI 与上下文层级详解](viking-uri-and-context-layers.md) --- ## 系统架构、C++ 索引内核与存储层 ### 相关页面 相关主题：[OpenViking 概览：上下文数据库与五大核心概念](#page-1), [部署、运维可观测性及社区热点议题](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [openviking/storage/vectordb/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/storage/vectordb/README.md) - [openviking/parse/parsers/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/README.md) - [openviking/parse/parsers/code/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/code/README.md) - [examples/basic-usage/README.md](https://github.com/volcengine/OpenViking/blob/main/examples/basic-usage/README.md) - [web-studio/README.md](https://github.com/volcengine/OpenViking/blob/main/web-studio/README.md) - [npm/cli/README.md](https://github.com/volcengine/OpenViking/blob/main/npm/cli/README.md) - [bot/workspace/skills/README.md](https://github.com/volcengine/OpenViking/blob/main/bot/workspace/skills/README.md)
# 系统架构、C++ 索引内核与存储层 ## 1. 总体架构概览 OpenViking 采用分层架构，自底向上依次为：**C++ 索引内核 → 存储层（AGFS + VikingVectorIndex）→ 解析与语义层 → 服务层与客户端层**。整个系统的核心设计哲学是「物理搬运」与「语义理解」分离，确保高吞吐的资源导入和异步的语义处理。 - **存储层**：以 [openviking/storage/vectordb/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/storage/vectordb/README.md) 中描述的 VikingVectorIndex 为核心，提供 C++ 实现的高性能向量索引能力。 - **解析层**：依据 [openviking/parse/parsers/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/README.md) 中的 V5.0 架构，将原始文档转换为统一的 `viking://` 资源树。 - **客户端层**：包括 Python SDK、HTTP API、CLI 与 Web Studio，按 [examples/basic-usage/README.md](https://github.com/volcengine/OpenViking/blob/main/examples/basic-usage/README.md) 与 [npm/cli/README.md](https://github.com/volcengine/OpenViking/blob/main/npm/cli/README.md) 提供资源管理与检索能力。 ```mermaid flowchart TB A[Client SDK / CLI / Web Studio] --> B[OpenViking Server HTTP API] B --> C[Service Layer / 语义队列] C --> D[Parser Layer: PDF/HTML/Code/Media] D --> E[AGFS 存储层] E --> F[VikingVectorIndex C++ 内核] F --> G[三表存储 C/D/T] ``` ## 2. C++ 索引内核：VikingVectorIndex VikingVectorIndex 是 OpenViking 的向量索引核心，其 C++ 实现通过 Python `abi3` 扩展绑定，对外暴露 Python API。资料来源：[openviking/storage/vectordb/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/storage/vectordb/README.md) ### 2.1 三表存储模型 C++ 内核将数据拆分为三张职责分离的表： | 表名 | 名称 | 职责 | |------|------|------| | C 表 | Candidate Table | 存储最新向量和标量数据，Key 为 `label` (uint64) | | D 表 | Delta Table | 记录 PUT/DELETE 变更历史，用于索引增量更新与崩溃恢复 | | T 表 | TTL Table | 按过期时间排序，加速 TTL 清理的后台任务 | 资料来源：[openviking/storage/vectordb/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/storage/vectordb/README.md) ### 2.2 关键特性 - **线程安全**：关键数据结构支持并发访问 - **增量更新**：D 表记录变更后重建索引，避免全量重建 - **TTL 清理**：T 表使得过期数据可高效回收 社区中关于 #744「Token 消耗与成本优化问题汇总」提到的 Embedding 处理成本，依赖于本内核对增量索引与并发访问的优化。资料来源：[openviking/storage/vectordb/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/storage/vectordb/README.md) ## 3. 存储层与解析层的协同 OpenViking 使用 AGFS（资源文件系统）作为统一的逻辑文件系统，URI 形如 `viking://resources/...`。解析层将外部资源（PDF、HTML、代码、媒体等）按 V5.0 架构处理： 1. **物理搬运阶段（Parser Phase）**：资源被上传到 `viking://temp/{uuid}/` 临时目录，**不进行 LLM 调用**，保证 `add_resource` 接口快速返回。资料来源：[openviking/parse/parsers/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/README.md) 2. **语义处理阶段（Semantic Phase）**：`TreeBuilder` 将临时目录移入正式路径，生成 `SemanticMsg` 推入 `SemanticQueue`，后台异步生成每层目录的 `.abstract.md`（L0）与 `.overview.md`（L1）。资料来源：[openviking/parse/parsers/code/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/code/README.md) 3. **代码仓库特别处理**：使用 `git clone --depth 1` 浅克隆或 zip 下载作为降级方案，自动忽略 `.git`、`node_modules` 等非代码目录。代码文件在 L2 层不进行拆分，直接存储完整内容。资料来源：[openviking/parse/parsers/code/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/code/README.md) ## 4. 服务层与客户端接入 ### 4.1 服务端运行模式 OpenViking Server 默认监听 `http://127.0.0.1:1933`，需要通过 `openviking-server --with-bot` 启动 VikingBot 支持，否则 `/bot/v1/*` 端点将返回 `503`。资料来源：[web-studio/README.md](https://github.com/volcengine/OpenViking/blob/main/web-studio/README.md) ### 4.2 客户端形态 - **嵌入式模式**：`ov.OpenViking(path="./data")` 本地初始化 - **HTTP 客户端模式**：`ov.SyncHTTPClient(url="http://localhost:1933")` 远程调用 - **CLI 工具**：支持 `ls` / `tree` / `read` / `abstract` / `overview` / `find` / `grep` 等命令 - **Web Studio**：React/Vite 单页应用，纯前端需连接运行中的 OpenViking Server 资料来源：[examples/basic-usage/README.md](https://github.com/volcengine/OpenViking/blob/main/examples/basic-usage/README.md) 与 [npm/cli/README.md](https://github.com/volcengine/OpenViking/blob/main/npm/cli/README.md) ### 4.3 智能体集成 OpenViking 提供多种 Agent 集成插件，包括 Claude Code、Codex、OpenClaw 等。`bot/workspace/skills/` 内置 `github`、`weather`、`summarize`、`tmux` 等技能，遵循 OpenClaw 的 SKILL.md 格式规范。资料来源：[bot/workspace/skills/README.md](https://github.com/volcengine/OpenViking/blob/main/bot/workspace/skills/README.md) 社区中 #591 报告的 OpenClaw `2026.3.12` 兼容性挂起问题，即与该插件生命周期钩子的同步逻辑相关。 ## See Also - [解析系统详细文档](openviking/parse/parsers/README.md) - [代码仓库解析策略](openviking/parse/parsers/code/README.md) - [向量数据库 C++ 内核](openviking/storage/vectordb/README.md) - [基本使用示例](examples/basic-usage/README.md) - [Web Studio 前端](web-studio/README.md) - [CLI 命令参考](npm/cli/README.md) --- ## Agent 集成生态：OpenClaw、Claude Code、Codex、OpenCode、LangChain 与 VikingBot ### 相关页面 相关主题：[OpenViking 概览：上下文数据库与五大核心概念](#page-1), [部署、运维可观测性及社区热点议题](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [examples/openclaw-plugin/README.md](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/README.md) - [examples/openclaw-plugin/package.json](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/package.json) - [examples/claude-code-memory-plugin/README.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) - [examples/codex-memory-plugin/README.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) - [bot/README.md](https://github.com/volcengine/OpenViking/blob/main/bot/README.md) - [bot/workspace/skills/README.md](https://github.com/volcengine/OpenViking/blob/main/bot/workspace/skills/README.md) - [bot/vikingbot/openviking_mount/README.md](https://github.com/volcengine/OpenViking/blob/main/bot/vikingbot/openviking_mount/README.md) - [web-studio/README.md](https://github.com/volcengine/OpenViking/blob/main/web-studio/README.md) - [npm/cli/README.md](https://github.com/volcengine/OpenViking/blob/main/npm/cli/README.md) - [openviking/parse/parsers/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/README.md) - [openviking/parse/parsers/code/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/code/README.md)
# Agent 集成生态：OpenClaw、Claude Code、Codex、OpenCode、LangChain 与 VikingBot OpenViking 不仅是一个上下文数据库与解析系统，也是一组面向主流 AI Agent 平台的长期记忆 / 上下文引擎适配层。仓库在 `examples/` 目录中提供了针对 **OpenClaw**、**Claude Code**、**Codex** 等 CLI Agent 的官方插件，并在 `bot/` 中提供名为 **VikingBot** 的本地代理运行时。Web Studio 与 CLI 则共同构成观测与管理侧。 ## 1. 集成模式总览 OpenViking 暴露 HTTP API（默认 `http://127.0.0.1:1933`），Agent 插件以"远端客户端"模式连接，所有数据通过 REST 端点交互，本地不再维护存储或索引进程。资料来源：[examples/openclaw-plugin/README.md:18-30]()、[web-studio/README.md:14-20]()。 | Agent 平台 | 集成形式 | 数据通道 | 主要能力 | |---|---|---|---| | OpenClaw | `clawhub:@openviking/openclaw-plugin` 包 | HTTP `baseUrl` + `apiKey` | 自动 recall、`/compact` 提交、记忆注入 | | Claude Code | `claude-code-memory-plugin` 目录 | 远端 HTTP（环境变量配置） | `UserPromptSubmit` 自动 recall、`Stop`/`PreCompact` 增量提交 | | Codex | `codex-memory-plugin` 目录 | Streamable HTTP + Bearer | 决定性 session id `cx-`、`MCP` 工具桥接 | | VikingBot | 仓库内 `bot/` 子项目 | 本地存储 + 远端模式双模式 | 7 个原生 OpenViking 工具 + 第三方 MCP | > 社区曾报告 OpenClaw 2026.3.12 升级后 `memory-openviking` 插件导致对话挂起的问题（issue #591），提示插件需对齐宿主平台版本。 ## 2. OpenClaw 插件 OpenClaw 插件以"context-engine"插槽形式注册，运行模式为纯 HTTP 客户端： - **快速安装**：`openclaw plugins install clawhub:@openviking/openclaw-plugin`，再通过 `openclaw openviking setup --base-url ... --api-key ...` 激活。资料来源：[examples/openclaw-plugin/README.md:33-44]()。 - **生命周期钩子**：在 `afterTurn` 阶段把新消息追加到 OpenViking session，commit/extraction 由阈值触发；`assemble` 在每轮回复前自动注入相关长期记忆；`/compact` 触发提交并抽取为长期记忆。资料来源：[examples/openclaw-plugin/README.md:60-71]()。 - **协议层抽象**：所有本地文件先经 `/api/v1/resources/temp_upload` 上传，目录通过纯 JS zip 实现压缩，规避明文路径外发。资料来源：[examples/openclaw-plugin/README.md:24-28]()。 - **运行时路由**：插件不启动本地子进程，远程服务必须独立部署；`baseUrl` 与 `apiKey` 来自插件配置。资料来源：[examples/openclaw-plugin/README.md:42-54]()。 ## 3. Claude Code 与 Codex 记忆插件 二者设计思路相近：把 OpenViking 当作 Agent 的"长期记忆后端"，在用户提问前自动 recall，在结束/压缩时增量 commit。 - **Claude Code** 通过环境变量驱动，例如 `OPENVIKING_COMMIT_TOKEN_THRESHOLD=20000` 控制提交阈值，`OPENVIKING_WRITE_PATH_ASYNC=true` 把写入解耦到后台 worker，避免 `Stop` 钩子超时。资料来源：[examples/claude-code-memory-plugin/README.md:53-72]()。 - **Codex** 使用决定性 session id `cx-` 增量追加，在 `PreCompact` 触发抽取，`SessionStart` 时按活动窗口启发式决定是否提交刚结束的会话。Codex 同时通过原生 `/mcp` 端点接入 `search / store / read / list / grep / glob / forget / add_resource / health` 等工具，无需本地 MCP 进程。资料来源：[examples/codex-memory-plugin/README.md:8-22]()。 - 两套插件均强调"recall → inject → commit"三段式流程，与 issue #744 所跟踪的 token 消耗 / embedding 成本问题紧密相关。资料来源：[examples/claude-code-memory-plugin/README.md:60-72]()。 ## 4. VikingBot：本地/远端双模式 Agent VikingBot 基于 Nanobot 构建，是 OpenClaw 风格的开箱即用 Agent，与 OpenViking 深度耦合： - **数据模式**：默认本地 `~/.openviking/data/`，也可切换为远端 Server 模式。资料来源：[bot/README.md:18-22]()。 - **原生工具集**：暴露 7 个专用工具——`openviking_read / list / search / add_resource / grep / glob / memory_commit`，配合 L0/L1/L2 三层内容访问。资料来源：[bot/README.md:38-46]()。 - **扩展能力**：通过 `tools.mcp_servers` 配置第三方 MCP（filesystem、GitHub 等），工具以 `mcp__` 形式注册。资料来源：[bot/README.md:50-66]()。 - **技能与挂载**：`bot/workspace/skills/` 提供 `github / summarize / tmux / skill-creator` 等内置技能（遵循 OpenClaw 的 `SKILL.md` 规范）；`bot/vikingbot/openviking_mount/` 将 `viking://` 虚拟文件系统挂载到本地路径（实验性）。资料来源：[bot/workspace/skills/README.md:18-30]()、[bot/vikingbot/openviking_mount/README.md:6-18]()。 ## 5. 观测与命令行侧 - **Web Studio** 是 React/Vite 静态 SPA，覆盖资源管理、检索、Bot 会话、运维诊断；其 sessions 页面依赖 VikingBot 端点（`/bot/v1/chat` 等），启动需 `openviking-server --with-bot`。资料来源：[web-studio/README.md:10-30]()。 - **CLI**（`@openviking/cli`）提供 `tui / chat / read / find / search / grep / glob / session / export / import` 等子命令，并支持多平台 darwin/linux/windows 包。资料来源：[npm/cli/README.md:38-72]()。 ## 6. 社区关注点 - **完整性证明**（issue #394）：随着 Agent 普遍依赖长期记忆，呼吁制定"Context Proofs"标准以审计返回上下文的真实性。资料来源：[examples/openclaw-plugin/README.md:1-4]()（说明 OpenViking 作为 OpenClaw context-engine 的角色）。 - **兼容性**：issue #591 反映 OpenClaw 2026.3.12 升级导致 `memory-openviking` 挂起，需要插件与宿主版本协同演进。 - **成本与 Token**（issue #744）：CLI 与插件暴露的 `OPENVIKING_COMMIT_TOKEN_THRESHOLD` / `OPENVIKING_RESUME_CONTEXT_BUDGET` 等参数正是为控制 embedding 与召回开销而设。 ## See Also - 解析系统与代码仓库处理：[openviking/parse/parsers/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/README.md)、[openviking/parse/parsers/code/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/code/README.md) - Web Studio 与 CLI：[web-studio/README.md](https://github.com/volcengine/OpenViking/blob/main/web-studio/README.md)、[npm/cli/README.md](https://github.com/volcengine/OpenViking/blob/main/npm/cli/README.md) --- ## 部署、运维可观测性及社区热点议题 ### 相关页面 相关主题：[系统架构、C++ 索引内核与存储层](#page-2), [Agent 集成生态：OpenClaw、Claude Code、Codex、OpenCode、LangChain 与 VikingBot](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [openviking/parse/parsers/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/README.md) - [examples/openclaw-plugin/README.md](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/README.md) - [bot/workspace/skills/README.md](https://github.com/volcengine/OpenViking/blob/main/bot/workspace/skills/README.md) - [openviking/parse/parsers/code/README.md](https://github.com/volcengine/OpenViking/blob/main/openviking/parse/parsers/code/README.md) - [npm/cli/README.md](https://github.com/volcengine/OpenViking/blob/main/npm/cli/README.md) - [web-studio/README.md](https://github.com/volcengine/OpenViking/blob/main/web-studio/README.md) - [examples/codex-memory-plugin/README.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) - [examples/claude-code-memory-plugin/README.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) - [examples/basic-usage/README.md](https://github.com/volcengine/OpenViking/blob/main/examples/basic-usage/README.md) - [bot/demo/werewolf/README.md](https://github.com/volcengine/OpenViking/blob/main/bot/demo/werewolf/README.md)
# 部署、运维可观测性及社区热点议题 本页面聚焦 OpenViking 在生产与社区场景下的部署拓扑、运行时可观测性入口以及当前社区正在跟踪的高优先级议题。OpenViking 提供嵌入式 SDK、HTTP 服务端与 Web/CLI 客户端等多种部署形态，运维可观测性依赖于服务端健康检查、任务队列、Bot 子系统探针与基于环境的配置契约。 ## 部署模式与运行时拓扑 OpenViking 提供三类运行时形态，可按场景组合使用： - **嵌入式客户端**：使用 `ov.OpenViking(path="./data")` 直接初始化本地存储与解析管线，适合单进程演示与本地开发（`资料来源：[examples/basic-usage/README.md:1-60]()`）。 - **HTTP 客户端**：`ov.SyncHTTPClient(url="http://localhost:1933")` 将 OpenViking Server 作为远端依赖，便于多端共享同一份向量与资源库；启用鉴权时需传入 `user_key`（`资料来源：[examples/basic-usage/README.md:1-60]()`）。 - **独立服务 + Web Studio**：通过 `openviking-server --with-bot` 启动核心 API 与 `/bot/v1/*` 代理；Web Studio 仅消费 HTTP 接口，不内嵌存储或 VikingBot 运行时（`资料来源：[web-studio/README.md:1-80]()`）。 部署核心原则是**进程职责分离**。Web Studio 不直接持有 OpenViking 存储、索引、检索、任务队列或 VikingBot 运行时，必须连接到一个独立运行的 OpenViking Server（`资料来源：[web-studio/README.md:1-30]()`）。CLI 同理：`@openviking/cli` 客户端按 darwin-arm64、darwin-x64、linux-x64 等平台分包，不在本机内嵌服务端（`资料来源：[npm/cli/README.md:1-60]()`）。 ```mermaid flowchart LR User[User / Agent] --> Studio[Web Studio / CLI] Studio -->|HTTP| Server[OpenViking Server] Server --> AGFS[(AGFS Storage)] Server --> Queue[SemanticQueue] Server --> BotProxy[/bot/v1/*/] BotProxy --> VikingBot[VikingBot Runtime] VikingBot --> Skills[bot/workspace/skills] ``` OpenClaw 插件采用**纯远程模式**：`baseUrl` 与 `apiKey` 来自插件配置，不在本机拉起子进程；本地文件先经 `/api/v1/resources/temp_upload` 上传，目录会被纯 JS 实现的 zip 工具打包后再上传（`资料来源：[examples/openclaw-plugin/README.md:1-40]()`）。Codex 与 Claude Code 的 Memory 插件同样以 HTTP 客户端形态接入，并直接消费 `/mcp` 流式端点（`资料来源：[examples/codex-memory-plugin/README.md:1-20]()`）。 ## 可观测性入口与健康契约 OpenViking 的可观测性以**轻量探针 + 异步任务追踪**为主，关键入口包括： | 探针 / 端点 | 用途 | 来源 | |------------|------|------| | `GET /health` | 核心服务存活检查 | `web-studio/README.md` | | `GET /ready` | 依赖就绪检查 | `web-studio/README.md` | | `GET /bot/v1/health` | VikingBot 子系统探针 | `web-studio/README.md` | | `task` 子命令（CLI） | 跟踪异步处理任务 | `npm/cli/README.md` | | `status` 子命令 | 查看服务端组件状态 | `npm/cli/README.md` | 部署 Web Studio 前必须确认 `/bot/v1/health` 返回健康；即使核心 API 可用，若 Bot 代理异常，Sessions 页面也无法提供真实对话（`资料来源：[web-studio/README.md:1-80]()`）。Bot 子系统的具体探活路径还包括 `vikingbot_url` 字段指向的 `/bot/v1/health`，可在狼人杀 Demo 的故障排查章节中看到（`资料来源：[bot/demo/werewolf/README.md:1-20]()`）。 异步处理的可观测性集中在 `SemanticQueue` 与 `SemanticProcessor`：解析器在 V5.0 架构下将临时目录物理搬运到 AGFS 后才入队语义生成，LLM 调用统一在 `SemanticProcessor` 中异步消费；这意味着 `add_resource` 快速返回后，需要通过任务通道观察摘要/概览的生成进度（`资料来源：[openviking/parse/parsers/README.md:1-80]()`）。Code 仓库解析同样遵循“物理搬运 + 异步理解”的两段式流程（`资料来源：[openviking/parse/parsers/code/README.md:1-60]()`）。 会话与记忆路径在 Claude Code 插件中可通过环境变量精细化控制，例如 `OPENVIKING_TIMEOUT_MS`、`OPENVIKING_CAPTURE_TIMEOUT_MS`、`OPENVIKING_COMMIT_TOKEN_THRESHOLD` 等，便于在 `Stop`、`PreCompact`、`SessionStart` 等钩子中观测延迟与提交阈值（`资料来源：[examples/claude-code-memory-plugin/README.md:1-40]()`）。 ## 社区热点议题跟踪 当前社区围绕**完整性、成本与兼容性**三类议题集中反馈： - **Agent 完整性标准（Issue #394）**：建议在 OpenViking 中引入“零知识上下文证明”（Zero-Knowledge Context Proofs），确保长程记忆中上下文数据库的交付完整性，避免 Agent 在持久化上下文上被静默篡改（`社区讨论：#394`）。 - **Token 消耗与成本优化（Issue #744）**：社区汇总了 Embedding、API 调用与解析阶段 Token 消耗相关的多个问题，python-sdk 已发布 `v0.1.2` 优化版本作为阶段性进展（`社区讨论：#744`）。 - **OpenClaw 兼容性问题（Issue #591）**：升级到 OpenClaw `2026.3.12` 后 `memory-openviking` 插件可能导致对话挂起；该问题并非 OpenViking 服务端 Bug，而是插件侧的兼容回归（`社区讨论：#591`）。 - **贡献者地图（Issue #1082）**：项目方建立了模块级维护者与 PR 评审入口索引，便于贡献者按模块定位 reviewer（`社区讨论：#1082`）。 - **Memex 个人知识助手 Demo（Issue #55）**：社区提议构建 CLI 形态的端到端示例，覆盖资源导入、检索、会话与记忆全链路（`社区讨论：#55`）。 ## 故障排查与最佳实践 常见的部署与运行故障集中在三类： 1. **Bot 子系统不可用**：Web Studio Sessions 页空白或返回 `503` 时，应先确认 `openviking-server --with-bot` 是否启动，并验证 `/bot/v1/health` 返回正常（`资料来源：[web-studio/README.md:1-80]()`）。 2. **异步任务堆积**：`task` 与 `status` 是首要排查命令；若资源长时间停留在临时目录，应检查 `SemanticQueue` 与 LLM Provider 配额（`资料来源：[npm/cli/README.md:1-60]()`）。 3. **插件侧兼容问题**：OpenClaw 升级后出现对话挂起，建议先在插件侧降级或绕过（`OPENVIKING_BYPASS_SESSION=1`），再观察服务端是否仍然异常（`资料来源：[examples/claude-code-memory-plugin/README.md:1-40]()`、`社区讨论：#591`）。 运维建议： - 跨域部署时，在 `ov.conf` 中配置 `server.cors_origins` 并设置 `server.root_api_key` 用于管理面访问（`资料来源：[web-studio/README.md:1-80]()`）。 - 通过 `VITE_OV_BASE_URL` 在构建期注入 API 起源，运行时仍允许用户在连接对话框中覆盖（`资料来源：[web-studio/README.md:1-80]()`）。 - 媒体与代码资源的上传建议使用 `temp_upload` 端点，避免将本地路径直接发送到服务端（`资料来源：[examples/openclaw-plugin/README.md:1-40]()`）。 ## See Also - [OpenViking 整体架构](../concepts/01-architecture.md) - [存储系统设计](../concepts/05-storage.md) - [上下文提取流程](../concepts/07-extraction.md) - [配置指南](../configuration/configuration.md) - [CLI 命令参考](../../npm/cli/README.md) - [Web Studio 部署](../../web-studio/README.md) --- --- ## Doramagic 踩坑日志 项目：volcengine/OpenViking 摘要：发现 10 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：Bug: openviking-memory.ts autoRecall has three critical bugs (mode:auto, input.parts vs output.parts, config scope)。 ## 1. 配置坑 · 来源证据：Bug: openviking-memory.ts autoRecall has three critical bugs (mode:auto, input.parts vs output.parts, config scope) - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: openviking-memory.ts autoRecall has three critical bugs (mode:auto, input.parts vs output.parts, config scope) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/volcengine/OpenViking/issues/2757 | 来源类型 github_issue 暴露的待验证使用条件。 ## 2. 配置坑 · 来源证据：[Bug] Semantic queue poison: `_process_memory_directory` raises on a memory file URI and re-enqueues forever - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] Semantic queue poison: `_process_memory_directory` raises on a memory file URI and re-enqueues forever - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/volcengine/OpenViking/issues/2734 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 3. 配置坑 · 来源证据：[Question]: 请问一下openclaw接入微信渠道，openviking能否支持多个微信用户的记忆隔离和召回 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Question]: 请问一下openclaw接入微信渠道，openviking能否支持多个微信用户的记忆隔离和召回 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/volcengine/OpenViking/issues/2761 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 4. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/volcengine/OpenViking | README/documentation is current enough for a first validation pass. ## 5. 运行坑 · 运行可能依赖外部服务 - 严重度：medium - 证据强度：source_linked - 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。 - 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。 - 证据：packet_text.keyword_scan | https://github.com/volcengine/OpenViking | matched external service / cloud / webhook / database keyword ## 6. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/volcengine/OpenViking | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/volcengine/OpenViking | no_demo; severity=medium ## 8. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/volcengine/OpenViking | no_demo; severity=medium ## 9. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/volcengine/OpenViking | issue_or_pr_quality=unknown ## 10. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/volcengine/OpenViking | release_recency=unknown