github volcengine/OpenViking v0.3.13
on GitHub

6 hours ago

OpenViking v0.3.13 Release Notes / 发布说明

Release date / 发布日期: 2026-04-29

Full Changelog / 完整变更记录: v0.3.12...v0.3.13

Commit range / 提交范围: v0.3.12...v0.3.13 (57 commits)

中文

版本概览

OpenViking v0.3.13 是一个面向服务化、Agent 集成和生产可观测性的增强版本。它在 openviking-server 内置了标准 MCP HTTP 端点，新增用户级 skill 隐私配置与版本管理，补齐 Prometheus / OpenTelemetry 配置入口，并进一步收紧 API 错误、URI 校验和 bot 工具沙箱边界。

升级时最需要关注两点：encryption.api_key_hashing.enabled 现在需要显式配置；OpenClaw 插件移除本地模式，并把 agentId 迁移为 agent_prefix。

主要更新

  • 内置 MCP 端点：openviking-server 现在在同一进程、同一端口暴露 /mcp，复用 REST API 的 API-Key 鉴权，提供 search、read、list、store、add_resource、grep、glob、forget、health 9 个工具。
  • 用户级隐私配置：新增 /api/v1/privacy-configs API 和 openviking privacy CLI，用于按 category + target_key 保存、轮换、回滚 skill 等敏感配置。
  • 可观测性升级：新增统一 server.observability 配置，支持 Prometheus /metrics，并为 metrics、traces、logs 提供 OpenTelemetry 导出配置。
  • 检索与 embedding 可调优：新增 embedding.text_source、embedding.max_input_tokens、retrieval.hotness_alpha、retrieval.score_propagation_alpha 等配置，便于控制向量化内容和层级检索排序。
  • API 与错误语义收敛：搜索空 query 会被提前拒绝；公开 API 的 viking:// URI 校验更严格；资源处理、损坏 zip、HTTP 客户端等错误统一进入标准 error envelope。
  • Docker 与初始化体验：Docker 镜像把持久化状态收敛到 /app/.openviking，缺少 ov.conf 时会保持容器存活并在任意路由返回 503 初始化指引。
  • 安全修复：bot image tool 禁止读取沙箱外宿主机文件；health check 在无凭证场景下跳过身份解析；API key 字段哈希从文件层加密中拆分为独立开关。

新功能用法

连接内置 MCP 端点

OpenViking MCP 端点位于 http://<server>:1933/mcp。大多数 MCP 客户端可使用如下配置： 

{
  "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 your-api-key-here"

管理 skill 隐私配置

隐私配置适合保存 skill 的 api_key、base_url 等敏感字段，并支持版本查询与回滚。 

openviking privacy categories
openviking privacy list skill

openviking privacy upsert skill byted-viking-search-knowledgebase \
  --values-json '{"api_key":"secret-2","base_url":"https://example.com"}'

openviking privacy versions skill byted-viking-search-knowledgebase
openviking privacy activate skill byted-viking-search-knowledgebase 2

也可以直接调用 HTTP API： 

curl -X POST "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -H "X-OpenViking-Account: default" \
  -H "X-OpenViking-User: alice" \
  -d '{
    "values": {
      "api_key": "secret-2",
      "base_url": "https://example.com"
    },
    "change_reason": "rotate key"
  }'

开启 Prometheus metrics 与 OpenTelemetry

最小 Prometheus 配置： 

{
  "server": {
    "observability": {
      "metrics": {
        "enabled": true
      }
    }
  }
}

同时配置 OTel 导出： 

{
  "server": {
    "observability": {
      "metrics": {
        "enabled": true,
        "exporters": {
          "prometheus": {"enabled": true},
          "otel": {
            "enabled": true,
            "protocol": "grpc",
            "endpoint": "otel-collector:4317",
            "service_name": "openviking-server",
            "export_interval_ms": 10000
          }
        }
      },
      "traces": {
        "enabled": true,
        "protocol": "grpc",
        "endpoint": "otel-collector:4317",
        "service_name": "openviking-server"
      },
      "logs": {
        "enabled": true,
        "protocol": "grpc",
        "endpoint": "otel-collector:4317",
        "service_name": "openviking-server"
      }
    }
  }
}

调整 embedding 输入和检索打分

embedding.text_source 控制文本资源向量化使用原文还是摘要；retrieval 控制最终召回分数如何混合 hotness 与层级传播分数。 

{
  "embedding": {
    "text_source": "content_only",
    "max_input_tokens": 4096,
    "dense": {
      "provider": "volcengine",
      "model": "doubao-embedding-vision-251215",
      "dimension": 1024,
      "input": "multimodal"
    }
  },
  "retrieval": {
    "hotness_alpha": 0.0,
    "score_propagation_alpha": 0.5
  }
}

如果希望排序严格反映向量相似度，保持 hotness_alpha: 0.0。

配置 API key 字段哈希

v0.3.13 将文件层加密和 API key 字段哈希拆成两个开关。若你依赖旧行为，需要显式开启： 

{
  "encryption": {
    "enabled": true,
    "api_key_hashing": {
      "enabled": true
    }
  }
}

默认 api_key_hashing.enabled 为 false：API key 以明文存在 JSON 中；如果 encryption.enabled 为 true，整个文件仍由 AES-GCM 加密保护。

体验与兼容性改进

  • openviking-server init 和 doctor 文档与流程更清晰，覆盖 OpenAI Codex、Kimi、GLM、Volcengine 和 Ollama 等配置路径。
  • Docker 启动推荐挂载 ~/.openviking:/app/.openviking；无 volume 的托管平台可用 OPENVIKING_CONF_CONTENT 注入完整 ov.conf。
  • storage.agfs.queue_db_path 可把 QueueFS SQLite 数据库放到 workspace 以外的位置，适合 workspace 卷不支持 SQLite 的环境。
  • S3 endpoint 支持只填写 hostname，并根据 use_ssl 自动补 https:// 或 http://；S3 key normalization 的字符集合可配置。
  • 内容写入后更快对读取可见；增量 add-resource 会保留临时树以完成 top-down diff 和索引同步。
  • session archive 中新增 memory_diff.json，便于审计一次记忆抽取带来的新增、更新与删除。
  • OpenClaw 插件仅保留远程模式，不再启动本地 OpenViking 子进程；agentId 迁移为 agent_prefix，recallTokenBudget 迁移为 recallMaxInjectedChars。

修复

  • 修复 skill 索引使用非 canonical URI 的问题。
  • 修复资源处理错误、损坏 zip、HTTP 客户端错误等场景下的 error envelope 与 HTTP 状态码一致性。
  • 修复 health check 在无认证请求下触发身份解析的问题。
  • 修复 content write 后立即读取不可见的问题。
  • 修复 public URI 校验过宽、空搜索 query 未提前拒绝、缺失 grep URI 返回状态不一致等 API 边界问题。
  • 修复 S3 endpoint 缺少 scheme、S3 key normalization 字符不可配置、ragfs Python 绑定加载范围过宽等存储问题。
  • 修复 OpenClaw 插件自动召回预算、租户 header 合成、超时容忍、配置迁移和若干测试稳定性问题。
  • 修复 bot 图片工具可访问沙箱外宿主机文件的安全问题。

文档、测试与安全

  • 新增隐私配置 API 文档、MCP 集成指南、Agent 安装 SOP、可观测性与 operation telemetry 文档。
  • 从 GitHub Releases 自动生成中英文 changelog，并修复文档工作流与自定义域名资源路径。
  • 补充 MCP endpoint、privacy config、HTTP error mapping、Prometheus metrics、OpenTelemetry middleware、URI validation、content write、VikingFS grep、setup wizard 等测试。
  • 更新社区二维码、配置示例、README 多语言文档和 OpenClaw plugin 安装说明。
  • 安全侧重点包括 bot sandbox 文件访问限制、API key 字段哈希显式化、公开 URI 校验和 API 错误信息收敛。

English

Overview

OpenViking v0.3.13 focuses on server integrations, agent workflows, and production observability. The release adds a native MCP HTTP endpoint to openviking-server, introduces user-level privacy config versioning for skills, expands Prometheus / OpenTelemetry support, and tightens API error handling, URI validation, and bot sandbox boundaries.

The most important upgrade notes are: encryption.api_key_hashing.enabled must now be configured explicitly, and the OpenClaw plugin is remote-only with agentId migrated to agent_prefix.

Highlights

  • Native MCP endpoint: openviking-server now exposes /mcp in the same process and port as the REST API, reusing API-Key auth and providing 9 tools: search, read, list, store, add_resource, grep, glob, forget, and health.
  • User-level privacy configs: new /api/v1/privacy-configs APIs and openviking privacy CLI commands manage sensitive skill settings by category + target_key, with version history and rollback.
  • Observability upgrade: a unified server.observability config enables Prometheus /metrics and OpenTelemetry exporters for metrics, traces, and logs.
  • Retrieval and embedding tuning: new embedding.text_source, embedding.max_input_tokens, retrieval.hotness_alpha, and retrieval.score_propagation_alpha controls make vectorization and hierarchical ranking more configurable.
  • API and error semantics: empty search queries are rejected early, public viking:// URI validation is stricter, and processing / zip / HTTP client errors now use standard error envelopes.
  • Docker and setup experience: Docker state is consolidated under /app/.openviking; when ov.conf is missing, the container stays alive and serves a 503 JSON initialization guide on every route.
  • Security fixes: the bot image tool can no longer read host files outside the sandbox; health checks avoid identity resolution when unauthenticated; API key hashing is now an explicit switch separate from file encryption.

New Feature Usage

Connect to the built-in MCP endpoint

The OpenViking MCP endpoint is available at http://<server>:1933/mcp. Most MCP clients can use: 

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

Claude Code requires HTTP transport: 

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

Manage skill privacy configs

Privacy configs are useful for skill fields such as api_key and base_url, with version listing and rollback. 

openviking privacy categories
openviking privacy list skill

openviking privacy upsert skill byted-viking-search-knowledgebase \
  --values-json '{"api_key":"secret-2","base_url":"https://example.com"}'

openviking privacy versions skill byted-viking-search-knowledgebase
openviking privacy activate skill byted-viking-search-knowledgebase 2

The same operation is available through HTTP: 

curl -X POST "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -H "X-OpenViking-Account: default" \
  -H "X-OpenViking-User: alice" \
  -d '{
    "values": {
      "api_key": "secret-2",
      "base_url": "https://example.com"
    },
    "change_reason": "rotate key"
  }'

Enable Prometheus metrics and OpenTelemetry

Minimal Prometheus config: 

{
  "server": {
    "observability": {
      "metrics": {
        "enabled": true
      }
    }
  }
}

OpenTelemetry exporters can be configured under the same tree: 

{
  "server": {
    "observability": {
      "metrics": {
        "enabled": true,
        "exporters": {
          "prometheus": {"enabled": true},
          "otel": {
            "enabled": true,
            "protocol": "grpc",
            "endpoint": "otel-collector:4317",
            "service_name": "openviking-server",
            "export_interval_ms": 10000
          }
        }
      },
      "traces": {
        "enabled": true,
        "protocol": "grpc",
        "endpoint": "otel-collector:4317",
        "service_name": "openviking-server"
      },
      "logs": {
        "enabled": true,
        "protocol": "grpc",
        "endpoint": "otel-collector:4317",
        "service_name": "openviking-server"
      }
    }
  }
}

Tune embedding input and retrieval scoring

embedding.text_source controls whether text resource vectorization uses original content or summaries. retrieval controls how final ranking mixes hotness and hierarchical score propagation. 

{
  "embedding": {
    "text_source": "content_only",
    "max_input_tokens": 4096,
    "dense": {
      "provider": "volcengine",
      "model": "doubao-embedding-vision-251215",
      "dimension": 1024,
      "input": "multimodal"
    }
  },
  "retrieval": {
    "hotness_alpha": 0.0,
    "score_propagation_alpha": 0.5
  }
}

Keep hotness_alpha: 0.0 when ranking should strictly reflect vector similarity.

Configure API key field hashing

v0.3.13 separates file encryption from API key field hashing. To preserve the old implicit behavior, configure it explicitly: 

{
  "encryption": {
    "enabled": true,
    "api_key_hashing": {
      "enabled": true
    }
  }
}

By default, api_key_hashing.enabled is false: API keys are stored as plaintext inside JSON files; when encryption.enabled is true, those files are still protected by AES-GCM encryption.

Improvements

  • openviking-server init and doctor docs and flows now cover OpenAI Codex, Kimi, GLM, Volcengine, and Ollama setup paths more clearly.
  • Docker deployments should mount ~/.openviking:/app/.openviking; hosted platforms without volume support can inject a full ov.conf through OPENVIKING_CONF_CONTENT.
  • storage.agfs.queue_db_path can place the QueueFS SQLite database outside the workspace, which helps when the workspace volume does not support SQLite well.
  • S3 endpoints can be hostname-only and are prefixed from use_ssl; S3 key normalization characters are configurable.
  • Content writes become readable sooner, and incremental add-resource keeps the temporary tree available for top-down diff and index synchronization.
  • Session archives now include memory_diff.json, making memory adds, updates, and deletes easier to audit.
  • The OpenClaw plugin is remote-only, no longer starts a local OpenViking child process, migrates agentId to agent_prefix, and replaces recallTokenBudget with recallMaxInjectedChars.

Fixes

  • Fixed skill indexing to use canonical URIs.
  • Fixed error envelope and HTTP status consistency for resource processing errors, corrupted zip inputs, and HTTP client errors.
  • Fixed health checks triggering identity resolution without credentials.
  • Fixed content writes not being immediately visible to reads.
  • Fixed overly loose public URI validation, missing early rejection for empty search queries, and inconsistent status behavior for missing grep URIs.
  • Fixed S3 endpoint scheme handling, configurable S3 key normalization characters, and overly broad ragfs Python binding loading.
  • Fixed OpenClaw plugin auto-recall budget handling, tenant header synthesis, timeout tolerance, config migration, and several stability issues in tests.
  • Fixed a security issue where the bot image tool could read host files outside the sandbox.

Docs, Tests, and Security

  • Added privacy config API docs, MCP integration docs, agent installation SOP, observability docs, and operation telemetry reference docs.
  • Added bilingual changelogs generated from GitHub Releases, and fixed docs workflows plus custom-domain asset paths.
  • Added or updated tests for MCP endpoint behavior, privacy configs, HTTP error mapping, Prometheus metrics, OpenTelemetry middleware, URI validation, content writes, VikingFS grep, setup wizard behavior, and related server flows.
  • Updated community QR code, config examples, multilingual README files, and OpenClaw plugin installation docs.
  • Security work focused on bot sandbox file access, explicit API key hashing, public URI validation, and safer API error surfaces.
Check out latest releases or
releases around volcengine/OpenViking v0.3.13

Don't miss a new OpenViking release

NewReleases is sending notifications on new releases.

Get notifications