Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs(cli): improve CLI agent setup flow (#2451)

Hao Zhe167215aff190
diff --git a/docs/en/getting-started/05-cli-setup.md b/docs/en/getting-started/05-cli-setup.md
index 5dd380e16..c9df61a53 100644
--- a/docs/en/getting-started/05-cli-setup.md
+++ b/docs/en/getting-started/05-cli-setup.md
@@ -9,13 +9,6 @@ Use this page in either of two ways:
- If you are setting up `ov` yourself, follow [Manual Setup](#manual-setup).
- If you are asking an agent to set it up for you, give the agent this page and ask it to follow [Agent-Assisted Setup](#agent-assisted-setup).
-Both paths should start by checking the installed CLI help:
-
-```bash
-ov --help
-ov config --help
-```
-
The CLI evolves quickly. Use `ov --help` and `ov <command> --help` as the source of truth for the commands available in your installed version.
## What This Configures
@@ -28,24 +21,37 @@ When you create named configs, `ov` stores them next to the active file as `~/.o
`ov config add`, `ov config edit`, `ov config list`, `ov config switch <name>`, and `ov config delete` are deterministic commands for scripts and agents.
-## Quick Path
+## Choose a Target
-```bash
-npm i -g @openviking/cli
-ov --help
-ov config
-ov config validate
-ov health
-ov status
-```
+Choose the OpenViking target before running setup commands.
+
+Agents should ask the user which target they want unless it has already been specified. Existing configs, active configs, local files, default ports, and running services can inform follow-up questions, but they are not consent for the agent to choose a target, switch or replace configs, probe local services, start servers, or write data.
-Expected result:
+### VolcEngine Cloud
-- `ov --help` prints the OpenViking command list.
-- `ov config` opens the interactive config manager.
-- `ov config validate` confirms the active config can reach and authenticate with the server.
-- `ov health` confirms basic server reachability.
-- `ov status` shows the active config and server diagnostics.
+Choose this when you want OpenViking hosted on VolcEngine Cloud.
+
+- Server endpoint used by `ov`: `https://api.vikingdb.cn-beijing.volces.com/openviking`
+- Console page for API keys: https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing
+- In the console, go to User Management → API Key to view and copy your key.
+- API key is required.
+- Standard setup only needs the API key. Do not ask for `--account` or `--user` unless the user's administrator specifically provides identity override values.
+
+### Remote Self-Managed
+
+Choose this when you connect to a self-managed OpenViking server hosted somewhere other than the current machine.
+
+- Server URL is provided by the user or server administrator.
+- API key may be required.
+- Root-key-only configs require `--account` and `--user`.
+
+### Local Self-Managed
+
+Choose this only when the user wants to connect to a self-managed OpenViking server on the current machine.
+
+- Default local URL: `http://127.0.0.1:1933`
+- API key is usually not needed for a local unauthenticated server.
+- Agents should not probe local ports, curl local health endpoints, or start server commands unless the user chose local self-managed.
## Before You Start
@@ -59,7 +65,7 @@ You need:
- a self-managed OpenViking server.
- An API key if your target requires authentication.
-API keys are sensitive. Prefer entering them through the interactive `ov config` prompt. For agent-assisted setup, prefer stdin when the agent already holds the key through a secure channel. Use an environment variable only when the key is already present in the shell environment. Avoid putting API keys directly in chat messages or shell history.
+API keys are sensitive. Prefer entering them through the interactive `ov config` prompt when you configure `ov` yourself. Only provide API keys to an agent through a channel you intentionally trust. The agent should pass the key through stdin and must not put it in shell commands, logs, long-term memory, or raw config output. Use an environment variable only when the key is already present in the shell environment.
## Install `ov`
@@ -70,6 +76,14 @@ command -v ov
ov --version
```
+If `ov --version` or any other `ov` command says OpenViking needs a display language, choose one and retry:
+
+```bash
+ov language en
+# or
+ov language zh-CN
+```
+
Install or upgrade the npm package:
```bash
@@ -106,26 +120,6 @@ OpenViking CLI configs can hold a user key, a root key, or both.
- Root key: use this for admin work and commands that require `--sudo`. A root key has no built-in tenant identity. If a config only has a root key, it must also include `--account` and `--user`; that root key then serves normal commands for that identity and `--sudo` commands.
- User key plus root key: use this when the same config should support daily data work and occasional admin work. Normal commands use the user key. `--sudo` commands use the root key with the configured account and user.
-## Choose a Target
-
-### VolcEngine Cloud
-
-Choose this when you want OpenViking hosted on VolcEngine Cloud.
-
-- Server endpoint used by `ov`: `https://api.vikingdb.cn-beijing.volces.com/openviking`
-- Console page for API keys: https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing
-- In the console, go to User Management → API Key to view and copy your key.
-- API key is required.
-- Standard setup only needs the API key. Do not ask for `--account` or `--user` unless the user's administrator specifically provides identity override values.
-
-### Self-Managed
-
-Choose this when you run or operate your own OpenViking server.
-
-- Default local URL: `http://127.0.0.1:1933`
-- API key is usually not needed for a local unauthenticated server.
-- API key may be required for a remote or authenticated self-managed server.
-
## Manual Setup
Use this path when you are reading the guide and configuring `ov` yourself.
@@ -141,7 +135,7 @@ Then choose:
1. `Add config`
2. `VolcEngine Cloud` or `Self-Managed`
3. A config name, or leave it empty to generate one
-4. The required URL and API key values
+4. The required URL and API key values for the target you chose above
5. Save the config after validation
If you manage more than one OpenViking target, use:
@@ -160,16 +154,17 @@ Use this path when an agent is setting up `ov` for a user. The agent should read
### Agent Checklist
-1. Confirm whether the user wants VolcEngine Cloud or a self-managed server.
-2. Run `ov --help`, `ov config --help`, and the relevant config subcommand help before choosing commands.
-3. If you have long-term memory and the user permits it, store a short summary of the current `ov --help` command surface. Do not store API keys or other secrets.
-4. Use non-interactive `ov config` commands when the required values are known.
-5. Always pass `--name` for agent setup so retries target the same saved config.
-6. If the agent already holds the API key through a secure channel, pass it with `--api-key-stdin` or `--root-api-key-stdin` and write only the key bytes to stdin. Use `--api-key-env` or `--root-api-key-env` only when that environment variable already exists. Do not ask the user to open a separate shell just to export a key for the agent.
-7. Use `-o json` and branch on the JSON result plus the process exit code.
-8. Validate the active config with `ov config validate`, then check `ov health` and `ov status`.
-9. If non-interactive setup fails because values are missing, auth is unclear, or terminal input is safer, guide the user through `ov config` instead.
-10. Do not run commands that add resources or otherwise store data in OpenViking unless the user explicitly permits that action.
+1. Ask which target the user wants unless it has already been specified: VolcEngine Cloud, remote self-managed, or local self-managed.
+2. Do not infer the intended setup from existing configs, active configs, local files, default ports, or running services.
+3. Ask before switching configs, replacing configs, probing local services, starting servers, or writing data.
+4. Run `ov --help`, `ov config --help`, and the relevant config subcommand help before choosing commands.
+5. If you have long-term memory and the user permits it, store a short summary of the current `ov --help` command surface. Do not store API keys or other secrets.
+6. Use non-interactive `ov config` commands when the required values are known.
+7. Always pass `--name` for agent setup so retries target the same saved config.
+8. If the agent already holds the API key through a trusted channel, pass it with `--api-key-stdin` or `--root-api-key-stdin` and write only the key bytes to stdin. Use `--api-key-env` or `--root-api-key-env` only when that environment variable already exists. Do not ask the user to open a separate shell just to export a key for the agent.
+9. Use `-o json` and branch on the JSON result plus the process exit code.
+10. Validate the active config with `ov config validate`, then check `ov health` and `ov status`.
+11. If non-interactive setup fails because values are missing, auth is unclear, or terminal input is safer, guide the user through `ov config` instead.
### Inspect the Installed CLI
@@ -186,18 +181,22 @@ ov config edit --help
Use the installed CLI help as the source of truth. If this page and the installed help disagree, follow the installed help and tell the user what changed.
+If a help command says OpenViking needs a display language, run `ov language en`, or `ov language zh-CN` if the user wants Chinese, then retry. Non-interactive config subcommands such as `ov config add`, `ov config list`, `ov config edit`, `ov config switch <name>`, and `ov config delete` can run before the display language is set.
+
### Use Stable Names for Retries
Always pass `--name` when an agent creates a config. If you omit it, `ov` generates a random name; a retry can create a second saved config instead of updating the intended one.
`ov config add` is safe to run again with the same `--name` when the values are identical. It exits `0`, and `--activate` will make that saved config active again. If the same name already exists with different values, the command exits `3` and asks for `--force`.
+In the examples below, replace placeholders such as `<CONFIG-NAME>` and `<REMOTE-OPENVIKING-URL>` with user-approved values before running commands. Do not include the angle brackets.
+
### Reading Results
When you use `-o json` with the non-interactive config commands, successful results are printed to stdout:
```json
-{"status":"ok","result":{"action":"add","name":"prod"}}
+{"status":"ok","result":{"action":"add","name":"<CONFIG-NAME>"}}
```
The result object depends on the subcommand. `add` and `edit` also include fields such as `kind`, `url`, `saved_path`, `active_path`, `activated`, and `validation`, so agents should not assume that only `action` and `name` are present.
@@ -228,7 +227,7 @@ ov config list -o json
The list output shape is:
```json
-{"status":"ok","result":[{"name":"prod","kind":"VolcEngine Cloud","url":"https://api.vikingdb.cn-beijing.volces.com/openviking","active":true}]}
+{"status":"ok","result":[{"name":"<CONFIG-NAME>","kind":"VolcEngine Cloud","url":"https://api.vikingdb.cn-beijing.volces.com/openviking","active":true}]}
```
For an existence check, inspect `result[].name`. To decide whether a config already needs switching, inspect the matching entry's `active` flag.
@@ -236,35 +235,45 @@ For an existence check, inspect `result[].name`. To decide whether a config alre
If a suitable saved config already exists, activate it by name:
```bash
-ov config switch prod -o json
+ov config switch <CONFIG-NAME> -o json
```
Then run the verification commands.
### Add VolcEngine Cloud
-If the agent already holds the API key through a secure channel, run:
+If the agent already holds the API key through a trusted channel, run:
```bash
-ov config add cloud --name prod --api-key-stdin --activate -o json
+ov config add cloud --name <CONFIG-NAME> --api-key-stdin --activate -o json
```
+A shell pipe has this shape:
+
+```bash
+printf '%s' "$API_KEY" | ov config add cloud --name <CONFIG-NAME> --api-key-stdin --activate -o json
+```
+
+`$API_KEY` stands for a trusted runtime secret source, not the literal key. Use stdin when the agent can supply the key without putting it in the command text, shell history, logs, or a long-lived exported environment variable.
+
Write only the API key bytes to stdin. Do not place the key in the shell command. This writes a VolcEngine Cloud config using the fixed endpoint `https://api.vikingdb.cn-beijing.volces.com/openviking`. The `cloud` target does not take a custom server URL.
Use an environment variable only if it already exists in the shell:
```bash
-ov config add cloud --name prod --api-key-env OV_API_KEY --activate -o json
+ov config add cloud --name <CONFIG-NAME> --api-key-env <API-KEY-ENV-VAR> --activate -o json
```
Do not pass `--account` or `--user` for standard VolcEngine Cloud setup. Use them only when the user or their OpenViking administrator provides identity override values.
### Add a Local Self-Managed Server
+Use this path only after the user chooses local self-managed.
+
For a local unauthenticated server:
```bash
-ov config add self-managed --name local --url http://127.0.0.1:1933 --activate -o json
+ov config add self-managed --name <CONFIG-NAME> --url http://127.0.0.1:1933 --activate -o json
```
If the local server is not running, guide the user to start it first. See the [Server Mode guide](03-quickstart-server.md).
@@ -274,15 +283,21 @@ If the local server is not running, guide the user to start it first. See the [S
For a hosted self-managed server with a normal API key:
```bash
-ov config add self-managed --name hosted --url https://ov.example.com --api-key-stdin --activate -o json
+ov config add self-managed --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --activate -o json
+```
+
+The stdin pipe form is:
+
+```bash
+printf '%s' "$API_KEY" | ov config add self-managed --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --activate -o json
```
-Write the API key to stdin. If the key is already in the shell environment, use `--api-key-env OV_API_KEY` instead.
+Write the API key to stdin. If the key is already in the shell environment, use `--api-key-env <API-KEY-ENV-VAR>` instead.
For a self-managed server where the user gives you only a root API key, include the target account and user:
```bash
-ov config add self-managed --name hosted --url https://ov.example.com --root-api-key-stdin --account "$OV_ACCOUNT" --user "$OV_USER" --activate -o json
+ov config add self-managed --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --root-api-key-stdin --account <ACCOUNT-ID> --user <USER-ID> --activate -o json
```
Write the root API key to stdin. Root keys require explicit `--account` and `--user` so normal CLI commands know which identity to use.
@@ -290,7 +305,7 @@ Write the root API key to stdin. Root keys require explicit `--account` and `--u
For a self-managed server where the user has both a user key and a root key, store both in one config:
```bash
-ov config add self-managed --name hosted-admin --url https://ov.example.com --api-key-stdin --root-api-key-env OV_ROOT_API_KEY --account "$OV_ACCOUNT" --user "$OV_USER" --activate -o json
+ov config add self-managed --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
```
This keeps normal commands on the user key and lets `--sudo` commands use the root key. Because one command has only one stdin stream, the second key must come from an existing environment variable. If neither key is already available in the environment, use `ov config` and guide the user through the interactive flow.
@@ -306,13 +321,13 @@ ov config list -o json
Rename and activate a saved config:
```bash
-ov config edit prod --new-name production --activate -o json
+ov config edit <CONFIG-NAME> --new-name <NEW-CONFIG-NAME> --activate -o json
```
Replace an API key:
```bash
-ov config edit production --api-key-stdin --activate -o json
+ov config edit <CONFIG-NAME> --api-key-stdin --activate -o json
```
Write the replacement API key to stdin.
@@ -320,7 +335,7 @@ Write the replacement API key to stdin.
Replace a self-managed URL:
```bash
-ov config edit local --url http://127.0.0.1:1933 --activate -o json
+ov config edit <CONFIG-NAME> --url <SELF-MANAGED-URL> --activate -o json
```
Use `--force` only when you intentionally want to replace an existing saved config name.
@@ -330,14 +345,14 @@ Use `--force` only when you intentionally want to replace an existing saved conf
Delete only non-active saved configs:
```bash
-ov config delete old-local -o json
+ov config delete <OLD-CONFIG-NAME> -o json
```
If the config is active, switch to another config first:
```bash
-ov config switch prod -o json
-ov config delete old-local -o json
+ov config switch <CONFIG-NAME> -o json
+ov config delete <OLD-CONFIG-NAME> -o json
```
## Verify the Setup
@@ -346,6 +361,7 @@ Run:
```bash
ov config show
+ov config list -o json
ov config validate
ov health
ov status
@@ -355,6 +371,10 @@ Use `ov config show` for inspection because it redacts secrets.
Do not print the raw config file unless you understand that it may contain secrets.
+If a verification command says OpenViking needs a display language, run `ov language en`, or `ov language zh-CN` if the user wants Chinese, then rerun verification.
+
+`ov status` includes broader server and data diagnostics. If `ov config validate` and `ov health` pass, a warning in `ov status` does not always mean CLI setup failed.
+
## Learn the Rest of the CLI
After the config is working, use the built-in help to explore the rest of `ov`:
@@ -371,9 +391,9 @@ Agents should refresh this help before running unfamiliar commands. If an agent
- API keys may grant access to your OpenViking data.
- Prefer the interactive `ov config` prompt for manual setup.
-- For agent-assisted setup, prefer stdin when the agent already holds the key. Use environment variables only when they already exist in the shell.
+- For agent-assisted setup, provide API keys only through a channel you intentionally trust.
+- Agents should pass keys through stdin. Use environment variables only when they already exist in the shell.
- Do not include API keys directly in shell commands that may be saved in shell history.
-- Do not paste API keys into chat unless you intentionally trust that channel.
- Do not print raw `~/.openviking/ovcli.conf`.
- Do not share screenshots that reveal API keys.
- Use temporary or revocable keys for demos and trials.
@@ -397,7 +417,7 @@ If npm reports a permission error, use your normal Node.js setup policy. Avoid `
### Local Server Is Not Running
-For self-managed local setup, verify the server first:
+Use this only when the user chose local self-managed setup. Then verify the server:
```bash
curl http://127.0.0.1:1933/health
@@ -426,7 +446,7 @@ Agents can switch by name:
```bash
ov config list -o json
-ov config switch prod -o json
+ov config switch <CONFIG-NAME> -o json
```
### Non-Interactive Setup Does Not Fit
diff --git a/docs/zh/getting-started/05-cli-setup.md b/docs/zh/getting-started/05-cli-setup.md
index b401127a2..0cb5eb5a8 100644
--- a/docs/zh/getting-started/05-cli-setup.md
+++ b/docs/zh/getting-started/05-cli-setup.md
@@ -9,13 +9,6 @@
- 如果你自己手动配置 `ov`,请阅读[手动配置](#手动配置)。
- 如果你让 Agent 帮你配置,请把本文发给 Agent,并让它阅读 [Agent 辅助配置](#agent-辅助配置)。
-两种方式都应该先查看当前安装版本的 CLI 帮助:
-
-```bash
-ov --help
-ov config --help
-```
-
CLI 会持续演进。请把 `ov --help` 和 `ov <command> --help` 作为当前安装版本的命令准确信息来源。
## 本文配置什么
@@ -28,24 +21,37 @@ CLI 使用 `~/.openviking/ovcli.conf` 作为 active 客户端连接配置。
`ov config add`、`ov config edit`、`ov config list`、`ov config switch <name>` 和 `ov config delete` 是面向脚本和 Agent 的确定性命令。
-## 最短路径
+## 选择连接目标
-```bash
-npm i -g @openviking/cli
-ov --help
-ov config
-ov config validate
-ov health
-ov status
-```
+运行配置命令前,先选择要连接的 OpenViking 目标。
+
+除非用户已经明确说明,Agent 应先询问用户要连接哪种目标。已有配置、active 配置、本地文件、默认端口和正在运行的服务可以帮助 Agent 追问细节,但不代表用户同意 Agent 选择目标、切换或替换配置、探测本地服务、启动服务端,或写入数据。
+
+### VolcEngine Cloud
+
+如果你希望使用 VolcEngine Cloud 托管的 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 服务端,选择此项。
-- `ov --help` 输出 OpenViking 命令列表。
-- `ov config` 打开交互式配置管理器。
-- `ov config validate` 确认 active 配置可以连接服务端并通过鉴权。
-- `ov health` 确认服务端基础可达。
-- `ov status` 展示 active 配置和服务端诊断信息。
+- 服务端 URL 由用户或服务端管理员提供。
+- 可能需要 API Key。
+- 只有 root key 的配置需要 `--account` 和 `--user`。
+
+### 本地自托管
+
+只有当用户要连接当前机器上的自托管 OpenViking 服务端时,才选择此项。
+
+- 本地默认 URL:`http://127.0.0.1:1933`
+- 本地无鉴权服务通常不需要 API Key。
+- 除非用户选择本地自托管,否则 Agent 不应探测本地端口、curl 本地 health endpoint,或运行启动服务端的命令。
## 开始前
@@ -59,7 +65,7 @@ ov status
- 自托管 OpenViking 服务端。
- 如果目标需要鉴权,需要准备 API Key。
-API Key 是敏感凭证。手动配置时优先通过 `ov config` 的交互式输入框输入。Agent 辅助配置时,如果 Agent 已经通过安全渠道拿到 key,优先使用 stdin。只有当 key 已经存在于当前 shell 环境变量中时,才使用环境变量。避免把 API Key 直接写进聊天消息或 shell history。
+API Key 是敏感凭证。手动配置时优先通过 `ov config` 的交互式输入框输入。只有当你明确相信当前渠道时,才把 API Key 提供给 Agent。Agent 应通过 stdin 传入 key,不能把 key 写进 shell 命令、日志、长期记忆或原始配置输出。只有当 key 已经存在于当前 shell 环境变量中时,才使用环境变量。
## 安装 `ov`
@@ -70,6 +76,14 @@ command -v ov
ov --version
```
+如果 `ov --version` 或任何其他 `ov` 命令提示 OpenViking 需要显示语言,请先选择语言再重试:
+
+```bash
+ov language en
+# 或
+ov language zh-CN
+```
+
安装或升级 npm 包:
```bash
@@ -106,26 +120,6 @@ OpenViking CLI 配置可以包含 user key、root key,或同时包含两者。
- Root key:用于管理操作和需要 `--sudo` 的命令。Root key 自身不包含租户身份。如果一个配置只有 root key,就必须同时包含 `--account` 和 `--user`;这个 root key 会同时服务于该身份下的普通命令和 `--sudo` 命令。
- User key + root key:适合一个配置同时支持日常数据操作和偶尔的管理操作。普通命令使用 user key,`--sudo` 命令使用 root key,并带上配置中的 account 和 user。
-## 选择连接目标
-
-### VolcEngine Cloud
-
-如果你希望使用火山引擎托管的 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`。
-
-### Self-Managed
-
-如果你运行或维护自己的 OpenViking 服务端,选择此项。
-
-- 本地默认 URL:`http://127.0.0.1:1933`
-- 本地无鉴权服务通常不需要 API Key。
-- 远程或开启鉴权的自托管服务端可能需要 API Key。
-
## 手动配置
如果你正在阅读本文,并准备自己配置 `ov`,使用这个路径。
@@ -141,7 +135,7 @@ ov config
1. `Add config`
2. `VolcEngine Cloud` 或 `Self-Managed`
3. 配置名称,或留空自动生成
-4. 所需的 URL 和 API Key
+4. 上面选择的目标所需的 URL 和 API Key
5. 校验成功后保存配置
如果你维护多个 OpenViking 目标,之后可以使用:
@@ -160,16 +154,17 @@ ov config switch
### Agent 检查清单
-1. 确认用户要连接 VolcEngine Cloud 还是自托管服务端。
-2. 在选择命令前,运行 `ov --help`、`ov config --help` 和相关 config 子命令的帮助。
-3. 如果你具备长期记忆能力,并且用户允许,可以记录当前 `ov --help` 命令面的简要摘要。不要记录 API Key 或其他密钥。
-4. 当必需信息明确时,使用非交互式 `ov config` 命令。
-5. Agent 配置时始终传 `--name`,这样重试会命中同一个 saved config。
-6. 如果 Agent 已经通过安全渠道拿到 API Key,使用 `--api-key-stdin` 或 `--root-api-key-stdin`,并且只把 key 内容写入 stdin。只有当环境变量已经存在时,才使用 `--api-key-env` 或 `--root-api-key-env`。不要要求用户额外打开一个 shell 只为了给 Agent export 一个 key。
-7. 使用 `-o json`,并根据 JSON 结果和进程退出码分支处理。
-8. 使用 `ov config validate` 校验 active 配置,然后运行 `ov health` 和 `ov status`。
-9. 如果非交互式配置因为信息缺失、鉴权不明确或终端输入更安全而失败,请引导用户使用 `ov config` 交互式向导。
-10. 除非用户明确允许,否则不要运行会添加资源或把数据写入 OpenViking 的命令。
+1. 除非用户已经明确说明,先询问用户要连接哪种目标:VolcEngine Cloud、远程自托管,还是本地自托管。
+2. 不要根据已有配置、active 配置、本地文件、默认端口或正在运行的服务推断用户想要的 setup。
+3. 切换配置、替换配置、探测本地服务、启动服务端或写入数据前,都要先询问用户。
+4. 在选择命令前,运行 `ov --help`、`ov config --help` 和相关 config 子命令的帮助。
+5. 如果你具备长期记忆能力,并且用户允许,可以记录当前 `ov --help` 命令面的简要摘要。不要记录 API Key 或其他密钥。
+6. 当必需信息明确时,使用非交互式 `ov config` 命令。
+7. Agent 配置时始终传 `--name`,这样重试会命中同一个 saved config。
+8. 如果 Agent 已经通过可信渠道拿到 API Key,使用 `--api-key-stdin` 或 `--root-api-key-stdin`,并且只把 key 内容写入 stdin。只有当环境变量已经存在时,才使用 `--api-key-env` 或 `--root-api-key-env`。不要要求用户额外打开一个 shell 只为了给 Agent export 一个 key。
+9. 使用 `-o json`,并根据 JSON 结果和进程退出码分支处理。
+10. 使用 `ov config validate` 校验 active 配置,然后运行 `ov health` 和 `ov status`。
+11. 如果非交互式配置因为信息缺失、鉴权不明确或终端输入更安全而失败,请引导用户使用 `ov config` 交互式向导。
### 查看当前安装的 CLI
@@ -186,18 +181,22 @@ 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":"prod"}}
+{"status":"ok","result":{"action":"add","name":"<CONFIG-NAME>"}}
```
`result` 对象会随子命令变化。`add` 和 `edit` 还会包含 `kind`、`url`、`saved_path`、`active_path`、`activated` 和 `validation` 等字段,因此 Agent 不应该假设结果里只有 `action` 和 `name`。
@@ -228,7 +227,7 @@ ov config list -o json
列表输出形状如下:
```json
-{"status":"ok","result":[{"name":"prod","kind":"VolcEngine Cloud","url":"https://api.vikingdb.cn-beijing.volces.com/openviking","active":true}]}
+{"status":"ok","result":[{"name":"<CONFIG-NAME>","kind":"VolcEngine Cloud","url":"https://api.vikingdb.cn-beijing.volces.com/openviking","active":true}]}
```
做存在性检查时,读取 `result[].name`。判断是否还需要切换 active config 时,读取匹配项的 `active` 标记。
@@ -236,35 +235,45 @@ ov config list -o json
如果已经存在合适的 saved config,可以按名称激活:
```bash
-ov config switch prod -o json
+ov config switch <CONFIG-NAME> -o json
```
然后运行验证命令。
### 添加 VolcEngine Cloud
-如果 Agent 已经通过安全渠道拿到 API Key,运行:
+如果 Agent 已经通过可信渠道拿到 API Key,运行:
+
+```bash
+ov config add cloud --name <CONFIG-NAME> --api-key-stdin --activate -o json
+```
+
+shell pipe 形式如下:
```bash
-ov config add cloud --name prod --api-key-stdin --activate -o json
+printf '%s' "$API_KEY" | ov config add cloud --name <CONFIG-NAME> --api-key-stdin --activate -o json
```
+`$API_KEY` 表示可信的运行时密钥来源,不是字面量 key。Agent 能在不把 key 写进命令文本、shell history、日志或长期 export 的环境变量时提供 key,就应使用 stdin。
+
只把 API Key 内容写入 stdin,不要把 key 放进 shell 命令本身。这会写入一个 VolcEngine Cloud 配置,并使用固定端点:`https://api.vikingdb.cn-beijing.volces.com/openviking`。`cloud` 目标不接受自定义服务端 URL。
只有当环境变量已经存在时,才使用环境变量:
```bash
-ov config add cloud --name prod --api-key-env OV_API_KEY --activate -o json
+ov config add cloud --name <CONFIG-NAME> --api-key-env <API-KEY-ENV-VAR> --activate -o json
```
标准 VolcEngine Cloud 配置不要传 `--account` 或 `--user`。只有当用户或 OpenViking 管理员提供身份覆盖值时,才使用它们。
### 添加本地自托管服务
+只有当用户选择本地自托管时,才使用这个路径。
+
对于本地无鉴权服务:
```bash
-ov config add self-managed --name local --url http://127.0.0.1:1933 --activate -o json
+ov config add self-managed --name <CONFIG-NAME> --url http://127.0.0.1:1933 --activate -o json
```
如果本地服务没有运行,请先引导用户启动服务端。参见[服务端模式](03-quickstart-server.md)。
@@ -274,15 +283,21 @@ ov config add self-managed --name local --url http://127.0.0.1:1933 --activate -
对于使用普通 API Key 的远程自托管服务:
```bash
-ov config add self-managed --name hosted --url https://ov.example.com --api-key-stdin --activate -o json
+ov config add self-managed --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --activate -o json
+```
+
+stdin pipe 形式如下:
+
+```bash
+printf '%s' "$API_KEY" | ov config add self-managed --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --activate -o json
```
-把 API Key 写入 stdin。如果 key 已经存在于当前 shell 环境变量中,可以改用 `--api-key-env OV_API_KEY`。
+把 API Key 写入 stdin。如果 key 已经存在于当前 shell 环境变量中,可以改用 `--api-key-env <API-KEY-ENV-VAR>`。
如果用户只提供 root API key,需要同时提供目标 account 和 user:
```bash
-ov config add self-managed --name hosted --url https://ov.example.com --root-api-key-stdin --account "$OV_ACCOUNT" --user "$OV_USER" --activate -o json
+ov config add self-managed --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 命令才知道以哪个身份执行。
@@ -290,7 +305,7 @@ ov config add self-managed --name hosted --url https://ov.example.com --root-api
如果用户同时拥有 user key 和 root key,可以把两者放在同一个配置里:
```bash
-ov config add self-managed --name hosted-admin --url https://ov.example.com --api-key-stdin --root-api-key-env OV_ROOT_API_KEY --account "$OV_ACCOUNT" --user "$OV_USER" --activate -o json
+ov config add self-managed --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` 并引导用户完成交互式流程。
@@ -306,13 +321,13 @@ ov config list -o json
重命名并激活 saved config:
```bash
-ov config edit prod --new-name production --activate -o json
+ov config edit <CONFIG-NAME> --new-name <NEW-CONFIG-NAME> --activate -o json
```
替换 API Key:
```bash
-ov config edit production --api-key-stdin --activate -o json
+ov config edit <CONFIG-NAME> --api-key-stdin --activate -o json
```
把新的 API Key 写入 stdin。
@@ -320,7 +335,7 @@ ov config edit production --api-key-stdin --activate -o json
替换自托管 URL:
```bash
-ov config edit local --url http://127.0.0.1:1933 --activate -o json
+ov config edit <CONFIG-NAME> --url <SELF-MANAGED-URL> --activate -o json
```
只有在你明确要覆盖已有 saved config 名称时,才使用 `--force`。
@@ -330,14 +345,14 @@ ov config edit local --url http://127.0.0.1:1933 --activate -o json
只删除非 active 的 saved config:
```bash
-ov config delete old-local -o json
+ov config delete <OLD-CONFIG-NAME> -o json
```
如果该配置正处于 active 状态,先切换到另一个配置:
```bash
-ov config switch prod -o json
-ov config delete old-local -o json
+ov config switch <CONFIG-NAME> -o json
+ov config delete <OLD-CONFIG-NAME> -o json
```
## 验证配置
@@ -346,6 +361,7 @@ ov config delete old-local -o json
```bash
ov config show
+ov config list -o json
ov config validate
ov health
ov status
@@ -355,6 +371,10 @@ ov status
除非你理解配置文件可能包含密钥,否则不要打印原始配置文件。
+如果验证命令提示 OpenViking 需要显示语言,请运行 `ov language en`;如果用户希望使用中文,则运行 `ov language zh-CN`,然后重新验证。
+
+`ov status` 包含更宽泛的服务端和数据诊断。如果 `ov config validate` 和 `ov health` 通过,`ov status` 中的 warning 不一定代表 CLI 配置失败。
+
## 学习其他 CLI 命令
配置成功后,用内置帮助继续了解 `ov` 的其他能力:
@@ -371,9 +391,9 @@ Agent 在运行不熟悉的命令前,应该重新查看帮助。如果 Agent
- API Key 可能允许访问你的 OpenViking 数据。
- 手动配置时,优先使用 `ov config` 的交互式输入框。
-- Agent 辅助配置时,如果 Agent 已经拿到 key,优先使用 stdin。只有当环境变量已经存在于当前 shell 中时,才使用环境变量。
+- Agent 辅助配置时,只有通过你明确相信的渠道提供 API Key。
+- Agent 应通过 stdin 传入 key。只有当环境变量已经存在于当前 shell 中时,才使用环境变量。
- 不要把 API Key 直接写进可能被 shell history 保存的命令。
-- 除非你明确信任当前聊天渠道,否则不要把 API Key 粘贴进聊天。
- 不要打印原始 `~/.openviking/ovcli.conf`。
- 不要分享包含 API Key 的截图。
- 演示和试用建议使用临时或可撤销的 key。
@@ -397,7 +417,7 @@ npm prefix -g
### 本地服务端没有运行
-对于本地 Self-Managed 配置,先验证服务端:
+只有当用户选择本地自托管时才使用此项。先验证服务端:
```bash
curl http://127.0.0.1:1933/health
@@ -426,7 +446,7 @@ Agent 可以按名称切换:
```bash
ov config list -o json
-ov config switch prod -o json
+ov config switch <CONFIG-NAME> -o json
```
### 非交互式配置不适合当前情况