Provider	Model Example	Notes
openai	gpt-4o	Official OpenAI API
volcengine

Tier	Purpose	Token Budget	Behavior
L0	Active working memory	4K tokens	Always loaded, fast access
L1

OpenViking Setup for OpenClaw

OpenViking 为 AI 智能体提供基于文件系统的内存管理，支持分层上下文加载和自进化记忆。本技能将引导您完成安装和配置。

OpenViking 提供的功能

- 文件系统范式：统一上下文管理（记忆、资源、技能）
分层加载（L0/L1/L2）：仅加载所需内容，节省 Token
自进化记忆：越用越智能
OpenClaw 插件：提供原生集成支持

前置条件

- Python 3.10+
Go 1.22+（用于 AGFS 组件）
GCC 9+ 或 Clang 11+（用于核心扩展）
VLM 模型访问权限（用于图像/内容理解）
Embedding 模型访问权限（用于向量化）

快速开始

步骤 1：安装 OpenViking

bash

Python 包

pip install openviking --upgrade --force-reinstall

CLI 工具

curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash

步骤 2：创建配置文件

创建 ~/.openviking/ov.conf：

json
{
storage: {
workspace: /home/your-name/openviking_workspace
},
log: {
level: INFO,
output: stdout
},
embedding: {
dense: {
api_base: https://api.openai.com/v1,
api_key: your-openai-api-key,
provider: openai,
dimension: 1536,
model: text-embedding-3-small
},
max_concurrent: 10
},
vlm: {
api_base: https://api.openai.com/v1,
api_key: your-openai-api-key,
provider: openai,
model: gpt-4o,
max_concurrent: 100
}
}

步骤 3：配置提供商

OpenViking 支持多种 VLM 提供商：

提供商	模型示例	说明
openai	gpt-4o	官方 OpenAI API
volcengine

对于 LiteLLM（推荐，灵活性更高）：

json
{
vlm: {
provider: litellm,
model: claude-3-5-sonnet-20241022,
api_key: your-anthropic-key
}
}

对于 Ollama（本地模型）：

json
{
vlm: {
provider: litellm,
model: ollama/llama3.1,
api_base: http://localhost:11434
}
}

OpenClaw 集成

插件安装

OpenViking 提供原生 OpenClaw 插件，实现无缝集成：

bash

安装 OpenClaw 插件

pip install openviking-openclaw

或从源码安装

git clone https://github.com/volcengine/OpenViking cd OpenViking/plugins/openclaw pip install -e .

OpenClaw 配置

添加到您的 OpenClaw 配置中：

yaml

~/.openclaw/config.yaml

memory:
provider: openviking
config:
workspace: ~/.openviking/workspace
tiers:
l0:
max_tokens: 4000
auto_flush: true
l1:
max_tokens: 16000
compression: true
l2:
max_tokens: 100000
archive: true

内存层级说明

层级	用途	Token 预算	行为
L0	活跃工作内存	4K tokens	始终加载，快速访问
L1

层级工作原理

1. 新上下文进入 L0
L0 填满 → 最旧项目压缩至 L1
L1 填满 → 最旧项目归档至 L2
检索时搜索所有层级，返回相关上下文

目录结构

~/.openviking/
├── ov.conf # 配置文件
└── workspace/
├── memories/
│ ├── sessions/ # L0：活跃会话记忆
│ ├── compressed/ # L1：压缩记忆
│ └── archive/ # L2：长期存储
├── resources/ # 文件、文档、资源
└── skills/ # 技能特定上下文

使用模式

添加记忆

python
from openviking import MemoryStore

store = MemoryStore()

添加到 L0

store.add_memory( content=用户偏好葡萄牙语回复, metadata={tier: l0, category: preference} )

添加资源

store.add_resource( path=project_spec.md, content=open(project_spec.md).read() )

检索上下文

python

跨所有层级语义搜索

results = store.search(
query=用户偏好,
tiers=[l0, l1, l2],
limit=10
)

基于目录的检索（更精确）

results = store.retrieve( path=memories/sessions/2026-03-16/, recursive=True )

压缩

python

触发手动压缩

store.compact()

查看压缩状态

status = store.status() print(fL0: {status.l0tokens}/{status.l0max}) print(fL1: {status.l1tokens}/{status.l1max})

最佳实践

记忆维护

1. 分类条目：使用元数据标签以便更好地检索
定期刷新 L0：让压缩机制运行，不要囤积
使用目录结构：按项目/主题组织
定期审查 L2：归档过时记忆

Token 效率

1. 让 OpenViking 自动管理层级
对 L2 使用语义搜索（不要加载整个归档）
在添加到 L1 前压缩冗长内容
保持 L0 容量低于 50% 以获得最佳性能

OpenClaw 工作流

1. 会话开始 → OpenViking 加载 L0
对话进行 → 上下文自动升级至 L1/L2
长时间间隔 → L2 提供相关历史上下文
会话累积 → 智能体随时间变得更智能

故障排除

常见问题

No module named openviking

- 确保 Python 3.10+ 已激活
尝试 pip install --user openviking

Embedding model not found

- 检查 ov.conf 中的提供商和模型是否正确
验证 API 密钥是否有效

L0 overflow

- 在配置中减少 l0.max_tokens
手动调用 store.compact()

Slow retrieval from L2

- 考虑将频繁访问的资源预加载到 L1
使用基于目录的检索以获得更好的精确度

资源

- GitHub：https://github.com/volcengine/OpenViking
文档：https://github.com/volcengine/OpenViking/tree/main/docs
OpenClaw 插件：https://github.com/volcengine/OpenViking/tree/main/plugins/openclaw
示例：https://github.com/volcengine/OpenViking/tree/main/examples

效果提升

设置完成后，您的智能体将获得：

1. 跨会话的持久记忆
更智能的检索，支持语义 + 目录搜索
Token 效率，通过分层加载实现
自我改进，随着上下文积累
可观察的上下文，带有检索轨迹

智能体工作得越多，保留的上下文就越多——而不会出现 Token 膨胀。

openviking-setupOpenViking设置