OpenViking Documentation

File: README.md Copy Chapter

What is OpenViking Copy Chapter

OpenViking is an open-source context database for AI agents. It stores memories, resources, and skills as one virtual filesystem under the viking:// protocol, so an agent browses its own context with ls, tree, and find instead of querying a black-box vector store. Content is processed into three tiers — L0 abstract, L1 overview, L2 details — and loaded on demand. Every retrieval leaves a trajectory you can watch and debug. Full introduction: Getting started.

The OpenViking Studio playground — a live demo you can open in the browser, no installation required.

Why OpenViking Copy Chapter

• One filesystem for all context. Memories, resources, and skills each get a viking:// URI. Agents locate and manipulate context deterministically, like a developer working with files. → Viking URI · Context types
• Tiered loading cuts token spend. Every entry is processed into L0 (abstract), L1 (overview), and L2 (details) on write, then loaded only as deep as the task requires. → Context layers
• Directory recursive retrieval. Vector search first locates the highest-scoring directory, then drills down layer by layer, so results arrive with their surrounding context intact. → Retrieval
• Observable retrieval. Each query preserves its directory-browsing trajectory. When a result looks wrong, you can see exactly which path produced it. → Retrieval
• Sessions become memory. After a session commits, OpenViking asynchronously extracts user preferences and agent experience into long-term memory. → Session

How the pieces fit together: Architecture. The thinking behind the design: The Database Paradigm for Context Engineering.

viking://
├── resources/              # Resources: project docs, repos, web pages, etc.
│   └── my_project/
│       ├── docs/
│       │   ├── api/
│       │   └── tutorials/
│       └── src/
└── user/
    └── {user_id}/
        ├── memories/
        │   └── preferences/
        │       ├── writing_style
        │       └── coding_habits
        ├── resources/
        │   └── private_project/
        ├── skills/
        │   ├── search_code
        │   └── analyze_data
        └── peers/
            └── web-visitor-alice/

The three loading tiers:

• L0 (Abstract): a one-sentence summary for quick relevance checks.
• L1 (Overview): core information and usage scenarios for planning.
• L2 (Details): the full original data, read only when needed.

Each directory carries its own L0/L1 layers, so relevance can be judged before any full file is read:

viking://resources/my_project/
├── .abstract               # L0: ~100 tokens - quick relevance check
├── .overview               # L1: ~2k tokens - structure and key points
└── docs/
    ├── .abstract
    ├── .overview
    └── api/
        ├── auth.md         # L2: full content, loaded on demand
        └── endpoints.md

Proof it works Copy Chapter

OpenViking 0.3.22 has been evaluated on long-conversation user memory (LoCoMo) and multi-turn agent tasks (tau2-bench). Full results and setup details, including knowledge-base QA, are in the benchmark report; reproduction scripts live in ./benchmark.

• User memory (LoCoMo): with OpenViking, all three agent integrations land at 80–83% accuracy — up from 24–57% on their native memory — while input tokens drop by 34.3–91.0% and query latency by 58.45–66.10%.
• Agent experience (tau2-bench): experience memory lifts task success by +6.87pp (retail) and +11.87pp (airline) over the same LLM without memory.

Quick start Copy Chapter

💡 Want to see it in action first? Try OpenViking Studio — a live hosted instance with a context playground, semantic search, and a multi-agent hub. No installation required.

Requires Python 3.10 or higher.

pip install openviking --upgrade
openviking-server init      # interactive wizard: providers, models, ov.conf
openviking-server doctor    # validate setup
openviking-server           # start (background: nohup openviking-server > openviking.log 2>&1 &)

init walks you through provider setup and writes ~/.openviking/ov.conf. It supports Volcengine, OpenAI, Codex OAuth, Kimi, GLM, and local Ollama — for Ollama it can detect and install the runtime and pull models suited to your hardware. doctor checks the config file, Python version, provider connectivity, and disk space without a running server. Manual ov.conf templates, per-provider examples, environment variables, and Windows setup: Configuration guide · Quick start docs.

The install already includes the ov client CLI. With the server running:

ov status
ov add-resource https://github.com/volcengine/OpenViking # --wait
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
# wait some time for semantic processing if not --wait
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en

Next steps:

• Client configuration (ov config), standalone CLI installs (npm / cargo), and advanced usage such as index rebuilding: CLI setup
• Docker and production deployment: Deployment guide

Use it with your agent Copy Chapter

Integrations inject OpenViking recall into your agent's context and auto-commit session memory:

• Claude Code
• Codex
• OpenClaw
• Hermes
• Cursor
• TRAE / TRAE CN / TraeCode CLI 2.0
• OpenCode
• pi
• Agent Plugins 1.0
• MCP clients
• LangChain / LangGraph

Setup instructions for each agent: Agent integrations overview.

OpenViking Helper (Beta) Copy Chapter

OpenViking Helper is a desktop console, currently in beta for macOS and Windows x64:

• Visual local agent setup: detects OpenViking CLI, Claude Code, Codex, Cursor, Trae, and OpenCode, then configures supported plugin, MCP, Hook, and CLI integrations.
• Session trace inspection: parses Claude Code, Codex, and Trae sessions to show OpenViking recall, prompt injection, MCP calls, capture, and commit events.
• Local memory and skill management: views local memory / rule files and SKILL.md skills, then syncs them to OpenViking.

Download:

• macOS Apple Silicon (arm64)
• macOS Intel (x64)
• Windows (x64)

VikingBot Copy Chapter

VikingBot is an AI agent framework built on top of OpenViking:

pip install "openviking[bot]"
openviking-server --with-bot
ov chat   # in another terminal

The official Docker image bundles VikingBot and starts it by default alongside the server and console UI. Details: VikingBot guide.

Deploy in production Copy Chapter

For production, run OpenViking as a standalone HTTP service — see Server deployment and the Deployment guide.

Commercial editions Copy Chapter

The open-source edition is not crippled. OpenViking in this repo is fully open source under AGPLv3: no feature gates, no account required, no activation key. Follow Deploy in production above and run it in production yourself — and that will stay true.

The two editions below answer "who operates it and where it runs", not "can I use it".

| ☁️ Managed SaaS
Officially hosted on Volcano Engine. Nothing to set up, nothing to operate.

Personal — for individual developers. Free trial for up to 50 files, and scales far beyond local hardware with VikingDB.
Enterprise — multi-user context management, team collaboration and permissions, enterprise SLA and support.

Existing open-source users can move over with the migration tool.
→ Volcano Engine product page · Documentation
Global hosting for regions outside China is coming to BytePlus. | 🏢 Self-Managed
Runs inside your own environment. Data never leaves it.

Online — deployed into your own cloud account / VPC, BYOC supported, with outbound access for updates and licensing.
Offline — fully air-gapped environments with no internet access, for regulated industries.

Adds distributed deployment and official support on top of the open-source edition, activated by license key.

→ Talk to us about self-managed deployment |
| --- | --- |

Just want to run the open-source edition? Go ahead — you don't need to contact anyone. Head to Quick start.

Research Copy Chapter

OpenViking open-sources a subset of the core capabilities described in the VikingMem paper:

VikingMem: A Memory Base Management System for Stateful LLM-based Applications
Jiajie Fu, Junwen Chen, Mengzhao Wang, Aoxiang He, Maojia Sheng, Xiangyu Ke, Yifan Zhu, and Yunjun Gao.
arXiv:2605.29640, 2026. Accepted by VLDB 2026.
📄 Read the paper on arXiv

Partner Projects Copy Chapter

OpenViking welcomes collaboration with other open-source projects to build the context data ecosystem. Our confirmed partners include:

• deer-flow - Open-source long-horizon SuperAgent harness
• NoKV - AI native distributed file system
• loopx - Lightweight loop engineering state kernel
• Hermes Agent - The agent that grows with you

Interested in joining our partner list? Please submit an issue to our community to apply.

Community & contributing Copy Chapter

OpenViking is still in its early stages, and there is plenty left to build.

• Docs: docs.openviking.ai · FAQ
• Blog: blog.openviking.ai
• Team: About us
• Chat: 📱 Lark Group · 💬 WeChat · 🎮 Discord · 🐦 X
• Contribute: bug fixes and new features are both welcome — see CONTRIBUTING.md

Security and privacy Copy Chapter

This project takes security seriously.
For vulnerability reporting and supported versions, see SECURITY.md

License Copy Chapter

The OpenViking project uses different licenses for different components:

• Main Project: AGPLv3 - see the LICENSE file for details
• crates/ov_cli: Apache 2.0 - see the LICENSE for details
• examples: Apache 2.0 - see the LICENSE for details
• third_party: Respective original licenses of third-party projects

File: bot/deploy/docker/README.md Copy Chapter

Vikingbot Docker 一键部署

本目录提供 Vikingbot 的 Docker 一键部署脚本，支持本地快速部署和多架构支持。

前置要求 Copy Chapter

请先安装 Docker：

• macOS: 下载 Docker Desktop
• Windows: 下载 Docker Desktop
• Linux: 参考 Docker 官方文档

部署脚本还会使用 Python 3 验证现有 ov.conf 的 JSON 结构和 Gateway 端口。

验证依赖：

docker --version
python3 --version

快速开始 Copy Chapter

从火山引擎镜像部署（推荐） Copy Section

如果你已经有推送到火山引擎镜像仓库的镜像，可以直接拉取并部署：

# 1. 创建必要的目录结构
mkdir -p ~/.vikingbot/

# 2. 启动容器
docker run -d \
    --name vikingbot \
    --restart unless-stopped \
    --platform linux/amd64 \
    -v ~/.vikingbot:/root/.vikingbot \
    -p 18791:18791 \
    vikingbot-cn-beijing.cr.volces.com/vikingbot/vikingbot:latest \
    gateway

# 3. 查看日志
docker logs --tail 50 -f vikingbot

按 Ctrl+C 退出日志查看，容器继续后台运行。

本地代码构建镜像部署 Copy Section

如果你想从本地代码构建镜像并部署：

一行命令部署

./deploy/docker/deploy.sh

脚本会自动检测本地架构（arm64/amd64）并构建适配的镜像。

分步部署

1. 构建镜像

./deploy/docker/build-image.sh

2. 部署服务

./deploy/docker/deploy.sh

3. 停止服务

./deploy/docker/stop.sh

多架构支持 Copy Chapter

脚本自动支持多架构，无需手动配置！

自动检测（推荐） Copy Section

脚本会自动检测你的系统架构并使用对应镜像：

# Apple Silicon (M1/M2/M3) - 自动使用 linux/arm64
./deploy/docker/deploy.sh

# Intel/AMD - 自动使用 linux/amd64
./deploy/docker/deploy.sh

手动指定架构 Copy Section

如需手动指定：

# 构建 arm64 镜像（Apple Silicon）
PLATFORM=linux/arm64 ./deploy/docker/build-image.sh

# 构建 amd64 镜像（Intel/AMD）
PLATFORM=linux/amd64 ./deploy/docker/build-image.sh

# 同时构建两个架构（多架构镜像）
MULTI_ARCH=true ./deploy/docker/build-image.sh

使用指定架构部署 Copy Section

# 使用 arm64 镜像部署
PLATFORM=linux/arm64 ./deploy/docker/deploy.sh

# 使用 amd64 镜像部署
PLATFORM=linux/amd64 ./deploy/docker/deploy.sh

文件说明 Copy Chapter

使用 Docker Compose Copy Chapter

项目根目录也提供了 docker-compose.yml：

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

环境变量配置 Copy Chapter

build-image.sh Copy Section

示例：

# 构建带版本标签的镜像
IMAGE_TAG=v1.0.0 ./deploy/docker/build-image.sh

# 不使用缓存重新构建
NO_CACHE=true ./deploy/docker/build-image.sh

# 构建 arm64 镜像
PLATFORM=linux/arm64 ./deploy/docker/build-image.sh

# 同时构建 amd64+arm64 多架构镜像
MULTI_ARCH=true ./deploy/docker/build-image.sh

deploy.sh Copy Section

示例：

# 使用自定义端口
HOST_PORT=8080 ./deploy/docker/deploy.sh

# 不自动构建镜像
AUTO_BUILD=false ./deploy/docker/deploy.sh

# 强制使用 arm64 镜像
PLATFORM=linux/arm64 ./deploy/docker/deploy.sh

stop.sh Copy Section

示例：

# 完全清理（容器+镜像+数据卷）
REMOVE_IMAGE=true REMOVE_VOLUME=true ./deploy/docker/stop.sh

配置文件 Copy Chapter

首次部署时，脚本会自动创建配置文件：~/.vikingbot/ov.conf。脚本同时生成随机 Gateway Token；在非本机请求中通过 X-Gateway-Token 请求头传入该值。

编辑该文件填入你的 API keys：

{
  "bot": {
    "agents": {
      "provider": "openrouter",
      "model": "openrouter/anthropic/claude-3.5-sonnet",
      "api_key": "sk-or-xxx"
    },
    "gateway": {
      "host": "0.0.0.0",
      "port": 18791,
      "token": "脚本生成的随机值"
    }
  }
}

重要： bot.gateway.port 必须与 CONTAINER_PORT 一致；脚本默认都使用 18791。如果现有配置不是有效 JSON、缺少 bot.gateway，或端口不一致，部署会在替换旧容器前停止并提示修复配置。

访问控制台 Copy Chapter

部署成功后，访问：http://localhost:18791

常用命令 Copy Chapter

# 查看日志
docker logs -f vikingbot

# 进入容器
docker exec -it vikingbot bash

# 运行 vikingbot 命令
docker exec vikingbot vikingbot status

# 重启容器
docker restart vikingbot

架构兼容性说明 Copy Chapter

与 VKE 部署共用 Dockerfile Copy Chapter

注意：本地 Docker 部署和 VKE 部署共用同一个 Dockerfile（deploy/Dockerfile），确保了环境一致性。

• VKE 部署：使用 deploy/vke/vke_deploy.py
• 本地部署：使用 deploy/docker/deploy.sh
• 两者都使用：deploy/Dockerfile

Dockerfile 已移除平台硬编码，支持灵活的多架构构建！

跨平台镜像构建（推送到仓库） Copy Chapter

如果你需要构建可以在 Windows/Mac/Linux 多平台运行的镜像，可以使用 build-multiarch.sh：

前置准备 Copy Section

1. 准备一个 Docker 镜像仓库（如 Docker Hub, ACR, Harbor 等）
2. 登录到镜像仓库

构建并推送跨平台镜像 Copy Section

# 构建 linux/amd64 + linux/arm64 双架构镜像并推送
REGISTRY=your-registry.com PUSH=true ./deploy/docker/build-multiarch.sh

环境变量配置 Copy Section

使用跨平台镜像 Copy Section

推送成功后，在任何平台都可以直接使用：

# 在 Apple Silicon Mac 上
PLATFORM=linux/arm64 ./deploy/docker/deploy.sh

# 在 Intel/AMD Linux 上
PLATFORM=linux/amd64 ./deploy/docker/deploy.sh

# 或让脚本自动检测
./deploy/docker/deploy.sh

验证镜像架构 Copy Section

# 查看镜像支持的架构
docker manifest inspect your-registry.com/vikingbot:latest

File: bot/deploy/vke/README.md Copy Chapter

VKE 部署指南

本文档介绍如何将 Vikingbot 部署到火山引擎容器服务（VKE）。

目录 Copy Chapter

• 架构概述
• 前置准备
  • 1. 火山引擎账号
  • 2. 创建 VKE 集群
  • 3. 创建容器镜像仓库
  • 4. 创建 TOS 存储桶（可选）
  • 5. 获取访问凭证
  • 6. 配置本地环境
• 快速部署
• 配置详解
• 手动部署
• 验证部署
• 故障排查

架构概述 Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

前置准备 Copy Chapter

1. 火山引擎账号 Copy Section

• 注册火山引擎账号：https://www.volcengine.com/
• 完成实名认证
• 开通以下服务：
  • 容器服务 VKE
  • 容器镜像服务 CR
  • 对象存储 TOS（可选，用于持久化存储）

2. 创建 VKE 集群 Copy Section

1. 登录火山引擎控制台
2. 进入 容器服务 VKE → 集群
3. 点击 创建集群
4. 配置集群参数：
   • 集群名称：vikingbot（或自定义）
   • Kubernetes 版本：选择最新稳定版（推荐 1.24+）
   • 容器运行时：containerd
   • 网络模式：Flannel 或 Calico
   • Service CIDR：默认即可
5. 配置节点池：
   • 节点规格：推荐 2核4G 或更高（ecs.g1.large）
   • 节点数量：至少 2 个节点
   • 系统盘：40Gi SSD
6. 确认配置并创建集群

等待集群创建完成（约 10-15 分钟）

3. 创建容器镜像仓库 Copy Section

1. 进入 容器镜像服务 CR → 命名空间
2. 点击 创建命名空间
   • 名称：vikingbot
   • 类型：私有
3. 进入 镜像仓库
4. 点击 创建镜像仓库
   • 名称：vikingbot
   • 命名空间：选择刚才创建的 vikingbot
   • 描述：Vikingbot 镜像仓库

4. 创建 TOS 存储桶（可选） Copy Section

如果使用 TOS 作为持久化存储，需要创建存储桶：

1. 进入 对象存储 TOS → 存储桶列表
2. 点击 创建存储桶
3. 配置参数：
   • 名称：vikingbot-data（或自定义）
   • 地域：选择与 VKE 集群相同的地域（如 cn-beijing）
   • 存储类型：标准存储
   • 权限：私有
4. 点击 确定 创建

5. 获取访问凭证 Copy Section

5.1 创建 AccessKey（仅 TOS 存储需要）

1. 鼠标悬停在右上角头像，点击 API 访问密钥
2. 点击 新建密钥
3. 完成手机验证
4. 保存生成的 AccessKey ID 和 Secret Access Key

重要：Secret Access Key 只显示一次，请妥善保存！

5.2 获取 Kubeconfig

1. 进入 容器服务 VKE → 集群
2. 找到你的集群，点击 连接
3. 在 集群访问凭证 页签，点击 下载 获取 Kubeconfig
4. 将下载的文件保存到 ~/.kube/config，或配置 KUBECONFIG 环境变量

验证连接：

kubectl get nodes

6. 配置本地环境 Copy Section

确保本地已安装：

• Docker：用于构建镜像
• kubectl：用于操作 Kubernetes 集群
• Python 3：部署脚本需要

验证安装：

docker --version
kubectl version --client
python3 --version

快速部署 Copy Chapter

步骤 1：复制配置文件 Copy Section

mkdir -p ~/.config/vikingbot
cp deploy/vke/vke_deploy.example.yaml ~/.config/vikingbot/vke_deploy.yaml

步骤 2：编辑配置 Copy Section

vim ~/.config/vikingbot/vke_deploy.yaml

填入以下信息：

volcengine_region: cn-beijing               # 地域

image_registry: vikingbot-cn-beijing.cr.volces.com  # 镜像仓库地址
image_namespace: vikingbot
image_repository: vikingbot
image_tag: latest

# 镜像仓库登录凭证（如果是私有仓库）
registry_username: "你的火山引擎账号"
registry_password: "你的火山引擎密码"

# 存储类型：local (EBS) 或 tos
storage_type: tos

# TOS 配置（仅 storage_type=tos 时需要）
volcengine_access_key: AKLTxxxxxxxxxx
volcengine_secret_key: xxxxxxxxxx
tos_bucket: vikingbot_data
tos_path: /.vikingbot/
tos_region: cn-beijing

步骤 3：执行部署 Copy Section

cd /path/to/vikingbot
chmod +x deploy/vke/deploy.sh
deploy/vke/deploy.sh

部署脚本会自动完成：

1. 构建 Docker 镜像
2. 推送镜像到火山引擎 CR
3. 创建 K8s 资源（Secret、PV、PVC、Deployment、Service）
4. 等待部署完成

配置详解 Copy Chapter

vke_deploy.yaml 配置项 Copy Section

手动部署 Copy Chapter

如果不想使用一键部署脚本，可以按以下步骤手动操作。

1. 构建并推送镜像 Copy Section

# 构建镜像
docker build --platform linux/amd64 -f deploy/Dockerfile -t vikingbot .

# 登录镜像仓库
docker login vikingbot-cn-beijing.cr.volces.com -u  -p 

# Tag 镜像
docker tag vikingbot vikingbot-cn-beijing.cr.volces.com/vikingbot/vikingbot:latest

# 推送
docker push vikingbot-cn-beijing.cr.volces.com/vikingbot/vikingbot:latest

2. 准备 Kubernetes Manifest Copy Section

复制 deploy/vke/k8s/deployment.yaml，替换以下变量：

• __IMAGE_NAME__：完整镜像名
• __REPLICAS__：副本数
• __ACCESS_MODES__：访问模式（ReadWriteOnce 或 ReadWriteMany）
• __STORAGE_CLASS_CONFIG__：StorageClass 配置
• __VOLUME_NAME_CONFIG__：VolumeName 配置

3. 创建 TOS Secret（仅使用 TOS 时） Copy Section

# Base64 编码 AccessKey
AK_B64=$(echo -n "your-access-key" | base64)
SK_B64=$(echo -n "your-secret-key" | base64)

# 创建 Secret
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: vikingbot-tos-secret
type: Opaque
data:
  AccessKeyId: ${AK_B64}
  SecretAccessKey: ${SK_B64}
EOF

4. 部署应用 Copy Section

kubectl apply -f deploy/vke/k8s/deployment.yaml

验证部署 Copy Chapter

查看 Pod 状态 Copy Section

kubectl get pods -l app=vikingbot

预期输出：

NAME                         READY   STATUS    RESTARTS   AGE
vikingbot-746d99fd94-xxxxx   1/1     Running   0          2m

查看 Service Copy Section

kubectl get svc vikingbot

查看日志 Copy Section

# 查看所有 Pod 日志
kubectl logs -l app=vikingbot --tail=100

# 跟随日志
kubectl logs -f deployment/vikingbot

查看部署状态 Copy Section

kubectl rollout status deployment/vikingbot

访问 Gateway（本地端口转发） Copy Section

kubectl port-forward svc/vikingbot 8080:80

然后访问：http://localhost:8080

故障排查 Copy Chapter

Pod 无法启动 Copy Section

# 查看 Pod 事件
kubectl describe pod 

# 查看日志
kubectl logs

镜像拉取失败 Copy Section

检查：

1. 镜像仓库地址是否正确
2. 镜像是否已推送
3. 仓库是否为私有，是否配置了 ImagePullSecret

存储挂载失败 Copy Section

# 查看 PVC 状态
kubectl get pvc

# 查看 PV 状态
kubectl get pv

# 查看事件
kubectl describe pvc vikingbot-data

健康检查失败 Copy Section

健康检查路径：/health，端口：18791

# 进入 Pod 内部检查
kubectl exec -it  -- bash

# 在 Pod 内测试
curl http://localhost:18791/health

常用命令 Copy Chapter

# 扩容/缩容
kubectl scale deployment vikingbot --replicas=3

# 更新镜像
kubectl set image deployment/vikingbot vikingbot=vikingbot-cn-beijing.cr.volces.com/vikingbot/vikingbot:new-tag

# 重启 Deployment
kubectl rollout restart deployment/vikingbot

# 回滚
kubectl rollout undo deployment/vikingbot

# 删除所有资源
kubectl delete -f deploy/vke/k8s/deployment.yaml

附录 Copy Chapter

地域列表 Copy Section

镜像仓库地址格式 Copy Section

{namespace}-{region}.cr.volces.com

示例：vikingbot-cn-beijing.cr.volces.com

参考链接 Copy Chapter

• 火山引擎 VKE 文档
• 火山引擎 CR 文档
• 火山引擎 TOS 文档
• Kubernetes 官方文档

File: bot/vikingbot/console/README_GRADIO.md Copy Chapter

Vikingbot Console - Gradio 版本

使用 Gradio 实现的纯 Python 控制台界面。

运行 Copy Chapter

vikingbot gateway

这会自动在 http://localhost:18791 启动控制台 Web UI！

功能 Copy Chapter

1. Dashboard Copy Section

• 显示系统状态
• 版本信息
• 配置路径和工作区路径

2. Config Copy Section

• Skills & Hooks: 独立标签页
• Agents / Providers / Channels / Gateway / Tools / Sandbox / Heartbeat: 每个在自己的标签页中
  • Agents: 展开 AgentDefaults
  • Providers: 每个 provider 在自己的子标签页中
  • Sandbox: backends 在自己的子标签页中
  • Channels: JSON 编辑器（可配置多个 channel）
  • Enums: 使用下拉框（SandboxBackend, SandboxMode）

3. Sessions Copy Section

• 刷新按钮：加载会话列表
• 会话选择：选择会话查看内容
• 会话内容显示：
  • 用户消息：绿色
  • 助手消息：红色
  • 其他消息：黑色

4. Workspace Copy Section

• 使用 Gradio 的 FileExplorer 组件
• 显示工作区文件树
• 选择文件查看内容

File: bot/vikingbot/openviking_mount/README.md Copy Chapter

OpenViking 文件系统挂载模块

这个模块将 OpenViking 的虚拟文件系统挂载到本地文件系统路径，让用户可以像操作普通文件一样操作 OpenViking 上的数据。

这个模块只是一个实验功能，并没有被实际使用

功能特性 Copy Chapter

• 文件系统范式: 将 OpenViking 的 viking:// URI 映射到本地文件路径
• 多作用域支持: 支持 resources、session、user 等多种作用域挂载
• 挂载管理: 支持多个挂载点的生命周期管理
• 语义搜索: 通过文件系统路径进行语义搜索
• 层级内容访问: 支持 L0 (abstract)、L1 (overview)、L2 (details) 三层内容访问

快速开始 Copy Chapter

基本使用 Copy Section

from vikingbot.openviking_mount import OpenVikingMount, MountConfig, MountScope
from pathlib import Path

# 创建挂载配置
config = MountConfig(
    mount_point=Path("./my_openviking_mount"),
    openviking_data_path=Path("./my_openviking_cache"),
    scope=MountScope.RESOURCES,
    auto_init=True,
    read_only=False
)

# 使用上下文管理器
with OpenVikingMount(config) as mount:
    # 列出目录
    files = mount.list_dir(mount.config.mount_point)
    for f in files:
        print(f"{f.name} ({'目录' if f.is_dir else '文件'})")
    
    # 读取文件
    content = mount.read_file(mount.config.mount_point / "some_file.md")
    print(content)
    
    # 获取摘要和概览
    abstract = mount.get_abstract(mount.config.mount_point / "some_dir")
    overview = mount.get_overview(mount.config.mount_point / "some_dir")
    print(f"摘要: {abstract}")
    print(f"概览: {overview}")
    
    # 语义搜索
    results = mount.search("什么是 OpenViking")
    for r in results:
        print(f"{r.uri}")

使用挂载管理器 Copy Section

from vikingbot.openviking_mount import OpenVikingMountManager, get_mount_manager
from pathlib import Path

# 获取全局管理器
manager = get_mount_manager()

# 创建资源挂载
mount = manager.create_resources_mount(
    mount_id="my_resources",
    openviking_data_path=Path("./ov_cache")
)

# 为会话创建挂载
session_mount = manager.create_session_mount(
    session_id="session_123",
    openviking_data_path=Path("./ov_cache")
)

# 列出所有挂载
mounts = manager.list_mounts()
for m in mounts:
    print(f"{m['id']} -> {m['mount_point']}")

# 获取挂载
mount = manager.get_mount("my_resources")

# 移除挂载
manager.remove_mount("my_resources", cleanup=True)

目录结构 Copy Chapter

vikingbot/openviking_mount/
├── __init__.py          # 模块入口，导出公共API
├── mount.py             # 核心挂载实现 (OpenVikingMount)
└── manager.py           # 挂载管理器 (OpenVikingMountManager)

API 参考 Copy Chapter

OpenVikingMount Copy Section

主要的挂载类，提供文件系统操作。

初始化参数

MountConfig

MountScope 枚举

主要方法

OpenVikingMountManager Copy Section

挂载管理器，管理多个挂载点的生命周期。

主要方法

全局函数 Copy Section

路径映射 Copy Chapter

OpenViking URI 到本地文件路径的映射规则：

OpenViking URI                    本地路径
-------------------               ------------------
viking://resources/foo     ->    {mount_point}/resources/foo
viking://session/bar       ->    {mount_point}/session/bar
viking://user/baz          ->    {mount_point}/user/baz

测试 Copy Chapter

运行测试：

cd /Users/bytedance/workspace/openviking/bot
.venv/bin/python test_openviking_mount.py

注意事项 Copy Chapter

1. 直接写入限制: OpenViking 主要通过 add_resource 添加外部资源，直接文件写入需要特殊处理
2. 性能考虑: 大量文件操作可能影响性能，建议批量处理
3. 数据同步: sync_to_disk 是一个简化实现，生产环境可能需要更复杂的同步机制
4. 只读模式: 设置 read_only=True 可以防止意外修改

下一步 Copy Chapter

• 集成到 vikingbot 的 SessionManager 中
• 添加 FUSE 支持实现真正的文件系统挂载
• 实现更完善的双向同步机制
• 添加更多测试用例

File: bot/workspace/skills/README.md Copy Chapter

vikingbot Skills

This directory contains built-in skills that extend vikingbot's capabilities.

Skill Format Copy Chapter

Each skill is a directory containing a SKILL.md file with:

• YAML frontmatter (name, description, metadata)
• Markdown instructions for the agent

Attribution Copy Chapter

These skills are adapted from OpenClaw's skill system.
The skill format and metadata structure follow OpenClaw's conventions to maintain compatibility.

Available Skills Copy Chapter