name size mode isDir uri

API 概览

本页介绍如何连接 OpenViking 以及所有 API 端点共享的约定。

连接 OpenViking

OpenViking 支持三种连接模式：

嵌入式模式

import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

嵌入式模式通过 ov.conf 配置 embedding、vlm、storage 等模块。默认路径 ~/.openviking/ov.conf，也可通过环境变量指定：

export OPENVIKING_CONFIG_FILE=/path/to/ov.conf

最小配置示例：

{
  "embedding": {
    "dense": {
      "api_base": "<api-endpoint>",
      "api_key": "<your-api-key>",
      "provider": "<volcengine|openai>",
      "dimension": 1024,
      "model": "<model-name>"
    }
  },
  "vlm": {
    "api_base": "<api-endpoint>",
    "api_key": "<your-api-key>",
    "provider": "<volcengine|openai>",
    "model": "<model-name>"
  }
}

完整配置选项和各服务商示例见 配置指南。

HTTP 模式

client = ov.SyncHTTPClient(
    url="http://localhost:1933",
    api_key="your-key",
)
client.initialize()

未显式传入 url 时，HTTP 客户端会自动从 ovcli.conf 读取连接信息。ovcli.conf 是 HTTP 客户端和 CLI 共享的配置文件，默认路径 ~/.openviking/ovcli.conf，也可通过环境变量指定：

export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf

{
  "url": "http://localhost:1933",
  "api_key": "your-key"
}

详见 配置指南。

直接 HTTP（curl）

curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
  -H "X-API-Key: your-key"

CLI 模式

CLI 连接到 OpenViking 服务端，将所有操作暴露为 Shell 命令。CLI 同样从 ovcli.conf 读取连接信息（与 HTTP 客户端共享）。

基本用法

openviking [全局选项] <command> [参数] [命令选项]

全局选项（必须放在命令名之前）

示例：

openviking --json ls viking://resources/
openviking -o json ls viking://resources/

生命周期

嵌入式模式

import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

# ... 使用 client ...

client.close()

HTTP 模式

import openviking as ov

client = ov.SyncHTTPClient(url="http://localhost:1933")
client.initialize()

# ... 使用 client ...

client.close()

认证

详见 认证指南。

• X-API-Key 请求头：X-API-Key: your-key
• Bearer 请求头：Authorization: Bearer your-key
• 如果服务端未配置 API Key，则跳过认证。
• /health 端点始终不需要认证。

响应格式

所有 HTTP API 响应遵循统一格式：

成功

{
  "status": "ok",
  "result": { ... },
  "time": 0.123
}

错误

{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found: viking://resources/nonexistent/"
  },
  "time": 0.01
}

CLI 输出格式

Table 模式（默认）

列表数据渲染为表格，非列表数据 fallback 到格式化 JSON：

openviking ls viking://resources/
# name          size  mode  isDir  uri
# .abstract.md  100   420   False  viking://resources/.abstract.md

JSON 模式（--output json）

所有命令输出格式化 JSON，与 API 响应的 result 结构一致：

openviking -o json ls viking://resources/
# [{ "name": "...", "size": 100, ... }, ...]

可在 ovcli.conf 中设置默认输出格式：

{
  "url": "http://localhost:1933",
  "output": "json"
}

脚本模式（--json）

紧凑 JSON + 状态包装，适用于脚本。覆盖 --output：

成功

{"ok": true, "result": ...}

错误

{"ok": false, "error": {"code": "NOT_FOUND", "message": "Resource not found", "details": {}}}

特殊情况

• 字符串结果（read、abstract、overview）：直接打印原文
• None 结果（mkdir、rm、mv）：无输出

退出码

错误码

API 端点

系统

资源

文件系统

内容

搜索

关联

会话

Observer

相关文档

• 资源管理 - 资源管理 API
• 检索 - 搜索 API
• 文件系统 - 文件系统操作
• 会话管理 - 会话管理
• 技能 - 技能管理
• 系统 - 系统和监控 API