2241 01 Overview 78b08e74

API 概览

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

连接 OpenViking

OpenViking 支持三种连接模式：

嵌入式模式

import openviking as ov

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

HTTP 模式

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

直接 HTTP（curl）

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

CLI 模式

CLI 连接到 OpenViking 服务端，将所有操作暴露为 Shell 命令。

配置

创建 ~/.openviking/ovcli.conf（或设置 OPENVIKING_CLI_CONFIG_FILE 环境变量）：

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

基本用法

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

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

示例：

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

客户端生命周期

client = ov.OpenViking(path="./data")  # or url="http://..."
client.initialize()  # Required before any operations

# ... use client ...

client.close()  # Release resources

认证

详见 认证指南。

• 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