Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: add server and client configuration reference (#3651)
yufeng9c9a29462ac6
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex 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): DefaultThreturn { 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.cssindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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)。