# OpenViking > 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。 **OpenViking** 是专为 AI 智能体（Agent）打造的上下文数据库，主要适用于多 Agent 协同、长期记忆管理、复杂任务执行等场景。该数据库采用 `viking:// `文件系统范式，将智能体的**记忆、资源与技能**进行统一组织管理，依托分层加载机制按需供给上下文，在减少 Token 消耗的同时提升运行效率，结合目录式检索优化信息召回效果。功能上，OpenViking 支持**多租户、多用户及多 Agent 隔离**，且能在会话结束后自动沉淀长期记忆，实现智能体能力的持续积累与自我优化，既有效降低开发者的上下文管理成本，也能显著提升 OpenClaw 等智能体的整体运行表现。 方舟 Coding Plan 支持在 OpenViking 中使用，可参考本文进行配置及使用。 > **注意** > > OpenViking 工具处于快速迭代阶段，本文使用的版本为 **0.4.15**，如果实际使用与以下步骤存在差异，可参见 [OpenViking：AI 智能体的上下文数据库](https://github.com/volcengine/OpenViking/blob/main/docs/repository/README_CN.md)。 > **说明** > > 需要先访问 [方舟 Coding Plan活动](https://www.volcengine.com/activity/codingplan)，按需订阅套餐后再配置使用工具。 # 核心配置 ## 模型配置 ### VLM 模型 Coding Plan 支持的 VLM 模型及配置方式如下： **选项：配置 Model Name (配置文件指定)** 在工具配置文件中指定 Model Name，可实时切换模型。支持配置的 Model Name： > **注意** > > 配置 Model Name 时，支持使用全小写格式，同时也支持直接复制 [开通管理页面](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=subscribe) 中的模型名称。 * `doubao-seed-2.1-pro` * `doubao-seed-2.1-lite` * `doubao-seed-evolving` * `minimax-m2.7` * `minimax-m3` * `glm-5.3` * `glm-5.3-flash` * `deepseek-v4-flash` * `deepseek-v4-pro` * `kimi-k2.6` * `kimi-k2.8-preview` * `kimi-k3` > **说明** > > Model Name 不支持配置为 `Auto`，如需使用，请通过控制台切换该模式。 **选项：配置 ark-code-latest (控制台管理)** 1. 在配置文件中指定模型为`ark-code-latest`。 2. 通过 [开通管理页面](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=subscribe) 选择或切换目标模型，切换模型后 3-5 分钟即可生效。 支持 Auto 模式，通过「效果 + 速度」双维度智能算法自动选择模型。 ### Embedding 模型 Coding Plan 支持的 Embedding 模型：`doubao-embedding-vision` ## Base URL 使用 Coding Plan 专属 Base URL：`https://ark.cn-beijing.volces.com/api/coding/v3`（兼容 OpenAI 接口协议） > **注意** > > 请使用 Coding Plan 专属 Base URL，否则会产生额外费用。 ## API Key [获取 API Key](https://ark.volcengine.com/region:cn-beijing/apikey) # 一、前提条件 * 已安装 [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 执行以下命令安装 OpenViking。 ```Bash pip install openviking --upgrade --force-reinstall ``` 安装结束后，执行以下命令查看安装结果，若显示版本号则安装成功。 ```Bash openviking --version ``` # 三、配置 OpenViking 1. 创建配置文件`~/.openviking/ov.conf`，配置信息如下。需要修改的配置信息如下： * `storage.workspace`：替换为实际的工作空间路径。 * `embedding`：配置 Embedding 模型，用于向量化和语义检索。 * `embedding.dense.model`：支持的 Embedding 模型 `doubao-embedding-vision`。 * `embedding.dense.api_key`：替换为您自己的 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。 * `vlm`：配置 VLM 模型，用于图像和内容理解。 * `vlm.model`：支持的 VLM 模型，具体参见[VLM 模型](/docs/coding-plan-personal-ai-openviking#47a3a76a)。 * `vlm.api_key`：替换为您自己的 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。 ```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/coding/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/coding/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/coding-plan-personal-ai-openviking#30f6a2c6)、[配置 OpenViking](/docs/coding-plan-personal-ai-openviking#ceac2da4)。 ### 启动服务 执行以下命令启动服务。 ```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/apikey)。 ```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/coding-plan-personal-ai-openclaw#b51c87f8)、[配置 OpenClaw](/docs/coding-plan-personal-ai-openclaw#48c0b1ea)。 ### 安装及配置 具体步骤参见 [为 OpenClaw 安装 OpenViking 记忆功能](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL-ZH.md)。 安装完成后，编辑配置文件`~/.openviking/ov.conf`，使用 Coding Plan 支持的模型。配置信息可参见 [配置工具](/docs/coding-plan-personal-ai-openviking#ceac2da4)。