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：

bash

python -m pip install --upgrade openviking-sdk

python

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 发布。

bash

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 类型声明。

bash

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，也可通过环境变量指定：

bash

export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf

使用 user/admin key 的配置文件示例：

json

{
  "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：

bash

python -m pip install --upgrade openviking-sdk

python

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"）。Rust ov CLI 不读取这个字段；使用 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）调用示例如下

bash

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 客户端共享）。

基本用法：

bash

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

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

选项	说明
`--output`, `-o`	输出格式：`table`（默认）、`json`
`--version`	显示 CLI 版本

示例：

bash

ov -o json ls viking://resources/

生命周期

Client-Server 模式

python

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 使用各接口说明的格式：

成功响应

json

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

顶层 status 表示本次 HTTP API 请求是否成功。某些成功响应会在 result 中返回业务状态，例如 "status": "success"、"status": "accepted" 或任务状态。这些字段不是 API 传输层错误。

错误响应

json

{
  "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：

bash

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} 包装：

bash

ov -o json ls viking://resources/
# {"ok":true,"result":[{"name":"...","size":100,...},...]}

使用 --compact=false 返回不带包装的格式化 JSON：

bash

ov -o json --compact=false ls viking://resources/

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

json

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

紧凑模式（`--compact`, `-c`，默认开启）

当 --output=json 时：紧凑 JSON 格式 + {ok, result} 包装，适用于脚本
当 --output=table 时：对表格输出采取精简表示（如去除空列等）

JSON 输出 - 成功：

json

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

JSON 输出 - 错误：

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 结果分布

检索

方法	路径	说明
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`	迁移旧版身份数据
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`	将用户提升为 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

SDK、HTTP 与 CLI 约定 ​

连接模式 ​

Client-Server 模式 ​

Python SDK 客户端 ​

Go SDK 客户端 ​

JavaScript/TypeScript SDK 客户端 ​

完全不依赖配置文件使用 Python SDK 客户端 ​

HTTP 调用示例 ​

CLI 模式 ​

生命周期 ​

Client-Server 模式 ​

认证 ​

响应格式 ​

成功响应 ​

错误响应 ​

CLI 输出格式 ​

Table 模式（默认） ​

JSON 模式（--output json） ​

紧凑模式（--compact, -c，默认开启） ​

特殊情况 ​

退出码 ​

错误码 ​

API 端点总览 ​

系统状态 ​

资源与文件系统 ​

ACL ​

内容 ​

技能 ​

会话、记忆与 Agent 进化 ​

检索 ​

Watch、快照与 OVPack ​

后台任务、运行观测与 Metrics ​

管理员与隐私配置 ​

OpenViking 网关管理 ​

OpenViking Assets、WebDAV、Agent Runtime API 与 VikingBot API ​

按任务查找接口 ​

SDK、HTTP 与 CLI 约定

连接模式

Client-Server 模式

Python SDK 客户端

Go SDK 客户端

JavaScript/TypeScript SDK 客户端

完全不依赖配置文件使用 Python SDK 客户端

HTTP 调用示例

CLI 模式

生命周期

Client-Server 模式

认证

响应格式

成功响应

错误响应

CLI 输出格式

Table 模式（默认）

JSON 模式（`--output json`）

紧凑模式（`--compact`, `-c`，默认开启）

特殊情况

退出码

错误码

API 端点总览

系统状态

资源与文件系统

ACL

内容

技能

会话、记忆与 Agent 进化

检索

Watch、快照与 OVPack

后台任务、运行观测与 Metrics

管理员与隐私配置

OpenViking 网关管理

OpenViking Assets、WebDAV、Agent Runtime API 与 VikingBot API

按任务查找接口