🚀 最小工作流
只保留最小可执行入口，不展开安装细节。先跑通“导入资源 → 等待处理 → 分层访问 → 检索”主链，再决定要不要上 Server / MCP / Bot。
最短路径：嵌入式 Python
import openviking as ov
client = ov.OpenViking(path="./data")
client.initialize()
res = client.add_resource(
path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"
)
root_uri = res["root_uri"]
client.wait_processed()
print(client.abstract(root_uri))
print(client.overview(root_uri))
print(client.find("what is openviking", target_uri=root_uri))
client.close()
最短路径：起 HTTP Server + CLI
# 终端 A：启动服务
openviking-server
# 终端 B：先看状态，再导资源
ov status
ov add-resource https://github.com/volcengine/OpenViking --wait
ov tree viking://resources/volcengine -L 2
ov find "what is openviking"
最短路径：HTTP Client 接远程服务
import openviking as ov
client = ov.SyncHTTPClient(
url="http://localhost:1933",
api_key=None,
timeout=120.0,
)
client.initialize()
client.add_resource(path="./document.md")
client.wait_processed()
results = client.find("search query")
client.close()
配置文件记忆法
OPENVIKING_CONFIG_FILE ~/.openviking/ov.confOPENVIKING_CLI_CONFIG_FILE ~/.openviking/ovcli.confov.confovcli.conf
🍳 高频 Recipes
cookbook 的重点不在 API 面，而在“什么时候用哪串命令”。下面这些是仓库和 zread 信息里最值得复用的路线。
把文档、仓库、网页喂进同一棵树
什么时候用：你要给 Agent 建一个长期可检索的知识底座。
ov add-resource https://github.com/volcengine/OpenViking --wait
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
ov grep "OpenViking" --uri viking://resources/volcengine/OpenViking/docs/zh
add-resource tree--wait wait- 长任务尽量别都前台阻塞：先导入，等处理，最后再集中检索。
用 L0/L1/L2 控制 token 成本
什么时候用：你要让 Agent 先做规划，再决定是否读全文。
# 先 find 锁定目录（语义定位）
ov find "hierarchical retrieval"
# 再定向读取更细内容
ov tree viking://resources/volcengine/OpenViking/docs -L 3
ov grep "directory recursive retrieval" --uri viking://resources/volcengine/OpenViking
find tree grep readabstract overview
暴露成 MCP，给外部 Agent 当工具
什么时候用：你希望 Claude 或别的支持 MCP 的 Agent 直接调用 OpenViking 的检索能力。
cd examples/mcp-query
uv sync
uv run server.py
claude mcp add --transport http openviking http://localhost:2033/mcp
query search add_resourcequery searchOV_CONFIG OV_DATA OV_PORT：（配置文件路径）、（数据目录）、（端口）。
examples/mcp-query/.mcp.json 形态（示意）：
{
"mcpServers": {
"openviking": {
"command": "python",
"args": ["server.py"],
"env": {
"OV_CONFIG": "./mcp.conf",
"OV_DATA": "./data",
"OV_PORT": "2033"
}
}
}
}
给 OpenClaw 接长期记忆
什么时候用：你已经在跑 OpenClaw，希望把记忆底座换成 OpenViking。
cd /path/to/OpenViking
npx ./examples/openclaw-memory-plugin/setup-helper
openclaw gateway
openclaw config set plugins.entries.memory-openviking.config.mode "remote"
openclaw config set plugins.entries.memory-openviking.config.baseUrl "http://your-server:1933"
openclaw config set plugins.entries.memory-openviking.config.autoRecall true --json
openclaw config set plugins.entries.memory-openviking.config.autoCapture true --json
- 本地模式：插件自动起 OpenViking，适合个人环境。
- 远程模式：OpenClaw 只连服务端，适合团队和统一运维。
- README 给出的实验数据说明，这条路线的收益不仅是效果提升，还有明显的 token 成本下降。
两分钟起一个能聊天的 VikingBot
什么时候用：你想快速验证“OpenViking + Agent”整条链，而不是自己拼装 bot。
pip install "openviking[bot]"
vikingbot gateway
vikingbot chat
vikingbot gatewayov.conf- VikingBot 自带“共享上下文 / 私有上下文”双模式：想做多 Agent 协作时优先共享，想做个人助手或隔离数据时用私有。
- 适合先验证资源管理、记忆提交和检索工具联动，再决定是否接 Feishu / Slack / Telegram。
从单机场景切到共享服务
什么时候用：你最初在本地嵌入式用得不错，现在要给多个进程、多个 Agent、多个租户共用。
openviking-server --host 0.0.0.0 --port 1933
{
"url": "http://localhost:1933",
"api_key": null,
"output": "table"
}
ovcli.confexamples/multi_tenant/