Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
SDK、HTTP 与 CLI 约定
本页介绍如何连接 OpenViking 以及所有 API 端点共享的约定。
连接模式
OpenViking 客户端通过 HTTP 连接 OpenViking Server。
| 模式 | 适用场景 | 说明 |
|---|---|---|
| HTTP | 连接 OpenViking 服务器 | 通过 HTTP API 连接远程服务器 |
| CLI | Shell 脚本、Agent 工具使用 | 通过 CLI 命令连接服务器 |
Client-Server 模式
Client-Server 模式通过 HTTP API 连接 OpenViking 服务器,支持多租户、远程访问等特性。OpenViking 的服务器启动方式请参见相关部署文档。
Python SDK 客户端
先在运行代码的 Python 环境中安装独立 SDK:
python -m pip install --upgrade openviking-sdk
from openviking_sdk import SyncHTTPClient
client = SyncHTTPClient(
url="http://localhost:1933",
api_key="your-key",
timeout=120.0,
)
client.initialize()
Go SDK 客户端
Go SDK 是 Client-Server 模式下的 HTTP-only 客户端,作为主仓库的 sdk/go 独立 Go module 发布。
go get github.com/volcengine/OpenViking/sdk/go
client, err := openviking.NewClient(openviking.Config{
BaseURL: "http://localhost:1933",
APIKey: "your-key",
})
if err != nil {
return err
}
defer client.CloseIdleConnections()
Go SDK 发送的身份请求头与 Python HTTP client 一致:
| Config 字段 | HTTP Header |
|---|---|
APIKey |
X-API-Key |
Account |
X-OpenViking-Account |
User |
X-OpenViking-User |
ActorPeerID |
X-OpenViking-Actor-Peer |
普通 api_key 部署下只需要设置 APIKey,服务端会从 API key 推导租户身份。只有在 trusted 部署或网关显式透传租户身份时,才需要设置 Account 和 User。
Go SDK 不保留旧 agent_id 兼容路径。更多示例见 sdk/go/README_CN.md。
JavaScript/TypeScript SDK 客户端
JavaScript/TypeScript SDK 是面向 Node.js 18+ 的 HTTP-only 客户端,同时发布 ESM、CommonJS 和 TypeScript 类型声明。
npm install @openviking/sdk
import { OpenVikingClient } from "@openviking/sdk";
const client = new OpenVikingClient({
baseUrl: "http://localhost:1933",
apiKey: "your-key",
});
const results = await client.search("部署文档", {
targetUri: "viking://resources",
});
它与 Python、Go HTTP Client 使用相同的身份请求头和响应信封。更多示例见
sdk/typescript/README_CN.md。
Python HTTP 客户端从 ovcli.conf 读取连接信息,显式传入的构造参数覆盖对应配置。ovcli.conf 是 HTTP 客户端和 CLI 共享的配置文件,默认路径 ~/.openviking/ovcli.conf,也可通过环境变量指定:
export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf
使用 user/admin key 的配置文件示例:
{
"url": "http://localhost:1933",
"api_key": "your-user-or-admin-key"
}
配置字段说明:
| 字段 | 说明 | 默认值 |
|---|---|---|
url |
服务端地址 | (必填) |
api_key |
API Key | null(无认证) |
account |
账户请求头;trusted 和 dev 模式使用,api_key 模式忽略 | null |
user |
用户请求头;trusted 和 dev 模式使用,api_key 模式忽略 | null |
timeout |
HTTP 请求超时时间(秒) | 60.0 |
output |
默认输出格式:"table" 或 "json" |
"table" |
详细内容请参见 配置指南。
完全不依赖配置文件使用 Python SDK 客户端
SyncHTTPClient 和 AsyncHTTPClient 可以在没有 ovcli.conf 文件时使用。先在运行代码的 Python 环境中安装独立 SDK:
python -m pip install --upgrade openviking-sdk
import openviking_sdk as ov
client = ov.SyncHTTPClient(
url="http://localhost:1933",
api_key="your-key",
timeout=30.0,
extra_headers={},
)
client.initialize()
即使显式传入参数,SDK 仍会读取已有的 ovcli.conf。显式值覆盖对应配置,其他设置可能来自环境变量或配置文件,因此无效配置仍会导致客户端构造失败。默认超时为 60 秒。文件位置见客户端配置。
HTTP 调用示例
- CLI、
SyncHTTPClient、AsyncHTTPClient遇到本地文件或目录时,会先自动上传,再调用服务端 API。 - Python HTTP client 可以通过
ovcli.conf启用 shared 临时上传(设置upload.mode = "shared")。RustovCLI 不读取这个字段;使用ov时请设置OPENVIKING_UPLOAD_MODE=shared。 - 裸 HTTP 调用没有这层封装。使用
curl或其他 HTTP 客户端时,需要先调用POST /api/v1/resources/temp_upload,再把返回的temp_file_id传给目标 API。 temp_upload默认使用upload_mode=local。只有在你显式需要分布式共享临时上传时,才应传upload_mode=shared。- 裸 HTTP 如果导入本地目录,需要先自行打成
.zip再通过上述方法上传;服务端不接受直接传宿主机目录路径。 POST /api/v1/resources可以直接接收远端 URL,但不接受./doc.md、/tmp/doc.md这类宿主机本地路径。
直接 HTTP(curl)调用示例如下
curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
-H "X-API-Key: your-key"
CLI 模式
OpenViking CLI 的命令是 ov(通过 npm install -g @openviking/cli 安装),连接到 OpenViking 服务端,提供常用操作的 Shell 命令。CLI 同样从 ovcli.conf 读取连接信息(与 HTTP 客户端共享)。
基本用法:
ov [全局选项] <command> [参数] [命令选项]
全局选项(必须放在命令名之前):
| 选项 | 说明 |
|---|---|
--output, -o |
输出格式:table(默认)、json |
--version |
显示 CLI 版本 |
示例:
ov -o json ls viking://resources/
生命周期
Client-Server 模式
import openviking_sdk as ov
client = ov.SyncHTTPClient(url="http://localhost:1933")
client.initialize()
# ... 使用 client ...
client.close()
CLI 则直接通过命令行调用,需要先配置 ovcli.conf 文件,无需额外初始化客户端:
ov -o json ls viking://resources/
认证
详见 认证指南。
- Authorization Bearer 请求头:
Authorization: Bearer your-key(建议的方式) - X-API-Key 请求头:
X-API-Key: your-key - 只有 dev 模式跳过认证;未设置
auth_mode且未设置server.root_api_key时自动选择 dev 模式。其他模式(api_key、trusted、OIDC、LDAP)按各自配置解析身份。 /health和/ready端点始终不需要认证。
响应格式
常规 JSON API 响应遵循以下格式;文件下载、SSE、Metrics 和 WebDAV 使用各接口说明的格式:
成功响应
{
"status": "ok",
"result": { ... }
}
顶层 status 表示本次 HTTP API 请求是否成功。某些成功响应会在 result 中返回业务状态,例如 "status": "success"、"status": "accepted" 或任务状态。这些字段不是 API 传输层错误。
错误响应
{
"status": "error",
"error": {
"code": "NOT_FOUND",
"message": "Resource not found: viking://resources/nonexistent/"
}
}
HTTP 错误始终使用顶层错误 envelope。资源解析、同步 reindex 等同步处理失败会返回非 2xx 响应,顶层为 status="error",并包含 error 对象。客户端不应通过 result.status="error" 判断请求失败。
请求校验失败,包括 JSON 格式错误、缺少必填字段和参数值非法,统一返回 HTTP 400,并使用 error.code="INVALID_ARGUMENT"。响应不会使用 FastAPI 原生的 {"detail": ...} 错误格式;当存在字段级校验信息时,会通过 error.details.validation_errors 返回。
Python HTTP SDK(SyncHTTPClient 和 AsyncHTTPClient)会把该 envelope 映射为对应的 OpenVikingError 子类。例如 PROCESSING_ERROR 会抛出 ProcessingError。
CLI 输出格式
Table 模式(默认)
列表数据渲染为表格,非列表数据 fallback 到格式化 JSON:
ov ls viking://resources/
# name size mode isDir uri
# .abstract.md 100 420 false viking://resources/.abstract.md
JSON 模式(--output json)
-o json 默认使用紧凑输出,并带有 {ok, result} 包装:
ov -o json ls viking://resources/
# {"ok":true,"result":[{"name":"...","size":100,...},...]}
使用 --compact=false 返回不带包装的格式化 JSON:
ov -o json --compact=false ls viking://resources/
可在 ovcli.conf 中设置默认输出格式:
{
"url": "http://localhost:1933",
"output": "json"
}
紧凑模式(--compact, -c,默认开启)
- 当
--output=json时:紧凑 JSON 格式 +{ok, result}包装,适用于脚本 - 当
--output=table时:对表格输出采取精简表示(如去除空列等)
JSON 输出 - 成功:
{"ok": true, "result": ...}
JSON 输出 - 错误:
{"ok": false, "error": {"code": "NOT_FOUND", "message": "...", "details": {}}}
特殊情况
- Table 模式下,
read、abstract、overview直接打印文本,mkdir、rm、mv打印操作确认信息。 - JSON 模式下,这些命令按上文的 JSON 格式输出。
退出码
注:退出码是 CLI(命令行工具)的返回码,不是 HTTP API 的状态码。
| 退出码 | 说明 | 触发场景 |
|---|---|---|
| 0 | 成功 | 命令执行成功 |
| 1 | 运行错误 | 命令执行失败,包括 API 调用错误或连接错误 |
| 2 | 参数或配置错误 | 命令行参数无效、配置加载失败、缺少必要凭据,或将 --sudo 用于不支持的命令 |
当前 Rust CLI 的连接失败返回退出码 1,不使用单独的连接错误退出码 3。
错误码
| 错误码 | HTTP 状态码 | 说明 |
|---|---|---|
OK |
200 | 成功 |
INVALID_ARGUMENT |
400 | 无效参数 |
INVALID_URI |
400 | 无效的 Viking URI 格式 |
NOT_FOUND |
404 | 资源未找到 |
ALREADY_EXISTS |
409 | 资源已存在 |
UNAUTHENTICATED |
401 | 缺少或无效的 API Key |
PERMISSION_DENIED |
403 | 权限不足 |
RESOURCE_EXHAUSTED |
429 | 超出速率限制 |
FAILED_PRECONDITION |
412 | 前置条件不满足 |
CONFLICT |
409 | 操作与正在进行的任务或已有状态冲突 |
DEADLINE_EXCEEDED |
504 | 操作超时 |
UNAVAILABLE |
503 | 服务不可用 |
PROCESSING_ERROR |
500 | 资源或语义处理失败 |
INTERNAL |
500 | 内部服务器错误 |
UNIMPLEMENTED |
501 | 功能未实现 |
EMBEDDING_FAILED |
500 | Embedding 生成失败 |
VLM_FAILED |
500 | VLM 调用失败 |
SESSION_EXPIRED |
410 | 会话已过期 |
NOT_INITIALIZED |
- | 服务或组件未初始化(需要先调用 initialize()) |
文件/目录类型不符合操作要求、复制或删除目录时缺少 recursive=true,以及 HTTP 来源域名明确不存在,均返回 INVALID_ARGUMENT(400)。正常路径锁竞争(包括加密写入)返回 CONFLICT(409);锁令牌损坏、锁 I/O 故障和落盘数据解密失败返回 INTERNAL(500)。HTTP 来源站不可用或发生临时网络故障时返回 UNAVAILABLE(503),抓取超时返回 DEADLINE_EXCEEDED(504)。
API 端点总览
以下目录以服务端实际挂载路由为准。每组标题会跳转到详细文档;详细页只为真实存在的 HTTP、Python SDK、TypeScript SDK、Go SDK 或 CLI 能力显示对应 Tab,不会用等价的裸 HTTP 调用冒充 SDK。
系统状态
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /health |
基础健康检查(无需认证) |
| GET | /ready |
AGFS、VectorDB、API Key 管理器和 Embedding 就绪检查(无需认证) |
| GET | /api/v1/system/status |
系统状态 |
| POST | /api/v1/system/wait |
等待后台处理完成 |
| POST | /api/v1/system/consistency |
文件系统与向量索引一致性检查 |
资源与文件系统
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/resources/temp_upload |
上传后续导入所需的临时文件 |
| POST | /api/v1/resources |
从 URL 或临时文件添加资源 |
| GET | /api/v1/fs/ls |
列出目录 |
| GET | /api/v1/fs/tree |
获取目录树 |
| GET | /api/v1/fs/stat |
获取资源状态 |
| GET | /api/v1/fs/attrs |
获取逻辑扩展属性 |
| POST | /api/v1/fs/attrs/set_tags |
设置检索标签(兼容别名) |
| POST | /api/v1/fs/mkdir |
创建目录 |
| DELETE | /api/v1/fs |
删除资源 |
| POST | /api/v1/fs/cp |
复制文件或目录及其向量记录 |
| POST | /api/v1/fs/mv |
移动或重命名资源 |
ACL
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/acl |
获取资源的直接、继承和有效 ACL |
| PUT | /api/v1/acl |
替换资源的直接 ACL |
| DELETE | /api/v1/acl |
清空资源的直接 ACL |
| POST | /api/v1/acl/grant |
设置一个 principal 的直接权限级别 |
| POST | /api/v1/acl/revoke |
删除一个 principal 的直接授权 |
内容
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/content/read |
读取完整内容(L2) |
| GET | /api/v1/content/abstract |
读取摘要(L0) |
| GET | /api/v1/content/overview |
读取概览(L1) |
| GET | /api/v1/content/download |
下载原始文件字节 |
| POST | /api/v1/content/write |
写入内容并刷新语义索引 |
| POST | /api/v1/content/batch-write |
写入多个文件并刷新索引 |
| POST | /api/v1/content/set_tags |
设置检索标签 |
| POST | /api/v1/content/reindex |
重建语义或向量索引 |
技能
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/skills |
列出技能 |
| POST | /api/v1/skills |
添加技能 |
| POST | /api/v1/skills/find |
搜索技能 |
| POST | /api/v1/skills/validate |
校验技能数据 |
| GET | /api/v1/skills/{skill_name} |
获取技能 |
| PUT | /api/v1/skills/{skill_name} |
更新技能 |
| DELETE | /api/v1/skills/{skill_name} |
删除技能 |
会话、记忆与 Agent 进化
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/sessions |
创建会话 |
| GET | /api/v1/sessions |
列出会话 |
| GET | /api/v1/sessions/{session_id} |
获取会话 |
| PATCH | /api/v1/sessions/{session_id}/config |
更新可变的会话配置 |
| GET | /api/v1/sessions/{session_id}/tool-results |
列出工具结果 |
| GET | /api/v1/sessions/{session_id}/tool-results/{tool_result_id} |
读取工具结果 |
| GET | /api/v1/sessions/{session_id}/tool-results/{tool_result_id}/search |
在工具结果内搜索 |
| GET | /api/v1/sessions/{session_id}/context |
获取组装后的上下文 |
| GET | /api/v1/sessions/{session_id}/archives/{archive_id} |
获取会话归档 |
| DELETE | /api/v1/sessions/{session_id} |
删除会话 |
| POST | /api/v1/sessions/{session_id}/commit |
归档会话并提取记忆 |
| POST | /api/v1/sessions/{session_id}/messages |
添加单条消息 |
| POST | /api/v1/sessions/{session_id}/messages/batch |
批量添加消息 |
| POST | /api/v1/search/recall |
已弃用:search 接口 mode="context" 之上的轻量预设 |
| GET | /api/v1/agent-evolution/experiences/trajectories |
分页查询应用过指定 Experience 的 Trajectory |
| GET | /api/v1/agent-evolution/experiences/outcomes |
聚合应用过指定 Experience 的 Trajectory 结果分布 |
规则(Beta)
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/rules/compile |
提交规则编译后台任务 |
| POST | /api/v1/rules/search |
按任务上下文召回适用的 active 规则 |
检索
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/search/find |
语义搜索 |
| POST | /api/v1/search/search |
上下文感知搜索;mode="context" 返回可注入的组装上下文 |
| POST | /api/v1/search/grep |
内容模式搜索 |
| POST | /api/v1/search/glob |
文件模式匹配 |
Watch、快照与 OVPack
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/watches |
列出 watch,或按 to_uri 查询 |
| GET | /api/v1/watches/{task_id} |
按任务 ID 获取 watch |
| PATCH | /api/v1/watches |
按 to_uri 更新 watch |
| PATCH | /api/v1/watches/{task_id} |
按任务 ID 更新 watch |
| DELETE | /api/v1/watches |
按 to_uri 删除 watch |
| DELETE | /api/v1/watches/{task_id} |
按任务 ID 删除 watch |
| POST | /api/v1/watches/trigger |
按 to_uri 触发 watch |
| POST | /api/v1/watches/{task_id}/trigger |
按任务 ID 触发 watch |
| POST | /api/v1/snapshot/commit |
创建快照 |
| GET | /api/v1/snapshot/log |
查看快照历史 |
| GET | /api/v1/snapshot/versions |
列出 Compile 产出文件的版本 |
| POST | /api/v1/snapshot/restore |
恢复历史快照 |
| GET | /api/v1/snapshot/show |
查看快照或其中的文件 |
| GET | /api/v1/snapshot/diff |
对比快照 |
| GET | /api/v1/snapshot/diff-paths |
分页列出变化的源文件 |
| GET | /api/v1/snapshot/ignore |
读取快照忽略规则 |
| PUT | /api/v1/snapshot/ignore |
替换快照忽略规则 |
| DELETE | /api/v1/snapshot/ignore |
清空快照忽略规则 |
| POST | /api/v1/pack/export |
导出 .ovpack |
| POST | /api/v1/pack/import |
导入 .ovpack |
| POST | /api/v1/pack/backup |
备份公开作用域 |
| POST | /api/v1/pack/restore |
恢复备份包 |
后台任务、运行观测与 Metrics
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/compile |
创建由 OV 托管的 Compile 任务 |
| GET | /api/v1/compile/capabilities |
检查 Compile 可用性 |
| GET | /api/v1/compile/submissions/{key} |
按提交键查询任务 |
| GET | /api/v1/tasks/{task_id} |
获取后台任务 |
| POST | /api/v1/tasks/{task_id}/cancel |
取消后台任务 |
| GET | /api/v1/tasks |
列出后台任务 |
| GET | /api/v1/observer/queue |
队列状态 |
| GET | /api/v1/observer/vikingdb |
VikingDB 状态 |
| GET | /api/v1/observer/models |
模型状态 |
| GET | /api/v1/observer/lock |
锁状态 |
| GET | /api/v1/observer/retrieval |
检索状态 |
| GET | /api/v1/observer/filesystem |
文件系统状态 |
| GET | /api/v1/observer/system |
聚合运行状态 |
| GET | /metrics |
Prometheus 指标 |
管理员与隐私配置
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/admin/configuration |
获取 Cluster 层显式运行时配置 |
| PATCH | /api/v1/admin/configuration |
更新 Cluster 层运行时配置 |
| POST | /api/v1/admin/configuration/test-model |
测试草稿模型或 Embedding 连接,不保存配置 |
| POST | /api/v1/admin/restart |
请求支持该能力的服务进程优雅重启(仅 ROOT) |
| GET | /api/v1/admin/accounts/{account_id}/configuration |
获取 Account 层显式运行时配置 |
| PATCH | /api/v1/admin/accounts/{account_id}/configuration |
更新 Account 层运行时配置 |
| GET | /api/v1/admin/agent-evolution |
获取 Agent 进化状态(deprecated) |
| PUT | /api/v1/admin/agent-evolution |
更新 Agent 进化状态(deprecated) |
| GET | /api/v1/admin/accounts/{account_id}/settings |
获取存量账号配置(deprecated) |
| PATCH | /api/v1/admin/accounts/{account_id}/settings |
更新存量账号配置(deprecated) |
| GET | /api/v1/admin/accounts/{account_id}/memory-templates |
列出可编辑记忆模板、默认值及生效值 |
| GET | /api/v1/admin/accounts/{account_id}/memory-templates/{memory_type} |
查询单个记忆模板 |
| PUT | /api/v1/admin/accounts/{account_id}/memory-templates/{memory_type} |
补齐并发布单个记忆模板 |
| DELETE | /api/v1/admin/accounts/{account_id}/memory-templates/{memory_type} |
删除记忆模板覆盖,恢复部署默认值 |
| POST | /api/v1/admin/accounts |
创建账号及首个管理员 |
| GET | /api/v1/admin/accounts |
列出账号 |
| POST | /api/v1/admin/migrate |
预留迁移入口;仅 ROOT 可调用,当前返回 400 INVALID_ARGUMENT |
| GET | /api/v1/admin/accounts/{account_id} |
获取单个账号的无凭据元数据 |
| DELETE | /api/v1/admin/accounts/{account_id} |
删除账号 |
| POST | /api/v1/admin/accounts/{account_id}/users |
注册用户 |
| GET | /api/v1/admin/accounts/{account_id}/users |
列出用户 |
| GET | /api/v1/admin/accounts/{account_id}/users/{user_id} |
获取单个用户的无凭据成员信息(user_id、role) |
| GET | /api/v1/admin/accounts/{account_id}/users/{user_id}/settings |
获取用户记忆策略 |
| PATCH | /api/v1/admin/accounts/{account_id}/users/{user_id}/settings |
更新用户记忆策略 |
| DELETE | /api/v1/admin/accounts/{account_id}/users/{user_id} |
移除用户 |
| PUT | /api/v1/admin/accounts/{account_id}/users/{user_id}/role |
在 USER 与 ADMIN 之间变更用户角色 |
| POST | /api/v1/admin/accounts/{account_id}/users/{user_id}/key |
重新生成用户 Key |
| POST | /api/v1/admin/accounts/{account_id}/groups |
创建用户组 |
| GET | /api/v1/admin/accounts/{account_id}/groups |
列出用户组 |
| DELETE | /api/v1/admin/accounts/{account_id}/groups/{group_id} |
删除用户组 |
| GET | /api/v1/admin/accounts/{account_id}/groups/{group_id}/members |
列出用户组成员 |
| PUT | /api/v1/admin/accounts/{account_id}/groups/{group_id}/members/{user_id} |
添加用户组成员 |
| DELETE | /api/v1/admin/accounts/{account_id}/groups/{group_id}/members/{user_id} |
移除用户组成员 |
| GET | /api/v1/privacy-configs |
列出隐私配置分类 |
| GET | /api/v1/privacy-configs/tree |
树形列出当前目标和字段元数据,不返回值 |
| POST | /api/v1/privacy-configs/scan |
扫描或修复正文中的登记值 |
| GET | /api/v1/privacy-configs/{category} |
列出分类目标 |
| GET | /api/v1/privacy-configs/{category}/{target_key} |
获取生效配置 |
| GET | /api/v1/privacy-configs/{category}/{target_key}/fields |
列出不含明文值的安全字段元数据 |
| GET | /api/v1/privacy-configs/{category}/{target_key}/field |
获取单字段引用或显式读取值 |
| POST | /api/v1/privacy-configs/resolve |
按字段 reference/URI 显式读取值 |
| GET | /api/v1/privacy-configs/{category}/{target_key}/versions |
列出配置版本 |
| GET | /api/v1/privacy-configs/{category}/{target_key}/versions/{version} |
获取指定版本 |
| POST | /api/v1/privacy-configs/{category}/{target_key} |
写入并激活新版本 |
| PATCH | /api/v1/privacy-configs/{category}/{target_key} |
原子合并字段;不存在时创建 |
| POST | /api/v1/privacy-configs/{category}/{target_key}/activate |
激活指定版本 |
| DELETE | /api/v1/privacy-configs/{category}/{target_key} |
删除目标及全部版本 |
| DELETE | /api/v1/privacy-configs/{category}/{target_key}/field |
删除当前字段 |
| DELETE | /api/v1/privacy-configs/selector |
按 URI/reference 删除目标或字段 |
OpenViking 网关管理
网关在 Server 内运行时,从 Server 端口访问;独立运行时,从网关自己的端口访问。OpenViking API 密钥决定调用方能访问哪个账号;部署者设置了网关管理密钥时,修改上游和上下文配置还需要这把密钥。每个用户都能给自己签发网关密钥。权限矩阵和错误原因见网关管理 API。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /gateway/admin/access |
读取调用方的权限和部署告警 |
| GET | /gateway/admin/guides |
读取客户端使用的网关地址 |
| GET | /gateway/admin/tools |
列出调用方可用的 OpenViking 工具 |
| GET | /gateway/admin/upstreams/{identifier} |
读取单个上游 |
| GET | /gateway/admin/policies/{identifier} |
读取单个上下文配置 |
| GET | /gateway/admin/keys/{identifier} |
读取单个网关密钥(不含密钥本身) |
| GET | /gateway/admin/overview |
读取调用方可见范围内的用量概览 |
| GET | /gateway/admin/logs |
读取调用方可见的请求日志 |
| GET | /gateway/admin/upstreams |
列出本账号的上游 |
| PUT / DELETE | /gateway/admin/upstreams/{identifier} |
创建/替换或删除上游 |
| POST | /gateway/admin/upstreams/{identifier}/test |
测试上游连接或模型 |
| POST | /gateway/admin/upstreams/import-vlm |
把 Server 的 VLM 配置导入为上游(仅嵌入部署) |
| GET | /gateway/admin/policies |
列出本账号的上下文配置 |
| PUT / DELETE | /gateway/admin/policies/{identifier} |
创建/替换或删除上下文配置 |
| GET / POST | /gateway/admin/keys |
列出调用方可见的网关密钥,或签发新密钥 |
| DELETE | /gateway/admin/keys/{identifier} |
吊销网关密钥 |
| POST | /gateway/admin/keys/{identifier}/capture/reset |
让一段对话重新开始保存 |
| DELETE | /gateway/admin/users/{user_id}/data |
admin 或 root:删除某个用户的网关数据 |
| DELETE | /gateway/admin/account/data |
root:删除整个账号的网关数据 |
OpenViking Assets、WebDAV、Agent Runtime API 与 VikingBot API
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/openviking-assets/resolve |
解析并校验 Catalog 与 Manifest,返回标准化资产计划 |
| POST | /api/v1/openviking-assets/preflight |
只读校验 Git 仓库和 ref 的访问权限 |
| OPTIONS | /webdav/resources、/webdav/resources/{resource_path} |
查询 WebDAV 能力 |
| PROPFIND | /webdav/resources、/webdav/resources/{resource_path} |
查询资源属性 |
| GET / HEAD | /webdav/resources、/webdav/resources/{resource_path} |
读取文件或目录 |
| PUT | /webdav/resources、/webdav/resources/{resource_path} |
写入 UTF-8 文本文件 |
| DELETE | /webdav/resources、/webdav/resources/{resource_path} |
删除文件或目录 |
| MKCOL | /webdav/resources、/webdav/resources/{resource_path} |
创建目录 |
| MOVE | /webdav/resources、/webdav/resources/{resource_path} |
移动或重命名资源 |
| POST | /api/v1/compile |
创建异步 Compile 任务 |
| GET | /api/v1/compile/config |
读取目标配置 |
| POST | /api/v1/compile/config/update |
更新目标配置 |
| GET | /api/v1/compile/configs |
列出可见目标 |
| GET | /api/v1/compile/operations |
列出目标操作记录 |
| GET | /api/v1/compile/operations/{operation_id}/outputs |
列出操作产出及版本引用 |
| POST | /api/v1/compile/embeddings |
生成 Compile 临时路由文本的向量 |
| GET | /api/v1/compile/capabilities |
检查 Compile 可用性 |
| GET | /api/v1/compile/submissions/{key} |
按提交键查询任务 |
| GET | /bot/v1/health |
VikingBot 健康检查 |
| POST | /bot/v1/chat |
VikingBot 非流式对话 |
| POST | /bot/v1/chat/stream |
VikingBot 流式对话 |
| POST | /bot/v1/feedback |
提交 VikingBot 回答反馈 |
| POST | /bot/v1/sessions/{session_id}/interrupt |
中断活跃或排队中的 VikingBot 会话 |
| POST | /bot/v1/sessions/{session_id}/steer |
向活跃流式会话发送追加输入 |
| POST | /bot/v1/compile |
已停用;返回新接口迁移提示 |
| GET | /bot/v1/compile/{task_id} |
已停用;返回 Task 接口迁移提示 |
| POST | /bot/v1/compile/{task_id}/cancel |
已停用;返回 Task 取消接口迁移提示 |
按任务查找接口
按操作类型选择对应文档:
| 分组 | 适合查找的内容 |
|---|---|
| 核心数据 | 资源、内容、文件系统、技能、会话、记忆 |
| 检索 | 语义检索、代码检索 |
| 数据生命周期 | Watch、快照、OVPack |
| 运维与观测 | 系统、任务、Observer、Metrics |
| 身份与治理 | 管理员、ACL、隐私配置 |
| 协议与扩展 | OpenViking Assets、WebDAV、Agent Runtime API、VikingBot API |