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: align authentication, tenancy and privacy guidance with the server (#5505)
Zayn Jarvisfa4fc64e7092
diff --git a/docs/en/api/08-admin.md b/docs/en/api/08-admin.mdindex c39346362..e73673263 100644--- a/docs/en/api/08-admin.md+++ b/docs/en/api/08-admin.md@@ -38,8 +38,7 @@ Configure `root_api_key` in `~/.openviking/ovcli.conf`:{"url": "http://localhost:1933","api_key": "alice-user-key",- "root_api_key": "your-root-api-key",- ...+ "root_api_key": "your-root-api-key"}```@@ -48,7 +47,7 @@ Configure `root_api_key` in `~/.openviking/ovcli.conf`:- `ov --sudo admin` - Account and user management- `ov --sudo system` - System utility commands- `ov --sudo reindex` - Rebuild indexes-- `ov --sudo admin migrate` - Legacy agent/session migration and cleanup+- `ov --sudo admin migrate` - Legacy session migration and cleanup- `ov --sudo task status/list` - Query root/system background tasks, such as migration tasks### Usage Limitations@@ -171,6 +170,14 @@ whether the User is named `default`.| PUT | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | Complete and publish one template || DELETE | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | Remove that override and restore deployment defaults |+To update a template while keeping existing customizations:++1. GET the template and copy its `effective` object.+2. Edit the permitted descriptions or `content_template`, then PUT the complete object. Omitted values revert to deployment defaults.+3. Check the returned `status` and `effective` values. New extractions use the published template; existing memories are not immediately rewritten.++Use DELETE to restore deployment defaults for that type.+The kernel accepts the existing memory YAML structure as a JSON object and enforcesthe following editing allowlist at the API boundary. Only these six types areexposed. Experience, Cases, Trajectories and other types are not exposed for reading@@ -235,6 +242,8 @@ objects using YAML field names such as `fields[].type`. List returns`result.account_id` and `result.templates`; single-template operations return`result.account_id` plus the template result.+::: details Publication, storage, and concurrent extraction+Storage is per Account and per type:```text@@ -290,6 +299,8 @@ All eligible Users/Peers in that Account share the templates; no shared deploymeregistry is mutated. Publishing/resetting does not proactively rewrite existingmemories; subsequent commits can update them according to the effective rules.+:::+Editable descriptions and content templates must be nonempty strings;each serialized file is limited to 1 MiB. Descriptions (both type-level and`fields[].description`) share one restricted Jinja contract, whether they come@@ -300,9 +311,7 @@ Only the existing `language` context variable is available; body fields,the same as the restricted bodies below: conditionals, local variables, boundedliteral loops, safe string methods, approved string filters and tests, but no arbitrary calls.For example, <code v-pre>Use {{ language.upper() }}.</code> renders as `Use EN.` when the existing-schema-rendering context supplies `language=en`. No new language propagation is-introduced; the Python protocol's existing static field-description path remains-unchanged. Missing language retains the previous undefined/empty-output behavior;+schema-rendering context supplies `language=en`. Rendering uses the language supplied by the calling path; both Python and JSON protocols render field descriptions with that context. Missing language retains the previous undefined/empty-output behavior;use `language or 'English'` for a fallback. Context values are not recursivelyevaluated as Jinja. Invalid custom expressions are rejected before publication,and persisted overrides are revalidated before extraction. Deployment descriptions@@ -316,8 +325,7 @@ including whitespace and template-like text. This is a per-field source-charactenot a UTF-8 byte, rendered-output or combined-description limit. Oversized updatesreturn 400 without modifying the active configuration. Publication does not invokean LLM. Storage failures/corrupt files-are reported, not silently treated as defaults. This change adds no public-file-browser directory, SDK/CLI commands, drafts or version-history UI.+are reported, not silently treated as defaults. These endpoints have no SDK/CLI wrappers. Use the HTTP API to read, publish, or reset templates.#### Managed content-template contract@@ -420,6 +428,12 @@ active configuration remains unchanged. Structurally valid older overrides usingunsupported Jinja can still be read, replaced or reset, but extraction refuses toexecute them unchecked. Corrupt YAML remains an explicit error.+For example, this `events` PUT body shows only the event name and summary, without ChatLog:++```json+{"content_template": "# {{ event_name.strip() }}\n\n## Summary\n{{ summary.strip() or 'Pending' }}"}+```+### Runtime ConfigurationROOT can manage Cluster configuration and any Account configuration. ADMIN can@@ -875,7 +889,7 @@ Create a new workspace with its first admin user.**Notes:**- In `trusted` mode, `user_key` is omitted from the response-- Omit `seed` for the default random API key. Treat seed values as secret material; short seeds can make the key guessable.+- Omit `seed` for the default random API key. Set `OV_KEY_SEED` to a securely generated secret before running a deterministic example; the Go example also requires `import "os"`. Short or predictable seeds make the key guessable.- `settings` receives structural and effective Embedding/VectorDB pair validation before the Account and its directories are created. A failed validation leaves no Account, user, or configuration file.- Account `vlm`, `query_planner`, `embedding`, and `vectordb` are ROOT-only. See [Account Configuration Reference](#account-configuration-reference) above for their schema, lifecycle, and validation. The current Python SDK, CLI, and other SDK Account-creation wrappers do not expose a `settings` argument; use the HTTP API for this capability.- Account-level namespace isolation settings are no longer supported. User memory uses user-scoped namespaces, and one-to-many external participants are represented with `peer_id`.@@ -897,8 +911,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \-H "X-API-Key: <root-key>" \-d '{"account_id": "acme",- "admin_user_id": "alice",- "seed": "alice-seed"+ "admin_user_id": "alice"}'```@@ -935,31 +948,9 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \}'```-**Trusted mode (registered gateway user)**+**Trusted mode**-```bash-# First, register the gateway admin user in api_key mode-curl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "Content-Type: application/json" \- -H "X-API-Key: <root-key>" \- -d '{- "account_id": "platform",- "admin_user_id": "gateway-admin"- }'--# Then use it in trusted mode; admin authorization comes from root_api_key-curl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "Content-Type: application/json" \- -H "X-API-Key: <root-key>" \- -H "X-OpenViking-Account: platform" \- -H "X-OpenViking-User: gateway-admin" \- -d '{- "account_id": "acme",- "admin_user_id": "alice"- }'-```--**Trusted mode (root fallback without identity headers)**+With `server.root_api_key` configured, use the root key for Admin API requests. No gateway-user registration or switch to `api_key` mode is required. Omit identity headers for these requests to avoid a mismatch with the target account or user in the URL.```bashcurl -X POST http://localhost:1933/api/v1/admin/accounts \@@ -982,7 +973,6 @@ client.initialize()result = client.admin_create_account(account_id="acme",admin_user_id="alice",- seed="alice-seed",)print(f"Account created: {result['account_id']}")print(f"Admin user: {result['admin_user_id']}")@@ -1015,7 +1005,7 @@ if err != nil {}fmt.Println(result["account_id"])-seed := "alice-seed"+seed := os.Getenv("OV_KEY_SEED")result, err = client.AdminCreateAccountWithOptions(ctx, "acme-private", "alice", &openviking.AdminCreateAccountOptions{Seed: &seed,UserConfig: map[string]any{@@ -1032,7 +1022,7 @@ result, err = client.AdminCreateAccountWithOptions(ctx, "acme-private", "alice",```bash# Requires ROOT privileges, use --sudoov --sudo admin create-account acme --admin alice-ov --sudo admin create-account acme --admin alice --seed alice-seed+ov --sudo admin create-account acme --admin alice --seed "$OV_KEY_SEED"ov --sudo admin create-account acme-private --admin alice \--user-config-json '{"add_targets":{"resource_uri":"viking://~/resources","skill_uri":"viking://~/skills"}}'@@ -1298,7 +1288,7 @@ Register a new user in a workspace.**Notes:**- In `trusted` mode, `user_key` is omitted from the response-- Omit `seed` for the default random API key. Treat seed values as secret material; short seeds can make the key guessable.+- Omit `seed` for the default random API key. Set `OV_KEY_SEED` to a securely generated secret before running a deterministic example; the Go example also requires `import "os"`. Short or predictable seeds make the key guessable.- ADMIN can only register users in their own account- The `"root"` role cannot be minted through user registration- `user_config.add_targets.resource_uri` must be a writable resource directory URI: `viking://resources` or `viking://resources/...`, `viking://~/resources` or `viking://~/resources/...`, `viking://user/{user_id}/resources` or `viking://user/{user_id}/resources/...`, or `viking://user/{user_id}/peers/{peer_id}/resources` or `viking://user/{user_id}/peers/{peer_id}/resources/...`.@@ -1319,8 +1309,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users \-H "X-API-Key: <root-or-admin-key>" \-d '{"user_id": "bob",- "role": "user",- "seed": "bob-seed"+ "role": "user"}'```@@ -1336,7 +1325,6 @@ result = client.admin_register_user(account_id="acme",user_id="bob",role="user",- seed="bob-seed",)print(f"User registered: {result['user_id']}")print(f"User key: {result.get('user_key', '(not exposed in trusted mode)')}")@@ -1364,7 +1352,7 @@ if err != nil {}fmt.Println(result["user_id"])-seed := "bob-seed"+seed := os.Getenv("OV_KEY_SEED")result, err = client.AdminRegisterUserWithOptions(ctx, "acme", "bob-private", "user", &openviking.AdminRegisterUserOptions{Seed: &seed,UserConfig: map[string]any{@@ -1379,7 +1367,7 @@ result, err = client.AdminRegisterUserWithOptions(ctx, "acme", "bob-private", "u# Either ROOT or account ADMIN can execute# If using regular user's api_key who is an ADMIN of acme:ov admin register-user acme bob --role user-ov admin register-user acme bob --role user --seed bob-seed+ov admin register-user acme bob --role user --seed "$OV_KEY_SEED"# If using root_api_key (--sudo):ov --sudo admin register-user acme bob --role user@@ -1429,6 +1417,8 @@ List active users in a workspace. Users with deletion in progress are omitted.| account_id | str | Yes | - | Workspace ID || name | str | No | null | Filter by user ID (wildcard `*` and `?` matching) || role | str | No | null | Filter by role |+| query | str | No | null | HTTP-only, case-insensitive literal substring match on user IDs |+| include_summary | bool | No | false | HTTP-only, return paginated users and account statistics in an object || include_credentials | bool | No | true | HTTP-only. Set false to return `user_id`, `role`, and `api_key_available` without credentials or key prefixes. The default preserves the existing mode-dependent response. || limit | int | No | null | Page size (≥1). Omit to return all matches || page | int | No | 1 | 1-based page number; only applies when `limit` is set |@@ -1702,7 +1692,7 @@ fmt.Println(result["role"])**CLI**```bash-# Requires ROOT privileges, use --sudo+# ROOT example; an acme ADMIN can use `ov admin set-role` without --sudoov --sudo admin set-role acme bob admin```@@ -1725,12 +1715,12 @@ ov --sudo admin set-role acme bob admin#### 1. API Implementation Overview-Regenerate a user's API key. The old key is immediately invalidated.+Generate and store a user API key. With the default random generation, the old key stops working after a successful update. Reusing the same account, user, and seed reproduces the same key; choose a new seed or omit it when rotating credentials.**Processing Flow:**1. Verify requester has ROOT privileges or is an ADMIN of the account2. Call API Key Manager to regenerate user key-3. Old key is immediately invalidated+3. With random generation or a new seed, the old key stops working immediately4. Return new user key**Code Entry Points:**@@ -1750,8 +1740,8 @@ Regenerate a user's API key. The old key is immediately invalidated.**Notes:**- ADMIN can only regenerate keys for users in their own account-- Old key is immediately invalidated, clients using it need to be updated-- Omit `seed` for the default random regenerated key.+- With random generation or a new seed, the old key stops working immediately; update clients that use it+- Omit `seed` for the default random regenerated key. Deterministic examples use `OV_KEY_SEED` or `OV_NEW_KEY_SEED`; set these to a securely generated secret before use. In Go, import `os`. Do not use the example variable names as seed values.#### 3. Usage Examples@@ -1765,7 +1755,7 @@ POST /api/v1/admin/accounts/{account_id}/users/{user_id}/keycurl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users/bob/key \-H "Content-Type: application/json" \-H "X-API-Key: <root-or-admin-key>" \- -d '{"seed": "bob-new-seed"}'+ -d '{}'```**Python SDK**@@ -1779,7 +1769,6 @@ client.initialize()result = client.admin_regenerate_key(account_id="acme",user_id="bob",- seed="bob-new-seed",)print(f"New user key: {result['user_key']}")```@@ -1799,7 +1788,7 @@ if err != nil {}fmt.Println(result["user_key"])-seed := "bob-new-seed"+seed := os.Getenv("OV_NEW_KEY_SEED")result, err = client.AdminRegenerateKeyWithOptions(ctx, "acme", "bob", &openviking.AdminRegenerateKeyOptions{Seed: &seed,})@@ -1811,7 +1800,7 @@ result, err = client.AdminRegenerateKeyWithOptions(ctx, "acme", "bob", &openviki# Either ROOT or account ADMIN can execute# If using regular user's api_key who is an ADMIN of acme:ov admin regenerate-key acme bob-ov admin regenerate-key acme bob --seed bob-new-seed+ov admin regenerate-key acme bob --seed "$OV_NEW_KEY_SEED"# If using root_api_key (--sudo):ov --sudo admin regenerate-key acme bob```@@ -1889,7 +1878,7 @@ curl -X POST http://localhost:1933/api/v1/admin/migrate \-H "X-API-Key: <root-key>" \-d '{"action": "migrate"}'-# Clean old namespaces+# Clean old namespaces after the migration task finishes and migrated data is verifiedcurl -X POST http://localhost:1933/api/v1/admin/migrate \-H "Content-Type: application/json" \-H "X-API-Key: <root-key>" \@@ -1924,14 +1913,16 @@ fmt.Println(result["task_id"])```bashov --sudo admin migrate --output json+# Check the returned task with ov --sudo task status <task_id>, then verify migrated data.ov --sudo admin migrate --cleanup --output json```-**Response Example**+**CLI Response Example (default compact output)**```json{- "task_id": "legacy_migration_..."+ "ok": true,+ "result": {"task_id": "6de05fc3-0334-40d6-ba9b-dd317eb4d351"}}```@@ -1943,6 +1934,8 @@ ov --sudo admin migrate --cleanup --output json### Typical Admin Workflow+This example includes user and account deletion. Run it only against a disposable workspace; omit the deletion steps when onboarding real users.+```bash# Step 1: ROOT creates workspace with alice as first admin (requires --sudo)ov --sudo admin create-account acme --admin alicediff --git a/docs/en/api/10-privacy.md b/docs/en/api/10-privacy.mdindex a2b4d4180..5338c4433 100644--- a/docs/en/api/10-privacy.md+++ b/docs/en/api/10-privacy.md@@ -2,7 +2,11 @@Privacy configs manage sensitive values by `category + target_key` (for example, a skill's `api_key` and `base_url`).-Each update creates a version snapshot. You can query history and switch the active version.+Changed values create a version snapshot. You can query history and switch the active version. Submitting the same values as the current version does not create a new version.++These examples use the current user’s API key. In trusted mode, supply the identity headers required by your deployment. Reads and CLI output contain the stored values; `***` below is an example placeholder, not automatic redaction.++Activating a version changes only the values stored in OpenViking. It does not rotate, revoke, or restore credentials at the external provider.## Endpoint Summary@@ -16,8 +20,6 @@ Each update creates a version snapshot. You can query history and switch the act| GET | `/api/v1/privacy-configs/{category}/{target_key}/versions/{version}` | Get a specific version snapshot || POST | `/api/v1/privacy-configs/{category}/{target_key}/activate` | Activate a specific version |-Detailed sections are below.----## Common Use Cases@@ -82,9 +84,7 @@ GET /api/v1/privacy-configs```bashcurl -X GET http://localhost:1933/api/v1/privacy-configs \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice"+ -H "X-API-Key: your-key"```**Response**@@ -110,9 +110,7 @@ GET /api/v1/privacy-configs/{category}```bashcurl -X GET http://localhost:1933/api/v1/privacy-configs/skill \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice"+ -H "X-API-Key: your-key"```**Response**@@ -138,9 +136,7 @@ GET /api/v1/privacy-configs/{category}/{target_key}```bashcurl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase" \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice"+ -H "X-API-Key: your-key"```**Response**@@ -178,7 +174,7 @@ Write a new version and set it as active.**Behavior**-- `values` is written as a full snapshot for that version+- `values` replaces the complete value map for that version; omitted keys are absent from the new snapshot- New keys are allowed and persisted- If `values` is identical to the current version, no new version is created@@ -200,8 +196,6 @@ POST /api/v1/privacy-configs/{category}/{target_key}curl -X POST "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase" \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice" \-d '{"values": {"api_key": "secret-2",@@ -248,9 +242,7 @@ GET /api/v1/privacy-configs/{category}/{target_key}/versions```bashcurl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/versions" \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice"+ -H "X-API-Key: your-key"```**Response**@@ -278,9 +270,7 @@ GET /api/v1/privacy-configs/{category}/{target_key}/versions/{version}```bashcurl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/versions/2" \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice"+ -H "X-API-Key: your-key"```**Response**@@ -324,8 +314,6 @@ POST /api/v1/privacy-configs/{category}/{target_key}/activatecurl -X POST "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/activate" \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice" \-d '{"version": 2}'```@@ -365,6 +353,9 @@ ov privacy skill byted-viking-search-knowledgebaseov privacy upsert skill byted-viking-search-knowledgebase \--values-json '{"api_key":"secret-2","base_url":"https://example.com"}'+# Read values from a local JSON file instead of command arguments+ov privacy upsert skill byted-viking-search-knowledgebase --values-file ./privacy-values.json+# Partial key update (CLI merges with current first)ov privacy upsert skill byted-viking-search-knowledgebase \--key-api_key secret-3diff --git a/docs/en/concepts/11-multi-tenant.md b/docs/en/concepts/11-multi-tenant.mdindex 19026a98a..4bc2acc05 100644--- a/docs/en/concepts/11-multi-tenant.md+++ b/docs/en/concepts/11-multi-tenant.md@@ -1,6 +1,6 @@# Multi-Tenant-OpenViking multi-tenancy does not mean "deploy one isolated server per team." Instead, a single OpenViking Server uses `account` and `user` identity boundaries to control sharing and isolation.+OpenViking multi-tenancy does not mean "deploy one isolated server per team." A single OpenViking Server uses `account` and `user` identity boundaries to control data sharing and isolation.This model fits two common scenarios:@@ -40,7 +40,7 @@ With multi-tenancy enabled, you can:| Role | Scope | Typical capabilities ||------|-------|----------------------|-| ROOT | Global | Create/delete accounts, cross-tenant access, user management |+| ROOT | Global | Create/delete accounts and manage users; not used for tenant data access in API key mode || ADMIN | Single account | Manage users in the same account, regenerate user keys || USER | Single account | Access its own user/peer/session data and shared resources in the same account |@@ -57,7 +57,7 @@ In trusted mode, an upstream gateway may also assert `X-OpenViking-Role: user` o### What `root_api_key` Does-Once `server.root_api_key` is configured, OpenViking enters formal multi-tenant mode:+In `api_key` mode, configuring `server.root_api_key` enables key-based account and user management:- The root key manages accounts and users- User keys are generated by the Admin API for normal data access@@ -79,7 +79,8 @@ If `auth_mode = "api_key"` and `root_api_key` is not configured, the server runs| User resources (`viking://user/{user_id}/resources`) | No | No | user || Peer resources (`viking://user/{user_id}/peers/{peer_id}/resources`) | No | No | user / peer || Memories | No | No | user / peer |-| Skills | No | No | user |+| Private skills (`viking://user/{user_id}/skills`) | No | No | user |+| Shared skills (`viking://agent/skills`) | No | Yes, subject to access permissions | account || Sessions | No | No | user / session |### Storage Layer@@ -109,9 +110,9 @@ So multi-tenant isolation does not rely on a special public URI format. It relieFilesystem operations and semantic retrieval are tenant-aware:- Non-ROOT requests are automatically filtered by `account_id`-- `resources` includes account-shared resources by default and uses effective ACLs when configured+- `resources` includes account-shared resources by default and uses effective ACLs when account-level `acl.enabled` is on and grants are configured- User resources remain isolated to the current user space; move them to `viking://resources` to share them-- `memory` and `skill` remain filtered by the current user space+- Memories and private skills remain filtered by the current user space; shared skills live at `viking://agent/skills` inside the account- An actor peer filters `viking://user/{user}/peers` to one peer for filesystem and retrieval operationsThis keeps "what you can search" aligned with "what you can read."@@ -239,43 +240,36 @@ If you give the plugin a root key directly, normal tenant-scoped data APIs willnot have a key-bound tenant user, so that is not a good default for day-to-dayaccess.-### Vikingbot: root key manages many end users+### VikingBot: Match the Server Authentication Mode-Vikingbot uses a different practice. It behaves more like a platform serving many end users:+Current VikingBot selects its connection through `bot.ov_server.api_key_type`. It does not automatically register each end user and cache a user key using a root key:-- The bot connects to OpenViking with a root key-- The bot config fixes an `account_id`-- The bot automatically registers users inside that account-- The bot caches per-user user keys and uses them for memory commit/search whenever possible+- `user`: connect to an `api_key` Server using a User/Admin `api_key`; the key determines data identity.+- `root`: use a trusted Server connection to assert account/user identity. This key cannot access tenant data on an `api_key` Server.+- A Bot started from the same configuration can inherit the current Server connection; configure external Server connections explicitly.-Example config:+Example for a fixed user identity:```json{"bot": {"ov_server": {"server_url": "http://127.0.0.1:1933",- "root_api_key": "test",- "account_id": "default",- "admin_user_id": "default"+ "api_key_type": "user",+ "api_key": "your-user-api-key"}}}```-Characteristics of this model:--- Good for one bot service serving many chat users-- `resources` are shared by default inside the same account; ACLs can refine access to individual directories or files-- User memories are isolated through auto-managed user identities-- The bot takes on more tenant lifecycle management logic than the OpenClaw plugin+Chat participants sharing one user key remain inside one OpenViking user boundary. `actor_peer_id` can restrict the peer collection view, but does not make that user's own memories or shared resources private to each participant. For separate user boundaries, a trusted entry point must supply distinct user connections or trusted identities; see [VikingBot Installation and Configuration](../guides/17-vikingbot.md).## Which Practice to Choose| Scenario | Recommended pattern ||----------|---------------------|| One OpenClaw instance maps to one fixed identity | OpenClaw plugin + user key |-| One gateway or bot service serves many end users | Vikingbot + root-key-managed users |+| One gateway or bot service serves many end users | Per-user connections or trusted identity forwarding || A trusted gateway injects identity upstream | `trusted` mode || Local single-user experience without formal tenant isolation | Dev mode without `root_api_key` |@@ -314,7 +308,7 @@ That is only dev mode:### 4. OpenClaw plugin and Vikingbot are not the same multi-tenant pattern- OpenClaw plugin is closer to "a client directly uses one user identity"-- Vikingbot is closer to "a platform manages many users and their user keys"+- VikingBot supports a fixed User/Admin key or trusted identity forwarding, according to the Server authentication mode## Related Documentationdiff --git a/docs/en/concepts/13-privacy.md b/docs/en/concepts/13-privacy.mdindex 8e4774d4f..c42317816 100644--- a/docs/en/concepts/13-privacy.md+++ b/docs/en/concepts/13-privacy.md@@ -4,7 +4,7 @@ This page explains OpenViking privacy configs and how they work with skill write## Goal-Privacy configs separate sensitive values (such as `api_key`, `token`, `base_url`) from skill body content so plaintext is not permanently stored in `SKILL.md`, while keeping full version management and rollback.+Privacy configs separate sensitive values (such as `api_key`, `token`, `base_url`) from skill body content to reduce plaintext storage of recognized values in `SKILL.md`, with version lookup and switching. Extraction relies on a model and replaces only recognized, matched spans; it does not guarantee discovery of every sensitive value.Core goals:@@ -24,7 +24,7 @@ Privacy configs are keyed by `category + target_key`.Storage layout in user space:```-viking://user/{user_space}/privacy/{category}/{target_key}/+viking://user/{user_id}/privacy/{category}/{target_key}/├── .meta.json # metadata (active_version/latest_version/labels, etc.)├── current.json # active version snapshot└── history/@@ -45,11 +45,13 @@ viking://user/{user_space}/privacy/{category}/{target_key}/- If `values` is identical to current `values`, no new version is created- Otherwise a new version is created and activated- New keys are allowed (no unknown-key rejection)+- `values` is a full snapshot, not a patch; omitted old keys are absent from the new version### activate- Sets a historical version as active (writes back to `current.json`)- Updates `active_version` in `.meta.json`+- Does not rotate or revoke credentials at an external service; it only selects the values OpenViking uses---@@ -74,7 +76,7 @@ add_skill3. **Block mapping captured**:- `original_content_blocks`- `replacement_content_blocks`-4. **Persisted content**: stored `SKILL.md` contains placeholders, not plaintext values.+4. **Persisted content**: matched spans become placeholders; unmatched content remains unchanged. This processes the skill body, not every attached file.---@@ -118,6 +120,8 @@ Current matching is suffix-based: `/skills/{name}/SKILL.md`, so it supports user---+`read` returns restored values, and extra-config notices also include values. Privacy APIs and historical snapshots can return full values as well. This feature does not redact responses or encrypt storage; see [Storage Encryption](./10-encryption.md) for encryption.+## Relationship with CLI/API- Management plane: Privacy API/CLI for versions (query, write, rollback)@@ -129,10 +133,10 @@ Common commands:```bashov privacy categoriesov privacy list skill-ov privacy skill <target_key>-ov privacy upsert skill <target_key> --values-json '{"api_key":"..."}'-ov privacy activate skill <target_key> <version>-ov read viking://user/default/skills/<target_key>/SKILL.md+ov privacy skill search-web+ov privacy upsert skill search-web --values-json '{"api_key":"..."}'+ov privacy activate skill search-web 1+ov read viking://~/skills/search-web/SKILL.md```---@@ -140,7 +144,7 @@ ov read viking://user/default/skills/<target_key>/SKILL.md## Benefits- Reduces plaintext sensitive data exposure in skill content-- Versioning supports key rotation and fast rollback+- Version history supports configuration changes after external credential rotation- Transparent to callers: `read` returns restored executable skill text- Notice block improves troubleshooting when config is incomplete or over-provisioneddiff --git a/docs/en/guides/04-authentication.md b/docs/en/guides/04-authentication.mdindex 2fdf7badf..25ed656ac 100644--- a/docs/en/guides/04-authentication.md+++ b/docs/en/guides/04-authentication.md@@ -2,17 +2,17 @@OpenViking Server supports multiple built-in authentication modes with role-based access control. The mode is auto-detected if not explicitly configured. In addition, custom authentication plugins can be registered to support arbitrary identity sources.-> **Recommended:** API Key mode is the most common and secure default choice, suitable for most deployment scenarios.+API Key mode is recommended for most deployments; it is auto-selected when no mode is specified and a nonempty root key is configured. Use API Key mode when OpenViking should manage credentials, OIDC or LDAP for an existing identity service, and Trusted mode behind a gateway that validates callers.## Authentication Modes Overview-| Mode | `server.auth_mode` | Identity Source | Typical Use | Recommendation |-|------|--------------------|-----------------|-------------|----------------|-| **API Key Mode** ⭐ | `api_key` | API key. Data ownership is resolved from the user/admin key. | Standard multi-tenant deployment | ⭐⭐⭐⭐⭐ |-| **OIDC Mode** | `oidc` | JWT tokens from external identity providers | Enterprise SSO integration with Okta/Auth0/Keycloak | ⭐⭐⭐⭐ |-| **LDAP Mode** | `ldap` | Enterprise LDAP/AD directory services | Integrate with existing enterprise user directory | ⭐⭐⭐⭐ |-| **Trusted Mode** | `trusted` | `X-OpenViking-Account` / `X-OpenViking-User`, plus `root_api_key` on non-localhost deployments. Role is looked up from APIKeyManager if the user exists. | Behind a trusted gateway or internal network boundary | ⭐⭐⭐ |-| **Dev Mode** | `dev` | No authentication, always ROOT | Local development only | ⭐⭐ |+| Mode | `server.auth_mode` | Identity Source | Typical Use |+|------|--------------------|-----------------|-------------|+| **API Key Mode** | `api_key` | API key. Data ownership is resolved from the user/admin key. | Standard multi-tenant deployment |+| **OIDC Mode** | `oidc` | JWT tokens from external identity providers | Enterprise SSO integration with Okta/Auth0/Keycloak |+| **LDAP Mode** | `ldap` | Enterprise LDAP/AD directory services | Integrate with existing enterprise user directory |+| **Trusted Mode** | `trusted` | `X-OpenViking-Account` / `X-OpenViking-User`, plus `root_api_key` on non-localhost deployments. Role is looked up from APIKeyManager if the user exists. | Behind a trusted gateway or internal network boundary |+| **Dev Mode** | `dev` | No authentication, always ROOT | Local development only |If `auth_mode` is not explicitly configured:- If `root_api_key` is set (non-empty): auto-selects `api_key` mode@@ -22,7 +22,7 @@ If `auth_mode` is not explicitly configured:## Quick Start: API Key Mode (Recommended)-API Key mode is the most secure and easiest default choice.+API Key mode uses a root key for account administration and user/admin keys for tenant data access.### Configuration@@ -74,33 +74,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users \ACL groups are the exception: groups and memberships are maintained through the [Admin API](../api/08-admin.md#groups), and members must be registered users in the current account. Clients cannot assert groups through headers or token claims. After authentication, the server resolves the group registry into `RequestContext.group_ids` for that request.-Trusted deployments can also call Admin API through a trusted gateway. There are two supported patterns:--- Present the trusted deployment's `root_api_key`. For `/api/v1/admin/*`, the server treats the request as ROOT after validating that key.-- Optionally also present `X-OpenViking-Account` + `X-OpenViking-User` when the admin route targets a specific account/user. Those headers must match the target URL and are kept as the request identity, but authorization still comes from the trusted `root_api_key`.--The role-update API only promotes users to ADMIN. Trusted Admin API authorization comes from the validated deployment root key; creating a ROOT user is not required or supported.--Example using a trusted upstream identity:--```bash-# First, register the gateway admin (do this once in api_key mode)-curl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "X-API-Key: your-secret-root-key" \- -H "Content-Type: application/json" \- -d '{"account_id": "platform", "admin_user_id": "gateway-admin"}'--# Then, in trusted mode, use that identity to call Admin API-curl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "X-API-Key: your-secret-root-key" \- -H "X-OpenViking-Account: platform" \- -H "X-OpenViking-User: gateway-admin" \- -H "Content-Type: application/json" \- -d '{- "account_id": "acme",- "admin_user_id": "alice"- }'-```+For gateway deployments, see [Trusted Mode](#trusted-mode) for identity headers and Admin API access.### Client Usage@@ -113,7 +87,7 @@ curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \-H "X-API-Key: <user-key>"```-**Authorization: Bearer ***+**Authorization: Bearer header**```bashcurl http://localhost:1933/api/v1/fs/ls?uri=viking:// \@@ -142,7 +116,7 @@ client = ov.SyncHTTPClient(When you use a user key or admin key, the server derives `account` and `user` from the key. Do not send `X-OpenViking-Account` / `X-OpenViking-User` in `api_key` mode; those identity headers are accepted only in `trusted` mode.-**CLI override flags**+**CLI request**```bashov ls viking://@@ -527,7 +501,7 @@ Clients submit credentials using Basic Auth:```bashcurl https://openviking.example.com/api/v1/fs/ls?uri=viking:// \- -u alice:password123+ -u alice```## Trusted Mode@@ -562,25 +536,13 @@ Trusted deployments can also call Admin API through a trusted gateway. There are1. Present the trusted deployment's `root_api_key`. For `/api/v1/admin/*`, the server treats the request as ROOT after validating that key.2. Optionally also present `X-OpenViking-Account` + `X-OpenViking-User` when the admin route targets a specific account/user. Those headers must match the target URL and are kept as the request identity, but authorization still comes from the trusted `root_api_key`.-Example using a trusted upstream identity:+A trusted deployment with a configured root key can create an account directly; switching to API key mode or registering a gateway user first is unnecessary.```bash-# First, register the gateway admin (do this once in api_key mode)-curl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "X-API-Key: your-secret-root-key" \- -H "Content-Type: application/json" \- -d '{"account_id": "platform", "admin_user_id": "gateway-admin"}'--# Then use that identity in trusted mode; admin authorization comes from root_api_keycurl -X POST http://localhost:1933/api/v1/admin/accounts \-H "X-API-Key: your-secret-root-key" \- -H "X-OpenViking-Account: platform" \- -H "X-OpenViking-User: gateway-admin" \-H "Content-Type: application/json" \- -d '{- "account_id": "acme",- "admin_user_id": "alice"- }'+ -d '{"account_id": "acme", "admin_user_id": "alice"}'```### Trusted Mode Client Configuration@@ -597,6 +559,8 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \}```+The curl and SDK examples below use the localhost configuration without a root key. If one is configured, also provide it as `X-API-Key` or SDK `api_key`.+**curl Example**```bash@@ -619,7 +583,7 @@ client = ov.SyncHTTPClient(## Dev Mode-When `auth_mode = "dev"` (or auto-detected when no `root_api_key` is configured), authentication is disabled. All requests are accepted as ROOT with the default account. **This is only allowed when the server binds to localhost** (`127.0.0.1`, `localhost`, or `::1`). If `host` is set to a non-loopback address (e.g. `0.0.0.0`) in `dev` mode, the server will refuse to start.+When `auth_mode = "dev"` (or auto-detected when no `root_api_key` is configured), authentication is disabled. Requests are accepted as ROOT; account/user default to `default` when identity headers are absent. **This is only allowed when the server binds to localhost** (`127.0.0.1`, `localhost`, or `::1`). If `host` is set to a non-loopback address (e.g. `0.0.0.0`) in `dev` mode, the server will refuse to start.```json{@@ -642,13 +606,13 @@ Or explicitly:}```-> **Security note:** The default `host` is `127.0.0.1`. If you need to expose the server on the network, you **must** configure `root_api_key`.+> The default `host` is `127.0.0.1`. Before binding to a network address, choose and configure API Key, OIDC, LDAP, or a protected Trusted deployment. Dev mode refuses non-loopback addresses.## Roles and Permissions| Role | Scope | Capabilities ||------|-------|-------------|-| ROOT | Global | All operations + Admin API (create/delete accounts, manage users) |+| ROOT | Deployment administration | Admin API and selected system operations; a root API key cannot access tenant data in API key mode || ADMIN | Own account | Regular operations + manage users in own account || USER | Own account | Regular operations (ls, read, find, sessions, etc.) |@@ -723,10 +687,10 @@ The built-in `Role` class supports dynamic registration of custom roles with pri```pythonfrom openviking.server.identity import Role-Role.register("operator", rank=1) # Between USER (0) and ADMIN (1)+Role.register("operator", rank=1) # Same rank as ADMIN for downgrade checks```-Custom roles work with `require_role()` and `require_auth_role()` decorators out of the box.+The rank is used for downgrade checks; it does not inherit ADMIN permissions. `require_role()` and `require_auth_role()` check explicit role names, so a route must list the custom role to accept it.---@@ -745,8 +709,7 @@ Edit `~/.openviking/ovcli.conf` to add LDAP authentication settings:"url": "http://localhost:1933","auth_mode": "ldap","ldap_username": "alice",- "ldap_password": "password123",- "account": "default"+ "ldap_password": "your-ldap-password"}```@@ -757,12 +720,11 @@ Edit `~/.openviking/ovcli.conf` to add LDAP authentication settings:| `url` | Yes | OpenViking server URL || `auth_mode` | Yes | Authentication mode, set to `"ldap"` to enable LDAP || `ldap_username` | Yes | LDAP username (UID) |-| `ldap_password` | No | LDAP password (omit to skip password in CLI) |-| `account` | No | OpenViking account ID (defaults to `"default"`) |+| `ldap_password` | Yes | LDAP password; without it the CLI does not send Basic Auth |#### 2. Mixed Configuration-You can configure some settings in the file and override others with environment variables (e.g. `OPENVIKING_URL`, `OPENVIKING_ACCOUNT`).+Use `OPENVIKING_CLI_CONFIG_FILE` to select another complete configuration file. The `ov` CLI does not use `OPENVIKING_URL` or `OPENVIKING_ACCOUNT` as connection overrides (except `ov chat`, which derives the bot endpoint from `OPENVIKING_URL`); those variables configure Agent plugins.### Using the CLI@@ -795,7 +757,7 @@ You can switch between LDAP and API Key authentication by editing `~/.openviking### Security Recommendations-1. **Avoid storing plaintext passwords**: Prefer environment variables or secret managers over hardcoding in config files+1. **Restrict config-file access**: The current CLI reads the LDAP password from its config file. Limit read access to the current user and keep the file out of repositories and shared logs2. **Use HTTPS**: Always use HTTPS in production environments3. **Least privilege**: Use regular user accounts for daily operations, admin accounts only for management tasks4. **Rotate passwords regularly**: Follow your organization's password security policy@@ -804,7 +766,7 @@ You can switch between LDAP and API Key authentication by editing `~/.openviking**"Missing LDAP credentials" error:**- Check that `auth_mode` is set to `"ldap"`-- Verify `username` and `password` are configured correctly+- Verify `ldap_username` and `ldap_password` are configured correctly**"LDAP authentication failed" error:**- Verify LDAP username and password are correctdiff --git a/docs/zh/api/08-admin.md b/docs/zh/api/08-admin.mdindex aff527e67..0ab72eb83 100644--- a/docs/zh/api/08-admin.md+++ b/docs/zh/api/08-admin.md@@ -38,8 +38,7 @@ Admin API 用于多租户环境下的账户、用户和用户组管理。包括{"url": "http://localhost:1933","api_key": "alice-user-key",- "root_api_key": "your-root-api-key",- ...+ "root_api_key": "your-root-api-key"}```@@ -48,7 +47,7 @@ Admin API 用于多租户环境下的账户、用户和用户组管理。包括- `ov --sudo admin` - 账户和用户管理- `ov --sudo system` - 系统工具命令- `ov --sudo reindex` - 重建索引-- `ov --sudo admin migrate` - legacy agent/session 迁移和 cleanup+- `ov --sudo admin migrate` - 旧 Session 迁移和清理- `ov --sudo task status/list` - 查询 root/system 后台任务,例如迁移任务### 使用限制@@ -166,6 +165,14 @@ ROOT 可管理任意 Account;ADMIN 仅可管理自己 Account 的模板;普| PUT | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | 补齐并发布单个模板 || DELETE | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | 删除该模板覆盖,恢复部署默认值 |+保留已有自定义内容并更新模板时,按以下步骤操作:++1. GET 目标模板,取出 `effective` 对象。+2. 修改允许编辑的说明或 `content_template`,再 PUT 整个对象。省略的配置会恢复部署默认值。+3. 核对返回的 `status` 和 `effective`。后续开始的抽取使用新模板,已有记忆不会立即重写。++需要恢复该类型的部署默认值时,调用 DELETE。+内核接收原有 Memory YAML 结构对应的 JSON 对象,并在接口层强制校验以下白名单。仅开放下列六类模板;Experience、Cases、Trajectories 等其他类型不开放查询或编辑,不支持通过接口新增、删除或重命名 Memory Type。DELETE 仅移除自定义覆盖,不删除模板类型。@@ -220,6 +227,8 @@ DELETE 始终移除该类型的覆盖;重复 PUT 默认配置或 DELETE 都是对象使用 YAML 字段名,例如 `fields[].type`。列表接口返回 `result.account_id` 和`result.templates`;单模板操作返回 `result.account_id` 及上述模板结果。+::: details 发布、存储与并发抽取的处理方式+按 Account、按模板独立存储:```text@@ -259,15 +268,17 @@ Registry;无关类型变更不会触发拆批。不同 Schema 分开合并、不同 Account 不串用,也不修改共享的部署 Registry。发布或恢复默认不会主动重写历史记忆,后续 Commit 可按生效规则更新已有记忆。+:::+白名单内提交的说明和正文模板必须是非空字符串;单文件序列化后不超过 1 MiB。`description`(类型说明及 `fields[].description`)统一支持受限 Jinja,不因来自部署默认值或账户覆盖而改变规则,不再记录或检查说明来源标志。仅开放已有上下文中的 `language`,不开放正文变量、`extract_context` 或任意对象。语法复用下节受限正文的条件、局部变量、有界字面量循环、安全字符串方法、白名单字符串过滤器及测试;不支持任意调用。例如已有 Schema 渲染上下文提供 `language=en` 时,<code v-pre>请使用 {{ language.upper() }}。</code> 会展开为 `请使用 EN。`,用户修改文字不会让变量停止展开。-本次不新增语言传递链路,Python 协议原有的静态字段说明展示路径保持不变。缺失语言时保留原来的 undefined/空字符串行为,可用 `language or '中文'` 提供回退;上下文值中的 Jinja 不会被递归执行。+渲染使用调用路径传入的语言,Python 和 JSON 协议均使用该上下文渲染字段说明。缺失语言时保留原来的 undefined/空字符串行为,可用 `language or '中文'` 提供回退;上下文值中的 Jinja 不会被递归执行。越界的自定义表达式在保存前拒绝,已保存说明在抽取加载时重新校验;部署说明渲染也受同样限制,已有部署若使用白名单外语法,需要调整,不能凭来源绕过限制。每条说明最多 2048 个 AST 节点,渲染结果最多 1 MiB。正文 `content_template` 的变量、源码大小及默认正文兼容规则仍按下节处理。每个可编辑 `description` 最多 50,000 个 Unicode 码点,按提交的原文计数,包含空格、换行和模板样式的文字,不按 UTF-8 字节或渲染后的长度计数。各说明独立计数,不合并计算;整个配置仍受 1 MiB 上限约束。超过上限返回 400,不修改当前配置。-发布不调用 LLM。存储错误或文件损坏明确报错,不伪装成系统默认。本次不增加公共文件浏览目录、SDK/CLI 命令、草稿或历史版本 UI。+发布不调用 LLM。存储错误或文件损坏明确报错,不伪装成系统默认。这些接口暂无 SDK/CLI 封装,读取、发布和恢复模板均使用 HTTP API。#### content_template 的编辑与执行边界@@ -335,7 +346,7 @@ Events 的默认 embedding 模板引用正文,因此正文变化也可能影失败不修改当前发布配置。此前保存的、结构有效但使用不支持 Jinja 的模板仍可读取、重新发布或恢复默认;不会绕过新规则继续执行,抽取加载时提示修复。损坏 YAML 仍明确报错。-示例:只展示事件名称和摘要,不输出 ChatLog:+示例:以下 `events` 的 PUT 请求体只展示事件名称和摘要,不输出 ChatLog:```json{"content_template": "# {{ event_name.strip() }}\n\n## 事件摘要\n{{ summary.strip() or '待补充' }}"}@@ -756,7 +767,7 @@ User override 并重新继承上述默认值,请 PATCH `{"memory_policy": null**说明:**- 在 `trusted` 模式下,响应中不会包含 `user_key` 字段-- 省略 `seed` 时使用默认随机 API Key。seed 应视为密钥材料;过短的 seed 会让 key 更容易被猜测。+- 省略 `seed` 时随机生成 API Key。运行确定性示例前,将 `OV_KEY_SEED` 设为安全生成的秘密值;Go 示例还需导入 `os`。不要使用短字符串或可预测内容作为 seed。- `settings` 在账号和目录创建前完成结构与有效 Embedding/VectorDB 联合校验。校验失败不会留下 Account、用户或配置文件。- Account `vlm`、`query_planner`、`embedding` 和 `vectordb` 是 ROOT-only 配置;字段 schema、生命周期和校验见上文 [Account Configuration 接口参考](#account-configuration-接口参考)。当前 Python SDK、CLI 及其他 SDK 的创建账号封装尚未暴露 `settings` 参数,使用此能力请直接调用 HTTP API。- 不再支持 account 级 namespace 隔离配置。用户记忆使用 user-scoped namespace,一对多外部参与者通过 `peer_id` 表达。@@ -778,8 +789,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \-H "X-API-Key: <root-key>" \-d '{"account_id": "acme",- "admin_user_id": "alice",- "seed": "alice-seed"+ "admin_user_id": "alice"}'```@@ -816,31 +826,9 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \}'```-`trusted` 模式示例:+**trusted 模式**-```bash-# 首先,在 api_key 模式下注册网关管理员用户-curl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "Content-Type: application/json" \- -H "X-API-Key: <root-key>" \- -d '{- "account_id": "platform",- "admin_user_id": "gateway-admin"- }'--# 然后在 trusted 模式下使用;管理权限来自 root_api_key-curl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "Content-Type: application/json" \- -H "X-API-Key: <root-key>" \- -H "X-OpenViking-Account: platform" \- -H "X-OpenViking-User: gateway-admin" \- -d '{- "account_id": "acme",- "admin_user_id": "alice"- }'-```--`trusted` 模式也支持"不带身份头"的 ROOT 回退写法:+配置 `server.root_api_key` 后,直接用 root key 调用 Admin API;无需先注册网关用户,也无需切换到 `api_key` 模式。这类请求可以省略身份头,避免与 URL 中的目标 account/user 不匹配。```bashcurl -X POST http://localhost:1933/api/v1/admin/accounts \@@ -863,7 +851,6 @@ client.initialize()result = client.admin_create_account(account_id="acme",admin_user_id="alice",- seed="alice-seed",)print(f"Account created: {result['account_id']}")print(f"Admin user: {result['admin_user_id']}")@@ -896,7 +883,7 @@ if err != nil {}fmt.Println(result["account_id"])-seed := "alice-seed"+seed := os.Getenv("OV_KEY_SEED")result, err = client.AdminCreateAccountWithOptions(ctx, "acme-private", "alice", &openviking.AdminCreateAccountOptions{Seed: &seed,UserConfig: map[string]any{@@ -913,7 +900,7 @@ result, err = client.AdminCreateAccountWithOptions(ctx, "acme-private", "alice",```bash# 需要 ROOT 权限,使用 --sudoov --sudo admin create-account acme --admin alice-ov --sudo admin create-account acme --admin alice --seed alice-seed+ov --sudo admin create-account acme --admin alice --seed "$OV_KEY_SEED"ov --sudo admin create-account acme-private --admin alice \--user-config-json '{"add_targets":{"resource_uri":"viking://~/resources","skill_uri":"viking://~/skills"}}'@@ -1177,7 +1164,7 @@ ov --sudo task status <task_id>**说明:**- 在 `trusted` 模式下,响应中不会包含 `user_key` 字段-- 省略 `seed` 时使用默认随机 API Key。seed 应视为密钥材料;过短的 seed 会让 key 更容易被猜测。+- 省略 `seed` 时随机生成 API Key。运行确定性示例前,将 `OV_KEY_SEED` 设为安全生成的秘密值;Go 示例还需导入 `os`。不要使用短字符串或可预测内容作为 seed。- ADMIN 只能在自己所属的 account 中注册用户- 无法通过用户注册接口直接创建 `"root"` 角色- `user_config.add_targets.resource_uri` 必须是可写资源目录 URI:`viking://resources` 或 `viking://resources/...`、`viking://~/resources` 或 `viking://~/resources/...`、`viking://user/{user_id}/resources` 或 `viking://user/{user_id}/resources/...`、`viking://user/{user_id}/peers/{peer_id}/resources` 或 `viking://user/{user_id}/peers/{peer_id}/resources/...`。@@ -1198,8 +1185,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users \-H "X-API-Key: <root-or-admin-key>" \-d '{"user_id": "bob",- "role": "user",- "seed": "bob-seed"+ "role": "user"}'```@@ -1215,7 +1201,6 @@ result = client.admin_register_user(account_id="acme",user_id="bob",role="user",- seed="bob-seed",)print(f"User registered: {result['user_id']}")print(f"User key: {result.get('user_key', '(not exposed in trusted mode)')}")@@ -1243,7 +1228,7 @@ if err != nil {}fmt.Println(result["user_id"])-seed := "bob-seed"+seed := os.Getenv("OV_KEY_SEED")result, err = client.AdminRegisterUserWithOptions(ctx, "acme", "bob-private", "user", &openviking.AdminRegisterUserOptions{Seed: &seed,UserConfig: map[string]any{@@ -1258,7 +1243,7 @@ result, err = client.AdminRegisterUserWithOptions(ctx, "acme", "bob-private", "u# ROOT 或本账户的 ADMIN 都可以执行# 如果使用普通用户的 api_key 但该用户是 acme 的 ADMIN:ov admin register-user acme bob --role user-ov admin register-user acme bob --role user --seed bob-seed+ov admin register-user acme bob --role user --seed "$OV_KEY_SEED"# 如果使用 root_api_key(--sudo):ov --sudo admin register-user acme bob --role user@@ -1308,6 +1293,8 @@ ov admin register-user acme bob-private --role user \| account_id | str | 是 | - | 工作区 ID || name | str | 否 | null | 按用户 ID 过滤(通配符 `*` 和 `?` 匹配) || role | str | 否 | null | 按角色过滤 |+| query | str | 否 | null | 仅 HTTP,按用户 ID 做不区分大小写的字面包含匹配 |+| include_summary | bool | 否 | false | 仅 HTTP,以对象返回分页用户和账号统计 || include_credentials | bool | 否 | true | 仅 HTTP。设为 false 时仅返回 `user_id`、`role` 和 `api_key_available`,不返回密钥或前缀;默认保持现有按鉴权模式返回字段的行为。 || limit | int | 否 | null | 每页数量(≥1)。省略则返回所有匹配项 || page | int | 否 | 1 | 从 1 开始的页码;仅在设置了 `limit` 时生效 |@@ -1580,7 +1567,7 @@ fmt.Println(result["role"])**CLI**```bash-# 需要 ROOT 权限,使用 --sudo+# ROOT 调用示例;acme 的 ADMIN 可用 ov admin set-role,无需 --sudoov --sudo admin set-role acme bob admin```@@ -1603,12 +1590,12 @@ ov --sudo admin set-role acme bob admin#### 1. API 实现介绍-重新生成用户的 API Key,旧 Key 立即失效。+生成并保存用户的 API Key。默认随机生成时,更新成功后旧 Key 失效。同一 account、user 和 seed 会生成相同的 Key;轮换密钥时应使用新 seed,或省略 seed。**处理流程:**1. 验证请求者具有 ROOT 权限,或为本账户的 ADMIN2. 调用 API Key Manager 重新生成用户密钥-3. 旧密钥立即失效+3. 随机生成或使用新 seed 时,旧密钥立即失效4. 返回新的用户密钥**代码入口:**@@ -1628,8 +1615,8 @@ ov --sudo admin set-role acme bob admin**说明:**- ADMIN 只能为自己所属的 account 中的用户重新生成密钥-- 旧密钥会立即失效,需要更新使用该密钥的客户端-- 省略 `seed` 时使用默认随机重新生成逻辑。+- 随机生成或使用新 seed 时,旧密钥立即失效,需要更新使用该密钥的客户端+- 省略 `seed` 时随机生成新密钥。确定性示例使用 `OV_KEY_SEED` 或 `OV_NEW_KEY_SEED`,运行前需将其设为安全生成的秘密值;Go 示例需导入 `os`。不要把示例变量名直接当作 seed。#### 3. 使用示例@@ -1643,7 +1630,7 @@ POST /api/v1/admin/accounts/{account_id}/users/{user_id}/keycurl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users/bob/key \-H "Content-Type: application/json" \-H "X-API-Key: <root-or-admin-key>" \- -d '{"seed": "bob-new-seed"}'+ -d '{}'```**Python SDK**@@ -1657,7 +1644,6 @@ client.initialize()result = client.admin_regenerate_key(account_id="acme",user_id="bob",- seed="bob-new-seed",)print(f"New user key: {result['user_key']}")```@@ -1677,7 +1663,7 @@ if err != nil {}fmt.Println(result["user_key"])-seed := "bob-new-seed"+seed := os.Getenv("OV_NEW_KEY_SEED")result, err = client.AdminRegenerateKeyWithOptions(ctx, "acme", "bob", &openviking.AdminRegenerateKeyOptions{Seed: &seed,})@@ -1689,7 +1675,7 @@ result, err = client.AdminRegenerateKeyWithOptions(ctx, "acme", "bob", &openviki# ROOT 或本账户的 ADMIN 都可以执行# 如果使用普通用户的 api_key 但该用户是 acme 的 ADMIN:ov admin regenerate-key acme bob-ov admin regenerate-key acme bob --seed bob-new-seed+ov admin regenerate-key acme bob --seed "$OV_NEW_KEY_SEED"# 如果使用 root_api_key(--sudo):ov --sudo admin regenerate-key acme bob```@@ -1767,7 +1753,7 @@ curl -X POST http://localhost:1933/api/v1/admin/migrate \-H "X-API-Key: <root-key>" \-d '{"action": "migrate"}'-# 清理旧 namespace+# 迁移任务完成并核对目标数据后,再清理旧 namespacecurl -X POST http://localhost:1933/api/v1/admin/migrate \-H "Content-Type: application/json" \-H "X-API-Key: <root-key>" \@@ -1802,14 +1788,16 @@ fmt.Println(result["task_id"])```bashov --sudo admin migrate --output json+# 先用 ov --sudo task status <task_id> 查询返回的任务,再核对迁移结果。ov --sudo admin migrate --cleanup --output json```-**响应示例**+**CLI 响应示例(默认 compact 输出)**```json{- "task_id": "legacy_migration_..."+ "ok": true,+ "result": {"task_id": "6de05fc3-0334-40d6-ba9b-dd317eb4d351"}}```@@ -1821,6 +1809,8 @@ ov --sudo admin migrate --cleanup --output json### 典型管理流程+示例包含删除用户和工作区的步骤,只应在测试工作区完整执行;为真实用户开通账号时跳过删除步骤。+```bash# 步骤 1:ROOT 创建工作区,指定 alice 为首个 admin(需要 --sudo)ov --sudo admin create-account acme --admin alicediff --git a/docs/zh/api/10-privacy.md b/docs/zh/api/10-privacy.mdindex 883ee6aa5..8aa83c7a7 100644--- a/docs/zh/api/10-privacy.md+++ b/docs/zh/api/10-privacy.md@@ -2,7 +2,11 @@隐私配置用于按 `category + target_key` 管理敏感字段版本(如 skill 的 `api_key`、`base_url`)。-每次更新都会生成版本快照,可查询历史版本并切换生效版本。+配置值变化时会生成版本快照,可查询历史版本并切换生效版本。提交与当前版本相同的值不会创建新版本。++以下示例使用当前用户的 API Key。trusted 模式需补充部署要求的身份头。读取接口和 CLI 会返回保存的实际值;下文的 `***` 仅为示例占位符,不表示接口自动脱敏。++激活版本只改变 OpenViking 保存的配置,不会替外部服务轮换、撤销或恢复密钥。## 典型场景@@ -25,8 +29,6 @@| GET | `/api/v1/privacy-configs/{category}/{target_key}/versions/{version}` | 获取指定版本详情 || POST | `/api/v1/privacy-configs/{category}/{target_key}/activate` | 激活指定版本 |-下面按接口逐一展开说明。----## 数据结构@@ -82,9 +84,7 @@ GET /api/v1/privacy-configs```bashcurl -X GET http://localhost:1933/api/v1/privacy-configs \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice"+ -H "X-API-Key: your-key"```**响应**@@ -110,9 +110,7 @@ GET /api/v1/privacy-configs/{category}```bashcurl -X GET http://localhost:1933/api/v1/privacy-configs/skill \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice"+ -H "X-API-Key: your-key"```**响应**@@ -138,9 +136,7 @@ GET /api/v1/privacy-configs/{category}/{target_key}```bashcurl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase" \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice"+ -H "X-API-Key: your-key"```**响应**@@ -178,7 +174,7 @@ curl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-sea**行为说明**-- `values` 按整包快照写入(本次传入内容成为新版本的 `values`)+- `values` 完整替换该版本的键值;本次省略的 key 不会出现在新快照中- 传入新 key 会直接写入(允许新增)- 若与当前版本完全一致,则复用当前版本号,不新建版本@@ -200,8 +196,6 @@ POST /api/v1/privacy-configs/{category}/{target_key}curl -X POST "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase" \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice" \-d '{"values": {"api_key": "secret-2",@@ -248,9 +242,7 @@ GET /api/v1/privacy-configs/{category}/{target_key}/versions```bashcurl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/versions" \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice"+ -H "X-API-Key: your-key"```**响应**@@ -278,9 +270,7 @@ GET /api/v1/privacy-configs/{category}/{target_key}/versions/{version}```bashcurl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/versions/2" \- -H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice"+ -H "X-API-Key: your-key"```**响应**@@ -324,8 +314,6 @@ POST /api/v1/privacy-configs/{category}/{target_key}/activatecurl -X POST "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/activate" \-H "Content-Type: application/json" \-H "X-API-Key: your-key" \- -H "X-OpenViking-Account: default" \- -H "X-OpenViking-User: alice" \-d '{"version": 2}'```@@ -365,6 +353,9 @@ ov privacy skill byted-viking-search-knowledgebaseov privacy upsert skill byted-viking-search-knowledgebase \--values-json '{"api_key":"secret-2","base_url":"https://example.com"}'+# 从本地 JSON 文件读取值,避免把值直接写入命令参数+ov privacy upsert skill byted-viking-search-knowledgebase --values-file ./privacy-values.json+# 仅更新部分 key(先读取 current 再合并)ov privacy upsert skill byted-viking-search-knowledgebase \--key-api_key secret-3diff --git a/docs/zh/concepts/11-multi-tenant.md b/docs/zh/concepts/11-multi-tenant.mdindex 78c77d4b6..c4280b059 100644--- a/docs/zh/concepts/11-multi-tenant.md+++ b/docs/zh/concepts/11-multi-tenant.md@@ -1,6 +1,6 @@# 多租户-OpenViking 的多租户不是“为每个团队部署一套独立服务”,而是在同一个 OpenViking Server 内,用 `account` 和 `user` 两层身份边界来隔离和共享数据。+OpenViking 的多租户不是“为每个团队部署一套独立服务”,而是在同一个 Server 内,通过 `account` 和 `user` 两层身份边界隔离和共享数据。它适合两类典型场景:@@ -40,7 +40,7 @@ OpenViking 的多租户不是“为每个团队部署一套独立服务”,而| 角色 | 作用域 | 典型能力 ||------|--------|----------|-| ROOT | 全局 | 创建/删除 account、跨租户访问、管理用户 |+| ROOT | 全局 | 创建/删除 account、管理用户;API Key 模式下不用于租户数据读写 || ADMIN | 单个 account | 管理本 account 的用户、重置 user key || USER | 单个 account | 访问自己的 user/peer/session 数据和 account 内共享资源 |@@ -57,7 +57,7 @@ OpenViking Server 支持两种多租户相关认证模式:### `root_api_key` 的作用-配置 `server.root_api_key` 后,OpenViking 才进入正式多租户模式:+在 `api_key` 模式下,配置 `server.root_api_key` 后启用基于 key 的账户和用户管理:- Root key 用于管理 account 和 user- User key 由 Admin API 生成,用于普通业务读写@@ -79,7 +79,8 @@ OpenViking Server 支持两种多租户相关认证模式:| 用户资源 (`viking://user/{user_id}/resources`) | 否 | 否 | user || Peer 资源 (`viking://user/{user_id}/peers/{peer_id}/resources`) | 否 | 否 | user / peer || 记忆 | 否 | 否 | user / peer |-| 技能 | 否 | 否 | user |+| 私有技能 (`viking://user/{user_id}/skills`) | 否 | 否 | user |+| 共享技能 (`viking://agent/skills`) | 否 | 是,受访问权限约束 | account || 会话 | 否 | 否 | user / session |### 存储层@@ -109,9 +110,9 @@ viking://user/alice/peers/web-visitor-alice/resources/文件系统操作和语义检索都受租户约束:- 非 ROOT 请求会自动按 `account_id` 过滤-- `resources` 默认允许检索 account 内共享资源;设置 ACL 后按有效 ACL 过滤+- `resources` 默认允许检索 account 内共享资源;开启账号级 `acl.enabled` 并设置 ACL 后按有效 ACL 过滤- 用户资源始终按当前 `user space` 隔离;需要共享时移动到 `viking://resources`-- `memory` 和 `skill` 继续按当前 `user space` 过滤+- 记忆和私有技能按当前 `user space` 过滤;共享技能位于 account 内的 `viking://agent/skills`- Actor peer 会把 `viking://user/{user}/peers` 过滤到一个 peer,并作用于文件系统和检索操作这意味着“能搜到什么”与“能读到什么”保持一致,不会因为向量召回而越权。@@ -236,43 +237,36 @@ openclaw config set plugins.entries.openviking.config.peer_prefix "<peer-prefix>如果给插件直接配置 root key,则普通租户数据 API 没有从 key 绑定出来的租户用户,这不适合作为日常读写方式。-### Vikingbot:root key 代管用户身份+### VikingBot:匹配 Server 的认证模式-Vikingbot 当前的实践与 OpenClaw 插件不同,它更接近“平台代理多个终端用户”:+当前 VikingBot 通过 `bot.ov_server.api_key_type` 选择连接方式,不会通过 root key 自动注册并缓存每个终端用户的 user key:-- bot 连接 OpenViking 时持有 root key-- bot 配置固定的 `account_id`-- bot 会在该 account 下自动注册用户-- bot 会缓存每个 user 的 user key,并尽量用对应 user key 去提交/检索 memory+- `user`:连接 `api_key` 模式的 Server,`api_key` 必须是 User/Admin key,数据身份由 key 决定。+- `root`:用于 trusted 模式,Bot 以受信连接传递 account/user 身份;不能拿它访问 `api_key` 模式的租户数据接口。+- 同配置启动时可以继承当前 Server 的地址和认证设置;外部 Server 应显式配置连接。-相关配置示例:+固定用户身份的配置示例:```json{"bot": {"ov_server": {"server_url": "http://127.0.0.1:1933",- "root_api_key": "test",- "account_id": "default",- "admin_user_id": "default"+ "api_key_type": "user",+ "api_key": "your-user-api-key"}}}```-这种模式的特点:--- 适合一个 bot 服务承载多个聊天用户-- 同一 account 下的 `resources` 默认共享,ACL 可以对具体目录或文件细化权限-- 用户记忆通过自动注册的 user 身份隔离-- bot 侧需要承担更多租户生命周期管理逻辑+共享同一个 user key 的聊天参与者仍属于同一 OpenViking user。`actor_peer_id` 可限制其 peer 集合视图,但不会把该用户自己的记忆和共享资源变成逐聊天用户私有数据。需要独立 user 边界时,应由可信身份入口提供不同的用户连接或使用 trusted 身份传递,见[VikingBot 安装与配置](../guides/17-vikingbot.md)。## 什么时候选哪种实践| 场景 | 推荐方式 ||------|----------|| 一个 OpenClaw 实例对应一个固定身份 | OpenClaw 插件 + user key |-| 一个网关/机器人服务承载很多最终用户 | Vikingbot + root key 代管用户 |+| 一个网关/机器人服务承载很多最终用户 | 按用户配置连接或由受信入口传递 trusted 身份 || 受信网关统一注入身份 | `trusted` 模式 || 单机本地体验、无需真正租户隔离 | 开发模式(无 `root_api_key`) |@@ -310,7 +304,7 @@ peer 集合过滤选择当前用户内的 peer 内容子空间,例如### 4. OpenClaw 插件和 Vikingbot 不是同一种租户实践- OpenClaw 插件:更像“客户端拿到一个 user 身份后直接访问”-- Vikingbot:更像“平台代理多个用户,并代为申请和管理 user key”+- VikingBot:支持固定 User/Admin key,也可作为受信入口传递身份;选择取决于 Server 认证模式## 相关文档diff --git a/docs/zh/concepts/13-privacy.md b/docs/zh/concepts/13-privacy.mdindex c873f8d23..bdcf9948d 100644--- a/docs/zh/concepts/13-privacy.md+++ b/docs/zh/concepts/13-privacy.md@@ -4,7 +4,7 @@## 目标-隐私配置用于把敏感值(如 `api_key`、`token`、`base_url`)从技能正文中分离出来,避免明文长期存储在 `SKILL.md` 中,同时保留版本化管理与回滚能力。+隐私配置用于把敏感值(如 `api_key`、`token`、`base_url`)从技能正文中分离出来,减少已识别敏感值在 `SKILL.md` 中的明文存储,并支持版本查询和切换。抽取依赖模型,只替换识别并匹配成功的片段,不能保证发现所有敏感信息。核心目标:@@ -24,7 +24,7 @@用户空间下的存储路径:```-viking://user/{user_space}/privacy/{category}/{target_key}/+viking://user/{user_id}/privacy/{category}/{target_key}/├── .meta.json # 元信息(active_version/latest_version/labels 等)├── current.json # 当前生效版本快照└── history/@@ -45,11 +45,13 @@ viking://user/{user_space}/privacy/{category}/{target_key}/- 如果与当前版本 `values` 完全一致,则不新建版本,直接返回当前版本- 否则创建新版本并自动设为当前生效版本- 允许新增 key(不会因“未知 key”报错)+- `values` 是完整快照,不是部分更新;省略的旧 key 不会保留在新版本中### activate(激活)- 将历史版本设置为当前生效版本(写回 `current.json`)- 更新 `.meta.json` 中的 `active_version`+- 不会轮换或撤销第三方服务中的密钥;这里只切换 OpenViking 使用的值---@@ -74,7 +76,7 @@ add_skill3. **保留块映射**:会同时记录:- `original_content_blocks`- `replacement_content_blocks`-4. **写盘结果**:`SKILL.md` 持久化的是占位符内容,不是明文值。+4. **写盘结果**:匹配成功的片段以占位符保存,未匹配内容保持原样。该流程处理技能正文,不等于扫描并清理所有附件。---@@ -114,10 +116,12 @@ fs.read(uri)- `Missing config: ...`(如有)- `Configured but not referenced in content: ...`(如有)-> 注意:当前实现中,仅当该 skill 已有 `current` 配置时才会进入 restore。若没有当前配置,不会追加 notice。+> 仅当该 skill 已有 `current` 配置时才会进入 restore。若没有当前配置,不会追加 notice。---+`read` 返回的是还原后的值;“额外配置”提示也会包含配置值。Privacy API 和历史快照同样可以返回完整值,该功能不等于响应脱敏或存储加密。需要加密存储时,另见[存储加密](./10-encryption.md)。+## 与 CLI/API 的关系- 管理面:通过 Privacy API/CLI 管理版本(查询、写入、回滚)@@ -129,10 +133,10 @@ fs.read(uri)```bashov privacy categoriesov privacy list skill-ov privacy skill <target_key>-ov privacy upsert skill <target_key> --values-json '{"api_key":"..."}'-ov privacy activate skill <target_key> <version>-ov read viking://user/default/skills/<target_key>/SKILL.md+ov privacy skill search-web+ov privacy upsert skill search-web --values-json '{"api_key":"..."}'+ov privacy activate skill search-web 1+ov read viking://~/skills/search-web/SKILL.md```---@@ -140,7 +144,7 @@ ov read viking://user/default/skills/<target_key>/SKILL.md## 设计收益- 降低明文敏感信息在技能正文中的暴露风险-- 通过版本化支持密钥轮换与快速回滚+- 为外部密钥轮换后的配置切换保留版本记录- 对上层调用透明:`read` 即可拿到还原后的可执行技能文本- 对不完整配置提供可观测提示,便于排障diff --git a/docs/zh/guides/04-authentication.md b/docs/zh/guides/04-authentication.mdindex 2a926e585..bb1248f9e 100644--- a/docs/zh/guides/04-authentication.md+++ b/docs/zh/guides/04-authentication.md@@ -1,44 +1,30 @@# 认证-> **先看这里:选择适合你的认证模式**--## 📚 前置知识 - 我该用哪个?--| 认证模式 | 是什么? | 适合谁? | **推荐度** |-|---------|----------|---------|------------|-| **API Key** (默认) | OpenViking 自己管理用户和密钥 | 小团队、独立部署 | ⭐⭐⭐⭐⭐ |-| **OIDC** | 对接企业单点登录(Okta/Auth0/Keycloak/Azure AD 等) | 企业 SSO 集成 | ⭐⭐⭐⭐ |-| **LDAP** | 对接企业用户目录(Windows AD/OpenLDAP) | 已有企业目录服务 | ⭐⭐⭐⭐ |-| **Trusted** | 上游网关/反向代理断言身份 | 部署在受信任内网/网关后 | ⭐⭐⭐ |-| **Dev** | 无认证,仅本地开发 | **只用于本地开发!** | ⭐⭐ |--### 🔍 决策树--```-┌─────────────────────────────────────────────────────┐-│ 企业里有现成的身份系统? │-├─────────────────────────────────────────────────────┤-│ 是 SaaS 身份?(Okta/Auth0/Keycloak) │-│ → 用 **OIDC** ✅ │-│ │-│ 是本地目录?(Windows AD/OpenLDAP) │-│ → 用 **LDAP** ✅ │-├─────────────────────────────────────────────────────┤-│ 没有身份系统? │-│ → 用 **API Key**(默认)✅ │-├─────────────────────────────────────────────────────┤-│ 部署在内部网关后面? │-│ → 用 **Trusted** ✅ │-└─────────────────────────────────────────────────────┘-```+选择认证模式后,配置服务端身份来源,再用对应凭证连接客户端。大多数部署推荐使用 API Key 模式;配置非空 root key 后,未指定认证模式时会自动选择 API Key。++## 选择认证模式++| 认证模式 | 是什么? | 适合谁? |+|---------|----------|---------|+| **API Key** | OpenViking 自己管理用户和密钥 | 小团队、独立部署 |+| **OIDC** | 对接企业单点登录(Okta/Auth0/Keycloak/Azure AD 等) | 企业 SSO 集成 |+| **LDAP** | 对接企业用户目录(Windows AD/OpenLDAP) | 已有企业目录服务 |+| **Trusted** | 上游网关/反向代理断言身份 | 部署在受信任内网/网关后 |+| **Dev** | 无认证,仅本地开发 | 本地开发,不接入公网 |++### 决策树++已有单点登录服务选 OIDC,已有企业目录选 LDAP;由网关验证并注入身份时选 Trusted。没有这些上游服务时,使用 API Key 管理账号和凭证。++未显式设置 `auth_mode` 时,有非空 `root_api_key` 会选用 `api_key`,未配置则选用 `dev`。空字符串 `root_api_key` 无效。----## 🏁 快速开始 - 3分钟跑起来+## 快速开始-### 方案一:API Key(最简单)+### 方案一:API Key-只需要配置 `root_api_key`,剩下的默认就好!+配置 `root_api_key`,启动后用它创建 account 和首个管理员。日常数据操作使用返回的 user/admin key。```json{@@ -58,13 +44,21 @@ openviking-server```bash# 创建账号 + 管理员curl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "X-API-Key: your-secret-root-key" \+ -H "X-API-Key: your-secret-root-key-here" \-H "Content-Type: application/json" \-d '{"account_id": "my-team", "admin_user_id": "alice"}'```+创建账号后,保存响应中的 `user_key`,将它用于 CLI、SDK 和数据 API。root key 不用于租户数据读写。+### 方案二:OIDC(企业 SSO)+OIDC 和 LDAP 需要可选认证依赖。在运行服务端的 Python 环境中安装:++```bash+uv pip install "openviking[auth]"+```+**最小配置(不需要 mapping):**```json@@ -83,10 +77,10 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \- `user_id` → 使用 OIDC 标准字段 `sub`- `role` → 默认为 `user`-启动后健康检查会自动验证是否连接成功!+启动后用有效的 OIDC token 请求数据接口,验证身份映射和访问权限;匿名 `/health` 成功只证明服务可访问。**进阶配置(需要隔离团队时):**-参考下方「🔧 Identity Mapping 详解」章节。+参考下方 [Identity Mapping](#identity-mapping-是什么) 和高级 Mapping 示例。### 方案三:LDAP(企业目录)@@ -116,7 +110,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \----## 📚 概念详解+## 身份与映射### OIDC 是什么?@@ -160,7 +154,7 @@ OIDC Claims: {----## ⚙️ 完整配置参考+## 完整配置参考### OIDC 完整配置@@ -303,7 +297,7 @@ OIDC Claims: {----## 🐛 故障排除+## 故障排除### OIDC 常见问题@@ -392,9 +386,9 @@ OIDC Claims: {----## 🔧 自定义认证插件(高级)+## 自定义认证插件-如果内置的模式不够用,可以自己开发!+需要接入其他身份源时,可以实现并注册自定义认证插件。服务端采用插件化认证架构。每种 `auth_mode` 对应一个 `AuthPlugin` 实现。内置插件(`dev`, `api_key`, `trusted`, `oidc`, `ldap`)会自动注册;第三方插件可通过继承 `AuthPlugin` 并在启动前注册来扩展。@@ -440,10 +434,10 @@ class CustomAuthPlugin(AuthPlugin):```pythonfrom openviking.server.identity import Role-Role.register("operator", rank=1) # 权限介于 USER (0) 与 ADMIN (1) 之间+Role.register("operator", rank=1) # 降权检查时,与 ADMIN 同级```-自定义角色可直接用于 `require_role()` 和 `require_auth_role()` 装饰器。+rank 用于降权检查,不会继承 ADMIN 的接口权限。`require_role()` 和 `require_auth_role()` 按角色名检查,路由需要明确允许该自定义角色。---@@ -460,14 +454,14 @@ trusted 模式的普通数据面请求无需预先注册 user 或创建 user API```bash# 创建工作区 + 首个 admincurl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "X-API-Key: your-secret-root-key" \+ -H "X-API-Key: your-secret-root-key-here" \-H "Content-Type: application/json" \-d '{"account_id": "acme", "admin_user_id": "alice"}'# 返回: {"result": {"account_id": "acme", "admin_user_id": "alice", "user_key": "..."}}# 注册普通用户(ROOT 或 ADMIN 均可)curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users \- -H "X-API-Key: your-secret-root-key" \+ -H "X-API-Key: your-secret-root-key-here" \-H "Content-Type: application/json" \-d '{"user_id": "bob", "role": "user"}'# 返回: {"result": {"account_id": "acme", "user_id": "bob", "user_key": "..."}}@@ -482,26 +476,7 @@ ACL 用户组是例外:组和成员通过 [Admin API](../api/08-admin.md#用角色更新 API 只支持将用户提升为 ADMIN。Trusted Admin API 的管理权限来自已校验的部署 root key,无需也不支持创建 ROOT 用户。-下面是“受信上游身份”这种方式的示例:--```bash-# 首先,注册网关管理员(在 api_key 模式下执行一次)-curl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "X-API-Key: your-secret-root-key" \- -H "Content-Type: application/json" \- -d '{"account_id": "platform", "admin_user_id": "gateway-admin"}'--# 然后,在 trusted 模式下使用该身份调用 Admin API-curl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "X-API-Key: your-secret-root-key" \- -H "X-OpenViking-Account: platform" \- -H "X-OpenViking-User: gateway-admin" \- -H "Content-Type: application/json" \- -d '{- "account_id": "acme",- "admin_user_id": "alice"- }'-```+配置了 root key 的 Trusted 部署可直接调用上面的 Admin API,无需先切换到 API Key 模式或注册网关管理员。## 客户端使用@@ -541,12 +516,12 @@ client = ov.SyncHTTPClient(}```-如果使用普通 `user key` 或 `admin key`,`account` 和 `user` 可以省略,因为服务端可以从 key 反查出来;如果使用 `trusted` 模式,则建议明确配置。+API Key 模式下,服务端从 user/admin key 解析 account 和 user,不接受用身份请求头切换用户。Trusted 模式下的数据请求需要明确提供 account 和 user。-**CLI 覆盖参数**+**CLI 请求**```bash-openviking --account acme --user alice ls viking://+ov ls viking://```### 使用 --sudo 和 Root API Key@@ -618,9 +593,13 @@ Trusted 模式不会查询 user key,而是直接信任每个请求显式携带}```+数据请求必须提供 `X-OpenViking-Account` 和 `X-OpenViking-User`。若配置了 `root_api_key`,请求还必须携带匹配的 API Key,以验证上游网关。++角色默认从已注册用户查询,未注册时为 USER。配置并验证 root key 后,上游可用 `X-OpenViking-Role: user` 或 `admin` 断言角色,不接受 `root`。Admin API 的 ROOT 授权来自部署 root key。+### Dev 模式-当 `auth_mode = "dev"`(或未配置 `root_api_key` 时自动推导)时,认证禁用,所有请求以 ROOT 身份访问 default account。+当 `auth_mode = "dev"`(或未配置 `root_api_key` 时自动推导)时,认证禁用,请求使用 ROOT 身份;未提供身份请求头时,account 和 user 均为 `default`。Dev 模式只允许监听 `127.0.0.1`、`localhost` 或 `::1`,监听其他地址会拒绝启动。```json{@@ -630,7 +609,7 @@ Trusted 模式不会查询 user key,而是直接信任每个请求显式携带}```-> **安全提示:** 默认 `host` 为 `127.0.0.1`。如果需要将服务暴露到网络,**必须**配置 `root_api_key`。+> 默认 `host` 为 `127.0.0.1`。监听网络地址前,选择并配置 API Key、OIDC、LDAP 或受保护的 Trusted 部署。---@@ -649,8 +628,7 @@ OpenViking CLI (`ov`) 支持通过 LDAP 进行认证。配置完成后,所有"url": "http://localhost:1933","auth_mode": "ldap","ldap_username": "alice",- "ldap_password": "password123",- "account": "default"+ "ldap_password": "your-ldap-password"}```@@ -661,12 +639,11 @@ OpenViking CLI (`ov`) 支持通过 LDAP 进行认证。配置完成后,所有| `url` | 是 | OpenViking 服务器地址 || `auth_mode` | 是 | 认证模式,设置为 `"ldap"` 启用 LDAP || `ldap_username` | 是 | LDAP 用户名(UID) |-| `ldap_password` | 否 | LDAP 密码(不提供时 CLI 不发送密码) |-| `account` | 否 | OpenViking 账户 ID(默认为 `"default"`) |+| `ldap_password` | 是 | LDAP 密码;缺少此字段时 CLI 不发送 Basic Auth |#### 2. 混合配置-可以部分配置在文件中,部分通过环境变量(如 `OPENVIKING_URL`、`OPENVIKING_ACCOUNT`)覆盖。+用 `OPENVIKING_CLI_CONFIG_FILE` 选择另一份完整配置文件。`ov` 不读取 `OPENVIKING_URL` 或 `OPENVIKING_ACCOUNT` 作为连接覆盖值(`ov chat` 例外,它用 `OPENVIKING_URL` 拼出 bot endpoint);这些变量属于 Agent 插件配置。### 使用 CLI@@ -699,7 +676,7 @@ make build-cli### 安全建议-1. **避免明文存储密码**:推荐使用环境变量或密钥管理工具,而非在配置文件中硬编码密码+1. **限制配置文件访问**:当前 CLI 从配置文件读取 LDAP 密码。只允许当前用户读取,避免提交到仓库或写入共享日志2. **使用 HTTPS**:生产环境中确保服务器使用 HTTPS 连接3. **最小权限**:使用普通用户账户进行日常操作,管理员账户仅用于管理任务4. **定期轮换密码**:遵循组织的密码安全策略@@ -708,7 +685,7 @@ make build-cli**"Missing LDAP credentials" 错误:**- 检查 `auth_mode` 是否设置为 `"ldap"`-- 确认 `username` 和 `password` 配置正确+- 确认 `ldap_username` 和 `ldap_password` 配置正确**"LDAP authentication failed" 错误:**- 验证 LDAP 用户名和密码是否正确@@ -741,7 +718,7 @@ ov config validate----## 📝 附录:Admin API 参考+## Admin API 参考| 方法 | 端点 | 角色 | 说明 ||------|------|------|------|