OpenViking CLI 配置指南

本文介绍如何安装 OpenViking CLI、完成配置，并验证它可以连接到 OpenViking。

ov 是客户端 CLI。它连接到已经存在的 OpenViking 服务端，或连接到 OpenViking Service（火山引擎云）。它不是服务端安装命令。如果你还没有安装或启动自定义 OpenViking 服务端，请先阅读快速开始或服务端模式。

你可以用两种方式阅读本文：

如果你自己手动配置 ov，请阅读手动配置。
如果你让 Agent 帮你配置，请把本文发给 Agent，并让它阅读 Agent 辅助配置。

CLI 会持续演进。请把 ov --help 和 ov <command> --help 作为当前安装版本的命令准确信息来源。

本文配置什么

CLI 使用 ~/.openviking/ovcli.conf 作为 active 客户端连接配置。

创建命名配置时，ov 会把配置保存为 ~/.openviking/ovcli.conf.<name>。切换配置时，ov 会把选中的已保存配置复制到 ~/.openviking/ovcli.conf。

ov config 是面向人的交互式配置管理器，可以新增、编辑、删除、校验和切换配置。

ov config add、ov config edit、ov config list、ov config switch <name> 和 ov config delete 是面向脚本和 Agent 的确定性命令。

选择连接目标

运行配置命令前，先选择要连接的 OpenViking 目标。

除非用户已经明确说明，Agent 应先询问用户要连接哪种目标。已有配置、active 配置、本地文件、默认端口和正在运行的服务可以帮助 Agent 追问细节，但不代表用户同意 Agent 选择目标、切换或替换配置、探测本地服务、启动服务端，或写入数据。

OpenViking Service（火山引擎云）

如果你希望使用火山引擎云上的 OpenViking 托管服务，选择此项。

ov 使用的服务端端点：https://api.vikingdb.cn-beijing.volces.com/openviking
管理 API Key 的控制台页面：https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing
在控制台进入 User Management → API Key，查看并复制你的 key。
API Key 必填。
标准配置只需要 API Key。除非用户的管理员明确提供身份覆盖值，否则不要询问 --account 或 --user。

远程自定义

如果你要连接不在当前机器上的自定义 OpenViking 服务端，选择此项。

服务端 URL 由用户或服务端管理员提供。
可能需要 API Key。
只有 root key 的配置需要 --account 和 --user。

本地自定义

只有当用户要连接当前机器上的自定义 OpenViking 服务端时，才选择此项。

本地默认 URL：http://127.0.0.1:1933
本地无鉴权服务通常不需要 API Key。
除非用户选择本地自定义配置，否则 Agent 不应探测本地端口、curl 本地 health endpoint，或运行启动服务端的命令。

注意： 最近的 CLI 版本（v0.3.23+）要求在运行大多数命令前先保存一个显示语言。在交互式终端中，CLI 会在首次使用时提示你选择；在非交互式 shell（Agent 或 CI）中，任何非豁免命令都会以 2 退出，直到你运行 ov language en 或 ov language zh-CN。只有 ov language/ov lang、ov config add|edit|delete|list 和 ov config switch <name> 是豁免的，因此请在上面的 ov config validate、ov health 和 ov status 之前先运行 ov language <code>。

开始前

你需要准备：

一种安装 CLI 的方式：
- 使用 Node.js 和 npm 安装独立的 @openviking/cli 包，或
- 使用 Python 工具安装完整的 openviking 包。
一个可访问的 OpenViking 目标：
- OpenViking Service（火山引擎云），或
- 自定义 OpenViking 服务端。
如果目标需要鉴权，需要准备 API Key。

API Key 是敏感凭证。手动配置时优先通过 ov config 的交互式输入框输入。只有当你明确相信当前渠道时，才把 API Key 提供给 Agent。Agent 应通过 stdin 传入 key，不能把 key 写进 shell 命令、日志、长期记忆或原始配置输出。只有当 key 已经存在于当前 shell 环境变量中时，才使用环境变量。

安装 `ov`

先检查是否已经安装：

bash

command -v ov
ov --version

如果 ov --version 或任何其他 ov 命令提示 OpenViking 需要显示语言，请先选择语言再重试：

bash

ov language en
# 或
ov language zh-CN

安装或升级 npm 包：

bash

npm i -g @openviking/cli

npm 包是最轻量的独立 CLI 安装方式。如果你同时需要 Python SDK 或服务端包，Python 包也会提供 ov：

bash

uv tool install openviking --upgrade
# 或
pip install openviking --upgrade --force-reinstall

验证：

bash

ov --help

如果仍然找不到 ov，关闭并重新打开 shell，或检查 npm 全局 prefix：

bash

npm prefix -g

在 macOS 和 Linux 上，全局 npm binary 目录通常是 $(npm prefix -g)/bin。确认该目录已经加入 PATH。

密钥类型

OpenViking CLI 配置可以包含 user key、root key，或同时包含两者。

User key：用于普通数据命令，例如 ov add-resource、ov find 和 ov tree。服务端会从 key 推导身份，所以通常不需要传 --account 或 --user。这是大多数用户需要的方式。
Root key：用于管理操作和需要 --sudo 的命令。Root key 自身不包含租户身份。如果一个配置只有 root key，就必须同时包含 --account 和 --user；这个 root key 会同时服务于该身份下的普通命令和 --sudo 命令。
User key + root key：适合一个配置同时支持日常数据操作和偶尔的管理操作。普通命令使用 user key，--sudo 命令使用 root key，并带上配置中的 account 和 user。

手动配置

如果你正在阅读本文，并准备自己配置 ov，使用这个路径。

运行：

bash

ov config

然后选择：

Add config
OpenViking Service（火山引擎云） 或 自定义
配置名称，或留空自动生成
上面选择的目标所需的 URL 和 API Key
校验成功后保存配置

如果你维护多个 OpenViking 目标，之后可以使用：

bash

ov config switch

切换 active 配置。

配置完成后，继续阅读验证配置。

Agent 辅助配置

如果 Agent 正在替用户配置 ov，使用这个路径。Agent 应该阅读整篇文档。当确定性命令不适合用户环境时，上面的手动配置流程就是回退路径。

Agent 检查清单

除非用户已经明确说明，先询问用户要连接哪种目标：OpenViking Service（火山引擎云）、远程自定义，还是本地自定义。
不要根据已有配置、active 配置、本地文件、默认端口或正在运行的服务推断用户想要的 setup。
切换配置、替换配置、探测本地服务、启动服务端或写入数据前，都要先询问用户。
在选择命令前，运行 ov --help、ov config --help 和相关 config 子命令的帮助。
如果你具备长期记忆能力，并且用户允许，可以记录当前 ov --help 命令面的简要摘要。不要记录 API Key 或其他密钥。
当必需信息明确时，使用非交互式 ov config 命令。
Agent 配置时始终传 --name，这样重试会命中同一个 saved config。
如果 Agent 已经通过可信渠道拿到 API Key，使用 --api-key-stdin 或 --root-api-key-stdin，并且只把 key 内容写入 stdin。只有当环境变量已经存在时，才使用 --api-key-env 或 --root-api-key-env。不要要求用户额外打开一个 shell 只为了给 Agent export 一个 key。
使用 -o json，并根据 JSON 结果和进程退出码分支处理。
使用 ov config validate 校验 active 配置，然后运行 ov health 和 ov status。
如果非交互式配置因为信息缺失、鉴权不明确或终端输入更安全而失败，请引导用户使用 ov config 交互式向导。

查看当前安装的 CLI

运行：

bash

ov --help
ov config --help
ov config add --help
ov config add ov-service --help
ov config add custom --help
ov config edit --help

以当前安装版本的 CLI 帮助为准。如果本文与本地帮助不一致，请遵循本地帮助，并告诉用户差异是什么。

如果 help 命令提示 OpenViking 需要显示语言，请运行 ov language en；如果用户希望使用中文，则运行 ov language zh-CN，然后重试。ov config add、ov config list、ov config edit、ov config switch <name> 和 ov config delete 等非交互式 config 子命令可以在设置显示语言前运行。

使用稳定名称便于重试

Agent 创建配置时始终传 --name。如果省略名称，ov 会随机生成名称；重试时可能创建第二个 saved config，而不是更新预期的配置。

当传入相同 --name 且配置内容完全一致时，ov config add 可以安全重复运行。它会以 0 退出，--activate 也会再次把该 saved config 设为 active。如果同名配置已经存在但内容不同，命令会以 3 退出，并要求只有在确认替换时才使用 --force。

下面示例中的 <CONFIG-NAME> 和 <REMOTE-OPENVIKING-URL> 等占位符需要替换成用户确认过的值再运行。运行时不要保留尖括号。

读取结果

对非交互式 config 命令使用 -o json 时，成功结果会输出到 stdout：

json

{"status":"ok","result":{"action":"add","name":"<CONFIG-NAME>"}}

result 对象会随子命令变化。add 和 edit 还会包含 kind、url、saved_path、active_path、activated 和 validation 等字段，因此 Agent 不应该假设结果里只有 action 和 name。

错误结果会输出到 stderr：

json

{"status":"error","error":{"code":"bad_input","message":"..."}}

Agent 应该根据进程退出码和 JSON 中的 error.code 分支处理，不要解析面向人的说明文字。

退出码	含义
`0`	成功，或已经处于目标状态
`2`	输入错误、缺少参数、名称非法、无法读取密钥来源，或在非交互式 shell 中尚未选择显示语言（请先运行 `ov language <code>`）
`3`	同名配置已经存在但内容不同；只有确认要替换时才传 `--force`
`4`	服务端不可达，或配置校验失败
`5`	鉴权或 key 角色不匹配，例如把 root key 传到了需要 user key 的位置
`6`	操作被拒绝，例如删除 active 配置

列出已有配置

bash

ov config list -o json

列表输出形状如下：

json

{"status":"ok","result":[{"name":"<CONFIG-NAME>","kind":"OpenViking Service","url":"https://api.vikingdb.cn-beijing.volces.com/openviking","active":true}]}

做存在性检查时，读取 result[].name。判断是否还需要切换 active config 时，读取匹配项的 active 标记。

如果已经存在合适的 saved config，可以按名称激活：

bash

ov config switch <CONFIG-NAME> -o json

然后运行验证命令。

添加 OpenViking Service

如果 Agent 已经通过可信渠道拿到 API Key，运行：

bash

ov config add ov-service --name <CONFIG-NAME> --api-key-stdin --activate -o json

shell pipe 形式如下：

bash

printf '%s' "$API_KEY" | ov config add ov-service --name <CONFIG-NAME> --api-key-stdin --activate -o json

$API_KEY 表示可信的运行时密钥来源，不是字面量 key。Agent 能在不把 key 写进命令文本、shell history、日志或长期 export 的环境变量时提供 key，就应使用 stdin。

只把 API Key 内容写入 stdin，不要把 key 放进 shell 命令本身。这会写入一个 OpenViking Service 配置，并使用固定端点：https://api.vikingdb.cn-beijing.volces.com/openviking。ov-service 目标不接受自定义服务端 URL。

只有当环境变量已经存在时，才使用环境变量：

bash

ov config add ov-service --name <CONFIG-NAME> --api-key-env <API-KEY-ENV-VAR> --activate -o json

标准 OpenViking Service 配置不要传 --account 或 --user。只有当用户或 OpenViking 管理员提供身份覆盖值时，才使用它们。

添加本地自定义服务

只有当用户选择本地自定义时，才使用这个路径。

对于本地无鉴权服务：

bash

ov config add custom --name <CONFIG-NAME> --url http://127.0.0.1:1933 --activate -o json

如果本地服务没有运行，请先引导用户启动服务端。参见服务端模式。

添加远程自定义服务

对于使用普通 API Key 的远程自定义服务：

bash

ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --activate -o json

stdin pipe 形式如下：

bash

printf '%s' "$API_KEY" | ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --activate -o json

把 API Key 写入 stdin。如果 key 已经存在于当前 shell 环境变量中，可以改用 --api-key-env <API-KEY-ENV-VAR>。

如果用户只提供 root API key，需要同时提供目标 account 和 user：

bash

ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --root-api-key-stdin --account <ACCOUNT-ID> --user <USER-ID> --activate -o json

把 root API key 写入 stdin。Root key 需要显式 --account 和 --user，这样普通 CLI 命令才知道以哪个身份执行。

如果用户同时拥有 user key 和 root key，可以把两者放在同一个配置里：

bash

ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --root-api-key-env <ROOT-API-KEY-ENV-VAR> --account <ACCOUNT-ID> --user <USER-ID> --activate -o json

这样普通命令使用 user key，需要 --sudo 的命令使用 root key。因为一个命令只有一个 stdin 流，第二个 key 必须来自已经存在的环境变量。如果两个 key 都不在环境变量中，请使用 ov config 并引导用户完成交互式流程。

编辑或替换配置

先列出配置：

bash

ov config list -o json

重命名并激活 saved config：

bash

ov config edit <CONFIG-NAME> --new-name <NEW-CONFIG-NAME> --activate -o json

替换 API Key：

bash

ov config edit <CONFIG-NAME> --api-key-stdin --activate -o json

把新的 API Key 写入 stdin。

替换自定义服务 URL：

bash

ov config edit <CONFIG-NAME> --url <CUSTOM-OPENVIKING-URL> --activate -o json

只有在你明确要覆盖已有 saved config 名称时，才使用 --force。

删除 saved config

只删除非 active 的 saved config：

bash

ov config delete <OLD-CONFIG-NAME> -o json

如果该配置正处于 active 状态，先切换到另一个配置：

bash

ov config switch <CONFIG-NAME> -o json
ov config delete <OLD-CONFIG-NAME> -o json

验证配置

运行：

bash

ov config show
ov config list -o json
ov config validate
ov health
ov status

检查配置时优先使用 ov config show，因为它会隐藏密钥。

除非你理解配置文件可能包含密钥，否则不要打印原始配置文件。

如果验证命令提示 OpenViking 需要显示语言，请运行 ov language en；如果用户希望使用中文，则运行 ov language zh-CN，然后重新验证。

ov status 包含更宽泛的服务端和数据诊断。如果 ov config validate 和 ov health 通过，ov status 中的 warning 不一定代表 CLI 配置失败。

学习其他 CLI 命令

配置成功后，用内置帮助继续了解 ov 的其他能力：

bash

ov --help
ov config --help
ov add-resource --help

Agent 在运行不熟悉的命令前，应该重新查看帮助。如果 Agent 为用户维护长期记忆，并且用户允许，可以记录当前命令面的简要摘要，方便之后继续工作。不要记录密钥、原始配置文件或私有服务详情，除非用户明确要求。

凭证安全

API Key 可能允许访问你的 OpenViking 数据。
手动配置时，优先使用 ov config 的交互式输入框。
Agent 辅助配置时，只有通过你明确相信的渠道提供 API Key。
Agent 应通过 stdin 传入 key。只有当环境变量已经存在于当前 shell 中时，才使用环境变量。
不要把 API Key 直接写进可能被 shell history 保存的命令。
不要打印原始 ~/.openviking/ovcli.conf。
不要分享包含 API Key 的截图。
演示和试用建议使用临时或可撤销的 key。

常见问题

找不到 `ov`

运行：

bash

npm i -g @openviking/cli
npm prefix -g

然后重新打开 shell，或把 npm 全局 binary 目录加入 PATH。在 macOS 和 Linux 上，该目录通常是 $(npm prefix -g)/bin。

npm 全局安装失败

如果 npm 报权限错误，请按你平时管理 Node.js 的方式处理。除非你本来就用 sudo 管理全局 npm 包，否则不要直接运行 sudo npm i -g。

本地服务端没有运行

只有当用户选择本地自定义时才使用此项。先验证服务端：

bash

curl http://127.0.0.1:1933/health

如果失败，先启动服务端再配置 ov。参见服务端模式。

API Key 校验失败

重新运行 ov config 并编辑配置。对于 OpenViking Service，确认 API Key 来自上面的 OpenViking 控制台地址。对于自定义服务，确认服务端是否要求鉴权。

Agent 不应该反复重试未知 key。请让用户确认目标类型、服务端 URL、key 类型、account 和 user。

active 配置不对

检查并切换：

bash

ov config show
ov config list
ov config switch
ov config validate

Agent 可以按名称切换：

bash

ov config list -o json
ov config switch <CONFIG-NAME> -o json

非交互式配置不适合当前情况

使用交互式向导：

bash

ov config

当密钥应由用户直接在终端输入、连接目标不明确，或校验结果需要人工判断时，这是合适的回退路径。

旧配置命令

使用 ov config。不要使用旧的或已移除的配置命令，例如 ov config setup-cli。

下一步

CLI 配置完成后，使用 ov --help 和 ov <command> --help 继续了解其他命令。

添加资源会把数据写入 active OpenViking 服务端。如果你想做一个小演示，请选择你愿意存入服务端的资源。Agent 运行这类演示命令前，必须先征得用户同意。

bash

ov add-resource https://github.com/volcengine/OpenViking --wait
ov find "what is OpenViking"
ov tree viking://resources/ -L 2

查看全部命令：

bash

ov --help
ov config --help
ov add-resource --help

OpenViking CLI 配置指南 ​

本文配置什么 ​

选择连接目标 ​

OpenViking Service（火山引擎云） ​

远程自定义 ​

本地自定义 ​

开始前 ​

安装 ov ​

密钥类型 ​

手动配置 ​

Agent 辅助配置 ​

Agent 检查清单 ​

查看当前安装的 CLI ​

使用稳定名称便于重试 ​

读取结果 ​

列出已有配置 ​

添加 OpenViking Service ​

添加本地自定义服务 ​

添加远程自定义服务 ​

编辑或替换配置 ​

删除 saved config ​

验证配置 ​

学习其他 CLI 命令 ​

凭证安全 ​

常见问题 ​

找不到 ov ​

npm 全局安装失败 ​

本地服务端没有运行 ​

API Key 校验失败 ​

active 配置不对 ​

非交互式配置不适合当前情况 ​

旧配置命令 ​

下一步 ​

OpenViking CLI 配置指南

本文配置什么

选择连接目标

OpenViking Service（火山引擎云）

远程自定义

本地自定义

开始前

安装 `ov`

密钥类型

手动配置

Agent 辅助配置

Agent 检查清单

查看当前安装的 CLI

使用稳定名称便于重试

读取结果

列出已有配置

添加 OpenViking Service

添加本地自定义服务

添加远程自定义服务

编辑或替换配置

删除 saved config

验证配置

学习其他 CLI 命令

凭证安全

常见问题

找不到 `ov`

npm 全局安装失败

本地服务端没有运行

API Key 校验失败

active 配置不对

非交互式配置不适合当前情况

旧配置命令

下一步