Skip to content

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

docs: add server and client configuration reference (#3651)

yufeng9c9a29462ac6
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 5f491e81b..5a0d49be0 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -30,6 +30,7 @@ const preferenceBootstrapScript = `;(() => {
const sectionNames: Record<string, string> = {
'getting-started': 'Getting Started',
+ configuration: 'Configuration',
concepts: 'Concepts',
guides: 'Guides',
'agent-integrations': 'Agent Integrations',
@@ -41,7 +42,8 @@ const sectionNames: Record<string, string> = {
}
const zhSectionNames: Record<string, string> = {
- 'getting-started': '快速开始',
+ 'getting-started': '开始使用',
+ configuration: '配置',
concepts: '核心概念',
guides: '指南',
'agent-integrations': 'Agent 集成',
@@ -62,7 +64,7 @@ const navLabels = {
about: 'About'
},
zh: {
- start: '快速开始',
+ start: '开始使用',
concepts: '核心概念',
guide: '指南',
api: 'API 参考',
@@ -100,6 +102,23 @@ function sidebarSection(dir: string, title: string, collapsed = true): DefaultTh
return { text: title, collapsed, items }
}
+const gettingStartedSidebar = {
+ en: [
+ ['01-introduction.md', 'Introduction'],
+ ['02-quickstart.md', 'Quick Start'],
+ ['03-quickstart-server.md', 'Server Deployment'],
+ ['04-setup-for-agent.md', 'Server Setup for Agent'],
+ ['05-cli-setup.md', 'OpenViking CLI']
+ ],
+ zh: [
+ ['01-introduction.md', '简介'],
+ ['02-quickstart.md', '快速开始'],
+ ['03-quickstart-server.md', '服务端部署'],
+ ['04-setup-for-agent.md', '服务端安装(Agent 版)'],
+ ['05-cli-setup.md', 'OpenViking CLI']
+ ]
+} as const
+
const agentIntegrationSidebar = {
en: {
overview: 'Integration Overview',
@@ -536,6 +555,20 @@ function agentIntegrationSection(
)
}
+function gettingStartedSection(
+ locale: 'en' | 'zh',
+ title: string,
+ collapsed = true
+): DefaultTheme.SidebarItem {
+ return {
+ text: title,
+ collapsed,
+ items: gettingStartedSidebar[locale].map((item) =>
+ configuredSidebarItem(locale, 'getting-started', item)
+ )
+ }
+}
+
function apiReferenceSection(
locale: 'en' | 'zh',
title: string,
@@ -586,6 +619,7 @@ function migrationSection(
type LocalizedSidebarSection =
| 'getting-started'
+ | 'configuration'
| 'concepts'
| 'guides'
| 'agent-integrations'
@@ -601,8 +635,9 @@ const localizedSidebarSectionBuilders: Record<
LocalizedSidebarSection,
LocalizedSidebarSectionBuilder
> = {
- 'getting-started': (locale, title, collapsed = true) =>
- sidebarSection(`${locale}/getting-started`, title, collapsed),
+ 'getting-started': gettingStartedSection,
+ configuration: (locale, title, collapsed = true) =>
+ sidebarSection(`${locale}/configuration`, title, collapsed),
concepts: conceptsSection,
guides: guidesSection,
'agent-integrations': agentIntegrationSection,
@@ -652,7 +687,7 @@ const designSidebar: DefaultTheme.SidebarItem[] = [
]
const enNav: DefaultTheme.NavItem[] = [
- { text: navLabels.en.start, link: '/en/getting-started/01-introduction', activeMatch: '/en/(getting-started|agent-integrations)/' },
+ { text: navLabels.en.start, link: '/en/getting-started/01-introduction', activeMatch: '/en/(getting-started|configuration|agent-integrations)/' },
{ text: navLabels.en.concepts, link: '/en/concepts/01-architecture', activeMatch: '/en/concepts/' },
{ text: navLabels.en.guide, link: '/en/guides/01-configuration', activeMatch: '/en/(guides|migration)/' },
{ text: navLabels.en.api, link: '/en/api/01-overview', activeMatch: '/en/api/' },
@@ -661,7 +696,7 @@ const enNav: DefaultTheme.NavItem[] = [
]
const zhNav: DefaultTheme.NavItem[] = [
- { text: navLabels.zh.start, link: '/zh/getting-started/01-introduction', activeMatch: '/zh/(getting-started|agent-integrations)/' },
+ { text: navLabels.zh.start, link: '/zh/getting-started/01-introduction', activeMatch: '/zh/(getting-started|configuration|agent-integrations)/' },
{ text: navLabels.zh.concepts, link: '/zh/concepts/01-architecture', activeMatch: '/zh/concepts/' },
{ text: navLabels.zh.guide, link: '/zh/guides/01-configuration', activeMatch: '/zh/(guides|migration)/' },
{ text: navLabels.zh.api, link: '/zh/api/01-overview', activeMatch: '/zh/api/' },
@@ -889,10 +924,11 @@ export default defineConfig({
level: [2, 3]
},
sidebar: {
- '/en/getting-started/': localizedGroupedSidebarItems('en', ['getting-started', 'agent-integrations']),
+ '/en/getting-started/': localizedGroupedSidebarItems('en', ['getting-started', 'configuration', 'agent-integrations']),
+ '/en/configuration/': localizedGroupedSidebarItems('en', ['getting-started', 'configuration', 'agent-integrations']),
'/en/concepts/': localizedSectionSidebarItems('en', 'concepts'),
'/en/guides/': localizedGroupedSidebarItems('en', ['guides', 'migration']),
- '/en/agent-integrations/': localizedGroupedSidebarItems('en', ['getting-started', 'agent-integrations']),
+ '/en/agent-integrations/': localizedGroupedSidebarItems('en', ['getting-started', 'configuration', 'agent-integrations']),
'/en/migration/': localizedGroupedSidebarItems('en', ['guides', 'migration']),
'/en/api/': localizedReferenceSidebarItems('en'),
'/en/about/': localizedAboutSidebarItems('en'),
@@ -909,10 +945,11 @@ export default defineConfig({
themeConfig: {
nav: zhNav,
sidebar: {
- '/zh/getting-started/': localizedGroupedSidebarItems('zh', ['getting-started', 'agent-integrations']),
+ '/zh/getting-started/': localizedGroupedSidebarItems('zh', ['getting-started', 'configuration', 'agent-integrations']),
+ '/zh/configuration/': localizedGroupedSidebarItems('zh', ['getting-started', 'configuration', 'agent-integrations']),
'/zh/concepts/': localizedSectionSidebarItems('zh', 'concepts'),
'/zh/guides/': localizedGroupedSidebarItems('zh', ['guides', 'migration']),
- '/zh/agent-integrations/': localizedGroupedSidebarItems('zh', ['getting-started', 'agent-integrations']),
+ '/zh/agent-integrations/': localizedGroupedSidebarItems('zh', ['getting-started', 'configuration', 'agent-integrations']),
'/zh/migration/': localizedGroupedSidebarItems('zh', ['guides', 'migration']),
'/zh/api/': localizedReferenceSidebarItems('zh'),
'/zh/about/': localizedAboutSidebarItems('zh')
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
index 96d32f196..3914e693e 100644
--- a/docs/.vitepress/theme/custom.css
+++ b/docs/.vitepress/theme/custom.css
@@ -110,6 +110,11 @@
display: none !important;
}
+.VPSidebar .VPSidebarItem > .item {
+ -webkit-user-select: none;
+ user-select: none;
+}
+
.ov-docs-search {
display: flex;
align-items: center;
diff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.md
new file mode 100644
index 000000000..d1ebad2d0
--- /dev/null
+++ b/docs/en/configuration/01-server.md
@@ -0,0 +1,373 @@
+# Server Configuration
+
+For initial setup, run `openviking-server init`, then run `openviking-server doctor` after saving the configuration.
+
+The OpenViking server and embedded Python SDK mode read `ov.conf`. The default path is:
+
+```text
+~/.openviking/ov.conf
+```
+
+Use an environment variable or startup option to select another file:
+
+```bash
+export OPENVIKING_CONFIG_FILE=/path/to/ov.conf
+openviking-server --config /path/to/ov.conf
+```
+
+The server reads the file at startup. Restart the server after changing models, retrieval, storage, or `server` settings, then run `openviking-server doctor`.
+
+## Configuration Structure
+
+```json
+{
+ "embedding": {},
+ "vlm": {},
+ "query_planner": {},
+ "rerank": {},
+ "retrieval": {},
+ "storage": {},
+ "server": {},
+ "memory": {},
+ "parsers": {},
+ "encryption": {},
+ "log": {},
+ "telemetry": {}
+}
+```
+
+Optional sections use their defaults when omitted. Unknown fields are rejected.
+
+## Top-Level Settings
+
+| Setting | Type / values | Default | Purpose |
+|---|---|---|---|
+| `default_account` | string | `"default"` | Default account in embedded SDK mode |
+| `default_user` | string | `"default"` | Default user in embedded SDK mode |
+| `embedding` | object | built-in local dense model | Dense, sparse, and hybrid embedding; defaults to `local` / `bge-small-zh-v1.5-f16` |
+| `vlm` | object | empty config | Content understanding, summaries, and memory extraction; configure a working model before using these capabilities |
+| `query_planner` | object / `null` | `null` | Retrieval intent model; falls back to `vlm` |
+| `rerank` | object | disabled | Retrieval result reranking |
+| `retrieval` | object | see below | Ranking and intent-analysis behavior |
+| `grep` | object | built-in defaults | Text search engine |
+| `storage` | object | local | Workspace, file system, and vector database |
+| `server` | object | local development | HTTP, authentication, uploads, and observability |
+| `memory` | object | see below | Memory and skill extraction on session commit |
+| `parsers` | object | parser defaults | PDF, code, image, audio, video, and text parsing |
+| `semantic` | object | built-in defaults | Abstract and overview generation limits |
+| `parser_api` | object | disabled | Third-party file parser API |
+| `connector` | object | disabled | External Connector ingestion service |
+| `encryption` | object | disabled | File and secret encryption |
+| `git` | object | local | Version backend: `local` or `s3` |
+| `log` | object | console | Log level, format, and file output |
+| `telemetry` | object | disabled | OpenTelemetry tracing |
+| `oauth` | object | disabled | MCP OAuth 2.1 |
+| `prompts` | object | built-in templates | Custom prompt template directory |
+| `ingest` | object | built-in defaults | Conversation-log ingestion |
+| `output_language_override` | string | `""` | Force summary/memory language; empty means auto-detect |
+| `allow_private_networks` | boolean | `false` | Allow fetching private-network resources |
+
+`auto_generate_l0`, `auto_generate_l1`, `default_search_mode`, and `default_search_limit` are deprecated compatibility fields. They are accepted when loading older configuration files but have no runtime effect.
+
+## Model Settings
+
+API-based `embedding`, `vlm`, `query_planner`, and `rerank` configurations reuse some field names, but each module has its own schema. Use only fields supported by the applicable module below.
+
+```json
+{
+ "embedding": {
+ "dense": {
+ "provider": "volcengine",
+ "model": "doubao-embedding-vision-251215",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "api_key": "<your-ark-api-key>",
+ "dimension": 1024,
+ "input": "multimodal"
+ }
+ },
+ "vlm": {
+ "provider": "volcengine",
+ "model": "doubao-seed-2-0-code-preview-260215",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "api_key": "<your-ark-api-key>",
+ "temperature": 0,
+ "max_retries": 3,
+ "thinking": false
+ },
+ "query_planner": {
+ "provider": "volcengine",
+ "model": "doubao-seed-2-0-code-preview-260215",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "api_key": "<your-ark-api-key>",
+ "thinking": false
+ },
+ "rerank": {
+ "provider": "vikingdb",
+ "ak": "<your-volcengine-ak>",
+ "sk": "<your-volcengine-sk>",
+ "host": "api-vikingdb.vikingdb.cn-beijing.volces.com",
+ "model_name": "doubao-seed-rerank",
+ "model_version": "251028",
+ "threshold": 0.1,
+ "max_input_tokens": 0
+ }
+}
+```
+
+| Field / path | Applies to | Purpose |
+|---|---|---|
+| `provider`, `model`, `api_base`, `api_key` | Embedding, VLM, Query Planner, Rerank | Model service, endpoint, and credential |
+| `api_version` | Embedding, VLM, Query Planner | API version for providers such as Azure |
+| `extra_headers` | Embedding, VLM, Query Planner, Rerank | Additional request headers |
+| `extra_request_body` | VLM, Query Planner | Additional completion request fields |
+| `extra_body` | `embedding.dense` / `sparse` / `hybrid` | Additional embedding request fields |
+| `timeout` | VLM, Query Planner, Rerank | Per-request timeout in seconds |
+| `embedding.max_retries`, `vlm.max_retries`, `query_planner.max_retries` | Embedding, VLM, Query Planner | Retry count; Rerank has no `max_retries` field |
+
+### `embedding.dense`
+
+| Field | Type / values | Purpose |
+|---|---|---|
+| `provider` | `openai`, `volcengine`, `azure`, `ollama`, `local`, etc. | Dense embedding service |
+| `dimension` | integer, `> 0` | Vector dimension; must match model output and existing collections |
+| `input` | `"text"` / `"multimodal"` | Input type |
+| `encoding_format` | `"float"` / `"base64"` | OpenAI-compatible vector encoding |
+
+Changing the model or `dimension` can make existing vector collections incompatible and may require migration or reindexing.
+
+### `rerank`
+
+| Field | Type / values | Default | Purpose |
+|---|---|---|---|
+| `provider` | `vikingdb`, `cohere`, `openai`, `litellm` / `null` | `null` | Rerank service; inferred from credentials when omitted |
+| `model` | string / `null` | `null` | OpenAI-compatible or LiteLLM rerank model |
+| `threshold` | number | `0.1` | Minimum score considered relevant |
+| `max_input_tokens` | integer; `0` or `>= 128` | `0` | Maximum estimated tokens per query-document pair; `0` disables truncation |
+
+Rerank has no separate `enabled` field. It becomes available when the required provider credentials are configured.
+
+## Retrieval Settings
+
+```json
+{
+ "retrieval": {
+ "hotness_alpha": 0,
+ "score_propagation_alpha": 1,
+ "enable_intent": true
+ }
+}
+```
+
+### `retrieval`
+
+| Field | Type / values | Default | Purpose |
+|---|---|---|---|
+| `hotness_alpha` | number, `0`–`1` | `0` | Hotness score weight; `0` disables it |
+| `score_propagation_alpha` | number, `0`–`1` | `1` | Child-result score weight in hierarchical retrieval |
+| `enable_intent` | boolean | `true` | Run intent analysis/query planning when `session_id` is present |
+
+Search and Find requests default to `limit: 10`; override the limit on each API or SDK request. `retrieval.enable_intent` controls LLM query planning for session-aware Search, while result reranking is enabled only when `rerank` has a usable provider configuration.
+
+## Storage Settings
+
+```json
+{
+ "storage": {
+ "workspace": "./data",
+ "skip_process_lock": false,
+ "agfs": {
+ "backend": "local"
+ },
+ "vectordb": {
+ "backend": "local"
+ }
+ }
+}
+```
+
+### `storage`
+
+| Field | Type / common values | Default | Purpose |
+|---|---|---|---|
+| `workspace` | path | `"./data"` | OpenViking workspace |
+| `agfs.backend` | `local`, `memory`, `s3` | `local` | File and metadata backend |
+| `vectordb.backend` | `local`, `cuvs`, `http`, `volcengine`, `vikingdb`, `qdrant`, `opengauss` | `local` | Vector database backend |
+| `vectordb.dimension` | integer | follows Embedding | Vector collection dimension |
+| `skip_process_lock` | boolean | `false` | Skip the workspace process lock; use only when accepting concurrent-write risk |
+
+Remote backends also require endpoint, bucket/collection, credentials, and timeout fields. See [Configuration](../guides/01-configuration.md#storage) for complete examples.
+
+## HTTP Server Settings
+
+```json
+{
+ "server": {
+ "host": "127.0.0.1",
+ "port": 1933,
+ "workers": 1,
+ "auth_mode": "dev",
+ "cors_origins": ["http://localhost:5173"],
+ "profile_enabled": false,
+ "temp_upload": {
+ "default_mode": "local"
+ }
+ }
+}
+```
+
+### `server`
+
+| Field | Type / values | Default | Purpose |
+|---|---|---|---|
+| `host` | IP / hostname | `"127.0.0.1"` | Listen address |
+| `port` | integer | `1933` | Listen port |
+| `workers` | integer | `1` | Worker process count |
+| `auth_mode` | `dev`, `api_key`, `trusted` / `null` | `null` | Auth mode; null is inferred from `root_api_key` |
+| `root_api_key` | string / `null` | `null` | Root key; setting it defaults auth to `api_key` |
+| `cors_origins` | string[] | `["*"]` | Allowed origins |
+| `profile_enabled` | boolean | `false` | Allow performance profiles |
+| `with_bot` | boolean | `false` | Enable the VikingBot API proxy |
+| `bot_api_url` | URL | `http://localhost:18790` | VikingBot OpenAPI endpoint |
+| `public_base_url` | URL / `null` | `null` | Externally visible base URL |
+| `upload_signed_ttl_seconds` | integer | `600` | Signed upload URL lifetime |
+| `temp_upload.default_mode` | `"local"` / `"shared"` | `"local"` | Temporary upload storage |
+
+### Encryption and API Key Hashing
+
+File encryption and API key hashing are configured in the top-level `encryption` section, not under `server`:
+
+```json
+{
+ "encryption": {
+ "enabled": false,
+ "api_key_hashing": {
+ "enabled": false
+ }
+ }
+}
+```
+
+| Field | Type / values | Default | Purpose |
+|---|---|---|---|
+| `encryption.enabled` | boolean | `false` | Enable file-level AES encryption |
+| `encryption.api_key_hashing.enabled` | boolean | `false` | Store API keys with Argon2id |
+
+See [Encryption](../guides/08-encryption.md) for provider and key-management settings.
+
+### Authentication Modes
+
+| Value | Use case |
+|---|---|
+| `dev` | Local-only development without API keys |
+| `api_key` | Validate root/user/admin keys |
+| `trusted` | Trust an upstream gateway to inject account/user identity |
+
+## Memory Settings
+
+```json
+{
+ "memory": {
+ "custom_templates_dir": "",
+ "experimental_memory_switch": false,
+ "eager_prefetch": true,
+ "prefetch_search_topn": 5,
+ "extraction_enabled": true,
+ "session_skill_extraction_enabled": false,
+ "link_enabled": false,
+ "v2_lock_retry_interval_seconds": 0.2,
+ "v2_lock_max_retries": 0
+ }
+}
+```
+
+### `memory`
+
+| Field | Type / values | Default | Purpose |
+|---|---|---|---|
+| `custom_templates_dir` | path | `""` | Additional memory template directory |
+| `experimental_memory_switch` | boolean | `false` | Enable experimental templates |
+| `eager_prefetch` | boolean | `true` | Search and read memories before extraction |
+| `prefetch_search_topn` | integer, `>= 1` | `5` | Results read during prefetch |
+| `extraction_enabled` | boolean | `true` | Extract long-term memories on session commit |
+| `session_skill_extraction_enabled` | boolean | `false` | Also extract reusable skills |
+| `link_enabled` | boolean | `false` | Generate and resolve memory links |
+| `v2_lock_retry_interval_seconds` | number, `>= 0` | `0.2` | Memory-lock retry interval |
+| `v2_lock_max_retries` | integer, `>= 0` | `0` | Retry limit; `0` means unlimited |
+
+## Parser Settings
+
+Parsers live under `parsers`:
+
+```json
+{
+ "parsers": {
+ "pdf": {},
+ "code": {
+ "code_summary_mode": "ast",
+ "extract_functions": true,
+ "extract_classes": true,
+ "max_token_limit": 50000
+ },
+ "image": {},
+ "audio": {},
+ "video": {},
+ "markdown": {},
+ "excel": {},
+ "html": {},
+ "text": {},
+ "directory": {},
+ "feishu": {
+ "domain": "https://open.feishu.cn",
+ "max_rows_per_sheet": 1000,
+ "max_records_per_table": 1000,
+ "download_images": true
+ },
+ "webfeed": {}
+ }
+}
+```
+
+| Setting | Purpose |
+|---|---|
+| `pdf` | PDF text, image, and layout parsing |
+| `code` | Repository file types, ignore rules, and network safety |
+| `image` | Image understanding and OCR |
+| `audio`, `video` | Audio/video parsing |
+| `markdown`, `html`, `text` | Text document chunking |
+| `excel` | Workbook parsing and chunking |
+| `directory` | Directory scanning and ignore rules |
+| `feishu` | Feishu/Lark access and parsing |
+| `webfeed` | Sitemap, RSS, and Atom ingestion |
+
+Provider-, parser-, storage-, and encryption-specific fields are documented in [Configuration](../guides/01-configuration.md).
+
+## Minimal Example
+
+```json
+{
+ "embedding": {
+ "dense": {
+ "provider": "volcengine",
+ "model": "doubao-embedding-vision-251215",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "api_key": "<your-ark-api-key>",
+ "dimension": 1024,
+ "input": "multimodal"
+ }
+ },
+ "vlm": {
+ "provider": "volcengine",
+ "model": "doubao-seed-2-0-code-preview-260215",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "api_key": "<your-ark-api-key>",
+ "thinking": false
+ },
+ "storage": {
+ "workspace": "./data"
+ },
+ "server": {
+ "host": "127.0.0.1",
+ "port": 1933
+ }
+}
+```
diff --git a/docs/en/configuration/02-client.md b/docs/en/configuration/02-client.md
new file mode 100644
index 000000000..da610cb37
--- /dev/null
+++ b/docs/en/configuration/02-client.md
@@ -0,0 +1,186 @@
+# ovcli Configuration
+
+`ovcli.conf` is the client configuration file for the `ov` CLI. It stores the server connection, authentication identity, and command defaults.
+
+Agent plugins for Codex, Claude Code, OpenCode, and other clients also read their own `OPENVIKING_*` environment variables for Recall, Capture, diagnostics, and other behavior. Those variables are not part of `ovcli.conf`; configure them in the corresponding [Agent Integration](../agent-integrations/01-overview.md) documentation.
+
+Use `ov config` to create and maintain configurations. Use `ov config show` to inspect the active configuration with secrets redacted.
+
+Default path:
+
+```text
+~/.openviking/ovcli.conf
+```
+
+To select another file:
+
+```bash
+export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf
+```
+
+## Complete Example
+
+```json
+{
+ "url": "https://openviking.example.com",
+ "api_key": "<user-or-admin-key>",
+ "root_api_key": "<root-key>",
+ "account": "acme",
+ "user": "alice",
+ "actor_peer_id": "agent:research-assistant",
+ "timeout": 60,
+ "output": "table",
+ "echo_command": true,
+ "show_progress": false,
+ "verbose": false,
+ "profile": false,
+ "upload": {
+ "ignore_dirs": "node_modules,.cache,dist",
+ "include": "*.md,*.pdf",
+ "exclude": "*.tmp,*.log"
+ },
+ "extra_headers": {
+ "X-Tenant": "acme"
+ },
+ "gateway_token": "<gateway-token>"
+}
+```
+
+Omit fields you do not need. A local server in `dev` mode usually needs only `url`.
+
+## Connection and Authentication
+
+```json
+{
+ "url": "https://openviking.example.com",
+ "api_key": "<user-or-admin-key>",
+ "root_api_key": "<root-key>",
+ "account": "acme",
+ "user": "alice",
+ "actor_peer_id": "agent:research-assistant",
+ "extra_headers": {
+ "X-Tenant": "acme"
+ },
+ "gateway_token": "<gateway-token>"
+}
+```
+
+| Field | Type / Values | Default | Purpose |
+|---|---|---|---|
+| `url` | HTTP(S) URL | `http://127.0.0.1:1933` | OpenViking server endpoint |
+| `api_key` | string / `null` | `null` | User/admin key for normal data operations |
+| `root_api_key` | string / `null` | `null` | Root key for `ov --sudo` administrative operations |
+| `account` | string / `null` | `null` | Account identity for trusted or root-key-only configurations |
+| `user` | string / `null` | `null` | User identity for trusted or root-key-only configurations |
+| `actor_peer_id` | string / `null` | `null` | Default Actor Peer identifier |
+| `agent_id` | string / `null` | `null` | Compatibility field; use `actor_peer_id` for new configs and do not set both |
+| `extra_headers` | object / `null` | `null` | Additional headers sent with every request; `extra_header` is a compatibility alias |
+| `gateway_token` | string / `null` | `null` | `X-Gateway-Token` used when retrying a gateway challenge |
+
+### Choosing API Keys
+
+| Configuration | Normal Commands | `ov --sudo` |
+|---|---|---|
+| `api_key` only | User/admin key | unavailable |
+| `root_api_key` plus `account` and `user` | Root key with explicit identity | Root key |
+| Both keys | `api_key` | `root_api_key` |
+| No keys | Local server with authentication disabled only | unavailable |
+
+`server.root_api_key` in `ov.conf` is accepted by the server. When the CLI manages that server, `root_api_key` in `ovcli.conf` must match it.
+
+## Command Behavior
+
+```json
+{
+ "timeout": 120,
+ "echo_command": true,
+ "show_progress": true,
+ "verbose": false,
+ "profile": false
+}
+```
+
+| Field | Type / Values | Default | Purpose |
+|---|---|---|---|
+| `timeout` | number, seconds, `> 0` | `60` | HTTP request timeout |
+| `echo_command` | boolean | `true` | Show effective request parameters for commands such as `find`, `search`, and `ls` |
+| `show_progress` | boolean | `false` | Show upload progress by default |
+| `verbose` | boolean | `false` | Show upload diagnostics by default |
+| `profile` | boolean | `false` | Request performance profiles; also requires `server.profile_enabled` |
+| `output` | `"table"` / `"json"` | `"table"` | Compatibility field; use `-o table` or `-o json` to select current command output |
+
+Command-line options such as `--profile`, `--progress`, `--no-progress`, and `--verbose` override the configuration for the current command.
+
+## Upload Filters
+
+```json
+{
+ "upload": {
+ "ignore_dirs": "node_modules,.cache,dist",
+ "include": "*.md,*.pdf",
+ "exclude": "*.tmp,*.log"
+ }
+}
+```
+
+| Field | Type / Format | Default | Purpose |
+|---|---|---|---|
+| `upload.ignore_dirs` | comma-separated string / `null` | `null` | Directory names to ignore |
+| `upload.include` | comma-separated globs / `null` | `null` | Upload only matching files |
+| `upload.exclude` | comma-separated globs / `null` | `null` | Exclude matching files |
+
+Local directory uploads also honor `.gitignore`. Command-line `--include` and `--exclude` rules are merged with the configuration.
+
+## Related Environment Variables
+
+The `ov` CLI directly uses only a small set of environment variables:
+
+| Environment Variable | Purpose |
+|---|---|
+| `OPENVIKING_CLI_CONFIG_FILE` | Select the `ovcli.conf` path |
+| `OPENVIKING_UPLOAD_MODE` | Select temporary upload mode: `local` or `shared` |
+
+The `--api-key-env <name>` and `--root-api-key-env <name>` options for `ov config add` and `ov config edit` read keys from a named environment variable and write them to the configuration.
+
+Variables such as `OPENVIKING_AUTO_RECALL`, `OPENVIKING_RECALL_LIMIT`, `OPENVIKING_AUTO_CAPTURE`, and `OPENVIKING_DEBUG` are read by Agent plugin processes and are not `ovcli.conf` fields.
+
+## Multiple Servers
+
+Normal `ov` commands, plus `ov config show` and `ov config validate`, resolve the effective configuration in this order:
+
+1. When `OPENVIKING_CLI_CONFIG_FILE` is set, that path is authoritative; a missing file is an error.
+2. When the variable is unset, the default active file:
+
+```text
+~/.openviking/ovcli.conf
+```
+
+The interactive manager and `ov config list`, `switch`, `add`, `edit`, and `delete` always manage the default store. Named configurations in that store live next to the default active file:
+
+```text
+~/.openviking/ovcli.conf.<name>
+```
+
+For example, a production configuration can contain:
+
+```json
+{
+ "url": "https://openviking.example.com",
+ "api_key": "<production-api-key>",
+ "timeout": 120
+}
+```
+
+Common commands:
+
+```bash
+ov config
+ov config list
+ov config switch <name>
+ov config validate
+ov config show
+```
+
+`ov config switch <name>` copies the named configuration to the default active file. If `OPENVIKING_CLI_CONFIG_FILE` remains set, normal `ov` commands continue to use the environment-selected file; unset it to use the switched default. New `ov` commands reread the effective file, while already-running Agent clients must restart before reading changes.
+
+See [OpenViking CLI Setup](../getting-started/05-cli-setup.md) for interactive and agent-assisted configuration workflows.
diff --git a/docs/zh/configuration/01-server.md b/docs/zh/configuration/01-server.md
new file mode 100644
index 000000000..f87bd22fe
--- /dev/null
+++ b/docs/zh/configuration/01-server.md
@@ -0,0 +1,373 @@
+# 服务端配置
+
+首次配置建议使用 `openviking-server init`,保存后运行 `openviking-server doctor`。
+
+OpenViking 服务端和 Python SDK 嵌入模式读取 `ov.conf`。默认路径是:
+
+```text
+~/.openviking/ov.conf
+```
+
+也可以通过环境变量或启动参数指定其他文件:
+
+```bash
+export OPENVIKING_CONFIG_FILE=/path/to/ov.conf
+openviking-server --config /path/to/ov.conf
+```
+
+服务端启动时读取配置。修改模型、检索、存储或 `server` 配置后,需要重启服务;重启后建议运行 `openviking-server doctor`。
+
+## 配置结构
+
+```json
+{
+ "embedding": {},
+ "vlm": {},
+ "query_planner": {},
+ "rerank": {},
+ "retrieval": {},
+ "storage": {},
+ "server": {},
+ "memory": {},
+ "parsers": {},
+ "encryption": {},
+ "log": {},
+ "telemetry": {}
+}
+```
+
+未配置的可选模块使用默认值。`ov.conf` 不允许未知字段,字段名写错时服务端会拒绝加载。
+
+## 顶层配置
+
+| 配置项 | 类型 / 可选值 | 默认值 | 作用 |
+|---|---|---|---|
+| `default_account` | string | `"default"` | SDK 嵌入模式使用的默认账号 |
+| `default_user` | string | `"default"` | SDK 嵌入模式使用的默认用户 |
+| `embedding` | object | 内置本地 Dense 模型 | 向量化模型和稀疏/混合检索配置;默认使用 `local` / `bge-small-zh-v1.5-f16` |
+| `vlm` | object | 空配置 | 内容理解、摘要和记忆抽取使用的模型;使用相关能力前需要配置可用模型 |
+| `query_planner` | object / `null` | `null` | 检索意图分析模型;未配置时回退到 `vlm` |
+| `rerank` | object | disabled | 检索结果重排模型 |
+| `retrieval` | object | 见下表 | 检索排序和意图分析策略 |
+| `grep` | object | 内置默认值 | 文本搜索引擎配置 |
+| `storage` | object | 本地存储 | 工作目录、文件系统和向量数据库 |
+| `server` | object | 本地开发模式 | HTTP 服务、鉴权、上传和可观测性 |
+| `memory` | object | 见下表 | 会话提交后的记忆与技能抽取 |
+| `parsers` | object | 各解析器默认值 | PDF、代码、图片、音视频等解析行为 |
+| `semantic` | object | 内置默认值 | abstract 和 overview 的生成限制 |
+| `parser_api` | object | disabled | 第三方文件解析 API |
+| `connector` | object | disabled | 外部 Connector 数据导入服务 |
+| `encryption` | object | disabled | 文件和敏感字段加密 |
+| `git` | object | local | 版本管理后端,可使用 `local` 或 `s3` |
+| `log` | object | 控制台日志 | 日志级别、格式和文件输出 |
+| `telemetry` | object | disabled | OpenTelemetry trace 上报 |
+| `oauth` | object | disabled | MCP OAuth 2.1 配置 |
+| `prompts` | object | 内置模板 | 自定义 Prompt 模板目录 |
+| `ingest` | object | 内置默认值 | 会话日志导入配置 |
+| `output_language_override` | string | `""` | 强制摘要和记忆输出语言;空值表示自动识别 |
+| `allow_private_networks` | boolean | `false` | 是否允许抓取内网或私有地址资源 |
+
+`auto_generate_l0`、`auto_generate_l1`、`default_search_mode` 和 `default_search_limit` 是已弃用的兼容字段。旧配置文件仍可加载这些字段,但它们不会影响运行时行为。
+
+## 模型配置
+
+API 型 `embedding`、`vlm`、`query_planner` 和 `rerank` 配置会复用部分字段名,但各模块使用独立 schema。请只使用下表中对应模块支持的字段。
+
+```json
+{
+ "embedding": {
+ "dense": {
+ "provider": "volcengine",
+ "model": "doubao-embedding-vision-251215",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "api_key": "<your-ark-api-key>",
+ "dimension": 1024,
+ "input": "multimodal"
+ }
+ },
+ "vlm": {
+ "provider": "volcengine",
+ "model": "doubao-seed-2-0-code-preview-260215",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "api_key": "<your-ark-api-key>",
+ "temperature": 0,
+ "max_retries": 3,
+ "thinking": false
+ },
+ "query_planner": {
+ "provider": "volcengine",
+ "model": "doubao-seed-2-0-code-preview-260215",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "api_key": "<your-ark-api-key>",
+ "thinking": false
+ },
+ "rerank": {
+ "provider": "vikingdb",
+ "ak": "<your-volcengine-ak>",
+ "sk": "<your-volcengine-sk>",
+ "host": "api-vikingdb.vikingdb.cn-beijing.volces.com",
+ "model_name": "doubao-seed-rerank",
+ "model_version": "251028",
+ "threshold": 0.1,
+ "max_input_tokens": 0
+ }
+}
+```
+
+| 字段 / 路径 | 适用模块 | 作用 |
+|---|---|---|
+| `provider`、`model`、`api_base`、`api_key` | Embedding、VLM、Query Planner、Rerank | 模型服务、地址和凭证 |
+| `api_version` | Embedding、VLM、Query Planner | Azure 等服务的 API 版本 |
+| `extra_headers` | Embedding、VLM、Query Planner、Rerank | 附加请求头 |
+| `extra_request_body` | VLM、Query Planner | 附加的 Completion 请求参数 |
+| `extra_body` | `embedding.dense` / `sparse` / `hybrid` | 附加的 Embedding 请求参数 |
+| `timeout` | VLM、Query Planner、Rerank | 单次请求超时,单位为秒 |
+| `embedding.max_retries`、`vlm.max_retries`、`query_planner.max_retries` | Embedding、VLM、Query Planner | 请求失败重试次数;Rerank 没有 `max_retries` 字段 |
+
+### `embedding.dense`
+
+| 字段 | 类型 / 可选值 | 作用 |
+|---|---|---|
+| `provider` | `openai`、`volcengine`、`azure`、`ollama`、`local` 等 | Dense Embedding 服务 |
+| `dimension` | integer,`> 0` | 向量维度,必须与模型输出及已有集合一致 |
+| `input` | `"text"` / `"multimodal"` | 输入类型 |
+| `encoding_format` | `"float"` / `"base64"` | OpenAI 兼容接口的向量编码格式 |
+
+更换模型或 `dimension` 可能与已有向量集合不兼容,需要迁移或重建索引。
+
+### `rerank`
+
+| 字段 | 类型 / 可选值 | 默认值 | 作用 |
+|---|---|---|---|
+| `provider` | `vikingdb`、`cohere`、`openai`、`litellm` / `null` | `null` | Rerank 服务类型;省略时根据凭证字段推断 |
+| `model` | string / `null` | `null` | OpenAI 兼容或 LiteLLM Rerank 模型 |
+| `threshold` | number | `0.1` | 判定结果相关的最低分数 |
+| `max_input_tokens` | integer;`0` 或 `>= 128` | `0` | 每个 query-document pair 的最大估算 token;`0` 表示不截断 |
+
+Rerank 没有单独的 `enabled` 字段;配置了对应 provider 所需的凭证后才会启用。
+
+## 检索配置
+
+```json
+{
+ "retrieval": {
+ "hotness_alpha": 0,
+ "score_propagation_alpha": 1,
+ "enable_intent": true
+ }
+}
+```
+
+### `retrieval`
+
+| 字段 | 类型 / 可选值 | 默认值 | 作用 |
+|---|---|---|---|
+| `hotness_alpha` | number,`0`–`1` | `0` | 热度分数权重;`0` 表示关闭热度加权 |
+| `score_propagation_alpha` | number,`0`–`1` | `1` | 层级检索时子结果自身分数的权重 |
+| `enable_intent` | boolean | `true` | 有 `session_id` 时是否进行意图分析和查询规划 |
+
+Search 和 Find 请求的默认 `limit` 为 `10`,可以在每次 API 或 SDK 请求中覆盖。`retrieval.enable_intent` 控制带 Session 的 Search 是否执行 LLM 查询规划;只有配置了可用的 `rerank` provider 时才会执行结果重排。
+
+## 存储配置
+
+```json
+{
+ "storage": {
+ "workspace": "./data",
+ "skip_process_lock": false,
+ "agfs": {
+ "backend": "local"
+ },
+ "vectordb": {
+ "backend": "local"
+ }
+ }
+}
+```
+
+### `storage`
+
+| 字段 | 类型 / 常用值 | 默认值 | 作用 |
+|---|---|---|---|
+| `workspace` | path | `"./data"` | OpenViking 工作目录 |
+| `agfs.backend` | `local`、`memory`、`s3` | `local` | 文件与元数据存储后端 |
+| `vectordb.backend` | `local`、`cuvs`、`http`、`volcengine`、`vikingdb`、`qdrant`、`opengauss` | `local` | 向量数据库后端 |
+| `vectordb.dimension` | integer | 跟随 Embedding | 向量集合维度 |
+| `skip_process_lock` | boolean | `false` | 是否跳过 workspace 进程锁;仅在明确接受并发写风险时启用 |
+
+远程存储后端还需要配置 endpoint、bucket/collection、鉴权和超时等字段。完整后端示例见[配置指南](../guides/01-configuration.md#storage)。
+
+## HTTP 服务配置
+
+```json
+{
+ "server": {
+ "host": "127.0.0.1",
+ "port": 1933,
+ "workers": 1,
+ "auth_mode": "dev",
+ "cors_origins": ["http://localhost:5173"],
+ "profile_enabled": false,
+ "temp_upload": {
+ "default_mode": "local"
+ }
+ }
+}
+```
+
+### `server`
+
+| 字段 | 类型 / 可选值 | 默认值 | 作用 |
+|---|---|---|---|
+| `host` | IP / hostname | `"127.0.0.1"` | HTTP 监听地址 |
+| `port` | integer | `1933` | HTTP 监听端口 |
+| `workers` | integer | `1` | 服务进程数量 |
+| `auth_mode` | `dev`、`api_key`、`trusted` / `null` | `null` | 鉴权模式;空值根据 `root_api_key` 自动判断 |
+| `root_api_key` | string / `null` | `null` | Root API Key;配置后默认启用 `api_key` 模式 |
+| `cors_origins` | string[] | `["*"]` | 允许的跨域来源 |
+| `profile_enabled` | boolean | `false` | 是否允许请求返回性能 profile |
+| `with_bot` | boolean | `false` | 是否启用 VikingBot API 代理 |
+| `bot_api_url` | URL | `http://localhost:18790` | VikingBot OpenAPI 地址 |
+| `public_base_url` | URL / `null` | `null` | 外部访问使用的服务基准地址 |
+| `upload_signed_ttl_seconds` | integer | `600` | 签名上传 URL 有效期 |
+| `temp_upload.default_mode` | `"local"` / `"shared"` | `"local"` | 临时上传存储模式 |
+
+### 文件加密与 API Key 哈希
+
+文件加密和 API Key 哈希在顶层 `encryption` 中配置,不属于 `server`:
+
+```json
+{
+ "encryption": {
+ "enabled": false,
+ "api_key_hashing": {
+ "enabled": false
+ }
+ }
+}
+```
+
+| 字段 | 类型 / 可选值 | 默认值 | 作用 |
+|---|---|---|---|
+| `encryption.enabled` | boolean | `false` | 是否启用文件级 AES 加密 |
+| `encryption.api_key_hashing.enabled` | boolean | `false` | 是否使用 Argon2id 保存 API Key |
+
+Provider 和密钥管理配置见[加密指南](../guides/08-encryption.md)。
+
+### 鉴权模式
+
+| 值 | 使用场景 |
+|---|---|
+| `dev` | 仅监听本机地址的开发环境,不要求 API Key |
+| `api_key` | 服务端校验 root/user/admin key |
+| `trusted` | 由受信任网关注入 account/user 身份 |
+
+## 记忆配置
+
+```json
+{
+ "memory": {
+ "custom_templates_dir": "",
+ "experimental_memory_switch": false,
+ "eager_prefetch": true,
+ "prefetch_search_topn": 5,
+ "extraction_enabled": true,
+ "session_skill_extraction_enabled": false,
+ "link_enabled": false,
+ "v2_lock_retry_interval_seconds": 0.2,
+ "v2_lock_max_retries": 0
+ }
+}
+```
+
+### `memory`
+
+| 字段 | 类型 / 可选值 | 默认值 | 作用 |
+|---|---|---|---|
+| `custom_templates_dir` | path | `""` | 附加的自定义记忆模板目录 |
+| `experimental_memory_switch` | boolean | `false` | 是否启用实验性记忆模板 |
+| `eager_prefetch` | boolean | `true` | 是否在抽取前预取并读取记忆内容 |
+| `prefetch_search_topn` | integer,`>= 1` | `5` | 预取时读取的检索结果数量 |
+| `extraction_enabled` | boolean | `true` | session commit 时是否抽取长期记忆 |
+| `session_skill_extraction_enabled` | boolean | `false` | 是否同时抽取可复用 Skill |
+| `link_enabled` | boolean | `false` | 是否生成和解析记忆链接 |
+| `v2_lock_retry_interval_seconds` | number,`>= 0` | `0.2` | 记忆锁获取失败后的重试间隔 |
+| `v2_lock_max_retries` | integer,`>= 0` | `0` | 最大重试次数;`0` 表示不限次数 |
+
+## 解析器配置
+
+解析器放在 `parsers` 下:
+
+```json
+{
+ "parsers": {
+ "pdf": {},
+ "code": {
+ "code_summary_mode": "ast",
+ "extract_functions": true,
+ "extract_classes": true,
+ "max_token_limit": 50000
+ },
+ "image": {},
+ "audio": {},
+ "video": {},
+ "markdown": {},
+ "excel": {},
+ "html": {},
+ "text": {},
+ "directory": {},
+ "feishu": {
+ "domain": "https://open.feishu.cn",
+ "max_rows_per_sheet": 1000,
+ "max_records_per_table": 1000,
+ "download_images": true
+ },
+ "webfeed": {}
+ }
+}
+```
+
+| 配置项 | 作用 |
+|---|---|
+| `pdf` | PDF 文本、图片和版面解析 |
+| `code` | 代码仓库文件类型、忽略规则和安全限制 |
+| `image` | 图片理解和 OCR |
+| `audio`、`video` | 音视频内容解析 |
+| `markdown`、`html`、`text` | 文本文档分段 |
+| `excel` | Excel 工作表解析与分段 |
+| `directory` | 目录扫描和忽略规则 |
+| `feishu` | 飞书文档访问与解析 |
+| `webfeed` | Sitemap、RSS 和 Atom 导入 |
+
+各模型 provider、解析器、存储后端和加密后端包含较多专用字段,完整字段表和配置示例见[配置指南](../guides/01-configuration.md)。
+
+## 最小示例
+
+```json
+{
+ "embedding": {
+ "dense": {
+ "provider": "volcengine",
+ "model": "doubao-embedding-vision-251215",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "api_key": "<your-ark-api-key>",
+ "dimension": 1024,
+ "input": "multimodal"
+ }
+ },
+ "vlm": {
+ "provider": "volcengine",
+ "model": "doubao-seed-2-0-code-preview-260215",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "api_key": "<your-ark-api-key>",
+ "thinking": false
+ },
+ "storage": {
+ "workspace": "./data"
+ },
+ "server": {
+ "host": "127.0.0.1",
+ "port": 1933
+ }
+}
+```
diff --git a/docs/zh/configuration/02-client.md b/docs/zh/configuration/02-client.md
new file mode 100644
index 000000000..a147aef81
--- /dev/null
+++ b/docs/zh/configuration/02-client.md
@@ -0,0 +1,186 @@
+# ovcli 配置
+
+`ovcli.conf` 是 `ov` CLI 的客户端配置文件,用于保存服务端连接、鉴权身份和命令默认行为。
+
+Codex、Claude Code、OpenCode 等 Agent 插件还会读取各自的 `OPENVIKING_*` 环境变量,用于控制 Recall、Capture、调试等行为;这些不属于 `ovcli.conf`,请在对应的 [Agent 集成](../agent-integrations/01-overview.md)文档中配置。
+
+建议使用 `ov config` 创建和维护配置;使用 `ov config show` 查看脱敏后的当前配置。
+
+默认路径:
+
+```text
+~/.openviking/ovcli.conf
+```
+
+也可以指定其他文件:
+
+```bash
+export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf
+```
+
+## 完整示例
+
+```json
+{
+ "url": "https://openviking.example.com",
+ "api_key": "<user-or-admin-key>",
+ "root_api_key": "<root-key>",
+ "account": "acme",
+ "user": "alice",
+ "actor_peer_id": "agent:research-assistant",
+ "timeout": 60,
+ "output": "table",
+ "echo_command": true,
+ "show_progress": false,
+ "verbose": false,
+ "profile": false,
+ "upload": {
+ "ignore_dirs": "node_modules,.cache,dist",
+ "include": "*.md,*.pdf",
+ "exclude": "*.tmp,*.log"
+ },
+ "extra_headers": {
+ "X-Tenant": "acme"
+ },
+ "gateway_token": "<gateway-token>"
+}
+```
+
+不需要的字段可以省略。本地 `dev` 模式通常只需要 `url`。
+
+## 连接与鉴权
+
+```json
+{
+ "url": "https://openviking.example.com",
+ "api_key": "<user-or-admin-key>",
+ "root_api_key": "<root-key>",
+ "account": "acme",
+ "user": "alice",
+ "actor_peer_id": "agent:research-assistant",
+ "extra_headers": {
+ "X-Tenant": "acme"
+ },
+ "gateway_token": "<gateway-token>"
+}
+```
+
+| 字段 | 类型 / 可选值 | 默认值 | 作用 |
+|---|---|---|---|
+| `url` | HTTP(S) URL | `http://127.0.0.1:1933` | OpenViking 服务端地址 |
+| `api_key` | string / `null` | `null` | 普通数据操作使用的 user/admin key |
+| `root_api_key` | string / `null` | `null` | `ov --sudo` 管理操作使用的 root key |
+| `account` | string / `null` | `null` | trusted 模式或 root-key-only 配置使用的账号身份 |
+| `user` | string / `null` | `null` | trusted 模式或 root-key-only 配置使用的用户身份 |
+| `actor_peer_id` | string / `null` | `null` | 默认 Actor Peer 标识 |
+| `agent_id` | string / `null` | `null` | 兼容字段;新配置使用 `actor_peer_id`,两者不能同时设置 |
+| `extra_headers` | object / `null` | `null` | 每个 HTTP 请求附加的自定义请求头;`extra_header` 是兼容别名 |
+| `gateway_token` | string / `null` | `null` | 网关挑战重试时使用的 `X-Gateway-Token` |
+
+### API Key 选择
+
+| 配置方式 | 普通命令 | `ov --sudo` |
+|---|---|---|
+| 仅 `api_key` | 使用 user/admin key | 不可用 |
+| 仅 `root_api_key`,并配置 `account`、`user` | 使用 root key 和显式身份 | 使用 root key |
+| 同时配置两种 key | 使用 `api_key` | 使用 `root_api_key` |
+| 两种 key 都不配置 | 仅适用于未开启鉴权的本地服务 | 不可用 |
+
+`ov.conf` 中的 `server.root_api_key` 是服务端接受的凭证;CLI 管理该服务端时,`ovcli.conf` 中的 `root_api_key` 需要与其一致。
+
+## 命令行为
+
+```json
+{
+ "timeout": 120,
+ "echo_command": true,
+ "show_progress": true,
+ "verbose": false,
+ "profile": false
+}
+```
+
+| 字段 | 类型 / 可选值 | 默认值 | 作用 |
+|---|---|---|---|
+| `timeout` | number,秒,`> 0` | `60` | HTTP 请求超时 |
+| `echo_command` | boolean | `true` | 是否显示 `find`、`search`、`ls` 等命令的实际请求参数 |
+| `show_progress` | boolean | `false` | 上传时是否默认显示进度 |
+| `verbose` | boolean | `false` | 上传时是否默认输出诊断信息 |
+| `profile` | boolean | `false` | 是否请求性能 profile;服务端还需启用 `server.profile_enabled` |
+| `output` | `"table"` / `"json"` | `"table"` | 兼容字段;当前命令使用 `-o table` 或 `-o json` 选择输出格式 |
+
+`--profile`、`--progress`、`--no-progress`、`--verbose` 等命令行参数会覆盖本次命令的配置。
+
+## 上传过滤
+
+```json
+{
+ "upload": {
+ "ignore_dirs": "node_modules,.cache,dist",
+ "include": "*.md,*.pdf",
+ "exclude": "*.tmp,*.log"
+ }
+}
+```
+
+| 字段 | 类型 / 格式 | 默认值 | 作用 |
+|---|---|---|---|
+| `upload.ignore_dirs` | 逗号分隔字符串 / `null` | `null` | 忽略的目录名 |
+| `upload.include` | 逗号分隔 glob / `null` | `null` | 只上传匹配的文件 |
+| `upload.exclude` | 逗号分隔 glob / `null` | `null` | 排除匹配的文件 |
+
+本地目录上传还会遵循 `.gitignore`。命令行 `--include`、`--exclude` 会与配置文件中的规则合并。
+
+## 相关环境变量
+
+`ov` CLI 直接使用的环境变量只有少量几个:
+
+| 环境变量 | 作用 |
+|---|---|
+| `OPENVIKING_CLI_CONFIG_FILE` | 指定要读取的 `ovcli.conf` 路径 |
+| `OPENVIKING_UPLOAD_MODE` | 指定临时上传模式:`local` 或 `shared` |
+
+`ov config add` 和 `ov config edit` 的 `--api-key-env <变量名>`、`--root-api-key-env <变量名>` 可以从指定环境变量读取密钥,并写入配置文件。
+
+Agent 插件使用的 `OPENVIKING_AUTO_RECALL`、`OPENVIKING_RECALL_LIMIT`、`OPENVIKING_AUTO_CAPTURE`、`OPENVIKING_DEBUG` 等变量由插件进程读取,不是 `ovcli.conf` 字段。
+
+## 多服务配置
+
+普通 `ov` 命令以及 `ov config show`、`ov config validate` 按以下顺序解析实际配置:
+
+1. 设置 `OPENVIKING_CLI_CONFIG_FILE` 后,该路径具有最高优先级;文件不存在时会直接报错。
+2. 未设置该变量时,使用默认 Active 文件:
+
+```text
+~/.openviking/ovcli.conf
+```
+
+交互式管理器以及 `ov config list`、`switch`、`add`、`edit`、`delete` 始终管理默认配置仓库。该仓库中的命名配置与默认 Active 文件位于同一目录:
+
+```text
+~/.openviking/ovcli.conf.<name>
+```
+
+例如,一份生产环境配置可以写成:
+
+```json
+{
+ "url": "https://openviking.example.com",
+ "api_key": "<production-api-key>",
+ "timeout": 120
+}
+```
+
+常用命令:
+
+```bash
+ov config
+ov config list
+ov config switch <name>
+ov config validate
+ov config show
+```
+
+`ov config switch <name>` 会把命名配置复制为默认 Active 文件。如果仍设置了 `OPENVIKING_CLI_CONFIG_FILE`,普通 `ov` 命令会继续读取环境变量指定的文件;需要取消该变量后才会使用刚切换的默认配置。新的 `ov` 命令会重新读取实际配置文件;已经运行的 Agent 客户端需要重启后才会读取变更。
+
+交互式配置和 Agent 辅助配置步骤见[OpenViking CLI 配置指南](../getting-started/05-cli-setup.md)。