# OpenViking > 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。 OpenViking 是专为 AI 智能体（Agent）打造的上下文数据库，主要适用于多 Agent 协同、长期记忆管理、复杂任务执行等场景。该数据库采用 viking://文件系统范式，将智能体的记忆、资源与技能进行统一组织管理，依托分层加载机制按需供给上下文，在减少 Token 消耗的同时提升运行效率，结合目录式检索优化信息召回效果。功能上，OpenViking 支持多租户、多用户及多 Agent 隔离，且能在会话结束后自动沉淀长期记忆，实现智能体能力的持续积累与自我优化，既有效降低开发者的上下文管理成本，也能显著提升 OpenClaw 等智能体的整体运行表现。​ 本文介绍如何在 OpenViking 中配置并使用方舟 Agent Plan 企业版。 > **注意** > > OpenViking 工具处于快速迭代阶段，本文使用的版本为 **0.4.15**。如果实际使用方式与本文存在差异，请参见 [OpenViking：AI 智能体的上下文数据库](https://github.com/volcengine/OpenViking/blob/main/docs/repository/README_CN.md)。 ## 前提条件 需由管理员账号完成以下操作后，子账号方可配置并使用 OpenViking： 1. **购买套餐**：[一、购买 Agent Plan 企业版](/docs/agent-plan-enterprise-get-started#purchase-plan)。 2. **分配席位**：[二、分配席位](/docs/agent-plan-enterprise-get-started#assign-seats)。 本地环境需满足以下要求： - 已安装 [Python 3.10 或更高版本](https://wiki.python.org/moin/BeginnersGuide/Download)。 - 已安装 [Go 1.22 或更高版本](https://golang.google.cn/dl/)。 - 已安装 C++ 编译器，且 GCC 版本不低于 9，或 Clang 版本不低于 11。 > **说明** > > - 通过命令 `clang++ --version` 和 `clang++ -std=c++17 -E -x c++ - < /dev/null`，检查 C++编译器支持情况。 > - 如果执行 `pip install openviking` 时提示 "No matching distribution found"，请先运行 `python3 --version` 确认 Python 版本不低于 3.10。 ## 安装 OpenViking 1. 执行以下命令安装 OpenViking。 ```Bash pip install openviking --upgrade --force-reinstall ``` 2. 执行以下命令查看安装结果。 ```Bash openviking --version ``` 如果命令返回版本号，则表示 OpenViking 安装成功。 ## 配置 OpenViking 1. 创建配置文件 `~/.openviking/ov.conf`，并按以下说明修改配置： - `storage.workspace`：替换为实际的工作空间路径。 - `embedding`：配置向量化模型，用于向量化和语义检索。 - `embedding.dense.model`：支持的 Embedding 模型 `doubao-embedding-vision`。 - `embedding.dense.api_key`：替换为您自己的 [专属 API Key](https://ark.volcengine.com/region:cn-beijing/subscription/agent-plan-enterprise/mine)。 - `vlm`：配置语言模型，用于图像和内容理解。 - `vlm.model`：支持的语言模型。具体参见[支持模型及 Harness](/docs/agent-plan-enterprise-plan-overview#supported-models-harness)。 - `vlm.api_key`：替换为您自己的 [专属 API Key](https://ark.volcengine.com/region:cn-beijing/subscription/agent-plan-enterprise/mine)。 ![获取专属 API Key](https://arkdocs.tos-cn-beijing.volces.com/images/agent-plan/agent-plan-enterprise-api-key.png) ```JSON { "storage": { "workspace": "/home/your-name/openviking_workspace" }, "log": { "level": "INFO", "output": "stdout" }, "embedding": { "dense": { "backend": "volcengine", "api_key": "", "model": "doubao-embedding-vision", "api_base": "https://ark.cn-beijing.volces.com/api/plan/v3", "dimension": 1024, "input": "multimodal" } }, "vlm": { "backend": "volcengine", "api_key": "", "model": "doubao-seed-2.1-pro", "api_base": "https://ark.cn-beijing.volces.com/api/plan/v3", "temperature": 0.1, "max_retries": 3 } } ``` 2. 根据系统环境选择对应的方式设置环境变量。​ > **说明** > > 如果配置文件位于其他路径，需要在环境变量中指定对应的文件路径。 **选项：macOS/Linux** ```Bash export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf ``` **选项：Windows** 在 PowerShell 中执行： ```Bash $env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf" ``` 或在 CMD 中执行： ```Bash set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf" ``` ## 使用 OpenViking > **说明** > > 需要先在另一个终端执行 `openviking-server` 启动服务，再运行下面的 Python 示例。 1. 创建 Python 文件`example.py`，代码内容如下。 ```Python from openviking_sdk import SyncHTTPClient # Initialize OpenViking HTTP client client = SyncHTTPClient(url="http://localhost:1933", api_key="") try: # Initialize the client client.initialize() # Add resource (supports URL, file, or directory) add_result = client.add_resource( path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md" ) root_uri = add_result['root_uri'] # Explore the resource tree structure ls_result = client.ls(root_uri) print(f"Directory structure:\n{ls_result}\n") # Use glob to find markdown files glob_result = client.glob(pattern="**/*.md", uri=root_uri) if glob_result['matches']: content = client.read(glob_result['matches'][0]) print(f"Content preview: {content[:200]}...\n") # Wait for semantic processing to complete print("Wait for semantic processing...") client.wait_processed(timeout=120) # Get abstract and overview of the resource abstract = client.abstract(root_uri) overview = client.overview(root_uri) print(f"Abstract:\n{abstract}\n\nOverview:\n{overview}\n") # Perform semantic search results = client.find("what is openviking", target_uri=root_uri) print("Search results:") for r in results.get("resources", []): print(f" {r['uri']} (score: {r['score']:.4f})") # Close the client client.close() except Exception as e: print(f"Error: {e}") ``` 2. 执行命令 `python example.py`，输出如下内容则说明 OpenViking 已成功运行。 ``` Directory structure: ... Content preview: ... Wait for semantic processing... Abstract: ... Overview: ... Search results: viking://resources/... (score: 0.8523) ... ``` ## 其他操作 ### CLI 服务端配置并使用 OpenViking 如果需要将 OpenViking 作为独立的 HTTP 服务运行，然后从任意客户端连接，请参考以下步骤进行配置。 #### 前提条件 已安装并完成配置 OpenViking，具体参见 [安装 OpenViking](/docs/agent-plan-enterprise-openviking#install-openviking)、[配置 OpenViking](/docs/agent-plan-enterprise-openviking#configure-openviking)。 #### 启动服务 执行以下命令启动服务。 ```Bash openviking-server ``` 启动完成后，在新的命令行界面执行以下命令验证服务启动是否成功，若返回`"status":"ok"`则表示启动成功。 ```Bash curl http://localhost:1933/health ``` #### 使用 CLI 连接 1. 创建 CLI 连接配置文件 `~/.openviking/ovcli.conf`，配置信息如下。其中``需替换为您自己的 [专属 API Key](https://ark.volcengine.com/region:cn-beijing/subscription/agent-plan-enterprise/mine)。 ```JSON { "url": "http://localhost:1933", "api_key": "", "output": "table" } ``` 2. 在新的命令行界面执行以下 CLI 命令。 ```Bash # Check system health openviking observer system # Add a resource to memory openviking add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md # List all synchronized resources openviking ls viking://resources # Query openviking find "what is openviking" ``` #### 使用 curl 连接 启动服务后，也可以在命令行界面使用 curl 命令连接 OpenViking。 ```Bash # Add a resource curl -X POST http://localhost:1933/api/v1/resources \ -H "Content-Type: application/json" \ -d '{"path": "https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"}' # List resources curl "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/" # Semantic search curl -X POST http://localhost:1933/api/v1/search/find \ -H "Content-Type: application/json" \ -d '{"query": "what is openviking"}' ``` ### 在 OpenClaw 中配置 OpenViking 记忆功能 通过 OpenViking 为 OpenClaw 提供长效记忆能力，配置完成后，OpenClaw 将自动记住对话中的重要信息，并在回复前回忆相关内容。 #### 前提条件 已完成 OpenClaw 的安装与配置，具体参见 [安装 OpenClaw](/docs/agent-plan-enterprise-openclaw#b51c87f8)、[配置 OpenClaw](/docs/agent-plan-enterprise-openclaw#48c0b1ea)。 #### 安装及配置 具体步骤参见 [为 OpenClaw 安装 OpenViking 记忆功能](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL-ZH.md)。 安装完成后，编辑配置文件`~/.openviking/ov.conf`，使用 Agent Plan 企业版支持的模型。配置信息可参见 [配置 OpenViking](/docs/agent-plan-enterprise-openviking#configure-openviking)。