Skip to content

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

feat(gateway): embed runtime and separate management access (#5960)

t0saki8a74caf5b054
diff --git a/.github/workflows/gateway.yml b/.github/workflows/gateway.yml
index 310021e08..4d6505f48 100644
--- a/.github/workflows/gateway.yml
+++ b/.github/workflows/gateway.yml
@@ -1,7 +1,7 @@
name: OpenViking Gateway
on:
pull_request:
- paths: ["openviking_gateway/**", "tests/gateway/**", "scripts/gateway_*", "openviking/server/routers/gateway.py", "openviking/service/gateway_deletion.py", "openviking_cli/utils/config/openviking_gateway_config.py", ".github/workflows/gateway.yml"]
+ paths: ["openviking_gateway/**", "tests/gateway/**", "scripts/gateway_*", "tests/fixtures/gateway_upstream_urls.json", "openviking_cli/utils/config/openviking_gateway_config.py", "openviking_cli/utils/config/encryption_config.py", "openviking_cli/setup_wizard.py", "openviking/crypto/**", ".github/workflows/gateway.yml"]
workflow_dispatch:
jobs:
test:
@@ -11,7 +11,7 @@ jobs:
- uses: actions/setup-python@v5
with:
python-version: "3.10"
- # The gateway talks to OpenViking over HTTP only, so its tests run from the
- # source tree with its own dependencies instead of building the native wheel.
- - run: pip install "aiohttp>=3.13.3" "async-timeout>=5.0.1" "orjson>=3.11.7" "packaging>=24.0" "fastapi>=0.128.0" "uvicorn>=0.39.0" "pydantic>=2.0.0" "httpx>=0.25.0" "cryptography>=48.0.1" "mcp>=1.27,<2" pytest pytest-asyncio
+ # The gateway talks to OpenViking over HTTP and reuses only its pure-Python crypto
+ # module, so its tests run from the source tree without building the native wheel.
+ - run: pip install "aiohttp>=3.13.3" "async-timeout>=5.0.1" "orjson>=3.11.7" "packaging>=24.0" "fastapi>=0.128.0" "uvicorn>=0.39.0" "pydantic>=2.0.0" "httpx>=0.25.0" "cryptography>=48.0.1" "json-repair>=0.25.0" "loguru>=0.7.3" "mcp>=1.27,<2" pytest pytest-asyncio
- run: PYTHONPATH=. pytest tests/gateway --confcutdir=tests/gateway -o addopts=''
diff --git a/Caddyfile b/Caddyfile
index 62510cc4f..c4986e79c 100644
--- a/Caddyfile
+++ b/Caddyfile
@@ -1,44 +1,17 @@
-# OpenViking reverse proxy — legacy fallback
+# Legacy HTTP entrypoint. Server and gateway (under /gateway) share OPENVIKING_SERVER_PORT.
+# Studio is served at /studio by the same server.
#
-# Port 1934 is retained only as a legacy entrypoint for existing deployments
-# that already reference it. Its primary remaining purpose is as the upstream
-# target for a TLS-terminating proxy (e.g. HTTPS via Caddy domain block).
-#
-# For new deployments, connect directly to the OV server on
-# OPENVIKING_SERVER_PORT (1933 by default). With the gateway Compose
-# profile, this is also the entrypoint for gateway clients: the gateway port
-# is not published and the block below routes its paths.
-# Web Studio is served by OV itself at /studio — no separate proxy needed.
-#
-# To add public HTTPS, append a domain block below (Caddy auto-provisions
-# Let's Encrypt certs):
+# For public HTTPS, add a domain block and publish ports 80/443 in Compose:
#
# {$OPENVIKING_PUBLIC_BASE_URL} {
-# # OpenViking Gateway paths; keep them in sync with the :1934 block below.
-# @gateway path /v1/* /api/v3/* /api/compatible/v1/* /gateway/uploads
-# handle @gateway {
-# reverse_proxy gateway:1935 {
-# flush_interval -1
-# }
-# }
-# handle {
-# reverse_proxy openviking:{$OPENVIKING_SERVER_PORT:1933}
+# reverse_proxy openviking:{$OPENVIKING_SERVER_PORT:1933} {
+# flush_interval -1
# }
-# # Optional: pin ACME email
# # tls {$OV_ACME_EMAIL}
# }
-#
-# Then expose ports 80/443 in docker-compose.yml and set
-# OPENVIKING_PUBLIC_BASE_URL=https://your-domain.com in .env.
:1934 {
- @gateway path /v1/* /api/v3/* /api/compatible/v1/* /gateway/uploads
- handle @gateway {
- reverse_proxy gateway:1935 {
- flush_interval -1
- }
- }
- handle {
- reverse_proxy openviking:{$OPENVIKING_SERVER_PORT:1933}
+ reverse_proxy openviking:{$OPENVIKING_SERVER_PORT:1933} {
+ flush_interval -1
}
}
diff --git a/Dockerfile b/Dockerfile
index db9362437..206f06822 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -83,13 +83,13 @@ RUN --mount=type=cache,target=/root/.cache/uv,id=uv-${TARGETPLATFORM} \
fi; \
case "${UV_LOCK_STRATEGY}" in \
locked) \
- uv sync --locked --no-editable --reinstall-package openviking --extra bot --extra gemini --extra opengauss --extra gateway \
+ uv sync --locked --no-editable --reinstall-package openviking --extra bot --extra gemini --extra opengauss \
;; \
auto) \
if ! uv lock --check; then \
uv lock; \
fi; \
- uv sync --locked --no-editable --reinstall-package openviking --extra bot --extra gemini --extra opengauss --extra gateway \
+ uv sync --locked --no-editable --reinstall-package openviking --extra bot --extra gemini --extra opengauss \
;; \
*) \
echo "Unsupported UV_LOCK_STRATEGY: ${UV_LOCK_STRATEGY}" >&2; \
diff --git a/deploy/helm/README.md b/deploy/helm/README.md
index b67540c30..e25a7928f 100644
--- a/deploy/helm/README.md
+++ b/deploy/helm/README.md
@@ -141,51 +141,90 @@ Secrets.
### OpenViking Gateway
-The chart can run [OpenViking Gateway](https://docs.openviking.ai/en/guides/15-gateway)
-as a second container in the OpenViking pod, sharing its volume and `ov.conf`. The gateway
-requires OpenViking Server to use API key authentication.
+Set `gateway.enabled: true` to run [OpenViking Gateway](https://docs.openviking.ai/en/guides/15-gateway)
+inside the server container. The chart adds `gateway.enabled` to `ov.conf` and stores
+gateway data in `<persistence.mountPath>/gateway` on the persistent volume. There is no
+sidecar and no extra Service port: clients use `/gateway` on the server port, and the existing Ingress
+forwards every path to OpenViking.
-Create a Secret with the fixed keys `encryption-key` and `admin-token`:
-
-```bash
-kubectl create secret generic openviking-gateway \
- --from-literal=encryption-key="$(python3 -c 'import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())')" \
- --from-literal=admin-token="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
-```
-
-Back up the encryption key along with the volume. The gateway can read its stored data only
-with this exact key, and the key can't be rotated.
-
-Then enable the gateway in your values:
+Model requests stream, so the Ingress must turn off response buffering and allow request
+bodies of at least 32 MiB and timeouts of 600 seconds. The chart does not set these
+annotations for you. With NGINX:
```yaml
gateway:
enabled: true
- existingSecret: openviking-gateway
- workers: 2
-
+ existingSecret: "" # optional: Secret with a management-key entry
config:
server:
auth_mode: api_key
gateway:
public_url: https://ov.example.com
+ingress:
+ enabled: true
+ className: nginx
+ annotations:
+ nginx.ingress.kubernetes.io/proxy-buffering: "off"
+ nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
+ nginx.ingress.kubernetes.io/proxy-body-size: 32m
+ nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
+ nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
+ hosts:
+ - host: ov.example.com
+ paths:
+ - path: /
+ pathType: Prefix
+```
+
+Set `config.gateway.public_url` to the address clients use, without `/gateway`; Studio's
+setup guides and file upload links are built from it, with `/gateway` appended. Clients use
+`https://ov.example.com/gateway/v1` (OpenAI-compatible) or `https://ov.example.com/gateway`
+(Anthropic).
+
+#### Secrets
+
+The gateway encrypts its stored data with the server's `config.encryption` settings; with
+server encryption off, it stores them unencrypted.
+
+`gateway.existingSecret` optionally names a Secret. Both entries are optional:
+
+- `management-key` (at least 32 characters) is passed as
+ `OPENVIKING_GATEWAY_MANAGEMENT_KEY`. With it, only requests that carry this key can change
+ upstreams and context profiles; see
+ [Gateway management key](https://docs.openviking.ai/en/guides/22-gateway-operations#gateway-management-key).
+- `encryption-key` is the v0.5.0 gateway key, passed as `OPENVIKING_GATEWAY_ENCRYPTION_KEY`.
+ It is only read once, to migrate data stored by the v0.5.0 gateway.
+
+```bash
+kubectl create secret generic openviking-gateway \
+ --from-literal=management-key="$(openssl rand -base64 32)"
```
-- The chart generates the rest of `config.gateway`: bind address, port, workers,
- internal URLs and a `storage_path` on the data volume. Values you set under
- `config.gateway` take precedence.
-- Set `public_url` to the address clients use, written out literally. The gateway does not
- expand `${VAR}` placeholders, and its container does not receive `extraEnv`.
-- With the ingress enabled, the chart routes `/v1`, `/api/v3`, `/api/compatible/v1` and
- `/gateway/uploads` to the gateway. It never routes the gateway's `/admin` paths;
- keep it that way in your own ingress rules.
-- Keep `replicaCount: 1`. The gateway's storage must be used from a single host; scale with
- `gateway.workers` instead.
-
-The chart does not set ingress annotations. Model requests stream and can be large, so turn off
-proxy buffering and allow 32 MiB request bodies and 600-second read timeouts. For the NGINX
-annotations, Studio setup and troubleshooting, see
-[OpenViking Gateway deployment and operations](https://docs.openviking.ai/en/guides/22-gateway-operations#helm).
+Keep `replicaCount: 1`: the gateway's SQLite databases serve one pod only. The default
+local vectordb also locks the workspace to a single worker, so raise the server's `workers`
+setting only after switching to a remote vectordb backend such as VikingDB.
+
+#### Upgrading from the sidecar chart
+
+- Keep the persistent volume. On first start the server re-encrypts the gateway's stored
+ data with its own encryption settings, reading the old key from the `encryption-key`
+ entry of `gateway.existingSecret` or from `encryption.key` in the gateway storage
+ directory. If old encrypted data exists and neither is present, the server refuses to start.
+ Keep the `encryption-key` entry for the upgrade release only; after the server has started
+ once, the key is no longer read and you can remove the entry.
+- Remove `gateway.port`, `gateway.workers` and `gateway.resources`.
+- Remove `host`, `port`, `workers`, `url`, `openviking_url` and `admin_token_env` from
+ `config.gateway`. The server ignores them with a startup warning.
+- Point `config.gateway.public_url` at the server's public address, not port 1935, and
+ move clients to the server port and the `/gateway` prefix: `http://host:1935/v1` becomes
+ `https://ov.example.com/gateway/v1`. The management API moved from
+ `/api/v1/admin/gateway/...` to `/gateway/admin/...`.
+- The shared admin token is gone and does not act as a management key. To restrict
+ changes to upstreams and context profiles, add a `management-key` entry to
+ `gateway.existingSecret`.
+
+For deployment, Studio management, backups and troubleshooting, see
+[OpenViking Gateway deployment and operations](https://docs.openviking.ai/en/guides/22-gateway-operations).
## Configuration
@@ -211,11 +250,8 @@ annotations, Studio setup and troubleshooting, see
| `config.server.root_api_key` | API key required when server binds to 0.0.0.0 | `""` |
| `config` | Full ov.conf configuration object | See `values.yaml` |
| `extraEnv` | Additional environment variables | `[]` |
-| `gateway.enabled` | Run OpenViking Gateway as a second container in the pod | `false` |
-| `gateway.existingSecret` | Secret with `encryption-key` and `admin-token`; required when enabled | `""` |
-| `gateway.workers` | Gateway worker processes | `2` |
-| `gateway.port` | Gateway container and Service port | `1935` |
-| `gateway.resources` | Gateway container resources | `{}` |
+| `gateway.enabled` | Run OpenViking Gateway inside the server container, under `/gateway` on the server port | `false` |
+| `gateway.existingSecret` | Optional Secret with optional entries `management-key` (required to change upstreams and context profiles) and `encryption-key` (v0.5.0 key, read once for migration) | `""` |
## Upgrading
diff --git a/deploy/helm/openviking/templates/configmap.yaml b/deploy/helm/openviking/templates/configmap.yaml
index 66beddcc6..d70e8f80a 100644
--- a/deploy/helm/openviking/templates/configmap.yaml
+++ b/deploy/helm/openviking/templates/configmap.yaml
@@ -1,6 +1,6 @@
{{- $config := deepCopy .Values.config }}
{{- if .Values.gateway.enabled }}
-{{- $gateway := dict "enabled" true "host" "0.0.0.0" "port" .Values.gateway.port "workers" .Values.gateway.workers "url" (printf "http://127.0.0.1:%v" .Values.gateway.port) "openviking_url" (printf "http://127.0.0.1:%v" (.Values.config.server.port | default 1933)) "storage_path" (printf "%s/gateway" .Values.persistence.mountPath) }}
+{{- $gateway := dict "enabled" true "storage_path" (printf "%s/gateway" .Values.persistence.mountPath) }}
{{- $_ := set $config "gateway" (mergeOverwrite $gateway ($config.gateway | default dict)) }}
{{- end }}
{{- if empty $config.storage.workspace }}
diff --git a/deploy/helm/openviking/templates/deployment.yaml b/deploy/helm/openviking/templates/deployment.yaml
index 62303047b..088389c93 100644
--- a/deploy/helm/openviking/templates/deployment.yaml
+++ b/deploy/helm/openviking/templates/deployment.yaml
@@ -47,12 +47,19 @@ spec:
image: {{ include "openviking.image" . | quote }}
imagePullPolicy: {{ .Values.image.pullPolicy }}
env:
- {{- if .Values.gateway.enabled }}
- - name: OPENVIKING_GATEWAY_ADMIN_TOKEN
+ {{- if and .Values.gateway.enabled .Values.gateway.existingSecret }}
+ - name: OPENVIKING_GATEWAY_MANAGEMENT_KEY
valueFrom:
secretKeyRef:
- name: {{ required "gateway.existingSecret is required" .Values.gateway.existingSecret }}
- key: admin-token
+ name: {{ .Values.gateway.existingSecret }}
+ key: management-key
+ optional: true
+ - name: OPENVIKING_GATEWAY_ENCRYPTION_KEY
+ valueFrom:
+ secretKeyRef:
+ name: {{ .Values.gateway.existingSecret }}
+ key: encryption-key
+ optional: true
{{- end }}
- name: OPENVIKING_CONFIG_FILE
value: {{ printf "%s/ov.conf" .Values.persistence.mountPath | quote }}
@@ -86,40 +93,6 @@ spec:
mountPath: {{ printf "%s/ov.conf" .Values.persistence.mountPath | quote }}
subPath: ov.conf
readOnly: true
- {{- if .Values.gateway.enabled }}
- - name: gateway
- image: {{ include "openviking.image" . | quote }}
- imagePullPolicy: {{ .Values.image.pullPolicy }}
- command: ["openviking-gateway"]
- args: ["--config", {{ printf "%s/ov.conf" .Values.persistence.mountPath | quote }}]
- env:
- - name: OPENVIKING_GATEWAY_ADMIN_TOKEN
- valueFrom:
- secretKeyRef:
- name: {{ .Values.gateway.existingSecret }}
- key: admin-token
- - name: OPENVIKING_GATEWAY_ENCRYPTION_KEY
- valueFrom:
- secretKeyRef:
- name: {{ .Values.gateway.existingSecret }}
- key: encryption-key
- ports:
- - name: gateway
- containerPort: {{ .Values.gateway.port }}
- readinessProbe:
- httpGet:
- path: /health
- port: gateway
- resources:
- {{- toYaml .Values.gateway.resources | nindent 12 }}
- volumeMounts:
- - name: data
- mountPath: {{ .Values.persistence.mountPath }}
- - name: config
- mountPath: {{ printf "%s/ov.conf" .Values.persistence.mountPath | quote }}
- subPath: ov.conf
- readOnly: true
- {{- end }}
volumes:
- name: config
configMap:
diff --git a/deploy/helm/openviking/templates/ingress.yaml b/deploy/helm/openviking/templates/ingress.yaml
index 1d4ad8e8d..2bfd27a9c 100644
--- a/deploy/helm/openviking/templates/ingress.yaml
+++ b/deploy/helm/openviking/templates/ingress.yaml
@@ -28,17 +28,6 @@ spec:
- host: {{ .host | quote }}
http:
paths:
- {{- if $.Values.gateway.enabled }}
- {{- range list "/v1" "/api/v3" "/api/compatible/v1" "/gateway/uploads" }}
- - path: {{ . }}
- pathType: Prefix
- backend:
- service:
- name: {{ include "openviking.fullname" $ }}
- port:
- name: gateway
- {{- end }}
- {{- end }}
{{- range .paths }}
- path: {{ .path }}
pathType: {{ .pathType }}
diff --git a/deploy/helm/openviking/templates/service.yaml b/deploy/helm/openviking/templates/service.yaml
index 356ce92bf..d0fcb4791 100644
--- a/deploy/helm/openviking/templates/service.yaml
+++ b/deploy/helm/openviking/templates/service.yaml
@@ -7,12 +7,6 @@ metadata:
spec:
type: {{ .Values.service.type }}
ports:
- {{- if .Values.gateway.enabled }}
- - port: {{ .Values.gateway.port }}
- targetPort: gateway
- protocol: TCP
- name: gateway
- {{- end }}
- port: {{ .Values.service.port }}
targetPort: http
protocol: TCP
diff --git a/deploy/helm/openviking/values.yaml b/deploy/helm/openviking/values.yaml
index 34ac4aa62..c4ca7b6bd 100644
--- a/deploy/helm/openviking/values.yaml
+++ b/deploy/helm/openviking/values.yaml
@@ -2,15 +2,12 @@
replicaCount: 1
-# Same pod, separate process and port. Multiple workers share local SQLite WAL.
-# Create a Secret with encryption-key (Fernet) and admin-token (32+ characters).
-# Requires authenticated OpenViking; dev mode only permits a loopback gateway.
+# Gateway runs inside the server under /gateway on the same port and uses the server's encryption settings.
gateway:
enabled: false
- workers: 2
- port: 1935
+ # Optional Secret name. Entries (each optional): management-key (32+ characters) and
+ # encryption-key (the v0.5.0 gateway key, read only to migrate old data).
existingSecret: ""
- resources: {}
image:
# Prefer ghcr.io. If it is hard to reach, use the mirror:
diff --git a/docker-compose.yml b/docker-compose.yml
index 44fb71d91..73b1785f5 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -16,22 +16,6 @@ version: "3.8"
# See docs/en/guides/12-public-access.md for the full walkthrough.
services:
- gateway:
- profiles: [gateway]
- image: ghcr.io/volcengine/openviking:latest
- entrypoint: [openviking-gateway]
- command: [--config, /app/.openviking/ov.conf]
- volumes:
- - ~/.openviking:/app/.openviking
- environment:
- OPENVIKING_GATEWAY_ENCRYPTION_KEY: ${OPENVIKING_GATEWAY_ENCRYPTION_KEY:-}
- OPENVIKING_GATEWAY_ADMIN_TOKEN: ${OPENVIKING_GATEWAY_ADMIN_TOKEN:-}
- expose:
- - "1935"
- restart: unless-stopped
- depends_on:
- - openviking
-
openviking:
# Prefer ghcr.io. If it is hard to reach, use the mirror:
# image: openviking-cn-beijing.cr.volces.com/volcengine/openviking:latest
@@ -44,7 +28,11 @@ services:
volumes:
- ~/.openviking:/app/.openviking
environment:
- OPENVIKING_GATEWAY_ADMIN_TOKEN: ${OPENVIKING_GATEWAY_ADMIN_TOKEN:-}
+ # Set OPENVIKING_GATEWAY_ENABLED=true in .env to run the gateway on this port.
+ OPENVIKING_GATEWAY_ENABLED: ${OPENVIKING_GATEWAY_ENABLED:-}
+ OPENVIKING_GATEWAY_MANAGEMENT_KEY: ${OPENVIKING_GATEWAY_MANAGEMENT_KEY:-}
+ # Only read once, to migrate data stored by the v0.5.0 gateway.
+ OPENVIKING_GATEWAY_ENCRYPTION_KEY: ${OPENVIKING_GATEWAY_ENCRYPTION_KEY:-}
OPENVIKING_PUBLIC_BASE_URL: ${OPENVIKING_PUBLIC_BASE_URL:-}
OPENVIKING_SERVER_PORT: ${OPENVIKING_SERVER_PORT:-1933}
healthcheck:
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.md
index f4603bf3b..b9707b347 100644
--- a/docs/en/api/01-overview.md
+++ b/docs/en/api/01-overview.md
@@ -530,12 +530,29 @@ This catalog follows the routes actually mounted by the server. Each group headi
### [OpenViking Gateway Management](25-gateway.md)
+When the gateway runs inside the server, use the server's port; when it runs standalone, use the gateway's own port. The OpenViking API key decides which account the caller can reach. If the deployer set a gateway management key, changing upstreams and context profiles also requires it. Every user can issue gateway keys for themselves. The access matrix and error reasons are in the [Gateway Management API](25-gateway.md).
+
| Method | Path | Description |
|--------|------|-------------|
-| GET | `/api/v1/admin/gateway/{path}` | Read gateway overview, logs, upstreams, context profiles, keys or tools for the caller's account |
-| POST | `/api/v1/admin/gateway/{path}` | Issue a gateway key, test an upstream or reset conversation saving |
-| PUT | `/api/v1/admin/gateway/{path}` | Create or replace an upstream or context profile |
-| DELETE | `/api/v1/admin/gateway/{path}` | Delete an upstream or context profile, revoke a key or delete a user's gateway data |
+| GET | `/gateway/admin/access` | Read the caller's permissions and deployment warnings |
+| GET | `/gateway/admin/guides` | Read the gateway address clients use |
+| GET | `/gateway/admin/tools` | List the OpenViking tools available to the caller |
+| GET | `/gateway/admin/upstreams/{identifier}` | Read one upstream |
+| GET | `/gateway/admin/policies/{identifier}` | Read one context profile |
+| GET | `/gateway/admin/keys/{identifier}` | Read one gateway key (without the secret) |
+| GET | `/gateway/admin/overview` | Read the usage overview within the caller's scope |
+| GET | `/gateway/admin/logs` | Read the request logs the caller can see |
+| GET | `/gateway/admin/upstreams` | List the account's upstreams |
+| PUT / DELETE | `/gateway/admin/upstreams/{identifier}` | Create/replace or delete an upstream |
+| POST | `/gateway/admin/upstreams/{identifier}/test` | Test an upstream connection |
+| POST | `/gateway/admin/upstreams/import-vlm` | Import the server's VLM settings as upstreams (embedded only) |
+| GET | `/gateway/admin/policies` | List the account's context profiles |
+| PUT / DELETE | `/gateway/admin/policies/{identifier}` | Create/replace or delete a context profile |
+| GET / POST | `/gateway/admin/keys` | List the gateway keys the caller can see, or issue a new one |
+| DELETE | `/gateway/admin/keys/{identifier}` | Revoke a gateway key |
+| POST | `/gateway/admin/keys/{identifier}/capture/reset` | Start saving a conversation again |
+| DELETE | `/gateway/admin/users/{user_id}/data` | Admin or root: delete a user's gateway data |
+| DELETE | `/gateway/admin/account/data` | Root: delete an account's gateway data |
### [OpenViking Assets](22-openviking-assets.md), [WebDAV](20-webdav.md), [Agent Runtime API](23-agent-runtime.md), and [VikingBot API](24-vikingbot.md)
diff --git a/docs/en/api/25-gateway.md b/docs/en/api/25-gateway.md
index 568afe616..04552776a 100644
--- a/docs/en/api/25-gateway.md
+++ b/docs/en/api/25-gateway.md
@@ -1,215 +1,222 @@
# OpenViking Gateway Management API
-OpenViking Server forwards OpenViking Gateway management calls below `/api/v1/admin/gateway`. Studio's OpenViking Gateway page uses these endpoints to manage upstreams, context profiles and gateway keys, and to read request logs. Model traffic does not go through this API; clients send it to the gateway's own port (see [OpenViking Gateway](../guides/15-gateway.md)).
+The management API lets you check permissions, configure upstreams and context profiles, issue gateway keys, and read usage and logs. All paths start with `/gateway/admin/` and are served by the gateway itself: when the gateway runs inside OpenViking Server, use the server's port (1933 by default); when it runs standalone, use the gateway's own port (1935 by default). The examples set `SERVER_URL` to that address without any path, such as `http://127.0.0.1:1933`.
-**Prerequisites**:
+Model clients do not call these endpoints. They use a gateway key on `/gateway/v1/*`, `/gateway/api/v3/*` or `/gateway/api/compatible/v1/*`; see [OpenViking Gateway](../guides/15-gateway.md#connect-clients).
-- `gateway.enabled` is `true` in `ov.conf`, and the gateway process is reachable at `gateway.url`.
-- OpenViking Server and the gateway share the admin token (`OPENVIKING_GATEWAY_ADMIN_TOKEN` by default, at least 32 characters).
-- The caller uses an ADMIN key or the root key. USER keys get `403`.
+## Credentials and account scope
-**Code entry points**:
+Every management request carries an OpenViking API key in `X-API-Key` or `Authorization: Bearer`. The gateway asks OpenViking which account, user and role the key belongs to, and caches the answer for up to 30 seconds. Local dev mode needs no key; the caller is always the root identity `default/default`. The gateway does not support trusted authentication.
-- `openviking/server/routers/gateway.py` - OpenViking Server proxy, role check and account scoping
-- `openviking_gateway/app.py` - gateway management routes
-- `openviking_gateway/models.py` - upstream, context profile and key models
+Upstreams and context profiles (called `policies` in the API) belong to an account and are shared by its users. A request acts on the caller's account by default. Root can name another account with the `account_id` query parameter; admins and users can only reach their own account.
-## How the proxy works
+The deployer can also set a gateway management key (see [Gateway management key](../guides/22-gateway-operations.md#gateway-management-key)). Once it is set, requests that change upstreams or context profiles must carry it in `X-OpenViking-Gateway-Management-Key`, including requests from OpenViking admins and root. A request that carries a wrong management key gets 401 `management_key_invalid` right away; it is not quietly treated as read-only.
-| Method | Path | Description |
-|--------|------|-------------|
-| GET / POST / PUT / DELETE | `/api/v1/admin/gateway/{path}` | Forwarded to `{gateway.url}/admin/{path}` for the caller's account |
-
-Every request to `/api/v1/admin/gateway/{path}` is sent to `{gateway.url}/admin/{path}` with the same method, query string and body. OpenViking Server replaces the caller's credentials with the admin token and adds `X-OpenViking-Account` set to the caller's account, so every call reads and changes only that account's gateway objects. An account admin cannot reach another account's data, and the caller cannot choose the destination.
-
-Only these first path segments are forwarded: `overview`, `logs`, `guides`, `upstreams`, `policies`, `keys`, `users` and `tools`. Any other path, or a path containing `..`, returns `404`. The gateway's response status and body are returned unchanged.
+| Operation | No management key set | Management key set |
+| --- | --- | --- |
+| Read upstreams and context profiles, test upstreams | Any user in the account | Any user in the account; the management key alone also works, for any account |
+| Create, change or delete upstreams and context profiles | Any user in the account | Only requests with the correct management key |
+| Import OpenViking's model settings | Root in an embedded deployment (including local dev) | Only requests with the correct management key, and only in an embedded deployment |
+| Issue, read and revoke gateway keys; reset saving | Users: their own keys; admins: their account; root: the selected account | Same; the management key adds no rights |
+| Read logs and the overview | Users: their own records; admins and root: the whole account | Same; always needs an OpenViking identity |
+| Delete a user's gateway data | An admin of that account, or root | Same |
+| Delete an account's gateway data | Root | Same |
-## API Reference
+The management key works on its own, without an OpenViking API key, which suits automation scripts. With it alone you can read and write upstreams and context profiles and call `/access`, choosing the account with `account_id` (`default` when omitted). Issuing keys and reading logs and the overview always need an OpenViking identity, and sending both credentials does not give those operations any extra rights. Setting, changing or removing the management key does not affect gateway keys already issued.
-Paths in the tables are relative to `/api/v1/admin/gateway/`. The management API calls context profiles `policies`.
+Read-only views of upstreams leave out the API key, header values and header names; they keep only `has_api_key` and `auth_mode`.
-### Overview and logs
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `overview` | Usage summary of the latest 10,000 log records: request count, output tokens, cache hit ratios for first calls and continuations, degradations, recall statistics and saving problems, plus OpenViking health and `log_retention_days` |
-| GET | `logs?limit=200` | Newest request log records; `limit` is 1–1000, default 200 |
-| GET | `guides` | Address clients should use: `base_url` and `public_url_configured` |
-| GET | `tools` | OpenViking tools a context profile can offer: `name`, `description` and, when present, `annotations` |
+## Access and discovery
-`tools` reads the tool list with the OpenViking key bound to one of the account's gateway keys. It returns an empty list while the account has no gateway keys, and an error when none of them can read it.
+| Method | Path | Returns |
+| --- | --- | --- |
+| GET | `/gateway/admin/access` | The caller's permissions: `managed`, `can_write_objects`, `can_import_vlm`, `can_issue_for_others`, `role`, `account_id`, `user_id`, `warnings` |
+| GET | `/gateway/admin/overview` | A summary of the latest 10,000 log records the caller can see: usage, cache hits, recall, saving problems, OpenViking status and log retention |
+| GET | `/gateway/admin/logs` | The newest log records the caller can see; `limit` defaults to 200, range 1–1000 |
+| GET | `/gateway/admin/guides` | The client address `base_url`, plus `public_url_configured`; `base_url` is `public_url` followed by `/gateway`, or the request's origin followed by `/gateway` when `public_url` is empty |
+| GET | `/gateway/admin/tools` | The OpenViking tools available to the caller, with names, descriptions and annotations, read with the caller's own OpenViking key (root: with the OpenViking key of a gateway key issued in this account, or the last catalog read, since OpenViking refuses root on `/mcp`) |
-**HTTP API**
+Studio decides which buttons to show from `/access` alone, and your own management tools should do the same. When a standalone gateway connects to the public OpenViking service without a management key, `warnings` includes `public_openviking_without_management_key`. It is only a warning and does not restrict anything.
```bash
-curl http://localhost:1933/api/v1/admin/gateway/overview \
- -H "X-API-Key: your-admin-key"
+curl "$SERVER_URL/gateway/admin/access" \
+ -H "X-API-Key: $OPENVIKING_API_KEY"
```
-**Response Example**
-
```json
{
- "requests": 128,
- "last_request_at": 1785000000.0,
- "output_tokens": 45210,
- "cache": {
- "first_call": {"requests": 40, "input_tokens": 320000, "cached_tokens": 250000, "cache_hit_ratio": 0.78},
- "continuation": {"requests": 88, "input_tokens": 910000, "cached_tokens": 860000, "cache_hit_ratio": 0.95}
- },
- "degradations": {},
- "recall_count": 96,
- "recall_requests": 40,
- "recall_ms": 182.5,
- "capture_issues": {"retrying": 0, "paused": 0},
- "sample_limit": 10000,
- "openviking": {"status": "ok", "healthy": true, "version": "0.4.16", "auth_mode": "api_key"},
- "log_retention_days": 30
+ "managed": true,
+ "can_write_objects": false,
+ "can_import_vlm": false,
+ "can_issue_for_others": true,
+ "role": "admin",
+ "account_id": "team",
+ "user_id": "alice",
+ "warnings": []
}
```
-### Upstreams and context profiles
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `upstreams` | List upstreams |
-| PUT | `upstreams/{upstream_id}` | Create or replace an upstream |
-| DELETE | `upstreams/{upstream_id}` | Delete an upstream |
-| POST | `upstreams/{upstream_id}/test` | Check that the gateway can reach the provider's model list |
-| GET | `policies` | List context profiles |
-| PUT | `policies/{policy_id}` | Create or replace a context profile |
-| DELETE | `policies/{policy_id}` | Delete a context profile |
-
-The caller chooses `upstream_id` and `policy_id`. A `PUT` body is the complete object, and unknown fields are rejected. For every field, its default and limits, see the upstream and context profile settings in the [configuration reference](../guides/22-gateway-operations.md#configuration-reference).
-
-Upstream `api_key` and `headers` values are write-only. Responses replace them with `has_api_key` and `header_names`. On `PUT`, a blank `api_key` keeps the stored key; omitting `headers` keeps every stored header, and a blank header value keeps the stored value for that name.
+If OpenViking rejects the API key, the response is 401 `openviking_http_401`.
-Deleting an upstream or context profile that a gateway key still uses returns `409`; revoke or update those keys first.
+## Upstreams and context profiles
-**HTTP API**
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/gateway/admin/upstreams` | List upstreams |
+| GET | `/gateway/admin/upstreams/{identifier}` | Read one upstream |
+| PUT | `/gateway/admin/upstreams/{identifier}` | Create or replace an upstream |
+| DELETE | `/gateway/admin/upstreams/{identifier}` | Delete an upstream no key uses |
+| POST | `/gateway/admin/upstreams/{identifier}/test` | Test the upstream connection |
+| POST | `/gateway/admin/upstreams/import-vlm` | Import OpenViking's model settings |
+| GET | `/gateway/admin/policies` | List context profiles |
+| GET | `/gateway/admin/policies/{identifier}` | Read one context profile |
+| PUT | `/gateway/admin/policies/{identifier}` | Create or replace a context profile |
+| DELETE | `/gateway/admin/policies/{identifier}` | Delete a context profile no key uses |
+
+The caller chooses the IDs. `PUT` takes the complete object, and unknown fields fail validation. The meaning, default and range of every field are in the [Configuration reference](../guides/22-gateway-operations.md#configuration-reference).
+
+An upstream's `api_key` and `headers` are write-only:
+
+- While `base_url` stays the same, a blank or missing `api_key` keeps the stored key, and a missing `headers` keeps all stored headers. A `headers` object replaces the whole set; an entry with an empty value keeps the value stored under that name.
+- **Changing `base_url` clears the stored API key and all header values.** Send the credentials the new address needs in the same request, so a stored key is never sent to a different address.
+- The editable view returns `has_api_key` and `header_names`, never the values.
```bash
-curl http://localhost:1933/api/v1/admin/gateway/upstreams \
- -H "X-API-Key: your-admin-key"
+curl -X PUT "$SERVER_URL/gateway/admin/upstreams/openai?account_id=team" \
+ -H "X-OpenViking-Gateway-Management-Key: $GATEWAY_MANAGEMENT_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"name":"OpenAI","protocol":"chat","base_url":"https://api.openai.com/v1","api_key":"<provider-key>"}'
```
-**Response Example**
+Deleting an object that gateway keys still use returns 409 `in_use` with `key_count`. Revoke those keys first. If you only want requests to stop reaching an upstream right away, turn it off instead of deleting it.
-```json
-[
- {
- "id": "openai",
- "revision": 2,
- "name": "OpenAI",
- "protocol": "chat",
- "vendor": "openai",
- "base_url": "https://api.openai.com/v1",
- "auth_mode": "managed",
- "has_api_key": true,
- "header_names": [],
- "models": ["gpt-5"],
- "aliases": {},
- "context_windows": {},
- "priority": 0,
- "enabled": true,
- "allow_gateway_tools": true,
- "coding_plan": false,
- "allow_coding_plan": false,
- "cache_min_tokens": 1024
- }
-]
-```
+### Connection tests
-`upstreams/{upstream_id}/test` returns `{"ok": true, "status": 200}` with the provider's status, or `{"ok": false, "reason": "upstream_unavailable"}` when the provider cannot be reached within 10 seconds.
+`POST /gateway/admin/upstreams/{identifier}/test` asks the provider for its model list with the stored credentials, with a 10-second timeout, and returns `{ok, status, reason, url}`. `status` is left out when no response arrived. Read-only callers can run it too. Anthropic upstreams send the key in both `x-api-key` and `Authorization: Bearer`; Chat Completions and Responses upstreams send only Bearer.
-### Gateway keys
+| Provider response | `reason` | `ok` |
+| --- | --- | --- |
+| No API key to use: none is stored, or the upstream expects each client to send its own. No request is sent. | `upstream_key_missing` | `false` |
+| 2xx with a `data` array in the body | `passed` | `true` |
+| 2xx with a body that signals failure, or 401 or 403 | `upstream_key_rejected` | `false` |
+| 404 or 405: the address answers, but the provider has no model list, so the key is not verified | `models_unavailable` | `true` |
+| 429: the address answers | `rate_limited` | `true` |
+| Network error or 5xx | `upstream_unavailable` | `false` |
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `keys` | List gateway keys without their secrets |
-| POST | `keys` | Issue a gateway key; the secret appears only in this response |
-| DELETE | `keys/{key_id}` | Revoke a gateway key |
-| POST | `keys/{key_id}/capture/reset` | Make conversation saving for one session resync from the next request |
+A passed test only shows that the address and key work. It does not show that a particular model is available, or that the upstream may be used with a Coding Plan.
+
+### Import VLM settings
+
+`POST /gateway/admin/upstreams/import-vlm` turns OpenViking Server's VLM credentials into upstreams in the selected account. It is available only in embedded deployments; a standalone gateway returns 404 `vlm_import_unavailable`.
-`POST keys` body:
+Each imported upstream gets the fixed ID `vlm-<credential id>`, so importing again does not create duplicates. A repeat import refreshes the fields that come from the server (`base_url`, `api_key`, `headers`, `protocol`, `vendor`, `coding_plan`) and keeps every other field as it was edited in the gateway, including `name`, `enabled`, `priority`, `models`, `aliases`, `context_windows` and `allow_coding_plan`. Upstreams whose path has a `coding` or `plan` segment are marked as Coding Plan and listed under `needs_confirmation` until `allow_coding_plan` is set.
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Display name |
-| `openviking_key` | string | Conditional | OpenViking key of the user the gateway key acts for; send this or `user_id` |
-| `user_id` | string | Conditional | User in the caller's account; OpenViking Server reads that user's key. Only account admins can use it |
-| `policy_id` | string | Yes | Context profile |
-| `upstream_ids` | string[] | Yes | At least one upstream |
-| `models` | string[] | No | Allowed models; empty allows every model the upstreams serve |
+```json
+{
+ "imported": [{"id": "vlm-default", "name": "default"}],
+ "needs_confirmation": [{"id": "vlm-coding", "name": "coding"}],
+ "skipped": [{"id": "vlm-codex", "reason": "openai_codex"}]
+}
+```
-The OpenViking key must belong to a USER or ADMIN of the caller's account. `user_id` works only when OpenViking Server can read stored user keys; with key hashing enabled, send `openviking_key` instead. Root callers must also send `openviking_key`, because the root key may resolve to a different account than the one Studio shows.
+| Skip `reason` | Meaning |
+| --- | --- |
+| `openai_codex` | Codex OAuth tokens refresh periodically, so the gateway cannot use them long term. |
+| `azure` | Azure OpenAI needs an `api-version` parameter, which the gateway does not send. |
+| `litellm_no_api_base` | The LiteLLM credential has no `api_base`. Add it in the OpenViking configuration and import again. |
+| `litellm_unsupported_route` | The LiteLLM route does not use the OpenAI Chat Completions API, such as `gemini/`, `bedrock/` or `vertex_ai/`. Add that provider as an upstream by hand. |
+| `invalid_configuration` | The credential does not make a valid upstream, for example because the base URL is invalid. |
-Existing keys cannot be edited; `PUT keys/{key_id}` returns `405`. Issue a replacement and revoke the old key.
+## Gateway keys
-**HTTP API**
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/gateway/admin/keys` | List the keys the caller can see, without the secret |
+| GET | `/gateway/admin/keys/{identifier}` | Read one visible key |
+| POST | `/gateway/admin/keys` | Issue a key; `key` in the response is the only time the full secret is returned |
+| DELETE | `/gateway/admin/keys/{identifier}` | Revoke a key; user data is kept |
+| POST | `/gateway/admin/keys/{identifier}/capture/reset` | Start saving a conversation again |
+| DELETE | `/gateway/admin/users/{user_id}/data` | Admin or root: revoke all of the user's keys and delete their conversation state and logs |
+| DELETE | `/gateway/admin/account/data` | Root: delete all of the account's gateway objects, keys, conversation state and logs |
+
+Request body for issuing a key:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `name` | Yes | Display name. |
+| `policy_id` | Yes | The context profile to use. |
+| `upstream_ids` | Yes | The upstreams the key may use; at least one. |
+| `models` | No | Allowed model names (as clients send them, including aliases); an empty list allows all. |
+| `user_id` | No | The OpenViking user the key belongs to; defaults to the caller. Root is not an account user, so root must name one (or supply `openviking_key`). Users can only name themselves. |
+| `openviking_key` | No | That user's OpenViking API key. Usually not needed; see below. |
+
+The gateway needs the target user's OpenViking API key, because it searches and saves memory as that user:
+
+- When callers (users or admins) issue a key for themselves, the gateway uses the caller's own key.
+- When an admin or root issues a key for someone else, the gateway reads that user's key from OpenViking with the caller's credentials. If OpenViking stores only key hashes, it cannot, and the response is 409 `user_key_unreadable`; supply the user's key in `openviking_key`.
+- The gateway checks the key with OpenViking: it must belong to the selected account and, when `user_id` is given, to that user.
+- A root API key cannot be bound to a gateway key, except `default/default` in local dev.
```bash
-curl -X POST http://localhost:1933/api/v1/admin/gateway/keys \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-admin-key" \
- -d '{"name":"alice laptop","user_id":"alice","policy_id":"default","upstream_ids":["openai"]}'
+curl -X POST "$SERVER_URL/gateway/admin/keys?account_id=team" \
+ -H "X-API-Key: $OPENVIKING_API_KEY" -H "Content-Type: application/json" \
+ -d '{"name":"Alice laptop","user_id":"alice","policy_id":"default","upstream_ids":["openai"]}'
```
-**Response Example**
-
```json
{
- "id": "3f6c…",
- "revision": 1,
- "name": "alice laptop",
+ "id": "3f9c…",
+ "name": "Alice laptop",
+ "user_id": "alice",
"policy_id": "default",
"upstream_ids": ["openai"],
"models": [],
- "user_id": "alice",
- "prefix": "ovgw_Xk3p9Q",
- "created_at": 1785000000.0,
- "key": "ovgw_Xk3p9Q…"
+ "prefix": "ovgw_Xk2pQ7a",
+ "created_at": 1760000000.0,
+ "revision": 1,
+ "key": "ovgw_Xk2pQ7a…"
}
```
-`keys/{key_id}/capture/reset` takes `{"session": "<session>", "protocol": "chat"}`, where `protocol` is `anthropic`, `chat` or `responses`. `session` is either the session header value the client sent, such as `X-OpenViking-Session`, or the `session` field of the request's log record; a session without a header can only be named by the latter. It returns `{"status": "ready", "message": "…"}`, or `404` when the key or session does not exist.
+Save the `key` from the response right away; the gateway keeps only its hash. `GET` returns the same fields without `key`. Gateway keys cannot be changed and have no `PUT`. To change the context profile, upstreams, models or user, issue a new key and revoke the old one.
-### User data
+When the user's OpenViking API key is regenerated or the user is deleted, the gateway keys bound to it stop working and are deleted; the user's data stays. See [Gateway keys](../guides/22-gateway-operations.md#gateway-keys).
-| Method | Path | Description |
-|--------|------|-------------|
-| DELETE | `users/{user_id}/data` | Revoke all of a user's gateway keys and delete their conversation state in the gateway |
+**Resetting saving.** The body is `{"session":"<session header value or the session from the log>","protocol":"chat"}`, where `protocol` is `chat`, `anthropic` or `responses`. On success the response is `{"status":"ready","message":"…"}`, and on the conversation's next request the gateway writes the full history to a new OpenViking session. If the conversation is not found, the response is 404 `not_found`.
-Sessions already saved to OpenViking are not affected.
+**Deleting data.** Both delete endpoints remove conversation content the gateway has not yet saved, and logs. Sessions and memories already stored in OpenViking are not affected. Retention and the other ways data is deleted are described in [Security and data](../guides/22-gateway-operations.md#security-and-data).
## Errors
-Errors raised by OpenViking Server itself use the standard error envelope:
-
-| Status | Code | Cause |
-|--------|------|-------|
-| 400 | `INVALID_ARGUMENT` | Root sent `user_id` in `POST keys`; unknown `user_id` |
-| 400 | `INVALID_ARGUMENT` | `POST keys` sent both `user_id` and `openviking_key` (original status 422) |
-| 403 | `PERMISSION_DENIED` | Caller is not ROOT or ADMIN |
-| 404 | `NOT_FOUND` | Path outside the forwarded resources |
-| 409 | `CONFLICT` | The chosen user's key cannot be read on the server |
-| 503 | `UNAVAILABLE` | OpenViking Gateway is not enabled, the admin token is not configured, or the gateway cannot be reached (original status 502) |
-
-Errors from the gateway pass through with its own status and a body such as `{"detail": "Unknown context policy"}`:
+Error responses from the management API carry a stable top-level `reason` and a short English `detail`. Some carry extra fields, for example:
-| Status | Cause |
-|--------|-------|
-| 400 | `POST keys` names an unknown context profile or upstream |
-| 403 | The OpenViking key belongs to another account |
-| 404 | Unknown resource, key or session |
-| 405 | `PUT keys/{key_id}` |
-| 409 | Deleting an upstream or context profile that keys still use |
-| 422 | Invalid body. The message does not echo submitted values, because they can contain secrets |
-
-When the gateway cannot verify an OpenViking key, the body is `{"error": {"message": "<reason>"}}` with reasons listed in [Issuing a key fails](../guides/22-gateway-operations.md#issuing-a-key-fails).
-
-## Related Documentation
+```json
+{"reason": "in_use", "detail": "Gateway keys still use this object; revoke them first.", "key_count": 2}
+```
-- [OpenViking Gateway](../guides/15-gateway.md) - how the gateway works and how to connect clients
-- [OpenViking Gateway deployment and operations](../guides/22-gateway-operations.md) - deployment, Studio management and configuration reference
-- [Admin](08-admin.md) - accounts, users and roles
+Check `reason`, not the text of `detail`. When the server does not have the gateway enabled, these paths do not exist and return 404; Studio shows this as `not_enabled`.
+
+| HTTP | `reason` | Meaning and fix |
+| --- | --- | --- |
+| 401 | `management_key_invalid` | The management key is wrong. Ask the deployer for the current one. |
+| 403 | `management_key_required` | A management key is set, and changing upstreams or context profiles requires it. |
+| 401 | `openviking_http_401` | OpenViking rejected the API key. Use a currently valid key. |
+| 401 | `openviking_identity_missing` | OpenViking returned no user for this key. |
+| 403 | `trusted_mode_unsupported` | OpenViking uses trusted authentication. Switch to `api_key` authentication. |
+| 403 | `other_account` | The key or the requested account is outside the caller's scope. |
+| 403 | `forbidden` | The operation is beyond the caller's role or user scope. |
+| 403 | `root_key_not_allowed` | A root API key cannot be bound to a gateway key. Use a user's API key. |
+| 409 | `user_key_unreadable` | OpenViking stores only a hash of the user's key. Supply the user's key in `openviking_key`. |
+| 409 | `in_use` | `key_count` gateway keys still use this object. |
+| 400 | `unknown_user`, `unknown_policy`, `unknown_upstream` | The named user, context profile or upstream does not exist. |
+| 400 | `user_required` | Root issued a key without `user_id` or `openviking_key`. Name the user the key is for. |
+| 404 | `not_found` | The object does not exist, or the caller cannot see it. |
+| 422 | `invalid_configuration` | The request body or Base URL is invalid. The error never repeats submitted credentials. |
+| 403 | `vlm_import_forbidden` | The caller may not import; `can_import_vlm` in `/access` is authoritative. |
+| 404 | `vlm_import_unavailable` | A standalone gateway cannot read the server's model settings. Add upstreams by hand. |
+| 503 | `openviking_unavailable`, `openviking_unreachable` | The gateway cannot reach OpenViking. Check that OpenViking is running; for a standalone gateway, also check `openviking_url` (in `gateway.conf` or `OPENVIKING_GATEWAY_OPENVIKING_URL`). |
+| 503 | `openviking_version_mismatch` | Standalone gateways only: OpenViking Server is older than required. `required_version` in the response gives the minimum version. |
+
+Other HTTP errors from OpenViking are reported as `openviking_http_<status>`. The gateway's own generic HTTP errors are reported as `gateway_http_<status>`, for example 405 `gateway_http_405` for an unsupported method.
+
+A 401 that a model client receives is not a management API error. It means the gateway key is missing, wrong or revoked, or the OpenViking key bound to it is no longer valid; see [Clients get an error from the gateway](../guides/22-gateway-operations.md#clients-get-an-error-from-the-gateway).
diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.md
index af22b5dad..f629b4b55 100644
--- a/docs/en/guides/03-deployment.md
+++ b/docs/en/guides/03-deployment.md
@@ -303,7 +303,7 @@ docker compose up -d
After startup, you can access:
- API service: `http://localhost:1933`
- Web Studio: `http://localhost:1933/studio` (same origin as the API)
-- Caddy entry point: `http://localhost:1934`. It proxies to 1933 and is kept for existing deployments. When you also run OpenViking Gateway, it sends the model API paths to the gateway; see [OpenViking Gateway deployment and operations](22-gateway-operations.md#docker-compose).
+- Caddy entry point: `http://localhost:1934`. It proxies every path to 1933 and is kept for existing deployments. With OpenViking Gateway enabled, the gateway is served under `/gateway` on the same port, for example `http://localhost:1933/gateway/v1`; see [OpenViking Gateway deployment and operations](22-gateway-operations.md#docker-compose).
### Deploy on Railway
diff --git a/docs/en/guides/12-public-access.md b/docs/en/guides/12-public-access.md
index 85ba082a4..5f1a059e7 100644
--- a/docs/en/guides/12-public-access.md
+++ b/docs/en/guides/12-public-access.md
@@ -77,7 +77,7 @@ as the issuer in OAuth metadata and `WWW-Authenticate` headers) and Caddy
}
```
-If you also run [OpenViking Gateway](15-gateway.md), use the domain block under [Docker Compose](22-gateway-operations.md#docker-compose) in the gateway's operations guide instead. It sends the model API paths to the gateway and everything else to OpenViking.
+With OpenViking Gateway enabled (`gateway.enabled: true`), the model APIs and the gateway management API are served under `/gateway` on the server port, so this proxy block covers them too. No extra upstream or path-based routing is needed.
### 3. Uncomment HTTPS lines in `docker-compose.yml`
@@ -203,20 +203,14 @@ For Compose, set it in `.env` and run `docker compose up -d`; an `export` in an
## Compatibility note: the `:1934` proxy
-`docker compose up` also ships a Caddy reverse proxy on port 1934. It sends the
-[OpenViking Gateway](15-gateway.md) paths (`/v1/*`, `/api/v3/*`, `/api/compatible/v1/*`
-and `/gateway/uploads`) to the `gateway` service and everything else to
-`openviking:{$OPENVIKING_SERVER_PORT:1933}`. The port is **kept for compatibility with
-deployments that already bookmarked 1934**, and it is how clients reach the gateway over
-plain HTTP, because the gateway's own port is not published (see
-[Docker Compose](22-gateway-operations.md#docker-compose) in the gateway's operations
-guide). New deployments can connect to 1933 on the private network; public clients should use
-the HTTPS entrypoint above. Remove the caddy service and the 1934 port mapping in
-`docker-compose.yml` if you don't need it.
+The bundled Caddy's compatibility port 1934 forwards all paths to `openviking:{$OPENVIKING_SERVER_PORT:1933}`. With OpenViking Gateway enabled, port 1933 serves the regular OpenViking APIs and, under `/gateway`, the model APIs, tool uploads and the gateway management API. You no longer need a separate gateway container, port 1935 or path-based routing rules.
+
+Keep 1934 if existing bookmarks or clients still use it; otherwise remove its port mapping. Public clients should use the HTTPS entrypoint.
+
## Related
- [Deployment Guide](03-deployment.md) — Docker, systemd, Kubernetes
- [OAuth Guide](11-oauth.md) — OAuth 2.1 setup and client onboarding
- [Authentication](04-authentication.md) — API key management
-- [OpenViking Gateway deployment and operations](22-gateway-operations.md) — routes, proxy settings and HTTPS for the gateway
+- [OpenViking Gateway deployment and operations](22-gateway-operations.md) — deploying the gateway, its routes and reverse proxy requirements
diff --git a/docs/en/guides/15-gateway.md b/docs/en/guides/15-gateway.md
index 22f094302..1c0a081f0 100644
--- a/docs/en/guides/15-gateway.md
+++ b/docs/en/guides/15-gateway.md
@@ -4,56 +4,60 @@ description: Give any API-key model client OpenViking memory by pointing it at O
# OpenViking Gateway
-Connect **any** model client that lets you change its base URL to OpenViking Gateway, and it gets OpenViking memory, with the model able to work with that memory itself. The client changes two settings: the base URL points at the gateway, and the model provider's API key is replaced with a gateway key. There is no plugin to install and no code or prompt to change.
+OpenViking Gateway is a model API proxy. Any client that lets you change its base URL can use it to get OpenViking memory. You change two settings: the base URL becomes the gateway address, and the provider's API key becomes a gateway key. There is no plugin to install and no code or prompt to change.
-With OpenViking tools on, the model can search memory, read the original text, note down something new and import material, all within a single reply. The gateway runs these tools itself, so the client does not have to declare or implement any of them. That lets **any** client, whether a chat app, an SDK script or a low-code platform, work with memory the way an agent does.
+For an animated walkthrough of how the gateway works, see [openviking.ai/gateway](https://openviking.ai/gateway).
+
+While it forwards a request, the gateway does three things:
| Capability | What the gateway does |
| --- | --- |
-| Automatic recall | For every new user message, the gateway first searches OpenViking and appends the relevant memory to that message before it reaches the model. On later requests it puts that content back exactly where it was, so the provider's prompt cache stays valid. |
-| Model-driven memory | The model calls OpenViking tools to search, read, write and import. The gateway runs each call and feeds the result back to the model, and the client receives one continuous reply. New context profiles turn this on with read-only tools only. |
-| Saving and compaction | The gateway saves conversations back to OpenViking, which extracts new memories from them. When a conversation nears the model's context window, the gateway has the same model write a summary that replaces the earlier part. |
+| Automatic recall | For each new user message, the gateway searches OpenViking, appends the relevant memory to that message, and then passes it to the model. |
+| Model-driven memory | The model can call OpenViking tools to search, read, write and import material. The gateway runs the tools, so the client does not declare or implement any of them. |
+| Saving and compaction | The gateway saves conversations to OpenViking, which extracts new memories from them. When a conversation nears the model's context window, the gateway has the same model write a summary that replaces the earlier part. |
-**Who it is for**: clients that cannot install a plugin or MCP server, such as chat apps, SDK scripts and low-code platforms, and teams that want to manage model providers, keys and memory settings in one place. **Not for**: clients signed in directly with a subscription (use a [subscription proxy upstream](#custom-upstreams) instead), and clients such as Cursor and Trae whose model calls leave from the vendor's servers.
+**Who it is for**: clients that cannot install a plugin or MCP server, such as chat apps, SDK scripts and low-code platforms, and teams that want to manage providers, keys and memory settings in one place. **Not for**: clients signed in directly with a subscription (use a [subscription proxy upstream](#custom-upstreams) instead), and clients such as Cursor and Trae whose model calls leave from the vendor's servers.
-The gateway accepts the three common model APIs: Anthropic Messages, OpenAI Chat Completions and OpenAI Responses (when each request carries the full history). It forwards every request to a model provider you configure, called an **upstream**, and never converts one API into another.
+The gateway supports three model APIs: Anthropic Messages, OpenAI Chat Completions and OpenAI Responses (when every request carries the full history). It forwards each request to a model endpoint you configure, called an **upstream** in these docs. A request goes out in the same API it came in; the gateway never converts between APIs.
-> **Note**: OpenViking Gateway runs as its own process, `openviking-gateway`, next to OpenViking Server. It is not VikingBot Gateway (`vikingbot gateway`), VikingBot's long-running entry point for remote access and chat platforms; the two are different OpenViking components with different jobs.
+OpenViking Gateway is in beta. This page covers how it works and how to connect clients. For deployment, managing it in Studio and troubleshooting, see [OpenViking Gateway deployment and operations](22-gateway-operations.md).
-OpenViking Gateway is currently in beta. This page explains how the gateway works and how to connect clients. To deploy it for a team and run it day to day, see [OpenViking Gateway deployment and operations](22-gateway-operations.md).
+> **Note**: OpenViking Gateway and VikingBot Gateway (`vikingbot gateway`) are different components. VikingBot Gateway handles remote access and chat platforms.
## Custom upstreams
-Upstreams are customizable: any service compatible with one of these three APIs can be an upstream, not only a model provider itself. Two common uses:
+Any service that speaks one of the three APIs can be an upstream, not only a model provider. Two common uses:
-- **Billing, quotas and load balancing.** The gateway does not handle these. If you need them, run a gateway such as LiteLLM or new-api behind it and add that as an upstream.
-- **Using subscription quota.** Clients cannot sign in to the gateway with a subscription, but you can add a reverse proxy such as [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) as an upstream. It exposes subscription accounts such as ChatGPT (Codex) and Claude as an API, so Codex, for example, can use a ChatGPT subscription through the gateway. Tibo, who leads Codex at OpenAI, has [publicly walked through](https://x.com/thsottiaux/status/2076119366647894371) connecting a Codex subscription with CLIProxyAPI. **Make sure this complies with your provider's terms.**
+- **Billing, quotas and load balancing.** The gateway does none of these. If you need them, put a service such as LiteLLM or new-api behind the gateway and add it as an upstream.
+- **Subscription quota.** Clients cannot sign in to the gateway with a subscription, but you can add a reverse proxy such as [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) as an upstream. It exposes subscription accounts such as ChatGPT (Codex) and Claude as an API, so Codex, for example, can use a ChatGPT subscription through the gateway. Tibo, who leads Codex at OpenAI, has [publicly walked through](https://x.com/thsottiaux/status/2076119366647894371) connecting a Codex subscription this way. **Check that this complies with your provider's terms.**
-See [Upstreams](22-gateway-operations.md#upstreams) for how to add one; choose *Generic* as the provider.
+To add one, choose *Generic* as the provider; see [Upstreams](22-gateway-operations.md#upstreams).
## Architecture at a glance
-![OpenViking Gateway architecture: the client changes only its base URL and API key, and a reverse proxy sends its model requests to the gateway; the gateway searches and saves memory with the user's own OpenViking key, then forwards the request to the upstream model provider in the same API; sessions and memories live in OpenViking, and the gateway host keeps only two encrypted SQLite files](../../images/gateway/architecture.en.svg)
+![OpenViking Gateway in its two forms. Embedded: clients call the OpenViking Server port, which passes everything under /gateway (model APIs, uploads and gateway management) to the gateway in the same process; the gateway searches and saves memory over loopback HTTP with the user's own OpenViking key. Standalone: openviking-gateway on its own port serves the same /gateway paths and a gateway-only Studio, and calls an existing OpenViking service over HTTP(S). Either way the gateway forwards each request to the upstream model provider in the same API, sessions and memories live in OpenViking, and the gateway keeps only two SQLite files (encrypted when OpenViking encryption is on)](../../images/gateway/architecture.en.svg)
-- **Where it runs**: the gateway is a separate service. It can share a machine or a Pod with OpenViking, or run on its own (see [Deployment options](22-gateway-operations.md#deployment-options)). In a shared deployment its port is not exposed; a reverse proxy routes the model API and tool upload paths to the gateway and everything else to OpenViking. For a local trial on one machine, you can skip the proxy.
-- **How it relates to OpenViking**: the gateway only calls OpenViking's public APIs. Embedding and memory extraction happen inside OpenViking.
-- **Where the data lives**: sessions and memories live in OpenViking. The gateway host keeps only two encrypted SQLite files, one for upstreams, keys and settings and one for conversation state. A conversation's state is deleted after 30 days without use. For deletion and isolation, see [Security and data](22-gateway-operations.md#security-and-data).
-- **When something fails**: if OpenViking is unavailable, conversations continue without memory and saving retries automatically. If the gateway is down, every model call that goes through it fails.
-- **Who manages it**: account admins issue a gateway key to each user in Studio. Each key is bound to one OpenViking user, one **context profile** (memory settings such as the recall budget, whether conversations are saved and whether OpenViking tools are offered) and a set of **upstreams** (the model endpoints and API keys requests are forwarded to).
+- **Where it runs**: once enabled, inside OpenViking Server on the server's port. You can also run `openviking-gateway` on its own against an existing OpenViking service, open source or OpenViking Cloud. Either way, every gateway URL is under `/gateway`, such as `/gateway/v1`, so clients use the same paths. See [Deployment options](22-gateway-operations.md#deployment-options).
+- **How it relates to OpenViking**: the gateway only calls OpenViking's public APIs. Embedding and memory extraction happen in OpenViking.
+- **Where the data lives**: sessions and memories live in OpenViking. The gateway host keeps only two SQLite files, encrypted when OpenViking encryption is on, one for upstreams, keys and settings and one for conversation state. See [Security and data](22-gateway-operations.md#security-and-data).
+- **When something fails**: if OpenViking is down, conversations go on without memory and saving retries on its own. If the gateway is down, every model call that goes through it fails.
+- **What you manage**: users in an account share its **upstreams** (model endpoints and their API keys) and **context profiles** (memory settings such as the recall budget, whether conversations are saved and whether OpenViking tools are offered). Each gateway key binds one OpenViking user, one context profile and a set of upstreams. Who may change what is in the [access matrix](../api/25-gateway.md#credentials-and-account-scope).
## What happens once you connect
-Two terms first. **Recall** means searching OpenViking for memory relevant to a message and appending it to that message. **Prompt caching** is a provider billing feature: the part of a request that matches the start of the previous one is billed at the cached rate, and everything from the first differing byte on is billed at the full rate. The cached rate is usually a small fraction of the full price; see each provider's pricing page for the exact figures.
+Two terms first. **Recall** means searching OpenViking for memory related to the current message and appending it to that message. **Prompt caching** is a provider billing feature: the part of a request that matches the start of the previous request is billed at the cached rate, and everything from the first differing byte on is billed at the full rate. The cached rate is usually a small fraction of the full rate; see each provider's pricing.
-| What you do | What you get | What it costs | What to watch |
-| --- | --- | --- | --- |
-| Point the base URL at the gateway and replace the API key with a gateway key. For Claude Code, also set `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` so sub-agent and background requests are labeled and are not recalled for or saved. | Relevant memory added to every new message, plus your user profile at the start of a conversation; conversations saved to OpenViking and turned into new memories; automatic compaction of long conversations; optionally, a model that searches, reads and writes OpenViking itself (see the [next section](#agentic-memory-for-any-client)). | The first model call of each new message waits up to 2 extra seconds; added memory is billed as input tokens, mostly at the cached rate on later requests; the turn that triggers compaction makes one extra model call. | Added memory is invisible in the client (the provider does see it), and Studio's request log records only counts and timing. Without a configured context window, the gateway assumes 1,000,000 tokens when deciding when to compact; for models with smaller windows, ask an admin to set the real window, or long conversations will be rejected by the provider as too long. When the client has an OpenViking plugin, the gateway does not recall, save or offer OpenViking tools for that conversation; when it only has OpenViking MCP tools, the gateway still recalls and saves but does not offer its own tools. |
+What you get: relevant memory on every new message, your user profile at the start of a new conversation, conversations saved to OpenViking and turned into new memories, and automatic compaction of long conversations. With OpenViking tools on, the model can also search, read and write memory itself (see the [next section](#agentic-memory-for-any-client)).
+
+What it costs: the first model call of each new message can wait up to 2 extra seconds; added memory is billed as input tokens, mostly at the cached rate on later requests; and the turn that triggers compaction makes one extra model call.
![What happens in one turn: the gateway recognizes the conversation and the request type, puts earlier memory back exactly as it was, recalls only for the new message, forwards the request to the upstream in the same API and queues the turn for saving; below, how replay keeps the prompt cache hitting, and how saving and compaction work across turns](../../images/gateway/one-turn.en.svg)
-The gateway recognizes when requests belong to the same conversation. Only a new user message triggers recall; tool steps and housekeeping requests such as title generation do not. The rest of this section walks through each step.
+The gateway recognizes requests from the same conversation on its own (see [How conversations are recognized](#how-conversations-are-recognized)). Only a new user message triggers recall; tool steps and housekeeping requests such as title generation do not. The budgets, timings and switches below all come from the key's **context profile**, where an admin can change or turn off each one.
+
+### What the model sees
-**What the model sees.** Model APIs are stateless: the client resends the whole conversation with every request. When a request ends with a new user message, the gateway searches OpenViking with the text of that message and appends the results to the end of the same message:
+Model APIs are stateless: the client resends the whole conversation with every request. When a request ends with a new user message, the gateway searches OpenViking with that message's text and appends the results to the end of the message:
```text
What did we decide about the release date?
@@ -66,11 +70,13 @@ The team moved the 2.0 release to the first week of November.
</openviking-context>
```
-The client never sees this block. It is not part of the reply, and the client's own history stays as it was. The token usage the provider reports, which the gateway passes back unchanged, does include it. Memory is searched once per user message; tool steps, sub-agent calls and housekeeping requests such as title generation reuse what was already added. Within one context window, that is until the conversation is compacted, an entry is added only once, and budgets per message and per context window cap how much is added.
+This block never appears in the reply, and the client's own history does not change. The provider does see it, and the token usage it reports includes it. Each user message is searched once; tool steps and housekeeping requests in the same turn reuse what was already added. Within one context window (until the conversation is compacted), an entry is added only once, and a budget per message and a budget per window cap the total.
-**The opening context.** A new conversation starts with your OpenViking user profile. When the Read tool is enabled, it also gets memory and skill catalogs, so the model can find relevant material beyond the automatic search. These use a separate 4,000-token budget; skills use at most a quarter of it. You can disable the profile or change the budget in the context profile. Unavailable parts are omitted without blocking the conversation.
+### The opening context
-When recall or OpenViking tools are enabled, an opening note explains where these additions come from and which features are active. For example, with recall, saving and three OpenViking tools enabled:
+When a new conversation starts, the gateway adds your OpenViking user profile. When the `read` tool is offered, it also adds memory and skill catalogs, so the model can look beyond what recall found. This opening context has its own 4,000-token budget, at most a quarter of it for skills, and does not count against the recall budget. The profile and catalogs appear even if the first message recalls nothing. A part that fails to load is left out and the conversation goes on. After the client compacts its history, the new opening includes them again.
+
+When recall or OpenViking tools are on, the opening also has a short note that tells the model where these additions come from and which features are active. For example, with recall, saving and three OpenViking tools on:
```text
<openviking-context source="gateway-session-start">
@@ -97,270 +103,197 @@ Relevant memory from OpenViking. Use the openviking_read tool to expand URIs.
</openviking-context>
```
-The profile and catalogs can appear even when the first message has no search results. The opening note and context do not consume the recall budget. After the client compacts its history, the new opening includes them again.
+### Replay
+
+The client's history does not contain what the gateway added. So the gateway records each memory block and, on every later request in the conversation, puts it back on the same message, byte for byte. There are two reasons. Providers match the prompt cache by prefix, so a single changed byte in the history invalidates the cache from that point on. And Claude's thinking signatures cover the earlier conversation, so Claude rejects a history that changed. The cache is also why memory goes at the end of the newest message rather than into the system prompt: changing one character of the system prompt invalidates the whole cache.
+
+### When conversations are saved
-**Replay.** The client's history does not contain what the gateway added, so the gateway keeps its own record of each memory block. On every later request in the conversation, it puts each block back on the message it was first added to, byte for byte. Providers cache prompts by prefix and Claude's thinking signatures cover the earlier conversation, so the history has to stay identical: that keeps the provider cache hitting and keeps Claude from rejecting the conversation. The same reason explains why memory goes at the end of the newest message rather than into the system prompt: changing a single character of the system prompt invalidates the entire cache after it.
+The gateway saves finished turns to an OpenViking session owned by the key's user; these sessions are named `gateway-…`. Saving runs one turn behind. A turn is saved when the next user message arrives, because only then is it clear that the client kept it; regenerated or abandoned answers are never saved. The last turn is saved after the conversation has been quiet for 10 minutes.
-**When conversations are saved.** The gateway saves finished turns to an OpenViking session owned by the key's user; these sessions are named `gateway-…`. A turn is saved when the next user message arrives, which confirms the client kept it, so regenerated or abandoned answers are never saved. The last turn of a conversation is saved after 10 quiet minutes. Then the gateway commits the session, and OpenViking extracts memories from it in the background. The gateway also commits whenever 20,000 tokens are waiting in the session to be committed. Text the gateway added, and client noise such as `<system-reminder>` blocks, are stripped before saving. Sub-agent, housekeeping and token-count requests are never saved.
+After saving, the gateway commits the session, and OpenViking extracts memories from it in the background. A commit happens when the conversation has been quiet for 10 minutes, or when 20,000 tokens are waiting to be committed. Before saving, the gateway strips what it added and client noise such as `<system-reminder>` blocks. Sub-agent, housekeeping and token-count requests are never saved.
-**Long conversations.** When a conversation reaches 90% of the model's context window (the default), the gateway compacts it: the same model writes a bounded summary of the conversation so far, and from then on that summary replaces everything before the cut. Nothing before the cut is kept word for word; the history shown in the client stays as it was. When conversations are saved and the model has the OpenViking grep and read tools, the summary is followed by directions for searching the saved conversation for details. The model writes the summary itself: OpenViking's Working Memory summaries are not used, and new OpenViking sessions the gateway creates have Working Memory turned off. The gateway assumes a 1,000,000-token window unless the upstream or the context profile sets the model's window, so set it for models with smaller windows. Each compaction costs one extra model request and one provider cache miss. See [Long conversations](22-gateway-operations.md#long-conversations) for the details.
+### Long conversations
-All of these numbers come from the key's **context profile**, where you can change budgets and timing or turn each feature off.
+When a conversation reaches 90% of the model's context window, the gateway compacts it: the same model writes a summary of the conversation so far, with a length cap, and from then on the summary replaces everything before the cut. The history shown in the client does not change. When saving is on and the model has the OpenViking `grep` and `read` tools, the summary ends with directions for finding details in the saved conversation. Each compaction costs one extra model request and one provider cache miss.
+
+The gateway needs to know the model's context window. If neither the upstream nor the context profile sets it, the gateway assumes 1,000,000 tokens. For a model with a smaller window, ask an admin to set the real one; otherwise the provider rejects long conversations as too long before compaction starts. Details are in [Long conversations](22-gateway-operations.md#long-conversations).
## Agentic memory for any client
-With automatic recall, the gateway guesses what the model needs. With OpenViking tools on, the model decides for itself what to search, read and remember. The gateway runs the tools, so the client does not declare or implement any of them, and it works even when the request carries no tools at all.
+With automatic recall, the gateway guesses what the model needs. With OpenViking tools on, the model decides for itself what to search, read and remember. The gateway runs the tools, so this works even when the client's request has no tools at all.
![One reply with OpenViking tools: the gateway adds recalled memory and the OpenViking tool definitions to the client's request; when the model calls an OpenViking tool, the gateway runs it with the user's OpenViking key, feeds the result back and asks the model again until it gives a final answer; the client receives one continuous reply with notice lines, and the tool rounds are replayed unchanged in the next turn](../../images/gateway/tool-loop.en.svg)
-- **Several steps in one reply**: the gateway intercepts the OpenViking tool calls the model makes, runs them with the user's OpenViking key, feeds the results back and asks the model again until it stops calling them. The client receives one continuous reply, streaming or not.
+- **Several steps in one reply**: the gateway intercepts the model's OpenViking tool calls, runs them with the user's OpenViking key, feeds the results back and asks the model again, until the model stops calling them. The client receives one continuous reply, streaming or not.
- **The client's own tools still work**: in the same reply, the model can call both OpenViking tools and client tools such as Bash. Client tool calls go to the client unchanged and pass through its permission prompts as usual.
-- **The next turn remembers**: the model's tool calls and the results the gateway fetched are not in the client's history. The gateway stores these tool rounds and replays them unchanged on the next turn, so the model remembers what it found and the prompt cache stays valid.
+- **The next turn remembers**: tool calls and results are not in the client's history, so the gateway stores these rounds and replays them unchanged on the next turn. The model remembers what it found, and the prompt cache keeps working.
### What each kind of client gets
-| Client | Without the gateway | Through the gateway with OpenViking tools on |
+| Client | Without the gateway | Through the gateway, with OpenViking tools on |
| --- | --- | --- |
-| Chat apps, such as Cherry Studio and Open WebUI | Using memory means configuring MCP or writing tools yourself; a plain chat only exchanges text. | The model searches memory, reads the original text by URI, and with `remember` checked notes down what the user asks it to remember. With `add_resource` checked, files the user attaches can be imported into OpenViking: when the client sends the original file, that file is imported; Open WebUI usually sends only the extracted text. The model can call OpenViking tools even in a plain chat mode with no tools at all. |
-| SDK scripts and low-code platforms | One question, one answer; multi-step work needs a loop you write yourself. | One request covers "search → read → grep for exact matches → answer", with no code changes. |
-| Coding agents such as Claude Code and Codex (without the OpenViking plugin or MCP server) | Their own tools, but no OpenViking. | OpenViking tools and client tools such as Bash mix in the same reply, with no plugin or MCP to install. If you want to approve each tool call, the plugin or MCP server is still the better choice. |
+| Chat apps, such as Cherry Studio and Open WebUI | To use memory you set up MCP or write tools yourself; a plain chat only exchanges text. | The model searches memory and reads the original text by URI. With `remember` checked, it notes down what the user asks it to remember; with `add_resource` checked, it imports files the user attaches. This works even in a plain chat mode with no tools. |
+| SDK scripts and low-code platforms | One question, one answer; multi-step work needs a loop you write. | One request covers "search → read → grep for exact matches → answer", with no code changes. |
+| Coding agents such as Claude Code and Codex (without the OpenViking plugin or MCP server) | Their own tools, but no OpenViking. | OpenViking tools and client tools such as Bash mix in the same reply. If you want to approve each tool call, the plugin or MCP server is still the better choice. |
### Which tools the model can use
-The tools come straight from the MCP tool list your OpenViking server provides, with an `openviking_` prefix added to each name, so tools that OpenViking adds later become available automatically. The common groups:
+The tool list comes straight from the MCP tools your OpenViking server provides, each with an `openviking_` prefix. Tools that OpenViking adds later become available on their own. The common groups:
| Purpose | Tools | What the model uses them for |
| --- | --- | --- |
| Search | `find`, `search`, `grep`, `glob` | Semantic search over memory and resources; exact lookups by regular expression or file name. |
| Browse and read | `list`, `tree`, `read` | Expanding a recalled entry to its original text by URI; browsing memory and skill directories. |
-| Write | `remember`, `write`, `edit` | Storing a long-term memory; writing or partially editing memory files. |
-| Import | `add_resource`, `add_skill` | Importing a web page or code repository by URL, importing a chat attachment, creating a skill from a piece of text, all without a shell on the client. |
-| Delete and permissions | `forget`, `set_acl` and others | Permanently deleting memory; changing access to shared resources. |
+| Write | `remember`, `write`, `edit` | Storing a long-term memory; writing or editing memory files. |
+| Import | `add_resource`, `add_skill` | Importing a web page or repository by URL, importing a chat attachment, creating a skill from text, all without a shell on the client. |
+| Delete and permissions | `forget`, `set_acl` and others | Deleting memory permanently; changing access to shared resources. |
-### Turning them on, and the limits
+### Defaults
-- **Read-only tools by default.** New context profiles have **OpenViking tools** on, including those made with **Create with recommended settings**. Only the read-only tools are selected: `find`, `search`, `grep`, `glob`, `list`, `tree`, `read`, `list_watches`, `get_acl`, `list_users`, `list_groups` and `health`. The tools that change data are left unchecked: `remember`, `write`, `edit`, `add_resource`, `add_skill`, `forget`, `set_acl` and `cancel_watch`. To let the model save memories, check `remember`; to let it import web pages or attachments, check `add_resource`. Tools that OpenViking adds later are selected automatically. Existing profiles keep their settings. The full set of tool definitions adds about 3,500 input tokens to every request in the conversation, so unchecking tools nobody needs also saves tokens. Changes apply to new conversations only.
-- **Limits.** Rounds, **Total time** and the token budget are unlimited by default: the model keeps using OpenViking tools until it finishes. In a streaming request, the user can stop the reply at any time; a non-streaming request keeps running after the client disconnects, so set **Total time** if your clients send non-streaming requests. If you set a round limit or token budget, once it is used up the gateway refuses further OpenViking calls and the model answers with the results it already has; if the model keeps calling after being refused, the request fails. If you set **Total time**, a request that runs longer than that fails. A single call that runs longer than 30 seconds returns an error to the model.
-- **Client requirements.** The client must send the full history every turn; with OpenAI Responses it must also set `store: false`. The gateway does not offer OpenViking tools when the client forces a specific tool or asks for structured output, when the upstream has **Allow OpenViking tools** off, or when the upstream is DeepSeek with **Restore reasoning the client drops** off and the request does not turn thinking off. With tools present, DeepSeek requires the reasoning of every earlier reply, which many clients do not send back; DeepSeek upstreams have **Restore reasoning the client drops** on by default, so the gateway puts that reasoning back and tools work with thinking on. See [Upstreams](22-gateway-operations.md#upstreams). Whether a conversation gets tools is decided at its first request that could use them, and they are turned off if the client turns out to have OpenViking tools of its own.
+New context profiles have OpenViking tools on, but only the read-only tools for searching, browsing and reading are selected. Tools that change data, such as `remember`, `add_resource` and `forget`, stay off until an admin checks them. Rounds, total time and the token budget are unlimited by default, so the model keeps using tools until it is done.
-For the full conditions, limit settings, file imports and failure handling, see [OpenViking tools](22-gateway-operations.md#openviking-tools).
+The client must send the full history every turn; with Responses it must also set `store: false`. The gateway does not offer its tools when the client forces a specific tool, asks for structured output, or already has OpenViking tools of its own. For the full default tool list, the limits, file imports and every reason tools are left out, see [OpenViking tools](22-gateway-operations.md#openviking-tools).
### What users see
-The model's text streams as usual. Each OpenViking tool call leaves a one-line notice in the reply: it appears when the call starts, and `done`, `failed` or `skipped` is added when it ends:
+The model's text streams as usual. Each OpenViking tool call leaves a one-line notice in the reply. It appears when the call starts, and `done`, `failed` or `skipped` is added when the call ends:
```text
> OpenViking find: "the release date we agreed on" — done
> OpenViking read: viking://user/alice/memories/release.md — done
```
-A notice shows only the tool name and what it works on, such as the query or URI; users never see the full arguments or the results. Notices are not sent to the model or saved to OpenViking, and an admin can turn them off in the context profile. The token usage the client receives is the sum of every model call in the reply.
+A notice shows only the tool name and what it works on, such as the query or URI. Users never see the full arguments or the results. The model does not see the notices, and the gateway does not save them to OpenViking; an admin can turn them off in the context profile. The token usage the client receives is the sum of every model call in the reply.
-### Costs and admin controls
+### Risks and controls
-> **Note**: Selected tools run without the client's permission prompts, including tools that write or delete data. A notice tells the user what already happened; it is not a request for approval. The model can do no more than the user's own OpenViking permissions allow.
+> **Note**: Selected tools run without the client's permission prompts, including tools that write or delete data. A notice reports what already happened; it does not ask for approval. The model can never do more than the user's own OpenViking permissions allow.
-- **Narrow the tool list.** For profiles used by chat apps, we recommend unchecking at least `forget` and `set_acl`. This is a recommendation, not the default.
-- **Four controls**: the on/off switch in the context profile, the per-tool checkboxes, each upstream's **Allow OpenViking tools** switch, and the limits on tool rounds and tokens.
-- **Gateway tools or a plugin/MCP server.** Plugins and MCP servers show each call and its result in the client and ask for approval first, which makes them more transparent for Claude Code and Codex. Gateway tools are mainly for clients that cannot use a plugin or MCP server.
+- **What admins control**: the tools switch and the per-tool checkboxes in the context profile, the **Allow OpenViking tools** switch on each upstream, and the limits on tool rounds, total time and tokens. For profiles used by chat apps, uncheck at least `forget` and `set_acl`.
+- **Gateway tools or a plugin/MCP server**: plugins and MCP servers show each call and its result in the client and ask for approval first, which makes them more transparent for Claude Code and Codex. Gateway tools are mainly for clients that cannot use a plugin or MCP server.
-**Experimental: agent-managed context windows.** Where the model has OpenViking tools, a profile can also let it manage its own context windows: it gets two more tools, one to check how full its window is and one to start a fresh window with hand-off notes it writes itself, and the gateway reminds it as the window fills. This is off by default. See [Experimental: agent-managed context windows](22-gateway-operations.md#experimental-agent-managed-context-windows).
+**Experimental**: a context profile can also let the model manage its own context window. The model gets two more tools, one that reports how full the window is and one that starts a fresh window after it writes hand-off notes, and the gateway reminds it as the window fills up. This is off by default; see [Experimental: agent-managed context windows](22-gateway-operations.md#experimental-agent-managed-context-windows).
## Gateway or plugin?
-OpenViking also connects to agents through plugins that run inside the agent: Claude Code, Codex, OpenCode, pi, OpenClaw, Hermes and others (see [Agent Integrations](../agent-integrations/01-overview.md)). The two approaches complement each other. Their differences come from where each one runs:
+OpenViking also connects to Claude Code, Codex, OpenCode, pi, OpenClaw, Hermes and other agents through plugins (see [Agent Integrations](../agent-integrations/01-overview.md)). The two approaches complement each other, and their differences all follow from where each one runs:
| | OpenViking Gateway | Agent plugin |
| --- | --- | --- |
| Where it runs | Between the client and the model provider. It sees only the requests sent to the model. | Inside the agent. It sees the agent's sessions, events and local workspace. |
-| Clients it covers | Anything that lets you set a base URL and an API key: chat apps, SDK and API apps, low-code platforms, coding agents. | Agents that have an OpenViking plugin. |
+| Clients it covers | Anything that lets you set a base URL and API key: chat apps, SDK and API apps, low-code platforms, coding agents. | Agents that have an OpenViking plugin. |
| Clients it cannot cover | Clients signed in directly with a subscription (a Claude login in Claude Code, a ChatGPT login in Codex; use a [subscription proxy upstream](#custom-upstreams) instead) and clients whose model calls leave from the vendor's servers, such as Cursor and Trae. | Clients without an extension API. |
-| Per-project memory | Cannot see the working directory or repository. Memory belongs to an OpenViking user, so to keep projects apart, give each project a gateway key bound to a different OpenViking user. | Detects the workspace and repository automatically. |
-| What you can see | Added memory is invisible in the client. OpenViking tool calls show up in the reply as one-line notices by default, without their results. You review both in Studio. Tool calls run without the client's permission prompts. | Tool calls appear in the transcript and go through the agent's permission prompts. |
+| Per-project memory | It cannot see the working directory or repository. Memory belongs to an OpenViking user, so to keep projects apart, give each project a gateway key bound to a different OpenViking user. | Detects the workspace and repository automatically. |
+| Visibility | Added memory is invisible in the client. OpenViking tool calls show a one-line notice in the reply by default, without results. Studio's request log records recall counts and tool rounds, not content. Tool calls skip the client's permission prompts. | Tool calls appear in the transcript and go through the agent's permission prompts. |
| When conversations are saved | One turn behind: a turn is saved when the next message arrives, the last turn after a quiet period. | On the agent's own events, such as the end of each turn. |
| Setup and upgrades | One service for everyone, nothing to install on each machine. Upstreams, keys and memory settings are managed in one place. | Installed and upgraded on each machine. |
-| Keys, data and failures | Holds provider API keys and unsaved conversation text centrally (encrypted) and adds one hop to every model call. If the gateway is down, model calls through it fail. | Provider keys stay with each agent; only captured conversations go to OpenViking. No extra service to keep running. |
+| Keys, data and failures | Holds provider API keys and unsaved conversation text centrally (encrypted when OpenViking encryption is on), and adds one hop to every model call. If the gateway is down, model calls through it fail. | Provider keys stay with each agent, and only saved conversations reach OpenViking. No extra service to run. |
-Keep the plugin for Claude Code, Codex or pi when you want per-project memory and tool calls you can see and approve. Use the gateway for clients that have no plugin, and when you want to manage providers, keys and memory settings centrally.
+Keep the plugin for Claude Code, Codex and pi when you need per-project memory or want to see and approve every tool call. Use the gateway for clients without a plugin, and when you want to manage providers, keys and memory settings centrally.
-**Using both.** When a request shows signs of an OpenViking plugin, the gateway stops adding memory, saving turns and offering OpenViking tools for that conversation and only forwards it, so nothing is added or saved twice. It looks for:
+**When both are in use, the gateway steps aside.** If a request shows signs of an OpenViking plugin, the gateway stops adding memory, saving turns and offering OpenViking tools for that conversation, and only forwards it. That keeps the same content from being added or saved twice. It looks for two signs:
-- memory blocks that plugins insert into the prompt: `<openviking-context>`, `<relevant-memories>`, `<relevant-memory>` or `<memory-context>`;
+- memory blocks that plugins insert: `<openviking-context>`, `<relevant-memories>`, `<relevant-memory>` or `<memory-context>`;
- an `X-OpenViking-Plugin` request header, which plugin and app authors can send to opt out explicitly.
-The decision is permanent for that conversation; start a new conversation without the plugin to use gateway memory again. Other conversations are not affected. On Studio's **Requests** tab these requests are flagged **OpenViking plugin in use**.
+The decision holds for the rest of that conversation and does not affect others. To use gateway memory again, start a new conversation without the plugin. Studio's request log flags these requests **OpenViking plugin in use**.
-OpenViking MCP tools alone, without a plugin, do not count: the gateway keeps adding memory and saving turns, and only stops offering its own OpenViking tools so the model does not see two sets (the `tool_name_collision` reason in [Gateway operations](22-gateway-operations.md)).
+OpenViking MCP tools alone, without a plugin, do not count. The gateway still adds memory and saves turns; it only stops offering its own OpenViking tools, so the model does not see two sets with the same names (the request log shows `tool_name_collision`).
## Quick start
-This walkthrough runs OpenViking Server, the gateway and a test client on one machine. You need:
+Start with a working OpenViking installation whose `ov.conf` has embedding and VLM models set up (see [Quick Start](../getting-started/02-quickstart.md)). The gateway is part of the core package; there is nothing extra to install. Pick the path that matches your server. To run the gateway against an existing OpenViking service without changing its configuration, see [Standalone deployment](22-gateway-operations.md#standalone-deployment).
-- a working OpenViking installation whose `ov.conf` already has embedding and VLM models configured (see [Quick Start](../getting-started/02-quickstart.md));
-- Python 3.10 or later;
-- an API key for a model provider. Subscription logins and Coding Plan keys don't work through the gateway.
+### Local server (no API key)
-### 1. Install the gateway
+For a server bound to `127.0.0.1` with the default local authentication.
-Install the `gateway` extra into the same environment as OpenViking:
+1. **Turn the gateway on.** Run `openviking-server init` and answer yes to **Enable OpenViking Gateway on the same port?**. With an existing configuration, choose **Update gateway** from the menu. You can also merge `{"gateway": {"enabled": true}}` into `ov.conf`.
+2. **Start or restart** `openviking-server`.
+3. **Open the gateway in Studio.** Open <http://127.0.0.1:1933/studio/> and choose **OpenViking Gateway** in the sidebar. No key is needed. If the default account has no upstreams yet, the gateway imports the server's VLM settings as upstreams at startup and creates a context profile, so the first two steps of the **Get started** checklist on the Overview tab are already done. An imported Coding Plan upstream needs your confirmation before use; see [Import OpenViking model settings](22-gateway-operations.md#import-openviking-model-settings). If nothing could be imported, add an upstream as described in [Upstreams](22-gateway-operations.md#upstreams).
+4. **Issue a gateway key.** On the Keys tab, choose **Issue key**, enter a name, pick the context profile and an upstream, and issue it. The key reads and writes memory as the local `default` user. The **Copy your gateway key** dialog shows the full `ovgw_…` key only once, so copy it before you close the dialog.
-::: code-group
+Then [send a test request](#send-a-test-request) to `http://127.0.0.1:1933/gateway`.
-```bash [pip]
-pip install "openviking[gateway]"
-```
+### Remote server (API keys)
-```bash [uv]
-uv tool install "openviking[gateway]" --upgrade
-```
+For a server that people reach over the network, with `api_key` authentication.
-:::
+1. **Turn the gateway on.** On the server host, run `openviking-server init`, choose **Remote (0.0.0.0)** for the bind address, and answer yes to **Enable OpenViking Gateway on the same port?**. The next question, **Allow users to configure their own gateway upstreams?**, decides who may change upstreams and context profiles:
+ - Yes: every signed-in user can configure their account's upstreams and context profiles.
+ - No: init generates a gateway management key starting with `ovgm_`, prints it and saves it to `gateway.management_key` in `ov.conf`. Only requests that carry this key can change upstreams and context profiles; see [Gateway management key](22-gateway-operations.md#gateway-management-key).
-`openviking-gateway --help` should now print the command's usage. On Linux and macOS you can add the `gateway-fast` extra (`"openviking[gateway,gateway-fast]"`) for a faster event loop and HTTP parser.
+ Then restart the server. Alternatively, sign in to Studio with the root key and choose **Enable gateway** on the OpenViking Gateway page: Studio writes `ov.conf` and restarts the server (single-worker server only).
+2. **Get an OpenViking API key.** Use your own user API key, or use the root key to create an account and user as described in [Authentication](04-authentication.md).
+3. **Sign in to Studio.** Open `https://ov.example.com/studio/`, enter your API key under **Connection Settings**, and choose **OpenViking Gateway** in the sidebar.
+4. **Add an upstream.** On the Upstreams tab, choose **Add upstream**, pick the provider and the protocol your client uses (the test request below uses Chat Completions), paste the provider's API key and save. Choose **Test** in the upstream list to check that the gateway reaches the provider. If the tab is read-only, the deployer set a gateway management key; see [Manage the gateway in Studio](22-gateway-operations.md#manage-the-gateway-in-studio).
+5. **Create a context profile.** On the Profiles tab, choose **Create with recommended settings**.
+6. **Issue a gateway key** for yourself, as in step 4 of the local path. To issue keys for other users, see [Gateway keys](22-gateway-operations.md#gateway-keys).
-### 2. Create the two secrets
+### Send a test request
-The gateway needs an encryption key for the data it stores, and an admin token that OpenViking Server uses to reach the gateway's management API on your behalf. Create both once and keep them in a file only you can read:
-
-```bash
-mkdir -p ~/.openviking
-cat > ~/.openviking/gateway.env <<EOF
-export OPENVIKING_GATEWAY_ENCRYPTION_KEY="$(python3 -c 'import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())')"
-export OPENVIKING_GATEWAY_ADMIN_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
-EOF
-chmod 600 ~/.openviking/gateway.env
-```
-
-Both OpenViking Server and the gateway need these variables, so load the file in every terminal you start them from. Keep the encryption key: if it changes, the gateway can no longer read what it stored.
-
-### 3. Turn on API key authentication and the gateway
-
-The gateway uses each person's own OpenViking key, so OpenViking must run in API key mode. Merge these settings into `~/.openviking/ov.conf`, using a long random value as the root key:
-
-```json
-{
- "server": {
- "auth_mode": "api_key",
- "root_api_key": "<root-key>"
- },
- "gateway": {
- "enabled": true,
- "public_url": "http://127.0.0.1:1935"
- }
-}
-```
-
-Everything else keeps its default: the gateway listens on `127.0.0.1:1935`, reaches OpenViking at `http://127.0.0.1:1933` and stores its data in `~/.openviking/gateway`. `public_url` is the address clients use; Studio shows it in its setup instructions.
-
-### 4. Start OpenViking Server
-
-```bash
-source ~/.openviking/gateway.env
-openviking-server
-```
-
-If the server was already running, restart it from this shell so it picks up both the new configuration and the admin token.
-
-### 5. Create an account and a user key
-
-In another terminal, use the root key to create an account with its first admin, as described in [Authentication](04-authentication.md#managing-accounts-and-users):
-
-```bash
-curl -X POST http://127.0.0.1:1933/api/v1/admin/accounts \
- -H "X-API-Key: <root-key>" \
- -H "Content-Type: application/json" \
- -d '{"account_id": "acme", "admin_user_id": "alice"}'
-# Returns: {"result": {"account_id": "acme", "admin_user_id": "alice", "user_key": "..."}}
-```
-
-Save alice's `user_key`. For this walkthrough it does two jobs: it signs you in to Studio as the account admin, and it is the OpenViking key the gateway uses for alice's memory. In a team, give each person a user key of their own (`POST /api/v1/admin/accounts/acme/users` with `"role": "user"`).
-
-### 6. Start the gateway
-
-```bash
-source ~/.openviking/gateway.env
-openviking-gateway --config ~/.openviking/ov.conf
-```
-
-Check that it can reach OpenViking:
-
-```bash
-curl -s http://127.0.0.1:1935/health
-# {"status":"ok","service":"openviking-gateway","openviking":{"status":"ok","healthy":true,"version":"…","auth_mode":"api_key"}}
-```
-
-Right after startup `openviking` may still read `{"status":"starting"}`. If it shows `"status":"degraded"`, see [Troubleshooting](22-gateway-operations.md#troubleshooting).
-
-### 7. Set up the gateway in Studio
-
-Open <http://127.0.0.1:1933/studio>, open **Connection Settings**, and paste alice's key as both the **User API key** and the **Admin API key**. Then choose **OpenViking Gateway** in the sidebar's **Settings** group. Until the first request arrives, the **Overview** tab shows a **Get started** checklist with the same four steps:
-
-1. **Add an upstream.** On the Upstreams tab, choose **Add upstream**. Give it a name, choose the provider and pick the protocol your client speaks (Chat Completions for this walkthrough). Studio fills in the provider's base URL, for example `https://api.openai.com/v1` for OpenAI; with *Generic*, enter it yourself. Keep **The gateway holds the API key** selected and paste the provider's API key. Save, then use **Test** in the upstream list to check that the gateway can reach the provider.
-2. **Create a context profile.** On the Profiles tab, choose **Create with recommended settings**. This creates a profile named "Default", with only the read-only OpenViking tools selected.
-3. **Issue a gateway key.** On the Keys tab, choose **Issue key**. Enter a name, choose alice as the **OpenViking user** (she is already selected when she is the account's only user), pick the "Default" profile and your upstream, then issue it. The **Copy your gateway key** dialog shows the full `ovgw_…` key once; copy it before you close the dialog.
-4. **Connect a client.** The Connect tab shows the setup for each client with your gateway address filled in. The same setups are listed in [Connect clients](#connect-clients) below.
-
-### 8. Send a test request
+For a local server, use `http://127.0.0.1:1933/gateway` as the address. Replace `<model>` with a model the upstream serves:
```bash
+export GATEWAY_URL=https://ov.example.com/gateway
export GATEWAY_KEY='ovgw_...'
-curl -s http://127.0.0.1:1935/v1/models -H "Authorization: Bearer $GATEWAY_KEY"
-# {"object":"list","data":[{"id":"…","object":"model","owned_by":"openviking-gateway"}]}
+curl -s "$GATEWAY_URL/v1/models" -H "Authorization: Bearer $GATEWAY_KEY"
-curl -s http://127.0.0.1:1935/v1/chat/completions \
+curl -s "$GATEWAY_URL/v1/chat/completions" \
-H "Authorization: Bearer $GATEWAY_KEY" \
-H "Content-Type: application/json" \
-H "X-OpenViking-Session: quickstart-1" \
-d '{"model": "<model>", "messages": [{"role": "user", "content": "Remember that I prefer short answers."}]}'
```
-The model list contains the models and aliases you entered on the upstream; it is empty if you left the upstream's model list empty. The second command should return a normal completion from your provider.
+The first command lists the models and aliases configured on the upstream; the list is empty if the upstream accepts any model name. The second should return a normal reply from your provider.
-### 9. Confirm that memory works
+### Confirm that memory works
-- **The request went through the gateway.** Open the Requests tab. Your request appears as a **New message** with status 200. The **Memory** column shows how many entries were added (for example `+3`) once OpenViking has something relevant; on a brand-new account it stays empty.
-- **The conversation is saved.** Send a second message with the same `X-OpenViking-Session` header. The first turn is saved as soon as the second message arrives, and the last turn after 10 quiet minutes. The conversation then appears in Studio's **Sessions** page (connected as alice) as a session named `gateway-…`.
-- **Memories are extracted.** OpenViking extracts memories after the session is committed: when the conversation has been quiet for 10 minutes, or when 20,000 uncommitted tokens have built up. Extraction runs in the background, so allow it a moment. Then start a new conversation (another session header value) and ask something that depends on it, such as "How long should your answers be?". The Memory column shows the recalled entries, and the reply should use them.
+1. **The request went through the gateway.** Open the Requests tab. Your request shows as a **New message** with status 200. Once OpenViking has something relevant, the **Memory** column shows how many entries were added (for example `+3`); on a brand-new account it stays empty.
+2. **The conversation is saved.** Send a second message with the same `X-OpenViking-Session` value; the first turn is saved right away. Connect Studio as the key's user, and a `gateway-…` session appears on the **Sessions** page.
+3. **Memories are extracted.** After 10 quiet minutes the gateway commits the session, and OpenViking extracts memories in the background, which takes a moment. Then start a new conversation with another session value and ask something that depends on the memory, such as "How long should your answers be?". The **Memory** column should show recalled entries, and the reply should use them.
-To see results faster while you try things out, create a second profile with a short **Save the latest reply after** time, issue a key with it, and use that key for new conversations. Profile changes apply only to conversations that start afterwards.
+To see results sooner while you try things out, create a second context profile with a shorter **Save the latest reply after** time, issue a key with it, and start a new conversation with that key. Profile changes only reach conversations that start afterwards.
## Connect clients
-Every client needs two things: the gateway address and a gateway key. The examples use `https://ov.example.com`; replace it with your own gateway address, which Studio shows at the top of the OpenViking Gateway page and on the Connect tab. Each client also needs an enabled upstream that speaks its protocol and serves the model it asks for, bound to its key.
+Every client needs the gateway address and a gateway key. The gateway address is the server's address followed by `/gateway`. The examples use `https://ov.example.com/gateway`; replace it with your gateway address, which Studio shows at the top of the OpenViking Gateway page and on the Connect tab. Anthropic clients use the gateway address as it is, OpenAI-compatible clients add `/v1`, and Ark SDKs add `/api/v3`. The client's key must also be bound to an enabled upstream that speaks the client's protocol and serves the model it requests.
| Client | Upstream protocol | Base URL | How its conversations are recognized |
| --- | --- | --- | --- |
-| [Claude Code](#claude-code) | Anthropic Messages | `https://ov.example.com` | Claude Code's session header |
-| [Codex CLI](#codex-cli) | Responses | `https://ov.example.com/v1` | Codex's session header |
-| [Chat clients and SDKs](#chat-clients-and-sdks) | Chat Completions (or the API your SDK speaks) | `https://ov.example.com/v1` | `X-OpenViking-Session`, if you send it |
-| [Open WebUI](#open-webui) | Chat Completions | `https://ov.example.com/v1` | `X-OpenViking-Session` connection header |
-| [OpenCode](#opencode) | Chat Completions | `https://ov.example.com/v1` | OpenCode's session header |
-| [pi](#pi) | Chat Completions | `https://ov.example.com/v1` | Usually matched from the conversation history |
-| [Volcano Engine Ark and BytePlus ModelArk SDKs](#volcano-engine-ark-and-byteplus-modelark-sdks) | Any of the three | `https://ov.example.com/api/v3` or `https://ov.example.com/api/compatible` | As the client sends it |
+| [Claude Code](#claude-code) | Anthropic Messages | `https://ov.example.com/gateway` | Claude Code's session header |
+| [Codex CLI](#codex-cli) | Responses | `https://ov.example.com/gateway/v1` | Codex's session header |
+| [Chat clients and SDKs](#chat-clients-and-sdks) | Chat Completions (or the API your SDK uses) | `https://ov.example.com/gateway/v1` | `X-OpenViking-Session`, which you send yourself |
+| [Open WebUI](#open-webui) | Chat Completions | `https://ov.example.com/gateway/v1` | An `X-OpenViking-Session` header set on the connection |
+| [OpenCode](#opencode) | Chat Completions | `https://ov.example.com/gateway/v1` | OpenCode's session header |
+| [pi](#pi) | Chat Completions | `https://ov.example.com/gateway/v1` | Usually matched from the conversation history |
+| [Volcano Engine Ark and BytePlus ModelArk SDKs](#volcano-engine-ark-and-byteplus-modelark-sdks) | Any of the three | `https://ov.example.com/gateway/api/v3` or `https://ov.example.com/gateway/api/compatible` | Depends on the headers the client sends |
-The Open WebUI, OpenCode and pi setups follow each client's documented provider settings. Treat them as a starting point and check the result: send two messages in one conversation, then expand both requests on the Requests tab. They should show the same conversation, and the first turn should be saved once the second message arrives.
+The Open WebUI, OpenCode and pi setups follow each client's documented provider settings. Treat them as a starting point and check the result: send two messages in one conversation, then expand both requests on the Requests tab. They should belong to the same conversation, and the first turn should be saved once the second message arrives.
### Claude Code
-Claude Code speaks Anthropic Messages. Set three environment variables before you start it:
+Claude Code uses Anthropic Messages. Set three environment variables before you start it:
```bash
-export ANTHROPIC_BASE_URL=https://ov.example.com
+export ANTHROPIC_BASE_URL=https://ov.example.com/gateway
export ANTHROPIC_AUTH_TOKEN='<gateway-key>'
export CLAUDE_CODE_GATEWAY_HINT_HEADERS=1
```
-- Use the address without `/v1`; Claude Code adds the path itself.
-- `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` makes Claude Code label sub-agent, compaction and background requests, so the gateway does not search memory for them or save them as conversation turns.
-- Claude Code sends its own session ID, so conversations are recognized automatically, including after `--resume`.
-- The upstream must accept the model names Claude Code asks for. Leave the upstream's model list empty, list those names, or map them with model aliases to the model your provider serves.
+- Leave `/v1` off the address; Claude Code adds the path itself.
+- `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` makes Claude Code label sub-agent, compaction and background requests, so the gateway does not recall memory for them or save them as conversation turns.
+- Claude Code sends its own session ID, which the gateway uses to recognize the conversation, including after `--resume`.
+- The upstream must accept the model names Claude Code requests: leave its model list empty, list those names, or map them to the provider's model with model aliases.
- A Claude subscription login does not work through the gateway; requests with a subscription token are rejected. Configure the upstream with a provider API key.
-- If Claude Code also has the OpenViking plugin, the gateway steps aside for those conversations (see [Gateway or plugin?](#gateway-or-plugin)). With only the OpenViking MCP server, the gateway keeps its memory but leaves the OpenViking tools to the MCP server.
+- If the OpenViking plugin is also installed, the gateway steps aside for those conversations (see [Gateway or plugin?](#gateway-or-plugin)). With only the OpenViking MCP server, the gateway still adds memory and leaves the OpenViking tools to the MCP server.
### Codex CLI
-Codex speaks the Responses API and sends the full history with every request, which is what the gateway needs. Add a provider to `~/.codex/config.toml`. The two top-level settings must come before any `[section]`:
+Codex uses the Responses API and sends the full history with every request, which is what the gateway needs. Add a provider to `~/.codex/config.toml`. The two top-level settings must come before any `[section]`:
```toml
model_provider = "openviking"
@@ -368,42 +301,42 @@ model = "<model>"
[model_providers.openviking]
name = "OpenViking Gateway"
-base_url = "https://ov.example.com/v1"
+base_url = "https://ov.example.com/gateway/v1"
wire_api = "responses"
env_key = "OPENVIKING_GATEWAY_KEY"
```
-Then put the gateway key in the environment Codex runs in:
+Then set the gateway key in the environment Codex runs in:
```bash
export OPENVIKING_GATEWAY_KEY='<gateway-key>'
```
-- The upstream bound to the key must speak Responses and serve `<model>`.
-- Codex first tries a WebSocket connection. The gateway declines it and Codex falls back to HTTP automatically.
-- Codex sends its own session ID, so conversations are recognized automatically, including after `codex resume`.
+- The upstream bound to the key must use Responses and serve `<model>`.
+- Codex first tries a WebSocket connection. The gateway declines it, and Codex falls back to HTTP.
+- Codex sends its own session ID, which the gateway uses to recognize the conversation, including after `codex resume`.
- Codex may warn that it has no metadata for an unfamiliar model name. The warning does not affect requests.
-- A ChatGPT login does not work through the gateway; use a provider API key on the upstream.
+- A ChatGPT login does not work through the gateway. Configure the upstream with a provider API key.
### Chat clients and SDKs
-Any client or SDK that speaks the OpenAI Chat Completions API can use the gateway. Enter these settings wherever the client asks for an OpenAI-compatible provider:
+Any client or SDK that supports the OpenAI Chat Completions API can connect. Enter these settings wherever the client asks for an OpenAI-compatible provider:
```text
-Base URL: https://ov.example.com/v1
+Base URL: https://ov.example.com/gateway/v1
API key: <gateway-key>
Model: <model>
X-OpenViking-Session: <conversation-id>
```
-The `X-OpenViking-Session` header is optional but recommended: it tells the gateway which conversation a request belongs to. Send a value that stays the same for one conversation and differs between conversations, such as your app's chat ID. Without it the gateway matches conversations from their history; see [How conversations are recognized](#how-conversations-are-recognized).
+The `X-OpenViking-Session` header is optional but recommended. It tells the gateway which conversation a request belongs to. Use a value that stays the same within a conversation and differs between conversations, such as your app's chat ID. Without it, the gateway matches conversations by their history; see [How conversations are recognized](#how-conversations-are-recognized).
With the OpenAI Python SDK:
```python
from openai import OpenAI
-client = OpenAI(base_url="https://ov.example.com/v1", api_key="<gateway-key>")
+client = OpenAI(base_url="https://ov.example.com/gateway/v1", api_key="<gateway-key>")
reply = client.chat.completions.create(
model="<model>",
@@ -413,13 +346,16 @@ reply = client.chat.completions.create(
print(reply.choices[0].message.content)
```
-SDKs for the other two APIs work the same way. Point the Anthropic SDK at `https://ov.example.com`. For the Responses API, use `https://ov.example.com/v1` and send the full history with `store: false` in every request; other Responses requests are forwarded without memory. The upstream must speak the same API as the SDK.
+SDKs for the other two APIs work the same way, as long as the upstream uses the same API as the SDK:
+
+- Point the Anthropic SDK at `https://ov.example.com/gateway`.
+- For the Responses API, use `https://ov.example.com/gateway/v1`, send the full history in every request and set `store: false`. Other Responses requests are forwarded without memory.
-When you stream Chat Completions, also request usage (`"stream_options": {"include_usage": true}`). Without it the provider reports no token counts for streamed replies, so Studio cannot show them and the gateway has to estimate from the request text how full the context window is.
+When you stream Chat Completions, also ask for usage (`"stream_options": {"include_usage": true}`). Otherwise the provider reports no token counts for streamed replies, Studio cannot show usage, and the gateway has to estimate how full the context window is.
### Open WebUI
-In Open WebUI, add an OpenAI-compatible connection (Admin Panel → Settings → Connections) with the base URL `https://ov.example.com/v1` and the gateway key. Add these custom headers to the connection, so each chat is its own conversation and Open WebUI's background tasks are recognized:
+In Open WebUI, add an OpenAI-compatible connection (Admin Panel → Settings → Connections) with the base URL `https://ov.example.com/gateway/v1` and the gateway key. Add these custom headers to the connection, so that each chat is its own conversation and the gateway recognizes Open WebUI's background tasks:
```json
{
@@ -428,14 +364,14 @@ In Open WebUI, add an OpenAI-compatible connection (Admin Panel → Settings →
}
```
-Also set `RAG_SYSTEM_CONTEXT=true` in Open WebUI's environment. Open WebUI then puts content retrieved from attached files into the system message, instead of rewriting your message for one turn, which keeps the conversation history stable between requests.
+Also set `RAG_SYSTEM_CONTEXT=true` in Open WebUI's environment. Open WebUI then puts content retrieved from attachments into the system message instead of rewriting your message for one turn, which keeps the conversation history stable between requests.
-- **One connection key is one memory owner.** Every Open WebUI user who chats through this connection reads and writes the memory of the OpenViking user behind the key. Give the connection to one person, or accept that its users share memory.
-- Open WebUI also sends background requests (titles, tags, follow-up suggestions) through the same connection. The gateway recognizes title and summary requests. If the Requests tab shows other background tasks as **New message**, set Open WebUI's task model to a connection that does not go through the gateway.
+- **One connection key means one memory owner.** Every Open WebUI user who chats through this connection reads and writes the memory of the OpenViking user behind the key. Give the connection to one person, or accept that its users share memory.
+- Open WebUI also sends background requests (titles, tags, follow-up suggestions) through the same connection. The gateway recognizes title and summary requests. If the request log shows other background tasks as **New message**, point Open WebUI's task model at a connection that does not go through the gateway.
### OpenCode
-Add a provider to `~/.config/opencode/opencode.json`, merging it with any settings already there:
+Add a provider to `~/.config/opencode/opencode.json`, merged with your existing settings:
```json
{
@@ -444,7 +380,7 @@ Add a provider to `~/.config/opencode/opencode.json`, merging it with any settin
"npm": "@ai-sdk/openai-compatible",
"name": "OpenViking",
"options": {
- "baseURL": "https://ov.example.com/v1",
+ "baseURL": "https://ov.example.com/gateway/v1",
"apiKey": "{env:OPENVIKING_GATEWAY_KEY}"
},
"models": {
@@ -455,7 +391,7 @@ Add a provider to `~/.config/opencode/opencode.json`, merging it with any settin
}
```
-Export `OPENVIKING_GATEWAY_KEY` with your gateway key and select `openviking/<model>` in OpenCode. The upstream must speak Chat Completions. If the OpenViking OpenCode plugin is installed as well, the gateway steps aside for those conversations.
+Export the gateway key as `OPENVIKING_GATEWAY_KEY`, then select `openviking/<model>` in OpenCode. The upstream must use Chat Completions. If the OpenViking plugin for OpenCode is also installed, the gateway steps aside for those conversations.
### pi
@@ -465,7 +401,7 @@ Add a provider to pi's model configuration, `~/.pi/agent/models.json`:
{
"providers": {
"openviking": {
- "baseUrl": "https://ov.example.com/v1",
+ "baseUrl": "https://ov.example.com/gateway/v1",
"apiKey": "$OPENVIKING_GATEWAY_KEY",
"api": "openai-completions",
"models": [
@@ -478,31 +414,34 @@ Add a provider to pi's model configuration, `~/.pi/agent/models.json`:
}
```
-`apiKey` reads your gateway key from the `OPENVIKING_GATEWAY_KEY` environment variable; export it before starting pi. Keep the leading `$`: pi sends a bare string as the key itself. The upstream must speak Chat Completions. Unless pi sends one of the headers listed in [How conversations are recognized](#how-conversations-are-recognized), the gateway matches its conversations from their history. If pi's own OpenViking extension is active, the gateway steps aside for those conversations; use one or the other.
+- `apiKey` reads the gateway key from the `OPENVIKING_GATEWAY_KEY` environment variable; export it before you start pi. Keep the leading `$`, or pi sends the string itself as the key.
+- The upstream must use Chat Completions.
+- pi usually sends no session header, so the gateway matches its conversations by their history (see [How conversations are recognized](#how-conversations-are-recognized)).
+- If pi's own OpenViking extension is active, the gateway steps aside for those conversations. Use one or the other.
### Volcano Engine Ark and BytePlus ModelArk SDKs
-Clients and SDKs already configured for Volcano Engine Ark or BytePlus ModelArk, its international edition, only need the domain replaced. The gateway accepts Ark's own paths (`/api/v3/chat/completions`, `/api/v3/responses`, `/api/v3/models` and `/api/compatible/v1/messages`) as well as the standard `/v1` paths:
+Clients and SDKs already set up for Volcano Engine Ark, or BytePlus ModelArk (its international edition), only need the address replaced. Under `/gateway`, the gateway accepts Ark's own paths (`/api/v3/chat/completions`, `/api/v3/responses`, `/api/v3/models` and `/api/compatible/v1/messages`) as well as the standard `/v1` paths:
-| Configured address | Gateway address |
+| Original address | Gateway address |
| --- | --- |
-| `https://ark.cn-beijing.volces.com/api/v3` | `https://ov.example.com/api/v3` |
-| `https://ark.ap-southeast.bytepluses.com/api/v3` | `https://ov.example.com/api/v3` |
-| `https://ark.cn-beijing.volces.com/api/compatible` (Anthropic-compatible) | `https://ov.example.com/api/compatible` |
+| `https://ark.cn-beijing.volces.com/api/v3` | `https://ov.example.com/gateway/api/v3` |
+| `https://ark.ap-southeast.bytepluses.com/api/v3` | `https://ov.example.com/gateway/api/v3` |
+| `https://ark.cn-beijing.volces.com/api/compatible` (Anthropic-compatible) | `https://ov.example.com/gateway/api/compatible` |
-Use the gateway key in place of the Ark or ModelArk API key. With the Volcano Engine Ark Python SDK:
+Use the gateway key in place of the Ark API key. With the Volcano Engine Ark Python SDK:
```python
from volcenginesdkarkruntime import Ark
-client = Ark(base_url="https://ov.example.com/api/v3", api_key="<gateway-key>")
+client = Ark(base_url="https://ov.example.com/gateway/api/v3", api_key="<gateway-key>")
```
-The paths only decide which API the client speaks. Requests still go to whichever upstream bound to the key speaks that API and serves the model; usually that is an upstream with the Volcano Engine Ark or BytePlus ModelArk provider (see [Upstreams](22-gateway-operations.md#upstreams)).
+The path a client uses only decides which API it speaks. The request still goes to an upstream bound to the key that uses that API and serves the model, usually one whose provider is Volcano Engine Ark or BytePlus ModelArk (see [Upstreams](22-gateway-operations.md#upstreams)).
## How conversations are recognized
-The gateway needs to know which conversation a request belongs to. A conversation is the unit that keeps its context profile and upstream, and that is saved to one OpenViking session. The gateway takes the first of these request headers that is present:
+The gateway needs to know which conversation a request belongs to. A conversation keeps one context profile and one upstream, and is saved to one OpenViking session. The gateway takes the first of these request headers that is present:
1. `X-OpenViking-Session`
2. `thread-id`
@@ -511,28 +450,27 @@ The gateway needs to know which conversation a request belongs to. A conversatio
5. `x-session-id`
6. `session-id` (Codex CLI)
-Without any of them, the gateway looks at the latest assistant reply in the history. If exactly one earlier conversation produced that reply, the request joins it; otherwise it starts a new conversation. A shared opening message alone never merges two conversations. This works for ordinary back-and-forth chat, but retries, regenerated answers and identical chats are ambiguous, so they may start a new conversation. Send `X-OpenViking-Session` whenever your client lets you set headers.
+If none is present, the gateway looks at the latest assistant reply in the history. If an earlier conversation produced that reply, the request joins it; otherwise it starts a new conversation. Two conversations that only share an opening message are never merged. This handles ordinary back-and-forth chat, but retries, regenerated answers and identical conversations are ambiguous and may start a new conversation. So send `X-OpenViking-Session` whenever your client lets you set headers.
-Conversations belong to the OpenViking user behind the key, separately for each API. Two gateway keys for the same user that send the same session value share one conversation; the same session value on another API is a different conversation. The gateway removes every `X-OpenViking-*` header before forwarding, so providers never see them.
+Conversations belong to the OpenViking user behind the key, separately for each API. Two gateway keys of the same user that send the same session value share one conversation; the same session value on a different API is a different conversation. The gateway removes all `X-OpenViking-*` headers before forwarding, so providers never see them.
-When a request is not recognized, memory still works: new messages are searched, and memory added earlier is replayed, because the gateway finds it by the messages themselves. What changes is that the request starts a new conversation. Its turns are saved to a new OpenViking session, and it starts with a fresh memory budget and the key's current profile.
+A request that does not join an existing conversation still gets memory: new messages are recalled for, and memory added earlier is replayed, because the gateway finds it by the messages themselves. The difference is that the request starts a new conversation. Its turns are saved to a new OpenViking session, its memory budget starts from zero, and it uses the key's current context profile.
## What to expect
-- **Memory is added per message.** The first model call of each new message waits for the OpenViking search, at most the profile's **Time limit** (2 seconds by default). If OpenViking does not answer in time, or is unavailable, the message goes to the model without memory and does not get it later. Model requests keep working while OpenViking is down.
-- **Settings apply to new conversations.** A conversation keeps the context profile and upstream it started with. Long-lived clients such as Claude Code and Codex keep a conversation across many days, so a profile change reaches them when they start a new conversation. A conversation's state is removed after 30 days without use.
-- **Saving is one turn behind.** The last turn of a conversation is saved after 10 quiet minutes, and memories appear only after OpenViking has processed the commit.
-- **Edited history starts over.** If the client edits or deletes earlier messages, regenerates an answer after it was saved, or compacts the conversation, the gateway saves the history as it now stands to a new OpenViking session. Turns already saved stay in the old session.
-- **Clients keep their full history.** After the gateway compacts a conversation, the client still resends the whole history, and the gateway replaces the part before the cut on every request. The usage the client sees is small after compaction, so clients that compact by token usage seldom do so on their own, and a very long session can eventually reach the request size limit.
-- **One key is one memory owner.** Everyone who uses a key shares the memory of the OpenViking user behind it. Issue one key per person, and per client if you want separate profiles.
-- **Subscription logins are not supported.** Requests that carry a Claude subscription token are rejected. Configure provider API keys on the upstreams.
-- **Responses needs the full history.** Responses requests that rely on state stored at the provider (`previous_response_id`, `conversation`, `background`) or that do not set `store: false` are forwarded without memory. Later lookups of those responses still reach the upstream that created them.
+- **Recall waits up to 2 seconds.** The first model call of each new message waits for the OpenViking search, at most the profile's **Time limit** (2 seconds by default). If OpenViking times out or is down, the message goes to the model without memory and never gets it later.
+- **Settings apply to new conversations.** A conversation keeps the context profile and upstream it started with. Long-running clients such as Claude Code and Codex can continue one conversation for days, so a profile change reaches them only when they start a new one. The gateway deletes a conversation's state after 30 days without use.
+- **Changed history is saved again.** If the client edits or deletes earlier messages, regenerates an answer after it was saved, or compacts the conversation itself, the gateway saves the current full history to a new OpenViking session. Turns already saved stay in the old session.
+- **Very long sessions can hit the request size limit.** After the gateway compacts a conversation, the client still sends the full history but sees small usage numbers, so clients that compact by usage rarely compact on their own. Request bodies over 32 MiB are rejected; operators can change the limit (see [Long conversations](22-gateway-operations.md#long-conversations)).
+- **One key means one memory owner.** Everyone who shares a key shares the memory of the OpenViking user behind it. Issue one key per person, and separate keys per client if you want different context profiles.
+- **Subscription logins are not supported.** Requests with a Claude subscription token are rejected. Configure the upstream with a provider API key.
+- **Responses needs the full history.** Responses requests that rely on state stored at the provider (`previous_response_id`, `conversation`, `background`), or that do not set `store: false`, are forwarded without memory. Later lookups of those responses still go to the upstream that created them.
- **Other endpoints pass through.** Endpoints other than the three model APIs and the model list, such as embeddings, are forwarded without memory to the highest-priority upstream bound to the key that serves the requested model.
-- **Requests have a size limit.** Request bodies larger than 32 MiB are rejected (an operator can change the limit).
## Next steps
-- [OpenViking Gateway deployment and operations](22-gateway-operations.md): deploy with Docker Compose or Helm, manage upstreams, profiles and keys, and troubleshoot.
+- [OpenViking Gateway deployment and operations](22-gateway-operations.md): deploy with Docker Compose, Helm or a standalone process; manage upstreams, context profiles and keys; troubleshoot.
+- [OpenViking Gateway Management API](../api/25-gateway.md): the access matrix and management endpoints.
- [Authentication](04-authentication.md): create accounts, users and their keys.
- [Public Access & Reverse Proxy](12-public-access.md): put OpenViking behind HTTPS.
- [Agent Integrations](../agent-integrations/01-overview.md): plugins for agents that support them.
diff --git a/docs/en/guides/17-vikingbot.md b/docs/en/guides/17-vikingbot.md
index c732273cd..e8ca7dcfd 100644
--- a/docs/en/guides/17-vikingbot.md
+++ b/docs/en/guides/17-vikingbot.md
@@ -98,7 +98,7 @@ openviking-server doctor
See the [OpenViking Configuration Guide](01-configuration.md) for details. VikingBot inherits the root-level `vlm` as its Agent model by default, so you normally do not need to configure `bot.agents` again.
-For an `api_key` server, register a User/Admin key and set it in `bot.ov_server.api_key` before starting the Bot; the root management key cannot serve as that user key. See [Authentication](04-authentication.md). In inherited `trusted` mode the Bot uses the server’s trusted identity configuration.
+For an `api_key` server, register a User/Admin key and set it in `bot.ov_server.api_key` before starting the Bot; the root API key cannot serve as that user key. See [Authentication](04-authentication.md). In inherited `trusted` mode the Bot uses the server’s trusted identity configuration.
### 2. Start Both Services
diff --git a/docs/en/guides/22-gateway-operations.md b/docs/en/guides/22-gateway-operations.md
index f99d5371f..b39d7eb1d 100644
--- a/docs/en/guides/22-gateway-operations.md
+++ b/docs/en/guides/22-gateway-operations.md
@@ -1,751 +1,696 @@
---
-description: Deploy OpenViking Gateway with Docker Compose, Helm or your own proxy, manage it in Studio, and troubleshoot it.
+description: Deploy OpenViking Gateway with Docker Compose, Helm or as a standalone process, manage it in Studio, and troubleshoot it.
---
# OpenViking Gateway deployment and operations
-This page is for the people who run OpenViking Gateway: deploying it, managing upstreams, context profiles and keys in Studio, keeping data safe, day-to-day operations, and fixing problems. For what the gateway does and how to connect clients, see [OpenViking Gateway](15-gateway.md); for the overall architecture, see [Architecture at a glance](15-gateway.md#architecture-at-a-glance) on that page.
+This page is for the people who run OpenViking Gateway: how to deploy it, how to manage upstreams, context profiles and keys in Studio, where data is stored and how to back it up, and how to track down problems. For what the gateway does and how to connect clients, see [OpenViking Gateway](15-gateway.md); for the overall design, see [Architecture at a glance](15-gateway.md#architecture-at-a-glance).
-OpenViking Gateway is currently in beta. Its settings and APIs may change between releases, so read the release notes before you upgrade.
+The gateway is in beta. Settings and APIs may change between releases, so read the release notes before you upgrade.
-The gateway is a separate process next to OpenViking Server, normally on port 1935. Clients send their model requests to it. You manage it in Studio, which OpenViking Server serves; Studio's management calls reach the gateway through OpenViking Server. The two processes talk only over HTTP: the gateway calls OpenViking's public APIs to search memory, save conversations and run tools, and OpenViking Server calls the gateway's management API. The diagram shows the request paths when a single HTTPS address is exposed:
+## Requirements
-```text
- clients
- |
- v
- reverse proxy (https://ov.example.com)
- | |
- | /v1/* | everything else:
- | /api/v3/* | /studio, /api/v1,
- | /api/compatible/v1/* | /mcp, /health, ...
- | /gateway/uploads |
- v v
- OpenViking Gateway :1935 <--- management --- OpenViking Server :1933
- | | ^
- | +--------- search, save, tools ----------+
- v
- model providers (upstreams)
-```
+- **OpenViking authentication**: `api_key` or local dev mode. The gateway does not support trusted authentication.
+- **OpenViking version**: an embedded gateway ships with the server, so there is nothing to check. A standalone gateway needs OpenViking Server 0.4.16 or later.
+- **Installation**: the gateway is part of the OpenViking core package. The optional `gateway-fast` extra (`pip install "openviking[gateway-fast]"`) adds a faster event loop and HTTP parser.
+- **Sign-in**: remote deployments need an OpenViking API key. Users, account admins and root can all sign in to the gateway pages in Studio. Local dev mode needs no key and always uses the `default/default` identity.
+- **Storage**: a local disk. The gateway's SQLite databases serve one host only; network filesystems and storage shared between hosts are not supported.
-## Requirements
+## Keys and credentials
-- **OpenViking Server 0.4.16 or later, in API key mode** (`server.auth_mode: "api_key"` with a `root_api_key`). The gateway acts for each person with that person's OpenViking key. In dev mode every key acts as root, which the gateway refuses, so no gateway key can be issued.
-- **The gateway itself**: the `openviking[gateway]` extra on Python 3.10 or later, or the official OpenViking Docker image, which already contains the `openviking-gateway` command.
-- **An account admin key** for Studio. Everything you configure belongs to the account of the key you sign in with. A root key also works but manages whichever account it resolves to, so prefer the account admin's key.
-- **An OpenViking user for each person** who gets a gateway key, in the same account. Users and admins both work; root does not. When you issue the key, OpenViking Server reads the user's OpenViking key itself; if it stores only key hashes, the user has to provide their key.
-- **API keys for your model providers.** Subscription logins are rejected, and Coding Plan keys are refused unless you explicitly allow them.
-- **A local disk on one host** for the gateway's storage (`~/.openviking/gateway` by default). Network file systems and storage shared between hosts are not supported. Run only one gateway instance at a time; for more capacity, add workers (see [Scaling](#scaling)).
-- **Two secrets**, described next.
+The gateway involves four keys, each with one job:
-## Secrets
+| Key | Purpose | Where it is used |
+| --- | --- | --- |
+| OpenViking API key | Signs in to Studio; decides which account and user memory is read and written as | `X-API-Key` or `Authorization: Bearer` on management requests |
+| Gateway key (`ovgw_…`) | Connects a client; each one binds a user, a context profile and a set of upstreams | The client's API key field |
+| Gateway management key (optional) | Restricts who can change upstreams and context profiles | `gateway.management_key`; the `X-OpenViking-Gateway-Management-Key` request header |
+| Upstream API key | Calls the model provider | The upstream editor |
-| Secret | Environment variable | Needed by | What it does |
-| --- | --- | --- | --- |
-| Encryption key | `OPENVIKING_GATEWAY_ENCRYPTION_KEY` | Gateway | Encrypts everything the gateway stores: upstream API keys and headers, the OpenViking keys bound to gateway keys, conversation state and request logs. Must be a Fernet key: 32 random bytes in URL-safe base64. |
-| Admin token | `OPENVIKING_GATEWAY_ADMIN_TOKEN` | Gateway and OpenViking Server | Authenticates OpenViking Server to the gateway's management API when you work in Studio. At least 32 characters. |
+The gateway has no encryption key of its own: it encrypts its local storage with OpenViking's encryption settings; see [Encryption](#encryption).
-Generate each once:
+### Gateway management key
-```bash
-# Encryption key (the same format as Fernet.generate_key() in the cryptography package)
-python3 -c 'import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())'
+Without a management key, every signed-in user in an account can add and change that account's upstreams and context profiles. With one, only requests that carry it can change them, including requests from OpenViking admins and root. Everyone else can view and test them, and pick them when issuing keys. The management key does not limit who can sign in, or whether users can issue gateway keys for themselves. The full rules are in the [access matrix](../api/25-gateway.md#credentials-and-account-scope).
-# Admin token
-python3 -c 'import secrets; print(secrets.token_urlsafe(48))'
-```
+To set one:
+
+- **`openviking-server init`** (embedded): for a remote deployment, answer no to **Allow users to configure their own gateway upstreams?**. Init generates a value starting with `ovgm_`, prints it and saves it to `gateway.management_key` in `ov.conf`.
+- **`openviking-gateway init`** (standalone): answer yes to **Require a management key to change upstreams and profiles?**. Init generates an `ovgm_` value, prints it once and saves it to `management_key` in `gateway.conf`.
+- **By hand**: use at least 32 characters, for example from `openssl rand -base64 32`. Put it in `management_key`, or set the `OPENVIKING_GATEWAY_MANAGEMENT_KEY` environment variable, which overrides the file in both forms; see [Configuration reference](#configuration-reference).
+- **Compose and Helm**: Compose passes `OPENVIKING_GATEWAY_MANAGEMENT_KEY` into the container; Helm reads it from the `management-key` entry of the Secret named in `gateway.existingSecret`. See [Docker Compose](#docker-compose) and [Helm](#helm).
+
+There is no command-line flag for the management key, because flags show up in process lists and shell history. Setting, changing or removing it takes a restart. It does not revoke issued gateway keys or change existing upstreams and context profiles.
+
+### Encryption
+
+The gateway encrypts stored credentials and conversation state with OpenViking's own encryption (see the [Encryption guide](08-encryption.md)):
-Keep them in your secret store or deployment environment, not in `ov.conf` or source control. To read them from differently named variables, set `encryption_key_env` and `admin_token_env` in the `gateway` section.
+- **Embedded**: the gateway follows the server's `encryption` section in `ov.conf`. There is nothing to set for the gateway itself.
+- **Standalone**: add an `encryption` block to `gateway.conf`. It has exactly the same fields as the `encryption` section of `ov.conf`, for example:
-- **The encryption key cannot be changed.** Nothing re-encrypts stored data, so with a different key the gateway cannot read what it stored. Back the key up together with the gateway's storage. If it is lost, point `storage_path` at an empty directory and set up upstreams, profiles and keys again.
-- **The admin token can be rotated.** Set the same new value for both processes and restart both. It only protects the management API and encrypts nothing.
-- Without valid secrets the gateway stops at startup. OpenViking Server starts without the admin token, but Studio's OpenViking Gateway page then reports that the management token is not configured.
+ ```json
+ {
+ "openviking_url": "https://ov.example.com",
+ "encryption": {
+ "enabled": true,
+ "provider": "local",
+ "local": { "key_file": "~/.openviking/master.key" }
+ }
+ }
+ ```
+
+When encryption is off or the block is missing, the gateway stores everything in plain text, protected only by file permissions. Turning encryption on later is safe: values written before stay readable, and new writes are encrypted. Turning it off, or switching to a different root key, makes the encrypted values unreadable, so keep the settings the data was written with. Back up the root key as the Encryption guide describes; without it, the gateway's databases cannot be read.
+
+Data written by the v0.5 gateway, which used its own key, is converted on the first start; see [Migration](#migration).
## Deploy
### Deployment options
-The gateway and OpenViking talk only over HTTP, so they can share a machine or a Pod, or run separately. Every form has to meet the [requirements](#requirements): OpenViking 0.4.16 or later in API key mode, gateway storage on a local disk of one host, one gateway instance at a time, the encryption key available to the gateway, and the same admin token in both processes. Leave load balancing, failover and rate limiting to a LiteLLM or new-api gateway behind it.
+| Form | How to enable it | Client address |
+| --- | --- | --- |
+| Embedded in the server (including Compose and Helm) | Turn on `gateway.enabled` in `ov.conf` | The server address plus `/gateway`, `http://127.0.0.1:1933/gateway` by default |
+| Standalone | `openviking-gateway init`, then `openviking-gateway` | The gateway's own address plus `/gateway`, `http://127.0.0.1:1935/gateway` by default |
-| Form | Suits | How to deploy | Watch for |
-| --- | --- | --- | --- |
-| Single machine | Trying it out yourself | Install `openviking[gateway]` and run `openviking-gateway` with the same `ov.conf` as OpenViking; see the [Quick start](15-gateway.md#quick-start). | You can skip the reverse proxy if only this machine uses it. |
-| [Docker Compose](#docker-compose) | Small teams on one server | The gateway runs in its own container, and the bundled Caddy routes by path on port 1934. | The gateway port is not mapped to the host; only the gateway container gets the encryption key. |
-| [Helm](#helm) | Kubernetes | The gateway runs as a second container in the OpenViking Pod, sharing its volume and `ov.conf`. | Keep one replica; the chart cannot split the gateway into its own Pod. |
-| [Separate deployment](#separate-deployment) | Gateway and OpenViking on different machines or Pods | Write your own Deployment or service definitions and put the same `gateway` section in both `ov.conf` files. | Each side must reach the other; the link carries users' OpenViking keys; network latency eats into the recall time limit. |
+Both forms serve the same model and management paths under `/gateway`. An embedded gateway needs no second process and no path-based reverse proxy. A standalone gateway leaves the existing OpenViking service's configuration untouched.
-Both processes read the `gateway` section of the same `ov.conf`. OpenViking Server uses it to find the gateway for Studio and for data deletion; the gateway uses all of it. A few rules apply to this section:
+### Enable it in the server
-- The gateway reads the file given by `--config`, else `OPENVIKING_CONFIG_FILE`, else `~/.openviking/ov.conf`. Unlike OpenViking Server, it does not fall back to `/etc/openviking/ov.conf`.
-- The gateway does not expand `$VAR` or `${VAR}` placeholders. Write literal values in `gateway`, and keep the secrets in the environment variables above.
-- Unknown keys are errors. OpenViking Server reports `Unknown config field 'gateway.<name>'`, and the gateway refuses to start.
-- Restart OpenViking Server after you change the section.
+Run `openviking-server init`, answer yes to **Enable OpenViking Gateway on the same port?**, then start or restart the server. With an existing configuration, choose **Update gateway** from the menu. For a remote deployment, init also asks whether users may configure upstreams themselves; see [Gateway management key](#gateway-management-key).
-Three addresses in this section are easy to mix up:
+You can also merge this into `ov.conf` and restart:
-| Setting | Who uses it | Typical value |
-| --- | --- | --- |
-| `url` | OpenViking Server, to reach the gateway's management API | `http://127.0.0.1:1935`; `http://gateway:1935` in Docker Compose |
-| `openviking_url` | The gateway, to reach OpenViking Server | `http://127.0.0.1:1933`; `http://openviking:1933` in Docker Compose |
-| `public_url` | Clients. Studio shows it in its setup instructions, and OpenViking tools use it for upload links. | `https://ov.example.com` |
+```json
+{
+ "gateway": {
+ "enabled": true
+ }
+}
+```
+
+On a server that uses API keys, root can also choose **Enable gateway** on Studio's OpenViking Gateway page, which writes `gateway.enabled: true` to `ov.conf` and restarts the server (the restart from Studio needs a single-worker server; otherwise Studio only saves the file and you restart the server yourself).
+
+Open `/studio/` on the server and choose **OpenViking Gateway** in the sidebar. In dev mode, if the default account has no upstreams, the gateway imports the server's usable VLM credentials as upstreams at startup and creates a `default` context profile. Imported Coding Plan upstreams need confirmation before use. If nothing can be imported, add an upstream by hand.
+
+**Letting an agent change the configuration.** An agent that holds the root API key can edit `ov.conf` and restart the server through the [runtime configuration API](../api/08-admin.md#runtime-configuration). A standalone gateway does not offer this API.
### Routes
-Serve OpenViking Server and the gateway from one public HTTPS origin and let the reverse proxy route by path:
+Every gateway URL is under `/gateway`, in both forms. An embedded server hands the whole `/gateway` prefix to the gateway and keeps every other path for itself:
-| Path | Goes to | Used for |
-| --- | --- | --- |
-| `/v1/*` | Gateway | Anthropic Messages, Chat Completions, Responses and the model list |
-| `/api/v3/*` | Gateway | Ark paths (Volcano Engine Ark and BytePlus ModelArk) for Chat Completions, Responses and the model list |
-| `/api/compatible/v1/*` | Gateway | Ark's Anthropic-compatible path |
-| `/gateway/uploads` | Gateway | One-time file uploads from OpenViking tools |
-| Everything else | OpenViking Server | Studio, REST API, MCP, OAuth, `/health` |
+| Path prefix | Purpose |
+| --- | --- |
+| `/gateway/v1/` | Model APIs and the model list |
+| `/gateway/api/v3/` | Ark-compatible clients |
+| `/gateway/api/compatible/v1/` | Ark Anthropic-compatible clients |
+| `/gateway/uploads` | Tool uploads |
+| `/gateway/admin/` | Management API (authenticated) |
+
+Clients therefore use these base URLs, with `http://127.0.0.1:1933` replaced by your server's address:
-With this layout, `public_url` is the public origin, for example `https://ov.example.com`. Anthropic clients use that address; OpenAI-style clients add `/v1`.
+| Client | Base URL |
+| --- | --- |
+| Claude Code and Anthropic SDKs | `http://127.0.0.1:1933/gateway` |
+| OpenAI-compatible clients and SDKs, including Codex, OpenCode, pi and Open WebUI | `http://127.0.0.1:1933/gateway/v1` |
+| Volcano Engine Ark and BytePlus ModelArk SDKs | `http://127.0.0.1:1933/gateway/api/v3` |
-> **Security**: Never route the gateway's `/admin/*` paths, or its whole port, from the public entry point. The gateway's management API accepts the admin token for any account. Studio reaches it through OpenViking Server, which checks that you are an account admin and limits every call to your own account. Forward exactly the four path groups above, and keep ports 1933 and 1935 private behind the proxy.
+`/health` stays the server's own health check; an embedded gateway has no separate `/health`.
-Whatever proxy you use, configure the gateway paths for long, streamed model calls:
+A standalone gateway serves the same `/gateway` paths on its own port, plus these at the root:
-- **No response buffering**, so streamed replies reach clients as they are generated.
-- **Request bodies of at least 32 MiB** (`max_body_bytes`). Long conversations with tool output get large, and nginx's default of 1 MB breaks them.
-- **A read timeout of at least 600 seconds** (`upstream_timeout_seconds`).
-- **No query strings in access logs for `/gateway/uploads`**, because they carry one-time upload tokens. The gateway itself writes no access log.
+- `/` redirects to `/studio/`, where Studio has only the gateway and connection pages.
+- `/health` returns `service: "openviking-gateway"`, `auth_mode` and `openviking_url`, and also the caller's identity when the request carries a valid OpenViking credential.
-### Docker Compose
+**Public address.** For a shared deployment, set `public_url` to the address clients use to reach the server (or the standalone gateway), without `/gateway`; the gateway appends `/gateway` itself. When it is empty, an embedded gateway uses the server's public address (`OPENVIKING_PUBLIC_BASE_URL` or `server.public_base_url`). Studio's setup guides build client settings from it: Anthropic clients use `<public_url>/gateway`, and OpenAI-style clients `<public_url>/gateway/v1`. Without it, the guides use the address the browser used to open Studio, but upload links for file imports only work with `public_url` set; see [Import files and skills](#import-files-and-skills).
-The bundled `docker-compose.yml` defines a `gateway` service under the `gateway` profile. It runs the same image with the same `~/.openviking` mount and `ov.conf` as OpenViking Server. Its port 1935 is reachable only inside the Compose network; clients reach it through the bundled Caddy, which already routes the gateway paths on port 1934.
+### Docker Compose
-1. **Put the secrets in `.env`** next to `docker-compose.yml`:
+Set `OPENVIKING_GATEWAY_ENABLED=true` in `.env`, then run `docker compose up -d`; or turn on `gateway.enabled` in the mounted `ov.conf`. The gateway runs inside the `openviking` service; there is no separate service or profile. Without Compose, add `-e OPENVIKING_GATEWAY_ENABLED=true` to `docker run`:
- ```dotenv
- OPENVIKING_GATEWAY_ENCRYPTION_KEY=<encryption-key>
- OPENVIKING_GATEWAY_ADMIN_TOKEN=<admin-token>
- ```
+```bash
+docker run -d -p 1933:1933 -v ~/.openviking:/app/.openviking \
+ -e OPENVIKING_GATEWAY_ENABLED=true \
+ ghcr.io/volcengine/openviking:latest
+```
- Compose passes the admin token to both containers and the encryption key only to the gateway. If either is empty, the gateway exits and Compose restarts it in a loop.
+The server listens on `0.0.0.0` inside the container, so `ov.conf` must use API-key authentication.
-2. **Merge these settings into `~/.openviking/ov.conf`:**
+- **Management key**: set `OPENVIKING_GATEWAY_MANAGEMENT_KEY` in `.env`, and the bundled Compose file passes it into the container; or put it in `gateway.management_key` in the mounted `ov.conf`. The Compose file also passes `OPENVIKING_GATEWAY_ENCRYPTION_KEY`, which is only read once to migrate v0.5 data; see [Migration](#migration).
+- **Public address**: set `OPENVIKING_PUBLIC_BASE_URL` (the bundled Compose file passes it); the gateway uses it when it has no `public_url` of its own.
+- **After a configuration change**: run `docker compose restart openviking`; read startup errors with `docker compose logs openviking`.
- ```json
- {
- "server": {
- "auth_mode": "api_key",
- "root_api_key": "<root-key>"
- },
- "gateway": {
- "enabled": true,
- "host": "0.0.0.0",
- "url": "http://gateway:1935",
- "openviking_url": "http://openviking:1933",
- "public_url": "http://<your-host>:1934"
- }
- }
- ```
+The bundled Caddy forwards all paths to `openviking:1933`. Clients can keep using the compatibility port 1934, or go straight to the server on 1933. For HTTPS, a single `reverse_proxy openviking:1933` carries Studio, the management API and model traffic; see [Public access](12-public-access.md).
- Use `http://<your-host>:1934` while clients reach the bundled Caddy port, or your HTTPS origin once you add one. `storage_path` can keep its default: inside the container it resolves to `/app/.openviking/gateway`, which lies in the mounted volume.
+### Helm
-3. **Start the stack with the profile:**
+Set `gateway.enabled: true` in the chart values. The gateway runs inside the server container, keeps its data in `<persistence.mountPath>/gateway`, and uses the server port for both the Service and the Ingress. Keep `replicaCount: 1`.
- ```bash
- docker compose --profile gateway up -d
- ```
+```yaml
+gateway:
+ enabled: true
+ existingSecret: "" # optional: Secret name, entry management-key
+config:
+ gateway:
+ public_url: https://ov.example.com
+```
- Include `--profile gateway` in later `up` commands as well. After you edit `ov.conf`, restart both containers with `docker compose --profile gateway restart openviking gateway`.
+- The gateway encrypts its data with the chart's `config.encryption` settings, the same as the server.
+- With a `management-key` entry in the `existingSecret` Secret, changing upstreams and context profiles requires that management key.
+- Model requests stream: the Ingress must turn off response buffering and allow request bodies of at least 32 MiB and timeouts of 600 seconds.
-4. **Check the routing.** A request without a key should reach the gateway and be refused:
+The NGINX annotations, the commands to create the Secrets and the notes on upgrading from the sidecar chart are in the [chart README](https://github.com/volcengine/OpenViking/blob/main/deploy/helm/README.md#openviking-gateway).
- ```bash
- curl -s http://127.0.0.1:1934/v1/models
- # {"detail":"Invalid or revoked OpenViking Gateway key"}
- ```
+### Standalone deployment
- Then open Studio and check that the Overview tab shows OpenViking as connected. `docker compose logs gateway` shows startup errors.
+A standalone gateway does not read `ov.conf`. It only needs the OpenViking address, so an existing open-source or OpenViking Cloud service needs no configuration change:
-If the gateway starts before OpenViking Server is ready, it runs without memory until its next check of OpenViking, at most 60 seconds later (`health_interval_seconds`). Messages sent in that window reach the model without memory.
+```bash
+openviking-gateway init # writes ~/.openviking/gateway.conf
+openviking-gateway
+```
-**HTTPS.** Follow [Option A in Public Access](12-public-access.md#adding-https-for-public-access) to set `OPENVIKING_PUBLIC_BASE_URL`, open ports 80 and 443 and add the Caddy volumes, but use this domain block in `Caddyfile` so the gateway paths reach the gateway:
+`openviking-gateway init` asks for the OpenViking address and checks it (showing the server's authentication mode and version), the listen address (`127.0.0.1:1935` by default), and whether to require a [management key](#gateway-management-key). It writes `~/.openviking/gateway.conf`, or the file named by `--config`, readable only by you. Run it again to change the settings: it offers the current values as defaults and keeps existing secrets unless you change them. The resulting file looks like this:
-```caddyfile
-{$OPENVIKING_PUBLIC_BASE_URL} {
- @gateway path /v1/* /api/v3/* /api/compatible/v1/* /gateway/uploads
- handle @gateway {
- reverse_proxy gateway:1935 {
- flush_interval -1
- }
- }
- handle {
- reverse_proxy openviking:{$OPENVIKING_SERVER_PORT:1933}
- }
+```json
+{
+ "openviking_url": "https://ov.example.com",
+ "host": "127.0.0.1",
+ "port": 1935
}
```
-Then set `gateway.public_url` to the same origin, written out literally (for example `https://ov.example.com`), and restart.
+Open the gateway's `/studio/` and sign in with the API key of an OpenViking user, account admin or root. The connection page shows which OpenViking address the gateway uses. A standalone gateway cannot read the remote server's VLM settings, so it cannot import model settings; add upstreams by hand.
-### Helm
+**Where the settings come from.** The only flag is `--config`. When `--config` or `OPENVIKING_GATEWAY_CONFIG_FILE` is set, it must point to an existing file; otherwise the gateway reads the first of `~/.openviking/gateway.conf` and `/etc/openviking/gateway.conf` that exists. Environment variables override any field in it. A container needs no file at all: set `OPENVIKING_GATEWAY_OPENVIKING_URL`, plus for example `OPENVIKING_GATEWAY_HOST=0.0.0.0`. Without an OpenViking address from either source, the gateway exits and asks you to run `openviking-gateway init` or set `OPENVIKING_GATEWAY_OPENVIKING_URL`. Every field and the override rule are in the [Configuration reference](#configuration-reference).
-The chart runs the gateway as a second container in the OpenViking pod, sharing its volume and `ov.conf`.
-
-1. **Create the Secret.** The key names `encryption-key` and `admin-token` are fixed:
-
- ```bash
- kubectl create secret generic openviking-gateway \
- --from-literal=encryption-key="$(python3 -c 'import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())')" \
- --from-literal=admin-token="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
- ```
-
-2. **Enable the gateway in your values.** The NGINX ingress annotations below are recommendations for streaming and large requests; the chart does not set them:
-
- ```yaml
- gateway:
- enabled: true
- existingSecret: openviking-gateway
- workers: 2
-
- config:
- server:
- auth_mode: api_key
- # Pass root_api_key from a Secret as described in the chart README.
- gateway:
- public_url: https://ov.example.com
-
- ingress:
- enabled: true
- className: nginx
- annotations:
- nginx.ingress.kubernetes.io/proxy-buffering: "off"
- nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
- nginx.ingress.kubernetes.io/proxy-body-size: 32m
- nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
- nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
- hosts:
- - host: ov.example.com
- paths:
- - path: /
- pathType: Prefix
- tls:
- - secretName: ov-example-com-tls
- hosts:
- - ov.example.com
- ```
-
-What the chart does when `gateway.enabled` is true:
-
-- It generates the rest of the `gateway` section: `enabled`, `host: 0.0.0.0`, `port`, `workers`, `url: http://127.0.0.1:<port>`, `openviking_url: http://127.0.0.1:<config.server.port>` and `storage_path: <persistence.mountPath>/gateway`. Values you put under `config.gateway` take precedence. Set `public_url` there, as a literal value.
-- It passes the admin token to both containers and the encryption key to the gateway container. The gateway container does not receive `extraEnv`.
-- It adds a `gateway` port to the Service. When the ingress is enabled, it routes `/v1`, `/api/v3`, `/api/compatible/v1` and `/gateway/uploads` to that port, ahead of your own paths.
-- It adds a readiness probe on the gateway's `/health`. `gateway.resources` sets the gateway container's requests and limits.
-
-Keep `replicaCount: 1`. The gateway's storage lives on the ReadWriteOnce volume and must be used from a single host; scale with `gateway.workers` instead. For passing the root key and model keys from Secrets, see the [chart README](https://github.com/volcengine/OpenViking/blob/main/deploy/helm/README.md).
-
-### Separate deployment
-
-When the gateway and OpenViking run on different machines or Pods, the chart and the Compose file no longer apply, and you write the deployment definitions yourself. Put the same `gateway` section in both `ov.conf` files, and keep these points in mind:
-
-- **Set the address in both directions.** The gateway reaches OpenViking at `openviking_url`; OpenViking Server reaches the gateway at `url`, which carries Studio's management calls and user data deletion. Both should be private addresses, and the gateway's `host` must listen on an interface the other side can reach.
-- **Protect the link between them.** The gateway calls OpenViking with each user's own OpenViking key, and management calls carry the admin token, so keep this link on a private network or behind TLS.
-- **Mind the latency.** Recall for each new message waits at most the context profile's **Time limit** (2 seconds by default), and the network round trip between the gateway and OpenViking counts against it. With higher latency, recall times out more often and the message goes to the model without memory.
-- **Upgrade in order.** When you upgrade the two separately, upgrade OpenViking first, then the gateway; see [Upgrades](#upgrades).
-
-### Your own reverse proxy
-
-With nginx on the same host as both processes, route the gateway paths before the catch-all location:
-
-```nginx
-server {
- listen 443 ssl;
- http2 on; # nginx < 1.25.1: remove this line and use `listen 443 ssl http2;`
- server_name ov.example.com;
-
- ssl_certificate /etc/letsencrypt/live/ov.example.com/fullchain.pem;
- ssl_certificate_key /etc/letsencrypt/live/ov.example.com/privkey.pem;
-
- # Model APIs: streamed replies, large histories, slow models.
- location ~ ^/(v1|api/v3|api/compatible/v1)/ {
- proxy_pass http://127.0.0.1:1935;
- proxy_http_version 1.1;
- proxy_buffering off;
- proxy_request_buffering off;
- client_max_body_size 32m;
- proxy_read_timeout 600s;
- proxy_send_timeout 600s;
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-Proto $scheme;
- }
+**Startup checks.** Before it starts, a standalone gateway contacts OpenViking once:
- # One-time file uploads. The query string carries the upload token.
- location = /gateway/uploads {
- proxy_pass http://127.0.0.1:1935;
- proxy_http_version 1.1;
- proxy_request_buffering off;
- client_max_body_size 32m;
- proxy_read_timeout 120s;
- access_log off;
- }
+- If OpenViking uses trusted authentication, the gateway refuses to start.
+- When the gateway binds to a non-loopback address, it starts only after confirming that OpenViking uses `api_key` authentication. If OpenViking is unreachable or runs in dev mode, the gateway exits. Start OpenViking first, or bind to `127.0.0.1`.
+- When OpenViking runs on another host, connect over TLS or a private network.
+
+**Connecting to the public OpenViking service.** When the gateway connects to `https://api.vikingdb.cn-beijing.volces.com/openviking` without a management key, the startup log and Studio show the `public_openviking_without_management_key` warning: anyone with an API key for that service can sign in to this gateway and change the upstreams in their account. If the gateway is only for you or your team, set `OPENVIKING_GATEWAY_MANAGEMENT_KEY` and restart to restrict changes. This does not limit who can sign in or whether they can issue gateway keys for themselves.
+
+### Reverse proxy and HTTPS
- # Studio, REST API, MCP and everything else.
- location / {
- proxy_pass http://127.0.0.1:1933;
- proxy_http_version 1.1;
- proxy_buffering off;
- proxy_read_timeout 300s;
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_set_header X-Forwarded-Host $host;
+Forward the whole site to the server (embedded) or to the gateway (standalone); no path-based routing is needed. With Caddy:
+
+```caddyfile
+ov.example.com {
+ reverse_proxy 127.0.0.1:1933 {
+ flush_interval -1
}
}
```
-If you raise `max_body_bytes` or `upstream_timeout_seconds`, raise `client_max_body_size` and the timeouts with them. For other proxies, apply the same four path groups and the settings listed under [Routes](#routes).
+Whatever proxy you use, it needs three things: response buffering off, so streamed output arrives in real time; request bodies of at least 32 MiB; and read timeouts of at least 600 seconds. Also keep the query strings of `/gateway/uploads` out of proxy logs, because they carry one-time upload tokens. Set up authentication before you expose the service; see [Public access](12-public-access.md).
### Scaling
-- **Workers.** `workers` (1–64; 1 by default, 2 in the Helm chart) sets how many gateway processes run on the host. They share the storage files, and each one also saves conversations in the background.
-- **One host.** Running the gateway on several hosts, or on a network file system, is not supported. With Helm, keep one replica.
-- **Change propagation.** Revoking a key or editing an upstream reaches the other worker processes within about 2 seconds.
-- **Health per process.** Each worker checks OpenViking on its own, so the OpenViking status on the Overview tab comes from whichever process answered.
-- **No load balancing or rate limiting.** Each conversation stays on one upstream, and the gateway neither retries on another upstream nor throttles requests; provider 429 responses reach the client unchanged. If you need balancing, failover or quotas, run LiteLLM or new-api behind the gateway as an upstream.
+One storage directory serves one deployment on one host, and an embedded and a standalone gateway must not share a directory. An embedded gateway follows the server's worker setting; a standalone gateway takes `workers`, from 1 to 64. For load balancing, failover or rate limiting across providers, add a service such as LiteLLM as an upstream.
## Manage the gateway in Studio
-Open Studio at `/studio` on OpenViking Server, open **Connection Settings** and enter an account admin key as the **Admin API key**. **OpenViking Gateway** then appears in the sidebar's **Settings** group; only account admins and root see it. Everything on these pages belongs to the account of that key. The page header shows the gateway address clients should use: `public_url`, or `url` while `public_url` is empty, in which case the **Connect** tab warns that clients may not reach it.
+Connect Studio with an OpenViking API key and open **OpenViking Gateway** in the sidebar. Upstreams and context profiles are shared by the whole account; gateway keys and request logs belong to individual users.
+
+- **No management key set**: every signed-in user can add and change the account's upstreams and context profiles.
+- **Management key set**: the Upstreams and Profiles tabs are read-only, for OpenViking admins and root too. Read-only users can still view and test upstreams (without their API keys and headers) and pick them when issuing keys for themselves. Choose **Enter gateway management key** to unlock editing; the header then shows **Editing upstreams and profiles**. Editing stays unlocked until you choose **Lock** or close the browser tab. If the management key is changed, Studio locks again on its own.
+- **Gateway keys**: everyone can issue keys for themselves; account admins can issue keys for users in their account; root first switches account in the sidebar. See [Gateway keys](#gateway-keys).
-If the gateway is not set up or cannot be reached, the page shows a setup card naming the setting to fix; see [Studio shows a setup card](#studio-shows-a-setup-card). Otherwise it has six tabs: **Overview**, **Upstreams**, **Profiles**, **Keys**, **Requests** and **Connect**. A new setup goes in that order: add an upstream, create a context profile, issue a gateway key, then connect a client using the Connect tab.
+Saved upstreams and context profiles take effect at once for the keys that use them (a context profile only affects conversations that start afterwards). If no usable upstream or context profile exists yet and you cannot change them, ask whoever deployed the gateway.
### Upstreams
-An upstream is one model provider endpoint that speaks one API: Anthropic Messages, Chat Completions or Responses. The gateway never converts between them, so add one upstream for each API your clients use, even when they share a provider: Anthropic Messages for Claude Code, Responses for Codex CLI, Chat Completions for most chat apps and SDKs.
+An upstream is one endpoint of a model service and uses exactly one API: Anthropic Messages, Chat Completions or Responses. The gateway does not convert between APIs, so add one upstream for each API your clients use, even when they come from the same provider. Claude Code uses Anthropic Messages, Codex CLI uses Responses, and most chat apps and SDKs use Chat Completions.
-Each provider offers these protocols, and the editor fills in the provider's default Base URL when you choose it:
+When you choose a provider in the editor, its default Base URL is filled in:
| Provider | Protocols | Default Base URL |
| --- | --- | --- |
-| Generic | All three | None; enter the address yourself |
+| Generic | All three | None; enter it yourself |
| Anthropic | Anthropic Messages | `https://api.anthropic.com` |
| OpenAI | Chat Completions, Responses | `https://api.openai.com/v1` |
| DeepSeek | All three | `https://api.deepseek.com`; `https://api.deepseek.com/anthropic` for Anthropic Messages |
-| Volcano Engine Ark | All three | `https://ark.cn-beijing.volces.com` |
-| BytePlus ModelArk | All three | `https://ark.ap-southeast.bytepluses.com` |
+| Volcano Engine Ark | All three | `https://ark.cn-beijing.volces.com/api/v3` for Chat Completions and Responses; `https://ark.cn-beijing.volces.com/api/compatible` for Anthropic Messages |
+| BytePlus ModelArk | All three | `https://ark.ap-southeast.bytepluses.com/api/v3` for Chat Completions and Responses; `https://ark.ap-southeast.bytepluses.com/api/compatible` for Anthropic Messages |
-The upstream editor has four sections.
+#### Endpoint
-**Endpoint.**
-
-- **Provider** decides which protocols you can pick and adjusts the gateway to the provider's quirks. The editor offers only the protocols the provider supports, as listed in the table above. Choose *Generic* for a provider not listed here, a compatible proxy such as LiteLLM or new-api, or a reverse proxy such as [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) that exposes subscription accounts as an API (see [Custom upstreams](15-gateway.md#custom-upstreams); make sure using subscription quota this way complies with your provider's terms).
+- **Provider** decides which protocols you can pick and lets the gateway handle each provider's differences. Choose *Generic* for a provider not in the list, for a compatible proxy such as LiteLLM or new-api, and for a reverse proxy such as [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) that exposes subscription accounts as an API (see [Custom upstreams](15-gateway.md#custom-upstreams); check yourself whether using subscription quota this way is allowed).
- *Generic*, *Anthropic* and *OpenAI* forward requests the same way.
- - *DeepSeek*: with tools present, DeepSeek requires every earlier reply in the history to carry its reasoning, which many chat apps do not send back. DeepSeek upstreams have **Restore reasoning the client drops** on by default (see Routing below), so requests keep thinking on and still get OpenViking tools. With that setting off, OpenViking tools are offered only when a request turns thinking off (`"thinking": {"type": "disabled"}`); standard Responses requests have no `thinking` field, so they then get no tools. Memory is added as usual.
- - *Volcano Engine Ark* and *BytePlus ModelArk*, Ark's international edition, work the same way: requests go to Ark's own paths. Each conversation gets a stable `prompt_cache_key` for Chat Completions and Responses, so Ark's prefix cache follows the conversation. Requests whose model, thinking, sampling, system prompt or tools differ from the conversation's first request are flagged **Cache parameters changed** (`ark_cache_parameters_changed`), because Ark resets its cache when these change.
-- **Protocol** decides which client requests the upstream can serve, and how the gateway sends the key: `x-api-key` for Anthropic Messages, `Authorization: Bearer` for the others.
-- **Base URL.** Choosing a provider fills in its default address from the table above. Switching the provider or protocol replaces the address only while it is empty or still the previous default, so an address you entered is kept; when it differs from the default, **Use default** under the field puts the default back. The gateway appends the client's request path and drops a duplicate `/v1`, so `https://api.openai.com/v1` and `https://api.anthropic.com` both work. The editor shows where requests will go. For Ark and ModelArk, use the origin without a path, such as `https://ark.cn-beijing.volces.com`, which works for every protocol; a base ending in `/api/v3` works only for Chat Completions and Responses, and one ending in `/api/compatible/v1` only for Anthropic Messages. A provider whose API path does not end in `/v1`, such as `…/api/paas/v4`, cannot be used directly; put a compatible proxy such as LiteLLM in between.
+ - *DeepSeek*: when a request has tools, DeepSeek requires every earlier reply in the history to carry its reasoning, and many chat apps do not send it back. DeepSeek upstreams have **Restore reasoning the client drops** on by default (see [Routing](#routing)), so requests can keep thinking on and still get OpenViking tools. With that setting off, OpenViking tools are offered only when a request turns thinking off (`"thinking": {"type": "disabled"}`). Standard Responses requests have no `thinking` field, so they then get no tools. Memory is added as usual.
+ - *Volcano Engine Ark* and *BytePlus ModelArk* behave the same: each Chat Completions and Responses conversation gets a fixed `prompt_cache_key`, so Ark's prefix cache follows the conversation. If a request's model, thinking mode, sampling parameters, system prompt or tools differ from the conversation's first request, Ark rebuilds its cache, and the request is flagged **Cache parameters changed** (`ark_cache_parameters_changed`).
+- **Protocol** decides which API the upstream accepts. Anthropic upstreams send both `x-api-key` and `Authorization: Bearer`; Chat Completions and Responses upstreams send only Bearer.
+- **Base URL**: copy it from the provider's SDK documentation. The gateway appends the endpoint to it:
+ - Chat Completions and Responses append `/chat/completions` or `/responses`. A bare domain does not get `/v1` added, so OpenAI needs `https://api.openai.com/v1`.
+ - Anthropic Messages appends `/v1/messages`, so the Base URL must not end in `/v1`; saving such a URL is rejected.
+ - A trailing slash is removed. Addresses with a version path, such as `/api/paas/v4`, work as is.
+ - Requests that clients send to the Ark paths (`/gateway/api/v3/`, `/gateway/api/compatible/v1/`) follow the same rules.
+ - An upstream has one Base URL. If a provider uses different addresses for different protocols, create separate upstreams. For example, Zhipu uses `https://open.bigmodel.cn/api/paas/v4` for Chat Completions and `https://open.bigmodel.cn/api/v1` for Responses. Ark Coding Plan uses `…/api/coding/v3` for Chat Completions and Responses and `…/api/coding` for Anthropic Messages.
+
+ The editor previews the final request URL as you type. If an OpenAI or Ark address is missing its path, or an Anthropic address ends in `/v1`, it warns you and offers a one-click fix.
-**Credentials.**
+#### Credentials
- **Who provides the API key**:
- - **The gateway holds the API key** (the default): the gateway sends the upstream's key, and clients need only a gateway key.
- - **Each client sends its own key**: every request must also carry the client's own provider key in an `X-OpenViking-Upstream-Key` header, next to its gateway key. Requests without it fail with 401 "Upstream API key is missing". The gateway passes the key to the provider in the provider's usual header and never forwards `X-OpenViking-*` headers.
-- **API key** and **Extra headers** are write-only. When you edit an upstream, leave the API key blank to keep the stored one. Extra headers show their names only: leave a value blank to keep it, or remove the row to delete the header. A stored API key cannot be cleared; to stop using it, switch to "Each client sends its own key" or delete the upstream.
-- **Extra headers** are added to every request to this upstream, such as a provider's version or organization header, and replace a client header of the same name. `Host`, `Content-Length`, `Transfer-Encoding` and `Connection` are not allowed.
-- **This key is a Coding Plan or subscription key.** Providers restrict Coding Plan and similar subscription keys to their own coding tools, and using one through a shared gateway can get the subscription suspended. When you check this box, every request routed to the upstream is rejected with 403 "Coding Plan upstreams are disabled; configure a model API key", unless you also check **Allow it anyway**. The gateway cannot tell such keys apart from ordinary ones, so mark them yourself. Claude subscription tokens (`sk-ant-oat…`) are always rejected.
+ - **The gateway holds the API key** (the default): the gateway sends the upstream's API key, and clients need only their gateway key.
+ - **Each client sends its own key**: besides the gateway key, every request carries the client's own provider API key in the `X-OpenViking-Upstream-Key` header. Without it the request fails with 401 "Upstream API key is missing". The gateway passes the key to the provider in the provider's usual header; `X-OpenViking-*` headers themselves are never forwarded.
+- **API key and extra headers are write-only.** Leave a field blank to keep the stored value; remove a header row to delete that header. **Changing the Base URL clears the stored API key and header values**, so enter them again whenever you change the address. A stored key is never sent to a new address.
+- **Extra headers** are added to every request to this upstream, such as a provider's version or organization header, and replace any client header with the same name. `Host`, `Content-Length`, `Transfer-Encoding` and `Connection` cannot be set.
+- **This key is a Coding Plan or subscription key**: providers usually allow subscription keys such as Coding Plan keys only in their own coding tools, and using one through a shared gateway can get the subscription suspended. When you check this, every request to the upstream is rejected with 403 "Coding Plan upstreams are disabled; configure a model API key", unless you also check **Allow this plan through the gateway**. The gateway cannot tell from the key itself whether it is a subscription key, so you have to mark it. Claude subscription tokens (`sk-ant-oat…`) are always rejected.
-**Models.**
+#### Models
-- **Models** lists the model names this upstream serves. Leave it empty to accept any name. Only listed names and aliases appear in the model list clients can request (`/v1/models`).
-- **Model aliases** map a name clients use to the model sent to the upstream, for example the Claude model names Claude Code asks for to the model your provider serves. Aliases appear in the model list, and request logs show the name the client used.
-- **Context windows** maps a model to its context window in tokens (at least 1,024), keyed by the name sent to the upstream after aliases. Long conversations are compacted at a share of this window. A model not listed here uses the profile's **Default context window**, or 1,000,000 tokens when that is not set either, so list every model with a smaller window; see [Long conversations](#long-conversations).
+- **Models** lists the model names this upstream serves. Leave it empty to accept any name. Only listed names and aliases appear in the model list (`/gateway/v1/models`).
+- **Model aliases** map a name that clients use to the model sent to the upstream, for example the Claude model names Claude Code requests to a model your provider serves. Aliases appear in the model list, and the request log shows the name the client used.
+- **Context windows** records each model's window size in tokens (at least 1,024), keyed by the model name actually sent to the upstream, after aliases. Long conversations are compacted at a share of this window, so list every model whose window is smaller than 1,000,000 tokens; see [Long conversations](#long-conversations).
-**Routing.**
+#### Routing
-- **Priority.** For each request, the gateway considers the enabled upstreams bound to the key that speak the request's API and serve its model, and picks the highest priority. A conversation stays on the upstream it started with as long as that upstream can still serve it, so priority changes affect new conversations.
-- **Enabled.** A disabled upstream receives no requests and disappears from the model list. Conversations that were using it move to the next candidate, which costs one provider cache miss and drops earlier Claude thinking blocks; these requests are flagged **Upstream switched** (`upstream_changed`). Disabling is the reversible alternative to deleting.
-- **Allow OpenViking tools** controls whether OpenViking tools may be offered through this upstream. Turning it off takes effect at once, also in conversations that already have the tools.
-- **Restore reasoning the client drops.** Clients often leave the model's reasoning out of earlier replies when they send the history back. With this on, the gateway records the reasoning of every reply it relays and puts it back on that reply in later requests: `reasoning_content` for Chat Completions, thinking blocks in their original positions for Anthropic Messages, and reasoning items with plain-text content before their item for Responses. The restored content is byte-identical every turn, so the provider's prompt cache keeps hitting; it does count as input tokens. Replies whose reasoning the client sent back itself are left unchanged. It is on by default for DeepSeek, Volcano Engine Ark and BytePlus ModelArk, and off for other providers. DeepSeek rejects tool requests whose history lacks reasoning, so with this off a DeepSeek upstream offers OpenViking tools only when a request turns thinking off. The same applies to single requests whose reasoning cannot be restored even with this on: the conversation moved to another upstream (`upstream_changed`), a Claude conversation lost its memory record (`missing_injection_record`), or the client resent thinking as text.
-- **Minimum cacheable prompt** (Ark and ModelArk only) is the shortest prompt the model caches. It only affects how the request log reports cache eligibility.
+- **Priority**: for each request, the gateway looks at the enabled upstreams bound to the key that use the request's API and serve the requested model, and picks the one with the highest priority. Once a conversation starts, it stays on its upstream as long as that upstream can still serve it, so priority changes only affect new conversations.
+- **Enabled**: a turned-off upstream receives no requests and disappears from the model list. Conversations that were using it move to the next candidate, which costs one provider cache miss and drops earlier Claude thinking blocks; these requests are flagged **Upstream switched** (`upstream_changed`). Turn an upstream off instead of deleting it if you may want it back.
+- **Allow OpenViking tools**: decides whether OpenViking tools can be offered through this upstream. Turning it off takes effect at once, also in conversations that already have the tools.
+- **Restore reasoning the client drops**: when clients send the history back, they often leave out the reasoning of the model's earlier replies. With this on, the gateway records the reasoning of every reply it relays and puts it back in later requests: `reasoning_content` for Chat Completions, thinking blocks for Anthropic Messages, and reasoning items with plain-text content before their item for Responses. The restored content is byte-identical every time, so the provider's prompt cache keeps hitting, but it counts as input tokens. Replies whose reasoning the client sent back itself are left alone. It is on by default for DeepSeek, Volcano Engine Ark and BytePlus ModelArk, and off for other providers. Some requests cannot get their reasoning back even with this on: the conversation moved to another upstream (`upstream_changed`), a Claude conversation lost its memory record (`missing_injection_record`), or the client sent thinking back as plain text. On a DeepSeek upstream, such requests also get no OpenViking tools.
+- **Minimum cacheable prompt** (Ark and ModelArk only): the shortest prompt the model can cache. It only affects how the request log reports cache eligibility.
-Every other upstream setting takes effect at once, in existing conversations too. There is no failover: when the chosen upstream fails, the client receives the error, and an unreachable provider returns 502 "Model upstream is unavailable".
+All upstream settings except priority take effect at once, in ongoing conversations too. The gateway does not fail over: when the chosen upstream returns an error, the client receives it, and an unreachable provider returns 502 "Model upstream is unavailable".
-**Test** on the list and **Test connection** in the editor request the provider's model list (`/v1/models`, or `/api/v3/models` on Ark and ModelArk) with the upstream's credentials and headers, waiting up to 10 seconds. A pass means the host is reachable and the key is accepted there. The test does not check model names or the Coding Plan setting. A provider without a model-list endpoint, or one that needs extra headers on it, can fail the test while real requests work. Upstreams where each client sends its own key cannot be tested.
+#### Test and delete
-An upstream that a key uses cannot be deleted; revoke those keys first, or disable the upstream.
+Choose **Test** in the upstream list. The gateway asks the provider for its model list with the stored credentials and tells you whether the address answered and the key was accepted. Read-only users can run it too. The test does not check a specific model, and passing it does not mean Coding Plan use is allowed; each result is explained in [Connection tests](../api/25-gateway.md#connection-tests).
-### Context profiles
+An upstream that keys still use cannot be deleted. Revoke those keys first, or turn the upstream off instead.
-A context profile is a named set of memory settings. Each gateway key uses one profile, and one profile can serve many keys. You might keep a "Coding" profile that recalls memories, resources and skills, and a "Chat" profile that recalls only memories with a smaller budget.
+### Import OpenViking model settings
-The **Profiles** tab shows one card per profile with a summary of its four sections and the number of keys using it. While the tab is empty, **Create with recommended settings** creates a profile named "Default" in one click and **Customize** opens the editor; after that, **New profile** opens the editor. A profile that a key uses cannot be deleted; **Duplicate** is a quick way to start a variant.
+In an embedded deployment, **Use OpenViking's model settings** (**Import from OpenViking** in the Upstreams tab header) turns the server's VLM credentials into upstreams in the current account. Without a management key, only root (including local dev) can import; with one, unlock editing first.
-> **Note**: Saved changes apply to conversations that start afterwards. A conversation takes a snapshot of its key's profile at its first request and keeps it, because changing what the model sees in the middle of a conversation would break the provider cache. Clients that open a new conversation for every chat pick up changes quickly. Claude Code, Codex and clients that send a stable session header keep the old settings until they start a new conversation, or until the conversation has gone unused for 30 days (`session_ttl_days`).
+- The result shows three groups: imported, needs confirmation and not imported. Upstreams whose path contains `coding` or `plan` are marked as Coding Plan. Once you have confirmed that the provider's terms allow it, check **Allow this plan through the gateway** to use one.
+- Importing again does not create duplicates. It refreshes the address, API key, headers, protocol and provider from the server, and keeps what you changed in the gateway: name, enabled state, priority, models, aliases, context windows and the Coding Plan confirmation.
+- Codex OAuth and Azure credentials, LiteLLM credentials without `api_base`, and LiteLLM routes that do not use the OpenAI Chat Completions API are skipped. The reasons are listed in [Import VLM settings](../api/25-gateway.md#import-vlm-settings).
-Each section has its own switch; Long conversations has one for each of its two features:
+### Context profiles
+
+A context profile is a named set of memory settings. Each gateway key uses one profile, and one profile can serve many keys. For example, a "Coding" profile might recall memories, resources and skills, while a "Chat" profile recalls only memories, with a smaller budget.
+
+The Profiles tab shows one card per profile, summarizing each section and counting the keys that use it. While the tab is empty, **Create with recommended settings** creates a profile named "Default" in one click and **Customize** opens the editor; after that, use **New profile**. A profile that keys use cannot be deleted. To make a variant, **Duplicate** is the quickest way.
+
+> **Note**: Saved changes apply only to conversations that start afterwards. A conversation records its profile at its first request and keeps it, because changing what the model sees mid-conversation would break the provider cache. Clients that open a new conversation for every chat pick up changes quickly. Claude Code, Codex and clients that send a fixed session header keep the old settings until they start a new conversation, or until the conversation has been idle for 30 days (`session_ttl_days`).
| Section | What it does | Main settings and defaults |
| --- | --- | --- |
| Recall memory | Searches OpenViking with each new user message and appends what is relevant to that message. | Sources: memories, resources, skills · Budget per message: 1,600 tokens · Budget per context window: 30,000 tokens · Relevance threshold: 0.35 · Time limit: 2 s |
| Save conversations | Writes finished turns to an OpenViking session and commits it, so OpenViking can extract memories. | Save the latest reply after: 600 s · Commit after: 20,000 tokens · Keep recent messages: 10 |
-| Long conversations | Compacts a conversation near the model's context window: the same model summarizes it, and the summary replaces the earlier messages. Agent-managed context windows are an experimental alternative. | Compaction: on · Compact at: 0.9 of the context window · Summary length: 8,000 tokens · Agent-managed context windows: off |
-| OpenViking tools | Lets the model use OpenViking's tools while it answers. Chat Completions, full-history Responses and Anthropic Messages. On by default for new profiles. | Read-only tools selected; tools that change data unchecked |
+| Long conversations | When a conversation nears the context window, has the same model write a summary that replaces the earlier messages. | Compaction: on · Compact at: 0.9 of the window · Summary length: 8,000 tokens · Agent-managed context windows: off |
+| OpenViking tools | Lets the model use OpenViking's tools while it answers. | On · read-only tools selected; see [OpenViking tools](#openviking-tools) |
-How the recall settings play out:
+Each section has its own switch, and Long conversations has one each for compaction and agent-managed context windows. Recall and saving are independent: a profile can recall without saving, or save without recalling.
-- **User profile at conversation start** provides your OpenViking profile independently of recall. With the Read tool enabled, memory and skill catalogs are also provided. **Opening context budget** caps these at 4,000 tokens by default, with at most a quarter for skills; 0 omits them all. This does not consume the recall budget.
-- Recall uses the content OpenViking selects and formats within the requested budget, including entries that provide a URI for the model to read later.
+**Recall details:**
-- The search query is the user message with client noise removed, cut to **Query length** characters (8,000). Messages shorter than 3 characters are not searched.
-- Each message gets at most the smaller of **Budget per message** and what is left of **Budget per context window**; with less than 64 tokens left, the gateway skips the search. The budget per context window starts over whenever the conversation is compacted, by the gateway or by the client. A budget of 0 turns recall off. Token counts are a conservative estimate, not the provider's billing count.
-- If OpenViking does not answer within the **Time limit**, the message goes to the model without memory and never gets it later, even when the client retries.
-- **Limit by category** (under **Advanced settings**) searches only the categories with a limit above 0, among events, entities, preferences, experiences, resources and skills, and takes at most that many entries from each. When it is off, all sources are ranked together.
+- **User profile at conversation start** works independently of recall. When the `read` tool is offered, memory and skill catalogs are added at the start as well. **Opening context budget** is 4,000 tokens by default, with at most a quarter for skills; 0 leaves all of it out. It does not count against the recall budget.
+- OpenViking selects and formats the recalled content within the budget. It may also return just a URI for the model to read later.
+- The search query is the user message with client noise removed, cut to **Query length** (8,000) characters. Messages shorter than 3 characters are not searched.
+- Each message gets at most the smaller of **Budget per message** and what is left of **Budget per context window**. With less than 64 tokens left, the search is skipped. The budget per context window starts over whenever the conversation is compacted, by the gateway or by the client. A budget of 0 turns recall off. These token counts are conservative estimates, not the provider's billing counts.
+- If OpenViking does not answer within the **Time limit**, the message goes to the model without memory and does not get it later, even if the client retries.
+- **Limit by category** (under **Advanced settings**) sets a maximum number of entries for each of six categories: events, entities, preferences, experiences, resources and skills. Only categories above 0 are searched. When it is off, all sources are ranked together.
-**Recall summary.** With **Show recall summary** on (off by default), the reply to each new user message starts with a short summary of what the gateway added to that message:
+**Recall summary.** With **Show recall summary** on (off by default), the reply to each new user message starts with a short summary of what the gateway added:
```text
> OpenViking context: user profile, memory index, skill list, earlier sessions
> OpenViking recall: 4 items (3 memories, 1 resource) — booking_duplicate_handling, user_lang_pref, +2 more
```
-The `context` line appears only in the first reply of a conversation and lists only what was actually provided at its start: the user profile, the memory and skill catalogs, and where earlier parts of the conversation are saved in OpenViking. The `recall` line counts the recalled entries by kind and names up to three of them. When the search fails, the line gives the reason instead, for example `> OpenViking recall failed: OpenViking unavailable`. The `recall` line is left out when nothing relevant was found, when recall is off or when its budget is used up, so after the first reply such a message gets no summary at all. Tool steps and other follow-up requests never get one, and a retry of the same message shows the same summary again. In Anthropic Messages the summary is a text block of its own, in Responses an assistant message of its own, and in Chat Completions the start of the reply text. Requests that ask for structured output (a JSON format) and Chat Completions requests with `n` above 1 get no summary. The setting works with or without OpenViking tools. The model never sees it: when the client sends the reply back with the next message, the gateway removes the summary before it forwards the request, and it never saves the summary to OpenViking. Like the other profile settings, the change applies to new conversations.
+- The `context` line appears only in the first reply of a conversation. It lists what the opening actually contained: the user profile, the memory catalog, the skill catalog, and where earlier parts of the conversation are stored in OpenViking.
+- The `recall` line counts the recalled entries by kind and names up to three. If the search fails, it gives the reason instead, for example `> OpenViking recall failed: OpenViking unavailable`. It is left out when nothing was found, recall is off or the budget is used up, so after the first reply such messages get no summary.
+- Tool steps and other follow-up requests show no summary. When the client retries the same message, the summary is the same as the first time.
+- In Anthropic Messages the summary is its own text block, in Responses its own assistant message, and in Chat Completions the start of the reply text. Requests that ask for structured output, and Chat Completions requests with `n` above 1, get no summary.
+- The model never sees the summary: when the client sends the reply back with the next message, the gateway removes it before forwarding, and it is not saved to OpenViking.
-How the saving settings play out:
+**Saving details:**
-- A turn is saved when the next user message arrives. **Save the latest reply after** sets how long the gateway waits before it also saves the last turn and commits the session, so short conversations get committed too.
-- **Commit after** commits the session whenever that many tokens are waiting in it. OpenViking extracts memories at each commit, in the background.
-- **Keep recent messages** keeps the newest whole turns, at least this many messages, in the session after a commit.
-- Recall and saving are independent: a profile that only saves, or only recalls, is valid.
+- A turn is saved when the next user message arrives. **Save the latest reply after** sets how long the gateway waits before it saves the last turn and commits the session, so short conversations get committed too.
+- **Commit after**: the session is committed whenever this many tokens are waiting. After each commit, OpenViking extracts memories in the background.
+- **Keep recent messages**: after a commit, the session keeps the newest whole turns, at least this many messages.
-The [Configuration reference](#configuration-reference) lists every setting with its API name and limits.
+The API name and range of every setting are in the [Configuration reference](#configuration-reference).
### Gateway keys
-A gateway key (`ovgw_…`) is what a client uses in place of a provider key. Each key belongs to one OpenViking user and uses one context profile and a set of upstreams.
+A gateway key (`ovgw_…`) is what a client uses in place of a provider API key. Each key belongs to one OpenViking user and uses one context profile and a set of upstreams.
-To issue one, choose **Issue key** on the **Keys** tab and fill in:
+On the Keys tab, choose **Issue key** and fill in:
-- **Name**, to recognize the key later, for example "alice · Claude Code".
-- **OpenViking user**: a user or admin in this account. The gateway searches and saves memory as this user. When you issue the key, OpenViking Server reads this user's OpenViking key and hands it to the gateway, which stores it encrypted; the key never passes through the browser and is never shown. If OpenViking Server stores only key hashes (`encryption.api_key_hashing.enabled`), or cannot read a user's key for another reason, that user can't be chosen in the list. Choose **Paste an OpenViking key** instead and enter the user's own key. When Studio is signed in with a root key, there is no list to choose from: a root key may resolve to another account than the one Studio shows, so paste the user's key. A pasted key can't be a root key.
+- **Name**: something to recognize the key by, for example "alice · Claude Code".
+- **Who is this for?**: users issue keys only for themselves; account admins can choose a user in their account; root switches account in the sidebar first. The gateway reads the chosen user's API key from OpenViking. If OpenViking stores only key hashes, it cannot, and Studio shows **Paste a user API key** so you can enter that user's current key. A root API key cannot be bound to a gateway key. In local dev mode, keys read and write memory as the `default` user.
- **Context profile**.
-- **Upstreams**: at least one. The key can reach only these.
-- **Allowed models** (optional): leave empty to allow every model these upstreams serve. The names are the ones clients send, including aliases. Requests for other models fail with 403 "Model is not allowed by this key", and the model list shows only allowed names.
+- **Upstreams**: at least one. The key can reach only the upstreams you select.
+- **Allowed models** (optional): leave empty to allow every model these upstreams serve. Enter the names clients send, including aliases. Requests for other models fail with 403 "Model is not allowed by this key", and the model list shows only allowed names.
-Before issuing, the gateway checks the user's OpenViking key with OpenViking. A pasted root key, a key from another account or an invalid key, or an unreachable OpenViking, stops the issue; see [Issuing a key fails](#issuing-a-key-fails).
+Before issuing, the gateway checks the user's key with OpenViking. If you paste a root key, a key from another account or an invalid key, or OpenViking is unreachable, issuing fails; see [Issuing a key fails](#issuing-a-key-fails).
-The **Copy your gateway key** dialog then shows the full key. This is the only time it is shown: the gateway keeps only a hash and the first characters. The dialog also has ready-to-paste setups for Claude Code, Codex CLI and chat clients with the real key and gateway address filled in. If a key is lost, issue a new one.
+After issuing, the **Copy your gateway key** dialog shows the full key. This is the only time you see it: the gateway keeps only a hash and the first few characters. The dialog also has setups for Claude Code, Codex CLI and chat clients, with the real key and gateway address filled in, ready to paste. If a key is lost, issue a new one.
-- **Keys cannot be edited.** To change a key's profile, upstreams, allowed models or OpenViking user, issue a new key and revoke the old one.
-- **Conversations belong to the user, not the key.** A new key for the same OpenViking user continues the same conversations when the client sends the same session ID, so replacing a key is seamless.
-- **Revoking** cuts off clients at once (other worker processes follow within about 2 seconds); requests already in flight finish. Turns not yet saved for conversations last used with that key are dropped. Conversations and memories stay. To replace a key without losing turns, switch the client to the new key first, then revoke the old one.
-- **When an OpenViking key changes.** The gateway keeps the user's OpenViking key from the time the key was issued. If that key is regenerated or removed, the gateway key keeps authenticating clients, but memory search fails and saving pauses with `openviking_http_401`. Issue a new gateway key for the user (Studio reads their new OpenViking key), switch the client, and revoke the old gateway key.
-- **One key per person.** Everyone using a key shares the memory of its OpenViking user. Issue one key per person, and per client when you want different profiles.
+- **Keys cannot be edited.** To change a key's context profile, upstreams, allowed models or user, issue a new key and revoke the old one.
+- **Conversations belong to the user, not the key.** If the client sends the same session ID, a new key for the same user continues the existing conversation, so replacing a key does not interrupt it.
+- **Revoking** a key stops it working at once. The user's conversation state and logs stay until they are explicitly deleted or expire.
+- **When the OpenViking key changes**: after the user's OpenViking API key is regenerated or the user is deleted, OpenViking rejects the old key the gateway stored. The gateway notices on a later request (up to about 30 seconds later) and deletes the gateway keys bound to it; conversation state and logs stay. Issue a new key with the current OpenViking key. If OpenViking is only unreachable or returns an error, the gateway keeps the key, and requests still reach the model, just without memory.
+- **One key per person.** Everyone who shares a key shares the memory of its OpenViking user. Issue one key per person, and separate keys per client if you want different context profiles.
-**Delete this user's gateway data…** (in a key's **More actions** menu) revokes every gateway key of that OpenViking user and deletes the gateway's conversation state for them. Sessions and memories in OpenViking are not affected; delete those in OpenViking. Removing a user or account in OpenViking does this automatically; see [Security and data](#security-and-data).
+Account admins and root can use **Delete this user's gateway data…** on the Keys tab. It revokes all of the user's gateway keys and deletes the conversation state the gateway keeps for them (including content not yet saved to OpenViking) and their request logs. Memories already in OpenViking are not affected; see [Security and data](#security-and-data).
### Requests and overview
-The **Overview** tab summarizes the latest 10,000 request-log records within the log retention period (30 days by default):
+Users see only their own requests; account admins and root see the whole account's.
+
+The **Overview** tab summarizes the latest 10,000 requests within the log retention period (30 days by default):
-- A **Get started** checklist until the first request arrives.
-- **Requests**: the number of model requests, when the last one arrived and how many output tokens they used.
-- **First-call cache hit rate**: the share of input tokens served from the provider's prompt cache on the first model call of each new user message. This is the gateway's most important health signal. It should stay close to what the provider reaches without the gateway; a drop usually means the history the gateway sends no longer matches the previous request. See [The first-call cache hit rate dropped](#the-first-call-cache-hit-rate-dropped).
-- **Within-turn cache hit rate**: the same for later calls within a turn, such as tool steps and OpenViking tool rounds. It is usually high either way.
-- **Memory entries recalled**: entries added to new messages, and how long a search in OpenViking took on average, counting only messages that searched.
-- **OpenViking**: Connected, Degraded or Starting, with the version, authentication mode and, when degraded, the reason. While OpenViking is unreachable, requests still reach the model without memory. Under **Saving conversations**, the card also counts conversations that are retrying or have paused saving to OpenViking.
-- **Degraded requests**: how often each issue occurred, with an explanation; the issues are listed in the [troubleshooting table](#issues-on-degraded-requests).
+- Until the first request arrives, a **Get started** checklist, in the order upstream → context profile → key → client.
+- **Requests**: the number of model requests, when the last one arrived, and their output tokens.
+- **First-call cache hit rate**: the share of input tokens served from the provider's prompt cache on the first model call of each new user message. This is the most important sign of a healthy gateway. It should stay close to what the provider reaches without the gateway. A clear drop usually means the history the gateway sends no longer matches the previous request; see [The first-call cache hit rate dropped](#the-first-call-cache-hit-rate-dropped).
+- **Within-turn cache hit rate**: the same for later calls in a turn, such as tool steps and OpenViking tool rounds. It is usually high.
+- **Memory entries recalled**: entries added to new messages, and how long an OpenViking search took on average (counting only messages that searched).
+- **OpenViking**: Connected, Degraded or Starting, with the version, and the reason when degraded. While OpenViking is unreachable, requests still reach the model without memory. The card's **Saving conversations** part counts conversations that are retrying or have paused saving.
+- **Degraded requests**: how often each issue occurred, with an explanation; see [Issues on degraded requests](#issues-on-degraded-requests).
- **Recent requests**, with a link to the Requests tab.
-The **Requests** tab lists the latest 1,000 records, newest first, and refreshes its first page every 30 seconds while you view it. Filter by **All**, **New messages**, **Tool steps** or **Issues**, by **Request type**, or search by model, conversation or key. Columns show the type, model (the name the client sent), the provider's HTTP status, tokens (input, cached share, output), **Memory** (`+3`: entries this request's search added, with the search time; `↺ 4`: memory added to 4 earlier messages, sent again unchanged), **Saving** status and **Issue**. Expand a row for the conversation ID, upstream, key, duration, the token breakdown, the memory search result, the context window (how full it was, and any compaction or new window), saving status with the next retry time, OpenViking tool details and, for an issue, what it means and what to do.
+The **Requests** tab lists the latest 1,000 records, newest first, and refreshes every 30 seconds while you are on the first page. Filter by **All**, **New messages**, **Tool steps** or **Issues**, or by **Request type**, or search by model, conversation or key.
+
+The columns are type, model (the name the client sent), the provider's HTTP status, tokens (input, cached share, output), **Memory**, **Saving** status and **Issue**. In the **Memory** column, `+3` means this request's search added 3 entries, shown with the search time, and `↺ 4` means memory added to 4 earlier messages was replayed unchanged. Expand a row for the conversation ID, upstream, key, duration, token breakdown, memory search result, context window use (and whether it was compacted or the model started a new window), saving status with the next retry time, and OpenViking tool details. For a request with an issue, the row also explains what happened and what to do.
-Only requests that reached a model provider are logged. Requests the gateway rejects first, such as an invalid key, a model the key does not allow, no matching upstream or a body over the size limit, are not; the client receives the error instead.
+Only requests that reached a model provider are logged. Requests the gateway rejects first are not, such as an invalid key, a model the key does not allow, no matching upstream or a body over the size limit; the client receives the error directly.
-| Type | What it is | Memory |
+| Type | Meaning | Memory |
| --- | --- | --- |
| New message | A request whose last message is a new user message | Searched once, earlier memory replayed; the turn is saved |
-| Tool step | The same turn continues, for example with tool results | Earlier memory replayed; saved with its turn |
+| Tool step | The same turn continuing, for example with tool results | Earlier memory replayed; saved with its turn |
| Housekeeping | Title, summary, compaction, suggestion and permission-check requests | Earlier memory replayed; never saved |
| Sub-agent | Requests from a client's sub-agents | Earlier memory replayed; never saved |
-| Token count | Token counting requests (`/v1/messages/count_tokens`) | Earlier memory replayed, so counts match what is sent |
+| Token count | Token-counting requests (`/gateway/v1/messages/count_tokens`) | Earlier memory replayed, so the count matches what is actually sent |
| Forwarded | Requests passed through unchanged, without memory: other endpoints, Responses requests that rely on provider-side state, compressed or unreadable bodies | None |
-| Memory sync | Background saving events; not model requests | — |
+| Memory sync | Background saving events, not model requests | — |
-The **Saving** column shows where each conversation stands:
+The **Saving** column shows each conversation's saving status:
- **On**: saving works normally.
-- **Off**: the conversation's profile does not save.
+- **Off**: the conversation's context profile does not save.
- **Retrying**: OpenViking rejected a save or could not be reached. The gateway retries after 10, 20, 40 and 80 seconds.
-- **Paused**: five attempts failed. The gateway keeps retrying every 5 minutes until it succeeds. Unsaved turns are kept until they are saved or the conversation expires.
+- **Paused**: five attempts in a row failed. The gateway then retries every 5 minutes until it succeeds. Unsaved turns are kept until they are saved or the conversation expires.
+- **Paused** with the reason `gateway_key_revoked`: the conversation's gateway key was revoked or deleted, and the gateway stops retrying. Saving resumes when the user next sends a request in this conversation with a valid key.
-The expanded row shows the reason, for example that OpenViking rejected the key (`openviking_http_401`: the user's OpenViking key is no longer valid) or that OpenViking is unreachable (`openviking_unavailable`). A note that the conversation history changed (`history_changed`) is normal: the client edited, regenerated or compacted the conversation, and the gateway continues saving in a new OpenViking session with the current history.
+The expanded row shows the reason, for example that OpenViking rejected the key (`openviking_http_401`, meaning the user's OpenViking key is no longer valid) or that OpenViking is unreachable (`openviking_unavailable`). A history change (`history_changed`) is normal: the client edited, regenerated or compacted the conversation, and the gateway continues saving the current history in a new OpenViking session.
-**Resync conversation…** in an expanded row starts a fresh OpenViking session for that conversation. The next time the user sends a message, the gateway writes the conversation's full history to it. What was already saved stays in the old session, so OpenViking may extract some memories twice. Use it when a conversation stays paused after you fixed the cause, or when you want a clean copy of a conversation. Nothing happens until the next message. Resync needs the key shown on the record; if that key has been revoked, use a newer record of the same conversation.
+**Resync conversation…** in an expanded row starts a new OpenViking session for the conversation. The next time the user sends a message, the gateway writes the full history to it. What was already saved stays in the old session, so some memories may be extracted twice. Use it when a conversation stays paused after you fixed the cause, or when you want a clean copy of a conversation. Nothing happens until the next message arrives. Resync needs the key shown on the record; if that key has been revoked, pick a newer record of the same conversation.
## OpenViking tools
-With OpenViking tools on, the model can use the tools available on your OpenViking server while answering, within the user's access permissions. The gateway runs the tools, and the client continues receiving the answer until the reply ends. Reported token usage includes all model calls made during that reply. For what this means for different clients, which tools the model can use and what users see in the reply, see [Agentic memory for any client](15-gateway.md#agentic-memory-for-any-client) in the OpenViking Gateway guide; this section covers client requirements, settings and limits.
+With OpenViking tools on, the model can use the tools your OpenViking service provides while it answers, within the user's own OpenViking permissions. The gateway runs the calls, the client keeps receiving the answer until the reply ends, and the token usage it sees includes every model call made along the way. For what this means for each kind of client and what users see in the reply, see [Agentic memory for any client](15-gateway.md#agentic-memory-for-any-client). This section covers client requirements, settings and limits.
-Tools support streaming and nonstreaming requests in all three protocols:
+The feature is meant for chat apps and API apps that cannot connect to the OpenViking MCP server. Clients that support MCP or have a plugin, such as Claude Code and Codex, are better served by those, because they show each tool call and its result and ask for approval first.
-| Protocol | Client requirements |
+### Client requirements
+
+All three protocols support streaming and non-streaming requests:
+
+| Protocol | What the client must do |
| --- | --- |
| Chat Completions | Send the full `messages` history. |
-| Responses | Use `store: false` and full `input` history; pass the entire returned `output` array back on the next request, including reasoning and client tool calls. Requests with `previous_response_id`, `conversation` or `background` continue to pass through without gateway tools. `item_reference` cannot reconstruct full history. |
-| Anthropic Messages | Send the full `messages` history and keep thinking/signature blocks intact. Token-count requests get the same tool definitions but do not execute tools. |
+| Responses | Use `store: false` and the full `input` history, and on the next turn send back the whole returned `output`, including reasoning and client tool calls. Requests with `previous_response_id`, `conversation` or `background` are forwarded as usual but get no gateway tools; `item_reference` cannot rebuild the full history. |
+| Anthropic Messages | Send the full `messages` history with thinking and signature blocks intact. Token-count requests carry the same tool definitions but run no tools. |
+
+When the model calls OpenViking tools and client tools in the same reply, the gateway handles the OpenViking calls, and the client runs its own tools and returns their results as usual. Responses supports client function and custom tools; Anthropic Messages supports client tool_use calls.
-If a reply calls both OpenViking and client tools, the gateway handles the OpenViking calls. The client runs its own tools and returns their results as usual. Responses supports client function and custom tools; Anthropic Messages supports client tool_use calls.
+### Choose tools
-This is meant for chat apps and API apps that cannot connect to OpenViking's MCP server. Clients that support MCP or have a plugin, such as Claude Code and Codex, are better served by those, where the client shows each tool call with its result and asks for permission first.
+New context profiles have **OpenViking tools** on, including those made with **Create with recommended settings**. The **Tools** list comes from your OpenViking service, and only read-only tools are selected by default:
-New context profiles have **OpenViking tools** on, including those made with **Create with recommended settings**. The **Tools** list comes from your OpenViking server, and only the read-only tools are selected by default: `find`, `search`, `grep`, `glob`, `list`, `tree`, `read`, `list_watches`, `get_acl`, `list_users`, `list_groups` and `health`. The tools that change data are left unchecked: `remember`, `write`, `edit`, `add_resource`, `add_skill`, `forget`, `set_acl` and `cancel_watch`. For example, check `remember` to let the model save memories, or `add_resource` to let it import web pages and attachments. Existing profiles keep their settings. Issue a gateway key first if the list is empty. New tools added to OpenViking are available automatically unless you uncheck them; ongoing conversations keep the tool list they started with.
+- **Selected by default**: `find`, `search`, `grep`, `glob`, `list`, `tree`, `read`, `list_watches`, `get_acl`, `list_users`, `list_groups` and `health`.
+- **Not selected by default** (they change data): `remember`, `write`, `edit`, `add_resource`, `add_skill`, `forget`, `set_acl` and `cancel_watch`. Check `remember` to let the model save memories, and `add_resource` to let it import web pages or attachments.
-**Allow OpenViking tools** is on by default for each upstream. With both switches on, new conversations get the selected tools with an `openviking_` prefix: for example `openviking_find`, `openviking_read`, `openviking_grep` and `openviking_glob`. The descriptions in Studio explain what each available tool does. Read-only labels appear only when OpenViking supplies that information. The definitions of the offered tools go with every request in the conversation; OpenViking's full set adds about 3,500 input tokens, so unchecking tools nobody needs also saves tokens.
+Tools that OpenViking adds later are available by default; ongoing conversations keep the tool list they started with. Existing context profiles keep their selection.
-> **Note**: All selected tools run without the client's permission prompts, including tools that write or delete data. Before you check a tool that changes data, make sure that is acceptable; for profiles used by chat apps, we recommend leaving `forget` and `set_acl` unchecked. A tool-call notice shows what happened; it is not a request for approval.
+**Allow OpenViking tools** is on by default for every upstream. With both switches on, new conversations get the selected tools with an `openviking_` prefix, such as `openviking_find` and `openviking_read`. Studio describes what each tool does, and shows a read-only label only when OpenViking provides that information. Tool definitions go with every request in the conversation, and the full set adds about 3,500 input tokens, so unchecking tools nobody needs also saves tokens.
-**Tool call notices.** With **Show tool calls** on (the default), the reply gets a one-line notice for each OpenViking tool call the gateway runs, at the point in the answer where the call happened:
+> **Note**: Selected tools run without the client's permission prompts, including tools that write or delete data. Before you check a tool that changes data, make sure that is acceptable. For profiles used by chat apps, leave `forget` and `set_acl` unchecked. A tool-call notice only reports what already happened; it is not an approval step.
+
+### Tool call notices
+
+With **Show tool calls** on (the default), each OpenViking tool call the gateway runs adds a one-line notice to the reply, at the point where the call happened:
```text
> OpenViking find: "release date" — done
```
-The notice names the tool and, where available, what it works on: the search query, the URI read, listed or written, or the file or skill being imported. In a streaming reply it appears as soon as the call starts, so users can see that something is happening during a slow import; a nonstreaming reply gets the same lines in the final message. The outcome is added when the call ends: `done`; `failed` when the call returned an error; `skipped` when the gateway refused the call and did not run it, for example because the round limit or the token budget was reached. Each notice is a paragraph of its own. In Chat Completions the notices are part of the reply text. In Anthropic Messages the notices for one round of calls share one text block, and in Responses they share one assistant message. The model never sees these lines; it gets the actual calls and results. The gateway does not save the notices to OpenViking either. To hide them, turn off **Show tool calls** in the profile's **OpenViking tools** section, and the reply contains only the model's own output. Like the other tool settings, the change applies to new conversations.
+- The notice names the tool and, when it can tell, what the call works on: the search query, the URI read, listed or written, or the file or skill being imported.
+- In a streaming reply, the notice appears as soon as the call starts, so users can see the gateway working during slow calls such as imports. A non-streaming reply carries the same notices in the final message.
+- When the call ends, the outcome is added: `done` when it finished, `failed` when it returned an error, and `skipped` when the gateway refused the call without running it, for example because the round limit or token budget was used up.
+- Each notice is its own paragraph. In Chat Completions the notices are part of the reply text; in Anthropic Messages the notices for one round of calls share a text block; in Responses they share an assistant message.
+- The model never sees the notices; it gets the real calls and results. The gateway does not save notices to OpenViking.
+
+To hide the notices, turn off **Show tool calls** in the profile's **OpenViking tools** section. Like the other tool settings, the change applies to new conversations.
-Whether a conversation gets tools is decided at its first request that could use them, not at a helper request such as title generation, and kept, so profile changes reach new conversations only. The one exception turns tools off: when the client shows OpenViking tools of its own before the model has called a gateway tool, for example because an MCP server connected after the first turn. When a request runs without tools, its detail on the Requests tab says why:
+### When tools are not offered
-| Reason | Cause |
+Whether a conversation gets tools is decided at its first request that could use them (housekeeping requests such as title generation do not count) and then stays fixed, so profile changes only reach new conversations. The one exception switches tools off: the client turns out to have OpenViking tools of its own before the model has called a gateway tool, for example because an MCP server connected after the first turn.
+
+Housekeeping requests, sub-agent requests and conversations where an OpenViking plugin was detected never get OpenViking tools. If such a request sends back history in which the model used these tools, the gateway still attaches the tool definitions so the history stays valid, but refuses new OpenViking calls. The client's own tools stay available in every request.
+
+When a request goes without tools, its detail in the request log gives the reason:
+
+| Reason | Meaning |
| --- | --- |
-| `tools_require_full_history` | Responses tools need full input history with `store: false`, without `item_reference`. |
+| `tools_require_full_history` | A Responses request needs `store: false` and the full input history, without `item_reference`. |
| `upstream_tools_disabled` | The upstream has **Allow OpenViking tools** off. |
-| `tools_multiple_choices` | The request asks for several choices (`n` greater than 1). |
+| `tools_multiple_choices` | The request asks for several choices (`n` above 1). |
| `tools_structured_output` | The request asks for structured output (`response_format`, `text.format` or `output_config.format`). |
-| `tools_non_function` | The Chat Completions client sent a tool of a type other than function. |
+| `tools_non_function` | A Chat Completions client sent a tool that is not a function. |
| `tools_forced_choice` | `tool_choice` is `required` or names a specific tool. |
-| `deepseek_reasoning_history_required` | The upstream's provider is DeepSeek, the request does not turn thinking off (`"thinking": {"type": "disabled"}`), and earlier replies would reach it without their reasoning: **Restore reasoning the client drops** is off, or this request cannot restore it because the conversation moved upstream, lost its memory record or has thinking resent as text. Standard Responses requests have no `thinking` field, so they count as thinking on. |
-| `tool_name_collision` | The client already has OpenViking tools, so the gateway leaves its own out for the rest of the conversation, except on a branch where the model already called them. A misdetection also lasts for the conversation; start a new one. This means: an MCP server name (`server_label`, `mcp_server_name`, `mcp_servers[].name`) contains the word `openviking`; a tool named after an OpenViking tool has that word too, such as `mcp__claude_ai_OpenViking__search` (a connector's `authenticate` tool does not count), including deferred tools listed by name on their own line; or a prefixed tool named after an OpenViking tool, such as `mcp__ov__read`, mentions `viking://`. On any request, a client tool with the same name as a gateway tool also counts, since upstreams reject duplicate names. |
-| `tools_unavailable` | OpenViking could not provide its tool list and no previously loaded list was available. Start a new conversation after connectivity recovers. |
-| `tools_not_selected_at_session_start` | The profile has tools on, but the conversation's tool list is empty: the profile selects no OpenViking tools, or the conversation started before an upgrade that left it without tools. Start a new conversation. |
+| `deepseek_reasoning_history_required` | The upstream is DeepSeek, the request does not turn thinking off (`"thinking": {"type": "disabled"}`), and earlier replies would reach the upstream without their reasoning: either **Restore reasoning the client drops** is off, or this request cannot restore it (the conversation changed upstream, lost its memory record, or had thinking sent back as text). Standard Responses requests have no `thinking` field and count as thinking on. |
+| `tool_name_collision` | The client already has OpenViking tools, so the gateway stops offering its own for the rest of the conversation (except on a branch where the model already called them). The conditions are listed below. |
+| `tools_unavailable` | The tool list could not be loaded from OpenViking, and no earlier list was available. Start a new conversation once the connection is back. |
+| `tools_not_selected_at_session_start` | The profile has tools on, but this conversation's tool list is empty: either the profile selects no tools, or the conversation started before a gateway upgrade. Start a new conversation. |
+
+The gateway decides that the client already has OpenViking tools (`tool_name_collision`) when any of these holds:
+
+- An MCP server name (`server_label`, `mcp_server_name`, `mcp_servers[].name`) contains the word `openviking`.
+- A tool whose name ends in an OpenViking tool name also contains that word, such as `mcp__claude_ai_OpenViking__search`. A connector's `authenticate` tool does not count. Deferred tools listed by name on a line of their own count too.
+- A prefixed tool whose name ends in an OpenViking tool name, such as `mcp__ov__read`, mentions `viking://` in its definition.
+- In any request, a client tool has the same name as a gateway tool, because upstreams reject duplicate tool names.
+
+A false match also lasts for the whole conversation; start a new one.
-Housekeeping and sub-agent requests, and conversations where an OpenViking plugin was detected, do not get OpenViking tools. When such a request resends history in which the model used them, the gateway still sends the tool definitions so that the history stays valid, but refuses new OpenViking calls. The client's own tools stay available in every request.
+### Import files and skills
-**Importing files and skills.** The import tools are available when your OpenViking server provides them and they are selected in the profile. URL imports do not need a shell tool. Local files need one of these upload paths:
+The model can import material when your OpenViking service provides the import tools and the profile has them checked. Importing by URL needs nothing more. Importing a local file needs one of these:
-- **A shell tool** (a client tool named like bash, shell, exec_command, terminal or run_command): the import tool returns a one-time upload link, and the model uploads the file with the client's own shell tool, which does go through the client's permission prompt. Skill directories are zipped first. The link points to `public_url` plus `/gateway/uploads`, so `public_url` must be an address the client can reach and your proxy must route that path to the gateway. Without `public_url`, imports fail with "Set gateway.public_url for client uploads".
-- **An attached file**: without a shell tool, the model can import a file attached to a user message, sent either as base64 file data or as attachment text. This includes Responses `input_file` and Anthropic `document.source` with embedded `base64` or `text` data. Open WebUI usually sends only the extracted text, which is imported as a text file. Attachment URLs and provider file IDs are not fetched; use the import tool's URL parameter for a supported remote resource.
+- **A client shell tool** (named like bash, shell, exec_command, terminal or run_command): the import tool returns a one-time upload link, and the model uploads the file with the client's shell tool, which goes through the client's permission prompt. Skill directories are zipped first. The link points to `public_url` plus `/gateway/uploads`, so `public_url` must be an address the client can reach, and any proxy in front must forward that path like the others. Without `public_url`, imports fail with "Set gateway.public_url for client uploads".
+- **An attachment on the user message**: without a shell tool, the model can import a file attached to a user message, sent either as base64 data or as attachment text. This covers embedded `base64` and `text` data in Responses `input_file` and Anthropic `document.source`. Open WebUI usually sends only the extracted text, which is imported as a text file. Attachment URLs and provider file IDs are not fetched; to import a remote resource, use the import tool's URL parameter.
-Uploads are limited to `max_body_bytes` (32 MiB by default).
+Uploads are limited by `max_body_bytes` (32 MiB by default).
-The limits sit under **Advanced settings** in the profile's **OpenViking tools** section:
+### Limits
+
+These limits are under **Advanced settings** in the profile's **OpenViking tools** section:
| Setting | API name | Default | Range | At the limit |
| --- | --- | --- | --- | --- |
| Rounds per request | `tool_max_rounds` | No limit | 1 or more | Further OpenViking calls are refused; the model continues with the results it has and the client's own tools. |
-| Time limit per call | `tool_timeout_seconds` | 30 s | up to 120 s | The call returns an error to the model. |
+| Time limit per call | `tool_timeout_seconds` | 30 s | Up to 120 s | The call returns an error to the model. |
| Result size | `tool_result_bytes` | 65,536 bytes | 1,024–1,048,576 | The result is truncated. |
-| Total time | `tool_total_seconds` | No limit | more than 0 s | The request fails with 504 "Hidden tool request timed out". |
-| Token budget | `tool_total_tokens` | No limit | 1,024 or more | Further OpenViking calls are refused; the model continues with the results it has and the client's own tools. This is not a billing cap; the final answer can exceed it. |
+| Total time | `tool_total_seconds` | No limit | More than 0 s | The request fails with 504 "Hidden tool request timed out". |
+| Token budget | `tool_total_tokens` | No limit | 1,024 or more | Further OpenViking calls are refused; the model continues with the results it has and the client's own tools. This is not a billing cap; the final answer can go past it. |
-Rounds, total time and the token budget are unlimited by default, as in an agent's own tool loop: the model keeps using OpenViking tools until it finishes. In a streaming request, the user can stop the reply at any time, and the gateway stops when the client disconnects. A non-streaming request keeps running after the client disconnects, so set **Total time** if your clients send non-streaming requests. Leave a field empty for no limit. Profiles saved before this default changed keep their earlier values (5 rounds, 120 s, 100,000 tokens); clear the fields to remove the limits.
+Rounds, total time and the token budget are unlimited by default. As in an agent's own tool loop, the model keeps using OpenViking tools until it is done. In a streaming request, the user can stop the reply at any time, and the gateway stops when the client disconnects. **A non-streaming request keeps running after the client disconnects, so set Total time if your clients send non-streaming requests.** An empty field means no limit. Profiles saved before these defaults became "no limit" keep their old values (5 rounds, 120 seconds, 100,000 tokens); clear the fields to remove the limits.
-The token budget covers the extra calls, results and subsequent model output from using OpenViking tools. Existing conversation history, tool definitions and images do not count. The gateway preserves the client's answer-length limit (`max_tokens`, `max_completion_tokens` or `max_output_tokens`). Once the budget is spent, the gateway refuses further OpenViking calls, and the model continues with the results already available and the client's own tools.
+The token budget counts only what using OpenViking tools adds: the extra calls, their results and the model output that follows. The client's existing conversation, tool definitions and images do not count. The gateway keeps the client's limit on answer length (`max_tokens`, `max_completion_tokens` or `max_output_tokens`).
-When an individual tool call fails, the model receives an error result and can continue answering. If the reply itself fails, for example because the provider rejects a follow-up model request or the model keeps calling OpenViking tools after they were refused, the client receives an error and the request log shows **OpenViking tools failed** (`hidden_tool_loop_failed`). Streaming Responses requests end with `response.failed`; Chat Completions and Anthropic Messages report `gateway_tool_error`.
+### Failure handling
-If an upstream keeps failing, turn off its **Allow OpenViking tools** setting. Claude conversations that have already used these tools may also show **Tool history unavailable** (`hidden_tool_history_unavailable`): earlier thinking can no longer be used and has been removed. Check the tool skip reason in the request detail, then restore the original settings or start a new conversation. A retried tool call reuses the first call's result, and an interrupted write is never repeated automatically.
+- **A single call fails**: the model receives an error result and can carry on with its answer.
+- **The whole answer fails**: for example, the provider rejects a follow-up model request, or the model keeps calling OpenViking tools after they were refused. The client receives an error, and the request log shows **OpenViking tools failed** (`hidden_tool_loop_failed`). Streaming Responses requests end with a `response.failed` event; Chat Completions and Anthropic Messages return a `gateway_tool_error` error.
+- **One upstream keeps failing**: turn off its **Allow OpenViking tools**. Claude conversations that already used the tools may then show **Tool history unavailable** (`hidden_tool_history_unavailable`): the earlier thinking can no longer be used, and the gateway removed it. Restore the setting named in the request detail's skip reason, or start a new conversation.
+- **Retries**: a retried tool call reuses the first call's result, and an interrupted write is never repeated automatically.
## Long conversations
-A model's context window limits how long a conversation can get. With **Compaction** on (the default), the gateway replaces the earlier part of a conversation with a summary before the conversation fills the window.
+A model's context window limits how long a conversation can get. With **Compaction** on (the default), the gateway replaces the earlier part of a conversation with a summary before the window fills up.
+
+**When it compacts.** On every new user message and every tool step, the gateway estimates how full the window is: the token usage the provider reported for this conversation's previous reply, plus an estimate for the messages added since. Without that usage (for example, streamed Chat Completions without `stream_options.include_usage`), it estimates the whole request. When the estimate reaches **Compact at** (0.9 of the window), the gateway compacts. Housekeeping, sub-agent and token-count requests never trigger compaction.
+
+**Where the window size comes from.** The gateway first looks for the model in the upstream's **Context windows** (by the model name sent to the upstream), then uses the profile's **Default context window**, and without either assumes 1,000,000 tokens. For a model with a smaller window, set one of the two; otherwise the provider rejects the conversation as too long before compaction ever starts.
-**When it compacts.** On each new user message and each tool step, the gateway estimates how full the context window is: the token usage the provider reported for the previous reply in this conversation, plus an estimate for the messages added since. Without that usage, for example for streamed Chat Completions without `stream_options.include_usage`, it estimates the whole request. When the estimate reaches **Compact at** (0.9 of the window), the gateway compacts. Housekeeping, sub-agent and token-count requests never trigger compaction.
+**How the summary is written.** The gateway sends one extra, non-streaming request to the same upstream and model. The client's system prompt, tools and thinking settings stay the same, so most of the request hits the provider's prompt cache. Settings that a plain-text summary cannot follow are removed: a forced tool choice becomes "no tool call", and structured output formats and stop sequences are dropped. The request contains the conversation up to the cut, plus an instruction for the model to summarize it for itself. The summary covers:
-The window comes from the upstream's **Context windows** entry for the model (the name sent to the upstream), else from the profile's **Default context window**. Without either, the gateway assumes 1,000,000 tokens. For a model with a smaller window, set one of the two; otherwise the provider rejects the conversation as too long before compaction ever starts.
+- the user's goals and the latest request, word for word;
+- key decisions and current progress;
+- files, paths and identifiers;
+- errors and how they were fixed;
+- open items;
+- key facts from the latest tool results.
-**How the summary is written.** The gateway sends one extra, nonstreaming request to the same upstream and model, with the client's system prompt, tools and thinking settings unchanged, so most of it is served from the provider's prompt cache. Settings a plain-text summary cannot follow are left out: a forced tool choice is turned off, and structured output formats and stop sequences are dropped. The request holds the conversation up to the cut and an instruction to summarize it for the model itself: the user's goals and latest request word for word, decisions and progress, files, paths and identifiers, errors and their fixes, open items, and key facts from recent tool results. An earlier summary is folded into the new one. The summary is plain text of at most **Summary length** tokens (8,000). Thinking counts against the output cap, and some models (DeepSeek V4.1, for example) think by default even when the request carries no thinking settings, so the gateway always allows 16,000 tokens of output beyond Summary length; when the client sets a manual thinking budget, it adds that budget instead. The provider bills the request like any other.
+An earlier summary is folded into the new one. The summary is plain text of at most **Summary length** (8,000) tokens. Thinking counts against the output cap, and some models (such as DeepSeek V4.1) think by default even when the request has no thinking settings, so the gateway always allows 16,000 tokens of output on top of the summary length; when the client sets an explicit thinking budget, it adds that budget instead. The provider bills this request like any other.
**What the model receives afterwards.** Where the cut falls depends on the request:
- On a new user message, the cut falls right before that message. The model receives the system and developer messages, the summary as one user message, and the new message.
-- During a tool step, the cut falls after the latest tool result, and the model continues the task from the summary.
+- On a tool step, the cut falls after the latest tool result, and the model continues the task from the summary.
-The summary message starts with a note that the gateway replaced the earlier part of the conversation and that the user did not write it, and ends with the conversation's opening note and profile, so these survive compaction. Every later request that resends this history, including housekeeping and token-count requests, gets the same replacement; sub-agents usually send their own, separate history, which stays untouched. A compaction costs one provider cache miss at the cut; after that, the cache works as before.
+The summary message starts by saying that the gateway replaced the earlier part of the conversation and that the user did not write it. It ends with the conversation's opening gateway note and user profile, so these survive compaction. Every later request that resends this history, including housekeeping and token-count requests, gets the same replacement; sub-agents usually send their own separate history and are not affected. Each compaction costs one provider cache miss at the cut, and caching works normally after that.
-**Nothing before the cut is kept word for word**, not even the latest turns. The model's earlier messages and their thinking depend on the history being replaced, and keeping some of them would break Claude's thinking signatures. Everything generated after the cut is sent as usual, thinking included.
+**Nothing before the cut is kept word for word**, not even the latest turns. The model's earlier replies and their thinking depend on the history being replaced, and keeping only part of it would break Claude's thinking signatures. Everything generated after the cut is sent as usual, thinking included.
-**Searching what was cut.** The conversation itself is still saved in OpenViking. When **Save conversations** is on and the conversation offers the `openviking_grep` and `openviking_read` tools, the summary is followed by directions: the conversation's OpenViking sessions (`viking://user/<user_id>/sessions/<session_id>/`), where their messages are stored, and how to search them: grep a session with a specific pattern to get line numbers, then read the lines around a match. When a cut falls in the middle of a turn, the part before it is saved to OpenViking right away, so the model can search it while the turn continues.
+**Finding what was cut.** The conversation itself is still saved in OpenViking. When **Save conversations** is on and the conversation has the `openviking_grep` and `openviking_read` tools, the summary ends with directions: the conversation's OpenViking session (`viking://user/<user_id>/sessions/<session_id>/`), where its messages are stored, and how to search them (grep the session for a specific pattern to get line numbers, then read the lines around a match). When a cut falls in the middle of a turn, the part before it is saved to OpenViking right away, so the model can search it within the same turn.
-**When compaction fails.** If the summary request fails, or the reply calls a tool, is empty or is cut off at the length limit, the gateway sends the full history instead and does not try again in that conversation for 60 seconds. The request's detail on the Requests tab shows **Compaction failed** with the reason. If the context is still at or above **Compact at** after a summary, for example because the system prompt and tools alone fill most of the window, the gateway keeps the summary but also waits 60 seconds before compacting again, with the reason `still_over_threshold`.
+**When compaction fails.** If the summary request fails, or the reply calls a tool, is empty or is cut off at the length limit, the gateway sends the full history instead and does not try to compact this conversation again for 60 seconds. The request detail shows **Compaction failed** with the reason. If usage is still at or above **Compact at** after the summary (for example because the system prompt and tools alone fill most of the window), the gateway keeps the summary and also waits 60 seconds before trying again, with the reason `still_over_threshold`.
-**Working Memory is not used.** The summary comes from the conversation's own model, not from OpenViking's session summaries. New OpenViking sessions the gateway creates have Working Memory turned off: commits still archive the messages and OpenViking still extracts memories, but it writes no session summary.
+**No Working Memory summaries.** The summary comes from the conversation's own model, not from OpenViking's session summaries. New OpenViking sessions that the gateway creates have Working Memory turned off: commits still archive messages and extract memories, but no session summary is written.
-**Memory budget.** **Budget per context window** starts over after each compaction, so an entry added before the cut can be added again.
+**The memory budget starts over.** **Budget per context window** resets after each compaction, so memory added before the cut may be added again.
-**Clients' own compaction.** After the gateway compacts, the client still resends its full history, and the gateway replaces the part before the cut on every request. The usage the client sees is small, so clients that compact by token usage seldom compact on their own, and a very long session can eventually exceed `max_body_bytes`. When a client compacts or edits its history, the gateway saves the new history to a new OpenViking session; when the search tools are available, the opening note of the new history points the model to the earlier sessions.
+**The client still sends the full history.** After the gateway compacts, the client keeps sending its full history, and the gateway replaces the part before the cut on every request. The client sees small usage numbers, so clients that compact by usage rarely compact on their own, and a very long session can eventually exceed `max_body_bytes`. When the client compacts or edits its history, the gateway saves the new history to a new OpenViking session; if the search tools are available, the opening gateway note of the new history tells the model where the earlier sessions are.
-Each request's detail on the Requests tab shows how full the context window was, whether earlier history was replaced, and the size and duration of a newly written summary.
+Each request's detail in the request log shows how full the context window was, whether earlier history was replaced, and the size and time of a newly written summary.
### Experimental: agent-managed context windows
-With **Agent-managed context windows** on (off by default), the model decides itself when to start a fresh context window and writes its own hand-off notes, instead of waiting for a summary. The setting takes effect only in conversations that get [OpenViking tools](#openviking-tools); elsewhere it does nothing, and compaction works as described above. Compaction, when on, also remains the fallback for a model that never starts a new window.
+With **Agent-managed context windows** on (off by default), the model decides when to start a fresh context window and writes its own hand-off notes, instead of waiting for the gateway's summary. The setting only works in conversations that get [OpenViking tools](#openviking-tools); other conversations are compacted as usual. When compaction is on, it remains the fallback if the model never starts a new window.
-What the model sees:
+The model sees:
-- Two tools next to the OpenViking tools. They are not part of the profile's **Tools** list; this setting alone controls them.
- - `openviking_new_context(reason, notes, next_steps)` starts a new window; `next_steps` is optional. It must be the only tool call in its round. Called together with other tools, every call in the round returns an error and the window is not reset. It also returns an error when the gateway already replaced the context at the same point in this request, for example by compacting it.
- - `openviking_context_remaining()` reports the window number, the estimated tokens used and left, the user turns in this window, the time since the user's previous message, and a one-line recommendation.
-- A line in the opening note saying that the model manages its own context windows with these tools.
-- A status line after each new user message, at the end of the memory block: `[context-status] window wN · ~X/Y tokens (P%) · T since your previous message`.
-- Reminders when the window reaches **Soft reminder at** (0.7) and **Hard reminder at** (0.85). The soft reminder, sent once per window, asks the model to start a new window once the current step is done, with notes that keep the exact paths, line numbers and values it will need. The hard one asks for a new window now and repeats on every step until the model starts one or compaction takes over. A reminder is attached to the new user message or, during a tool step, to the tool result.
+- **Two extra tools.** They are not in the profile's **Tools** list; only this setting controls them.
+ - `openviking_new_context(reason, notes, next_steps)` starts a new window; `next_steps` is optional. It must be the only tool call in its round. Called together with other tools, every call in the round returns an error and the window is not reset. It also returns an error if the gateway already replaced the context at the same point in this request (for example, it just compacted).
+ - `openviking_context_remaining()` returns the window number, estimated tokens used and left, the user turns in this window, the time since the user's previous message, and a one-line recommendation.
+- **One more line in the opening gateway note**, telling the model that it manages its own context windows with these two tools.
+- **A status line**: after each new user message, the memory block ends with `[context-status] window wN · ~X/Y tokens (P%) · T since your previous message`.
+- **Two reminders**: when the window reaches **Soft reminder at** (0.7), the gateway reminds the model once to start a new window after the current step, with notes that keep the exact paths, line numbers and values it will need. At **Hard reminder at** (0.85), it tells the model to start a new window now, and repeats on every step until the model does or compaction takes over. Reminders are attached to the new user message, or to the tool result during a tool step.
-When the model calls `openviking_new_context`, the gateway replaces the conversation so far with a window header, and the model carries on in the same reply. The header says that the model started window N and that the user did not write it, then gives the reason, the notes and next steps, the user's latest message word for word, directions for searching earlier windows (under the same conditions as for compaction), and the conversation's opening note. Later requests rebuild the same window from the client's history. The part before the reset is saved to OpenViking right away and stays searchable. The reason and notes appear only in the header; they are not saved to OpenViking. A reset costs one provider cache miss but no summary request.
+When the model calls `openviking_new_context`, the gateway replaces the conversation so far with a window header, and the model carries on in the same reply. The header contains, in order: that this is window N started by the model and that the user did not write it; the reason, notes and next steps; the user's latest message word for word; how to search earlier windows (under the same conditions as for compaction); and the conversation's opening gateway note. Later requests rebuild the same window from the client's history. The content before the reset is saved to OpenViking right away and stays searchable. The reason and notes appear only in the header and are not saved to OpenViking. Each reset costs one provider cache miss but needs no summary request.
-Each request's detail on the Requests tab shows the window number, whether the model started a new window, and which reminder it got. How well this works depends on the model, and the behavior may change in later releases.
+Each request's detail in the request log shows the window number, whether the model started a new window, and which reminder it received. How well this works depends on the model, and the behavior may change in later releases.
## Security and data
-**Isolation by user.** Each gateway key is bound to one OpenViking user. The gateway searches memory, saves conversations and calls tools with that user's own OpenViking key, so it never has more access than the user does, and each user's conversation state is kept apart. Sessions and memories always live in OpenViking; the gateway stores only the state it needs to keep conversations going.
+**Isolation by user.** Each gateway key is bound to one OpenViking user. The gateway searches memory, saves conversations and calls tools with that user's own OpenViking key, so it can never do more than the user can, and each user's conversation state is kept separate. Sessions and memories always live in OpenViking; the gateway keeps only the state it needs to continue conversations.
-**What the gateway stores.** Under `storage_path`, the gateway keeps two SQLite databases:
+**What the gateway stores.** `storage_path` holds two SQLite databases. Only the system user that runs the gateway can read the files, and with [encryption](#encryption) on, every stored value is encrypted as well:
-- `management.sqlite3`: upstreams, context profiles, gateway keys, request logs and the mapping from Responses IDs to upstreams. Upstream API keys and header values, and the OpenViking keys bound to gateway keys, are encrypted. Gateway keys themselves are stored only as a hash and a short prefix.
-- `kernel.sqlite3`: per-conversation state, including the memory text added to messages (needed for replay), OpenViking tool rounds, summaries and conversation text waiting to be saved.
+- `management.sqlite3`: upstreams, context profiles, gateway keys, request logs, and which upstream created each Responses response. This includes upstream API keys, header values and the OpenViking keys bound to gateway keys, which are in plain text when encryption is off; gateway keys themselves are stored only as a hash and a short prefix.
+- `kernel.sqlite3`: the state of each conversation, including the memory text added to messages (needed for replay), OpenViking tool rounds, summaries and conversation text waiting to be saved.
-Stored values are encrypted with the encryption key. The files are readable only by the user running the gateway.
-
-**What request logs contain.** Metadata only: request type, model, status, upstream, a hash of the conversation ID, token counts, memory counts and timing, saving status and issues. Never message text, recalled memory, tool arguments or results, or any key. The gateway writes no HTTP access log, and its error messages never repeat submitted values.
+**What request logs record.** Metadata only: request type, model, status, upstream, a hash of the conversation ID, token counts, memory counts and timing, saving status and issues. Never message text, recalled memory, tool arguments or results, or any key. The gateway writes no HTTP access log, and its error messages never repeat submitted values.
**What providers see.** Every upstream receives the full model input, including memory the gateway added and OpenViking tool results. Only add providers you trust with that data.
-**Retention.** Cleanup runs every hour:
+**Retention.** A cleanup job runs every hour:
| Data | Kept for | Setting |
| --- | --- | --- |
-| Conversation state | 30 days after its last use | `session_ttl_days` |
+| Conversation state | 30 days after last use | `session_ttl_days` |
| Request logs | 30 days | `log_retention_days` |
-| Responses ID mappings | 30 days | `response_ttl_seconds` |
+| Which upstream created each Responses response | 30 days | `response_ttl_seconds` |
| Sessions and memories in OpenViking | OpenViking's own rules | — |
-**Deleting data.**
+**Deleting data.** Revoking a gateway key, or the bound OpenViking key becoming invalid, does not delete user data. There are three ways to delete it:
+
+- An account admin or root uses **Delete this user's gateway data…** in Studio, or calls `DELETE /gateway/admin/users/{user_id}/data`. This revokes the user's gateway keys and deletes their conversation state and logs, including content not yet saved.
+- Root calls `DELETE /gateway/admin/account/data?account_id=<account>` to delete all gateway data of an account.
+- In an embedded deployment, deleting a user or account in OpenViking also deletes the matching gateway data. A standalone deployment has no such step; its data stays until it is explicitly deleted or expires.
-- Delete one user's gateway data from Studio (a key's **More actions** menu → **Delete this user's gateway data…**) or with `DELETE /api/v1/admin/gateway/users/{user_id}/data` on OpenViking Server, using an account admin key. This revokes the user's gateway keys and deletes their conversation state. Request-log metadata ages out with retention.
-- Removing a user in OpenViking does the same automatically. Removing an account also deletes the account's upstreams, profiles, keys and request logs from the gateway. If the gateway is unreachable at that moment, OpenViking keeps retrying. If you stop using the gateway, set `gateway.enabled` to `false` so deletions no longer wait for it.
-- Sessions and memories in OpenViking are deleted through OpenViking, not the gateway.
-- Deleting a memory in OpenViking does not remove a copy already added to a conversation: to replay it exactly, the gateway keeps the added memory text in the conversation state until the conversation expires. To clear it at once, delete the user's gateway data. That also revokes all of the user's gateway keys, so you have to issue new ones afterwards.
+None of this touches memories and sessions already stored in OpenViking. The reverse also holds: after you delete a memory in OpenViking, the copy the gateway saved for an ongoing conversation is still replayed until that conversation expires. To clear it now, delete the user's gateway data.
-**Access.**
+**Access control.**
-- Clients authenticate with gateway keys, sent as `Authorization: Bearer` or `x-api-key`. Keys can be revoked at any time.
-- The gateway uses each user's own OpenViking key for memory search, saving and tools, so it can do only what that user can do.
-- Only OpenViking Server should hold the admin token, and the gateway's `/admin/*` paths must stay private (see [Routes](#routes)). Studio users are checked by OpenViking Server: account admins and root only, each limited to their own account. The admin token has no such limit: whoever holds it can manage every account, so never expose the gateway port to the internet.
-- Account admins can issue gateway keys for any user in their account (when OpenViking stores only key hashes, the user has to provide their key). A gateway key lets its holder recall memory and call tools as that user, so the right to issue keys amounts to reading the memory of every user in the account. Give it only to admins you trust.
-- `/gateway/uploads` needs no gateway key. A one-time token signed by OpenViking authorizes each upload, and the gateway forwards it only to OpenViking's upload endpoint. Keep its query string out of proxy logs.
+- Clients authenticate with gateway keys, sent in `Authorization: Bearer` or `x-api-key`. Keys can be revoked at any time.
+- The management key only controls changes to upstreams and context profiles. It grants no access to memory or logs and no right to issue keys; see the [access matrix](../api/25-gateway.md#credentials-and-account-scope).
+- Account admins can issue gateway keys for any user in their account (when OpenViking stores only key hashes, the user has to supply their key). A gateway key lets its holder recall memory and call tools as that user, so the right to issue keys amounts to reading the memory of every user in the account. Give it only to admins you trust.
+- `/gateway/uploads` needs no gateway key. Each upload is authorized by a one-time token signed by OpenViking, and the gateway only forwards it to OpenViking's upload endpoint. Keep its query string out of proxy logs.
- `X-OpenViking-*` headers, client credentials and cookies are never forwarded to upstreams.
-**Backups.** Back up `storage_path`, including both databases with their `-wal` and `-shm` files, together with the encryption key. For a consistent copy, stop the gateway or use SQLite's online backup (`sqlite3 kernel.sqlite3 ".backup kernel.backup.sqlite3"`, and the same for `management.sqlite3`). What a loss means:
+**Backups.** Back up `storage_path`, including both databases and their `-wal` and `-shm` files; with encryption on, also keep a backup of OpenViking's root key. For a consistent copy, stop the gateway first, or use SQLite's online backup (`sqlite3 kernel.sqlite3 ".backup kernel.backup.sqlite3"`, and the same for `management.sqlite3`). What losing each file means:
-- **`kernel.sqlite3` lost**: memory added earlier cannot be replayed. Each ongoing conversation pays one provider cache miss, Claude conversations lose earlier thinking once (**Memory record missing**, `missing_injection_record`), and turns not yet saved are lost.
-- **`management.sqlite3` lost**: upstreams, profiles, keys and request logs are gone. Set them up again and issue new keys.
-- **Encryption key lost**: neither database can be read. Start with an empty `storage_path`.
+- **`kernel.sqlite3` lost**: memory added earlier cannot be replayed. Each ongoing conversation takes one provider cache miss, Claude conversations lose their earlier thinking once (**Memory record missing**, `missing_injection_record`), and turns not yet saved are lost.
+- **`management.sqlite3` lost**: upstreams, context profiles, keys and request logs are gone. Set them up again and issue new keys.
+- **Root key lost** (encryption on): the encrypted values in both databases cannot be read. Start again with an empty `storage_path`.
## Day-to-day operations
-The OpenViking Gateway page is open only to account admins and root. Initial setup follows the order upstream → context profile → key → connect a client; after that, day-to-day work comes down to a few things.
-
-- **Watch the first-call cache hit rate.** The **First-call cache hit rate** on the Overview tab reflects prompt caching across turns and should stay close to what the provider reaches without the gateway. The **Within-turn cache hit rate** covers tool steps and is normally high. If the first-call rate drops noticeably, see [The first-call cache hit rate dropped](#the-first-call-cache-hit-rate-dropped).
-- **Use the request log to track down a single request.** Filter by new messages, tool steps or issues, then expand a row to see the recall result, saving status and why OpenViking tools were off; see [Requests and overview](#requests-and-overview).
-- **Set the public address.** Shared deployments must set `public_url`. Without it, Studio's setup instructions show the internal address and the upload links of the OpenViking import tools do not work.
-- **Back up regularly.** Back up the gateway's storage directory and the encryption key; for how, and what a loss means, see **Backups** under [Security and data](#security-and-data).
+- **Watch the first-call cache hit rate.** It reflects prompt caching across turns and should stay close to what the provider reaches without the gateway. The **Within-turn cache hit rate** covers tool steps and is normally high. If the first-call rate drops noticeably, see [The first-call cache hit rate dropped](#the-first-call-cache-hit-rate-dropped).
+- **Use the request log to look into a single request.** Filter by new messages, tool steps or issues, then expand a row to see the recall result, saving status and why OpenViking tools were left out; see [Requests and overview](#requests-and-overview).
+- **Set the public address.** Set `public_url` to the address clients use, without `/gateway`, so client settings and upload links stay correct behind a reverse proxy.
+- **Back up regularly.** Back up the gateway's storage directory and, with encryption on, OpenViking's root key; see **Backups** under [Security and data](#security-and-data).
### Upgrades
-- OpenViking Server must be at least `min_server_version` (0.4.16). With an older server, memory search and saving stop and no keys can be issued. When you upgrade the gateway and OpenViking separately, upgrade OpenViking first, then the gateway.
- Read the release notes before you upgrade. If a new gateway version cannot read the old storage format, it stops at startup with `Unsupported gateway schema`; see [The gateway does not start](#the-gateway-does-not-start).
+- A standalone gateway needs OpenViking Server `min_server_version` (0.4.16) or later. With an older server, memory search and saving stop and no keys can be issued. When you upgrade the two separately, upgrade OpenViking first, then the gateway. An embedded gateway ships with its server and skips this check.
+- To move from the sidecar or an older standalone gateway, see [Migration](#migration).
### Monitoring
-The gateway exports no metrics such as Prometheus and writes no HTTP access log. Check how it is doing on Studio's Overview and Requests tabs, or through the management API on OpenViking Server (`/api/v1/admin/gateway/overview` and `logs`); use the gateway's `/health` to check that the process is alive.
+The gateway exports no metrics such as Prometheus and writes no HTTP access log. Check its state on Studio's Overview and Requests tabs, or through the management API's `/gateway/admin/overview` and `/gateway/admin/logs`. Use `/health` for liveness: the server's health check in an embedded deployment, and the gateway's own in a standalone one.
## Design trade-offs
-The table explains why the gateway's key design choices were made and what they cost, to help you judge whether it fits your setup:
+The table explains why the gateway's main design choices were made and what they cost, so you can judge whether it fits your setup:
| Design | Choice and reason | Cost |
| --- | --- | --- |
-| Where it plugs in | On the model call path instead of a plugin in every agent: clients that cannot install plugins can use it, and provider keys are managed in one place. | It cannot see the working directory; keeping projects' memory apart means using a different OpenViking user per project. |
-| Who runs the tools | The gateway runs OpenViking tools during the reply, stores the tool rounds and replays them unchanged on the next turn: even clients with no tools and no MCP support get a model that uses memory itself. | No per-call approval; clients must send the full history every turn; admins need to narrow the tool list and limits. |
-| Where memory goes | At the end of the newest user message, not in the system prompt: changing one character of the system prompt invalidates the whole cache, while appending at the end and replaying it unchanged keeps the prefix stable. | The gateway must reliably record the exact text of every addition; if a record is lost, the cache misses once. |
-| When turns are saved | One turn behind: only when the next message brings the previous turn back is it clear that the user kept it. | The last turn is saved only after **Save the latest reply after** (10 minutes by default). |
+| Where it plugs in | On the model call path instead of a plugin in every agent: clients that cannot install plugins can use it, and provider keys are managed in one place. | It cannot see the working directory; keeping projects' memory apart means a different OpenViking user per project. |
+| Who runs the tools | The gateway runs OpenViking tools during the reply, stores the rounds and replays them unchanged on the next turn: even clients with no tools and no MCP support get a model that uses memory on its own. | No per-call approval; clients must send the full history every turn; admins need to narrow the tool list and limits. |
+| Where memory goes | At the end of the newest user message, not in the system prompt: one changed character in the system prompt invalidates the whole cache, while appending at the end and replaying unchanged keeps the prefix stable. | The gateway must reliably record the exact text of every addition; a lost record costs one cache miss. |
+| When turns are saved | One turn behind: only when the next message brings the previous turn back is it clear the user kept it. | The last turn is saved only after **Save the latest reply after** (10 minutes by default). |
| Long conversations | The gateway has the same model write the summary: only the gateway knows what the model actually received, and the summary request mostly hits the cache. | The turn that triggers compaction costs one extra, billed model call; text before the cut is no longer sent to the model. |
-| Local state | SQLite on a single host, with no Postgres or Redis dependency, suited to self-hosting on one machine. | The gateway cannot fail over between machines and is a single point on the model call path. |
-| Client identity | The gateway issues its own keys instead of using OpenViking keys directly: they can be revoked on their own, and one person's clients can be bound to different context profiles. | The gateway has to keep users' OpenViking keys encrypted; a leaked gateway key exposes that user's memory. |
+| Local state | SQLite on one host, with no Postgres or Redis dependency, which suits self-hosting. | The gateway cannot fail over between machines and is a single point on the model call path. |
+| Client identity | The gateway issues its own keys instead of using OpenViking keys directly: they can be revoked on their own, and one person's clients can use different context profiles. | The gateway has to store users' OpenViking keys, so turn on encryption; a leaked gateway key exposes that user's memory. |
## Configuration reference
-The `gateway` section of `ov.conf`, with every key at its default:
+Both forms use the same fields; they differ only in where the file lives and how you create it:
-```jsonc
-{
- "gateway": {
- "enabled": false, // the gateway refuses to start until true
- "host": "127.0.0.1", // bind address
- "port": 1935,
- "workers": 1, // 1–64 processes on this host
- "url": "http://127.0.0.1:1935", // how OpenViking Server reaches the gateway
- "openviking_url": "http://127.0.0.1:1933", // how the gateway reaches OpenViking Server
- "public_url": "", // how clients reach the gateway
- "storage_path": "~/.openviking/gateway", // local disk only
- "encryption_key_env": "OPENVIKING_GATEWAY_ENCRYPTION_KEY",
- "admin_token_env": "OPENVIKING_GATEWAY_ADMIN_TOKEN",
- "min_server_version": "0.4.16",
- "session_ttl_days": 30,
- "response_ttl_seconds": 2592000,
- "log_retention_days": 30,
- "max_body_bytes": 33554432,
- "upstream_timeout_seconds": 600,
- "health_interval_seconds": 60
- }
-}
-```
+- **Embedded**: the `gateway` section of `ov.conf`, written by `openviking-server init`. Host, port and workers come from the server.
+- **Standalone**: the root of `gateway.conf`, with no `gateway` wrapper, written by `openviking-gateway init`. When `--config` or `OPENVIKING_GATEWAY_CONFIG_FILE` is set, it must point to an existing file; otherwise the gateway reads the first of `~/.openviking/gateway.conf` and `/etc/openviking/gateway.conf` that exists. `OPENVIKING_CONFIG_FILE` only selects the server's configuration.
-| Key | Default | Description |
-| --- | --- | --- |
-| `enabled` | `false` | Turns the gateway on. When false, the gateway refuses to start and Studio's OpenViking Gateway page shows a setup card. |
-| `host` | `127.0.0.1` | Bind address. Must be a loopback address while OpenViking runs in dev mode. |
-| `port` | `1935` | Gateway port. |
-| `workers` | `1` | Gateway processes on this host, 1–64. |
-| `url` | `http://127.0.0.1:1935` | Address OpenViking Server uses for management and data deletion. Also the address Studio shows when `public_url` is empty. |
-| `openviking_url` | `http://127.0.0.1:1933` | Address the gateway uses to reach OpenViking Server. |
-| `public_url` | empty | Address clients use. Studio shows it in setup instructions; upload links for OpenViking tools use it. Set it in every shared deployment. |
-| `storage_path` | `~/.openviking/gateway` | Directory for the two databases. Must be on a local disk. |
-| `encryption_key_env` | `OPENVIKING_GATEWAY_ENCRYPTION_KEY` | Environment variable holding the encryption key. |
-| `admin_token_env` | `OPENVIKING_GATEWAY_ADMIN_TOKEN` | Environment variable holding the admin token. |
-| `min_server_version` | `0.4.16` | Oldest OpenViking Server version the gateway works with. With an older or unparsable version, memory search and saving stop and no keys can be issued. |
-| `session_ttl_days` | `30` | Days of inactivity after which a conversation's state is removed. |
-| `response_ttl_seconds` | `2592000` | How long Responses IDs stay mapped to their upstream (at least 60). |
-| `log_retention_days` | `30` | Request log retention. |
-| `max_body_bytes` | `33554432` | Largest request body and upload, in bytes (at least 1,024). Larger ones get 413. |
-| `upstream_timeout_seconds` | `600` | Total time limit for one call to a provider. |
-| `health_interval_seconds` | `60` | How often the gateway checks OpenViking (at least 1). |
-
-URL settings must be plain `http` or `https` addresses without credentials, query or fragment; a trailing `/` is removed.
-
-**Environment variables:**
-
-| Variable | Read by | Purpose |
-| --- | --- | --- |
-| `OPENVIKING_GATEWAY_ENCRYPTION_KEY` | Gateway | Encryption key (see [Secrets](#secrets)). |
-| `OPENVIKING_GATEWAY_ADMIN_TOKEN` | Gateway and OpenViking Server | Admin token, at least 32 characters. |
-| `OPENVIKING_CONFIG_FILE` | Gateway and OpenViking Server | Path to `ov.conf` when `--config` is not given. |
-
-**Context profile settings.** Studio label first, then the name used in the management API (where profiles are called `policies`):
-
-| Studio label | API name | Default | Limits | Meaning |
+| Field | Form | Default | Meaning |
+| --- | --- | --- | --- |
+| `enabled` | Embedded | `false` | Turns the gateway on inside the server |
+| `openviking_url` | Standalone | — (required) | Address of the OpenViking Server |
+| `host` | Standalone | `127.0.0.1` | Listen address |
+| `port` | Standalone | `1935` | Listen port |
+| `workers` | Standalone | `1` | Worker processes, 1–64 |
+| `encryption` | Standalone | not set (plain text) | Same fields as the `encryption` section of `ov.conf`; see [Encryption](#encryption). Embedded gateways use the server's section |
+| `public_url` | Both | empty | The external address clients use, without `/gateway` (the gateway appends it); when empty, an embedded gateway uses the server's public address; with neither, setup guides use the request's origin and file uploads do not work |
+| `storage_path` | Both | `~/.openviking/gateway` | Local storage directory |
+| `management_key` | Both | empty | Optional gateway management key, at least 32 characters |
+| `min_server_version` | Both | `0.4.16` | Lowest OpenViking Server version a standalone gateway accepts |
+| `session_ttl_days` | Both | `30` | Days of inactivity before a conversation expires; minimum 1 |
+| `response_ttl_seconds` | Both | `2592000` | Seconds to remember which upstream created a Responses response; minimum 60 |
+| `log_retention_days` | Both | `30` | Days to keep request logs; minimum 1 |
+| `max_body_bytes` | Both | `33554432` | Size limit for requests and uploads; minimum 1,024 bytes |
+| `upstream_timeout_seconds` | Both | `600` | Timeout for provider requests; must be above 0 |
+| `health_interval_seconds` | Both | `60` | Seconds between OpenViking status checks; minimum 1 |
+
+**Environment variables override the file.** The rule is the same in both forms: a non-empty `OPENVIKING_GATEWAY_<FIELD NAME IN UPPER CASE>` variable, such as `OPENVIKING_GATEWAY_PUBLIC_URL` or `OPENVIKING_GATEWAY_MANAGEMENT_KEY`, wins over the value in the file; an empty variable counts as unset. A value in the file can also be a `"$VAR"` reference. The `encryption` block can only be set in the file. Containers usually need no file: set the fields they need as variables.
+
+URLs must be HTTP(S) and contain no credentials, query or fragment. Unknown fields fail validation, except removed ones, which are ignored with a startup warning: `encryption_key_env`, and in `ov.conf` also the v0.5 fields listed in [Migration](#migration).
+
+**Context profile settings.** Studio label first, then the name in the management API (which calls context profiles `policies`):
+
+| Studio label | API name | Default | Range | Meaning |
| --- | --- | --- | --- | --- |
| Name | `name` | `Default` | | Display name. |
| Recall memory | `recall` | `true` | | Search memory for each new user message. |
| User profile at conversation start | `profile` | `true` | | Provide the user profile when a conversation starts, independently of recall. |
-| Opening context budget | `profile_max_tokens` | `4000` | 0–32,000 | Separate budget for the profile and catalogs; 0 omits them. Catalogs require the Read tool. |
-| Show recall summary | `show_recall` | `false` | | Start the reply with a one-line summary of what OpenViking added, or why recall failed. The model never sees it. |
-| Sources | `context_types` | `memory`, `resource`, `skill` | at least one | What to search: memories, resources, skills. |
+| Opening context budget | `profile_max_tokens` | `4000` | 0–32,000 | Separate budget for the profile and catalogs; 0 leaves them out. Catalogs need the `read` tool. |
+| Show recall summary | `show_recall` | `false` | | Start the reply with a summary of what OpenViking added, or why recall failed. The model never sees it. |
+| Sources | `context_types` | `memory`, `resource`, `skill` | At least one | What to search: memories, resources, skills. |
| Budget per message | `max_tokens` | `1600` | 64–32,000 | Most tokens added to one message. |
-| Budget per context window | `session_max_tokens` | `30000` | ≥ 0 | Most tokens added within one context window; starts over after each compaction. 0 turns recall off. |
+| Budget per context window | `session_max_tokens` | `30000` | ≥ 0 | Most tokens added within one context window; resets after each compaction. 0 turns recall off. |
| Relevance threshold | `score_threshold` | `0.35` | 0–1 | Lowest relevance score accepted. |
-| Time limit | `recall_timeout` | `2` (seconds) | up to 30 | How long a search may take before the message goes on without memory. |
+| Time limit | `recall_timeout` | `2` (seconds) | Up to 30 | How long a search may take before the message goes on without memory. |
| Query length | `query_max_chars` | `8000` | 3–32,000 | Characters of the message used as the search query. |
-| Limit by category | `quotas` | `{}` (off) | keys: `events`, `entities`, `preferences`, `experiences`, `resources`, `skills` | Most entries per category; only categories above 0 are searched. |
+| Limit by category | `quotas` | `{}` (off) | Keys: `events`, `entities`, `preferences`, `experiences`, `resources`, `skills` | Most entries per category; only categories above 0 are searched. |
| Save conversations | `capture` | `true` | | Save finished turns to OpenViking. |
| Save the latest reply after | `idle_seconds` | `600` (seconds) | ≥ 1 | Quiet time before the last turn is saved and the session committed. |
| Commit after | `commit_tokens` | `20000` | ≥ 1 | Tokens waiting in the session that trigger a commit. |
@@ -753,17 +698,17 @@ URL settings must be plain `http` or `https` addresses without credentials, quer
| Compaction | `compaction` | `true` | | Replace the earlier part of a conversation with a summary near the context window. |
| Compact at | `compaction_threshold` | `0.9` | 0.5–0.98 | Share of the context window that triggers compaction. |
| Summary length | `summary_max_tokens` | `8000` | 1,000–32,000 | Most tokens in one summary. |
-| Default context window | `context_window` | unset (1,000,000 assumed) | ≥ 1,024 | Window used when the upstream does not list the model. |
+| Default context window | `context_window` | Not set (1,000,000 assumed) | ≥ 1,024 | Window used when the upstream does not list the model. |
| Agent-managed context windows | `agent_windows` | `false` | | Experimental. Let the model start new context windows itself; needs OpenViking tools. |
-| Soft reminder at | `window_soft_ratio` | `0.7` | 0.3–0.95, below `window_hard_ratio` | Share of the context window at which the model is reminded to start a new window soon. |
-| Hard reminder at | `window_hard_ratio` | `0.85` | 0.4–0.97 | Share of the context window at which the model is told to start a new window now. |
-| OpenViking tools | `gateway_tools` | `true` | | Offer OpenViking tools for Chat, full-history Responses and Anthropic Messages. |
-| Unselected tools | `disabled_tools` | The 8 tools that change data: `remember`, `write`, `edit`, `add_resource`, `add_skill`, `forget`, `set_acl` and `cancel_watch` | Tool names from OpenViking, without `openviking_` | Tools unavailable to new conversations; every other available tool is offered, including ones added later. API requests that omit the field get the default list; an empty list enables every available tool when the main switch is on. |
+| Soft reminder at | `window_soft_ratio` | `0.7` | 0.3–0.95, below `window_hard_ratio` | Share of the window at which the model is reminded to start a new window soon. |
+| Hard reminder at | `window_hard_ratio` | `0.85` | 0.4–0.97 | Share of the window at which the model is told to start a new window now. |
+| OpenViking tools | `gateway_tools` | `true` | | Offer OpenViking tools for Chat Completions, full-history Responses and Anthropic Messages. |
+| Unchecked tools | `disabled_tools` | The 8 tools that change data; see [Choose tools](#choose-tools) | OpenViking tool names, without `openviking_` | Tools new conversations do not get; every other available tool is offered, including ones added later. API requests that omit the field get the default list; an empty list with the main switch on offers every available tool. |
| Show tool calls | `show_tool_calls` | `true` | | Add a one-line notice to the reply for each OpenViking tool call. |
-| Rounds per request | `tool_max_rounds` | `null` (no limit) | 1 or more | See [OpenViking tools](#openviking-tools). |
-| Time limit per call | `tool_timeout_seconds` | `30` | up to 120 | |
+| Rounds per request | `tool_max_rounds` | `null` (no limit) | 1 or more | See [Limits](#limits). |
+| Time limit per call | `tool_timeout_seconds` | `30` | Up to 120 | |
| Result size | `tool_result_bytes` | `65536` | 1,024–1,048,576 | |
-| Total time | `tool_total_seconds` | `null` (no limit) | more than 0 | |
+| Total time | `tool_total_seconds` | `null` (no limit) | More than 0 | |
| Token budget | `tool_total_tokens` | `null` (no limit) | 1,024 or more | |
**Upstream settings:**
@@ -772,25 +717,42 @@ URL settings must be plain `http` or `https` addresses without credentials, quer
| --- | --- | --- | --- |
| Name | `name` | | Display name. |
| Protocol | `protocol` | | `anthropic` (Anthropic Messages), `chat` (Chat Completions) or `responses` (Responses). |
-| Provider | `vendor` | `generic` | `generic`, `anthropic`, `openai`, `deepseek`, `ark` (Volcano Engine Ark) or `byteplus` (BytePlus ModelArk). Studio offers only the protocols the provider supports; the API accepts any pair. |
-| Base URL | `base_url` | | Provider address; see [Upstreams](#upstreams) for each provider's default and the path rules. |
-| Who provides the API key | `auth_mode` | `managed` | `managed` (The gateway holds the API key) or `passthrough` (Each client sends its own key). |
-| API key | `api_key` | | Write-only. Blank on edit keeps the stored key. |
-| Extra headers | `headers` | `{}` | Write-only values; names are visible. |
-| Models | `models` | `[]` | Model names served; empty accepts any. |
-| Model aliases | `aliases` | `{}` | Client-facing name → model sent to the upstream. |
+| Provider | `vendor` | `generic` | `generic`, `anthropic`, `openai`, `deepseek`, `ark` (Volcano Engine Ark) or `byteplus` (BytePlus ModelArk). Studio offers only the protocols a provider supports; the API accepts any pair. |
+| Base URL | `base_url` | | Provider address; defaults and path rules are in [Upstreams](#upstreams). |
+| Who provides the API key | `auth_mode` | `managed` | `managed` (the gateway holds the API key) or `passthrough` (each client sends its own key). |
+| API key | `api_key` | | Write-only; see [Credentials](#credentials). |
+| Extra headers | `headers` | `{}` | Write-only; see [Credentials](#credentials). |
+| Models | `models` | `[]` | Model names served; empty accepts any name. |
+| Model aliases | `aliases` | `{}` | Name clients use → model sent to the upstream. |
| Context windows | `context_windows` | `{}` | Model → tokens, each at least 1,024. |
-| Priority | `priority` | `0` | Higher wins for new conversations. |
-| Enabled | `enabled` | `true` | Disabled upstreams receive no requests. |
-| Allow OpenViking tools | `allow_gateway_tools` | `true` | Whether OpenViking tools may be offered through this upstream. |
-| Restore reasoning the client drops | `replay_reasoning` | `null` (follows the provider) | Puts reasoning the client dropped back on earlier replies. `null` means on for `deepseek`, `ark` and `byteplus` and off for other providers; `true` or `false` overrides the provider default. Studio saves `null` while the switch matches the provider default. |
+| Priority | `priority` | `0` | Higher values win for new conversations. |
+| Enabled | `enabled` | `true` | A turned-off upstream receives no requests. |
+| Allow OpenViking tools | `allow_gateway_tools` | `true` | Whether OpenViking tools can be offered through this upstream. |
+| Restore reasoning the client drops | `replay_reasoning` | `null` (follows the provider) | Puts reasoning the client dropped back on earlier replies. `null` means on for `deepseek`, `ark` and `byteplus` and off for other providers; `true` or `false` overrides that. Studio saves `null` while the switch matches the provider default. |
| This key is a Coding Plan or subscription key | `coding_plan` | `false` | Rejects requests to this upstream unless allowed. |
-| Allow it anyway | `allow_coding_plan` | `false` | Allows a key marked as Coding Plan. |
-| Minimum cacheable prompt | `cache_min_tokens` | `1024` | Ark and ModelArk only; affects cache-eligibility reporting. |
+| Allow this plan through the gateway | `allow_coding_plan` | `false` | Allows use of a key marked as Coding Plan. |
+| Minimum cacheable prompt | `cache_min_tokens` | `1024` | Ark and ModelArk only; affects how cache eligibility is reported. |
+
+Gateway key fields, every management operation, the access rules and the error reasons are in the [Management API](../api/25-gateway.md).
+
+## Migration
-**Gateway key fields:** Name (`name`), OpenViking key (`openviking_key`), Context profile (`policy_id`), Upstreams (`upstream_ids`, at least one) and Allowed models (`models`). When you issue through OpenViking Server, you can send the `user_id` of a user in this account instead of `openviking_key`, and OpenViking Server reads that user's key; send only one of the two.
+These steps apply when you move from the sidecar or standalone gateway of earlier releases to the embedded gateway.
-Studio calls the management API on OpenViking Server under `/api/v1/admin/gateway/`, with the resources `overview`, `logs`, `guides`, `upstreams`, `policies`, `keys` and `users/{user_id}/data`. Scripts can call the same paths with an account admin key.
+1. **Back up first.** Back up `storage_path` (both databases and `encryption.key`, if it is there). Stop the old gateway process or sidecar before you enable the embedded gateway.
+2. **Remove old fields.** Delete `host`, `port`, `workers`, `url`, `openviking_url`, `admin_token_env` and `encryption_key_env` from the `gateway` section of `ov.conf`. The server ignores them and logs a warning at startup, so an old `ov.conf` still starts, but clean them up. `openviking-server init` → **Update gateway** removes them for you. To keep running the gateway on its own instead, run `openviking-gateway init`, or move its settings to a separate `gateway.conf`, without the `gateway` wrapper and `enabled`. The standalone command no longer takes `--openviking-url`, `--host`, `--port`, `--workers` or `--storage-path`; set them in `gateway.conf` or as environment variables.
+3. **Fix the public address.** Point `public_url` at the server's public address, without `/gateway`, or remove it. The old quick start set it to `http://127.0.0.1:1935`, which the embedded gateway no longer listens on, so setup guides and upload links would point at nothing. When `public_url` points at another port, `openviking-server init` → **Update gateway** offers to clear it.
+4. **Update client addresses and deployment config.** Every gateway URL now lives under `/gateway`, so clients change both the port and the path: `http://host:1935/v1` becomes `http://host:1933/gateway/v1`, a Claude Code `ANTHROPIC_BASE_URL` of `http://host:1935` becomes `http://host:1933/gateway`, and Ark SDKs move to `http://host:1933/gateway/api/v3`. The old paths are not served any more. Scripts that call the management API move from `/api/v1/admin/gateway/...` to `/gateway/admin/...`. Remove the old 1935 Service and Ingress routes, the Compose `gateway` service and profile, and the Helm sidecar settings `gateway.workers`, `gateway.port` and `gateway.resources`. 1935 is still the standalone default port, and a standalone gateway uses the same `/gateway` paths.
+5. **Let the first start convert stored data.** The v0.5 gateway encrypted its data with its own key. On the first start, the new gateway (embedded or standalone) decrypts it with that key and rewrites it under the current [encryption](#encryption) settings, or in plain text when encryption is off, so turn on OpenViking encryption before this start if you want the data to stay encrypted. The old key is read from the `OPENVIKING_GATEWAY_ENCRYPTION_KEY` environment variable, or from `encryption.key` in `storage_path`. `encryption_key_env` is ignored: if you used it to point at another variable, export the key as `OPENVIKING_GATEWAY_ENCRYPTION_KEY` for this start. If old encrypted data exists and neither source has the key, the gateway refuses to start and the error names both places. With Helm, keep the `encryption-key` entry in the `existingSecret` Secret for the upgrade release only. After a successful start the old key is never read again, so you can remove the variable, the Secret entry and `encryption.key`.
+6. **Remove the shared admin token.** `OPENVIKING_GATEWAY_ADMIN_TOKEN` is **not** used as a management key. To restrict who can change upstreams and context profiles, set `management_key` explicitly.
+7. **Check upstream addresses.** On first start, the gateway rewrites stored Base URLs once, so each upstream keeps calling the same address as before the upgrade:
+ - Ark and ModelArk Chat Completions and Responses upstreams with only a domain get `/api/v3` added.
+ - Other Chat Completions and Responses upstreams whose path does not end in a version segment such as `/v1` or `/v4` get `/v1` added. This covers bare domains (`https://api.deepseek.com` → `https://api.deepseek.com/v1`) and addresses with a path prefix (`https://openrouter.ai/api` → `https://openrouter.ai/api/v1`, or a self-hosted proxy under `/litellm`).
+ - Ark and ModelArk Anthropic upstreams with only a domain get `/api/compatible` added.
+ - Anthropic Base URLs ending in `/v1` lose the `/v1`.
+
+ Addresses that already end in another version segment are left alone, such as Zhipu's `https://open.bigmodel.cn/api/paas/v4`. Before the upgrade it became `…/v4/v1` and failed; now it works as entered. New and edited upstreams follow the rules in [Upstreams](#upstreams), and an Anthropic Base URL ending in `/v1` is rejected.
+8. **Note the changes to logs and revocation.** Request logs gain a user column; older records have no user and appear only in account admin and root views. Revoking a key no longer deletes the user's data; explicit deletion and retention still apply.
## Troubleshooting
@@ -798,130 +760,129 @@ Studio calls the management API on OpenViking Server under `/api/v1/admin/gatewa
| Symptom | Cause | What to do |
| --- | --- | --- |
-| A conversation gets no recall and is not saved | An OpenViking plugin was detected, and the gateway stepped aside, leaving recall, saving and OpenViking tools to the plugin. | Expected: it keeps the same content from being added or saved twice. See [Gateway or plugin?](15-gateway.md#gateway-or-plugin). |
-| Saving shows **Retrying**, then **Paused** | OpenViking rejected the save or could not be reached, often because the user's OpenViking key was regenerated. | The gateway recovers on its own once the cause is fixed; if the key is no longer valid, issue a new gateway key. See [Conversations do not appear in OpenViking](#conversations-do-not-appear-in-openviking). |
-| The profile has tools on, but the conversation has none | No request that could use tools has arrived yet, OpenViking's tool list failed to load for the first one, the client does not send the full history, or the client has OpenViking tools of its own. | Check the reason in the request log (see [OpenViking tools](#openviking-tools)). `tool_name_collision` is expected when the client has the OpenViking MCP server; for other reasons, fix the cause and start a new conversation. |
+| A conversation gets no recall and is not saved | An OpenViking plugin was detected, and the gateway left recall, saving and tools to the plugin. | Expected: it keeps content from being added or saved twice. See [Gateway or plugin?](15-gateway.md#gateway-or-plugin). |
+| Saving shows **Retrying**, then **Paused** | OpenViking rejected the save or could not be reached, or the conversation's gateway key was revoked (`gateway_key_revoked`), for example after the user's OpenViking key was regenerated. | Saving resumes on its own once OpenViking is back. After a revocation, issue a new gateway key; the user's next request resumes saving. See [Conversations do not appear in OpenViking](#conversations-do-not-appear-in-openviking). |
+| The profile has tools on, but the conversation has none | No request that could use tools has arrived yet, loading the tool list failed on the first one, the client does not send the full history, or the client has its own OpenViking tools. | Check the reason in the request log (see [When tools are not offered](#when-tools-are-not-offered)). `tool_name_collision` is expected when the client has the OpenViking MCP server; for other reasons, fix the cause and start a new conversation. |
| Requests go without memory | OpenViking unreachable or too slow, budget used up, nothing relevant, and so on. | See [No memory is added](#no-memory-is-added). |
| The provider rejects a long conversation as too long | The gateway does not know the model's real window and compacts too late. | See [Long conversations hit the context limit](#long-conversations-hit-the-context-limit). |
### The gateway does not start
-| Message | Cause and fix |
-| --- | --- |
-| `configure a Fernet encryption key and an admin token of at least 32 characters` | A secret is missing or too short in the gateway's environment. Load both [secrets](#secrets) into the shell, `.env` or Secret the gateway starts from. |
-| `Set gateway.enabled=true in ov.conf` | The section is missing or disabled, or the gateway read another file. It reads `--config`, then `OPENVIKING_CONFIG_FILE`, then `~/.openviking/ov.conf`, and nothing else. |
-| `Missing OpenViking Gateway dependencies: …` | Install the extra: `pip install "openviking[gateway]"`. |
-| A validation error about a `gateway` field | An unknown key, a typo or an invalid value. `${VAR}` placeholders are not expanded, so a placeholder in a numeric or URL field fails too. |
-| `OpenViking Gateway must bind to loopback when OpenViking uses dev authentication` | OpenViking runs in dev mode while `host` is not a loopback address. Switch OpenViking to API key mode. |
-| `Unsupported gateway schema; configure a fresh storage_path` | The storage was written by an incompatible gateway version. Point `storage_path` at an empty directory and set the gateway up again. |
+When an embedded gateway cannot start, the whole OpenViking Server stops. Read the startup error in the server log (`docker compose logs openviking` with Compose).
-In Docker Compose, a gateway that keeps restarting usually has empty secrets in `.env`; `docker compose logs gateway` shows the message.
+- **v0.5 data without the old key**: the storage directory holds data encrypted by the v0.5 gateway, but there is neither `OPENVIKING_GATEWAY_ENCRYPTION_KEY` nor `encryption.key` in `storage_path`. Provide the original key; see step 5 of [Migration](#migration).
+- **Old fields**: remove the fields listed in step 2 of [Migration](#migration).
+- **Management key too short**: it needs at least 32 characters. An unset environment variable referenced with `$VAR` causes the same error.
+- **Encryption settings**: the server's `encryption` section (embedded) or the `encryption` block in `gateway.conf` (standalone) is invalid, or its root key cannot be loaded. See the [Encryption guide](08-encryption.md).
+- **Unsupported storage format** (`Unsupported gateway schema`): the storage directory was written by an incompatible gateway version (an older one, or a newer one if you downgraded). Use a fresh, empty `storage_path`.
+- **Standalone without an OpenViking URL**: run `openviking-gateway init`, or set `OPENVIKING_GATEWAY_OPENVIKING_URL`.
+- **Standalone config file not found**: the file named by `--config` or `OPENVIKING_GATEWAY_CONFIG_FILE` does not exist. Fix the path, or create the file with `openviking-gateway init --config <path>`.
+- **Standalone on a non-loopback address**: the startup check must reach OpenViking and confirm `api_key` authentication, or the gateway exits. Start OpenViking first (in containers, wait until it is ready), or bind to `127.0.0.1`.
### Studio shows a setup card
-The OpenViking Gateway page shows a setup card instead of its tabs when OpenViking Server cannot use the gateway:
-
-- **The OpenViking Gateway is turned off**: OpenViking Server's `ov.conf` lacks `gateway.enabled: true`. Add it and restart OpenViking Server.
-- **The management token is missing**: OpenViking Server's environment lacks the admin token, or it is shorter than 32 characters. Set it (in Docker Compose through `.env`, in Helm through `gateway.existingSecret`) and restart OpenViking Server.
-- **OpenViking can't reach the gateway**: OpenViking Server cannot reach `gateway.url`. Check that the gateway is running and that `url` is the address OpenViking Server can use: `http://gateway:1935` in Docker Compose (the chart sets it for Helm).
-
-If both processes are running but the page says "Your key was rejected. Check Connection settings." although the same admin key works on **Users & Permissions**, the two processes have different admin tokens, and the gateway answers 401 "Invalid gateway management credential". Set the same token for both and restart them.
+| Card | What to do |
+| --- | --- |
+| The gateway is not enabled on this OpenViking server (404) | Run `openviking-server init` → **Update gateway**, or set `gateway.enabled: true` in `ov.conf` and restart. On a server that uses API keys, root can choose **Enable gateway** on that page instead. Account admins and regular users see a card that only asks them to contact whoever deployed the server. |
+| Connect to OpenViking first, or Your OpenViking API key is invalid (401) | Open connection settings and enter your current OpenViking API key. |
+| The gateway does not support Trusted mode (`trusted_mode_unsupported`) | Switch the server to `api_key` authentication. |
+| The gateway cannot reach OpenViking (`openviking_unreachable`) | Standalone gateways only: check `openviking_url` (in `gateway.conf` or `OPENVIKING_GATEWAY_OPENVIKING_URL`) and the network. |
-If **OpenViking Gateway** is missing from the sidebar, Studio has no admin access: enter an account admin or root key as the **Admin API key** in **Connection Settings**. While OpenViking runs in dev mode, Studio hides its management pages.
+If the Upstreams and Profiles tabs are read-only, the deployer set a gateway management key: choose **Enter gateway management key** to unlock them. An OpenViking root or admin API key does not unlock editing. After the management key is changed (`management_key_invalid`), Studio locks again.
### Issuing a key fails
-The **Issue a gateway key** dialog shows why issuing failed. The code in parentheses is the reason the management API returns.
+The **Issue a gateway key** dialog shows why issuing failed; the code in parentheses is the `reason` the management API returned.
| Message in Studio | Cause and fix |
| --- | --- |
-| The server can't read this user's OpenViking key. Paste the key instead. | OpenViking Server can't read the chosen user's key, usually because it stores only key hashes (`encryption.api_key_hashing.enabled`). Choose **Paste an OpenViking key** and enter the user's own key. |
-| This is a root key. (`root_key_not_allowed`) | The OpenViking key is a root key, or OpenViking runs in dev mode, where every key acts as root. Use the user's own key, and API key mode. |
-| This OpenViking key belongs to another account. | The key belongs to a different account than the one you manage in Studio. |
-| OpenViking rejected this key. (`openviking_http_401`) | The key is incomplete, was regenerated, or its user was removed. Use the user's current key. |
+| The server only stores a hash of this user's API key and cannot read it. Paste their user API key instead. (`user_key_unreadable`) | OpenViking Server stores only key hashes (`encryption.api_key_hashing.enabled`). Choose **Paste a user API key** and enter that user's own key. |
+| This is a root API key. Use the user API key of a user in this account. (`root_key_not_allowed`) | A root API key cannot be bound to a gateway key. Use the API key of a user or account admin instead. Local dev mode's `default/default` is exempt. |
+| This OpenViking API key belongs to another account. (`other_account`) | The key belongs to a different account from the one you are managing in Studio. |
+| OpenViking rejected this key. (`openviking_http_401`) | The key is incomplete or was regenerated, or the user was deleted. Use the user's current key. |
| OpenViking couldn't tell which user this key belongs to (`openviking_identity_missing`) | OpenViking returned no user for this key. Use the key of a user in this account. |
-| The gateway couldn't reach OpenViking to check this key. (`openviking_unavailable`) | The gateway cannot reach `openviking_url`. |
-| OpenViking is older than the gateway requires. (`openviking_version_mismatch`) | OpenViking Server is older than `min_server_version` (0.4.16). Upgrade it. A server installed from a source checkout without version tags may report a development version such as `0.1.dev123`; install a release, or set `min_server_version` to match. |
+| The gateway couldn't reach OpenViking to check this key. (`openviking_unavailable`) | The gateway cannot reach OpenViking; for a standalone gateway, check `openviking_url`. |
+| OpenViking is older than the gateway requires. (`openviking_version_mismatch`) | Standalone gateways only: OpenViking Server is older than `min_server_version` (0.4.16). Upgrade it. A server installed from source without version tags may report a development version such as `0.1.dev123`; install a release, or set `min_server_version` to match. |
### Clients get an error from the gateway
-These rejections happen before a request reaches a provider, so they do not appear on the Requests tab.
+These rejections happen before the request reaches a provider, so they do not appear in the request log.
| Status and message | Cause and fix |
| --- | --- |
-| 401 "Invalid or revoked OpenViking Gateway key" | The client sent no gateway key, a revoked one, or its provider key. Check which key the client sends. |
-| 403 "Claude subscription OAuth credentials are not supported" | The client sent a Claude subscription token, for example Claude Code signed in with a subscription and no `ANTHROPIC_AUTH_TOKEN` set; or the upstream holds one. Use API keys. |
+| 401 "Invalid gateway key. It may have been revoked, or removed because its OpenViking API key was regenerated…" | The client sent no gateway key, a revoked key or its provider API key, or the gateway deleted the key after the user's OpenViking API key was regenerated. Check which key the client actually sends, and issue a new one if needed. |
+| 403 "Claude subscription OAuth credentials are not supported" | The client sent a Claude subscription token, for example Claude Code signed in with a subscription and no `ANTHROPIC_AUTH_TOKEN` set; or the upstream stores a subscription token. Use an API key. |
| 403 "Model is not allowed by this key" | The model is not in the key's allowed models. Issue a key that allows it. |
-| 404 "No allowed upstream matches this protocol and model" | No enabled upstream bound to the key speaks the API the client called and serves the requested model. Check the upstream's protocol, its models and aliases, whether it is enabled, and the key's upstreams. |
-| 401 "Upstream API key is missing" | The upstream expects each client to send its own key in `X-OpenViking-Upstream-Key`, or a gateway-held upstream has no API key. |
-| 403 "Coding Plan upstreams are disabled; configure a model API key" | The upstream is marked as a Coding Plan key. Use a model API key, or deliberately check **Allow it anyway**. |
-| 404 "Unknown response for this key", 403 "Response upstream is no longer allowed" | A Responses lookup for a response this key did not create, or whose upstream is now disabled or no longer bound to the key. |
+| 404 "No allowed upstream matches this protocol and model" | No enabled upstream bound to the key uses the API the client called and serves the requested model. Check the upstreams' protocol, models and aliases, whether they are enabled, and which upstreams the key is bound to. |
+| 401 "Upstream API key is missing" | The upstream expects each client to send its own key in `X-OpenViking-Upstream-Key`, or an upstream where the gateway holds the key has none stored. |
+| 403 "Coding Plan upstreams are disabled; configure a model API key" | The upstream is marked as a Coding Plan key. Use a model API key, or deliberately check **Allow this plan through the gateway**. |
+| 404 "Unknown response for this key", 403 "Response upstream is no longer allowed" | The Responses response being looked up was not created with this key, or the upstream that created it is now turned off or no longer bound to the key. |
| 413 | The request body is larger than `max_body_bytes`, or than your proxy's own limit. |
| 426 | A WebSocket connection to the Responses API. Expected: Codex falls back to HTTP. |
-| 502 "Model upstream is unavailable" | The gateway could not reach the provider, or the call exceeded `upstream_timeout_seconds`. Use **Test connection** on the upstream. |
-| 503 "Dev authentication requires a loopback gateway" | OpenViking runs in dev mode. Switch it to API key mode. |
-| 504 "Hidden tool request timed out" | OpenViking tool rounds exceeded the profile's **Total time** for tools, or, when **Total time** is not set, one model request inside the tool rounds exceeded `upstream_timeout_seconds`. |
+| 502 "Model upstream is unavailable" | The gateway could not reach the provider, or the call took longer than `upstream_timeout_seconds`. Choose **Test** on the upstream. |
+| 504 "Hidden tool request timed out" | The OpenViking tool rounds took longer than the profile's tool **Total time**; or, with no total time set, one model request during the tool rounds took longer than `upstream_timeout_seconds`. |
### No memory is added
-Find the request on the Requests tab. If it is not there, the client is not going through the gateway, or the gateway rejected it (see the previous section). Otherwise, expand it and check the memory search result:
+First find the request in the request log. If it is not there, the client did not go through the gateway, or the gateway rejected the request (see the previous section). If it is there, expand it and check the memory search result:
-- **Nothing relevant found** (`empty`): normal for a new user. Memories exist only after a conversation has been committed and OpenViking has extracted them.
+- **Nothing relevant found** (`empty`): normal for a new user. Memories exist only after a conversation is committed and OpenViking has extracted them.
- **Recall is off or the budget is used up** (`disabled`): the profile has recall off, the conversation used up its budget, or the message is shorter than 3 characters.
-- **OpenViking is unreachable or didn't answer in time** (`openviking_unavailable`): check the OpenViking card on the Overview tab. If OpenViking is up but slow, consider a longer **Time limit**.
-- **OpenViking rejected the key** (`openviking_http_401`): the user's OpenViking key is no longer valid. Issue a new gateway key with the current OpenViking key.
+- **OpenViking is unreachable or didn't answer in time** (`openviking_unavailable`): check the OpenViking card on the Overview tab. If OpenViking is running but slow, raise the **Time limit**.
+- **OpenViking rejected the key** (`openviking_http_401`): the user's OpenViking key is no longer valid. Issue a new gateway key with the current key.
- **OpenViking is older than the gateway requires** (`openviking_version_mismatch`): see [Issuing a key fails](#issuing-a-key-fails).
-- **OpenViking plugin in use** (`plugin_present`): an OpenViking plugin was detected, and the gateway stepped aside for this conversation.
-- **Type is not New message**: tool steps, housekeeping and sub-agent requests never search; they replay what earlier messages received.
+- **OpenViking plugin in use** (`plugin_present`): the gateway detected an OpenViking plugin and stepped aside for this conversation.
+- **The type is not New message**: tool steps, housekeeping and sub-agent requests never search; they replay the memory earlier messages received.
A message whose search failed never gets memory later; the next message searches again.
### Conversations do not appear in OpenViking
-- **Saving is one turn behind.** A turn appears when the next message arrives, the last turn after **Save the latest reply after** (10 minutes by default).
-- **The profile does not save.** The Saving column shows Off.
-- **Saving is retrying or paused.** The expanded row shows the reason. Fix the cause, for example an invalid OpenViking key; the gateway retries within 5 minutes. If the conversation stays paused, use **Resync conversation…**.
-- **An OpenViking plugin is in use** (`plugin_present`); the gateway saves nothing for that conversation.
-- **You are looking as another user.** Sessions belong to the OpenViking user behind the gateway key and are named `gateway-…`.
-- **Memories come later than sessions.** OpenViking extracts memories only after a commit, in the background.
+- **Saving runs one turn behind.** A turn appears when the next message arrives; the last turn waits for **Save the latest reply after** (10 minutes by default).
+- **The profile does not save.** The **Saving** column shows Off.
+- **Saving is retrying or paused.** The expanded row shows the reason. Once the cause is fixed (for example, OpenViking is reachable again), the gateway retries within 5 minutes. With `gateway_key_revoked`, issue a new gateway key; the next request resumes saving. If the conversation stays paused, use **Resync conversation…**.
+- **An OpenViking plugin was detected** (`plugin_present`): the gateway saves nothing for that conversation.
+- **You are looking as a different user.** Sessions belong to the OpenViking user behind the gateway key and are named `gateway-…`.
+- **Memories show up later than sessions.** OpenViking extracts memories in the background, only after a commit.
### The first-call cache hit rate dropped
-Compare it with what the provider reaches without the gateway, then look at the issues on recent requests:
+Compare it with what the provider reaches without the gateway, then look at the issues flagged on recent requests:
-- **Memory record missing** (`missing_injection_record`): the gateway's storage was lost, restored from an old backup or expired, so memory added earlier could not be replayed. Ongoing conversations recover after one miss.
-- **Upstream switched** (`upstream_changed`): conversations moved to another upstream because theirs was disabled, is not bound to the key the client now uses, or stopped serving the model.
-- **Cache parameters changed** (`ark_cache_parameters_changed`): on Ark or ModelArk, the client changes the model, thinking, sampling, system prompt or tools within a conversation.
-- No issue: the client itself may change earlier messages or its system prompt every turn, for example by inserting the current time. The gateway cannot fix that. Each compaction, and each new context window the model starts, also costs one miss, which is expected.
+- **Memory record missing** (`missing_injection_record`): the gateway's storage was lost or restored from an old backup, or the record expired, so memory added earlier could not be replayed. Ongoing conversations recover after one miss.
+- **Upstream switched** (`upstream_changed`): the conversation's upstream was turned off, is not bound to the key the client now uses, or no longer serves the model, so the conversation moved to another upstream.
+- **Cache parameters changed** (`ark_cache_parameters_changed`): on Ark or ModelArk, the client changed the model, thinking mode, sampling parameters, system prompt or tools within a conversation.
+- **No issue flagged**: the client itself may change earlier messages or its system prompt every turn, for example by inserting the current time, which the gateway cannot fix. Each compaction, and each new context window the model starts, also costs one miss; that is expected.
### Long conversations hit the context limit
-If the provider rejects long conversations as too long for the model:
+When the provider rejects a long conversation as too long, it is usually one of three causes:
-- **The model's window is unknown to the gateway.** Without an entry in the upstream's **Context windows** or a **Default context window** in the profile, the gateway assumes 1,000,000 tokens and compacts too late for smaller models. Add the model's window.
-- **Compaction is off** in the conversation's profile. Profile changes reach new conversations only.
-- **Compaction failed.** The request detail shows the reason, and the gateway tries again after 60 seconds. If summaries are cut off at the length limit, raise **Summary length**. `still_over_threshold` means the system prompt, tools and summary alone fill most of the window: lower **Summary length**, or check the model's window.
+- **The gateway does not know the model's window.** The upstream's **Context windows** has no entry for the model and the profile has no **Default context window**, so the gateway assumes 1,000,000 tokens and compacts too late for a smaller model. Add the model's window.
+- **The conversation's profile has compaction off.** Profile changes only reach new conversations.
+- **Compaction failed.** The request detail shows the reason, and the gateway tries again after 60 seconds. If summaries keep getting cut off at the length limit, raise **Summary length**. `still_over_threshold` means the system prompt, tools and summary alone fill most of the window: lower **Summary length**, or check the model's context window setting.
### File imports fail
- "Set gateway.public_url for client uploads": set `public_url` to an address the client can reach.
-- The upload link cannot be reached, or returns 404: route `/gateway/uploads` to the gateway in your proxy.
+- The upload link is unreachable or returns 404: make sure `public_url` is not an old `:1935` address, does not already end in `/gateway`, and that your proxy forwards `/gateway/uploads` like the other paths.
- 413: the file is larger than `max_body_bytes` or the proxy's limit.
- 502 "OpenViking upload is unavailable": the gateway cannot reach OpenViking Server.
-- The import tools are not offered: the OpenViking server does not provide them, the profile has them unchecked, or gateway tools are disabled for this request. Check the Tools list and request details.
+- The model has no import tool: the OpenViking service does not provide it, the profile has it unchecked, or this request cannot use gateway tools. Check the tool list and the request detail.
### Issues on degraded requests
-The **Requests** and **Overview** tabs flag requests the gateway could not fully handle. Studio shows the label; the code in parentheses is the same issue in the management API:
+The Requests and Overview tabs flag requests the gateway could not fully handle. Studio shows the issue label; the code in parentheses is the matching value in the management API:
| Issue | What happened | What to do |
| --- | --- | --- |
-| Memory unavailable (`memory_store_failure`) | The gateway could not read or write its storage, or the user's gateway data was just deleted. The request went to the model without memory; for Claude, earlier thinking was dropped. | Check disk space, permissions and the gateway's log. Expected right after deleting a user's data. |
-| Forwarded unchanged (`unsafe_json`) | The request contained numbers or duplicate keys that cannot be re-encoded exactly, so it was forwarded byte for byte without memory. | Usually specific to one client; nothing to change in the gateway. |
-| Upstream switched (`upstream_changed`) | The conversation's upstream could no longer serve it, so it moved to another one, with one cache miss and earlier Claude thinking dropped. | Re-enable the upstream, or have the client use a key that includes it; otherwise accept the move. |
-| Memory record missing (`missing_injection_record`) | Claude conversation: memory added earlier is no longer on record, so earlier thinking was dropped once. | Expected after storage loss or for very old conversations. Start a new conversation if it repeats. |
-| OpenViking plugin in use (`plugin_present`) | An OpenViking plugin was detected; gateway memory is off for this conversation. | Expected when a plugin is in use. Use either the plugin or the gateway for that client. |
-| Cache parameters changed (`ark_cache_parameters_changed`) | On Ark or ModelArk, cache-relevant parameters differ from the conversation's first request; the prompt cache probably missed. | Keep model, thinking, sampling, system prompt and tools stable within a conversation. |
-| Tool history unavailable (`hidden_tool_history_unavailable`) | A Claude conversation previously used OpenViking tools, but this request cannot use them, so earlier thinking has been removed. | Check the tool skip reason in the request detail, restore the original settings or start a new conversation. |
-| OpenViking tools failed (`hidden_tool_loop_failed`) | The model could not finish answering while using OpenViking tools, and the client received an error. | See [OpenViking tools](#openviking-tools). |
-| Reply not saved (`capture_parse_failure`) | A streamed reply could not be parsed, so this reply was not saved. The client was not affected. | Nothing; it is informational. |
+| Memory unavailable (`memory_store_failure`) | The gateway could not read or write its storage, or the user's gateway data was just deleted. The request went to the model without memory; in Claude conversations, earlier thinking was removed. | Check disk space, permissions and the gateway log. Expected right after deleting a user's gateway data. |
+| Forwarded unchanged (`unsafe_json`) | The request had numbers that cannot be re-encoded exactly, or duplicate keys, so the gateway forwarded it byte for byte without memory. | Usually specific to one client; nothing to change in the gateway. |
+| Upstream switched (`upstream_changed`) | The conversation's upstream could no longer serve it, so it moved to another one, with one cache miss and earlier Claude thinking removed. | Turn the upstream back on, or give the client a key that includes it; or accept the switch. |
+| Memory record missing (`missing_injection_record`) | In a Claude conversation, memory added earlier is no longer on record, so earlier thinking was removed once. | Expected after storage loss or in very old conversations. If it keeps happening, start a new conversation. |
+| OpenViking plugin in use (`plugin_present`) | An OpenViking plugin was detected, and this conversation no longer uses gateway memory. | Expected when a plugin is in use. Use either the plugin or the gateway for a given client. |
+| Cache parameters changed (`ark_cache_parameters_changed`) | On Ark or ModelArk, parameters that affect caching differ from the conversation's first request, so the prompt cache probably missed. | Keep the model, thinking mode, sampling parameters, system prompt and tools the same within a conversation. |
+| Tool history unavailable (`hidden_tool_history_unavailable`) | A Claude conversation used OpenViking tools, but this request cannot use them, so earlier thinking was removed. | Check the tool skip reason in the request detail, restore the original settings, or start a new conversation. |
+| OpenViking tools failed (`hidden_tool_loop_failed`) | The model could not finish its answer while using OpenViking tools, and the client received an error. | See [Failure handling](#failure-handling). |
+| Reply not saved (`capture_parse_failure`) | A streamed reply could not be parsed, so it was not saved. The client was not affected. | Nothing to do; it is for information only. |
+| Key not verified (`revocation_check_unavailable`) | OpenViking could not confirm the gateway key, so the request was served without checking whether the key was revoked. | Check that OpenViking is reachable and healthy. |
diff --git a/docs/images/gateway/architecture.en.svg b/docs/images/gateway/architecture.en.svg
index d4067eee0..e1901071d 100644
--- a/docs/images/gateway/architecture.en.svg
+++ b/docs/images/gateway/architecture.en.svg
@@ -1,163 +1,146 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="990" viewBox="0 0 1600 990">
-<rect x="0" y="0" width="1600" height="990" rx="20" fill="#FFFFFF"/>
+<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="1100" viewBox="0 0 1600 1100">
+<rect x="0" y="0" width="1600" height="1100" rx="20" fill="#FFFFFF" stroke="none" stroke-width="0"/>
<text x="40" y="52" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="24" font-weight="700" fill="#1F2329" text-anchor="start">Where OpenViking Gateway runs and where its data lives</text>
-<rect x="320" y="90" width="890" height="822" rx="14" fill="#FCFBFF" stroke="#B7A3F0" stroke-width="1.5" stroke-dasharray="8 6"/>
-<text x="340" y="122" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#6425D0" text-anchor="start">Your deployment · gateway and OpenViking on one host or apart</text>
-<text x="340" y="146" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">They talk only over HTTP: separate containers in Compose, one Pod in Helm, or separate machines</text>
<text x="40" y="142" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#3370FF" text-anchor="start">Clients</text>
<rect x="40" y="160" width="220" height="64" rx="10" fill="#EAF2FF" stroke="#3370FF" stroke-width="1.5"/>
<text x="150" y="198" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="700" fill="#1F2329" text-anchor="middle">Claude Code · Codex</text>
+<polyline points="260,192 274,192" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
<rect x="40" y="242" width="220" height="64" rx="10" fill="#EAF2FF" stroke="#3370FF" stroke-width="1.5"/>
<text x="150" y="280" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="700" fill="#1F2329" text-anchor="middle">Chat apps · SDK apps</text>
+<polyline points="260,274 274,274" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
<rect x="40" y="324" width="220" height="64" rx="10" fill="#EAF2FF" stroke="#3370FF" stroke-width="1.5"/>
<text x="150" y="362" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="700" fill="#1F2329" text-anchor="middle">Low-code · other agents</text>
+<polyline points="260,356 274,356" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
<rect x="40" y="412" width="220" height="90" rx="10" fill="#F5F9FF" stroke="#3370FF" stroke-width="1.5" stroke-dasharray="5 4"/>
<text x="56" y="438" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="start">Change two settings</text>
<text x="56" y="463" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">Base URL → gateway</text>
<text x="56" y="487" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">API key → gateway key</text>
-<polyline points="260,192 274,192" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<polyline points="260,274 274,274" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<polyline points="260,356 274,356" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<polyline points="274,192 274,356" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<rect x="350" y="170" width="130" height="490" rx="10" fill="#F5F6F7" stroke="#8F959E" stroke-width="1.5"/>
-<polyline points="393,290 411,290" fill="none" stroke="#8F959E" stroke-width="2" stroke-linejoin="round"/>
-<polyline points="411,290 431,276" fill="none" stroke="#8F959E" stroke-width="2" stroke-linejoin="round"/>
-<polyline points="411,290 431,304" fill="none" stroke="#8F959E" stroke-width="2" stroke-linejoin="round"/>
-<circle cx="411" cy="290" r="4" fill="#8F959E"/>
-<text x="415" y="336" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="18" font-weight="700" fill="#1F2329" text-anchor="middle">Reverse</text>
-<text x="415" y="358" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="18" font-weight="700" fill="#1F2329" text-anchor="middle">proxy</text>
-<text x="415" y="384" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">Caddy /</text>
-<text x="415" y="405" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">nginx /</text>
-<text x="415" y="426" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">Ingress</text>
-<text x="415" y="460" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#646A73" text-anchor="middle">Single public</text>
-<text x="415" y="481" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#646A73" text-anchor="middle">entry · HTTPS</text>
-<text x="415" y="502" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#646A73" text-anchor="middle">Routes by path</text>
-<text x="415" y="610" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#8F959E" text-anchor="middle">Optional for</text>
-<text x="415" y="631" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#8F959E" text-anchor="middle">a local trial</text>
-<rect x="560" y="170" width="340" height="220" rx="10" fill="#F3EEFF" stroke="#7F3BF5" stroke-width="2.5"/>
-<text x="580" y="208" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="22" font-weight="700" fill="#1F2329" text-anchor="start">OpenViking Gateway</text>
-<rect x="826.4" y="190" width="61" height="24" rx="12" fill="#FFFFFF" stroke="#7F3BF5" stroke-width="1.2"/>
-<text x="856.9" y="207.4" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="600" fill="#7F3BF5" text-anchor="middle">:1935</text>
-<rect x="578" y="226" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
-<text x="652" y="247.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">Recall memories</text>
-<rect x="738" y="226" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
-<text x="812" y="247.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">Replay verbatim</text>
-<rect x="578" y="268" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
-<text x="652" y="289.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">Save turns</text>
-<rect x="738" y="268" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
-<text x="812" y="289.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">Compact history</text>
-<text x="580" y="336" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">Optional: runs OpenViking tools</text>
-<rect x="632.8" y="352" width="251.2" height="26" rx="13" fill="#FFFFFF" stroke="#7F3BF5" stroke-width="1.2"/>
-<text x="758.4" y="370.04" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#7F3BF5" text-anchor="middle">Optional OpenViking component</text>
-<rect x="560" y="510" width="340" height="180" rx="10" fill="#E6DCFF" stroke="#6425D0" stroke-width="2"/>
-<text x="580" y="548" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="20" font-weight="700" fill="#1F2329" text-anchor="start">OpenViking Server</text>
-<rect x="786" y="530" width="61" height="24" rx="12" fill="#FFFFFF" stroke="#6425D0" stroke-width="1.2"/>
-<text x="816.5" y="547.4" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="600" fill="#6425D0" text-anchor="middle">:1933</text>
-<text x="580" y="582" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">Search · sessions ·</text>
-<text x="580" y="603" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">memory extraction · embedding</text>
-<rect x="704" y="638" width="180" height="36" rx="8" fill="#FFFFFF" stroke="#6425D0" stroke-width="1.2"/>
-<text x="794" y="662" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="600" fill="#1F2329" text-anchor="middle">Studio admin UI</text>
-<polyline points="642.5,690 642.5,742" fill="none" stroke="#6425D0" stroke-width="1.5" stroke-linejoin="round"/>
-<ellipse cx="642.5" cy="846" rx="82.5" ry="16" fill="#FAF8FF" stroke="#6425D0" stroke-width="1.5"/>
-<rect x="560" y="758" width="165" height="88" fill="#FAF8FF" stroke="none"/>
-<line x1="560" y1="758" x2="560" y2="846" stroke="#6425D0" stroke-width="1.5"/>
-<line x1="725" y1="758" x2="725" y2="846" stroke="#6425D0" stroke-width="1.5"/>
-<ellipse cx="642.5" cy="758" rx="82.5" ry="16" fill="#FFFFFF" stroke="#6425D0" stroke-width="1.5"/>
-<text x="642.5" y="798" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="middle">AGFS file store</text>
-<text x="642.5" y="822" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">Session and</text>
-<text x="642.5" y="841" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">memory content</text>
-<polyline points="817.5,690 817.5,742" fill="none" stroke="#6425D0" stroke-width="1.5" stroke-linejoin="round"/>
-<ellipse cx="817.5" cy="846" rx="82.5" ry="16" fill="#FAF8FF" stroke="#6425D0" stroke-width="1.5"/>
-<rect x="735" y="758" width="165" height="88" fill="#FAF8FF" stroke="none"/>
-<line x1="735" y1="758" x2="735" y2="846" stroke="#6425D0" stroke-width="1.5"/>
-<line x1="900" y1="758" x2="900" y2="846" stroke="#6425D0" stroke-width="1.5"/>
-<ellipse cx="817.5" cy="758" rx="82.5" ry="16" fill="#FFFFFF" stroke="#6425D0" stroke-width="1.5"/>
-<text x="817.5" y="806" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="middle">Vector DB</text>
-<text x="817.5" y="832" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">Search index</text>
-<text x="730" y="892" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="middle">The source of truth for sessions and memories</text>
-<polyline points="900,380 1065,430" fill="none" stroke="#7F3BF5" stroke-width="2" stroke-linejoin="round" stroke-dasharray="2 5"/>
-<ellipse cx="1065" cy="788" rx="125" ry="18" fill="#FAF8FF" stroke="#7F3BF5" stroke-width="1.5"/>
-<rect x="940" y="448" width="250" height="340" fill="#FAF8FF" stroke="none"/>
-<line x1="940" y1="448" x2="940" y2="788" stroke="#7F3BF5" stroke-width="1.5"/>
-<line x1="1190" y1="448" x2="1190" y2="788" stroke="#7F3BF5" stroke-width="1.5"/>
-<ellipse cx="1065" cy="448" rx="125" ry="18" fill="#FFFFFF" stroke="#7F3BF5" stroke-width="1.5"/>
-<text x="1065" y="490" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#1F2329" text-anchor="middle">Gateway local state</text>
-<text x="1065" y="513" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#646A73" text-anchor="middle">Two encrypted SQLite files</text>
-<rect x="952" y="526" width="226" height="122" rx="8" fill="#FFFFFF" stroke="#D9CCFB" stroke-width="1"/>
-<text x="962" y="548" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="700" fill="#7F3BF5" text-anchor="start">Management DB</text>
-<text x="962" y="566" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">Upstreams, provider keys,</text>
-<text x="962" y="584" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">users' OpenViking keys,</text>
-<text x="962" y="602" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">gateway key hashes,</text>
-<text x="962" y="620" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">context profiles,</text>
-<text x="962" y="638" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">request logs (metadata)</text>
-<rect x="952" y="656" width="226" height="122" rx="8" fill="#FFFFFF" stroke="#D9CCFB" stroke-width="1"/>
-<text x="962" y="678" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="700" fill="#7F3BF5" text-anchor="start">Conversation state DB</text>
-<text x="962" y="696" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">Added memory text,</text>
-<text x="962" y="714" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">summaries, tool calls,</text>
-<text x="962" y="732" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">turns waiting to be saved;</text>
-<text x="962" y="750" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">deleted 30 days after</text>
-<text x="962" y="768" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">last use</text>
-<text x="1065" y="832" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#646A73" text-anchor="middle">Single host, 1–64 workers</text>
-<text x="1260" y="142" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#FF8800" text-anchor="start">Upstream model providers</text>
-<rect x="1260" y="160" width="300" height="180" rx="10" fill="#FFF3E8" stroke="#FF8800" stroke-width="1.5"/>
-<text x="1410" y="210" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">Anthropic · OpenAI · DeepSeek</text>
-<text x="1410" y="240" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">Volcano Engine Ark</text>
-<text x="1410" y="270" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">BytePlus ModelArk</text>
-<text x="1410" y="300" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">Compatible self-hosted APIs</text>
-<text x="1260" y="368" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">Sees the full model input,</text>
-<text x="1260" y="390" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">including added memories</text>
+<polyline points="274,192 274,715" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
<polyline points="274,274 341,274" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
<polygon points="350,274 340,278 340,270" fill="#646A73"/>
-<rect x="275.4" y="249.7" width="73.2" height="18.2" rx="3" fill="#FFFFFF"/>
-<text x="312" y="263" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">Requests</text>
-<rect x="264.15" y="283.65" width="95.7" height="16.9" rx="3" fill="#FFFFFF"/>
-<text x="312" y="296" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#646A73" text-anchor="middle">full history</text>
-<rect x="271.95" y="301.65" width="80.1" height="16.9" rx="3" fill="#FFFFFF"/>
-<text x="312" y="314" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#646A73" text-anchor="middle">every turn</text>
-<polyline points="480,250 551,250" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<polygon points="560,250 550,254 550,246" fill="#646A73"/>
-<text x="520" y="216" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">Model APIs</text>
-<text x="520" y="236" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">Uploads</text>
-<polyline points="480,610 551,610" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 4"/>
-<polygon points="560,610 550,614 550,606" fill="#646A73"/>
-<text x="520" y="580" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#646A73" text-anchor="middle">All other</text>
-<text x="520" y="598" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#646A73" text-anchor="middle">paths</text>
-<polyline points="900,232 1251,232" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<polygon points="1260,232 1250,236 1250,228" fill="#646A73"/>
-<rect x="899.75" y="205.75" width="316.5" height="19.5" rx="3" fill="#FCFBFF"/>
-<text x="1058" y="220" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">Same API: original request + memories</text>
-<polyline points="1260,302 909,302" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<polygon points="900,302 910,298 910,306" fill="#646A73"/>
-<rect x="990.5" y="311.75" width="159" height="19.5" rx="3" fill="#FCFBFF"/>
-<text x="1070" y="326" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">Reply streams back</text>
-<polyline points="650,401 650,499" fill="none" stroke="#7F3BF5" stroke-width="3" stroke-linejoin="round"/>
-<polygon points="650,510 644.5,498 655.5,498" fill="#7F3BF5"/>
-<polygon points="650,390 655.5,402 644.5,402" fill="#7F3BF5"/>
-<text x="664" y="418" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#7F3BF5" text-anchor="start">As the user, with their</text>
-<text x="664" y="436.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#7F3BF5" text-anchor="start">own OpenViking key</text>
-<text x="664" y="455" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#7F3BF5" text-anchor="start">① Search OpenViking (≤ 2 s)</text>
-<text x="664" y="473.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#7F3BF5" text-anchor="start">② Save the conversation</text>
-<text x="664" y="492" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#7F3BF5" text-anchor="start">③ OpenViking tools (optional)</text>
-<polyline points="596,510 596,399" fill="none" stroke="#7F3BF5" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 4"/>
-<polygon points="596,390 600,400 592,400" fill="#7F3BF5"/>
-<text x="588" y="440" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#7F3BF5" text-anchor="end">Studio</text>
-<text x="588" y="461" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#7F3BF5" text-anchor="end">admin calls</text>
-<circle cx="1400" cy="618" r="12" fill="#FFFFFF" stroke="#646A73" stroke-width="2"/>
-<path d="M 1380 654 Q 1380 634 1400 634 Q 1420 634 1420 654 Z" fill="#FFFFFF" stroke="#646A73" stroke-width="2"/>
-<text x="1400" y="680" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="600" fill="#1F2329" text-anchor="middle">Admin</text>
-<polyline points="1400,692 1400,858 920,858 920,656 909,656" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 4"/>
-<polygon points="900,656 910,652 910,660" fill="#646A73"/>
-<rect x="1212.1" y="870.7" width="379.8" height="18.2" rx="3" fill="#FFFFFF"/>
-<text x="1402" y="884" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">Issues gateway keys and adds upstreams in Studio</text>
-<polyline points="40,951 68,951" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<text x="76" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">Every request</text>
-<text x="181.3" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start"> · </text>
-<polyline points="207.7,951 235.7,951" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 4"/>
-<text x="243.7" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">Admin or optional</text>
-<text x="378.7" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start"> · </text>
-<circle cx="411.1000000000001" cy="951" r="6" fill="#FF8800"/>
-<text x="423.1" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">OpenViking down: chats continue without memory</text>
-<text x="790" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start"> · </text>
-<circle cx="822.4" cy="951" r="6" fill="#F54A45"/>
-<text x="834.4" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">Gateway down: every model call through it fails</text>
+<polyline points="274,715 341,715" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="350,715 340,719 340,711" fill="#646A73"/>
+<rect x="320" y="90" width="890" height="455" rx="14" fill="#FCFBFF" stroke="#B7A3F0" stroke-width="1.5" stroke-dasharray="8 6"/>
+<text x="340" y="122" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#6425D0" text-anchor="start">Embedded · the gateway runs inside OpenViking Server</text>
+<text x="340" y="146" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">Same process and port (:1933) · turn on with gateway.enabled</text>
+<rect x="350" y="170" width="170" height="340" rx="10" fill="#F5F6F7" stroke="#8F959E" stroke-width="1.5"/>
+<text x="435" y="204" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#1F2329" text-anchor="middle">Server port</text>
+<text x="435" y="227" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="600" fill="#6425D0" text-anchor="middle">:1933</text>
+<text x="435" y="266" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#7F3BF5" text-anchor="middle">Gateway paths</text>
+<text x="435" y="288" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="700" fill="#1F2329" text-anchor="middle">/gateway/</text>
+<text x="435" y="308" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">Model APIs</text>
+<text x="435" y="328" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">Tool uploads</text>
+<text x="435" y="348" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">Management API</text>
+<text x="435" y="418" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#646A73" text-anchor="middle">Other paths</text>
+<text x="435" y="440" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#646A73" text-anchor="middle">OpenViking APIs</text>
+<text x="435" y="460" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#646A73" text-anchor="middle">and Studio</text>
+<polyline points="520,250 561,250" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="570,250 560,254 560,246" fill="#646A73"/>
+<polyline points="520,470 561,470" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 4"/>
+<polygon points="570,470 560,474 560,466" fill="#646A73"/>
+<rect x="570" y="170" width="330" height="170" rx="10" fill="#F3EEFF" stroke="#7F3BF5" stroke-width="2.5"/>
+<text x="590" y="206" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="22" font-weight="700" fill="#1F2329" text-anchor="start">OpenViking Gateway</text>
+<rect x="588" y="222" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
+<text x="662.0" y="243.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">Recall memories</text>
+<rect x="748" y="222" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
+<text x="822.0" y="243.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">Replay verbatim</text>
+<rect x="588" y="262" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
+<text x="662.0" y="283.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">Save turns</text>
+<rect x="748" y="262" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
+<text x="822.0" y="283.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">Compact history</text>
+<text x="590" y="322" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">Optional: runs OpenViking tools</text>
+<polyline points="650,352 650,418" fill="none" stroke="#7F3BF5" stroke-width="3" stroke-linejoin="round"/>
+<polygon points="650,430 644.5,418 655.5,418" fill="#7F3BF5"/>
+<polygon points="650,340 655.5,352 644.5,352" fill="#7F3BF5"/>
+<text x="664" y="362" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#7F3BF5" text-anchor="start">Loopback HTTP, as the user with</text>
+<text x="664" y="380.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#7F3BF5" text-anchor="start">their own OpenViking key</text>
+<text x="664" y="399" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#7F3BF5" text-anchor="start">① Search ≤ 2 s · ② Save · ③ Tools</text>
+<rect x="570" y="430" width="330" height="90" rx="10" fill="#E6DCFF" stroke="#6425D0" stroke-width="2"/>
+<text x="590" y="460" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="18" font-weight="700" fill="#1F2329" text-anchor="start">OpenViking Server core</text>
+<text x="590" y="484" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">Search · sessions · memory extraction</text>
+<text x="590" y="505" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">Studio · source of truth for memories</text>
+<polyline points="900,322 1065,344" fill="none" stroke="#7F3BF5" stroke-width="2" stroke-linejoin="round" stroke-dasharray="2 5"/>
+<ellipse cx="1065.0" cy="516" rx="125.0" ry="16" fill="#FAF8FF" stroke="#7F3BF5" stroke-width="1.5"/>
+<rect x="940" y="362" width="250" height="154" rx="0" fill="#FAF8FF" stroke="none" stroke-width="0"/>
+<line x1="940" y1="362" x2="940" y2="516" stroke="#7F3BF5" stroke-width="1.5"/>
+<line x1="1190" y1="362" x2="1190" y2="516" stroke="#7F3BF5" stroke-width="1.5"/>
+<ellipse cx="1065.0" cy="362" rx="125.0" ry="16" fill="#FFFFFF" stroke="#7F3BF5" stroke-width="1.5"/>
+<text x="1065" y="400" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="middle">Gateway local state</text>
+<text x="1065" y="421" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#646A73" text-anchor="middle">Two SQLite files</text>
+<text x="1065" y="446" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">Management: upstreams, keys,</text>
+<text x="1065" y="465" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">profiles, request logs</text>
+<text x="1065" y="490" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">Conversations: added memory,</text>
+<text x="1065" y="509" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">summaries, unsaved turns</text>
+<rect x="320" y="575" width="890" height="440" rx="14" fill="#FCFBFF" stroke="#B7A3F0" stroke-width="1.5" stroke-dasharray="8 6"/>
+<text x="340" y="607" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#6425D0" text-anchor="start">Standalone · openviking-gateway connects to an existing OpenViking</text>
+<text x="340" y="631" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">Own port (:1935) and Studio · open source or OpenViking Cloud · no server change</text>
+<rect x="350" y="655" width="170" height="200" rx="10" fill="#F5F6F7" stroke="#8F959E" stroke-width="1.5"/>
+<text x="435" y="690" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#1F2329" text-anchor="middle">Gateway port</text>
+<text x="435" y="713" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="600" fill="#7F3BF5" text-anchor="middle">:1935</text>
+<text x="435" y="752" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">Model APIs,</text>
+<text x="435" y="772" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">uploads,</text>
+<text x="435" y="792" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">management API</text>
+<text x="435" y="812" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">and Studio</text>
+<polyline points="520,715 561,715" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="570,715 560,719 560,711" fill="#646A73"/>
+<rect x="570" y="655" width="330" height="150" rx="10" fill="#F3EEFF" stroke="#7F3BF5" stroke-width="2.5"/>
+<text x="590" y="691" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="22" font-weight="700" fill="#1F2329" text-anchor="start">OpenViking Gateway</text>
+<rect x="588" y="707" width="294" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
+<text x="735.0" y="728.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">Same recall, replay, saving, compaction</text>
+<rect x="588" y="747" width="294" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
+<text x="735.0" y="768.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">Studio: gateway pages only</text>
+<polyline points="650,817 650,863" fill="none" stroke="#7F3BF5" stroke-width="3" stroke-linejoin="round"/>
+<polygon points="650,875 644.5,863 655.5,863" fill="#7F3BF5"/>
+<polygon points="650,805 655.5,817 644.5,817" fill="#7F3BF5"/>
+<text x="664" y="832" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#7F3BF5" text-anchor="start">HTTP(S), as the user with</text>
+<text x="664" y="851" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#7F3BF5" text-anchor="start">their own OpenViking key</text>
+<rect x="570" y="875" width="330" height="110" rx="10" fill="#E6DCFF" stroke="#6425D0" stroke-width="2"/>
+<text x="590" y="905" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="18" font-weight="700" fill="#1F2329" text-anchor="start">Existing OpenViking service</text>
+<text x="590" y="929" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">Open source or OpenViking Cloud</text>
+<text x="590" y="950" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">Server configuration unchanged</text>
+<text x="590" y="971" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">Source of truth for memories</text>
+<polyline points="900,795 1065,814" fill="none" stroke="#7F3BF5" stroke-width="2" stroke-linejoin="round" stroke-dasharray="2 5"/>
+<ellipse cx="1065.0" cy="960" rx="125.0" ry="16" fill="#FAF8FF" stroke="#7F3BF5" stroke-width="1.5"/>
+<rect x="940" y="830" width="250" height="130" rx="0" fill="#FAF8FF" stroke="none" stroke-width="0"/>
+<line x1="940" y1="830" x2="940" y2="960" stroke="#7F3BF5" stroke-width="1.5"/>
+<line x1="1190" y1="830" x2="1190" y2="960" stroke="#7F3BF5" stroke-width="1.5"/>
+<ellipse cx="1065.0" cy="830" rx="125.0" ry="16" fill="#FFFFFF" stroke="#7F3BF5" stroke-width="1.5"/>
+<text x="1065" y="868" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="middle">Gateway local state</text>
+<text x="1065" y="896" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">Same two SQLite files,</text>
+<text x="1065" y="915" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">on the gateway&#x27;s host</text>
+<text x="1260" y="142" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#FF8800" text-anchor="start">Upstream model providers</text>
+<rect x="1260" y="160" width="300" height="620" rx="10" fill="#FFF3E8" stroke="#FF8800" stroke-width="1.5"/>
+<text x="1410" y="420" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">Anthropic · OpenAI · DeepSeek</text>
+<text x="1410" y="450" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">Volcano Engine Ark</text>
+<text x="1410" y="480" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">BytePlus ModelArk</text>
+<text x="1410" y="510" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">Compatible self-hosted APIs</text>
+<text x="1260" y="808" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">Sees the full model input,</text>
+<text x="1260" y="830" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">including added memories</text>
+<polyline points="900,200 1251,200" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="1260,200 1250,204 1250,196" fill="#646A73"/>
+<rect x="918.6" y="176" width="322.8" height="21" rx="3" fill="#FCFBFF" stroke="#FCFBFF" stroke-width="0"/>
+<text x="1080" y="192" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">Same API: original request + memories</text>
+<polyline points="1260,290 909,290" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="900,290 910,286 910,294" fill="#646A73"/>
+<rect x="998.4" y="300" width="163.2" height="21" rx="3" fill="#FCFBFF" stroke="#FCFBFF" stroke-width="0"/>
+<text x="1080" y="316" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">Reply streams back</text>
+<polyline points="900,680 1251,680" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="1260,680 1250,684 1250,676" fill="#646A73"/>
+<rect x="918.6" y="656" width="322.8" height="21" rx="3" fill="#FCFBFF" stroke="#FCFBFF" stroke-width="0"/>
+<text x="1080" y="672" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">Same API: original request + memories</text>
+<polyline points="1260,750 909,750" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="900,750 910,746 910,754" fill="#646A73"/>
+<rect x="998.4" y="760" width="163.2" height="21" rx="3" fill="#FCFBFF" stroke="#FCFBFF" stroke-width="0"/>
+<text x="1080" y="776" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">Reply streams back</text>
+<polyline points="40,1056 68,1056" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<text x="76" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">Every request</text>
+<text x="187.39999999999998" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start"> · </text>
+<polyline points="213.39999999999998,1056 241.39999999999998,1056" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 4"/>
+<text x="249.39999999999998" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">Other OpenViking traffic</text>
+<text x="446.6" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start"> · </text>
+<circle cx="478.6" cy="1056" r="6" fill="#FF8800"/>
+<text x="490.6" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">OpenViking down: chats continue without memory</text>
+<text x="859.4000000000003" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start"> · </text>
+<circle cx="891.4000000000003" cy="1056" r="6" fill="#F54A45"/>
+<text x="903.4000000000003" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">Gateway down: every model call through it fails</text>
</svg>
diff --git a/docs/images/gateway/architecture.zh.svg b/docs/images/gateway/architecture.zh.svg
index 97fd5d7c4..2d67ecd51 100644
--- a/docs/images/gateway/architecture.zh.svg
+++ b/docs/images/gateway/architecture.zh.svg
@@ -1,155 +1,146 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="990" viewBox="0 0 1600 990">
-<rect x="0" y="0" width="1600" height="990" rx="20" fill="#FFFFFF"/>
-<text x="40" y="52" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="24" font-weight="700" fill="#1F2329" text-anchor="start">OpenViking 网关在哪里运行、数据存在哪里</text>
-<rect x="320" y="90" width="890" height="822" rx="14" fill="#FCFBFF" stroke="#B7A3F0" stroke-width="1.5" stroke-dasharray="8 6"/>
-<text x="340" y="122" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#6425D0" text-anchor="start">你的部署 · 网关和 OpenViking 可同机,也可分开</text>
-<text x="340" y="146" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">两者只通过 HTTP 通信:Compose 各一个容器,Helm 同在一个 Pod,也可放在不同机器</text>
+<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="1100" viewBox="0 0 1600 1100">
+<rect x="0" y="0" width="1600" height="1100" rx="20" fill="#FFFFFF" stroke="none" stroke-width="0"/>
+<text x="40" y="52" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="24" font-weight="700" fill="#1F2329" text-anchor="start">OpenViking 网关在哪里运行,数据存在哪里</text>
<text x="40" y="142" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#3370FF" text-anchor="start">客户端</text>
-<rect x="40" y="160" width="230" height="64" rx="10" fill="#EAF2FF" stroke="#3370FF" stroke-width="1.5"/>
-<text x="155" y="198" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="middle">Claude Code · Codex</text>
-<rect x="40" y="242" width="230" height="64" rx="10" fill="#EAF2FF" stroke="#3370FF" stroke-width="1.5"/>
-<text x="155" y="280" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="middle">聊天应用 · SDK 应用</text>
-<rect x="40" y="324" width="230" height="64" rx="10" fill="#EAF2FF" stroke="#3370FF" stroke-width="1.5"/>
-<text x="155" y="362" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="middle">低代码平台 · 其他 Agent</text>
-<rect x="40" y="412" width="230" height="90" rx="10" fill="#F5F9FF" stroke="#3370FF" stroke-width="1.5" stroke-dasharray="5 4"/>
-<text x="56" y="438" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="start">只改两处</text>
-<text x="56" y="463" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">Base URL → 网关地址</text>
+<rect x="40" y="160" width="220" height="64" rx="10" fill="#EAF2FF" stroke="#3370FF" stroke-width="1.5"/>
+<text x="150" y="198" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="700" fill="#1F2329" text-anchor="middle">Claude Code · Codex</text>
+<polyline points="260,192 274,192" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<rect x="40" y="242" width="220" height="64" rx="10" fill="#EAF2FF" stroke="#3370FF" stroke-width="1.5"/>
+<text x="150" y="280" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="700" fill="#1F2329" text-anchor="middle">聊天应用 · SDK 应用</text>
+<polyline points="260,274 274,274" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<rect x="40" y="324" width="220" height="64" rx="10" fill="#EAF2FF" stroke="#3370FF" stroke-width="1.5"/>
+<text x="150" y="362" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="700" fill="#1F2329" text-anchor="middle">低代码平台 · 其他 Agent</text>
+<polyline points="260,356 274,356" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<rect x="40" y="412" width="220" height="90" rx="10" fill="#F5F9FF" stroke="#3370FF" stroke-width="1.5" stroke-dasharray="5 4"/>
+<text x="56" y="438" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="start">只改两项设置</text>
+<text x="56" y="463" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">Base URL → 网关</text>
<text x="56" y="487" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">API Key → 网关密钥</text>
-<polyline points="270,192 284,192" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<polyline points="270,274 284,274" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<polyline points="270,356 284,356" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<polyline points="284,192 284,356" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<rect x="350" y="170" width="130" height="490" rx="10" fill="#F5F6F7" stroke="#8F959E" stroke-width="1.5"/>
-<polyline points="393,290 411,290" fill="none" stroke="#8F959E" stroke-width="2" stroke-linejoin="round"/>
-<polyline points="411,290 431,276" fill="none" stroke="#8F959E" stroke-width="2" stroke-linejoin="round"/>
-<polyline points="411,290 431,304" fill="none" stroke="#8F959E" stroke-width="2" stroke-linejoin="round"/>
-<circle cx="411" cy="290" r="4" fill="#8F959E"/>
-<text x="415" y="346" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="18" font-weight="700" fill="#1F2329" text-anchor="middle">反向代理</text>
-<text x="415" y="374" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">Caddy /</text>
-<text x="415" y="395" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">nginx /</text>
-<text x="415" y="416" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">Ingress</text>
-<text x="415" y="460" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="middle">唯一对外入口</text>
-<text x="415" y="481" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="middle">HTTPS</text>
-<text x="415" y="502" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="middle">按路径分流</text>
-<text x="415" y="610" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#8F959E" text-anchor="middle">单机试用</text>
-<text x="415" y="631" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#8F959E" text-anchor="middle">可省略</text>
-<rect x="560" y="170" width="340" height="220" rx="10" fill="#F3EEFF" stroke="#7F3BF5" stroke-width="2.5"/>
-<text x="580" y="208" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="22" font-weight="700" fill="#1F2329" text-anchor="start">OpenViking 网关</text>
-<rect x="771" y="190" width="61" height="24" rx="12" fill="#FFFFFF" stroke="#7F3BF5" stroke-width="1.2"/>
-<text x="801.5" y="207.4" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="600" fill="#7F3BF5" text-anchor="middle">:1935</text>
-<rect x="578" y="226" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
-<text x="652" y="247.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="600" fill="#1F2329" text-anchor="middle">召回记忆</text>
-<rect x="738" y="226" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
-<text x="812" y="247.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="600" fill="#1F2329" text-anchor="middle">原样放回</text>
-<rect x="578" y="268" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
-<text x="652" y="289.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="600" fill="#1F2329" text-anchor="middle">保存对话</text>
-<rect x="738" y="268" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
-<text x="812" y="289.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="600" fill="#1F2329" text-anchor="middle">压缩长对话</text>
-<text x="580" y="336" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">可选:代为执行 OpenViking 工具</text>
-<rect x="713.5" y="352" width="170.5" height="26" rx="13" fill="#FFFFFF" stroke="#7F3BF5" stroke-width="1.2"/>
-<text x="798.75" y="370.4" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#7F3BF5" text-anchor="middle">OpenViking 可选组件</text>
-<rect x="560" y="510" width="340" height="180" rx="10" fill="#E6DCFF" stroke="#6425D0" stroke-width="2"/>
-<text x="580" y="548" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="20" font-weight="700" fill="#1F2329" text-anchor="start">OpenViking Server</text>
-<rect x="786" y="530" width="61" height="24" rx="12" fill="#FFFFFF" stroke="#6425D0" stroke-width="1.2"/>
-<text x="816.5" y="547.4" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="600" fill="#6425D0" text-anchor="middle">:1933</text>
-<text x="580" y="584" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">检索 · 会话 · 记忆提取 · 向量化</text>
-<rect x="704" y="638" width="180" height="36" rx="8" fill="#FFFFFF" stroke="#6425D0" stroke-width="1.2"/>
-<text x="794" y="662" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="600" fill="#1F2329" text-anchor="middle">Studio 管理界面</text>
-<polyline points="642.5,690 642.5,742" fill="none" stroke="#6425D0" stroke-width="1.5" stroke-linejoin="round"/>
-<ellipse cx="642.5" cy="846" rx="82.5" ry="16" fill="#FAF8FF" stroke="#6425D0" stroke-width="1.5"/>
-<rect x="560" y="758" width="165" height="88" fill="#FAF8FF" stroke="none"/>
-<line x1="560" y1="758" x2="560" y2="846" stroke="#6425D0" stroke-width="1.5"/>
-<line x1="725" y1="758" x2="725" y2="846" stroke="#6425D0" stroke-width="1.5"/>
-<ellipse cx="642.5" cy="758" rx="82.5" ry="16" fill="#FFFFFF" stroke="#6425D0" stroke-width="1.5"/>
-<text x="642.5" y="806" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="middle">文件存储(AGFS)</text>
-<text x="642.5" y="832" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">会话和记忆正文</text>
-<polyline points="817.5,690 817.5,742" fill="none" stroke="#6425D0" stroke-width="1.5" stroke-linejoin="round"/>
-<ellipse cx="817.5" cy="846" rx="82.5" ry="16" fill="#FAF8FF" stroke="#6425D0" stroke-width="1.5"/>
-<rect x="735" y="758" width="165" height="88" fill="#FAF8FF" stroke="none"/>
-<line x1="735" y1="758" x2="735" y2="846" stroke="#6425D0" stroke-width="1.5"/>
-<line x1="900" y1="758" x2="900" y2="846" stroke="#6425D0" stroke-width="1.5"/>
-<ellipse cx="817.5" cy="758" rx="82.5" ry="16" fill="#FFFFFF" stroke="#6425D0" stroke-width="1.5"/>
-<text x="817.5" y="806" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="middle">向量库</text>
-<text x="817.5" y="832" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">检索索引</text>
-<text x="730" y="892" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="middle">会话和记忆的正本在这里</text>
-<polyline points="900,380 1065,430" fill="none" stroke="#7F3BF5" stroke-width="2" stroke-linejoin="round" stroke-dasharray="2 5"/>
-<ellipse cx="1065" cy="788" rx="125" ry="18" fill="#FAF8FF" stroke="#7F3BF5" stroke-width="1.5"/>
-<rect x="940" y="448" width="250" height="340" fill="#FAF8FF" stroke="none"/>
-<line x1="940" y1="448" x2="940" y2="788" stroke="#7F3BF5" stroke-width="1.5"/>
-<line x1="1190" y1="448" x2="1190" y2="788" stroke="#7F3BF5" stroke-width="1.5"/>
-<ellipse cx="1065" cy="448" rx="125" ry="18" fill="#FFFFFF" stroke="#7F3BF5" stroke-width="1.5"/>
-<text x="1065" y="490" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#1F2329" text-anchor="middle">网关本机状态</text>
-<text x="1065" y="513" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="middle">两个 SQLite,值加密</text>
-<rect x="952" y="526" width="226" height="122" rx="8" fill="#FFFFFF" stroke="#D9CCFB" stroke-width="1"/>
-<text x="962" y="548" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="700" fill="#7F3BF5" text-anchor="start">管理库</text>
-<text x="962" y="568" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">上游地址与服务商 Key、</text>
-<text x="962" y="588" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">用户的 OpenViking 密钥、</text>
-<text x="962" y="608" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">网关密钥哈希、上下文配置、</text>
-<text x="962" y="628" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">请求日志(仅元数据)</text>
-<rect x="952" y="656" width="226" height="122" rx="8" fill="#FFFFFF" stroke="#D9CCFB" stroke-width="1"/>
-<text x="962" y="678" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="700" fill="#7F3BF5" text-anchor="start">对话状态库</text>
-<text x="962" y="698" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">补充过的记忆原文、</text>
-<text x="962" y="718" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">压缩摘要、工具调用往返、</text>
-<text x="962" y="738" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">待保存的轮次</text>
-<text x="962" y="758" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="start">最后一次使用 30 天后删除</text>
-<text x="1065" y="832" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="middle">一台主机、单实例(可多工作进程)</text>
-<text x="1260" y="142" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#FF8800" text-anchor="start">上游模型服务商</text>
-<rect x="1260" y="160" width="300" height="180" rx="10" fill="#FFF3E8" stroke="#FF8800" stroke-width="1.5"/>
-<text x="1410" y="224" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">Anthropic · OpenAI · DeepSeek</text>
-<text x="1410" y="256" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">火山方舟 · BytePlus 方舟</text>
-<text x="1410" y="288" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">自建兼容服务</text>
-<text x="1260" y="368" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">能看到完整模型输入,</text>
-<text x="1260" y="390" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">包括补充的记忆</text>
-<polyline points="284,274 341,274" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polyline points="274,192 274,715" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polyline points="274,274 341,274" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
<polygon points="350,274 340,278 340,270" fill="#646A73"/>
-<rect x="284" y="248.75" width="66" height="19.5" rx="3" fill="#FFFFFF"/>
-<text x="317" y="263" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="600" fill="#1F2329" text-anchor="middle">模型请求</text>
-<rect x="291.5" y="283.75" width="51" height="19.5" rx="3" fill="#FFFFFF"/>
-<text x="317" y="298" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="middle">每轮带</text>
-<rect x="284" y="303.75" width="66" height="19.5" rx="3" fill="#FFFFFF"/>
-<text x="317" y="318" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="middle">完整历史</text>
-<polyline points="480,250 551,250" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<polygon points="560,250 550,254 550,246" fill="#646A73"/>
-<text x="520" y="216" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">模型 API</text>
-<text x="520" y="236" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">工具上传</text>
-<polyline points="480,610 551,610" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 4"/>
-<polygon points="560,610 550,614 550,606" fill="#646A73"/>
-<text x="520" y="598" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="middle">其他路径</text>
-<polyline points="900,232 1251,232" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<polygon points="1260,232 1250,236 1250,228" fill="#646A73"/>
-<rect x="935" y="205.75" width="270" height="19.5" rx="3" fill="#FCFBFF"/>
-<text x="1070" y="220" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">同一种 API 转发:原请求 + 补充的记忆</text>
-<polyline points="1260,302 909,302" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<polygon points="900,302 910,298 910,306" fill="#646A73"/>
-<rect x="1022" y="311.75" width="96" height="19.5" rx="3" fill="#FCFBFF"/>
-<text x="1070" y="326" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">回复逐块流回</text>
-<polyline points="650,401 650,499" fill="none" stroke="#7F3BF5" stroke-width="3" stroke-linejoin="round"/>
-<polygon points="650,510 644.5,498 655.5,498" fill="#7F3BF5"/>
-<polygon points="650,390 655.5,402 644.5,402" fill="#7F3BF5"/>
-<text x="664" y="418" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="700" fill="#7F3BF5" text-anchor="start">用该用户的 OpenViking 密钥</text>
-<text x="664" y="439" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#7F3BF5" text-anchor="start">① 搜索 OpenViking(最多等 2 秒)</text>
-<text x="664" y="460" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#7F3BF5" text-anchor="start">② 保存对话</text>
-<text x="664" y="481" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#7F3BF5" text-anchor="start">③ OpenViking 工具(可选)</text>
-<polyline points="596,510 596,399" fill="none" stroke="#7F3BF5" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 4"/>
-<polygon points="596,390 600,400 592,400" fill="#7F3BF5"/>
-<text x="588" y="440" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#7F3BF5" text-anchor="end">Studio 的</text>
-<text x="588" y="461" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#7F3BF5" text-anchor="end">管理操作</text>
-<circle cx="1400" cy="618" r="12" fill="#FFFFFF" stroke="#646A73" stroke-width="2"/>
-<path d="M 1380 654 Q 1380 634 1400 634 Q 1420 634 1420 654 Z" fill="#FFFFFF" stroke="#646A73" stroke-width="2"/>
-<text x="1400" y="680" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="600" fill="#1F2329" text-anchor="middle">管理员</text>
-<polyline points="1400,692 1400,858 920,858 920,656 909,656" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 4"/>
-<polygon points="900,656 910,652 910,660" fill="#646A73"/>
-<rect x="1220.5" y="869.75" width="249" height="19.5" rx="3" fill="#FFFFFF"/>
-<text x="1345" y="884" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">在 Studio 签发网关密钥、配置上游</text>
-<polyline points="40,951 68,951" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
-<text x="76" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">每次对话都走</text>
-<text x="166" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start"> · </text>
-<polyline points="205,951 233,951" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 4"/>
-<text x="241" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">管理或可选</text>
-<text x="316" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start"> · </text>
-<circle cx="361.0" cy="951" r="6" fill="#FF8800"/>
-<text x="373" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">OpenViking 不可用:对话照常,只是不带记忆</text>
-<text x="692.5" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start"> · </text>
-<circle cx="737.5" cy="951" r="6" fill="#F54A45"/>
-<text x="749.5" y="956" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">网关停机:经过它的模型调用全部失败</text>
+<polyline points="274,715 341,715" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="350,715 340,719 340,711" fill="#646A73"/>
+<rect x="320" y="90" width="890" height="455" rx="14" fill="#FCFBFF" stroke="#B7A3F0" stroke-width="1.5" stroke-dasharray="8 6"/>
+<text x="340" y="122" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#6425D0" text-anchor="start">嵌入 · 网关运行在 OpenViking Server 内</text>
+<text x="340" y="146" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">同一进程、同一端口(:1933)· 用 gateway.enabled 开启</text>
+<rect x="350" y="170" width="170" height="340" rx="10" fill="#F5F6F7" stroke="#8F959E" stroke-width="1.5"/>
+<text x="435" y="204" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#1F2329" text-anchor="middle">Server 端口</text>
+<text x="435" y="227" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="600" fill="#6425D0" text-anchor="middle">:1933</text>
+<text x="435" y="266" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#7F3BF5" text-anchor="middle">网关路径</text>
+<text x="435" y="288" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="700" fill="#1F2329" text-anchor="middle">/gateway/</text>
+<text x="435" y="308" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">模型 API</text>
+<text x="435" y="328" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">工具上传</text>
+<text x="435" y="348" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">管理 API</text>
+<text x="435" y="418" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#646A73" text-anchor="middle">其他路径</text>
+<text x="435" y="440" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#646A73" text-anchor="middle">OpenViking 接口</text>
+<text x="435" y="460" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#646A73" text-anchor="middle">和 Studio</text>
+<polyline points="520,250 561,250" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="570,250 560,254 560,246" fill="#646A73"/>
+<polyline points="520,470 561,470" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 4"/>
+<polygon points="570,470 560,474 560,466" fill="#646A73"/>
+<rect x="570" y="170" width="330" height="170" rx="10" fill="#F3EEFF" stroke="#7F3BF5" stroke-width="2.5"/>
+<text x="590" y="206" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="22" font-weight="700" fill="#1F2329" text-anchor="start">OpenViking 网关</text>
+<rect x="588" y="222" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
+<text x="662.0" y="243.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">召回记忆</text>
+<rect x="748" y="222" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
+<text x="822.0" y="243.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">原样回放</text>
+<rect x="588" y="262" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
+<text x="662.0" y="283.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">保存对话</text>
+<rect x="748" y="262" width="148" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
+<text x="822.0" y="283.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">压缩历史</text>
+<text x="590" y="322" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">可选:执行 OpenViking 工具</text>
+<polyline points="650,352 650,418" fill="none" stroke="#7F3BF5" stroke-width="3" stroke-linejoin="round"/>
+<polygon points="650,430 644.5,418 655.5,418" fill="#7F3BF5"/>
+<polygon points="650,340 655.5,352 644.5,352" fill="#7F3BF5"/>
+<text x="664" y="362" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#7F3BF5" text-anchor="start">本机回环 HTTP,以用户身份、</text>
+<text x="664" y="380.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#7F3BF5" text-anchor="start">使用其本人的 OpenViking 密钥</text>
+<text x="664" y="399" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#7F3BF5" text-anchor="start">① 检索 ≤ 2 秒 · ② 保存 · ③ 工具</text>
+<rect x="570" y="430" width="330" height="90" rx="10" fill="#E6DCFF" stroke="#6425D0" stroke-width="2"/>
+<text x="590" y="460" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="18" font-weight="700" fill="#1F2329" text-anchor="start">OpenViking Server 核心</text>
+<text x="590" y="484" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">检索 · 会话 · 记忆提取</text>
+<text x="590" y="505" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">Studio · 会话和记忆的唯一来源</text>
+<polyline points="900,322 1065,344" fill="none" stroke="#7F3BF5" stroke-width="2" stroke-linejoin="round" stroke-dasharray="2 5"/>
+<ellipse cx="1065.0" cy="516" rx="125.0" ry="16" fill="#FAF8FF" stroke="#7F3BF5" stroke-width="1.5"/>
+<rect x="940" y="362" width="250" height="154" rx="0" fill="#FAF8FF" stroke="none" stroke-width="0"/>
+<line x1="940" y1="362" x2="940" y2="516" stroke="#7F3BF5" stroke-width="1.5"/>
+<line x1="1190" y1="362" x2="1190" y2="516" stroke="#7F3BF5" stroke-width="1.5"/>
+<ellipse cx="1065.0" cy="362" rx="125.0" ry="16" fill="#FFFFFF" stroke="#7F3BF5" stroke-width="1.5"/>
+<text x="1065" y="400" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="middle">网关本地状态</text>
+<text x="1065" y="421" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#646A73" text-anchor="middle">两个 SQLite 文件</text>
+<text x="1065" y="446" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">管理库:上游、密钥、</text>
+<text x="1065" y="465" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">上下文配置、请求日志</text>
+<text x="1065" y="490" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">对话状态库:补充的记忆、</text>
+<text x="1065" y="509" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">摘要、未保存的轮次</text>
+<rect x="320" y="575" width="890" height="440" rx="14" fill="#FCFBFF" stroke="#B7A3F0" stroke-width="1.5" stroke-dasharray="8 6"/>
+<text x="340" y="607" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#6425D0" text-anchor="start">独立 · openviking-gateway 连接已有的 OpenViking</text>
+<text x="340" y="631" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">自己的端口(:1935)和 Studio · 开源版或商业版均可 · 无需修改服务端</text>
+<rect x="350" y="655" width="170" height="200" rx="10" fill="#F5F6F7" stroke="#8F959E" stroke-width="1.5"/>
+<text x="435" y="690" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#1F2329" text-anchor="middle">网关端口</text>
+<text x="435" y="713" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="600" fill="#7F3BF5" text-anchor="middle">:1935</text>
+<text x="435" y="752" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">模型 API、</text>
+<text x="435" y="772" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">上传、</text>
+<text x="435" y="792" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">管理 API</text>
+<text x="435" y="812" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="13" font-weight="400" fill="#1F2329" text-anchor="middle">和 Studio</text>
+<polyline points="520,715 561,715" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="570,715 560,719 560,711" fill="#646A73"/>
+<rect x="570" y="655" width="330" height="150" rx="10" fill="#F3EEFF" stroke="#7F3BF5" stroke-width="2.5"/>
+<text x="590" y="691" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="22" font-weight="700" fill="#1F2329" text-anchor="start">OpenViking 网关</text>
+<rect x="588" y="707" width="294" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
+<text x="735.0" y="728.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">召回、回放、保存、压缩与嵌入相同</text>
+<rect x="588" y="747" width="294" height="32" rx="8" fill="#FFFFFF" stroke="#CDB7FA" stroke-width="1.2"/>
+<text x="735.0" y="768.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="600" fill="#1F2329" text-anchor="middle">Studio:只有网关相关页面</text>
+<polyline points="650,817 650,863" fill="none" stroke="#7F3BF5" stroke-width="3" stroke-linejoin="round"/>
+<polygon points="650,875 644.5,863 655.5,863" fill="#7F3BF5"/>
+<polygon points="650,805 655.5,817 644.5,817" fill="#7F3BF5"/>
+<text x="664" y="832" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#7F3BF5" text-anchor="start">HTTP(S),以用户身份、</text>
+<text x="664" y="851" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="700" fill="#7F3BF5" text-anchor="start">使用其本人的 OpenViking 密钥</text>
+<rect x="570" y="875" width="330" height="110" rx="10" fill="#E6DCFF" stroke="#6425D0" stroke-width="2"/>
+<text x="590" y="905" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="18" font-weight="700" fill="#1F2329" text-anchor="start">已有的 OpenViking 服务</text>
+<text x="590" y="929" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">开源版或 OpenViking 商业版</text>
+<text x="590" y="950" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">服务端配置无需修改</text>
+<text x="590" y="971" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="start">会话和记忆的唯一来源</text>
+<polyline points="900,795 1065,814" fill="none" stroke="#7F3BF5" stroke-width="2" stroke-linejoin="round" stroke-dasharray="2 5"/>
+<ellipse cx="1065.0" cy="960" rx="125.0" ry="16" fill="#FAF8FF" stroke="#7F3BF5" stroke-width="1.5"/>
+<rect x="940" y="830" width="250" height="130" rx="0" fill="#FAF8FF" stroke="none" stroke-width="0"/>
+<line x1="940" y1="830" x2="940" y2="960" stroke="#7F3BF5" stroke-width="1.5"/>
+<line x1="1190" y1="830" x2="1190" y2="960" stroke="#7F3BF5" stroke-width="1.5"/>
+<ellipse cx="1065.0" cy="830" rx="125.0" ry="16" fill="#FFFFFF" stroke="#7F3BF5" stroke-width="1.5"/>
+<text x="1065" y="868" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="700" fill="#1F2329" text-anchor="middle">网关本地状态</text>
+<text x="1065" y="896" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">同样两个 SQLite 文件,</text>
+<text x="1065" y="915" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="14" font-weight="400" fill="#1F2329" text-anchor="middle">和网关在同一台主机上</text>
+<text x="1260" y="142" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="17" font-weight="700" fill="#FF8800" text-anchor="start">上游模型服务商</text>
+<rect x="1260" y="160" width="300" height="620" rx="10" fill="#FFF3E8" stroke="#FF8800" stroke-width="1.5"/>
+<text x="1410" y="420" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">Anthropic · OpenAI · DeepSeek</text>
+<text x="1410" y="450" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">火山方舟</text>
+<text x="1410" y="480" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">BytePlus ModelArk</text>
+<text x="1410" y="510" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="16" font-weight="400" fill="#1F2329" text-anchor="middle">兼容的自建 API</text>
+<text x="1260" y="808" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">能看到完整的模型输入,</text>
+<text x="1260" y="830" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">包括补充的记忆</text>
+<polyline points="900,200 1251,200" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="1260,200 1250,204 1250,196" fill="#646A73"/>
+<rect x="969.6" y="176" width="220.8" height="21" rx="3" fill="#FCFBFF" stroke="#FCFBFF" stroke-width="0"/>
+<text x="1080" y="192" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">同一种 API:原始请求 + 记忆</text>
+<polyline points="1260,290 909,290" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="900,290 910,286 910,294" fill="#646A73"/>
+<rect x="1029.0" y="300" width="102" height="21" rx="3" fill="#FCFBFF" stroke="#FCFBFF" stroke-width="0"/>
+<text x="1080" y="316" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">回复流式返回</text>
+<polyline points="900,680 1251,680" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="1260,680 1250,684 1250,676" fill="#646A73"/>
+<rect x="969.6" y="656" width="220.8" height="21" rx="3" fill="#FCFBFF" stroke="#FCFBFF" stroke-width="0"/>
+<text x="1080" y="672" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">同一种 API:原始请求 + 记忆</text>
+<polyline points="1260,750 909,750" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<polygon points="900,750 910,746 910,754" fill="#646A73"/>
+<rect x="1029.0" y="760" width="102" height="21" rx="3" fill="#FCFBFF" stroke="#FCFBFF" stroke-width="0"/>
+<text x="1080" y="776" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#1F2329" text-anchor="middle">回复流式返回</text>
+<polyline points="40,1056 68,1056" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round"/>
+<text x="76" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">每个请求</text>
+<text x="146" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start"> · </text>
+<polyline points="172,1056 200,1056" fill="none" stroke="#646A73" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 4"/>
+<text x="208" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">其他 OpenViking 流量</text>
+<text x="371.59999999999997" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start"> · </text>
+<circle cx="403.59999999999997" cy="1056" r="6" fill="#FF8800"/>
+<text x="415.59999999999997" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">OpenViking 不可用:对话继续,只是没有记忆</text>
+<text x="736.3999999999999" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start"> · </text>
+<circle cx="768.3999999999999" cy="1056" r="6" fill="#F54A45"/>
+<text x="780.3999999999999" y="1061" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', 'Noto Sans CJK SC', sans-serif" font-size="15" font-weight="400" fill="#646A73" text-anchor="start">网关不可用:经过它的模型调用全部失败</text>
</svg>
diff --git a/docs/scripts/check-api-reference.mjs b/docs/scripts/check-api-reference.mjs
index d83dcb212..62900f54b 100644
--- a/docs/scripts/check-api-reference.mjs
+++ b/docs/scripts/check-api-reference.mjs
@@ -83,19 +83,37 @@ const internalRouterFiles = new Set([
'stats.py',
'user_settings.py',
])
-for (const file of fs.readdirSync(routerDir).filter((name) => name.endsWith('.py'))) {
- if (internalRouterFiles.has(file)) continue
- const source = fs.readFileSync(path.join(routerDir, file), 'utf8')
+const routerFiles = fs.readdirSync(routerDir)
+ .filter((name) => name.endsWith('.py') && !internalRouterFiles.has(name))
+ .map((name) => path.join(routerDir, name))
+// Gateway management is a public API owned by its ASGI application, including
+// when that application is embedded in the server.
+const gatewayManagement = path.join(repoRoot, 'openviking_gateway/management.py')
+routerFiles.push(gatewayManagement)
+// Both hosts mount the gateway application at MOUNT_PATH.
+const gatewayMount = fs
+ .readFileSync(path.join(repoRoot, 'openviking_gateway/config.py'), 'utf8')
+ .match(/^MOUNT_PATH\s*=\s*["']([^"']+)["']/m)[1]
+for (const routerFile of routerFiles) {
+ const file = path.basename(routerFile)
+ const isGateway = routerFile === gatewayManagement
+ const source = fs.readFileSync(routerFile, 'utf8')
+ const prefixConstant = source.match(/^PREFIX\s*=\s*["']([^"']+)["']/m)?.[1]
const routerPrefix =
- source.match(/router\s*=\s*APIRouter\([^)]*prefix=["']([^"']+)/s)?.[1] ?? ''
- const mountPrefix = file === 'bot.py' ? '/bot/v1' : ''
+ source.match(/router\s*=\s*APIRouter\([^)]*prefix=["']([^"']+)/s)?.[1] ??
+ (source.match(/router\s*=\s*APIRouter\([^)]*prefix=PREFIX\b/s) ? prefixConstant : '') ?? ''
+ const mountPrefix = file === 'bot.py' ? '/bot/v1' : isGateway ? gatewayMount : ''
+ // Gateway upstreams and policies share the handlers that object_routes(kind) registers.
+ const objectKinds = Array.from(source.matchAll(/object_routes\(\s*["']([^"']+)["']/g),
+ (match) => match[1])
const decorators = [
...Array.from(
- source.matchAll(/@router\.(get|post|put|patch|delete)\(\s*["']([^"']*)/g),
+ source.matchAll(/@router\.(get|post|put|patch|delete)\(\s*f?["']([^"']*)/g),
(match) => ({
index: match.index,
methods: [match[1].toUpperCase()],
- path: match[2],
+ // Unescape f-string braces.
+ path: match[2].replaceAll('{{', '{').replaceAll('}}', '}'),
sourceLength: match[0].length,
})
),
@@ -137,8 +155,20 @@ for (const file of fs.readdirSync(routerDir).filter((name) => name.endsWith('.py
) continue
query.set(defaultMatch[1], false)
}
- for (const method of decorator.methods) {
- routes.set(`${method} ${normalizePath(routePath)}`, { query, pathParameters })
+ // The caller dependency consumes account_id directly from query_params.
+ if (isGateway) query.set('account_id', false)
+ const concretePaths = routePath.includes('{kind}')
+ ? objectKinds.map((kind) => routePath.replace('{kind}', kind))
+ : [routePath]
+ for (const concretePath of concretePaths) {
+ const concreteParameters = new Set(
+ Array.from(concretePath.matchAll(/\{([^}:]+)(?::[^}]+)?\}/g), (item) => item[1])
+ )
+ for (const method of decorator.methods) {
+ routes.set(`${method} ${normalizePath(concretePath)}`, {
+ query, pathParameters: concreteParameters,
+ })
+ }
}
}
}
diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.md
index 8e278afd1..00e917525 100644
--- a/docs/zh/api/01-overview.md
+++ b/docs/zh/api/01-overview.md
@@ -525,12 +525,29 @@ JSON 输出 - 错误:
### [OpenViking 网关管理](25-gateway.md)
+网关在 Server 内运行时,从 Server 端口访问;独立运行时,从网关自己的端口访问。OpenViking API 密钥决定调用方能访问哪个账号;部署者设置了网关管理密钥时,修改上游和上下文配置还需要这把密钥。每个用户都能给自己签发网关密钥。权限矩阵和错误原因见[网关管理 API](25-gateway.md)。
+
| 方法 | 路径 | 说明 |
|------|------|------|
-| GET | `/api/v1/admin/gateway/{path}` | 读取调用方账号的网关概览、日志、上游、上下文配置、密钥或工具 |
-| POST | `/api/v1/admin/gateway/{path}` | 签发网关密钥、测试上游或重置对话保存 |
-| PUT | `/api/v1/admin/gateway/{path}` | 创建或替换上游、上下文配置 |
-| DELETE | `/api/v1/admin/gateway/{path}` | 删除上游或上下文配置、吊销密钥或删除用户的网关数据 |
+| GET | `/gateway/admin/access` | 读取调用方的权限和部署告警 |
+| GET | `/gateway/admin/guides` | 读取客户端使用的网关地址 |
+| GET | `/gateway/admin/tools` | 列出调用方可用的 OpenViking 工具 |
+| GET | `/gateway/admin/upstreams/{identifier}` | 读取单个上游 |
+| GET | `/gateway/admin/policies/{identifier}` | 读取单个上下文配置 |
+| GET | `/gateway/admin/keys/{identifier}` | 读取单个网关密钥(不含密钥本身) |
+| GET | `/gateway/admin/overview` | 读取调用方可见范围内的用量概览 |
+| GET | `/gateway/admin/logs` | 读取调用方可见的请求日志 |
+| GET | `/gateway/admin/upstreams` | 列出本账号的上游 |
+| PUT / DELETE | `/gateway/admin/upstreams/{identifier}` | 创建/替换或删除上游 |
+| POST | `/gateway/admin/upstreams/{identifier}/test` | 测试上游连接 |
+| POST | `/gateway/admin/upstreams/import-vlm` | 把 Server 的 VLM 配置导入为上游(仅嵌入部署) |
+| GET | `/gateway/admin/policies` | 列出本账号的上下文配置 |
+| PUT / DELETE | `/gateway/admin/policies/{identifier}` | 创建/替换或删除上下文配置 |
+| GET / POST | `/gateway/admin/keys` | 列出调用方可见的网关密钥,或签发新密钥 |
+| DELETE | `/gateway/admin/keys/{identifier}` | 吊销网关密钥 |
+| POST | `/gateway/admin/keys/{identifier}/capture/reset` | 让一段对话重新开始保存 |
+| DELETE | `/gateway/admin/users/{user_id}/data` | admin 或 root:删除某个用户的网关数据 |
+| DELETE | `/gateway/admin/account/data` | root:删除整个账号的网关数据 |
### [OpenViking Assets](22-openviking-assets.md)、[WebDAV](20-webdav.md)、[Agent Runtime API](23-agent-runtime.md) 与 [VikingBot API](24-vikingbot.md)
diff --git a/docs/zh/api/25-gateway.md b/docs/zh/api/25-gateway.md
index 0bae8ac0f..966aef916 100644
--- a/docs/zh/api/25-gateway.md
+++ b/docs/zh/api/25-gateway.md
@@ -1,215 +1,222 @@
# OpenViking 网关管理 API
-OpenViking Server 在 `/api/v1/admin/gateway` 下转发 OpenViking 网关的管理请求。Studio 的网关页面通过这些端点管理上游、上下文配置和网关密钥,并读取请求日志。模型请求不走这组 API,客户端直接发到网关自己的端口(见[OpenViking 网关](../guides/15-gateway.md))。
+管理 API 用来查看权限、配置上游和上下文配置、签发网关密钥、读取用量和日志。所有路径都以 `/gateway/admin/` 开头,由网关直接提供:网关在 OpenViking Server 内运行时,访问 Server 的端口(默认 1933);独立运行时,访问网关自己的端口(默认 1935)。示例中的 `SERVER_URL` 指这个地址本身,不带路径,例如 `http://127.0.0.1:1933`。
-**前提条件**:
+模型客户端不调用这组接口。它们用网关密钥访问 `/gateway/v1/*`、`/gateway/api/v3/*` 或 `/gateway/api/compatible/v1/*`,见[OpenViking 网关](../guides/15-gateway.md#接入客户端)。
-- `ov.conf` 中 `gateway.enabled` 为 `true`,并且网关进程可以通过 `gateway.url` 访问。
-- OpenViking Server 和网关使用同一个管理令牌(默认读取 `OPENVIKING_GATEWAY_ADMIN_TOKEN`,至少 32 个字符)。
-- 调用方使用 ADMIN 密钥或 root 密钥。USER 密钥返回 `403`。
+## 凭证和账号范围
-**代码入口**:
+每个管理请求都要带 OpenViking API 密钥,放在 `X-API-Key` 或 `Authorization: Bearer` 中。网关向 OpenViking 确认这把密钥属于哪个账号、哪个用户、什么角色,确认结果最多缓存 30 秒。本地 dev 模式不需要密钥,调用方固定为 root 身份 `default/default`。网关不支持 trusted 认证。
-- `openviking/server/routers/gateway.py` - OpenViking Server 代理、角色检查和账号隔离
-- `openviking_gateway/app.py` - 网关管理路由
-- `openviking_gateway/models.py` - 上游、上下文配置和密钥模型
+上游和上下文配置(API 中叫 `policies`)属于账号,同一账号的用户共用。请求默认作用于调用方所在的账号;root 可以用 query 参数 `account_id` 指定其他账号,admin 和 user 只能访问自己的账号。
-## 代理方式
+部署者可以另外设置网关管理密钥(配置方法见[网关管理密钥](../guides/22-gateway-operations.md#网关管理密钥))。设置之后,修改上游和上下文配置的请求必须在 `X-OpenViking-Gateway-Management-Key` 中带上它,OpenViking 的 admin 和 root 也不例外。请求带了管理密钥但值不对时,网关直接返回 401 `management_key_invalid`,不会降级成只读请求。
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET / POST / PUT / DELETE | `/api/v1/admin/gateway/{path}` | 以调用方账号转发到 `{gateway.url}/admin/{path}` |
-
-发往 `/api/v1/admin/gateway/{path}` 的请求会以相同的方法、查询参数和请求体转发到 `{gateway.url}/admin/{path}`。OpenViking Server 用管理令牌替换调用方的凭据,并把 `X-OpenViking-Account` 设为调用方所在的账号,因此每次调用只能读取和修改本账号的网关对象。账号管理员访问不到其他账号的数据,调用方也无法指定转发目标。
-
-只有第一段路径是 `overview`、`logs`、`guides`、`upstreams`、`policies`、`keys`、`users` 或 `tools` 的请求会被转发。其他路径以及包含 `..` 的路径返回 `404`。网关返回的状态码和响应体原样返回给调用方。
+| 操作 | 未设置管理密钥 | 已设置管理密钥 |
+| --- | --- | --- |
+| 读取上游和上下文配置、测试上游 | 本账号的任何用户 | 本账号的任何用户;单独持有管理密钥也可以,并能指定任意账号 |
+| 创建、修改、删除上游或上下文配置 | 本账号的任何用户 | 只有带正确管理密钥的请求 |
+| 导入 OpenViking 的模型配置 | 嵌入部署中的 root(包括本地 dev) | 只有带正确管理密钥的请求,且只限嵌入部署 |
+| 签发、读取、吊销网关密钥,重置保存 | user 只能操作自己的密钥;admin 操作本账号;root 操作所选账号 | 同左,管理密钥不增加任何权限 |
+| 读取日志和概览 | user 只看自己的;admin 和 root 看整个账号 | 同左,始终需要 OpenViking 身份 |
+| 删除某个用户的网关数据 | 本账号的 admin,或 root | 同左 |
+| 删除整个账号的网关数据 | root | 同左 |
-## API 参考
+管理密钥可以不带 OpenViking API 密钥单独使用,适合自动化脚本:它能读写上游和上下文配置、调用 `/access`,用 `account_id` 指定账号(省略时为 `default`)。签发密钥、读取日志和概览始终需要 OpenViking 身份;两种凭证同时提供,也不会让这些操作获得更高的权限。设置、更换或去掉管理密钥都不影响已签发的网关密钥。
-表格中的路径都相对于 `/api/v1/admin/gateway/`。管理 API 把上下文配置称为 `policies`。
+只读视图不返回上游的 API Key、请求头的值和请求头名称,只保留 `has_api_key` 和 `auth_mode`。
-### 概览和日志
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | `overview` | 根据最近 10,000 条日志汇总用量:请求数、输出 token、首次调用和续写的缓存命中率、降级、召回统计和保存异常,另附 OpenViking 健康状态和 `log_retention_days` |
-| GET | `logs?limit=200` | 最新的请求日志;`limit` 取 1–1000,默认 200 |
-| GET | `guides` | 客户端应使用的地址:`base_url` 和 `public_url_configured` |
-| GET | `tools` | 上下文配置可以提供的 OpenViking 工具:`name`、`description`,以及存在时的 `annotations` |
+## 权限与发现
-`tools` 借用本账号某个网关密钥绑定的 OpenViking 密钥读取工具列表。账号里还没有网关密钥时返回空列表;用哪个密钥都读不到时返回错误。
+| 方法 | 路径 | 返回 |
+| --- | --- | --- |
+| GET | `/gateway/admin/access` | 调用方的权限:`managed`、`can_write_objects`、`can_import_vlm`、`can_issue_for_others`、`role`、`account_id`、`user_id`、`warnings` |
+| GET | `/gateway/admin/overview` | 调用方可见的最近 10,000 条日志汇总:用量、缓存命中、召回、保存异常、OpenViking 状态和日志保留期 |
+| GET | `/gateway/admin/logs` | 调用方可见的最新日志;`limit` 默认 200,取值 1–1000 |
+| GET | `/gateway/admin/guides` | 客户端接入地址 `base_url`,以及 `public_url_configured`;`base_url` 是 `public_url` 加 `/gateway`,未设置 `public_url` 时取请求的来源地址加 `/gateway` |
+| GET | `/gateway/admin/tools` | 调用方能用的 OpenViking 工具:名称、描述和 annotations,用调用方自己的 OpenViking 密钥读取(OpenViking 拒绝 root 访问 `/mcp`,所以 root 改用本账号已签发网关密钥对应的 OpenViking 密钥,没有时返回上次读到的目录) |
-**HTTP API**
+Studio 只根据 `/access` 决定显示哪些按钮,自己写的管理工具也应这样做。独立网关连接公共 OpenViking 服务且没有设置管理密钥时,`warnings` 中会出现 `public_openviking_without_management_key`。它只是告警,不限制任何操作。
```bash
-curl http://localhost:1933/api/v1/admin/gateway/overview \
- -H "X-API-Key: your-admin-key"
+curl "$SERVER_URL/gateway/admin/access" \
+ -H "X-API-Key: $OPENVIKING_API_KEY"
```
-**响应示例**
-
```json
{
- "requests": 128,
- "last_request_at": 1785000000.0,
- "output_tokens": 45210,
- "cache": {
- "first_call": {"requests": 40, "input_tokens": 320000, "cached_tokens": 250000, "cache_hit_ratio": 0.78},
- "continuation": {"requests": 88, "input_tokens": 910000, "cached_tokens": 860000, "cache_hit_ratio": 0.95}
- },
- "degradations": {},
- "recall_count": 96,
- "recall_requests": 40,
- "recall_ms": 182.5,
- "capture_issues": {"retrying": 0, "paused": 0},
- "sample_limit": 10000,
- "openviking": {"status": "ok", "healthy": true, "version": "0.4.16", "auth_mode": "api_key"},
- "log_retention_days": 30
+ "managed": true,
+ "can_write_objects": false,
+ "can_import_vlm": false,
+ "can_issue_for_others": true,
+ "role": "admin",
+ "account_id": "team",
+ "user_id": "alice",
+ "warnings": []
}
```
-### 上游和上下文配置
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | `upstreams` | 列出上游 |
-| PUT | `upstreams/{upstream_id}` | 创建或替换上游 |
-| DELETE | `upstreams/{upstream_id}` | 删除上游 |
-| POST | `upstreams/{upstream_id}/test` | 检查网关能否访问服务商的模型列表 |
-| GET | `policies` | 列出上下文配置 |
-| PUT | `policies/{policy_id}` | 创建或替换上下文配置 |
-| DELETE | `policies/{policy_id}` | 删除上下文配置 |
-
-`upstream_id` 和 `policy_id` 由调用方指定。`PUT` 的请求体是完整对象,未知字段会被拒绝。各字段的默认值和取值范围见[配置参考](../guides/22-gateway-operations.md#配置参考)中的上游设置和上下文配置设置。
-
-上游的 `api_key` 和 `headers` 的值只写不读,响应中分别换成 `has_api_key` 和 `header_names`。`PUT` 时 `api_key` 留空会保留已存的密钥;省略 `headers` 会保留所有已存的请求头,某个请求头的值留空则保留这个名字已存的值。
+OpenViking 拒绝 API 密钥时,返回 401 `openviking_http_401`。
-如果还有网关密钥在用某个上游或上下文配置,删除它会返回 `409`,需要先吊销或更新这些密钥。
+## 上游和上下文配置
-**HTTP API**
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/gateway/admin/upstreams` | 列出上游 |
+| GET | `/gateway/admin/upstreams/{identifier}` | 读取单个上游 |
+| PUT | `/gateway/admin/upstreams/{identifier}` | 创建或替换上游 |
+| DELETE | `/gateway/admin/upstreams/{identifier}` | 删除没有密钥在用的上游 |
+| POST | `/gateway/admin/upstreams/{identifier}/test` | 测试上游连接 |
+| POST | `/gateway/admin/upstreams/import-vlm` | 导入 OpenViking 的模型配置 |
+| GET | `/gateway/admin/policies` | 列出上下文配置 |
+| GET | `/gateway/admin/policies/{identifier}` | 读取单个上下文配置 |
+| PUT | `/gateway/admin/policies/{identifier}` | 创建或替换上下文配置 |
+| DELETE | `/gateway/admin/policies/{identifier}` | 删除没有密钥在用的上下文配置 |
+
+ID 由调用方指定。`PUT` 提交完整对象,未知字段会导致校验失败。各字段的含义、默认值和取值范围见[配置参考](../guides/22-gateway-operations.md#配置参考)。
+
+上游的 `api_key` 和 `headers` 只写不读:
+
+- `base_url` 不变时,`api_key` 留空或省略就保留已存的密钥;省略 `headers` 保留全部已存请求头;提交 `headers` 对象则替换整个集合,其中值为空的项沿用这个名称已存的值。
+- **修改 `base_url` 会清除已存的 API Key 和全部请求头值。** 新地址需要的凭证要随这次请求重新提交,这样已存的密钥不会被发往另一个地址。
+- 可编辑视图返回 `has_api_key` 和 `header_names`,不返回值。
```bash
-curl http://localhost:1933/api/v1/admin/gateway/upstreams \
- -H "X-API-Key: your-admin-key"
+curl -X PUT "$SERVER_URL/gateway/admin/upstreams/openai?account_id=team" \
+ -H "X-OpenViking-Gateway-Management-Key: $GATEWAY_MANAGEMENT_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"name":"OpenAI","protocol":"chat","base_url":"https://api.openai.com/v1","api_key":"<provider-key>"}'
```
-**响应示例**
+删除仍有网关密钥在用的对象,返回 409 `in_use` 和 `key_count`。先吊销这些密钥;只是想让请求立即停止发往某个上游,可以停用它而不删除。
-```json
-[
- {
- "id": "openai",
- "revision": 2,
- "name": "OpenAI",
- "protocol": "chat",
- "vendor": "openai",
- "base_url": "https://api.openai.com/v1",
- "auth_mode": "managed",
- "has_api_key": true,
- "header_names": [],
- "models": ["gpt-5"],
- "aliases": {},
- "context_windows": {},
- "priority": 0,
- "enabled": true,
- "allow_gateway_tools": true,
- "coding_plan": false,
- "allow_coding_plan": false,
- "cache_min_tokens": 1024
- }
-]
-```
+### 连接测试
-`upstreams/{upstream_id}/test` 返回 `{"ok": true, "status": 200}`,其中 `status` 是服务商返回的状态码;如果 10 秒内连不上服务商,返回 `{"ok": false, "reason": "upstream_unavailable"}`。
+`POST /gateway/admin/upstreams/{identifier}/test` 用已存的凭证请求服务商的模型列表,超时 10 秒,返回 `{ok, status, reason, url}`;没有收到响应时不含 `status`。只读调用方也能使用。Anthropic 上游同时在 `x-api-key` 和 `Authorization: Bearer` 中发送密钥,Chat Completions 和 Responses 上游只发送 Bearer。
-### 网关密钥
+| 服务商的响应 | `reason` | `ok` |
+| --- | --- | --- |
+| 没有可用的 API Key:没有保存,或者上游要求每个客户端自带。网关不发请求。 | `upstream_key_missing` | `false` |
+| 2xx,响应体带 `data` 数组 | `passed` | `true` |
+| 2xx 但响应体表示失败,或者 401、403 | `upstream_key_rejected` | `false` |
+| 404、405:地址可达,但服务商不提供模型列表,密钥没有得到验证 | `models_unavailable` | `true` |
+| 429:地址可达 | `rate_limited` | `true` |
+| 网络错误或 5xx | `upstream_unavailable` | `false` |
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | `keys` | 列出网关密钥,不含密钥本身 |
-| POST | `keys` | 签发网关密钥;密钥只在这次响应中出现 |
-| DELETE | `keys/{key_id}` | 吊销网关密钥 |
-| POST | `keys/{key_id}/capture/reset` | 让某个会话的对话保存从下一次请求起重新同步 |
+测试通过只说明地址和密钥可用,不代表某个具体模型可用,也不代表上游允许使用 Coding Plan。
+
+### 导入 VLM 配置
+
+`POST /gateway/admin/upstreams/import-vlm` 把 OpenViking Server 的 VLM 凭证导入为所选账号的上游,只在嵌入部署中可用;独立网关返回 404 `vlm_import_unavailable`。
-`POST keys` 的请求体:
+每个导入的上游 ID 固定为 `vlm-<credential id>`,重复导入不会产生重复的上游。再次导入时,来自服务端的字段(`base_url`、`api_key`、`headers`、`protocol`、`vendor`、`coding_plan`)按服务端配置刷新,其他字段保留在网关里改过的值,包括 `name`、`enabled`、`priority`、`models`、`aliases`、`context_windows` 和 `allow_coding_plan`。路径中含 `coding` 或 `plan` 段的上游会被标为 Coding Plan,在设置 `allow_coding_plan` 之前归入 `needs_confirmation`。
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `name` | string | 是 | 显示名称 |
-| `openviking_key` | string | 条件必填 | 网关密钥代表的用户的 OpenViking 密钥;与 `user_id` 二选一 |
-| `user_id` | string | 条件必填 | 调用方账号中的用户,由 OpenViking Server 读取这个用户的密钥;仅账号管理员可用 |
-| `policy_id` | string | 是 | 上下文配置 |
-| `upstream_ids` | string[] | 是 | 至少一个上游 |
-| `models` | string[] | 否 | 允许的模型;为空时允许上游提供的所有模型 |
+```json
+{
+ "imported": [{"id": "vlm-default", "name": "default"}],
+ "needs_confirmation": [{"id": "vlm-coding", "name": "coding"}],
+ "skipped": [{"id": "vlm-codex", "reason": "openai_codex"}]
+}
+```
-OpenViking 密钥必须属于调用方账号中的 USER 或 ADMIN。只有 OpenViking Server 能读出已存的用户密钥时,`user_id` 才可用;启用了密钥哈希时改传 `openviking_key`。root 调用方也必须传 `openviking_key`,因为 root 密钥解析出的账号可能和 Studio 显示的账号不同。
+| 跳过原因 `reason` | 说明 |
+| --- | --- |
+| `openai_codex` | Codex OAuth 令牌会定期刷新,网关无法长期使用。 |
+| `azure` | Azure OpenAI 需要 `api-version` 参数,网关不发送它。 |
+| `litellm_no_api_base` | LiteLLM 凭证没有 `api_base`。在 OpenViking 配置中补上后重新导入。 |
+| `litellm_unsupported_route` | LiteLLM 路由不使用 OpenAI Chat Completions API,例如 `gemini/`、`bedrock/` 或 `vertex_ai/`。请手动把这个服务商添加为上游。 |
+| `invalid_configuration` | 凭证构不成有效的上游,例如 base URL 无效。 |
-已签发的密钥不能修改,`PUT keys/{key_id}` 返回 `405`。需要修改时签发一个新密钥,再吊销旧密钥。
+## 网关密钥
-**HTTP API**
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/gateway/admin/keys` | 列出调用方可见的密钥,不含密钥本身 |
+| GET | `/gateway/admin/keys/{identifier}` | 读取单个可见密钥 |
+| POST | `/gateway/admin/keys` | 签发密钥,响应中的 `key` 是唯一一次返回的完整密钥 |
+| DELETE | `/gateway/admin/keys/{identifier}` | 吊销密钥,保留用户数据 |
+| POST | `/gateway/admin/keys/{identifier}/capture/reset` | 让一段对话重新开始保存 |
+| DELETE | `/gateway/admin/users/{user_id}/data` | admin 或 root:吊销该用户的全部密钥,删除其对话状态和日志 |
+| DELETE | `/gateway/admin/account/data` | root:删除账号的全部网关对象、密钥、对话状态和日志 |
+
+签发请求体:
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `name` | 是 | 显示名称。 |
+| `policy_id` | 是 | 使用的上下文配置。 |
+| `upstream_ids` | 是 | 可用的上游,至少一个。 |
+| `models` | 否 | 允许的模型名(客户端发送的名称,包括别名);空列表表示不限。 |
+| `user_id` | 否 | 密钥归属的 OpenViking 用户,默认是调用方自己。root 不是账号里的用户,必须指定用户(或提供 `openviking_key`)。user 只能填自己。 |
+| `openviking_key` | 否 | 该用户的 OpenViking API 密钥。通常不用填,见下文。 |
+
+网关需要拿到目标用户的 OpenViking API 密钥,之后以这个用户的身份检索和保存记忆:
+
+- 给自己签发时,直接使用调用方的密钥(user 或 admin)。
+- admin 或 root 给别人签发时,网关用调用方的凭证向 OpenViking 读取该用户的密钥。OpenViking 只保存密钥哈希时读不出来,返回 409 `user_key_unreadable`,这时要在 `openviking_key` 中提供该用户的密钥。
+- 网关会向 OpenViking 核实这把密钥:它必须属于所选账号;提供了 `user_id` 时,还必须属于这个用户。
+- root API 密钥不能绑定到网关密钥,本地 dev 的 `default/default` 例外。
```bash
-curl -X POST http://localhost:1933/api/v1/admin/gateway/keys \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-admin-key" \
- -d '{"name":"alice laptop","user_id":"alice","policy_id":"default","upstream_ids":["openai"]}'
+curl -X POST "$SERVER_URL/gateway/admin/keys?account_id=team" \
+ -H "X-API-Key: $OPENVIKING_API_KEY" -H "Content-Type: application/json" \
+ -d '{"name":"Alice laptop","user_id":"alice","policy_id":"default","upstream_ids":["openai"]}'
```
-**响应示例**
-
```json
{
- "id": "3f6c…",
- "revision": 1,
- "name": "alice laptop",
+ "id": "3f9c…",
+ "name": "Alice laptop",
+ "user_id": "alice",
"policy_id": "default",
"upstream_ids": ["openai"],
"models": [],
- "user_id": "alice",
- "prefix": "ovgw_Xk3p9Q",
- "created_at": 1785000000.0,
- "key": "ovgw_Xk3p9Q…"
+ "prefix": "ovgw_Xk2pQ7a",
+ "created_at": 1760000000.0,
+ "revision": 1,
+ "key": "ovgw_Xk2pQ7a…"
}
```
-`keys/{key_id}/capture/reset` 的请求体是 `{"session": "<会话>", "protocol": "chat"}`,`protocol` 取 `anthropic`、`chat` 或 `responses`。`session` 可以填客户端发送的会话请求头的值(例如 `X-OpenViking-Session`),也可以填请求日志里的 `session` 字段;没有会话请求头的会话只能用后者。成功时返回 `{"status": "ready", "message": "…"}`;密钥或会话不存在时返回 `404`。
+立即保存响应中的 `key`,网关只保留它的哈希。`GET` 返回同样的字段,但没有 `key`。网关密钥不能修改,没有对应的 `PUT`;要换上下文配置、上游、模型或用户,就签发新密钥,再吊销旧的。
-### 用户数据
+用户的 OpenViking API 密钥重新生成或用户被删除后,绑定它的网关密钥会失效并被删除,用户数据保留,见[网关密钥](../guides/22-gateway-operations.md#网关密钥)。
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| DELETE | `users/{user_id}/data` | 吊销用户的所有网关密钥,并删除网关中这个用户的对话状态 |
+**重置保存。** 请求体为 `{"session":"<会话请求头的值或日志中的 session>","protocol":"chat"}`,`protocol` 取 `chat`、`anthropic` 或 `responses`。成功返回 `{"status":"ready","message":"…"}`,网关会在这段对话的下一个请求里,把完整历史写入一个新的 OpenViking 会话。找不到这段对话时返回 404 `not_found`。
-已经保存到 OpenViking 的会话不受影响。
+**删除数据。** 两个删除接口会清掉网关里尚未保存的对话内容和日志,不影响已经存入 OpenViking 的会话和记忆。保留期和其他删除途径见[安全与数据](../guides/22-gateway-operations.md#安全与数据)。
## 错误
-OpenViking Server 自身产生的错误使用标准错误响应格式:
-
-| 状态码 | 错误码 | 原因 |
-|--------|--------|------|
-| 400 | `INVALID_ARGUMENT` | root 在 `POST keys` 中传了 `user_id`;`user_id` 不存在 |
-| 400 | `INVALID_ARGUMENT` | `POST keys` 同时传了 `user_id` 和 `openviking_key`(原始状态码 422) |
-| 403 | `PERMISSION_DENIED` | 调用方不是 ROOT 或 ADMIN |
-| 404 | `NOT_FOUND` | 路径不在转发范围内 |
-| 409 | `CONFLICT` | 服务端读不出所选用户的密钥 |
-| 503 | `UNAVAILABLE` | OpenViking 网关未启用、管理令牌未配置,或连不上网关(原始状态码 502) |
-
-网关返回的错误保留网关的状态码,响应体形如 `{"detail": "Unknown context policy"}`:
+管理接口的错误响应带稳定的顶层 `reason`,以及一句简短的英文说明 `detail`;部分错误另有附加字段,例如:
-| 状态码 | 原因 |
-|--------|------|
-| 400 | `POST keys` 指定的上下文配置或上游不存在 |
-| 403 | OpenViking 密钥属于其他账号 |
-| 404 | 资源、密钥或会话不存在 |
-| 405 | 调用了 `PUT keys/{key_id}` |
-| 409 | 删除仍被密钥使用的上游或上下文配置 |
-| 422 | 请求体无效。提交的值可能包含密钥,所以错误信息不会回显它们 |
-
-网关无法验证 OpenViking 密钥时,响应体是 `{"error": {"message": "<原因>"}}`,原因值见[签发密钥失败](../guides/22-gateway-operations.md#签发密钥失败)。
-
-## 相关文档
+```json
+{"reason": "in_use", "detail": "Gateway keys still use this object; revoke them first.", "key_count": 2}
+```
-- [OpenViking 网关](../guides/15-gateway.md) - 网关的工作方式和客户端接入
-- [OpenViking 网关部署与运维](../guides/22-gateway-operations.md) - 部署、在 Studio 中管理网关和配置参考
-- [管理员](08-admin.md) - 账号、用户和角色
+请按 `reason` 判断,不要匹配 `detail` 文本。服务端没有开启网关时,这组路径不存在,返回 404;Studio 把这种情况显示为 `not_enabled`。
+
+| HTTP | `reason` | 含义和处理 |
+| --- | --- | --- |
+| 401 | `management_key_invalid` | 管理密钥不正确。向部署者确认当前的管理密钥。 |
+| 403 | `management_key_required` | 已设置管理密钥,修改上游或上下文配置时必须带上它。 |
+| 401 | `openviking_http_401` | OpenViking 拒绝了 API 密钥。换用当前有效的密钥。 |
+| 401 | `openviking_identity_missing` | OpenViking 没有返回这把密钥对应的用户。 |
+| 403 | `trusted_mode_unsupported` | OpenViking 使用 trusted 认证。改用 `api_key` 认证。 |
+| 403 | `other_account` | 密钥或请求的账号不在调用方的权限范围内。 |
+| 403 | `forbidden` | 操作超出调用方的角色或用户范围。 |
+| 403 | `root_key_not_allowed` | root API 密钥不能绑定到网关密钥。改用某个用户的 API 密钥。 |
+| 409 | `user_key_unreadable` | OpenViking 只保存了该用户密钥的哈希。在 `openviking_key` 中提供该用户的密钥。 |
+| 409 | `in_use` | 还有 `key_count` 个网关密钥在用这个对象。 |
+| 400 | `unknown_user`、`unknown_policy`、`unknown_upstream` | 指定的用户、上下文配置或上游不存在。 |
+| 400 | `user_required` | root 签发密钥时没有提供 `user_id` 或 `openviking_key`。指定密钥归属的用户。 |
+| 404 | `not_found` | 对象不存在,或者调用方看不到它。 |
+| 422 | `invalid_configuration` | 请求体或 Base URL 不合法。错误信息不会回显提交的凭证。 |
+| 403 | `vlm_import_forbidden` | 调用方没有导入权限,以 `/access` 的 `can_import_vlm` 为准。 |
+| 404 | `vlm_import_unavailable` | 独立网关读不到服务端的模型配置,请手动添加上游。 |
+| 503 | `openviking_unavailable`、`openviking_unreachable` | 网关连不上 OpenViking。检查 OpenViking 是否运行;独立网关还要检查 `openviking_url`(`gateway.conf` 或 `OPENVIKING_GATEWAY_OPENVIKING_URL`)。 |
+| 503 | `openviking_version_mismatch` | 仅独立网关:OpenViking Server 低于要求的版本,响应中的 `required_version` 给出最低版本。 |
+
+OpenViking 返回的其他 HTTP 错误记为 `openviking_http_<status>`;网关自身的通用 HTTP 错误记为 `gateway_http_<status>`,例如对不支持的方法返回 405 `gateway_http_405`。
+
+模型客户端收到的 401 不属于管理 API。原因可能是网关密钥缺失、错误或已吊销,也可能是它绑定的 OpenViking 密钥已经失效,排查方法见[客户端收到网关返回的错误](../guides/22-gateway-operations.md#客户端收到网关返回的错误)。
diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.md
index da5e56fad..e8445f9d5 100644
--- a/docs/zh/guides/03-deployment.md
+++ b/docs/zh/guides/03-deployment.md
@@ -298,7 +298,7 @@ docker compose up -d
启动后可以访问:
- API 服务:`http://localhost:1933`
- Web Studio:`http://localhost:1933/studio`(与 API 同源)
-- Caddy 入口:`http://localhost:1934`。它把请求转发到 1933,主要为已有部署保留;同时运行 OpenViking 网关时,它还把模型 API 路径转发给网关,见[OpenViking 网关部署与运维](22-gateway-operations.md#docker-compose)。
+- Caddy 入口:`http://localhost:1934`。它把所有路径转发到 1933,主要为已有部署保留。开启 OpenViking 网关后,网关在同一端口的 `/gateway` 下提供服务,例如 `http://localhost:1933/gateway/v1`,见[OpenViking 网关部署与运维](22-gateway-operations.md#docker-compose)。
### 部署到 Railway
diff --git a/docs/zh/guides/12-public-access.md b/docs/zh/guides/12-public-access.md
index e3fa27522..675d5f2c6 100644
--- a/docs/zh/guides/12-public-access.md
+++ b/docs/zh/guides/12-public-access.md
@@ -73,7 +73,7 @@ [email protected] # 可选;推荐用于 Let's Encrypt
}
```
-如果同时运行[OpenViking 网关](15-gateway.md),请改用网关运维指南 [Docker Compose](22-gateway-operations.md#docker-compose) 一节中的域名块。它把模型 API 路径转发给网关,其余请求转发给 OpenViking。
+开启 OpenViking 网关(`gateway.enabled: true`)后,模型 API 和网关管理 API 也在 Server 端口的 `/gateway` 下,这条反代配置同样覆盖它们,不需要额外的上游或按路径分流。
### 3. 取消 `docker-compose.yml` 中的 HTTPS 注释
@@ -197,13 +197,16 @@ Compose 部署应修改 `.env` 并运行 `docker compose up -d`,在其他 shel
<a id="兼容备注-1934-单上游反代"></a>
-## 兼容备注:`:1934` 反代
+## 兼容说明:`:1934` 代理
+
+自带 Caddy 的兼容端口 1934 把所有路径转发到 `openviking:{$OPENVIKING_SERVER_PORT:1933}`。开启 OpenViking 网关后,1933 端口同时提供 OpenViking 的普通接口,以及 `/gateway` 下的模型 API、工具上传和网关管理 API,不再需要单独的网关容器、1935 端口或按路径分流的规则。
+
+已有书签或客户端还在用 1934 时可以保留它,用不到就删掉端口映射。公网客户端请走 HTTPS 入口。
-`docker compose up` 默认在 1934 端口启一个 Caddy 反代。它把[OpenViking 网关](15-gateway.md)的路径(`/v1/*`、`/api/v3/*`、`/api/compatible/v1/*` 和 `/gateway/uploads`)转发给 `gateway` 服务,其余请求转发给 `openviking:1933`。这个入口**主要为兼容已经书签到 1934 的旧部署保留**。网关自己的端口不对宿主机开放,所以不配 HTTPS 时,客户端要经这个端口访问网关,见网关运维指南的 [Docker Compose](22-gateway-operations.md#docker-compose) 一节。新部署直接连私网中的 1933,公网客户端使用上面的 HTTPS 入口;不需要这个入口可以从 `docker-compose.yml` 注释掉 caddy 服务和 1934 端口映射。
## 相关文档
- [部署指南](03-deployment.md) — Docker、systemd、Kubernetes
- [OAuth 指南](11-oauth.md) — OAuth 2.1 配置与客户端接入
- [认证](04-authentication.md) — API Key 管理
-- [OpenViking 网关部署与运维](22-gateway-operations.md) — 网关的路由、代理设置和 HTTPS
+- [OpenViking 网关部署与运维](22-gateway-operations.md) — 网关的部署、路由和反向代理要求
diff --git a/docs/zh/guides/15-gateway.md b/docs/zh/guides/15-gateway.md
index 446335275..e51cc98b2 100644
--- a/docs/zh/guides/15-gateway.md
+++ b/docs/zh/guides/15-gateway.md
@@ -4,56 +4,60 @@ description: 把任何使用 API Key 的模型客户端指向 OpenViking 网关
# OpenViking 网关
-**任何**能修改 Base URL 的模型客户端,接上 OpenViking 网关就能用上 OpenViking 记忆,还能让模型主动使用记忆。客户端只改两处:Base URL 改成网关地址,模型服务商的 API Key 换成网关密钥。不用安装插件,也不用改代码或提示词。
+OpenViking 网关是一个模型 API 代理:客户端只要能修改 Base URL,接上它就能用上 OpenViking 记忆。接入只改两处:Base URL 换成网关地址,模型服务商的 API Key 换成网关密钥。不用装插件,也不用改代码或提示词。
-开启 OpenViking 工具后,模型能在一条回复里自己检索记忆、读取原文、记下新内容、导入资料。这些工具由网关代为执行,客户端不需要声明或实现任何工具,所以聊天应用、SDK 脚本、低代码平台这类**任意**客户端,也能像 Agent 一样操作记忆。
+想先直观了解网关的工作原理,可以看官网的动画演示:[openviking.ai/gateway](https://openviking.ai/gateway)。
+
+网关在转发请求时完成三件事:
| 能力 | 网关做什么 |
| --- | --- |
-| 自动召回 | 用户每发一条新消息,网关先检索 OpenViking,把相关记忆附加到这条消息上再交给模型。之后的请求里,网关把这些内容原样放回原位,服务商的提示缓存不会因此失效。 |
-| 主动使用记忆 | 模型调用 OpenViking 工具来检索、读取、写入和导入,网关执行调用后把结果接回给模型,客户端只收到一条连贯的回复。新建的上下文配置默认开启,只提供只读工具。 |
-| 沉淀与压缩 | 网关把对话保存回 OpenViking,由 OpenViking 从中提取新的记忆。对话接近模型的上下文窗口时,网关让同一个模型写一份摘要,替换较早的内容。 |
+| 自动召回 | 用户每发一条新消息,网关先检索 OpenViking,把相关记忆附加到这条消息上,再交给模型。 |
+| 主动使用记忆 | 模型可以调用 OpenViking 工具检索、读取、写入和导入资料。工具由网关执行,客户端不用声明或实现任何工具。 |
+| 沉淀与压缩 | 网关把对话保存回 OpenViking,由 OpenViking 从中提取新记忆。对话接近模型的上下文窗口时,网关让同一个模型写摘要,替换较早的内容。 |
**适合谁**:装不了插件或 MCP 的客户端,例如聊天应用、SDK 脚本和低代码平台;以及想集中管理模型服务商、密钥和记忆设置的团队。**不适用**:直接用订阅账号登录的客户端(可以改用[订阅反代上游](#自定义上游)),以及 Cursor、Trae 这类从厂商服务器发起模型调用的客户端。
-网关支持三种常用的模型 API:Anthropic Messages、OpenAI Chat Completions 和 OpenAI Responses(要求每个请求都带完整历史)。它把每个请求转发给你配置的模型服务商,这里称为**上游**;请求用哪种 API 发来,就用同一种 API 转发,网关不做转换。
+网关支持三种模型 API:Anthropic Messages、OpenAI Chat Completions 和 OpenAI Responses(要求每个请求带完整历史)。请求转发到你配置的模型服务地址,本文称为**上游**。请求用哪种 API 发来,网关就用同一种 API 转发,不做协议转换。
-> **注意**:OpenViking 网关是一个单独运行的进程 `openviking-gateway`,不在 OpenViking Server 进程里。它和 VikingBot Gateway(`vikingbot gateway` 命令)是两个不同的组件:后者是 VikingBot 的长期运行入口,负责远程访问和接入聊天平台。
+网关目前处于 Beta 阶段。本页介绍它的工作方式和客户端接入;部署、Studio 中的管理和排障见[OpenViking 网关部署与运维](22-gateway-operations.md)。
-网关目前处于 Beta 阶段。本页介绍网关的工作方式和客户端接入方法。为团队部署网关和日常运维,见[OpenViking 网关部署与运维](22-gateway-operations.md)。
+> **注意**:OpenViking 网关和 VikingBot Gateway(`vikingbot gateway`)是两个组件。后者负责远程访问和聊天平台接入。
## 自定义上游
-上游可以自定义:任何兼容这三种 API 之一的服务都能添加为上游,不一定是模型服务商本身。常见的两种用法:
+任何兼容这三种 API 之一的服务都能添加为上游,不一定是模型服务商本身。两种常见用法:
-- **计费、配额和负载均衡。** 网关不负责这些。需要时在网关后面接一层 LiteLLM、new-api 这类网关,把它添加为上游。
-- **使用订阅额度。** 客户端不能直接用订阅账号登录网关,但可以把 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) 这类反向代理添加为上游。它把 ChatGPT(Codex)、Claude 等订阅账号包装成 API,例如 Codex 就可以经网关用上 ChatGPT 订阅额度。OpenAI Codex 负责人 Tibo 曾[公开介绍](https://x.com/thsottiaux/status/2076119366647894371)过用 CLIProxyAPI 接入 Codex 订阅的做法。**是否符合服务商的使用条款,请自行确认。**
+- **计费、配额和负载均衡。** 网关不做这些。需要时在网关后面接一层 LiteLLM、new-api 这类服务,把它添加为上游。
+- **使用订阅额度。** 客户端不能用订阅账号登录网关,但可以把 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) 这类反向代理添加为上游。它把 ChatGPT(Codex)、Claude 等订阅账号包装成 API,例如 Codex 就能经网关使用 ChatGPT 订阅额度。OpenAI Codex 负责人 Tibo 曾[公开介绍](https://x.com/thsottiaux/status/2076119366647894371)过用 CLIProxyAPI 接入 Codex 订阅的做法。**是否符合服务商的使用条款,请自行确认。**
-添加方法见[上游](22-gateway-operations.md#上游),服务商选*通用*。
+添加时服务商选*通用*,见[上游](22-gateway-operations.md#上游)。
## 一张图看懂架构
-![OpenViking 网关架构:客户端只改 Base URL 和 API Key,经反向代理把模型请求发给网关;网关用用户自己的 OpenViking 密钥搜索 OpenViking、保存对话,再用同一种 API 把请求转发给上游模型服务商;会话和记忆的正本在 OpenViking,网关本机只有两个加密的 SQLite 文件](../../images/gateway/architecture.zh.svg)
+![OpenViking 网关的两种运行形态。嵌入:客户端访问 OpenViking Server 的端口,Server 把 /gateway 下的所有路径(模型 API、上传和网关管理)交给同一进程里的网关,网关通过本机回环 HTTP、用用户本人的 OpenViking 密钥检索和保存记忆。独立:openviking-gateway 用自己的端口提供同样的 /gateway 路径和只含网关页面的 Studio,通过 HTTP(S) 调用已有的 OpenViking 服务。两种形态下,网关都用同一种 API 把请求转发给上游模型服务商;会话和记忆的正本在 OpenViking,网关本机只有两个 SQLite 文件(开启 OpenViking 加密时加密存储)](../../images/gateway/architecture.zh.svg)
-- **运行在哪**:网关是独立的服务,可以和 OpenViking 装在同一台机器、放在同一个 Pod,也可以分开部署(见[部署方式](22-gateway-operations.md#部署方式))。共享部署时网关端口不对外开放,由反向代理把模型 API 和工具上传路径转发给网关,其余路径转发给 OpenViking;只在本机试用时可以省掉反向代理。
-- **和 OpenViking 的关系**:网关只调用 OpenViking 的公开接口,向量化和记忆提取都在 OpenViking 里完成。
-- **数据在哪**:会话和记忆的正本在 OpenViking。网关本机只有两个加密的 SQLite 文件,一个存上游、密钥和配置,一个存对话状态;对话闲置 30 天后,网关删除它的状态。删除和隔离方式见[安全与数据](22-gateway-operations.md#安全与数据)。
-- **出故障时**:OpenViking 不可用时对话照常进行,只是不带记忆,保存对话会自动重试。网关停止服务时,经过它的模型调用全部失败。
-- **谁来管**:账号管理员在 Studio 里给每位用户签发网关密钥。每个密钥绑定一位 OpenViking 用户、一份**上下文配置**(召回预算、是否保存对话、是否开放 OpenViking 工具等记忆设置)和一组**上游**(请求转发到的模型服务地址和 API Key)。
+- **运行在哪**:开启后嵌入 OpenViking Server,和 Server 共用端口;也可以用 `openviking-gateway` 独立运行,连接已有的 OpenViking 服务(开源版或商业版)。两种方式下网关的所有 URL 都在 `/gateway` 下(例如 `/gateway/v1`),客户端路径相同,见[部署方式](22-gateway-operations.md#部署方式)。
+- **和 OpenViking 的关系**:网关只调用 OpenViking 的公开接口,向量化和记忆提取都在 OpenViking 中完成。
+- **数据在哪**:会话和记忆的正本在 OpenViking。网关本机只有两个 SQLite 文件(开启 OpenViking 加密时加密存储),一个存上游、密钥和配置,一个存对话状态,见[安全与数据](22-gateway-operations.md#安全与数据)。
+- **出故障时**:OpenViking 不可用时,对话照常进行,只是不带记忆,保存会自动重试。网关停止服务时,经过它的模型调用全部失败。
+- **管理哪些对象**:同一账号的用户共用**上游**(模型服务地址和 API Key)和**上下文配置**(召回预算、是否保存对话、是否开放 OpenViking 工具等记忆设置)。每个网关密钥绑定一位 OpenViking 用户、一份上下文配置和一组上游。谁能修改什么,见[权限矩阵](../api/25-gateway.md#凭证和账号范围)。
## 接入后,对话会发生什么
-先说明两个概念。**召回**是指从 OpenViking 搜出和这条消息相关的记忆,附加到消息上。**提示缓存**是服务商的计费机制:请求开头和上一次相同的部分按缓存价计费,从第一个不同的字节起按原价重新计算。缓存价通常只有原价的一小部分,具体比例见各服务商的定价说明。
+先解释两个词。**召回**指从 OpenViking 搜出和当前消息相关的记忆,附加到消息上。**提示缓存**是服务商的计费机制:请求开头和上一次相同的部分按缓存价计费,从第一个不同的字节起按原价计费。缓存价通常只有原价的一小部分,具体比例见各服务商的定价。
-| 你要做的 | 你会得到 | 额外开销 | 需要留意 |
-| --- | --- | --- | --- |
-| 把 Base URL 改成网关地址,API Key 换成网关密钥。Claude Code 还要设置 `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`,给子 Agent 和后台请求加上标记,避免为它们召回和保存。 | 每条新消息都补充相关记忆,对话开头还提供用户画像;对话保存回 OpenViking 并提取成新记忆;长对话自动压缩;可选:模型主动检索、读取和写入 OpenViking(见[下一节](#让任意客户端拥有-agentic-记忆))。 | 每条新消息的第一次模型调用最多多等 2 秒;补充的记忆按输入 token 计费,之后的请求里大部分按缓存价计费;触发压缩的那一轮多一次模型调用。 | 补充的记忆在客户端里看不到(服务商看得到),Studio 的请求日志也只记条数和耗时;没有设置上下文窗口时,网关按 1,000,000 token 的窗口决定何时压缩,使用窗口更小的模型时要请管理员填上实际窗口,否则长对话会因过长被服务商拒绝;客户端装了 OpenViking 插件时,网关不为这段对话召回、保存,也不提供 OpenViking 工具;只接了 OpenViking MCP 工具时,网关照常召回和保存,但不再提供自己的工具。 |
+接入后你会得到:每条新消息补上相关记忆,新对话开头带上用户画像;对话保存回 OpenViking 并提取成新记忆;长对话自动压缩;开启 OpenViking 工具后,模型还能主动检索、读取和写入记忆(见[下一节](#让任意客户端拥有-agentic-记忆))。
+
+代价有三项:每条新消息的第一次模型调用最多多等 2 秒;补充的记忆按输入 token 计费,后续请求里大部分按缓存价计费;触发压缩的那一轮多一次模型调用。
![一轮对话里发生了什么:网关识别对话和请求类型,把之前补充的记忆原样放回,只为新消息召回,再用同一种 API 转发给上游,并把这一轮放进待保存队列;下方说明原样放回如何让提示缓存持续命中,以及跨轮的保存和长对话压缩](../../images/gateway/one-turn.zh.svg)
-网关会自动认出同一段对话,只有用户的新消息触发召回,工具步骤和生成标题这类辅助请求不召回。下面依次说明各个环节。
+网关自动认出同一段对话(方法见[网关如何识别对话](#网关如何识别对话))。只有用户的新消息触发召回,工具步骤和生成标题这类辅助请求不触发。下文的预算、时长和开关都来自密钥使用的**上下文配置**,管理员可以逐项调整或关闭。
+
+### 模型看到什么
-**模型看到什么。** 模型 API 是无状态的,客户端每次请求都要把整段对话重新发一遍。当请求以一条新的用户消息结尾时,网关用这条消息的文本搜索 OpenViking,把结果附加到这条消息的末尾:
+模型 API 是无状态的,客户端每次请求都把整段对话重新发一遍。请求以一条新的用户消息结尾时,网关用这条消息的文本检索 OpenViking,把结果附加到消息末尾:
```text
发布日期最后定在哪天?
@@ -66,11 +70,13 @@ Relevant memory from OpenViking.
</openviking-context>
```
-客户端看不到这段内容:它不出现在回复里,客户端自己保存的历史也保持原样。不过服务商返回的 token 用量包含这部分,网关把用量原样传回客户端。每条用户消息只搜索一次;工具步骤、子 Agent 调用以及生成标题之类的辅助请求,沿用已经补充的内容。在同一个上下文窗口内,也就是对话被压缩之前,同一条记忆只补充一次;单条消息和单个上下文窗口的预算也限制了补充的总量。
+这段内容不出现在回复里,客户端保存的历史也不变;服务商看得到它,返回的 token 用量也包含它。每条用户消息只检索一次,同一轮里的工具步骤和辅助请求沿用已经补充的内容。在同一个上下文窗口内(压缩之前),同一条记忆只补充一次,补充总量受单条消息和单个窗口两级预算限制。
-**开头的内容。** 新对话开始时会带上你的 OpenViking 用户画像。启用读取工具后,还会提供记忆和技能目录,让模型能在自动检索之外继续查找资料。这些内容使用独立的 4,000 token 预算,技能目录最多占四分之一。你可以在上下文配置中关闭画像或调整预算。某部分读取失败时会省略该部分,对话照常继续。
+### 对话开头的内容
-开启召回或 OpenViking 工具时,开头还有一段说明,告诉模型这些内容来自哪里、哪些功能已启用。例如,开启召回、保存对话和三个 OpenViking 工具时:
+新对话开始时,网关附上你的 OpenViking 用户画像;提供 `read` 工具时,还附上记忆和技能目录,方便模型在自动召回之外继续查找。这部分有独立的 4,000 token 预算,技能目录最多占四分之一,不占召回预算。即使第一条消息没有召回到记忆,画像和目录也会出现;某部分读取失败就省略它,对话照常继续。客户端压缩历史后,新的开头会再次附上这些内容。
+
+开启召回或 OpenViking 工具时,开头还有一段说明,告诉模型这些内容从哪来、启用了哪些功能。例如同时开启召回、保存对话和三个 OpenViking 工具时:
```text
<openviking-context source="gateway-session-start">
@@ -97,266 +103,193 @@ Relevant memory from OpenViking. Use the openviking_read tool to expand URIs.
</openviking-context>
```
-即使第一条消息没有搜到相关记忆,画像和目录仍可出现。开头的说明、画像和目录都不占召回预算。客户端压缩历史后,新的开头会再次提供这些内容。
+### 记忆原样放回
+
+客户端保存的历史里没有网关补充的内容,所以网关自己记下每个记忆块,在这段对话之后的每个请求里放回原来那条消息上,逐字节一致。原因有两个:服务商按前缀匹配提示缓存,历史有一个字节不同,后面的缓存就全部失效;Claude 的思考签名覆盖之前的对话,历史变了,Claude 会拒绝这段对话。记忆放在最新消息末尾而不放进系统提示词,也是为了缓存:系统提示词改一个字,整份缓存都会失效。
+
+### 对话什么时候保存
-**原样放回。** 客户端保存的历史里没有网关补充的内容,所以网关自己记下每个记忆块,在这段对话后续的每个请求里,把它放回最初附加的那条消息上,逐字节保持一致。服务商按前缀缓存提示词,Claude 的思考签名又覆盖了之前的对话,所以历史必须保持一致:这样服务商的缓存才能持续命中,Claude 也不会拒绝这段对话。记忆放在最新消息的末尾而不是系统提示词里,也是同样的原因:系统提示词改动一个字,之后的整份缓存都会失效。
+网关把完成的轮次保存到密钥所属用户的 OpenViking 会话里,会话名形如 `gateway-…`。保存晚一轮:下一条用户消息到达时,网关才保存上一轮,因为这时才能确认客户端保留了它,被重新生成或放弃的回答不会保存。最后一轮在对话停顿 10 分钟后保存。
-**对话什么时候保存。** 网关把已完成的轮次保存到密钥所属用户的 OpenViking 会话里,这些会话名为 `gateway-…`。下一条用户消息到达时,网关才保存上一轮,因为这时才能确认客户端保留了它,所以重新生成或被放弃的回答不会被保存。对话的最后一轮在停顿 10 分钟后保存,随后网关提交会话,OpenViking 在后台从中提取记忆。会话里待提交的内容累计到 20,000 token 时,网关也会提交一次。保存前,网关会去掉自己添加的内容,以及 `<system-reminder>` 这类客户端噪声。子 Agent 请求、辅助请求和 token 计数请求从不保存。
+保存之后,网关会提交会话,OpenViking 在后台从中提取记忆。提交发生在两种时候:对话停顿 10 分钟,或者待提交内容累计到 20,000 token。保存前,网关会去掉自己添加的内容和 `<system-reminder>` 这类客户端噪声。子 Agent 请求、辅助请求和 token 计数请求从不保存。
-**长对话。** 对话用到模型上下文窗口的 90%(默认值)时,网关会压缩它:由同一个模型为到目前为止的对话写一份有长度上限的摘要,此后这份摘要取代压缩位置之前的全部内容,不保留任何原文;客户端界面里的历史保持不变。如果开启了保存对话,并且模型能用 OpenViking 的 grep 和 read 工具,摘要后面会说明如何在已保存的对话里查找细节。摘要由模型自己生成,不再使用 OpenViking 的 Working Memory 摘要,网关新建的 OpenViking 会话也都关闭了 Working Memory。上游和上下文配置都没有设置模型的上下文窗口时,网关按 1,000,000 token 计算,所以窗口更小的模型需要设置窗口。每次压缩会多一次模型请求,服务商缓存也会失效一次。详见[长对话](22-gateway-operations.md#长对话)。
+### 长对话
-以上数字都来自密钥使用的**上下文配置**。你可以在其中调整预算和时间,也可以分别关闭每项功能。
+对话用到模型上下文窗口的 90% 时,网关压缩它:让同一个模型为目前为止的对话写一份有长度上限的摘要,此后用摘要代替压缩位置之前的全部内容,客户端界面里的历史不变。开启了保存对话、模型也能用 OpenViking 的 grep 和 read 工具时,摘要后面会说明如何在已保存的对话里查找细节。每次压缩多一次模型请求,服务商缓存也失效一次。
+
+网关需要知道模型的上下文窗口有多大。上游和上下文配置都没有设置时,网关按 1,000,000 token 计算,所以使用窗口更小的模型时,要请管理员填上实际窗口,否则长对话会在压缩前被服务商以过长为由拒绝。压缩的细节见[长对话](22-gateway-operations.md#长对话)。
## 让任意客户端拥有 Agentic 记忆
-自动召回是网关替模型猜它需要什么;开启 OpenViking 工具后,由模型自己决定查什么、读什么、记什么。工具由网关执行,客户端不用声明或实现任何工具,请求里一个工具都没有也能用。
+自动召回是网关替模型猜它需要什么;开启 OpenViking 工具后,由模型自己决定查什么、读什么、记什么。工具由网关执行,客户端的请求里一个工具都没有也能用。
![开启 OpenViking 工具后的一条回复:网关在客户端的请求上附加召回的记忆和 OpenViking 工具定义,模型调用 OpenViking 工具时由网关用该用户的 OpenViking 密钥执行,再把结果接回请求继续询问模型,直到模型给出最终回答;客户端收到的是一条带提示行的连贯回复,工具往返在下一轮被原样放回](../../images/gateway/tool-loop.zh.svg)
-- **一条回复里完成多步操作**:网关拦下模型发出的 OpenViking 工具调用,用该用户的 OpenViking 密钥执行,把结果接回后再问模型,直到模型不再调用。客户端只收到一条连贯的回复,流式和非流式都支持。
+- **一条回复里完成多步操作**:网关拦下模型发出的 OpenViking 工具调用,用该用户的 OpenViking 密钥执行,把结果接回再问模型,直到模型不再调用。客户端只收到一条连贯的回复,流式和非流式都支持。
- **客户端自己的工具照常可用**:同一条回复里,模型可以同时调用 OpenViking 工具和客户端工具(例如 Bash)。客户端工具的调用原样交给客户端执行,照常经过客户端的权限确认。
-- **下一轮还记得**:模型发出的工具调用和网关拿回的结果不在客户端的历史里,网关把这些工具往返存下来,下一轮原样放回。模型记得自己查到过什么,提示缓存也不会因此失效。
+- **下一轮还记得**:工具调用和结果不在客户端的历史里,网关把这些往返存下来,下一轮原样放回。模型记得自己查到过什么,提示缓存也不受影响。
### 不同客户端得到什么
| 客户端 | 不经过网关时 | 经过网关并开启 OpenViking 工具后 |
| --- | --- | --- |
-| 聊天应用,例如 Cherry Studio、Open WebUI | 要用记忆得自己配 MCP 或写工具,普通对话只收发文本。 | 模型自己检索记忆、按 URI 读取原文;勾选 `remember` 后还能记下用户要求记住的事。勾选 `add_resource` 后,用户附带的文件可以导入 OpenViking:客户端发送原文件就导入原文件,Open WebUI 通常只发送提取出的文本。即使是不带任何工具的纯聊天模式,模型也能调用 OpenViking 工具。 |
-| SDK 脚本、低代码平台 | 一问一答,要多步操作就得自己写循环。 | 一次请求里完成“检索 → 读取 → grep 精确匹配 → 作答”,代码不用改。 |
-| Claude Code、Codex 等编程 Agent(未装 OpenViking 插件或 MCP) | 有自己的工具,但没有 OpenViking。 | OpenViking 工具和 Bash 等客户端工具在同一条回复里混用,不用装插件或配 MCP。需要逐次确认工具调用时,仍建议使用插件或 MCP。 |
+| 聊天应用,例如 Cherry Studio、Open WebUI | 要用记忆得自己配 MCP 或写工具,普通对话只收发文本。 | 模型自己检索记忆、按 URI 读取原文。勾选 `remember` 后,能记下用户要求记住的事;勾选 `add_resource` 后,能把用户附带的文件导入 OpenViking。不带任何工具的纯聊天模式也能用。 |
+| SDK 脚本、低代码平台 | 一问一答,多步操作要自己写循环。 | 一次请求里完成“检索 → 读取 → grep 精确匹配 → 作答”,代码不用改。 |
+| Claude Code、Codex 等编程 Agent(未装 OpenViking 插件或 MCP) | 有自己的工具,但没有 OpenViking。 | OpenViking 工具和 Bash 等客户端工具在同一条回复里混用。需要逐次确认工具调用时,仍建议用插件或 MCP。 |
### 模型能用哪些工具
-工具直接来自你的 OpenViking 服务提供的 MCP 工具清单,名称前加 `openviking_` 前缀,OpenViking 新增的工具也会自动可用。常用的几类:
+工具清单直接来自你的 OpenViking 服务提供的 MCP 工具,名称加上 `openviking_` 前缀;OpenViking 新增的工具也会自动可用。常用的几类:
| 用途 | 工具 | 模型拿来做什么 |
| --- | --- | --- |
| 检索 | `find`、`search`、`grep`、`glob` | 语义检索记忆和资料;按正则或文件名精确查找。 |
| 浏览和读取 | `list`、`tree`、`read` | 按 URI 展开召回条目的原文,浏览记忆和技能目录。 |
| 写入 | `remember`、`write`、`edit` | 存一条长期记忆,写入或局部修改记忆文件。 |
-| 导入 | `add_resource`、`add_skill` | 按 URL 导入网页或代码仓库、导入对话附件、用一段文本新建技能,都不需要客户端有 shell。 |
+| 导入 | `add_resource`、`add_skill` | 按 URL 导入网页或代码仓库,导入对话附件,用一段文本新建技能,都不需要客户端有 shell。 |
| 删除和权限 | `forget`、`set_acl` 等 | 永久删除记忆,修改共享资源的访问权限。 |
-### 怎么开启、有什么上限
+### 默认设置
-- **默认只提供只读工具。** 新建的上下文配置默认打开 **OpenViking 工具**,“使用推荐设置创建”也一样。默认勾选的是只读工具:`find`、`search`、`grep`、`glob`、`list`、`tree`、`read`、`list_watches`、`get_acl`、`list_users`、`list_groups` 和 `health`。会修改数据的工具默认不勾选:`remember`、`write`、`edit`、`add_resource`、`add_skill`、`forget`、`set_acl` 和 `cancel_watch`。想让模型保存记忆,就勾选 `remember`;想让它导入网页或附件,就勾选 `add_resource`。OpenViking 以后新增的工具会自动勾选。已有的上下文配置保留原来的设置。全部工具定义约占 3,500 个输入 token,会随对话中的每个请求发送,所以取消用不到的工具也能节省 token。改动只影响新对话。
-- **上限。** 工具轮数、**总时长**和 **Token 预算**默认都不限:模型会一直使用 OpenViking 工具直到完成。流式请求中,用户可以随时中断回复;非流式请求在客户端断开后仍会继续执行,如果客户端发送非流式请求,建议设置**总时长**。设置了工具轮数或 Token 预算的,用完后网关拒绝之后的 OpenViking 调用,模型用已有结果继续回答;模型被拒后仍坚持调用,这个请求就会报错。设置了**总时长**的,请求超过这个时长就会失败。单次调用超过 30 秒,这次调用向模型返回错误。
-- **客户端要求。** 客户端要每轮回传完整历史;使用 OpenAI Responses 时要设置 `store: false`。客户端强制指定某个工具或要求结构化输出、上游关闭了**允许 OpenViking 工具**,或者上游是 DeepSeek、关闭了**补全推理内容回传**而请求又没有关闭思考模式时,网关不提供 OpenViking 工具。DeepSeek 要求带工具的请求回传之前每条回复的推理内容,而很多客户端不会发回来;DeepSeek 上游默认开启**补全推理内容回传**,由网关补回这部分内容,所以保持思考模式也能使用工具,见[上游](22-gateway-operations.md#上游)。对话是否带工具,由它第一个能用工具的请求决定;如果客户端自己也接了 OpenViking 工具,网关会关掉自己的工具。
+新建的上下文配置默认开启 OpenViking 工具,但只勾选检索、浏览和读取这类只读工具。会修改数据的工具(如 `remember`、`add_resource`、`forget`)要管理员主动勾选。轮数、总时长和 token 预算默认都不限,模型会一直使用工具直到完成。
-完整的条件、上限设置、文件导入方式和失败处理,见[OpenViking 工具](22-gateway-operations.md#openviking-工具)。
+客户端必须每轮回传完整历史;使用 Responses 时还要设置 `store: false`。客户端强制指定工具、要求结构化输出,或者自己已经接了 OpenViking 工具时,网关不再提供自己的工具。完整的默认工具列表、上限、文件导入方式和不提供工具的原因,见[OpenViking 工具](22-gateway-operations.md#openviking-工具)。
### 用户看到什么
-模型的文字实时流出。每次 OpenViking 工具调用都在回复里留一行提示,调用开始时出现,结束后补上 `done`、`failed` 或 `skipped`:
+模型的文字实时流出。每次 OpenViking 工具调用在回复里留一行提示,调用开始时出现,结束后补上 `done`、`failed` 或 `skipped`:
```text
> OpenViking find: "上次定的发布日期" — done
> OpenViking read: viking://user/alice/memories/release.md — done
```
-提示行只显示工具名和查询词、URI 这类调用对象,完整参数和调用结果用户看不到。提示行不发给模型,也不保存到 OpenViking,管理员可以在上下文配置里关掉它。客户端收到的 token 用量是这条回复里所有模型调用之和。
+提示行只显示工具名和调用对象(查询词、URI 等),用户看不到完整参数和结果。模型看不到提示行,网关也不把它保存到 OpenViking;管理员可以在上下文配置里关掉它。客户端收到的 token 用量是这条回复中所有模型调用之和。
-### 代价与管理员的控制点
+### 风险和控制点
-> **注意**:勾选的工具直接执行,不经过客户端的权限确认,包括写入和删除数据的工具。提示行是事后告知,不是确认。模型能做的事以该用户自己的 OpenViking 权限为上限。
+> **注意**:勾选的工具直接执行,不经过客户端的权限确认,写入和删除数据的工具也一样。提示行是事后告知,不是确认。模型能做的事以该用户自己的 OpenViking 权限为上限。
-- **收紧工具。** 给聊天应用用的上下文配置,建议至少取消 `forget` 和 `set_acl`。这是建议,不是默认值。
-- **四个控制点**:上下文配置里的总开关、逐个工具勾选、每个上游的**允许 OpenViking 工具**开关,以及工具轮数和 token 上限。
-- **和插件或 MCP 怎么选。** 插件和 MCP 在客户端里显示每次调用和结果,并在调用前请求确认,所以 Claude Code、Codex 用它们更透明。网关工具主要服务接不了插件或 MCP 的客户端。
+- **管理员的控制点**:上下文配置里的总开关和逐个工具勾选、每个上游的**允许 OpenViking 工具**开关,以及工具轮数、总时长和 token 上限。给聊天应用用的配置,建议至少不勾选 `forget` 和 `set_acl`。
+- **和插件或 MCP 怎么选**:插件和 MCP 在客户端里显示每次调用和结果,调用前还会请求确认,所以 Claude Code、Codex 用它们更透明。网关工具主要服务接不了插件或 MCP 的客户端。
-**实验性:Agent 自管上下文窗口。** 模型能使用 OpenViking 工具时,上下文配置还可以让它自己管理上下文窗口:模型会多两个工具,一个查看当前窗口用了多少,一个写好交接笔记后开启新窗口;窗口快满时,网关还会提醒它。这项功能默认关闭。详见[实验性:Agent 自管上下文窗口](22-gateway-operations.md#实验性-agent-自管上下文窗口)。
+**实验性功能**:上下文配置还可以让模型自己管理上下文窗口:模型多两个工具,一个查看窗口用了多少,一个写好交接笔记后开启新窗口;窗口快满时网关会提醒它。这项功能默认关闭,见[实验性:Agent 自管上下文窗口](22-gateway-operations.md#实验性-agent-自管上下文窗口)。
## 网关还是插件
-OpenViking 也可以通过运行在 Agent 内部的插件接入 Claude Code、Codex、OpenCode、pi、OpenClaw、Hermes 等 Agent(见 [Agent 集成概览](../agent-integrations/01-overview.md))。两种方式互相补充,差别都来自它们运行的位置:
+OpenViking 也能以插件形式接入 Claude Code、Codex、OpenCode、pi、OpenClaw、Hermes 等 Agent(见 [Agent 集成概览](../agent-integrations/01-overview.md))。两种方式互相补充,差别都来自运行位置:
| | OpenViking 网关 | Agent 插件 |
| --- | --- | --- |
-| 运行位置 | 在客户端和模型服务商之间,只能看到发给模型的请求。 | 在 Agent 内部,能看到 Agent 的会话、事件和本地工作区。 |
-| 适用的客户端 | 凡是能设置 Base URL 和 API Key 的客户端:聊天应用、SDK 和 API 应用、低代码平台、编程 Agent。 | 有 OpenViking 插件的 Agent。 |
-| 无法覆盖的客户端 | 直接用订阅账号登录的客户端(Claude Code 的 Claude 登录、Codex 的 ChatGPT 登录;可以改用[订阅反代上游](#自定义上游)),以及模型调用从厂商服务器发出的客户端,例如 Cursor 和 Trae。 | 没有扩展接口的客户端。 |
-| 按项目区分记忆 | 看不到工作目录和代码仓库。记忆按 OpenViking 用户归属,需要按项目隔离时,给每个项目使用绑定不同 OpenViking 用户的网关密钥。 | 自动识别工作区和代码仓库。 |
-| 能看到什么 | 补充的记忆在客户端里不可见。OpenViking 工具调用默认在回复里显示为一行提示,但不显示调用结果。两者都可以到 Studio 查看。工具调用不经过客户端的权限确认。 | 工具调用出现在对话记录里,并经过 Agent 的权限确认。 |
-| 保存时机 | 晚一轮:下一条消息到达时保存上一轮,最后一轮在对话停顿一段时间后保存。 | 跟随 Agent 自己的事件,例如每轮结束时。 |
-| 安装与升级 | 所有人共用一个服务,不用在每台机器上安装。上游、密钥和记忆设置集中管理。 | 每台机器分别安装和升级。 |
-| 密钥、数据和故障 | 集中保管服务商的 API Key 和尚未保存的对话文本(加密存储),每次模型调用多经过一跳。网关停止服务时,经由它的模型调用都会失败。 | 服务商的 API Key 留在各自的 Agent 里,只有保存的对话进入 OpenViking,不需要额外维护服务。 |
+| 运行位置 | 在客户端和模型服务商之间,只看得到发给模型的请求。 | 在 Agent 内部,看得到 Agent 的会话、事件和本地工作区。 |
+| 适用的客户端 | 能设置 Base URL 和 API Key 的客户端:聊天应用、SDK 和 API 应用、低代码平台、编程 Agent。 | 有 OpenViking 插件的 Agent。 |
+| 覆盖不到的客户端 | 用订阅账号直接登录的客户端(Claude Code 的 Claude 登录、Codex 的 ChatGPT 登录;可以改用[订阅反代上游](#自定义上游)),以及从厂商服务器发起模型调用的客户端,例如 Cursor 和 Trae。 | 没有扩展接口的客户端。 |
+| 按项目区分记忆 | 看不到工作目录和代码仓库。记忆按 OpenViking 用户归属,要按项目隔离,就给每个项目一个绑定不同 OpenViking 用户的网关密钥。 | 自动识别工作区和代码仓库。 |
+| 可见性 | 补充的记忆在客户端里不可见。OpenViking 工具调用默认在回复里显示一行提示,不显示结果。Studio 的请求日志记录召回条数和工具轮数,不记录内容。工具调用不经过客户端的权限确认。 | 工具调用出现在对话记录里,经过 Agent 的权限确认。 |
+| 保存时机 | 晚一轮:下一条消息到达时保存上一轮,最后一轮在对话停顿后保存。 | 跟随 Agent 自己的事件,例如每轮结束时。 |
+| 安装与升级 | 所有人共用一个服务,不用在每台机器上安装;上游、密钥和记忆设置集中管理。 | 每台机器分别安装和升级。 |
+| 密钥、数据和故障 | 集中保管服务商的 API Key 和尚未保存的对话文本(开启 OpenViking 加密时加密存储),每次模型调用多一跳。网关停止服务时,经过它的模型调用全部失败。 | 服务商的 API Key 留在各自的 Agent 里,只有保存的对话进入 OpenViking,不需要额外维护服务。 |
-Claude Code、Codex 和 pi 如果需要按项目区分记忆,或者要求每次工具调用都能看到并确认,就继续用插件。没有插件的客户端,以及想集中管理服务商、密钥和记忆设置的场景,用网关。
+Claude Code、Codex 和 pi 需要按项目区分记忆,或者要求每次工具调用都能看到并确认时,继续用插件。没有插件的客户端,以及想集中管理服务商、密钥和记忆设置的场景,用网关。
-**两者同时使用。** 请求中出现 OpenViking 插件的迹象时,网关会停止为这段对话补充记忆、保存对话和提供 OpenViking 工具,只负责转发,这样同一份内容不会被补充两次或保存两次。网关根据以下两类迹象判断:
+**两者同时使用时,网关让路。** 请求中出现 OpenViking 插件的迹象时,网关不再为这段对话补充记忆、保存对话或提供 OpenViking 工具,只做转发,避免同一份内容被补充两次、保存两次。判断依据有两类:
-- 插件插入提示词的记忆块:`<openviking-context>`、`<relevant-memories>`、`<relevant-memory>` 或 `<memory-context>`;
-- `X-OpenViking-Plugin` 请求头,插件和应用的作者可以发送它,明确表示不需要网关补充记忆。
+- 插件插入的记忆块:`<openviking-context>`、`<relevant-memories>`、`<relevant-memory>` 或 `<memory-context>`;
+- `X-OpenViking-Plugin` 请求头。插件和应用的作者可以发送它,明确告诉网关不要补充记忆。
-这个判断对这段对话一直有效;想重新用上网关记忆,需要在不带插件的情况下开始新对话。其他对话不受影响。在 Studio 的“请求日志”标签页里,这些请求会标上**检测到 OpenViking 插件**。
+这个判断对整段对话有效,其他对话不受影响;想重新用上网关记忆,需要不带插件开始新对话。Studio 的请求日志会把这些请求标为**检测到 OpenViking 插件**。
-只接了 OpenViking MCP 工具、没有装插件的客户端不算:网关照常补充记忆和保存对话,只是不再提供自己的 OpenViking 工具,免得模型看到两套(即[网关运维](22-gateway-operations.md)里的 `tool_name_collision`)。
+只接了 OpenViking MCP 工具、没装插件的客户端不算:网关照常补充记忆和保存对话,只是不再提供自己的 OpenViking 工具,免得模型看到两套同名工具(请求日志中显示为 `tool_name_collision`)。
## 快速开始
-下面的流程在一台机器上运行 OpenViking Server、网关和测试客户端。你需要:
+先准备好一套能正常工作的 OpenViking,`ov.conf` 中已经配好 embedding 和 VLM 模型(见[快速开始](../getting-started/02-quickstart.md))。网关包含在核心包中,不需要另外安装。下面按服务端的情况选一条路径。已有 OpenViking 服务、不想改它的配置时,可以独立运行网关,见[独立部署](22-gateway-operations.md#独立部署)。
-- 一套能正常工作的 OpenViking,`ov.conf` 中已经配置好 embedding 和 VLM 模型(见[快速开始](../getting-started/02-quickstart.md));
-- Python 3.10 或更高版本;
-- 一个模型服务商的 API Key。订阅登录和 Coding Plan 密钥无法通过网关使用。
+### 本地服务(不需要 API 密钥)
-### 1. 安装网关
+适用于绑定在 `127.0.0.1`、使用默认本地认证的服务。
-把 `gateway` 可选依赖安装到 OpenViking 所在的环境:
+1. **开启网关。** 运行 `openviking-server init`,在 **Enable OpenViking Gateway on the same port?** 处回答 yes;已有配置时,在菜单中选择 **Update gateway**。也可以直接把 `{"gateway": {"enabled": true}}` 合并进 `ov.conf`。
+2. **启动或重启** `openviking-server`。
+3. **在 Studio 中打开网关。** 打开 <http://127.0.0.1:1933/studio/>,在侧边栏选择 **OpenViking 网关**,不用填写密钥。默认账号还没有上游时,网关启动时会把服务端的 VLM 配置导入为上游,并创建一份上下文配置,所以“概览”标签页的**快速开始**清单前两步已经完成。导入的 Coding Plan 上游需要你确认后才能使用,见[导入 OpenViking 模型配置](22-gateway-operations.md#导入-openviking-模型配置);没有可导入的配置时,按[上游](22-gateway-operations.md#上游)手动添加。
+4. **签发网关密钥。** 在“密钥”标签页点**签发密钥**,填写名称,选择上下文配置和上游,然后签发。这个密钥以本地 `default` 用户的身份读写记忆。**复制网关密钥**对话框只显示一次完整的 `ovgw_…` 密钥,关闭前先复制。
-::: code-group
+然后向 `http://127.0.0.1:1933/gateway` [发送测试请求](#发送测试请求)。
-```bash [pip]
-pip install "openviking[gateway]"
-```
+### 远程服务(使用 API 密钥)
-```bash [uv]
-uv tool install "openviking[gateway]" --upgrade
-```
+适用于通过网络访问、使用 `api_key` 认证的服务。
-:::
+1. **开启网关。** 在服务端主机上运行 `openviking-server init`,绑定选择 **Remote (0.0.0.0)**,在 **Enable OpenViking Gateway on the same port?** 处回答 yes。接下来的 **Allow users to configure their own gateway upstreams?** 决定谁能修改上游和上下文配置:
+ - 回答 yes:每个登录的用户都能配置本账号的上游和上下文配置。
+ - 回答 no:init 生成一个以 `ovgm_` 开头的网关管理密钥,打印出来并写入 `ov.conf` 的 `gateway.management_key`。只有输入这个密钥才能修改上游和上下文配置,见[网关管理密钥](22-gateway-operations.md#网关管理密钥)。
-安装后,`openviking-gateway --help` 会打印命令用法。在 Linux 和 macOS 上,还可以加装 `gateway-fast`(`"openviking[gateway,gateway-fast]"`),换用更快的事件循环和 HTTP 解析器。
+ 然后重启服务。也可以用 root 密钥登录 Studio,在 OpenViking 网关页面点**开启网关**:Studio 会写入 `ov.conf` 并重启服务(仅限只有一个 worker 的服务端)。
+2. **准备 OpenViking API 密钥。** 用你自己的用户 API 密钥,或者按[认证](04-authentication.md)用 root 密钥创建账号和用户。
+3. **登录 Studio。** 打开 `https://ov.example.com/studio/`,在**连接设置**中填入 API 密钥,然后在侧边栏选择 **OpenViking 网关**。
+4. **添加上游。** 在“上游”标签页点**添加上游**,选择服务商和客户端使用的协议(下面的测试请求用 Chat Completions),粘贴服务商的 API Key 后保存。在上游列表里点**测试**,确认网关能连上服务商。如果标签页是只读的,说明部署者设置了网关管理密钥,见[在 Studio 中管理网关](22-gateway-operations.md#在-studio-中管理网关)。
+5. **创建上下文配置。** 在“上下文配置”标签页点**使用推荐设置创建**。
+6. **签发网关密钥**,做法同本地路径第 4 步,签发给你自己。要给其他用户签发,见[网关密钥](22-gateway-operations.md#网关密钥)。
-### 2. 生成加密密钥和管理令牌
+### 发送测试请求
-网关需要两样东西:一个加密密钥,用来加密它存储的数据;一个管理令牌,OpenViking Server 凭它代你调用网关的管理接口。两者各生成一次,保存在只有你能读取的文件里:
-
-```bash
-mkdir -p ~/.openviking
-cat > ~/.openviking/gateway.env <<EOF
-export OPENVIKING_GATEWAY_ENCRYPTION_KEY="$(python3 -c 'import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())')"
-export OPENVIKING_GATEWAY_ADMIN_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
-EOF
-chmod 600 ~/.openviking/gateway.env
-```
-
-OpenViking Server 和网关都要读取这两个环境变量,所以启动它们的每个终端都要先加载这个文件。加密密钥务必保留好:一旦更换,网关就读不出之前存储的数据。
-
-### 3. 开启 API Key 认证和网关
-
-网关用每个人自己的 OpenViking 密钥访问记忆,所以 OpenViking 必须运行在 API Key 模式。把下面的设置合并进 `~/.openviking/ov.conf`,root key 用一个足够长的随机值:
-
-```json
-{
- "server": {
- "auth_mode": "api_key",
- "root_api_key": "<root-key>"
- },
- "gateway": {
- "enabled": true,
- "public_url": "http://127.0.0.1:1935"
- }
-}
-```
-
-其余设置保持默认:网关监听 `127.0.0.1:1935`,通过 `http://127.0.0.1:1933` 访问 OpenViking,数据存放在 `~/.openviking/gateway`。`public_url` 是客户端使用的地址,Studio 的接入说明会显示它。
-
-### 4. 启动 OpenViking Server
-
-```bash
-source ~/.openviking/gateway.env
-openviking-server
-```
-
-如果服务已经在运行,就从这个终端重新启动它,让它同时读到新配置和管理令牌。
-
-### 5. 创建账号和用户密钥
-
-在另一个终端里,用 root key 创建一个账号及其首位管理员,做法见[认证](04-authentication.md):
-
-```bash
-curl -X POST http://127.0.0.1:1933/api/v1/admin/accounts \
- -H "X-API-Key: <root-key>" \
- -H "Content-Type: application/json" \
- -d '{"account_id": "acme", "admin_user_id": "alice"}'
-# 返回:{"result": {"account_id": "acme", "admin_user_id": "alice", "user_key": "..."}}
-```
-
-保存 alice 的 `user_key`。在这个流程里它有两个用途:在 Studio 里以账号管理员身份登录,以及作为网关访问 alice 记忆时使用的 OpenViking 密钥。团队使用时,给每个人单独创建用户密钥(调用 `POST /api/v1/admin/accounts/acme/users`,并指定 `"role": "user"`)。
-
-### 6. 启动网关
-
-```bash
-source ~/.openviking/gateway.env
-openviking-gateway --config ~/.openviking/ov.conf
-```
-
-检查它能否连上 OpenViking:
-
-```bash
-curl -s http://127.0.0.1:1935/health
-# {"status":"ok","service":"openviking-gateway","openviking":{"status":"ok","healthy":true,"version":"…","auth_mode":"api_key"}}
-```
-
-刚启动时,`openviking` 可能还显示 `{"status":"starting"}`。如果显示 `"status":"degraded"`,见[故障排查](22-gateway-operations.md#故障排查)。
-
-### 7. 在 Studio 中完成设置
-
-打开 <http://127.0.0.1:1933/studio>,进入**连接设置**,把 alice 的密钥同时填入**用户 API 密钥**和**管理员 API 密钥**。然后在侧边栏的“设置”分组里选择**OpenViking 网关**。第一个请求到达之前,“概览”标签页会显示**快速开始**清单,步骤与下面相同:
-
-1. **添加上游。** 在“上游”标签页选择**添加上游**。填写名称,选择服务商,再选择客户端使用的协议(本流程用 Chat Completions)。Studio 会填入服务商的 Base URL,例如 OpenAI 为 `https://api.openai.com/v1`;选*通用*时需要自己填写。保持选中**由网关保管 API Key**,再粘贴服务商的 API Key。保存后在上游列表里点**测试**,确认网关能连上服务商。
-2. **创建上下文配置。** 在“上下文配置”标签页选择**使用推荐设置创建**,会创建一份名为“默认”的配置,其中 OpenViking 工具只勾选了只读工具。
-3. **签发网关密钥。** 在“密钥”标签页选择**签发密钥**。填写名称,在 **OpenViking 用户**中选择 alice(账号里只有她一个用户时已经自动选好),再选择“默认”配置和刚添加的上游,然后签发。**复制网关密钥**对话框只显示一次完整的 `ovgw_…` 密钥,关闭之前先复制好。
-4. **接入客户端。** “接入”标签页列出了每种客户端的配置,并已填好你的网关地址。下文[接入客户端](#接入客户端)也列出了同样的配置。
-
-### 8. 发送测试请求
+本地服务把地址换成 `http://127.0.0.1:1933/gateway`,并把 `<model>` 换成上游提供的模型:
```bash
+export GATEWAY_URL=https://ov.example.com/gateway
export GATEWAY_KEY='ovgw_...'
-curl -s http://127.0.0.1:1935/v1/models -H "Authorization: Bearer $GATEWAY_KEY"
-# {"object":"list","data":[{"id":"…","object":"model","owned_by":"openviking-gateway"}]}
+curl -s "$GATEWAY_URL/v1/models" -H "Authorization: Bearer $GATEWAY_KEY"
-curl -s http://127.0.0.1:1935/v1/chat/completions \
+curl -s "$GATEWAY_URL/v1/chat/completions" \
-H "Authorization: Bearer $GATEWAY_KEY" \
-H "Content-Type: application/json" \
-H "X-OpenViking-Session: quickstart-1" \
-d '{"model": "<model>", "messages": [{"role": "user", "content": "记住:我喜欢简短的回答。"}]}'
```
-模型列表里是你在上游中填写的模型和别名;如果上游的模型列表留空,这里也是空的。第二条命令应该返回服务商的一次正常回复。
+第一条命令列出上游配置的模型和别名;上游接受任意模型名时,列表为空。第二条命令应该返回服务商的一次正常回复。
-### 9. 确认记忆生效
+### 确认记忆生效
-- **请求经过了网关。** 打开“请求日志”标签页,刚才的请求显示为**新消息**,状态为 200。OpenViking 中有相关内容时,**记忆**列会显示补充的条数(例如 `+3`);全新账号下这一列为空。
-- **对话已保存。** 用同一个 `X-OpenViking-Session` 请求头再发一条消息。第二条消息一到,第一轮就会保存;最后一轮在停顿 10 分钟后保存。之后,以 alice 身份连接 Studio 时,这段对话会以 `gateway-…` 会话的形式出现在**会话**页面。
-- **记忆已提取。** 会话提交之后,OpenViking 才会提取记忆:对话停顿 10 分钟时提交一次,待提交内容累计到 20,000 token 时也会提交。提取在后台进行,需要稍等片刻。然后换一个会话请求头的值开始新对话,问一个依赖这条记忆的问题,例如“你的回答应该多长?”。**记忆**列会显示召回的条数,回复也应该用上了这些记忆。
+1. **请求经过了网关。** 打开“请求日志”标签页,刚才的请求显示为**新消息**,状态 200。OpenViking 里有相关内容时,**记忆**列显示补充的条数(例如 `+3`);全新账号下这一列为空。
+2. **对话已保存。** 用同一个 `X-OpenViking-Session` 值再发一条消息,第一轮随即保存。以密钥所属用户的身份连接 Studio,**会话**页面会出现一个 `gateway-…` 会话。
+3. **记忆已提取。** 对话停顿 10 分钟后,网关提交会话,OpenViking 在后台提取记忆,需要稍等片刻。然后换一个会话值开始新对话,问一个依赖这条记忆的问题,例如“你的回答应该多长?”。**记忆**列应显示召回的条数,回复也应该用上了这条记忆。
-试用阶段想更快看到效果,可以另建一份上下文配置,把**最新回复等待时长**调短,用它签发一个密钥,再用这个密钥开始新对话。上下文配置的修改只对之后开始的对话生效。
+试用时想更快看到效果,可以另建一份上下文配置,把**最新回复等待时长**调短,用它签发一个密钥,再用这个密钥开始新对话。上下文配置的修改只对之后开始的对话生效。
## 接入客户端
-每个客户端都需要两样东西:网关地址和网关密钥。示例使用 `https://ov.example.com`,请换成你自己的网关地址;Studio 在 OpenViking 网关页面顶部和“接入”标签页都会显示它。另外,客户端所用的密钥必须绑定一个已启用的上游,这个上游要支持客户端的协议,并提供客户端请求的模型。
+每个客户端需要两样东西:网关地址和网关密钥。网关地址是服务地址加上 `/gateway`。下面的示例用 `https://ov.example.com/gateway`,请换成你的网关地址;Studio 的 OpenViking 网关页面顶部和“接入”标签页都会显示它。Anthropic 客户端直接使用网关地址,OpenAI 兼容客户端在后面加 `/v1`,方舟 SDK 加 `/api/v3`。客户端用的密钥还必须绑定一个已启用的上游,这个上游要支持客户端的协议,并提供客户端请求的模型。
| 客户端 | 上游协议 | Base URL | 对话识别方式 |
| --- | --- | --- | --- |
-| [Claude Code](#claude-code) | Anthropic Messages | `https://ov.example.com` | Claude Code 的会话请求头 |
-| [Codex CLI](#codex-cli) | Responses | `https://ov.example.com/v1` | Codex 的会话请求头 |
-| [聊天客户端和 SDK](#聊天客户端和-sdk) | Chat Completions(或 SDK 使用的 API) | `https://ov.example.com/v1` | `X-OpenViking-Session`,需要自己发送 |
-| [Open WebUI](#open-webui) | Chat Completions | `https://ov.example.com/v1` | 连接上配置的 `X-OpenViking-Session` 请求头 |
-| [OpenCode](#opencode) | Chat Completions | `https://ov.example.com/v1` | OpenCode 的会话请求头 |
-| [pi](#pi) | Chat Completions | `https://ov.example.com/v1` | 通常根据对话历史匹配 |
-| [火山方舟与 BytePlus 方舟 SDK](#火山方舟与-byteplus-方舟-sdk) | 三种均可 | `https://ov.example.com/api/v3` 或 `https://ov.example.com/api/compatible` | 取决于客户端发送的请求头 |
+| [Claude Code](#claude-code) | Anthropic Messages | `https://ov.example.com/gateway` | Claude Code 的会话请求头 |
+| [Codex CLI](#codex-cli) | Responses | `https://ov.example.com/gateway/v1` | Codex 的会话请求头 |
+| [聊天客户端和 SDK](#聊天客户端和-sdk) | Chat Completions(或 SDK 使用的 API) | `https://ov.example.com/gateway/v1` | `X-OpenViking-Session`,需要自己发送 |
+| [Open WebUI](#open-webui) | Chat Completions | `https://ov.example.com/gateway/v1` | 在连接上配置 `X-OpenViking-Session` 请求头 |
+| [OpenCode](#opencode) | Chat Completions | `https://ov.example.com/gateway/v1` | OpenCode 的会话请求头 |
+| [pi](#pi) | Chat Completions | `https://ov.example.com/gateway/v1` | 通常根据对话历史匹配 |
+| [火山方舟与 BytePlus 方舟 SDK](#火山方舟与-byteplus-方舟-sdk) | 三种均可 | `https://ov.example.com/gateway/api/v3` 或 `https://ov.example.com/gateway/api/compatible` | 取决于客户端发送的请求头 |
-Open WebUI、OpenCode 和 pi 的配置依据各自文档中的服务商设置编写,请把它们当作起点,配好后检查一下效果:在同一段对话里发两条消息,然后在“请求日志”中展开这两个请求。它们应该属于同一段对话,而且第二条消息到达后,第一轮已经保存。
+Open WebUI、OpenCode 和 pi 的配置依据它们各自文档中的服务商设置编写,请当作起点,配好后验证一下:在同一段对话里发两条消息,然后在“请求日志”中展开这两个请求,它们应该属于同一段对话,并且第二条消息到达后,第一轮已经保存。
### Claude Code
Claude Code 使用 Anthropic Messages。启动前设置三个环境变量:
```bash
-export ANTHROPIC_BASE_URL=https://ov.example.com
+export ANTHROPIC_BASE_URL=https://ov.example.com/gateway
export ANTHROPIC_AUTH_TOKEN='<gateway-key>'
export CLAUDE_CODE_GATEWAY_HINT_HEADERS=1
```
- 地址不要带 `/v1`,Claude Code 会自己补全路径。
-- `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` 让 Claude Code 给子 Agent、上下文压缩和后台请求加上标记,网关就不会为这些请求搜索记忆,也不会把它们当成对话轮次保存。
-- Claude Code 会发送自己的会话 ID,所以网关能自动识别对话,`--resume` 之后也一样。
-- 上游必须接受 Claude Code 请求的模型名。可以把上游的模型列表留空、列出这些名称,或者用模型别名把它们映射到服务商提供的模型。
-- Claude 订阅登录无法通过网关使用,携带订阅令牌的请求会被拒绝。请为上游配置服务商的 API Key。
-- 如果 Claude Code 同时装了 OpenViking 插件,网关会让出这些对话(见[网关还是插件](#网关还是插件))。只接了 OpenViking MCP 服务器时,网关照常补充记忆,OpenViking 工具交给 MCP 服务器。
+- `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` 让 Claude Code 给子 Agent、上下文压缩和后台请求加上标记,网关就不会为它们召回记忆,也不会把它们当作对话轮次保存。
+- Claude Code 发送自己的会话 ID,网关据此识别对话,`--resume` 之后也一样。
+- 上游必须接受 Claude Code 请求的模型名:模型列表留空、列出这些名称,或者用模型别名映射到服务商的模型。
+- Claude 订阅登录不能通过网关使用,带订阅令牌的请求会被拒绝。请为上游配置服务商的 API Key。
+- 同时装了 OpenViking 插件时,网关会让出这些对话(见[网关还是插件](#网关还是插件))。只接了 OpenViking MCP 服务器时,网关照常补充记忆,OpenViking 工具交给 MCP 服务器。
### Codex CLI
@@ -368,7 +301,7 @@ model = "<model>"
[model_providers.openviking]
name = "OpenViking Gateway"
-base_url = "https://ov.example.com/v1"
+base_url = "https://ov.example.com/gateway/v1"
wire_api = "responses"
env_key = "OPENVIKING_GATEWAY_KEY"
```
@@ -380,30 +313,30 @@ export OPENVIKING_GATEWAY_KEY='<gateway-key>'
```
- 密钥绑定的上游必须使用 Responses,并提供 `<model>`。
-- Codex 会先尝试 WebSocket 连接,网关拒绝后它会自动改用 HTTP。
-- Codex 会发送自己的会话 ID,所以网关能自动识别对话,`codex resume` 之后也一样。
-- 遇到不认识的模型名,Codex 可能提示缺少模型元数据,这个提示不影响请求。
-- ChatGPT 登录无法通过网关使用,请在上游配置服务商的 API Key。
+- Codex 会先尝试 WebSocket 连接,被网关拒绝后自动改用 HTTP。
+- Codex 发送自己的会话 ID,网关据此识别对话,`codex resume` 之后也一样。
+- 遇到不认识的模型名,Codex 可能提示缺少模型元数据,不影响请求。
+- ChatGPT 登录不能通过网关使用,请为上游配置服务商的 API Key。
### 聊天客户端和 SDK
-支持 OpenAI Chat Completions API 的客户端和 SDK 都能使用网关。在客户端要求填写 OpenAI 兼容服务商的地方填入:
+支持 OpenAI Chat Completions API 的客户端和 SDK 都能接入。在客户端填写 OpenAI 兼容服务商的地方填入:
```text
-Base URL: https://ov.example.com/v1
+Base URL: https://ov.example.com/gateway/v1
API key: <gateway-key>
Model: <model>
X-OpenViking-Session: <conversation-id>
```
-`X-OpenViking-Session` 请求头可选,但建议发送,它告诉网关请求属于哪段对话。取值要在同一段对话内保持不变、不同对话之间互不相同,例如应用里的聊天 ID。不发送时,网关根据历史匹配对话,见[网关如何识别对话](#网关如何识别对话)。
+`X-OpenViking-Session` 请求头可选,但建议发送,它告诉网关请求属于哪段对话。取值在同一段对话内保持不变、不同对话之间互不相同,例如应用里的聊天 ID。不发送时,网关根据历史匹配对话,见[网关如何识别对话](#网关如何识别对话)。
-使用 OpenAI Python SDK:
+用 OpenAI Python SDK:
```python
from openai import OpenAI
-client = OpenAI(base_url="https://ov.example.com/v1", api_key="<gateway-key>")
+client = OpenAI(base_url="https://ov.example.com/gateway/v1", api_key="<gateway-key>")
reply = client.chat.completions.create(
model="<model>",
@@ -413,13 +346,16 @@ reply = client.chat.completions.create(
print(reply.choices[0].message.content)
```
-另外两种 API 的 SDK 用法相同。Anthropic SDK 指向 `https://ov.example.com`。Responses API 使用 `https://ov.example.com/v1`,每个请求都要带完整历史并设置 `store: false`,其他 Responses 请求会直接转发,不补充记忆。上游使用的 API 必须和 SDK 一致。
+另外两种 API 的 SDK 用法相同,上游使用的 API 要和 SDK 一致:
+
+- Anthropic SDK 指向 `https://ov.example.com/gateway`。
+- Responses API 使用 `https://ov.example.com/gateway/v1`,每个请求都要带完整历史并设置 `store: false`;其他 Responses 请求直接转发,不补充记忆。
-流式调用 Chat Completions 时,还要请求返回用量(`"stream_options": {"include_usage": true}`)。否则服务商不会为流式回复报告 token 数,Studio 无法显示用量,网关也只能根据请求内容估算上下文窗口用了多少。
+流式调用 Chat Completions 时,请同时请求返回用量(`"stream_options": {"include_usage": true}`)。否则服务商不报告流式回复的 token 数,Studio 显示不了用量,网关也只能估算上下文窗口用了多少。
### Open WebUI
-在 Open WebUI 中添加一个 OpenAI 兼容连接(Admin Panel → Settings → Connections),Base URL 填 `https://ov.example.com/v1`,密钥填网关密钥。再给这个连接添加以下自定义请求头,这样每个聊天都是一段独立的对话,Open WebUI 的后台任务也能被识别出来:
+在 Open WebUI 中添加一个 OpenAI 兼容连接(Admin Panel → Settings → Connections),Base URL 填 `https://ov.example.com/gateway/v1`,密钥填网关密钥。再给这个连接加上下面的自定义请求头,让每个聊天成为一段独立的对话,并让网关认出 Open WebUI 的后台任务:
```json
{
@@ -428,14 +364,14 @@ print(reply.choices[0].message.content)
}
```
-同时在 Open WebUI 的环境变量中设置 `RAG_SYSTEM_CONTEXT=true`。这样 Open WebUI 会把从附件中检索到的内容放进 system 消息,而不是临时改写你这一轮的消息,对话历史在请求之间就能保持稳定。
+同时在 Open WebUI 的环境变量中设置 `RAG_SYSTEM_CONTEXT=true`。这样 Open WebUI 把附件检索结果放进 system 消息,而不是临时改写你这一轮的消息,请求之间的对话历史才能保持稳定。
-- **一个连接密钥只对应一位记忆归属者。** 通过这个连接聊天的所有 Open WebUI 用户,读写的都是密钥背后那位 OpenViking 用户的记忆。要么只把这个连接给一个人使用,要么接受这些用户共享记忆。
-- Open WebUI 还会通过同一个连接发送后台请求(生成标题、标签和追问建议)。网关能识别标题和摘要请求。如果请求日志里有其他后台任务被标成**新消息**,就把 Open WebUI 的任务模型改成一个不经过网关的连接。
+- **一个连接密钥只对应一位记忆归属者。** 通过这个连接聊天的所有 Open WebUI 用户,读写的都是密钥背后那位 OpenViking 用户的记忆。要么只让一个人用这个连接,要么接受这些用户共享记忆。
+- Open WebUI 还会通过同一个连接发送后台请求(生成标题、标签和追问建议)。网关能识别标题和摘要请求;如果请求日志里有其他后台任务被标成**新消息**,就把 Open WebUI 的任务模型改成一个不经过网关的连接。
### OpenCode
-在 `~/.config/opencode/opencode.json` 中添加一个服务商,与已有的设置合并:
+在 `~/.config/opencode/opencode.json` 中添加一个服务商,与已有设置合并:
```json
{
@@ -444,7 +380,7 @@ print(reply.choices[0].message.content)
"npm": "@ai-sdk/openai-compatible",
"name": "OpenViking",
"options": {
- "baseURL": "https://ov.example.com/v1",
+ "baseURL": "https://ov.example.com/gateway/v1",
"apiKey": "{env:OPENVIKING_GATEWAY_KEY}"
},
"models": {
@@ -455,7 +391,7 @@ print(reply.choices[0].message.content)
}
```
-把网关密钥导出为 `OPENVIKING_GATEWAY_KEY`,然后在 OpenCode 中选择 `openviking/<model>`。上游必须使用 Chat Completions。如果同时安装了 OpenViking 的 OpenCode 插件,网关会让出这些对话。
+把网关密钥导出为 `OPENVIKING_GATEWAY_KEY`,然后在 OpenCode 中选择 `openviking/<model>`。上游必须使用 Chat Completions。同时装了 OpenViking 的 OpenCode 插件时,网关会让出这些对话。
### pi
@@ -465,7 +401,7 @@ print(reply.choices[0].message.content)
{
"providers": {
"openviking": {
- "baseUrl": "https://ov.example.com/v1",
+ "baseUrl": "https://ov.example.com/gateway/v1",
"apiKey": "$OPENVIKING_GATEWAY_KEY",
"api": "openai-completions",
"models": [
@@ -478,31 +414,34 @@ print(reply.choices[0].message.content)
}
```
-`apiKey` 从环境变量 `OPENVIKING_GATEWAY_KEY` 读取网关密钥,启动 pi 前先导出它。开头的 `$` 不能省,pi 会把不带 `$` 的字符串直接当作密钥发送。上游必须使用 Chat Completions。除非 pi 发送了[网关如何识别对话](#网关如何识别对话)中列出的某个请求头,否则网关会根据历史匹配它的对话。如果 pi 自己的 OpenViking 扩展处于启用状态,网关会让出这些对话,两者选一个使用即可。
+- `apiKey` 从环境变量 `OPENVIKING_GATEWAY_KEY` 读取网关密钥,启动 pi 前先导出它。开头的 `$` 不能省,否则 pi 会把这个字符串本身当作密钥发送。
+- 上游必须使用 Chat Completions。
+- pi 通常不发送会话请求头,网关根据历史匹配它的对话(见[网关如何识别对话](#网关如何识别对话))。
+- pi 自己的 OpenViking 扩展启用时,网关会让出这些对话,两者选一个即可。
### 火山方舟与 BytePlus 方舟 SDK
-已经配置好火山方舟或其海外站 BytePlus 方舟的客户端和 SDK,只需替换域名。网关既接受方舟自己的路径(`/api/v3/chat/completions`、`/api/v3/responses`、`/api/v3/models` 和 `/api/compatible/v1/messages`),也接受标准的 `/v1` 路径:
+已经接入火山方舟或其海外站 BytePlus 方舟的客户端和 SDK,只需替换地址。在 `/gateway` 下,网关既接受方舟自己的路径(`/api/v3/chat/completions`、`/api/v3/responses`、`/api/v3/models` 和 `/api/compatible/v1/messages`),也接受标准的 `/v1` 路径:
| 原地址 | 网关地址 |
| --- | --- |
-| `https://ark.cn-beijing.volces.com/api/v3` | `https://ov.example.com/api/v3` |
-| `https://ark.ap-southeast.bytepluses.com/api/v3` | `https://ov.example.com/api/v3` |
-| `https://ark.cn-beijing.volces.com/api/compatible`(Anthropic 兼容) | `https://ov.example.com/api/compatible` |
+| `https://ark.cn-beijing.volces.com/api/v3` | `https://ov.example.com/gateway/api/v3` |
+| `https://ark.ap-southeast.bytepluses.com/api/v3` | `https://ov.example.com/gateway/api/v3` |
+| `https://ark.cn-beijing.volces.com/api/compatible`(Anthropic 兼容) | `https://ov.example.com/gateway/api/compatible` |
-用网关密钥代替方舟的 API Key。使用火山方舟 Python SDK:
+用网关密钥代替方舟的 API Key。以火山方舟 Python SDK 为例:
```python
from volcenginesdkarkruntime import Ark
-client = Ark(base_url="https://ov.example.com/api/v3", api_key="<gateway-key>")
+client = Ark(base_url="https://ov.example.com/gateway/api/v3", api_key="<gateway-key>")
```
-路径只决定客户端使用哪种 API。请求仍然发往密钥绑定的、使用这种 API 并提供该模型的上游,通常是服务商选为“火山方舟”或“BytePlus 方舟(海外站)”的上游(见[上游](22-gateway-operations.md#上游))。
+客户端用哪个路径,只决定它使用哪种 API。请求仍然发往密钥绑定的、使用这种 API 并提供该模型的上游,通常是服务商选为“火山方舟”或“BytePlus 方舟(海外站)”的上游(见[上游](22-gateway-operations.md#上游))。
## 网关如何识别对话
-网关需要知道请求属于哪段对话。一段对话固定使用同一份上下文配置和同一个上游,并保存到同一个 OpenViking 会话。网关按以下顺序取第一个出现的请求头:
+网关需要知道请求属于哪段对话:一段对话固定使用同一份上下文配置和同一个上游,并保存到同一个 OpenViking 会话。网关按以下顺序取第一个出现的请求头:
1. `X-OpenViking-Session`
2. `thread-id`
@@ -511,28 +450,27 @@ client = Ark(base_url="https://ov.example.com/api/v3", api_key="<gateway-key>")
5. `x-session-id`
6. `session-id`(Codex CLI)
-这些请求头都没有时,网关查看历史中最近一条助手回复。如果恰好有一段之前的对话产生过这条回复,请求就并入那段对话;否则开始一段新对话。两段对话不会仅仅因为开场消息相同而被合并。普通的一问一答这样就能识别,但重试、重新生成的回答和内容完全相同的对话存在歧义,可能被当成新对话。所以只要客户端允许设置请求头,就发送 `X-OpenViking-Session`。
+这些请求头都没有时,网关查看历史中最近一条助手回复:如果之前某段对话产生过这条回复,请求就并入那段对话,否则开始一段新对话。开场消息相同的两段对话不会因此被合并。普通的一问一答这样就能识别,但重试、重新生成和内容完全相同的对话存在歧义,可能被当成新对话。所以只要客户端允许设置请求头,就发送 `X-OpenViking-Session`。
-对话归属于密钥背后的 OpenViking 用户,并且按 API 分开。同一用户的两个网关密钥如果发送相同的会话值,会共享同一段对话;同一个会话值用在另一种 API 上,则是另一段对话。网关在转发前会去掉所有 `X-OpenViking-*` 请求头,服务商看不到它们。
+对话归属于密钥背后的 OpenViking 用户,并按 API 区分。同一用户的两个网关密钥发送相同的会话值,会共享同一段对话;同一个会话值用在另一种 API 上,则是另一段对话。网关转发前会去掉所有 `X-OpenViking-*` 请求头,服务商看不到它们。
-请求没有归入已有对话时,记忆照样工作:新消息照常搜索,之前补充的记忆也照常原样放回,因为网关是根据消息本身找到这些记忆的。区别在于这个请求会开始一段新对话:它的轮次保存到新的 OpenViking 会话,记忆预算从头计算,并使用密钥当前的上下文配置。
+请求没有归入已有对话时,记忆照样工作:新消息照常召回,之前补充的记忆也照常原样放回,因为网关是根据消息本身找到这些记忆的。区别在于这个请求会开始一段新对话:它的轮次保存到新的 OpenViking 会话,记忆预算从头计算,并使用密钥当前的上下文配置。
## 使用须知
-- **记忆按消息补充。** 每条新消息的第一次模型调用要等 OpenViking 搜索完成,最多等上下文配置里的**超时时间**(默认 2 秒)。OpenViking 超时或不可用时,这条消息不带记忆直接发给模型,之后也不会补上。OpenViking 停止服务期间,模型请求照常可用。
-- **设置只对新对话生效。** 一段对话始终使用它开始时的上下文配置和上游。Claude Code、Codex 这类长期运行的客户端会把一段对话延续很多天,所以修改上下文配置后,要等它们开始新对话才会生效。对话闲置 30 天后,网关会删除它的状态。
-- **保存晚一轮。** 对话的最后一轮在停顿 10 分钟后保存,记忆要等 OpenViking 处理完提交后才会出现。
-- **改动过的历史会重新保存。** 如果客户端编辑或删除了之前的消息、在回答保存后重新生成,或者压缩了对话,网关会把当前的完整历史保存到一个新的 OpenViking 会话。已经保存的轮次留在旧会话里。
-- **客户端保留完整历史。** 网关压缩对话后,客户端仍会发送完整历史,网关在每个请求里把压缩位置之前的部分换成摘要。压缩之后客户端看到的用量很小,按 token 用量决定是否压缩的客户端很少再自己压缩,所以特别长的会话最终可能碰到请求大小上限。
-- **一个密钥只对应一位记忆归属者。** 使用同一个密钥的人共享其背后 OpenViking 用户的记忆。请给每人签发一个密钥;想让不同客户端使用不同的上下文配置,就按客户端再分开签发。
-- **不支持订阅登录。** 携带 Claude 订阅令牌的请求会被拒绝。请在上游配置服务商的 API Key。
-- **Responses 需要完整历史。** 依赖服务商端状态的 Responses 请求(`previous_response_id`、`conversation`、`background`),以及没有设置 `store: false` 的请求,会直接转发,不补充记忆。之后查询这些响应时,请求仍然发往创建它们的上游。
+- **召回最多等 2 秒。** 每条新消息的第一次模型调用要等 OpenViking 检索完成,最多等上下文配置里的**超时时间**(默认 2 秒)。OpenViking 超时或不可用时,这条消息不带记忆直接发给模型,之后也不会补上。
+- **设置只对新对话生效。** 一段对话始终使用它开始时的上下文配置和上游。Claude Code、Codex 这类长期运行的客户端会把一段对话延续很多天,修改上下文配置后要等它们开始新对话才生效。对话闲置 30 天后,网关删除它的状态。
+- **改动过的历史会重新保存。** 客户端编辑或删除了之前的消息、在回答保存后重新生成,或者自己压缩了对话时,网关把当前的完整历史保存到一个新的 OpenViking 会话,已经保存的轮次留在旧会话里。
+- **特别长的会话可能碰到请求大小上限。** 网关压缩对话后,客户端仍发送完整历史,但看到的用量很小,所以按用量决定何时压缩的客户端很少再自己压缩。请求体超过 32 MiB 会被拒绝,运维人员可以调整这个上限,见[长对话](22-gateway-operations.md#长对话)。
+- **一个密钥只对应一位记忆归属者。** 共用一个密钥的人共享其背后 OpenViking 用户的记忆。请给每人签发一个密钥;想让不同客户端使用不同的上下文配置,再按客户端分开签发。
+- **不支持订阅登录。** 带 Claude 订阅令牌的请求会被拒绝。请为上游配置服务商的 API Key。
+- **Responses 需要完整历史。** 依赖服务商端状态的 Responses 请求(`previous_response_id`、`conversation`、`background`),以及没有设置 `store: false` 的请求,直接转发,不补充记忆。之后查询这些响应时,请求仍然发往创建它们的上游。
- **其他接口直接转发。** 三种模型 API 和模型列表之外的接口(例如 embeddings)不补充记忆,直接转发给密钥绑定的、提供所请求模型且优先级最高的上游。
-- **请求有大小上限。** 超过 32 MiB 的请求体会被拒绝,运维人员可以调整这个上限。
## 下一步
-- [OpenViking 网关部署与运维](22-gateway-operations.md):用 Docker Compose 或 Helm 部署,管理上游、上下文配置和密钥,排查问题。
+- [OpenViking 网关部署与运维](22-gateway-operations.md):用 Docker Compose、Helm 或独立进程部署,管理上游、上下文配置和密钥,排查问题。
+- [OpenViking 网关管理 API](../api/25-gateway.md):权限矩阵和管理接口。
- [认证](04-authentication.md):创建账号、用户和他们的密钥。
- [公网访问与反向代理](12-public-access.md):为 OpenViking 配置 HTTPS。
- [Agent 集成概览](../agent-integrations/01-overview.md):为支持插件的 Agent 安装插件。
diff --git a/docs/zh/guides/17-vikingbot.md b/docs/zh/guides/17-vikingbot.md
index 197143197..cd1a66dfa 100644
--- a/docs/zh/guides/17-vikingbot.md
+++ b/docs/zh/guides/17-vikingbot.md
@@ -98,7 +98,7 @@ openviking-server doctor
详细配置见 [OpenViking 配置指南](01-configuration.md)。VikingBot 默认继承根级 `vlm` 作为 Agent 模型,因此通常不需要重复配置 `bot.agents`。
-Server 使用 `api_key` 模式时,先注册 User/Admin Key 并写入 `bot.ov_server.api_key`;不能把 root 管理 Key 当作用户 Key 使用。操作见[认证指南](04-authentication.md)。继承 `trusted` 模式时,Bot 使用服务端的可信身份配置。
+Server 使用 `api_key` 模式时,先注册 User/Admin Key 并写入 `bot.ov_server.api_key`;不能把 root API 密钥当作用户 Key 使用。操作见[认证指南](04-authentication.md)。继承 `trusted` 模式时,Bot 使用服务端的可信身份配置。
### 2. 一体启动
diff --git a/docs/zh/guides/22-gateway-operations.md b/docs/zh/guides/22-gateway-operations.md
index 9947469b0..11e02db3c 100644
--- a/docs/zh/guides/22-gateway-operations.md
+++ b/docs/zh/guides/22-gateway-operations.md
@@ -1,613 +1,587 @@
---
-description: 用 Docker Compose、Helm 或自建反向代理部署 OpenViking 网关,在 Studio 中管理网关并排查问题。
+description: 用 Docker Compose、Helm 或独立进程部署 OpenViking 网关,在 Studio 中管理网关并排查问题。
---
# OpenViking 网关部署与运维
-本页写给负责运行 OpenViking 网关的人,内容包括部署网关,在 Studio 中管理上游、上下文配置和密钥,保护数据,日常运维,以及排查问题。网关能做什么、客户端怎么接入,见[OpenViking 网关](15-gateway.md);整体架构见其中的[一张图看懂架构](15-gateway.md#一张图看懂架构)。
+本页写给运行 OpenViking 网关的人:怎么部署,怎么在 Studio 中管理上游、上下文配置和密钥,数据存在哪里、怎么备份,以及出了问题怎么查。网关能做什么、客户端怎么接入,见[OpenViking 网关](15-gateway.md);整体结构见[一张图看懂架构](15-gateway.md#一张图看懂架构)。
-网关目前处于 Beta 阶段,设置和接口可能随版本调整,升级前请先阅读发布说明。
+网关目前处于 Beta 阶段,设置和接口可能随版本调整,升级前请先读发布说明。
-网关是独立于 OpenViking Server 的进程,默认监听 1935 端口。客户端把模型请求发给网关;管理网关则在 Studio 中进行,Studio 由 OpenViking Server 提供,管理操作经 OpenViking Server 转发给网关。两者之间只走 HTTP:网关调用 OpenViking 的公开接口搜索记忆、保存对话和执行工具,OpenViking Server 则调用网关的管理接口。下图是对外只开一个 HTTPS 地址时的请求路径:
+## 环境要求
-```text
- 客户端
- |
- v
- 反向代理 (https://ov.example.com)
- | |
- | /v1/* | 其他路径:
- | /api/v3/* | /studio、/api/v1、
- | /api/compatible/v1/* | /mcp、/health 等
- | /gateway/uploads |
- v v
- OpenViking 网关 :1935 <----- 管理 ---- OpenViking Server :1933
- | | ^
- | +-------- 搜索、保存、工具 --------+
- v
- 模型服务商 (上游)
-```
+- **OpenViking 的认证方式**:`api_key` 或本地 dev 模式。网关不支持 trusted 认证。
+- **OpenViking 版本**:嵌入运行时和 Server 同版本发布,无需额外检查;独立运行时要求 OpenViking Server 0.4.16 或更高版本。
+- **安装**:网关包含在 OpenViking 核心包中。可选的 `gateway-fast` extra(`pip install "openviking[gateway-fast]"`)装上更快的事件循环和 HTTP 解析器。
+- **登录身份**:远程部署需要 OpenViking API 密钥,普通用户、账号管理员和 root 都能登录 Studio 的网关页面。本地 dev 模式不需要密钥,固定使用 `default/default` 身份。
+- **存储**:本地磁盘。网关的 SQLite 数据库只供一台主机使用,不支持网络文件系统或跨主机共享存储。
-## 环境要求
+## 密钥和凭证
-- **OpenViking Server 0.4.16 或更高版本,并运行在 API Key 模式**(`server.auth_mode: "api_key"`,同时配置 `root_api_key`)。网关用每个人自己的 OpenViking 密钥,以这个人的身份访问 OpenViking。dev 模式下任何密钥都按 root 身份处理,而网关不接受 root 身份,所以一个网关密钥也签发不了。
-- **网关本身**:在 Python 3.10 或更高版本上安装 `openviking[gateway]` 可选依赖,或者使用官方 OpenViking Docker 镜像,镜像里已经包含 `openviking-gateway` 命令。
-- **用于 Studio 的账号管理员密钥。** 你在 Studio 中配置的内容,都属于登录所用密钥所在的账号。root key 也能用,但它管理的是它解析到的那个账号,所以优先使用账号管理员的密钥。
-- **每位领取网关密钥的人都要是同一账号中的 OpenViking 用户**,普通用户和管理员都可以,root 不行。签发时由 OpenViking Server 读取这个用户的 OpenViking 密钥;如果它只保存密钥哈希,就需要这个用户自己提供密钥。
-- **模型服务商的 API Key。** 订阅登录会被拒绝;Coding Plan 密钥默认也会被拒绝,除非你明确允许。
-- **单台主机上的本地磁盘**,用于网关存储(默认 `~/.openviking/gateway`)。不支持网络文件系统,也不支持在多台主机之间共享存储。同一时间只运行一个网关实例;需要更多处理能力时增加工作进程,见[扩展](#扩展)。
-- **加密密钥和管理令牌**,见下一节。
+网关涉及四种密钥,各管一件事:
-## 加密密钥和管理令牌
+| 密钥 | 用途 | 在哪里使用 |
+| --- | --- | --- |
+| OpenViking API 密钥 | 登录 Studio;决定以哪个账号、哪个用户的身份读写记忆 | 管理请求的 `X-API-Key` 或 `Authorization: Bearer` |
+| 网关密钥(`ovgw_…`) | 客户端接入;每把绑定一位用户、一份上下文配置和一组上游 | 客户端的 API Key 输入框 |
+| 网关管理密钥(可选) | 限制谁能修改上游和上下文配置 | `gateway.management_key`;请求头 `X-OpenViking-Gateway-Management-Key` |
+| 上游 API Key | 调用模型服务商 | 上游编辑页 |
-| 名称 | 环境变量 | 谁需要 | 作用 |
-| --- | --- | --- | --- |
-| 加密密钥 | `OPENVIKING_GATEWAY_ENCRYPTION_KEY` | 网关 | 加密网关存储的全部数据:上游 API Key 和请求头、绑定到网关密钥的 OpenViking 密钥、对话状态和请求日志。必须是 Fernet 密钥,即 32 字节随机数的 URL 安全 base64 编码。 |
-| 管理令牌 | `OPENVIKING_GATEWAY_ADMIN_TOKEN` | 网关和 OpenViking Server | 你在 Studio 中操作时,OpenViking Server 用它向网关的管理接口证明身份。至少 32 个字符。 |
+网关没有自己的加密密钥,本地存储按 OpenViking 的加密配置加密,见[加密](#加密)。
-两者各生成一次:
+### 网关管理密钥
-```bash
-# 加密密钥(格式与 cryptography 包中 Fernet.generate_key() 的输出相同)
-python3 -c 'import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())'
+不设置管理密钥时,账号内每个登录的用户都能添加和修改本账号的上游和上下文配置。设置之后,只有带上这把密钥的请求能修改它们,OpenViking 的 admin 和 root 也不例外;其他人只能查看、测试,并在签发密钥时选用。管理密钥不限制谁能登录,也不限制用户给自己签发网关密钥。完整的权限规则见[权限矩阵](../api/25-gateway.md#凭证和账号范围)。
-# 管理令牌
-python3 -c 'import secrets; print(secrets.token_urlsafe(48))'
-```
+设置方法:
+
+- **`openviking-server init`**(嵌入):远程部署回答 **Allow users to configure their own gateway upstreams?** 时选 no,init 会生成一个以 `ovgm_` 开头的值,打印出来并写入 `ov.conf` 的 `gateway.management_key`。
+- **`openviking-gateway init`**(独立):回答 **Require a management key to change upstreams and profiles?** 时选 yes,init 会生成一个 `ovgm_` 开头的值,只打印一次,并写入 `gateway.conf` 的 `management_key`。
+- **手动设置**:值至少 32 个字符,可以用 `openssl rand -base64 32` 生成。写进 `management_key`,或者设置环境变量 `OPENVIKING_GATEWAY_MANAGEMENT_KEY`;两种部署下环境变量都优先于配置文件,见[配置参考](#配置参考)。
+- **Compose 和 Helm**:Compose 会把 `OPENVIKING_GATEWAY_MANAGEMENT_KEY` 传进容器;Helm 从 `gateway.existingSecret` 指定的 Secret 中读取 `management-key` 字段。见 [Docker Compose](#docker-compose) 和 [Helm](#helm)。
+
+管理密钥不提供命令行参数,因为命令行参数会出现在进程列表和 shell 历史里。设置、更换或去掉管理密钥后需要重启,这不会吊销已签发的网关密钥,也不会改动已有的上游和上下文配置。
+
+### 加密
+
+网关用 OpenViking 自己的加密功能保护已存的凭证和对话状态(见[加密指南](08-encryption.md)):
-把它们放进密钥管理系统或部署环境,不要写进 `ov.conf`,也不要提交到代码仓库。如果要从其他名称的环境变量读取,在 `gateway` 中设置 `encryption_key_env` 和 `admin_token_env`。
+- **嵌入**:网关沿用 Server 在 `ov.conf` 中的 `encryption` 段,不需要为网关单独设置。
+- **独立**:在 `gateway.conf` 中加一个 `encryption` 块,字段和 `ov.conf` 的 `encryption` 段完全相同,例如:
-- **加密密钥不能更换。** 网关不会重新加密已存储的数据,换了密钥就读不出原来的内容。请把密钥和网关存储一起备份。密钥丢失后,只能把 `storage_path` 指向一个空目录,重新配置上游、上下文配置和密钥。
-- **管理令牌可以轮换。** 给两个进程设置相同的新值,然后都重启。它只保护管理接口,不加密任何数据。
-- 缺少有效的加密密钥或管理令牌时,网关在启动阶段就会退出。OpenViking Server 没有管理令牌也能启动,但 Studio 的 OpenViking 网关页面会提示缺少管理令牌。
+ ```json
+ {
+ "openviking_url": "https://ov.example.com",
+ "encryption": {
+ "enabled": true,
+ "provider": "local",
+ "local": { "key_file": "~/.openviking/master.key" }
+ }
+ }
+ ```
+
+加密关闭或没有这个块时,网关以明文存储,只靠文件权限保护。之后再开启加密不会出问题:已有的明文值照常可读,新写入的值会加密。反过来,关闭加密或换一把根密钥后,已加密的值就读不出来了,所以要保持写入时的加密设置。按加密指南备份根密钥,丢了它,网关的数据库就无法读取。
+
+v0.5 网关用自己的密钥加密数据,这些数据会在首次启动时转换,见[迁移](#迁移)。
## 部署
### 部署方式
-网关和 OpenViking 之间只走 HTTP,所以可以装在同一台机器、放在同一个 Pod,也可以分开部署。无论哪种形态,都要满足[环境要求](#环境要求):OpenViking 0.4.16 或更高版本并开启 API Key 认证,网关存储放在一台主机的本地磁盘上,同一时间只运行一个网关实例,网关持有加密密钥,两个进程配置同一个管理令牌。负载均衡、故障转移和限流交给接在网关后面的 LiteLLM 或 new-api。
+| 方式 | 怎么开启 | 客户端地址 |
+| --- | --- | --- |
+| 嵌入 Server(包括 Compose 和 Helm) | 在 `ov.conf` 中开启 `gateway.enabled` | Server 地址加 `/gateway`,默认 `http://127.0.0.1:1933/gateway` |
+| 独立运行 | 先 `openviking-gateway init`,再 `openviking-gateway` | 网关自己的地址加 `/gateway`,默认 `http://127.0.0.1:1935/gateway` |
-| 形态 | 适合 | 怎么部署 | 要留意 |
-| --- | --- | --- | --- |
-| 单机 | 个人试用 | 安装 `openviking[gateway]`,运行 `openviking-gateway`,和 OpenViking 读取同一份 `ov.conf`,步骤见[快速开始](15-gateway.md#快速开始)。 | 只在本机使用时可以不配反向代理。 |
-| [Docker Compose](#docker-compose) | 小团队、单台服务器 | 网关是单独的容器,自带的 Caddy 在 1934 端口按路径分流。 | 网关端口不映射到主机;加密密钥只传给网关容器。 |
-| [Helm](#helm) | Kubernetes | 网关作为 OpenViking Pod 里的第二个容器,共用存储卷和 `ov.conf`。 | 保持一个副本;Chart 不支持把网关拆成单独的 Pod。 |
-| [分开部署](#分开部署) | 网关和 OpenViking 在不同的机器或 Pod | 自己编写 Deployment 或服务定义,两边的 `ov.conf` 放同一份 `gateway` 配置。 | 两边互相要能访问;链路上传输用户的 OpenViking 密钥;网络延迟会占用召回的等待时间。 |
+两种方式都在 `/gateway` 下提供相同的模型路径和管理路径。嵌入部署不需要第二个进程,也不需要按路径分流的反向代理;独立部署不用改动已有 OpenViking 服务的配置。
-两个进程读取同一个 `ov.conf` 中的 `gateway` 部分。OpenViking Server 用它找到网关,供 Studio 和数据删除使用;网关则用到整个部分。这一部分有几条规则:
+### 在 Server 中启用
-- 网关读取 `--config` 指定的文件,没有指定时读取 `OPENVIKING_CONFIG_FILE`,再没有就读取 `~/.openviking/ov.conf`。与 OpenViking Server 不同,它不会回退到 `/etc/openviking/ov.conf`。
-- 网关不展开 `$VAR` 或 `${VAR}` 占位符。`gateway` 中请写字面值,密钥和令牌放在上面的环境变量里。
-- 未知的键会报错。OpenViking Server 报告 `Unknown config field 'gateway.<name>'`,网关则拒绝启动。
-- 修改这一部分后,要重启 OpenViking Server。
+运行 `openviking-server init`,在 **Enable OpenViking Gateway on the same port?** 处回答 yes,然后启动或重启服务。已有配置时,在菜单中选择 **Update gateway**。远程部署还会询问是否允许用户自行配置上游,见[网关管理密钥](#网关管理密钥)。
-其中三个地址容易混淆:
+也可以手动把下面的内容合并进 `ov.conf`,再重启:
-| 设置 | 谁使用 | 常见取值 |
-| --- | --- | --- |
-| `url` | OpenViking Server,用来访问网关的管理接口 | `http://127.0.0.1:1935`;Docker Compose 中为 `http://gateway:1935` |
-| `openviking_url` | 网关,用来访问 OpenViking Server | `http://127.0.0.1:1933`;Docker Compose 中为 `http://openviking:1933` |
-| `public_url` | 客户端。Studio 的接入说明显示这个地址,OpenViking 工具也用它生成上传链接。 | `https://ov.example.com` |
+```json
+{
+ "gateway": {
+ "enabled": true
+ }
+}
+```
+
+使用 API 密钥的服务端上,root 也可以在 Studio 的 OpenViking 网关页面点**开启网关**:Studio 会把 `gateway.enabled: true` 写入 `ov.conf` 并重启服务(从 Studio 重启要求服务端只有一个 worker,否则 Studio 只保存文件,需要你自行重启)。
+
+打开服务端的 `/studio/`,在侧边栏选择 **OpenViking 网关**。dev 模式下,如果默认账号还没有上游,网关启动时会导入服务端可用的 VLM 凭证作为上游,并创建 `default` 上下文配置。导入的 Coding Plan 上游需要确认后才能使用;没有可导入的凭证时,请手动添加上游。
+
+**让 Agent 修改配置。** 持有 root API 密钥的 Agent 可以通过[运行时配置接口](../api/08-admin.md#runtime-configuration)修改 `ov.conf` 并重启服务。独立网关不提供这组接口。
### 路由
-让 OpenViking Server 和网关共用同一个公网 HTTPS 地址,由反向代理按路径分流:
+两种部署方式下,网关的所有 URL 都在 `/gateway` 下。嵌入部署中,Server 把整个 `/gateway` 前缀交给网关,其他路径仍由 Server 自己处理:
-| 路径 | 转发到 | 用途 |
-| --- | --- | --- |
-| `/v1/*` | 网关 | Anthropic Messages、Chat Completions、Responses 和模型列表 |
-| `/api/v3/*` | 网关 | 方舟路径(火山方舟和 BytePlus 方舟)下的 Chat Completions、Responses 和模型列表 |
-| `/api/compatible/v1/*` | 网关 | 方舟的 Anthropic 兼容路径 |
-| `/gateway/uploads` | 网关 | OpenViking 工具的一次性文件上传 |
-| 其他所有路径 | OpenViking Server | Studio、REST API、MCP、OAuth、`/health` |
+| 路径前缀 | 用途 |
+| --- | --- |
+| `/gateway/v1/` | 模型 API 和模型列表 |
+| `/gateway/api/v3/` | 方舟兼容客户端 |
+| `/gateway/api/compatible/v1/` | 方舟 Anthropic 兼容客户端 |
+| `/gateway/uploads` | 工具上传 |
+| `/gateway/admin/` | 管理 API,需要认证 |
-按这种布局,`public_url` 就填这个公网地址,例如 `https://ov.example.com`。Anthropic 客户端直接使用这个地址,OpenAI 风格的客户端在后面加上 `/v1`。
+因此客户端使用下面的 Base URL,把 `http://127.0.0.1:1933` 换成你的 Server 地址即可:
-> **安全**:不要从公网入口转发网关的 `/admin/*` 路径,也不要直接暴露网关端口。网关的管理接口只认管理令牌,持有令牌就能管理任何账号。Studio 经由 OpenViking Server 访问管理接口,OpenViking Server 会确认你是账号管理员,并把每次调用限制在你自己的账号内。只转发上面四组路径,1933 和 1935 端口都留在代理后面,不对外开放。
+| 客户端 | Base URL |
+| --- | --- |
+| Claude Code 和 Anthropic SDK | `http://127.0.0.1:1933/gateway` |
+| OpenAI 兼容的客户端和 SDK,包括 Codex、OpenCode、pi 和 Open WebUI | `http://127.0.0.1:1933/gateway/v1` |
+| 火山方舟和 BytePlus 方舟 SDK | `http://127.0.0.1:1933/gateway/api/v3` |
-不管用哪种代理,网关路径都要按长时间的流式模型调用来配置:
+`/health` 仍是 Server 自己的健康检查,嵌入网关不单独提供 `/health`。
-- **关闭响应缓冲**,流式回复才能边生成边送达客户端。
-- **请求体上限至少 32 MiB**(`max_body_bytes`)。带工具输出的长对话请求体很大,nginx 默认的 1 MB 会让这些请求失败。
-- **读超时至少 600 秒**(`upstream_timeout_seconds`)。
-- **`/gateway/uploads` 的访问日志不记录查询字符串**,因为里面带有一次性上传令牌。网关本身不写访问日志。
+独立网关在自己的端口上提供同样的 `/gateway` 路径,另外在根路径提供:
-### Docker Compose
+- `/` 跳转到 `/studio/`,Studio 只包含网关和连接页面。
+- `/health` 返回 `service: "openviking-gateway"`、`auth_mode` 和 `openviking_url`;请求带有效的 OpenViking 凭证时,还返回调用方身份。
-仓库自带的 `docker-compose.yml` 在 `gateway` profile 下定义了 `gateway` 服务。它与 OpenViking Server 使用同一个镜像、同一个 `~/.openviking` 挂载和同一个 `ov.conf`。它的 1935 端口只在 Compose 网络内可达,客户端通过自带的 Caddy 访问网关,Caddy 已经在 1934 端口把网关路径转发过去。
+**对外地址。** 共享部署要把 `public_url` 设为客户端访问 Server(或独立网关)的地址,不带 `/gateway`,网关会自己加上。嵌入网关不设置时,沿用 Server 的对外地址(`OPENVIKING_PUBLIC_BASE_URL` 或 `server.public_base_url`)。Studio 的接入指南用它生成配置:Anthropic 客户端使用 `<public_url>/gateway`,OpenAI 风格的客户端使用 `<public_url>/gateway/v1`。不设置时,指南使用浏览器访问 Studio 的地址;但文件导入的上传链接必须依赖 `public_url`,见[导入文件和技能](#导入文件和技能)。
-1. **把加密密钥和管理令牌写进 `.env`**,放在 `docker-compose.yml` 旁边:
+### Docker Compose
- ```dotenv
- OPENVIKING_GATEWAY_ENCRYPTION_KEY=<encryption-key>
- OPENVIKING_GATEWAY_ADMIN_TOKEN=<admin-token>
- ```
+在 `.env` 中设置 `OPENVIKING_GATEWAY_ENABLED=true`,然后运行 `docker compose up -d`;也可以在挂载的 `ov.conf` 里开启 `gateway.enabled`。网关在 `openviking` 服务内运行,不需要单独的服务或 profile。不用 Compose 时,`docker run` 加上 `-e OPENVIKING_GATEWAY_ENABLED=true` 即可:
- Compose 把管理令牌传给两个容器,加密密钥只传给网关。其中任何一个为空,网关都会退出,Compose 则会不停地重启它。
+```bash
+docker run -d -p 1933:1933 -v ~/.openviking:/app/.openviking \
+ -e OPENVIKING_GATEWAY_ENABLED=true \
+ ghcr.io/volcengine/openviking:latest
+```
-2. **把以下设置合并进 `~/.openviking/ov.conf`:**
+容器内 Server 监听 `0.0.0.0`,所以 `ov.conf` 要使用 API 密钥认证。
- ```json
- {
- "server": {
- "auth_mode": "api_key",
- "root_api_key": "<root-key>"
- },
- "gateway": {
- "enabled": true,
- "host": "0.0.0.0",
- "url": "http://gateway:1935",
- "openviking_url": "http://openviking:1933",
- "public_url": "http://<your-host>:1934"
- }
- }
- ```
+- **管理密钥**:在 `.env` 中设置 `OPENVIKING_GATEWAY_MANAGEMENT_KEY`,自带的 Compose 文件会把它传进容器;也可以写进挂载的 `ov.conf` 的 `gateway.management_key`。Compose 文件还会传入 `OPENVIKING_GATEWAY_ENCRYPTION_KEY`,它只在迁移 v0.5 数据时读取一次,见[迁移](#迁移)。
+- **对外地址**:设置 `OPENVIKING_PUBLIC_BASE_URL`(自带的 Compose 文件会传入)即可,网关没有单独配置 `public_url` 时沿用它。
+- **修改配置后**:执行 `docker compose restart openviking`;启动错误用 `docker compose logs openviking` 查看。
- 客户端还在访问自带 Caddy 的端口时,使用 `http://<your-host>:1934`;配好 HTTPS 地址之后改用它。`storage_path` 可以保持默认:在容器内它解析为 `/app/.openviking/gateway`,正好位于挂载卷中。
+自带的 Caddy 把所有路径转发到 `openviking:1933`。可以继续用兼容端口 1934,也可以直接访问 Server 的 1933。配置 HTTPS 时,一条 `reverse_proxy openviking:1933` 就能承载 Studio、管理接口和模型流量,见[公网访问](12-public-access.md)。
-3. **带上 profile 启动:**
+### Helm
- ```bash
- docker compose --profile gateway up -d
- ```
+在 chart values 中设置 `gateway.enabled: true`。网关嵌入 server 容器,数据保存在 `<persistence.mountPath>/gateway`,Service 和 Ingress 都使用 Server 端口。保持 `replicaCount: 1`。
- 之后执行 `up` 时也要带上 `--profile gateway`。修改 `ov.conf` 后,用 `docker compose --profile gateway restart openviking gateway` 重启两个容器。
+```yaml
+gateway:
+ enabled: true
+ existingSecret: "" # 可选:Secret 名称,字段 management-key
+config:
+ gateway:
+ public_url: https://ov.example.com
+```
-4. **检查路由。** 不带密钥的请求应该到达网关并被拒绝:
+- 网关和 Server 一样,按 chart 的 `config.encryption` 设置加密数据。
+- `existingSecret` 指定的 Secret 中有 `management-key` 字段时,修改上游和上下文配置需要这把管理密钥。
+- 模型请求是流式的:Ingress 要关闭响应缓冲,允许至少 32 MiB 的请求体和 600 秒超时。
- ```bash
- curl -s http://127.0.0.1:1934/v1/models
- # {"detail":"Invalid or revoked OpenViking Gateway key"}
- ```
+NGINX annotations、创建 Secret 的命令和从 sidecar 版本升级的说明见 [chart README](https://github.com/volcengine/OpenViking/blob/main/deploy/helm/README.md#openviking-gateway)。
- 然后打开 Studio,确认“概览”标签页显示 OpenViking 已连接。启动错误可以用 `docker compose logs gateway` 查看。
+### 独立部署
-如果网关启动时 OpenViking Server 还没有就绪,网关会先在不带记忆的状态下运行,直到下一次检查 OpenViking,最多等 60 秒(`health_interval_seconds`)。这段时间里发出的消息不带记忆直接发给模型。
+独立网关不读取 `ov.conf`,只需要知道 OpenViking 的地址,已有的开源版或商业版服务不用改配置:
-**HTTPS。** 按[公网访问与反向代理](12-public-access.md#添加-https公网访问)中的方式 A 设置 `OPENVIKING_PUBLIC_BASE_URL`、开放 80 和 443 端口并添加 Caddy 卷,但 `Caddyfile` 中的域名块改用下面这段,让网关路径转发到网关:
+```bash
+openviking-gateway init # 写入 ~/.openviking/gateway.conf
+openviking-gateway
+```
-```caddyfile
-{$OPENVIKING_PUBLIC_BASE_URL} {
- @gateway path /v1/* /api/v3/* /api/compatible/v1/* /gateway/uploads
- handle @gateway {
- reverse_proxy gateway:1935 {
- flush_interval -1
- }
- }
- handle {
- reverse_proxy openviking:{$OPENVIKING_SERVER_PORT:1933}
- }
+`openviking-gateway init` 依次询问 OpenViking 地址(会实际访问一次,并显示服务端的认证模式和版本)、监听地址(默认 `127.0.0.1:1935`),以及是否要求[管理密钥](#网关管理密钥)。结果写入 `~/.openviking/gateway.conf`,或者 `--config` 指定的文件,只有你自己能读。想修改设置就再运行一次:它把当前值作为默认值,已有的密钥不改就原样保留。生成的文件类似这样:
+
+```json
+{
+ "openviking_url": "https://ov.example.com",
+ "host": "127.0.0.1",
+ "port": 1935
}
```
-然后把 `gateway.public_url` 设为同一个地址,并写成字面值(例如 `https://ov.example.com`),再重启。
+打开网关的 `/studio/`,用 OpenViking 用户、账号管理员或 root 的 API 密钥登录。连接页会显示网关连接的 OpenViking 地址。独立网关读不到远端服务的 VLM 配置,所以不能导入模型配置,上游要手动添加。
-### Helm
+**设置从哪里来。** 命令行只有 `--config` 一个参数。设置了 `--config` 或 `OPENVIKING_GATEWAY_CONFIG_FILE` 时,它必须指向已存在的文件;两者都没设置时,网关读取 `~/.openviking/gateway.conf` 和 `/etc/openviking/gateway.conf` 中第一个存在的文件。环境变量可以覆盖其中任何字段。容器里可以完全不用文件:设置 `OPENVIKING_GATEWAY_OPENVIKING_URL`,再按需加上 `OPENVIKING_GATEWAY_HOST=0.0.0.0` 之类的变量。两处都没有 OpenViking 地址时,网关退出,并提示运行 `openviking-gateway init` 或设置 `OPENVIKING_GATEWAY_OPENVIKING_URL`。全部字段和覆盖规则见[配置参考](#配置参考)。
-Chart 把网关作为 OpenViking Pod 中的第二个容器运行,与 OpenViking 共用存储卷和 `ov.conf`。
-
-1. **创建 Secret。** 键名 `encryption-key` 和 `admin-token` 是固定的:
-
- ```bash
- kubectl create secret generic openviking-gateway \
- --from-literal=encryption-key="$(python3 -c 'import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())')" \
- --from-literal=admin-token="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
- ```
-
-2. **在 values 中启用网关。** 下面的 NGINX Ingress 注解是针对流式响应和大请求的推荐配置,Chart 不会自动设置:
-
- ```yaml
- gateway:
- enabled: true
- existingSecret: openviking-gateway
- workers: 2
-
- config:
- server:
- auth_mode: api_key
- # 按 Chart README 的说明从 Secret 传入 root_api_key。
- gateway:
- public_url: https://ov.example.com
-
- ingress:
- enabled: true
- className: nginx
- annotations:
- nginx.ingress.kubernetes.io/proxy-buffering: "off"
- nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
- nginx.ingress.kubernetes.io/proxy-body-size: 32m
- nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
- nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
- hosts:
- - host: ov.example.com
- paths:
- - path: /
- pathType: Prefix
- tls:
- - secretName: ov-example-com-tls
- hosts:
- - ov.example.com
- ```
-
-values 中的 `gateway.enabled` 为 true 时,Chart 会:
-
-- 生成 `gateway` 部分的其余设置:`enabled`、`host: 0.0.0.0`、`port`、`workers`、`url: http://127.0.0.1:<port>`、`openviking_url: http://127.0.0.1:<config.server.port>` 和 `storage_path: <persistence.mountPath>/gateway`。你在 `config.gateway` 下写的值优先。`public_url` 就在那里设置,并写成字面值。
-- 把管理令牌传给两个容器,把加密密钥传给网关容器。网关容器不接收 `extraEnv`。
-- 在 Service 上添加 `gateway` 端口。启用 Ingress 时,把 `/v1`、`/api/v3`、`/api/compatible/v1` 和 `/gateway/uploads` 路由到这个端口,并排在你自己的路径之前。
-- 为网关的 `/health` 添加就绪探针。`gateway.resources` 设置网关容器的资源请求和限制。
-
-保持 `replicaCount: 1`。网关的存储位于 ReadWriteOnce 卷上,只能由一台主机使用;需要更多处理能力时,调大 `gateway.workers`。如何从 Secret 传入 root key 和模型密钥,见 [Chart README](https://github.com/volcengine/OpenViking/blob/main/deploy/helm/README.md)。
-
-### 分开部署
-
-网关和 OpenViking 运行在不同的机器或 Pod 上时,Chart 和 Compose 文件不再适用,需要自己编写部署定义。两边的 `ov.conf` 放同一份 `gateway` 配置,并注意以下几点:
-
-- **两个方向的地址都要填。** 网关通过 `openviking_url` 访问 OpenViking;OpenViking Server 通过 `url` 访问网关,Studio 的管理操作和删除用户数据都经过这个地址。两个地址都应该是内网地址,网关的 `host` 要监听对方能访问的网卡。
-- **保护两者之间的链路。** 网关调用 OpenViking 时带着用户自己的 OpenViking 密钥,管理请求也带着管理令牌,所以这段链路要走内网或 TLS。
-- **留意延迟。** 每条新消息的召回最多等上下文配置中的**超时时间**(默认 2 秒),网关到 OpenViking 的网络延迟也算在里面。延迟较高时,召回更容易超时,消息就不带记忆发给模型。
-- **注意版本匹配。** 两边分别升级时,先升级 OpenViking,再升级网关,见[升级](#升级)。
-
-### 自建反向代理
-
-nginx 与两个进程在同一台主机上时,把网关路径写在兜底的 location 之前:
-
-```nginx
-server {
- listen 443 ssl;
- http2 on; # nginx < 1.25.1:删掉这一行,改用 `listen 443 ssl http2;`
- server_name ov.example.com;
-
- ssl_certificate /etc/letsencrypt/live/ov.example.com/fullchain.pem;
- ssl_certificate_key /etc/letsencrypt/live/ov.example.com/privkey.pem;
-
- # 模型 API:流式回复、很长的历史、响应慢的模型。
- location ~ ^/(v1|api/v3|api/compatible/v1)/ {
- proxy_pass http://127.0.0.1:1935;
- proxy_http_version 1.1;
- proxy_buffering off;
- proxy_request_buffering off;
- client_max_body_size 32m;
- proxy_read_timeout 600s;
- proxy_send_timeout 600s;
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-Proto $scheme;
- }
+**启动检查。** 独立网关启动前会先访问一次 OpenViking:
- # 一次性文件上传。查询字符串里带着上传令牌。
- location = /gateway/uploads {
- proxy_pass http://127.0.0.1:1935;
- proxy_http_version 1.1;
- proxy_request_buffering off;
- client_max_body_size 32m;
- proxy_read_timeout 120s;
- access_log off;
- }
+- OpenViking 使用 trusted 认证时,网关拒绝启动。
+- 绑定非回环地址时,必须确认 OpenViking 使用 `api_key` 认证才会启动;OpenViking 连不上或处于 dev 模式时,网关直接退出。请先启动 OpenViking,或者只绑定 `127.0.0.1`。
+- 跨主机连接 OpenViking 时,请使用 TLS 或私有网络。
+
+**连接公共 OpenViking 服务。** 连接 `https://api.vikingdb.cn-beijing.volces.com/openviking` 且没有设置管理密钥时,启动日志和 Studio 都会显示 `public_openviking_without_management_key` 告警:任何持有该服务 API 密钥的人都能登录这台网关,并修改所在账号的上游。网关只给你自己或团队使用时,设置 `OPENVIKING_GATEWAY_MANAGEMENT_KEY` 后重启即可限制修改;这不限制谁能登录,也不限制他们给自己签发网关密钥。
- # Studio、REST API、MCP 和其他所有路径。
- location / {
- proxy_pass http://127.0.0.1:1933;
- proxy_http_version 1.1;
- proxy_buffering off;
- proxy_read_timeout 300s;
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_set_header X-Forwarded-Host $host;
+### 反向代理和 HTTPS
+
+把整个站点转发到 Server(嵌入)或网关(独立),不需要按路径分流。以 Caddy 为例:
+
+```caddyfile
+ov.example.com {
+ reverse_proxy 127.0.0.1:1933 {
+ flush_interval -1
}
}
```
-如果调大了 `max_body_bytes` 或 `upstream_timeout_seconds`,`client_max_body_size` 和各项超时也要一起调大。其他代理同样按这四组路径和[路由](#路由)一节列出的设置来配置。
+无论用哪种代理,都要满足三点:关闭响应缓冲,流式输出才能实时到达;允许至少 32 MiB 的请求体;读取超时至少 600 秒。另外,不要在代理日志中记录 `/gateway/uploads` 的查询字符串,其中带有一次性上传令牌。对外发布前先配置好认证,见[公网访问](12-public-access.md)。
### 扩展
-- **工作进程。** `workers`(1–64;默认 1,Helm Chart 中为 2)决定主机上运行几个网关进程。它们共用存储文件,每个进程还会在后台保存对话。
-- **单台主机。** 不支持在多台主机上运行网关,也不支持网络文件系统。使用 Helm 时保持一个副本。
-- **变更传播。** 吊销密钥或编辑上游后,其他工作进程大约 2 秒内跟上。
-- **健康状态按进程计算。** 每个工作进程独立检查 OpenViking,所以“概览”标签页上的 OpenViking 状态来自恰好响应这次查询的那个进程。
-- **没有负载均衡和限流。** 每段对话固定在一个上游上,网关不会换一个上游重试,也不限流;服务商返回的 429 原样传给客户端。需要负载均衡、故障转移或配额时,在网关后面接 LiteLLM 或 new-api,再把它添加为上游。
+一个存储目录只供一台主机上的一套部署使用,嵌入网关和独立网关不能共用同一目录。嵌入网关跟随 Server 的 worker 设置;独立网关用 `workers` 设置,取值 1–64。需要在服务商之间负载均衡、故障转移或限流时,把 LiteLLM 这类服务添加为上游。
## 在 Studio 中管理网关
-在 OpenViking Server 上打开 `/studio`,进入**连接设置**,把账号管理员密钥填入**管理员 API 密钥**。侧边栏的“设置”分组里随即出现**OpenViking 网关**,只有账号管理员和 root 能看到它。这些页面上的所有内容都属于该密钥所在的账号。页面顶部显示客户端应该使用的网关地址,即 `public_url`;`public_url` 为空时显示 `url`,“接入”标签页会提示客户端可能连不上这个地址。
+用 OpenViking API 密钥连接 Studio 后,在侧边栏打开 **OpenViking 网关**。上游和上下文配置由整个账号共享,网关密钥和请求日志属于各个用户:
-如果网关没有配置好或者无法访问,页面会显示一张设置卡片,指出要修改哪项配置,见 [Studio 显示设置卡片](#studio-显示设置卡片)。否则页面有六个标签页:**概览**、**上游**、**上下文配置**、**密钥**、**请求日志**和**接入**。初次设置就按这个顺序:添加上游,创建上下文配置,签发网关密钥,最后按“接入”标签页的说明接入客户端。
+- **没有设置管理密钥**:每个登录的用户都能添加和修改本账号的上游和上下文配置。
+- **设置了管理密钥**:“上游”和“上下文配置”标签页变为只读,OpenViking 的 admin 和 root 也一样。只读时仍能查看和测试上游(看不到 API Key 和请求头),并在给自己签发密钥时选用。点**输入网关管理密钥**解锁编辑,页头会显示“可修改上游和上下文配置”;解锁状态保持到点击**锁定**或关闭浏览器标签页。管理密钥被更换后,Studio 会自动锁定。
+- **网关密钥**:每个人都能给自己签发;账号管理员可以给本账号的用户签发;root 先在侧边栏切换账号。见[网关密钥](#网关密钥)。
+
+上游和上下文配置保存后,立即对使用它们的密钥生效(上下文配置只影响之后开始的对话)。还没有可用的上游或上下文配置、自己又不能修改时,请联系部署网关的人。
### 上游
-上游是模型服务商的一个接口,只使用一种 API:Anthropic Messages、Chat Completions 或 Responses。网关不在它们之间做转换,所以客户端用到几种 API,就要添加几个上游,即使它们来自同一个服务商:Claude Code 用 Anthropic Messages,Codex CLI 用 Responses,大多数聊天应用和 SDK 用 Chat Completions。
+上游是模型服务的一个接口,只使用一种 API:Anthropic Messages、Chat Completions 或 Responses。网关不在 API 之间转换,所以客户端用到几种 API,就要添加几个上游,即使它们来自同一家服务商:Claude Code 用 Anthropic Messages,Codex CLI 用 Responses,大多数聊天应用和 SDK 用 Chat Completions。
-各服务商提供的协议如下。在编辑页选择服务商后,会自动填入它的默认 Base URL:
+在编辑页选择服务商后,会自动填入它的默认 Base URL:
| 服务商 | 协议 | 默认 Base URL |
| --- | --- | --- |
-| 通用 | 三种都有 | 无,需要自己填写 |
+| 通用 | 三种都有 | 无,自己填写 |
| Anthropic | Anthropic Messages | `https://api.anthropic.com` |
| OpenAI | Chat Completions、Responses | `https://api.openai.com/v1` |
| DeepSeek | 三种都有 | `https://api.deepseek.com`;Anthropic Messages 为 `https://api.deepseek.com/anthropic` |
-| 火山方舟 | 三种都有 | `https://ark.cn-beijing.volces.com` |
-| BytePlus 方舟(海外站) | 三种都有 | `https://ark.ap-southeast.bytepluses.com` |
-
-上游编辑页分为四部分。
+| 火山方舟 | 三种都有 | Chat Completions 和 Responses 为 `https://ark.cn-beijing.volces.com/api/v3`;Anthropic Messages 为 `https://ark.cn-beijing.volces.com/api/compatible` |
+| BytePlus 方舟(海外站) | 三种都有 | Chat Completions 和 Responses 为 `https://ark.ap-southeast.bytepluses.com/api/v3`;Anthropic Messages 为 `https://ark.ap-southeast.bytepluses.com/api/compatible` |
-**接口。**
+#### 接口
-- **服务商**决定可以选哪些协议,并让网关适配各家服务商的差异。编辑页只提供服务商支持的协议,见上表。列表里没有的服务商、LiteLLM 和 new-api 这类兼容代理,以及 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) 这类把订阅账号包装成 API 的反向代理,都选*通用*(见[自定义上游](15-gateway.md#自定义上游);用订阅额度时是否合规请自行确认)。
+- **服务商**决定可选的协议,并让网关适配各家的差异。列表里没有的服务商、LiteLLM 和 new-api 这类兼容代理,以及 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) 这类把订阅账号包装成 API 的反向代理,都选*通用*(见[自定义上游](15-gateway.md#自定义上游);用订阅额度是否合规请自行确认)。
- *通用*、*Anthropic* 和 *OpenAI* 转发请求的方式相同。
- - *DeepSeek*:请求带工具时,DeepSeek 要求历史里之前每条回复都带着推理内容,而很多聊天应用不会把推理内容发回来。DeepSeek 上游默认开启**补全推理内容回传**(见下文“路由”),所以请求保持思考模式也能得到 OpenViking 工具。关闭这项设置后,只有请求关闭了思考模式(`"thinking": {"type": "disabled"}`)时才提供 OpenViking 工具;标准的 Responses 请求没有 `thinking` 字段,这时也得不到工具。记忆照常补充。
- - *火山方舟*和它的海外站 *BytePlus 方舟*行为相同:请求发往方舟自己的路径。Chat Completions 和 Responses 的每段对话都使用一个固定的 `prompt_cache_key`,方舟的前缀缓存就能跟着对话走。如果请求的模型、思考模式、采样参数、系统提示词或工具与对话的第一个请求不同,就会被标记为**缓存参数有变化**(`ark_cache_parameters_changed`),因为这些参数一变,方舟就会重新建立缓存。
-- **协议**决定上游能处理哪些客户端请求,也决定网关如何发送密钥:Anthropic Messages 用 `x-api-key`,另外两种用 `Authorization: Bearer`。
-- **Base URL。** 选择服务商后,编辑页会填入上表中的默认地址。切换服务商或协议时,只有地址为空或仍是之前的默认地址,才会换成新的默认地址,自己填写的地址不会被覆盖;地址与默认地址不同时,点输入框下方的**使用默认地址**即可恢复。网关把客户端的请求路径拼接在后面,并去掉重复的 `/v1`,所以 `https://api.openai.com/v1` 和 `https://api.anthropic.com` 都能用。编辑页会显示请求实际发往的地址。火山方舟和 BytePlus 方舟请填写不带路径的地址,例如 `https://ark.cn-beijing.volces.com`,它适用于全部三种协议;以 `/api/v3` 结尾的地址只适用于 Chat Completions 和 Responses,以 `/api/compatible/v1` 结尾的只适用于 Anthropic Messages。API 路径不以 `/v1` 结尾的服务商(例如 `…/api/paas/v4`)不能直接使用,需要在中间加一个 LiteLLM 之类的兼容代理。
+ - *DeepSeek*:请求带工具时,DeepSeek 要求历史中之前每条回复都带推理内容,而很多聊天应用不回传它。DeepSeek 上游默认开启**补全推理内容回传**(见下文“路由和开关”),所以请求保持思考模式也能用 OpenViking 工具。关闭这项后,只有请求关闭了思考模式(`"thinking": {"type": "disabled"}`)才提供 OpenViking 工具;标准 Responses 请求没有 `thinking` 字段,这时也得不到工具。记忆照常补充。
+ - *火山方舟*和 *BytePlus 方舟*行为相同:Chat Completions 和 Responses 的每段对话使用一个固定的 `prompt_cache_key`,方舟的前缀缓存就能跟着对话走。请求的模型、思考模式、采样参数、系统提示词或工具和对话的第一个请求不同时,方舟会重建缓存,请求被标为**缓存参数有变化**(`ark_cache_parameters_changed`)。
+- **协议**决定上游接受哪种 API。Anthropic 上游同时发送 `x-api-key` 和 `Authorization: Bearer`,Chat Completions 和 Responses 上游只发送 Bearer。
+- **Base URL** 按服务商 SDK 文档填写,网关在后面拼接端点:
+ - Chat Completions 和 Responses 拼接 `/chat/completions` 或 `/responses`。只填域名时不会自动补 `/v1`,OpenAI 要写 `https://api.openai.com/v1`。
+ - Anthropic Messages 拼接 `/v1/messages`,所以 Base URL 不能以 `/v1` 结尾,否则保存时被拒绝。
+ - 末尾的斜杠会被去掉。`/api/paas/v4` 这类带版本路径的地址可以直接使用。
+ - 客户端用方舟路径(`/gateway/api/v3/`、`/gateway/api/compatible/v1/`)发来的请求,按同样的规则拼接。
+ - 一个上游只有一个 Base URL。同一服务商的不同协议地址不同时,要分别建上游:例如智谱 Chat Completions 用 `https://open.bigmodel.cn/api/paas/v4`,Responses 用 `https://open.bigmodel.cn/api/v1`。方舟 Coding Plan 的 Chat Completions 和 Responses 用 `…/api/coding/v3`,Anthropic Messages 用 `…/api/coding`。
+
+ 编辑页会实时预览最终的请求地址;OpenAI、方舟这类地址漏掉路径,或者 Anthropic 地址多了 `/v1` 时,会给出提示和一键修正。
-**凭证。**
+#### 凭证
- **API Key 由谁提供**:
- **由网关保管 API Key**(默认):网关发送上游的 API Key,客户端只需要网关密钥。
- - **每个客户端自带 API Key**:每个请求除了网关密钥,还要在 `X-OpenViking-Upstream-Key` 请求头里带上客户端自己的服务商 API Key。缺少这个请求头的请求返回 401 "Upstream API key is missing"。网关按服务商惯用的请求头把这个 API Key 传过去,`X-OpenViking-*` 请求头本身从不转发。
-- **API Key** 和**额外请求头**只能写入,不能读回。编辑上游时,API Key 留空表示保留已保存的值。额外请求头只显示名称:值留空表示保留,删除这一行表示删除这个请求头。已保存的 API Key 无法清空;不想再用它时,改为“每个客户端自带 API Key”,或者删除这个上游。
-- **额外请求头**会加到发往这个上游的每个请求上,例如服务商的版本或组织请求头,并覆盖客户端发送的同名请求头。不允许设置 `Host`、`Content-Length`、`Transfer-Encoding` 和 `Connection`。
-- **这是 Coding Plan 或订阅密钥。** 服务商通常只允许 Coding Plan 这类订阅密钥用在自家的编程工具里,通过共享网关使用可能导致订阅被封禁。勾选后,路由到这个上游的每个请求都会被拒绝,返回 403 "Coding Plan upstreams are disabled; configure a model API key",除非同时勾选**仍然允许**。网关无法从密钥本身分辨它是不是订阅密钥,需要你自己标记。Claude 订阅令牌(`sk-ant-oat…`)始终会被拒绝。
+ - **每个客户端自带 API Key**:每个请求除了网关密钥,还要在 `X-OpenViking-Upstream-Key` 请求头里带上客户端自己的服务商 API Key,缺少时返回 401 "Upstream API key is missing"。网关按服务商惯用的请求头转发这个 API Key,`X-OpenViking-*` 请求头本身从不转发。
+- **API Key 和额外请求头只写不读**:留空表示保留已存的值,删除请求头行就删除这个请求头。**修改 Base URL 会清除已存的 API Key 和请求头值**,所以每次改地址都要重新填写,已存的密钥不会被发往新地址。
+- **额外请求头**加在发往这个上游的每个请求上,例如服务商的版本或组织请求头,并覆盖客户端发送的同名请求头。不能设置 `Host`、`Content-Length`、`Transfer-Encoding` 和 `Connection`。
+- **这是 Coding Plan 或订阅密钥**:服务商通常只允许 Coding Plan 这类订阅密钥用在自家的编程工具里,通过共享网关使用可能导致订阅被封禁。勾选后,发往这个上游的请求一律被拒绝,返回 403 "Coding Plan upstreams are disabled; configure a model API key",除非同时勾选**允许通过网关使用这个套餐**。网关无法从密钥本身分辨它是不是订阅密钥,需要你自己标记。Claude 订阅令牌(`sk-ant-oat…`)始终被拒绝。
-**模型。**
+#### 模型
-- **模型**列出这个上游提供的模型名。留空表示接受任何名称。只有列出的名称和别名会出现在客户端可以请求的模型列表(`/v1/models`)中。
-- **模型别名**把客户端使用的名称映射为发给上游的模型,例如把 Claude Code 请求的 Claude 模型名映射到服务商提供的模型。别名会出现在模型列表中,请求日志显示的是客户端使用的名称。
-- **上下文窗口**以 token 为单位记录各个模型的上下文窗口(至少 1,024),键是经过别名映射、实际发给上游的模型名。长对话按这个窗口的比例触发压缩。没有列在这里的模型使用上下文配置的**默认上下文窗口**,那里也没有设置时按 1,000,000 token 计算,所以窗口更小的模型都要列出来,见[长对话](#长对话)。
+- **模型**列出这个上游提供的模型名,留空表示接受任何名称。只有列出的名称和别名会出现在模型列表(`/gateway/v1/models`)里。
+- **模型别名**把客户端使用的名称映射为发给上游的模型,例如把 Claude Code 请求的 Claude 模型名映射到服务商提供的模型。别名出现在模型列表中,请求日志显示客户端使用的名称。
+- **上下文窗口**按模型记录窗口大小(token,至少 1,024),键是映射之后、实际发给上游的模型名。长对话按窗口的比例触发压缩,窗口小于 1,000,000 token 的模型都要列出来,见[长对话](#长对话)。
-**路由。**
+#### 路由和开关
-- **优先级。** 对每个请求,网关从密钥绑定的已启用上游中挑出使用这种 API、并且提供所请求模型的那些,再选优先级最高的一个。只要原来的上游还能服务,对话就一直留在它开始时的上游上,所以修改优先级只影响新对话。
-- **启用。** 停用的上游不接收请求,也不出现在模型列表里。原本使用它的对话会转到下一个候选上游,这会造成一次服务商缓存未命中,并丢掉之前的 Claude 思考块;这些请求会被标记为**上游已切换**(`upstream_changed`)。想保留恢复的余地,就用停用代替删除。
-- **允许 OpenViking 工具**决定能否通过这个上游提供 OpenViking 工具。关闭后立即生效,已经带工具的对话也会受影响。
-- **补全推理内容回传。** 客户端回传历史时,常常丢掉模型之前回复里的推理内容。开启后,网关记下经它转发的每条回复的推理内容,在后续请求里放回原来的回复上:Chat Completions 补回 `reasoning_content`,Anthropic Messages 把 thinking 块放回原位,Responses 把带明文内容的 reasoning 项放回对应条目之前。每轮补回的内容逐字节相同,所以服务商的提示词缓存照常命中;补回的内容计入输入 token。客户端自己回传了推理内容的回复保持不变。DeepSeek、火山方舟和 BytePlus 方舟默认开启,其他服务商默认关闭。DeepSeek 在带工具的请求里缺少推理内容会报错,所以关闭后,DeepSeek 上游只在请求关闭思考模式时提供 OpenViking 工具。即使开启,有些请求也补不回推理内容,这些请求同样得不到工具:对话换了上游(`upstream_changed`)、Claude 对话丢了记忆记录(`missing_injection_record`),或者客户端把思考内容当作正文发回。
-- **最小可缓存长度**(仅火山方舟和 BytePlus 方舟)是模型能缓存的最短提示词长度,只影响请求日志如何报告缓存资格。
+- **优先级**:对每个请求,网关在密钥绑定的已启用上游中,找出使用这种 API 并提供所请求模型的上游,选优先级最高的一个。对话一旦开始,只要原来的上游还能服务就一直用它,所以修改优先级只影响新对话。
+- **启用**:停用的上游不接收请求,也不出现在模型列表里。原本使用它的对话会转到下一个候选上游,造成一次服务商缓存未命中,并丢掉之前的 Claude 思考块,这些请求被标为**上游已切换**(`upstream_changed`)。想保留恢复的余地,就停用而不是删除。
+- **允许 OpenViking 工具**:决定能否通过这个上游提供 OpenViking 工具。关闭后立即生效,已经带工具的对话也受影响。
+- **补全推理内容回传**:客户端回传历史时常常丢掉模型之前回复里的推理内容。开启后,网关记下经它转发的每条回复的推理内容,在后续请求中放回原处:Chat Completions 补回 `reasoning_content`,Anthropic Messages 放回 thinking 块,Responses 把带明文内容的 reasoning 项放回对应条目之前。补回的内容每次逐字节相同,服务商的提示缓存照常命中,但计入输入 token。客户端自己回传了推理内容的回复保持不变。DeepSeek、火山方舟和 BytePlus 方舟默认开启,其他服务商默认关闭。有些请求即使开启也补不回推理内容:对话换了上游(`upstream_changed`)、Claude 对话丢了记忆记录(`missing_injection_record`),或者客户端把思考内容当作正文发回;DeepSeek 上游的这类请求同样得不到 OpenViking 工具。
+- **最小可缓存长度**(仅火山方舟和 BytePlus 方舟):模型能缓存的最短提示词长度,只影响请求日志如何报告缓存资格。
-其他上游设置都立即生效,对进行中的对话也一样。网关没有故障转移:选中的上游出错时,客户端会收到这个错误;服务商无法访问时返回 502 "Model upstream is unavailable"。
+除了优先级,其他上游设置都立即生效,进行中的对话也一样。网关不做故障转移:选中的上游出错时,客户端收到这个错误;服务商无法访问时返回 502 "Model upstream is unavailable"。
-列表中的**测试**和编辑页的**测试连接**会用上游的凭证和请求头请求服务商的模型列表(`/v1/models`,火山方舟和 BytePlus 方舟为 `/api/v3/models`),最多等待 10 秒。测试通过说明主机可达,并且服务商接受这个 API Key。测试不检查模型名,也不检查 Coding Plan 设置。没有模型列表接口、或者访问这个接口需要额外请求头的服务商,可能测试失败而实际请求正常。“每个客户端自带 API Key”的上游无法测试。
+#### 测试和删除
-有密钥在使用的上游不能删除;先吊销这些密钥,或者改为停用这个上游。
+在上游列表里点**测试**,网关用已存的凭证请求服务商的模型列表,告诉你地址是否有响应、密钥是否被接受。只读用户也能测试。测试不验证具体模型,也不代表允许使用 Coding Plan;各种结果的含义见[连接测试](../api/25-gateway.md#连接测试)。
-### 上下文配置
+有密钥在用的上游不能删除:先吊销这些密钥,或者改为停用这个上游。
+
+### 导入 OpenViking 模型配置
+
+嵌入部署中,**使用 OpenViking 的模型配置**(上游页头的**从 OpenViking 导入**)把服务端的 VLM 凭证导入为当前账号的上游。没有设置管理密钥时只有 root(包括本地 dev)能导入;设置了管理密钥时需要先解锁。
-上下文配置是一组有名字的记忆设置。每个网关密钥使用一份上下文配置,一份上下文配置可以供多个密钥使用。比如可以准备一份“Coding”配置,召回记忆、资源和技能;再准备一份“Chat”配置,只召回记忆,预算也更小。
+- 结果分三组显示:已导入、需要确认、未导入。路径中带 `coding` 或 `plan` 的上游被标为 Coding Plan,确认服务商条款允许后,勾选**允许通过网关使用这个套餐**才能使用。
+- 重复导入不会产生重复的上游。再次导入时,地址、API Key、请求头、协议和服务商按服务端配置刷新;你在网关里改过的名称、启用状态、优先级、模型、别名、上下文窗口和 Coding Plan 确认都保留。
+- Codex OAuth 和 Azure 凭证、缺少 `api_base` 的 LiteLLM 凭证,以及不使用 OpenAI Chat Completions API 的 LiteLLM 路由会被跳过,原因见[导入 VLM 配置](../api/25-gateway.md#导入-vlm-配置)。
-“上下文配置”标签页为每份配置显示一张卡片,概括四个部分的设置和使用它的密钥数。标签页还是空的时候,**使用推荐设置创建**一键创建一份名为“默认”的配置,**自定义**打开编辑页;之后用**新建配置**打开编辑页。有密钥在使用的配置不能删除;想做一份变体,用**复制一份**最快。
+### 上下文配置
+
+上下文配置是一组有名字的记忆设置。每个网关密钥使用一份,一份可以供多个密钥使用。比如准备一份“Coding”配置,召回记忆、资源和技能;再准备一份“Chat”配置,只召回记忆,预算也小一些。
-> **注意**:保存的修改只对之后开始的对话生效。对话在第一个请求时记下密钥当时的上下文配置并一直沿用,因为在对话中途改变模型看到的内容会破坏服务商缓存。每次聊天都新开对话的客户端很快就能用上新设置。Claude Code、Codex 以及发送固定会话请求头的客户端会一直沿用旧设置,直到开始新对话,或者这段对话闲置满 30 天(`session_ttl_days`)。
+“上下文配置”标签页为每份配置显示一张卡片,概括各部分的设置和使用它的密钥数。标签页为空时,**使用推荐设置创建**一键创建一份名为“默认”的配置,**自定义**打开编辑页;之后用**新建配置**。有密钥在用的配置不能删除;想做一份变体,用**复制一份**最快。
-各部分都有自己的开关,长对话部分的两项功能各有一个:
+> **注意**:保存的修改只对之后开始的对话生效。对话在第一个请求时记下当时的上下文配置并一直沿用,因为中途改变模型看到的内容会破坏服务商缓存。每次聊天都新开对话的客户端很快就能用上新设置;Claude Code、Codex 以及发送固定会话请求头的客户端会一直沿用旧设置,直到开始新对话,或者这段对话闲置满 30 天(`session_ttl_days`)。
| 部分 | 作用 | 主要设置和默认值 |
| --- | --- | --- |
-| 召回记忆 | 用每条新的用户消息搜索 OpenViking,把相关内容附加到这条消息上。 | 检索范围:记忆、资源、技能 · 单条消息预算:1,600 token · 单个上下文窗口预算:30,000 token · 相关度阈值:0.35 · 超时时间:2 秒 |
-| 保存对话 | 把已完成的轮次写入 OpenViking 会话并提交,供 OpenViking 提取记忆。 | 最新回复等待时长:600 秒 · 提交阈值:20,000 token · 保留最近消息:10 |
-| 长对话 | 对话接近模型的上下文窗口时压缩:由同一个模型写摘要,用摘要替换之前的消息。Agent 自管上下文窗口是实验性的另一种方式。 | 压缩:开启 · 压缩时机:上下文窗口的 0.9 · 摘要长度上限:8,000 token · Agent 自管上下文窗口:关闭 |
-| OpenViking 工具 | 让模型在回答时使用 OpenViking 的工具。支持 Chat Completions、完整历史的 Responses 和 Anthropic Messages,新建的配置默认开启。 | 默认勾选只读工具,会修改数据的工具不勾选 |
+| 召回记忆 | 用每条新的用户消息检索 OpenViking,把相关内容附加到这条消息上。 | 检索范围:记忆、资源、技能 · 单条消息预算:1,600 token · 单个上下文窗口预算:30,000 token · 相关度阈值:0.35 · 超时时间:2 秒 |
+| 保存对话 | 把完成的轮次写入 OpenViking 会话并提交,供 OpenViking 提取记忆。 | 最新回复等待时长:600 秒 · 提交阈值:20,000 token · 保留最近消息:10 |
+| 长对话 | 对话接近上下文窗口时,让同一个模型写摘要,替换之前的消息。 | 压缩:开启 · 压缩时机:窗口的 0.9 · 摘要长度上限:8,000 token · Agent 自管上下文窗口:关闭 |
+| OpenViking 工具 | 让模型在回答时使用 OpenViking 的工具。 | 开启 · 只勾选只读工具,见 [OpenViking 工具](#openviking-工具) |
-召回设置的实际效果:
+每个部分都有自己的开关,长对话部分的压缩和 Agent 自管上下文窗口各有一个。召回和保存相互独立,只召回不保存、只保存不召回都可以。
-- **会话开头提供用户画像**独立于召回。启用读取工具后,还会提供记忆和技能目录。**开头内容预算**默认限制为 4,000 token,其中技能最多占四分之一;设为 0 时全部省略。这些内容不占召回预算。
-- 召回采用 OpenViking 在指定预算内选取和排版的内容,也包括只提供 URI、供模型之后读取的条目。
+**召回的细节:**
-- 检索文本是去掉客户端噪声后的用户消息,最多截取**检索文本长度**个字符(8,000)。少于 3 个字符的消息不搜索。
-- 每条消息最多补充**单条消息预算**与**单个上下文窗口预算**剩余额度中较小的那个;剩余额度不足 64 token 时跳过搜索。无论是网关还是客户端压缩了对话,单个上下文窗口预算都会重新计算。预算设为 0 就关闭了召回。这里的 token 数是偏保守的估算,不是服务商的计费数。
-- OpenViking 在**超时时间**内没有返回时,这条消息不带记忆直接发给模型,之后也不会补上,客户端重试也一样。
-- **按分类限量**(在“高级设置”中)可以给事件、实体、偏好、经验、资源和技能六个分类分别设置条数上限,只搜索上限大于 0 的分类。关闭时,所有来源放在一起排序。
+- **会话开头提供用户画像**独立于召回。提供 `read` 工具时,开头还提供记忆和技能目录。**开头内容预算**默认 4,000 token,技能最多占四分之一,设为 0 时全部省略;这部分不占召回预算。
+- 召回内容由 OpenViking 在预算内选取和排版,也可能只给出 URI,供模型之后读取。
+- 检索文本是去掉客户端噪声后的用户消息,最多取**检索文本长度**(8,000)个字符。少于 3 个字符的消息不检索。
+- 每条消息最多补充**单条消息预算**和**单个上下文窗口预算**剩余额度中较小的那个;剩余额度不足 64 token 时跳过检索。无论网关还是客户端压缩了对话,单个上下文窗口预算都重新计算。预算设为 0 就等于关闭召回。这里的 token 数是偏保守的估算,不是服务商的计费数。
+- OpenViking 在**超时时间**内没有返回时,这条消息不带记忆发给模型,之后也不补,客户端重试也一样。
+- **按分类限量**(在“高级设置”中)可以给事件、实体、偏好、经验、资源和技能六类分别设条数上限,只检索上限大于 0 的类别。关闭时,所有来源放在一起排序。
-**召回摘要。** 开启**显示召回摘要**(默认关闭)后,每条新用户消息的回复都以一段简短的摘要开头,说明网关给这条消息补充了什么:
+**召回摘要。** 开启**显示召回摘要**(默认关闭)后,每条新用户消息的回复以一段简短摘要开头,说明网关补充了什么:
```text
> OpenViking context: user profile, memory index, skill list, earlier sessions
> OpenViking recall: 4 items (3 memories, 1 resource) — booking_duplicate_handling, user_lang_pref, +2 more
```
-`context` 行只出现在对话的第一条回复里,并且只列出开头实际提供的内容:用户画像、记忆目录、技能目录,以及这段对话较早部分在 OpenViking 中的保存位置。`recall` 行按类别统计召回的条目数,并列出最多三个条目名。搜索失败时,这一行改为说明原因,例如 `> OpenViking recall failed: OpenViking unavailable`。没有找到相关内容、召回已关闭或预算已用完时不显示 `recall` 行,因此在第一条回复之后,这样的消息没有摘要。工具步骤等后续请求从不显示摘要;客户端重试同一条消息时,摘要和第一次相同。在 Anthropic Messages 中,摘要单独占一个文本块;在 Responses 中单独占一条助手消息;在 Chat Completions 中是回复文本的开头。要求结构化输出(JSON 格式)的请求,以及 `n` 大于 1 的 Chat Completions 请求,不显示摘要。无论是否开启 OpenViking 工具,这项设置都有效。模型看不到摘要:客户端随下一条消息把回复发回来时,网关会先删掉摘要再转发请求,也不会把它保存到 OpenViking。和其他上下文配置一样,改动只影响新对话。
+- `context` 行只出现在对话的第一条回复里,列出开头实际提供的内容:用户画像、记忆目录、技能目录,以及这段对话较早部分在 OpenViking 中的位置。
+- `recall` 行按类别统计召回条数,最多列出三个条目名。检索失败时改为说明原因,例如 `> OpenViking recall failed: OpenViking unavailable`。没有找到内容、召回已关闭或预算用完时不显示,所以第一条回复之后,这类消息没有摘要。
+- 工具步骤等后续请求不显示摘要;客户端重试同一条消息时,摘要和第一次相同。
+- 摘要在 Anthropic Messages 中单独占一个文本块,在 Responses 中单独占一条助手消息,在 Chat Completions 中位于回复文本开头。要求结构化输出的请求,以及 `n` 大于 1 的 Chat Completions 请求,不显示摘要。
+- 模型看不到摘要:客户端随下一条消息把回复发回来时,网关先删掉摘要再转发,也不把它保存到 OpenViking。
-保存设置的实际效果:
+**保存的细节:**
-- 下一条用户消息到达时,上一轮就会保存。**最新回复等待时长**决定网关等多久之后把最后一轮也保存下来并提交会话,这样短对话也能被提交。
-- **提交阈值**:会话中待提交的内容达到这么多 token 时就提交一次。每次提交后,OpenViking 在后台提取记忆。
+- 下一条用户消息到达时,上一轮就会保存。**最新回复等待时长**决定网关等多久之后保存最后一轮并提交会话,这样短对话也能被提交。
+- **提交阈值**:会话中待提交的内容达到这么多 token 时提交一次。每次提交后,OpenViking 在后台提取记忆。
- **保留最近消息**:提交后,会话中保留最新的若干完整轮次,至少包含这么多条消息。
-- 召回和保存相互独立:只保存不召回、或者只召回不保存的配置都有效。
-[配置参考](#配置参考)列出了每项设置的 API 名称和取值范围。
+每项设置的 API 名称和取值范围见[配置参考](#配置参考)。
### 网关密钥
-网关密钥(`ovgw_…`)是客户端用来代替服务商 API Key 的凭证。每个密钥属于一个 OpenViking 用户,使用一份上下文配置和一组上游。
+网关密钥(`ovgw_…`)是客户端用来代替服务商 API Key 的凭证。每把密钥属于一位 OpenViking 用户,使用一份上下文配置和一组上游。
-在“密钥”标签页选择**签发密钥**,然后填写:
+在“密钥”标签页点**签发密钥**,依次填写:
- **名称**:方便日后辨认,例如“alice · Claude Code”。
-- **OpenViking 用户**:本账号中的一个用户或管理员。网关以这个用户的身份搜索和保存记忆。签发时,OpenViking Server 读取这个用户的 OpenViking 密钥并交给网关,网关加密保存;密钥不经过浏览器,之后也不再显示。如果 OpenViking Server 只保存密钥的哈希(启用了 `encryption.api_key_hashing.enabled`),或者因为其他原因读不到某个用户的密钥,这个用户在列表里不可选。这时选择**粘贴 OpenViking 密钥**,填入该用户自己的密钥。用 root key 登录 Studio 时没有用户列表可选:root key 解析到的账号可能不是 Studio 当前显示的账号,所以要粘贴用户的密钥。粘贴的密钥不能是 root key。
+- **给谁用**:普通用户只能给自己签发;账号管理员可以选本账号的用户;root 先在侧边栏切换账号。网关会从 OpenViking 读取所选用户的 API 密钥;OpenViking 只保存密钥哈希时读不出来,Studio 会显示**粘贴用户 API 密钥**输入框,填入该用户当前的密钥。root API 密钥不能绑定到网关密钥。本地 dev 模式下,密钥以 `default` 用户的身份读写记忆。
- **上下文配置**。
-- **上游**:至少一个。这个密钥只能访问选中的上游。
-- **允许的模型**(可选):留空表示允许这些上游提供的所有模型。这里填客户端发送的名称,包括别名。请求其他模型会返回 403 "Model is not allowed by this key",模型列表也只显示允许的名称。
+- **上游**:至少一个,密钥只能访问选中的上游。
+- **允许的模型**(可选):留空表示允许这些上游的全部模型。这里填客户端发送的名称,包括别名。请求其他模型返回 403 "Model is not allowed by this key",模型列表也只显示允许的名称。
-签发前,网关会向 OpenViking 核实这个用户的 OpenViking 密钥。如果粘贴的是 root key、其他账号的密钥或无效的密钥,或者 OpenViking 无法访问,签发就会失败,见[签发密钥失败](#签发密钥失败)。
+签发前,网关会向 OpenViking 核实这位用户的密钥。粘贴的是 root 密钥、其他账号的密钥或无效密钥,或者 OpenViking 连不上时,签发失败,见[签发密钥失败](#签发密钥失败)。
-签发成功后,**复制网关密钥**对话框显示完整密钥。这是唯一一次显示:网关只保存密钥的哈希和开头几个字符。对话框里还有 Claude Code、Codex CLI 和聊天客户端的配置,已经填好真实密钥和网关地址,可以直接粘贴。密钥丢了就重新签发一个。
+签发成功后,**复制网关密钥**对话框显示完整密钥,这是唯一一次:网关只保存它的哈希和开头几个字符。对话框里还有 Claude Code、Codex CLI 和聊天客户端的配置,已填好真实密钥和网关地址,可以直接粘贴。密钥丢了就重新签发。
-- **密钥不能编辑。** 要更换密钥的上下文配置、上游、允许的模型或 OpenViking 用户,就签发一个新密钥,再吊销旧的。
-- **对话属于用户,不属于密钥。** 只要客户端发送相同的会话 ID,同一 OpenViking 用户的新密钥就会接着原来的对话,所以换密钥不会打断对话。
-- **吊销**会立即切断客户端的访问(其他工作进程约 2 秒内跟上),正在进行的请求会正常完成。最后使用这个密钥的对话里还没保存的轮次会被丢弃,对话和记忆本身都保留。想换密钥又不丢轮次,就先把客户端切到新密钥,再吊销旧的。
-- **OpenViking 密钥变了怎么办。** 网关保存的是签发时这个用户的 OpenViking 密钥。如果该密钥被重新生成或删除,网关密钥仍能通过客户端认证,但记忆搜索会失败,保存也会因 `openviking_http_401` 暂停。为该用户重新签发网关密钥(Studio 会读取新的 OpenViking 密钥),切换客户端,再吊销旧的网关密钥。
-- **每人一个密钥。** 使用同一个密钥的人共享其 OpenViking 用户的记忆。请给每人签发一个密钥;想让不同客户端使用不同的上下文配置,就按客户端再分开签发。
+- **密钥不能编辑。** 要更换上下文配置、上游、允许的模型或用户,就签发新密钥,再吊销旧的。
+- **对话属于用户,不属于密钥。** 客户端发送相同的会话 ID 时,同一用户的新密钥会接着原来的对话,换密钥不会打断对话。
+- **吊销**后,这把密钥立即不能再用;用户的对话状态和日志保留,直到被显式删除或过期。
+- **OpenViking 密钥变了。** 用户的 OpenViking API 密钥重新生成或用户被删除后,OpenViking 会拒绝网关保存的旧密钥。网关在随后的请求中发现这一点(最多延迟约 30 秒),删除绑定它的网关密钥,对话状态和日志保留。请用当前的 OpenViking 密钥重新签发。OpenViking 暂时连不上或出错时,网关不删除密钥,请求照常发给模型,只是不带记忆。
+- **每人一把密钥。** 共用一把密钥的人共享其 OpenViking 用户的记忆。请给每人签发一把;想让不同客户端使用不同的上下文配置,再按客户端分开签发。
-**删除该用户的网关数据…**(在密钥的**更多操作**菜单中)会吊销该 OpenViking 用户的所有网关密钥,并删除网关为该用户保存的对话状态。OpenViking 中的会话和记忆不受影响,需要在 OpenViking 中删除。在 OpenViking 中删除用户或账号时,网关会自动做同样的清理,见[安全与数据](#安全与数据)。
+账号管理员和 root 可以在密钥页使用**删除该用户的网关数据…**:吊销该用户的全部网关密钥,删除网关为该用户保存的对话状态(包括尚未保存到 OpenViking 的内容)和请求日志。已存入 OpenViking 的记忆不受影响,见[安全与数据](#安全与数据)。
### 请求日志和概览
-**概览**标签页汇总日志保留期(默认 30 天)内最新的 10,000 条请求日志:
+普通用户只看到自己的请求,账号管理员和 root 看到整个账号的请求。
+
+**概览**标签页汇总日志保留期(默认 30 天)内最新的 10,000 条请求:
-- 第一个请求到达之前,显示**快速开始**清单。
-- **请求数**:模型请求的数量、最近一次请求的时间,以及这些请求用掉的输出 token。
-- **首次调用缓存命中率**:每条新用户消息的第一次模型调用中,命中服务商提示词缓存的输入 token 所占的比例。这是判断网关是否健康最重要的指标,应该接近不经过网关时服务商能达到的水平;明显下降通常说明网关发送的历史和上一次请求对不上了,见[首次调用缓存命中率下降](#首次调用缓存命中率下降)。
-- **轮内缓存命中率**:同一轮里后续调用的缓存命中率,例如工具步骤和 OpenViking 工具的往返。这个值通常都很高。
-- **召回的记忆条数**:补充到新消息中的记忆条数,以及每次检索 OpenViking 的平均耗时(只统计实际检索了的消息)。
-- **OpenViking**:显示已连接、异常或启动中,附带版本和认证模式,异常时还会给出原因。OpenViking 无法访问期间,请求照常发给模型,只是不带记忆。卡片中的**保存对话**一栏还会统计正在重试或已暂停保存的对话数。
-- **降级请求**:每种异常出现的次数和说明,异常类型见[故障排查中的表格](#降级请求的异常)。
+- 第一个请求到达之前,显示**快速开始**清单,顺序是“上游 → 上下文配置 → 签发密钥 → 接入”。
+- **请求数**:模型请求的数量、最近一次请求的时间,以及这些请求的输出 token。
+- **首次调用缓存命中率**:每条新用户消息的第一次模型调用中,命中服务商提示缓存的输入 token 所占比例。这是判断网关是否健康最重要的指标,应该接近不经过网关时服务商能达到的水平;明显下降通常说明网关发送的历史和上一次对不上了,见[首次调用缓存命中率下降](#首次调用缓存命中率下降)。
+- **轮内缓存命中率**:同一轮里后续调用的命中率,例如工具步骤和 OpenViking 工具的往返,通常很高。
+- **召回的记忆条数**:补充到新消息中的条数,以及每次检索 OpenViking 的平均耗时(只统计实际检索了的消息)。
+- **OpenViking**:已连接、异常或启动中,附带版本;异常时给出原因。OpenViking 连不上期间,请求照常发给模型,只是不带记忆。卡片中的**保存对话**一栏统计正在重试或已暂停保存的对话数。
+- **降级请求**:每种异常出现的次数和说明,见[降级请求的异常](#降级请求的异常)。
- **最近请求**,以及前往“请求日志”标签页的链接。
-**请求日志**标签页按时间倒序列出最新的 1,000 条记录,停留在第一页时每 30 秒刷新一次。可以按**全部**、**新消息**、**工具步骤**或**异常**筛选,也可以按**请求类型**筛选,或者按模型、对话或密钥搜索。各列显示类型、模型(客户端发送的名称)、服务商返回的 HTTP 状态、token(输入、缓存占比、输出)、**记忆**(`+3` 表示这次搜索补充的条数,附带搜索耗时;`↺ 4` 表示之前 4 条消息补充的记忆被原样放回)、**保存**状态和**异常**。展开一行可以看到对话 ID、上游、密钥、耗时、token 明细、记忆搜索结果、上下文窗口(用了多少,以及是否压缩或开启了新窗口)、保存状态和下次重试时间、OpenViking 工具详情;有异常的请求还会说明发生了什么、该怎么处理。
+**请求日志**标签页按时间倒序列出最新的 1,000 条记录,停留在第一页时每 30 秒刷新一次。可以按**全部**、**新消息**、**工具步骤**或**异常**筛选,也可以按请求类型筛选,或者按模型、对话或密钥搜索。
-只有到达模型服务商的请求才会被记录。网关先行拒绝的请求不会记录,例如密钥无效、模型不在密钥的允许范围内、没有匹配的上游、请求体超过上限,这些情况下客户端会直接收到错误。
+各列依次是类型、模型(客户端发送的名称)、服务商返回的 HTTP 状态、token(输入、缓存占比、输出)、**记忆**、**保存**状态和**异常**。**记忆**列中,`+3` 表示这次检索补充了 3 条,并附检索耗时;`↺ 4` 表示之前 4 条消息补充的记忆被原样放回。展开一行可以看到对话 ID、上游、密钥、耗时、token 明细、记忆检索结果、上下文窗口用量(以及是否压缩或开启了新窗口)、保存状态和下次重试时间、OpenViking 工具详情;有异常的请求还会说明发生了什么、怎么处理。
+
+只有到达模型服务商的请求才会记录。被网关先行拒绝的请求不记录,例如密钥无效、模型不在允许范围内、没有匹配的上游、请求体超限,这些情况下客户端直接收到错误。
| 类型 | 含义 | 记忆 |
| --- | --- | --- |
-| 新消息 | 最后一条是新用户消息的请求 | 搜索一次,并放回之前的记忆;这一轮会被保存 |
+| 新消息 | 最后一条是新用户消息的请求 | 检索一次,并放回之前的记忆;这一轮会被保存 |
| 工具步骤 | 同一轮的延续,例如带着工具结果继续 | 放回之前的记忆;随所在轮次一起保存 |
| 辅助请求 | 生成标题、摘要、压缩、建议和权限检查的请求 | 放回之前的记忆;从不保存 |
| 子 Agent | 客户端的子 Agent 发出的请求 | 放回之前的记忆;从不保存 |
-| Token 计数 | token 计数请求(`/v1/messages/count_tokens`) | 放回之前的记忆,计数才和实际发送的内容一致 |
-| 直接转发 | 不做改动、不带记忆直接转发的请求:其他接口、依赖服务商端状态的 Responses 请求、压缩过或无法解析的请求体 | 无 |
+| Token 计数 | token 计数请求(`/gateway/v1/messages/count_tokens`) | 放回之前的记忆,计数才和实际发送的内容一致 |
+| 直接转发 | 原样转发、不带记忆的请求:其他接口、依赖服务商端状态的 Responses 请求、压缩过或无法解析的请求体 | 无 |
| 记忆同步 | 后台保存事件,不是模型请求 | — |
**保存**列显示每段对话的保存状态:
- **正常**:保存正常进行。
- **已关闭**:这段对话的上下文配置不保存对话。
-- **重试中**:OpenViking 拒绝了保存,或者无法访问。网关会在 10、20、40、80 秒后依次重试。
-- **已暂停**:连续 5 次失败。网关之后每 5 分钟重试一次,直到成功。未保存的轮次会一直保留,直到保存成功或者对话过期。
+- **重试中**:OpenViking 拒绝了保存或无法访问。网关在 10、20、40、80 秒后依次重试。
+- **已暂停**:连续失败 5 次。网关之后每 5 分钟重试一次,直到成功;未保存的轮次一直保留,直到保存成功或对话过期。
+- **已暂停**,原因为 `gateway_key_revoked`:这段对话的网关密钥已被吊销或删除,网关不再重试。用户之后用有效密钥在这段对话里发请求时,保存自动恢复。
-展开的行会显示原因,例如 OpenViking 拒绝了密钥(`openviking_http_401`,即用户的 OpenViking 密钥已失效),或者 OpenViking 无法访问(`openviking_unavailable`)。提示对话历史有改动(`history_changed`)是正常的:客户端编辑、重新生成或压缩了对话,网关用当前历史在新的 OpenViking 会话中继续保存。
+展开的行会显示原因,例如 OpenViking 拒绝了密钥(`openviking_http_401`,即用户的 OpenViking 密钥已失效),或者 OpenViking 无法访问(`openviking_unavailable`)。对话历史有改动(`history_changed`)是正常的:客户端编辑、重新生成或压缩了对话,网关用当前历史在新的 OpenViking 会话中继续保存。
-展开行中的**重新同步对话…**会为这段对话新建一个 OpenViking 会话。用户下次发消息时,网关把对话的完整历史写进这个会话。已经保存的内容留在旧会话里,所以 OpenViking 可能会把部分记忆提取两次。修复了原因但对话仍然暂停,或者想要一份干净的对话副本时,可以用它。下一条消息到达之前,什么都不会发生。重新同步需要记录上显示的那个密钥;如果它已被吊销,请选同一段对话里更新的一条记录。
+展开行中的**重新同步对话…**为这段对话新建一个 OpenViking 会话,用户下次发消息时,网关把完整历史写进去。已经保存的内容留在旧会话里,所以部分记忆可能被提取两次。原因已经修复、对话却仍然暂停,或者想要一份干净的对话副本时,可以用它。下一条消息到达之前什么都不会发生。重新同步需要记录上显示的那把密钥;它已被吊销时,请选同一段对话里更新的一条记录。
## OpenViking 工具
-开启 OpenViking 工具后,模型可以在回答过程中使用 OpenViking 服务提供的工具,访问范围受该用户的权限限制。工具调用由网关执行,客户端会持续收到回答,直到本次回复结束。显示的 token 用量包含期间所有模型调用。这项功能对各类客户端意味着什么、模型能用哪些工具、用户在回复里看到什么,见 OpenViking 网关指南中的[让任意客户端拥有 Agentic 记忆](15-gateway.md#让任意客户端拥有-agentic-记忆);本节说明客户端要求、设置和上限。
+开启 OpenViking 工具后,模型能在回答过程中使用 OpenViking 服务提供的工具,范围受该用户自己的 OpenViking 权限限制。调用由网关执行,客户端持续收到回答直到本次回复结束,显示的 token 用量包含期间所有模型调用。这项功能对各类客户端意味着什么、用户在回复里看到什么,见[让任意客户端拥有 Agentic 记忆](15-gateway.md#让任意客户端拥有-agentic-记忆);本节说明客户端要求、设置和上限。
+
+这项功能面向接不了 OpenViking MCP 服务器的聊天应用和 API 应用。Claude Code、Codex 这类支持 MCP 或有插件的客户端,用 MCP 或插件更合适,因为它们会显示每次工具调用和结果,并在调用前请求确认。
+
+### 客户端要求
三种协议都支持流式和非流式请求:
| 协议 | 客户端要求 |
| --- | --- |
-| Chat Completions | 回传完整 `messages` 历史。 |
-| Responses | 使用 `store: false` 和完整 `input` 历史;下一轮回传本轮返回的全部 `output` 内容,包括 reasoning 和客户端工具调用。带 `previous_response_id`、`conversation` 或 `background` 的请求继续普通转发,不提供网关工具;`item_reference` 无法还原完整历史。 |
-| Anthropic Messages | 回传完整 `messages` 历史,保留 thinking/signature 块。计数请求使用相同工具定义,但不执行工具。 |
+| Chat Completions | 回传完整的 `messages` 历史。 |
+| Responses | 使用 `store: false` 和完整的 `input` 历史;下一轮回传本轮返回的全部 `output` 内容,包括 reasoning 和客户端工具调用。带 `previous_response_id`、`conversation` 或 `background` 的请求照常转发,不提供网关工具;`item_reference` 无法还原完整历史。 |
+| Anthropic Messages | 回传完整的 `messages` 历史,保留 thinking 和 signature 块。token 计数请求带相同的工具定义,但不执行工具。 |
+
+模型在同一条回复中同时调用 OpenViking 工具和客户端工具时,网关处理 OpenViking 调用,客户端照常执行自己的工具并回传结果。Responses 支持客户端的 function 和 custom 工具,Anthropic Messages 支持客户端的 tool_use 调用。
+
+### 选择工具
+
+新建的上下文配置默认开启 **OpenViking 工具**,“使用推荐设置创建”也一样。**工具**清单来自你的 OpenViking 服务,默认只勾选只读工具:
-模型在同一条回复中同时调用 OpenViking 和客户端工具时,网关会处理 OpenViking 调用,客户端照常执行自己的工具并回传结果。Responses 支持客户端的 function 和 custom 工具,Anthropic Messages 支持客户端的 tool_use 调用。
+- **默认勾选**:`find`、`search`、`grep`、`glob`、`list`、`tree`、`read`、`list_watches`、`get_acl`、`list_users`、`list_groups` 和 `health`。
+- **默认不勾选**(会修改数据):`remember`、`write`、`edit`、`add_resource`、`add_skill`、`forget`、`set_acl` 和 `cancel_watch`。想让模型保存记忆就勾选 `remember`,想让它导入网页或附件就勾选 `add_resource`。
-这项功能面向无法连接 OpenViking MCP 服务器的聊天应用和 API 应用。支持 MCP 或有插件的客户端,例如 Claude Code 和 Codex,用 MCP 或插件更合适,因为客户端会在那里显示每次工具调用及其结果,并在调用前请求确认。
+OpenViking 以后新增的工具会默认可用,已有对话仍沿用开始时的工具清单。已有的上下文配置保留原来的勾选。
-新建的上下文配置默认打开 **OpenViking 工具**,“使用推荐设置创建”也一样。**工具**清单来自你的 OpenViking 服务,默认只勾选只读工具:`find`、`search`、`grep`、`glob`、`list`、`tree`、`read`、`list_watches`、`get_acl`、`list_users`、`list_groups` 和 `health`。会修改数据的工具默认不勾选:`remember`、`write`、`edit`、`add_resource`、`add_skill`、`forget`、`set_acl` 和 `cancel_watch`。比如想让模型保存记忆,就勾选 `remember`;想让它导入网页或附件,就勾选 `add_resource`。已有的上下文配置保留原来的设置。还没有网关密钥时,先签发一个密钥再加载清单。OpenViking 后续新增的工具也会默认可用,已有对话仍沿用开始时的工具清单。
+每个上游的**允许 OpenViking 工具**默认开启。两个开关都开启时,新对话获得选中的工具,名称加上 `openviking_` 前缀,例如 `openviking_find`、`openviking_read`。Studio 会说明每个工具的用途;只有 OpenViking 提供了相应信息时,才显示只读标记。工具定义随对话中的每个请求发送,全部工具约占 3,500 个输入 token,所以取消用不到的工具也能省 token。
-每个上游的**允许 OpenViking 工具**默认开启。两个开关都开启后,新对话会获得选中的工具,名称加上 `openviking_` 前缀,例如 `openviking_find`、`openviking_read`、`openviking_grep` 和 `openviking_glob`。Studio 中的说明介绍各个工具的用途;只有 OpenViking 提供了相应信息时,页面才显示只读标记。提供给模型的工具定义会随对话中的每个请求发送,OpenViking 的全部工具约占 3,500 个输入 token,所以取消勾选用不到的工具也能节省 token。
+> **注意**:选中的工具直接执行,不经过客户端的权限确认,写入和删除数据的工具也一样。勾选会修改数据的工具前,先确认能接受这一点;给聊天应用用的配置,建议不勾选 `forget` 和 `set_acl`。调用提示只说明已经发生的操作,不是权限确认。
-> **注意**:所有选中的工具都直接执行,不经过客户端的权限确认,包括写入和删除数据的工具。勾选会修改数据的工具之前,先确认可以接受这一点;给聊天应用用的上下文配置,建议不要勾选 `forget` 和 `set_acl`。调用提示用于说明已经发生的操作,不是权限确认。
+### 工具调用提示
-**工具调用提示。** 开启**显示工具调用**(默认开启)时,网关每执行一次 OpenViking 工具调用,就在回复中调用发生的位置加一行提示:
+开启**显示工具调用**(默认开启)时,网关每执行一次 OpenViking 工具调用,就在回复中调用发生的位置加一行提示:
```text
> OpenViking find: "release date" — done
```
-提示写明工具名;能够识别调用对象时,还会显示:检索的查询词,读取、列出或写入的 URI,或者正在导入的文件或技能。流式回复中,调用一开始提示就会出现,所以导入这类耗时的调用进行时,用户也能看到网关在工作;非流式回复会在最终消息里带上同样的提示。调用结束后再补上结果:`done` 表示完成,`failed` 表示调用返回了错误,`skipped` 表示网关拒绝了这次调用,没有执行,例如工具轮数已达上限或 token 预算已经用完。每条提示单独成段。在 Chat Completions 中,提示是回复文本的一部分;在 Anthropic Messages 中,同一轮调用的提示放在同一个文本块里;在 Responses 中,同一轮调用的提示放在同一条助手消息里。模型看不到这些提示,它收到的是真实的调用和结果;网关也不会把提示保存到 OpenViking。要隐藏提示,在上下文配置的 **OpenViking 工具**部分关闭**显示工具调用**,回复里就只有模型自己的输出。和其他工具设置一样,改动只影响新对话。
+- 提示写明工具名;能识别调用对象时,还显示检索的查询词,读取、列出或写入的 URI,或者正在导入的文件或技能。
+- 流式回复中,调用一开始提示就出现,导入这类耗时的调用进行时,用户也能看到网关在工作;非流式回复在最终消息里带上同样的提示。
+- 调用结束后补上结果:`done` 表示完成,`failed` 表示调用返回了错误,`skipped` 表示网关拒绝了这次调用、没有执行,例如工具轮数或 token 预算已经用完。
+- 每条提示单独成段。在 Chat Completions 中,提示是回复文本的一部分;在 Anthropic Messages 中,同一轮调用的提示放在同一个文本块里;在 Responses 中,放在同一条助手消息里。
+- 模型看不到这些提示,它收到的是真实的调用和结果;网关也不把提示保存到 OpenViking。
-对话是否带工具,由它第一个能用工具的请求决定(生成标题这类辅助请求不算),之后保持不变,所以修改上下文配置只影响新对话。唯一的例外是关闭工具:模型还没调用过网关工具时,客户端出现了自己的 OpenViking 工具,例如 MCP 服务器在第一轮之后才连上。请求没有带工具时,请求日志的详情会说明原因:
+要隐藏提示,在上下文配置的 **OpenViking 工具**部分关闭**显示工具调用**。和其他工具设置一样,改动只影响新对话。
+
+### 什么时候不提供工具
+
+对话是否带工具,由它第一个能用工具的请求决定(生成标题这类辅助请求不算),之后保持不变,所以修改上下文配置只影响新对话。唯一的例外是关闭:模型还没调用过网关工具时,客户端出现了自己的 OpenViking 工具,例如 MCP 服务器在第一轮之后才连上。
+
+辅助请求、子 Agent 请求和检测到 OpenViking 插件的对话都不带 OpenViking 工具。这类请求如果回传了模型用过这些工具的历史,网关仍附上工具定义,让这段历史保持有效,但拒绝新的 OpenViking 调用。客户端自己的工具在每个请求里都照常可用。
+
+请求没有带工具时,请求日志的详情会说明原因:
| 原因 | 说明 |
| --- | --- |
-| `tools_require_full_history` | Responses 工具需要 `store: false` 和完整 input 历史,不能使用 `item_reference`。 |
+| `tools_require_full_history` | Responses 请求需要 `store: false` 和完整 input 历史,不能使用 `item_reference`。 |
| `upstream_tools_disabled` | 上游关闭了**允许 OpenViking 工具**。 |
| `tools_multiple_choices` | 请求要求返回多个候选(`n` 大于 1)。 |
| `tools_structured_output` | 请求要求结构化输出(`response_format`、`text.format` 或 `output_config.format`)。 |
| `tools_non_function` | Chat Completions 客户端传入了 function 以外类型的工具。 |
| `tools_forced_choice` | `tool_choice` 为 `required`,或者指定了某个工具。 |
-| `deepseek_reasoning_history_required` | 上游的服务商是 DeepSeek,请求没有关闭思考模式(`"thinking": {"type": "disabled"}`),而之前的回复发到上游时会缺少推理内容:关闭了**补全推理内容回传**,或者这个请求补不回推理内容,因为对话换了上游、丢了记忆记录,或者思考内容被当作正文发回。标准的 Responses 请求没有 `thinking` 字段,按开启思考模式处理。 |
-| `tool_name_collision` | 客户端已接入 OpenViking 工具,网关在这段对话剩下的部分不再提供自己的工具;模型已经调用过网关工具的分支除外。误判同样会持续整段对话,开新对话即可。满足以下任一条件即算:MCP 服务名(`server_label`、`mcp_server_name`、`mcp_servers[].name`)含有单词 `openviking`;以 OpenViking 工具名命名的工具名中也含这个单词,如 `mcp__claude_ai_OpenViking__search`(连接器的 `authenticate` 工具不算),包括独占一行列出的延迟加载工具名;带前缀、以 OpenViking 工具名结尾的工具(如 `mcp__ov__read`)在定义中出现 `viking://`。此外,任一请求中客户端工具与网关工具同名也算,因为上游会拒绝重名工具。 |
-| `tools_unavailable` | 无法从 OpenViking 加载工具清单,也没有之前加载成功的清单。连接恢复后请开始新对话。 |
-| `tools_not_selected_at_session_start` | 上下文配置开启了工具,但这段对话的工具列表是空的:配置里没有选中任何 OpenViking 工具,或者对话是在网关升级前开始的、当时没拿到工具。开始新对话即可。 |
+| `deepseek_reasoning_history_required` | 上游是 DeepSeek,请求没有关闭思考模式(`"thinking": {"type": "disabled"}`),而之前的回复发到上游时会缺推理内容:关闭了**补全推理内容回传**,或者这个请求补不回推理内容(对话换了上游、丢了记忆记录,或者思考内容被当作正文发回)。标准 Responses 请求没有 `thinking` 字段,按开启思考模式处理。 |
+| `tool_name_collision` | 客户端已经接了 OpenViking 工具,网关在这段对话剩下的部分不再提供自己的工具(模型已经调用过网关工具的分支除外)。判断条件见下文。 |
+| `tools_unavailable` | 无法从 OpenViking 加载工具清单,也没有之前加载成功的清单。连接恢复后开始新对话。 |
+| `tools_not_selected_at_session_start` | 上下文配置开启了工具,但这段对话的工具列表为空:配置里一个工具都没选,或者对话在网关升级前就已开始。开始新对话即可。 |
+
+满足以下任一条件,网关就认为客户端已经接了 OpenViking 工具(`tool_name_collision`):
-辅助请求、子 Agent 请求和检测到 OpenViking 插件的对话都不带 OpenViking 工具。这类请求如果回传了模型用过这些工具的历史,网关仍会附上工具定义,让这段历史保持有效,但会拒绝新的 OpenViking 调用。客户端自己的工具在每个请求里都照常可用。
+- MCP 服务名(`server_label`、`mcp_server_name`、`mcp_servers[].name`)含单词 `openviking`。
+- 以 OpenViking 工具名结尾的工具名中也含这个单词,例如 `mcp__claude_ai_OpenViking__search`;连接器的 `authenticate` 工具不算。独占一行列出的延迟加载工具名也算。
+- 带前缀、以 OpenViking 工具名结尾的工具(例如 `mcp__ov__read`),定义中出现 `viking://`。
+- 任一请求中,客户端工具和网关工具同名,因为上游会拒绝重名工具。
-**导入文件和技能。** OpenViking 服务提供导入工具、且配置中勾选了它们时即可使用。通过 URL 导入不需要 shell 工具,本地文件则需要以下上传方式之一:
+误判同样会持续整段对话,开始新对话即可。
-- **有 shell 工具**(名称类似 bash、shell、exec_command、terminal 或 run_command 的客户端工具):导入工具返回一个一次性上传链接,模型再用客户端自己的 shell 工具上传文件,这一步会经过客户端的权限确认。技能目录会先打包成 zip。链接指向 `public_url` 加上 `/gateway/uploads`,所以 `public_url` 必须是客户端能访问的地址,代理也要把这个路径转发给网关。没有设置 `public_url` 时,导入会失败并提示 "Set gateway.public_url for client uploads"。
-- **有附件**:没有 shell 工具时,模型可以导入用户消息里附带的文件,文件可以是 base64 数据,也可以是附件文本,支持 Responses `input_file` 和 Anthropic `document.source` 内嵌的 `base64`、`text` 数据。Open WebUI 通常只发送提取出的文本,这些文本会作为文本文件导入。附件中的 URL 和服务商的文件 ID 不会被抓取;导入支持的远程资源时,请使用导入工具的 URL 参数。
+### 导入文件和技能
+
+OpenViking 服务提供导入工具、上下文配置也勾选了它们时,模型就能导入资料。按 URL 导入不需要额外条件;导入本地文件需要以下两种方式之一:
+
+- **客户端有 shell 工具**(名称类似 bash、shell、exec_command、terminal 或 run_command):导入工具返回一个一次性上传链接,模型再用客户端的 shell 工具上传文件,这一步经过客户端的权限确认。技能目录会先打包成 zip。链接指向 `public_url` 加 `/gateway/uploads`,所以 `public_url` 必须是客户端能访问的地址,前面的代理也要像其他路径一样转发它。没有设置 `public_url` 时,导入失败并提示 "Set gateway.public_url for client uploads"。
+- **用户消息带附件**:没有 shell 工具时,模型可以导入用户消息里附带的文件,文件可以是 base64 数据,也可以是附件文本,支持 Responses `input_file` 和 Anthropic `document.source` 中内嵌的 `base64`、`text` 数据。Open WebUI 通常只发送提取出的文本,这些文本作为文本文件导入。附件中的 URL 和服务商的文件 ID 不会被抓取;要导入远程资源,请用导入工具的 URL 参数。
上传大小受 `max_body_bytes` 限制(默认 32 MiB)。
+### 上限
+
上下文配置中 **OpenViking 工具**部分的**高级设置**里有以下上限:
| 设置 | API 名称 | 默认值 | 范围 | 达到上限时 |
| --- | --- | --- | --- | --- |
-| 每次请求的工具轮数 | `tool_max_rounds` | 不限 | 1 及以上 | 拒绝后续的 OpenViking 调用,模型用已有结果和客户端自己的工具继续。 |
+| 每次请求的工具轮数 | `tool_max_rounds` | 不限 | 1 及以上 | 拒绝之后的 OpenViking 调用,模型用已有结果和客户端自己的工具继续。 |
| 单次调用超时 | `tool_timeout_seconds` | 30 秒 | 最多 120 秒 | 这次调用向模型返回错误。 |
| 结果大小上限 | `tool_result_bytes` | 65,536 字节 | 1,024–1,048,576 | 结果被截断。 |
| 总时长 | `tool_total_seconds` | 不限 | 大于 0 秒 | 请求失败,返回 504 "Hidden tool request timed out"。 |
-| Token 预算 | `tool_total_tokens` | 不限 | 1,024 及以上 | 拒绝后续的 OpenViking 调用,模型用已有结果和客户端自己的工具继续。这不是计费上限,最终回答可能超出它。 |
+| Token 预算 | `tool_total_tokens` | 不限 | 1,024 及以上 | 拒绝之后的 OpenViking 调用,模型用已有结果和客户端自己的工具继续。这不是计费上限,最终回答可能超出它。 |
-轮数、总时长和 Token 预算默认都不限,和 Agent 自己的工具循环一样:模型会一直使用 OpenViking 工具直到完成。流式请求中,用户可以随时中断回复,客户端断开后网关也会停止。非流式请求在客户端断开后仍会继续执行,所以如果客户端发送非流式请求,请设置**总时长**。字段留空即表示不限。这项默认值修改之前保存的上下文配置仍保留原来的值(5 轮、120 秒、100,000 Token),清空这几项即可取消限制。
+轮数、总时长和 Token 预算默认都不限,和 Agent 自己的工具循环一样,模型会一直使用 OpenViking 工具直到完成。流式请求中,用户可以随时中断回复,客户端断开后网关也会停止。**非流式请求在客户端断开后仍会继续执行,所以客户端发送非流式请求时,请设置总时长。**字段留空表示不限。这几项默认值改为“不限”之前保存的上下文配置仍保留原来的值(5 轮、120 秒、100,000 token),清空即可取消限制。
-Token 预算用于模型使用 OpenViking 工具时新增的调用、结果和后续生成内容,客户端已有的对话、工具定义和图片不计入。网关保留客户端设置的回答长度上限(`max_tokens`、`max_completion_tokens` 或 `max_output_tokens`)。预算用完后,网关会拒绝之后的 OpenViking 调用,模型利用已有结果和客户端自己的工具继续回答。
+Token 预算只计算模型使用 OpenViking 工具时新增的调用、结果和后续生成内容,客户端已有的对话、工具定义和图片不计入。网关保留客户端设置的回答长度上限(`max_tokens`、`max_completion_tokens` 或 `max_output_tokens`)。
-单次工具调用失败时,模型会收到错误结果,并可据此继续回答。如果整个回答失败,例如服务商拒绝了后续模型请求,或者 OpenViking 调用被拒绝后模型仍继续调用,客户端会收到错误,请求日志中会显示 **OpenViking 工具调用失败**(`hidden_tool_loop_failed`)。流式 Responses 请求以 `response.failed` 事件结束;Chat Completions 和 Anthropic Messages 返回 `gateway_tool_error` 错误。
+### 失败处理
-如果某个上游反复失败,可以关闭它的**允许 OpenViking 工具**。已使用过这些工具的 Claude 对话可能同时出现 **工具历史无法继续使用**(`hidden_tool_history_unavailable`):之前的思考内容无法继续使用,网关已将其去掉。可根据请求详情中的工具停用原因恢复原设置,或开始一段新对话。重试的工具调用会复用第一次调用的结果,中断的写入操作不会自动重做。
+- **单次调用失败**:模型收到错误结果,可以据此继续回答。
+- **整个回答失败**:例如服务商拒绝了后续的模型请求,或者 OpenViking 调用被拒绝后模型仍坚持调用。客户端收到错误,请求日志显示 **OpenViking 工具调用失败**(`hidden_tool_loop_failed`)。流式 Responses 请求以 `response.failed` 事件结束;Chat Completions 和 Anthropic Messages 返回 `gateway_tool_error` 错误。
+- **某个上游反复失败**:关闭它的**允许 OpenViking 工具**。用过这些工具的 Claude 对话可能随之出现**工具历史无法继续使用**(`hidden_tool_history_unavailable`):之前的思考内容无法继续使用,网关已将其去掉。可以按请求详情中的停用原因恢复设置,或者开始新对话。
+- **重试**:重试的工具调用复用第一次调用的结果,中断的写入操作不会自动重做。
## 长对话
-模型的上下文窗口限制了一段对话能有多长。开启**压缩**(默认开启)后,网关会在对话撑满窗口之前,把较早的部分换成一份摘要。
+模型的上下文窗口限制了一段对话的长度。开启**压缩**(默认开启)后,网关会在对话撑满窗口之前,把较早的部分换成一份摘要。
-**何时压缩。** 每收到一条新的用户消息或一个工具步骤,网关都会估算上下文窗口用了多少:取服务商为这段对话上一次回复报告的 token 用量,再加上之后新增消息的估算值。没有这份用量时(例如流式 Chat Completions 没有设置 `stream_options.include_usage`),就估算整个请求。估算值达到**压缩时机**(窗口的 0.9)时,网关开始压缩。辅助请求、子 Agent 请求和 token 计数请求不会触发压缩。
+**何时压缩。** 每收到一条新的用户消息或一个工具步骤,网关都估算一次窗口用量:取服务商为这段对话上一次回复报告的 token 用量,加上之后新增消息的估算值。没有这份用量时(例如流式 Chat Completions 没有设置 `stream_options.include_usage`),就估算整个请求。估算值达到**压缩时机**(窗口的 0.9)时开始压缩。辅助请求、子 Agent 请求和 token 计数请求不触发压缩。
-上下文窗口取自上游**上下文窗口**中该模型的条目(按发给上游的模型名查找),没有时取上下文配置的**默认上下文窗口**。两者都没有,网关按 1,000,000 token 计算。窗口更小的模型请设置其中一项,否则还没等到压缩,服务商就会以对话过长为由拒绝请求。
+**窗口大小从哪来。** 网关先查上游**上下文窗口**中该模型的条目(按发给上游的模型名查找),没有时用上下文配置的**默认上下文窗口**,两者都没有时按 1,000,000 token 计算。使用窗口更小的模型时请设置其中一项,否则还没等到压缩,服务商就会以对话过长为由拒绝请求。
-**摘要怎么生成。** 网关向同一个上游、同一个模型额外发一次非流式请求,客户端的系统提示词、工具和思考设置都保持不变,所以大部分内容能命中服务商的提示词缓存。纯文本摘要无法遵守的设置会去掉:强制的工具选择改为不调用工具,结构化输出格式和停止序列也不保留。这个请求包含压缩位置之前的对话,以及一条要求模型为自己写摘要的指令。摘要要覆盖:用户的目标和最新请求的原文、关键决定和当前进度、文件、路径和标识符、出过的错误和修正、未完成的事项,以及最近几次工具结果里的要点。之前的摘要会并进新摘要。摘要是纯文本,最多**摘要长度上限**个 token(8,000)。思考内容也计入输出上限,而有些模型(如 DeepSeek V4.1)即使请求里没有思考设置也会默认思考,所以网关总是在摘要长度上限之外再留 16,000 token 的输出余量;客户端手动指定了思考预算时,改为加上这份预算。这次请求和其他请求一样由服务商计费。
+**摘要怎么生成。** 网关向同一个上游、同一个模型额外发一次非流式请求,客户端的系统提示词、工具和思考设置保持不变,所以大部分内容能命中服务商的提示缓存。纯文本摘要做不到的设置会被去掉:强制的工具选择改为不调用工具,结构化输出格式和停止序列也不保留。这次请求包含压缩位置之前的对话,以及一条让模型为自己写摘要的指令,摘要要覆盖:
-**之后模型收到什么。** 压缩位置取决于请求类型:
+- 用户的目标和最新请求的原文;
+- 关键决定和当前进度;
+- 文件、路径和标识符;
+- 出过的错误和修正;
+- 未完成的事项;
+- 最近几次工具结果里的要点。
+
+之前的摘要会并入新摘要。摘要是纯文本,最长**摘要长度上限**(8,000)个 token。思考内容也计入输出上限,而有些模型(如 DeepSeek V4.1)即使请求里没有思考设置也会默认思考,所以网关总在摘要长度上限之外再留 16,000 token 的输出余量;客户端手动指定了思考预算时,改为加上这份预算。这次请求和其他请求一样由服务商计费。
+
+**压缩之后模型收到什么。** 压缩位置取决于请求类型:
- 新的用户消息:压缩位置就在这条消息之前。模型收到 system 和 developer 消息、作为一条用户消息的摘要,以及这条新消息。
- 工具步骤:压缩位置在最近一次工具结果之后,模型从摘要出发继续完成任务。
-摘要消息开头说明网关替换了对话较早的部分、这段内容不是用户写的,结尾附上这段对话开头的网关说明和用户画像,所以压缩后它们仍然保留。之后凡是重新发送这段历史的请求,包括辅助请求和 token 计数请求,都会做同样的替换;子 Agent 通常发送自己单独的历史,不受影响。每次压缩会让服务商缓存在压缩位置失效一次,之后缓存照常命中。
+摘要消息开头说明网关替换了对话较早的部分、这段内容不是用户写的;结尾附上这段对话开头的网关说明和用户画像,压缩后它们仍然保留。之后凡是重发这段历史的请求,包括辅助请求和 token 计数请求,都做同样的替换;子 Agent 通常发送自己单独的历史,不受影响。每次压缩让服务商缓存在压缩位置失效一次,之后照常命中。
-**压缩位置之前的内容不保留原文**,最近几轮也不例外。模型之前的回复和其中的思考内容都依赖被替换掉的历史,只保留其中一部分会破坏 Claude 的思考签名。压缩位置之后生成的内容照常发送,思考内容也一样。
+**压缩位置之前的原文一概不保留**,最近几轮也一样。模型之前的回复和其中的思考内容都依赖被替换掉的历史,只保留一部分会破坏 Claude 的思考签名。压缩位置之后生成的内容照常发送,包括思考内容。
-**查找被压缩的内容。** 对话本身仍然保存在 OpenViking 里。开启了**保存对话**、并且这段对话提供了 `openviking_grep` 和 `openviking_read` 工具时,摘要后面会附上查找方法:这段对话对应的 OpenViking 会话(`viking://user/<user_id>/sessions/<session_id>/`)、会话里消息的存放位置,以及检索步骤:先用具体的关键词 grep 会话,拿到行号,再读取匹配位置前后的内容。如果压缩发生在一轮对话中间,压缩位置之前的部分会立即保存到 OpenViking,模型在这一轮里就能检索到。
+**查找被压缩的内容。** 对话本身仍保存在 OpenViking 里。开启了**保存对话**、这段对话也提供了 `openviking_grep` 和 `openviking_read` 工具时,摘要后面会附上查找方法:这段对话对应的 OpenViking 会话(`viking://user/<user_id>/sessions/<session_id>/`)、会话中消息的存放位置,以及检索步骤:先用具体关键词 grep 会话拿到行号,再读取匹配位置前后的内容。压缩发生在一轮中间时,压缩位置之前的部分会立即保存到 OpenViking,模型在这一轮里就能检索到。
-**压缩失败时。** 如果摘要请求失败,或者回复里调用了工具、内容为空、因长度上限被截断,网关就改为发送完整历史,并且 60 秒内不会在这段对话里再次尝试。请求日志中这条请求的详情会显示**压缩失败**及原因。如果摘要写完后上下文仍达到**压缩时机**,比如系统提示词和工具本身就占了窗口的大部分,网关会保留这份摘要,但同样等 60 秒再尝试压缩,原因显示为 `still_over_threshold`。
+**压缩失败时。** 摘要请求失败,或者回复里调用了工具、内容为空、因长度上限被截断时,网关改为发送完整历史,并在 60 秒内不再为这段对话尝试压缩。请求详情会显示**压缩失败**及原因。如果摘要写完后用量仍达到**压缩时机**(例如系统提示词和工具本身就占了窗口的大部分),网关保留这份摘要,同样 60 秒后再尝试,原因显示为 `still_over_threshold`。
-**不再使用 Working Memory。** 摘要由对话所用的模型生成,不再使用 OpenViking 的会话摘要。网关新建的 OpenViking 会话都关闭了 Working Memory:提交时仍会归档消息,OpenViking 也照常提取记忆,只是不再生成会话摘要。
+**不再生成 Working Memory 摘要。** 摘要由对话所用的模型生成,不使用 OpenViking 的会话摘要。网关新建的 OpenViking 会话都关闭了 Working Memory:提交时照常归档消息、提取记忆,只是不生成会话摘要。
-**记忆预算。** 每压缩一次,**单个上下文窗口预算**就重新计算,压缩位置之前补充过的记忆也可能再次补充。
+**记忆预算重新计算。** 每压缩一次,**单个上下文窗口预算**就重新计算,压缩位置之前补充过的记忆可能再次补充。
-**客户端自己的压缩。** 网关压缩之后,客户端仍会发送完整历史,网关在每个请求里把压缩位置之前的部分替换掉。客户端看到的用量很小,按 token 用量决定是否压缩的客户端很少再自己压缩,所以特别长的会话最终可能超过 `max_body_bytes`。客户端压缩或编辑历史后,网关把新历史保存到新的 OpenViking 会话;检索工具可用时,新历史开头的网关说明会告诉模型之前的会话在哪里。
+**客户端仍发送完整历史。** 网关压缩后,客户端还是发送完整历史,网关在每个请求里替换压缩位置之前的部分。客户端看到的用量很小,按用量决定何时压缩的客户端很少再自己压缩,所以特别长的会话最终可能超过 `max_body_bytes`。客户端压缩或编辑历史后,网关把新历史保存到新的 OpenViking 会话;检索工具可用时,新历史开头的网关说明会告诉模型之前的会话在哪里。
-请求日志中每条请求的详情会显示上下文窗口用了多少、较早的历史是否被替换,以及新生成摘要的大小和耗时。
+请求日志中每条请求的详情会显示上下文窗口用量、较早的历史是否被替换,以及新摘要的大小和耗时。
### 实验性:Agent 自管上下文窗口
-开启 **Agent 自管上下文窗口**(默认关闭)后,由模型自己决定何时开启新的上下文窗口,并自己写交接笔记,不必等网关生成摘要。这项设置只在能使用 [OpenViking 工具](#openviking-工具)的对话中生效,其他对话不受影响,压缩照上文所述进行。开启压缩时,如果模型一直不开新窗口,压缩仍会兜底。
+开启 **Agent 自管上下文窗口**(默认关闭)后,由模型自己决定何时开启新的上下文窗口,并自己写交接笔记,不必等网关生成摘要。这项设置只对能使用 [OpenViking 工具](#openviking-工具)的对话生效,其他对话照常压缩。开启压缩时,如果模型一直不开新窗口,压缩仍会兜底。
模型会看到:
-- 在 OpenViking 工具之外多出两个工具。它们不在上下文配置的**工具**清单里,只由这项设置控制。
- - `openviking_new_context(reason, notes, next_steps)`:开启新窗口,`next_steps` 可省略。它必须在一轮里单独调用;和其他工具在同一轮调用时,这一轮的每个调用都返回错误,窗口不会重置。如果网关在本次请求里已经在同一位置替换过上下文,比如刚压缩过,它同样返回错误。
+- **两个额外的工具**。它们不在上下文配置的**工具**清单里,只由这项设置控制:
+ - `openviking_new_context(reason, notes, next_steps)`:开启新窗口,`next_steps` 可省略。它必须在一轮里单独调用;和其他工具同一轮调用时,这一轮的每个调用都返回错误,窗口不重置。网关在本次请求里已经在同一位置替换过上下文(例如刚压缩过)时,它同样返回错误。
- `openviking_context_remaining()`:返回窗口序号、已用和剩余 token 的估算值、本窗口内的用户轮数、距用户上一条消息的时间,以及一句建议。
-- 开头的网关说明里多一行,告诉模型它用这两个工具自己管理上下文窗口。
-- 每条新的用户消息之后,记忆块末尾有一行状态:`[context-status] window wN · ~X/Y tokens (P%) · T since your previous message`。
-- 窗口用到**软提醒时机**(0.7)和**硬提醒时机**(0.85)时,网关分别发出软提醒和硬提醒。软提醒每个窗口只发一次,要求模型做完当前这一步就开启新窗口,并在交接笔记里记下之后要用到的确切路径、行号和取值。硬提醒要求模型立即开启新窗口,此后每一步都会重复,直到模型开启新窗口或压缩接手。提醒附在新的用户消息上,工具步骤里则附在工具结果上。
+- **开头的网关说明里多一行**,告诉模型它用这两个工具自己管理上下文窗口。
+- **一行状态**:每条新的用户消息之后,记忆块末尾附上 `[context-status] window wN · ~X/Y tokens (P%) · T since your previous message`。
+- **两级提醒**:窗口用到**软提醒时机**(0.7)时,网关提醒一次,要求模型做完当前这一步就开启新窗口,并在交接笔记里记下之后要用的确切路径、行号和取值。用到**硬提醒时机**(0.85)时,要求模型立即开启新窗口,此后每一步都重复,直到模型开启新窗口或压缩接手。提醒附在新的用户消息上,工具步骤里则附在工具结果上。
-模型调用 `openviking_new_context` 后,网关把目前为止的对话换成一个窗口头,模型在同一条回复里接着工作。窗口头先说明这是模型开启的第 N 个窗口、内容不是用户写的,然后依次是 reason、notes 和 next_steps、用户最新一条消息的原文、检索之前窗口的方法(条件和压缩时相同),以及这段对话开头的网关说明。之后的请求会根据客户端的历史重建同一个窗口。重置之前的内容会立即保存到 OpenViking,之后仍可检索。reason 和 notes 只出现在窗口头里,不会保存到 OpenViking。每次重置会让服务商缓存失效一次,但不需要摘要请求。
+模型调用 `openviking_new_context` 后,网关把目前为止的对话换成一个窗口头,模型在同一条回复里接着工作。窗口头依次包含:这是模型开启的第 N 个窗口、内容不是用户写的;reason、notes 和 next_steps;用户最新一条消息的原文;检索之前窗口的方法(条件和压缩时相同);这段对话开头的网关说明。之后的请求会根据客户端的历史重建同一个窗口。重置之前的内容会立即保存到 OpenViking,之后仍可检索;reason 和 notes 只出现在窗口头里,不保存到 OpenViking。每次重置让服务商缓存失效一次,但不需要摘要请求。
请求日志中每条请求的详情会显示窗口序号、模型是否开启了新窗口,以及收到了哪种提醒。效果取决于所用的模型,后续版本中的行为也可能调整。
## 安全与数据
-**按用户隔离。** 每个网关密钥绑定一位 OpenViking 用户。网关用这位用户自己的 OpenViking 密钥搜索记忆、保存对话和调用工具,所以权限不会超出用户本人;各用户的对话状态也互相隔离。会话和记忆的正本始终在 OpenViking,网关只保存让对话继续所需的状态。
-
-**网关存储什么。** 网关在 `storage_path` 下保存两个 SQLite 数据库:
+**按用户隔离。** 每把网关密钥绑定一位 OpenViking 用户。网关用这位用户自己的 OpenViking 密钥检索记忆、保存对话和调用工具,所以能做的事不会超出用户本人的权限;各用户的对话状态互相隔离。会话和记忆的正本始终在 OpenViking,网关只保存让对话继续所需的状态。
-- `management.sqlite3`:上游、上下文配置、网关密钥、请求日志,以及 Responses ID 到上游的映射。上游 API Key、请求头的值,以及绑定到网关密钥的 OpenViking 密钥都加密存储。网关密钥本身只保存哈希和一段短前缀。
-- `kernel.sqlite3`:每段对话的状态,包括补充到消息中的记忆文本(原样放回需要它)、OpenViking 工具的往返记录、摘要,以及等待保存的对话文本。
+**网关存储什么。** `storage_path` 下有两个 SQLite 数据库,文件只有运行网关的系统用户能读取;开启[加密](#加密)后,存储的每个值也都会加密:
-存储的值都用加密密钥加密。文件只有运行网关的用户能读取。
+- `management.sqlite3`:上游、上下文配置、网关密钥、请求日志,以及每个 Responses 响应由哪个上游创建。其中包括上游 API Key、请求头的值,以及网关密钥绑定的 OpenViking 密钥,加密关闭时它们以明文存储;网关密钥本身只存哈希和一段短前缀。
+- `kernel.sqlite3`:每段对话的状态,包括补充到消息中的记忆原文(原样放回需要它)、OpenViking 工具的往返记录、摘要,以及等待保存的对话文本。
-**请求日志包含什么。** 只有元数据:请求类型、模型、状态、上游、对话 ID 的哈希、token 数、记忆条数和耗时、保存状态和异常。从不包含消息文本、召回的记忆、工具参数和结果,也不包含任何密钥。网关不写 HTTP 访问日志,错误信息也从不回显提交的值。
+**请求日志记什么。** 只有元数据:请求类型、模型、状态、上游、对话 ID 的哈希、token 数、记忆条数和耗时、保存状态和异常。不记录消息文本、召回的记忆、工具参数和结果,也不记录任何密钥。网关不写 HTTP 访问日志,错误信息也不回显提交的值。
-**服务商能看到什么。** 每个上游都会收到完整的模型输入,包括网关补充的记忆和 OpenViking 工具的结果。只添加你放心交出这些数据的服务商。
+**服务商能看到什么。** 每个上游都收到完整的模型输入,包括网关补充的记忆和 OpenViking 工具的结果。只添加你放心交出这些数据的服务商。
**保留期限。** 清理任务每小时运行一次:
@@ -615,138 +589,109 @@ Token 预算用于模型使用 OpenViking 工具时新增的调用、结果和
| --- | --- | --- |
| 对话状态 | 最后一次使用后 30 天 | `session_ttl_days` |
| 请求日志 | 30 天 | `log_retention_days` |
-| Responses ID 映射 | 30 天 | `response_ttl_seconds` |
+| Responses 响应与上游的对应关系 | 30 天 | `response_ttl_seconds` |
| OpenViking 中的会话和记忆 | 遵循 OpenViking 自己的规则 | — |
-**删除数据。**
+**删除数据。** 吊销网关密钥、或者它绑定的 OpenViking 密钥失效,都不会删除用户数据。要删除,有三种途径:
-- 在 Studio 中删除某个用户的网关数据(密钥的**更多操作**菜单 → **删除该用户的网关数据…**),或者用账号管理员密钥调用 OpenViking Server 的 `DELETE /api/v1/admin/gateway/users/{user_id}/data`。这会吊销该用户的网关密钥,并删除其对话状态。请求日志中的元数据按保留期限自然过期。
-- 在 OpenViking 中删除用户时,网关会自动执行同样的操作。删除账号时,还会从网关中删除这个账号的上游、上下文配置、密钥和请求日志。如果当时网关无法访问,OpenViking 会持续重试。不再使用网关时,把 `gateway.enabled` 设为 `false`,删除操作就不会再等待网关。
-- OpenViking 中的会话和记忆要通过 OpenViking 删除,不经过网关。
-- 在 OpenViking 中删除一条记忆,不会抹掉已经补充进对话的副本:网关为了原样放回,在对话状态里保留了补充过的记忆文本,直到对话过期。要立即清除,就删除该用户的网关数据。这会同时吊销他的全部网关密钥,之后要重新签发。
+- 账号管理员或 root 在 Studio 中用**删除该用户的网关数据…**,或者调用 `DELETE /gateway/admin/users/{user_id}/data`:吊销该用户的网关密钥,删除对话状态和日志,包括尚未保存的内容。
+- root 调用 `DELETE /gateway/admin/account/data?account_id=<account>`,清除整个账号的网关数据。
+- 嵌入部署中,在 OpenViking 里删除用户或账号时,网关自动删除对应的网关数据。独立部署没有这一步,数据保留到显式删除或过期。
+
+已存入 OpenViking 的记忆和会话不受这些操作影响。反过来,在 OpenViking 中删除一条记忆后,网关为进行中的对话保存的那份记忆副本仍会被原样放回,直到对话过期;要立即清除,删除该用户的网关数据。
**访问控制。**
-- 客户端用网关密钥认证,放在 `Authorization: Bearer` 或 `x-api-key` 中。密钥可以随时吊销。
-- 网关用每个用户自己的 OpenViking 密钥做记忆搜索、保存和工具调用,所以它能做的事不会超出这个用户的权限。
-- 管理令牌只应由 OpenViking Server 持有,网关的 `/admin/*` 路径必须保持私有(见[路由](#路由))。Studio 用户由 OpenViking Server 校验:只有账号管理员和 root 能访问,并且只能管理自己的账号。管理令牌则不受账号限制,持有它就能管理所有账号,所以网关端口不能对公网开放。
-- 账号管理员能为本账号的任何用户签发网关密钥(OpenViking 只保存密钥哈希时,需要用户本人提供密钥)。拿到网关密钥就能以该用户的身份召回记忆、调用工具,所以签发权实际上等于读取本账号所有用户记忆的权限,只交给可信的管理员。
+- 客户端用网关密钥认证,放在 `Authorization: Bearer` 或 `x-api-key` 中,密钥可以随时吊销。
+- 管理密钥只控制上游和上下文配置的修改,不授予读取记忆、日志或签发密钥的权限,见[权限矩阵](../api/25-gateway.md#凭证和账号范围)。
+- 账号管理员能给本账号的任何用户签发网关密钥(OpenViking 只存密钥哈希时,需要用户本人提供密钥)。拿到网关密钥就能以该用户的身份召回记忆、调用工具,所以签发权实际上等于读取本账号所有用户记忆的权限,只交给可信的管理员。
- `/gateway/uploads` 不需要网关密钥。每次上传由 OpenViking 签发的一次性令牌授权,网关只把它转发到 OpenViking 的上传接口。不要让它的查询字符串出现在代理日志里。
- `X-OpenViking-*` 请求头、客户端凭证和 Cookie 从不转发给上游。
-**备份。** 备份 `storage_path`,包括两个数据库及其 `-wal` 和 `-shm` 文件,并和加密密钥放在一起。要得到一致的副本,先停止网关,或者使用 SQLite 的在线备份(`sqlite3 kernel.sqlite3 ".backup kernel.backup.sqlite3"`,`management.sqlite3` 同理)。各种丢失的后果如下:
+**备份。** 备份 `storage_path`,包括两个数据库及其 `-wal`、`-shm` 文件;开启加密时,还要保管好 OpenViking 根密钥的备份。要得到一致的副本,先停止网关,或者用 SQLite 的在线备份(`sqlite3 kernel.sqlite3 ".backup kernel.backup.sqlite3"`,`management.sqlite3` 同理)。丢失不同文件的后果:
-- **丢失 `kernel.sqlite3`**:之前补充的记忆无法放回。每段进行中的对话会有一次服务商缓存未命中,Claude 对话会丢失一次之前的思考内容(**记忆记录缺失**,`missing_injection_record`),尚未保存的轮次也会丢失。
-- **丢失 `management.sqlite3`**:上游、上下文配置、密钥和请求日志全部丢失。需要重新配置,并签发新密钥。
-- **丢失加密密钥**:两个数据库都无法读取,只能从空的 `storage_path` 重新开始。
+- **丢失 `kernel.sqlite3`**:之前补充的记忆无法放回。每段进行中的对话会有一次服务商缓存未命中,Claude 对话会丢掉一次之前的思考内容(**记忆记录缺失**,`missing_injection_record`),尚未保存的轮次也会丢失。
+- **丢失 `management.sqlite3`**:上游、上下文配置、密钥和请求日志全部丢失,需要重新配置并签发新密钥。
+- **丢失根密钥**(开启加密时):两个数据库中已加密的值都无法读取,只能从空的 `storage_path` 重新开始。
## 日常运维
-OpenViking 网关页面只对账号管理员和 root 开放。初次设置按“上游 → 上下文配置 → 签发密钥 → 接入”的顺序进行,之后的日常工作集中在下面几件事上。
-
-- **盯住首次调用缓存命中率。** “概览”标签页上的**首次调用缓存命中率**反映跨轮次的提示缓存,应该接近不经过网关时服务商能达到的水平;**轮内缓存命中率**覆盖工具步骤,正常时很高。明显下降时,见[首次调用缓存命中率下降](#首次调用缓存命中率下降)。
+- **盯住首次调用缓存命中率。** 它反映跨轮次的提示缓存,应该接近不经过网关时服务商能达到的水平;**轮内缓存命中率**覆盖工具步骤,正常时很高。明显下降时,见[首次调用缓存命中率下降](#首次调用缓存命中率下降)。
- **用请求日志定位单个请求。** 按新消息、工具步骤或异常筛选,展开一行就能看到召回结果、保存状态和 OpenViking 工具的停用原因,见[请求日志和概览](#请求日志和概览)。
-- **设置对外地址。** 共享部署必须设置 `public_url`。不设置时,Studio 的接入说明显示内部地址,OpenViking 工具的上传链接也无法使用。
-- **定期备份。** 备份网关存储目录和加密密钥,方法和丢失的后果见[安全与数据](#安全与数据)中的“备份”。
+- **设置对外地址。** 把 `public_url` 设为客户端访问的地址(不带 `/gateway`),反向代理后的客户端配置和上传链接才能保持一致。
+- **定期备份。** 备份网关存储目录;开启加密时还要备份 OpenViking 根密钥,见[安全与数据](#安全与数据)中的“备份”。
### 升级
-- OpenViking Server 的版本不能低于 `min_server_version`(0.4.16),否则记忆搜索和保存都会停止,也无法签发密钥。网关和 OpenViking 分开升级时,先升级 OpenViking,再升级网关。
-- 升级前阅读发布说明。新版本的网关如果不能读取旧的存储格式,会在启动时报 `Unsupported gateway schema`,见[网关无法启动](#网关无法启动)。
+- 升级前读发布说明。新版本的网关读不了旧的存储格式时,启动会报 `Unsupported gateway schema`,见[网关无法启动](#网关无法启动)。
+- 独立网关要求 OpenViking Server 不低于 `min_server_version`(0.4.16),否则记忆检索和保存都会停止,也无法签发密钥。两者分开升级时,先升级 OpenViking,再升级网关。嵌入网关和 Server 同版本发布,不做这项检查。
+- 从 sidecar 或旧版独立网关升级,见[迁移](#迁移)。
### 观测
-网关不导出 Prometheus 之类的监控指标,也不写 HTTP 访问日志。运行状态通过 Studio 的“概览”和“请求日志”标签页,或者 OpenViking Server 上的管理 API(`/api/v1/admin/gateway/overview` 和 `logs`)查看;进程是否存活可以用网关的 `/health` 检查。
+网关不导出 Prometheus 之类的监控指标,也不写 HTTP 访问日志。运行状态通过 Studio 的“概览”和“请求日志”标签页查看,或者调用管理 API 的 `/gateway/admin/overview` 和 `/gateway/admin/logs`。进程存活用 `/health` 检查:嵌入部署用 Server 的健康检查,独立部署用网关自己的。
## 设计取舍
-下表说明网关几项关键设计的原因和代价,帮助你判断它是否适合自己的场景:
+下表说明网关几项关键设计的原因和代价,帮你判断它是否适合自己的场景:
| 设计 | 选择及原因 | 代价 |
| --- | --- | --- |
-| 接入位置 | 接在模型调用路径上,而不是给每个 Agent 安装插件:装不了插件的客户端也能用,服务商密钥集中管理。 | 看不到工作目录,按项目隔离记忆要给每个项目使用不同的 OpenViking 用户。 |
-| 工具由谁执行 | 网关在回复过程中代为执行 OpenViking 工具,并把工具往返存下来,下一轮原样放回:没有工具、不支持 MCP 的客户端也能让模型主动使用记忆。 | 没有逐次确认;客户端必须每轮回传完整历史;需要管理员收紧工具清单和上限。 |
-| 记忆放在哪 | 附加在最新的用户消息末尾,而不是系统提示词里:系统提示词改动一个字,整份缓存都会失效;附加在末尾并在之后原样放回,前缀就始终不变。 | 网关必须可靠地记下每处补充的原文,记录丢失时缓存会失效一次。 |
+| 接入位置 | 接在模型调用路径上,而不是给每个 Agent 装插件:装不了插件的客户端也能用,服务商密钥集中管理。 | 看不到工作目录,按项目隔离记忆要给每个项目用不同的 OpenViking 用户。 |
+| 工具由谁执行 | 网关在回复过程中代为执行 OpenViking 工具,存下往返并在下一轮原样放回:没有工具、不支持 MCP 的客户端也能让模型主动使用记忆。 | 没有逐次确认;客户端必须每轮回传完整历史;需要管理员收紧工具清单和上限。 |
+| 记忆放在哪 | 附加在最新用户消息末尾,而不是系统提示词里:系统提示词改一个字整份缓存就失效;附加在末尾并在之后原样放回,前缀始终不变。 | 网关必须可靠地记下每处补充的原文,记录丢失时缓存失效一次。 |
| 保存时机 | 晚一轮保存:下一条消息带回上一轮,才能确认用户保留了它。 | 最后一轮要等**最新回复等待时长**(默认 10 分钟)之后才保存。 |
-| 长对话 | 由网关让同一个模型写摘要:只有网关知道模型实际收到了什么,摘要请求也大部分命中缓存。 | 触发压缩的那一轮多一次模型调用和一次计费;压缩位置之前的原文不再发给模型。 |
-| 本地状态 | 单台主机上的 SQLite,不引入 Postgres、Redis 这类依赖,适合在单台主机上自部署。 | 网关不能多机互备,是模型调用路径上的单点。 |
-| 客户端身份 | 网关签发自己的密钥,而不是直接使用 OpenViking 密钥:可以单独吊销,同一个人的不同客户端可以绑定不同的上下文配置。 | 网关要加密保管用户的 OpenViking 密钥;网关密钥泄露,等于该用户的记忆泄露。 |
+| 长对话 | 由网关让同一个模型写摘要:只有网关知道模型实际收到了什么,摘要请求也大部分命中缓存。 | 触发压缩的那一轮多一次模型调用和计费;压缩位置之前的原文不再发给模型。 |
+| 本地状态 | 单台主机上的 SQLite,不引入 Postgres、Redis 这类依赖,适合自部署。 | 网关不能多机互备,是模型调用路径上的单点。 |
+| 客户端身份 | 网关签发自己的密钥,而不是直接用 OpenViking 密钥:可以单独吊销,同一个人的不同客户端可以绑定不同的上下文配置。 | 网关要保存用户的 OpenViking 密钥,因此应开启加密;网关密钥泄露,等于该用户的记忆泄露。 |
## 配置参考
-`ov.conf` 中的 `gateway` 部分,所有键都取默认值:
+两种部署用同一套字段,区别只在配置文件放在哪、用什么命令生成:
-```jsonc
-{
- "gateway": {
- "enabled": false, // 设为 true 之前,网关拒绝启动
- "host": "127.0.0.1", // 监听地址
- "port": 1935,
- "workers": 1, // 本机运行 1–64 个进程
- "url": "http://127.0.0.1:1935", // OpenViking Server 访问网关的地址
- "openviking_url": "http://127.0.0.1:1933", // 网关访问 OpenViking Server 的地址
- "public_url": "", // 客户端访问网关的地址
- "storage_path": "~/.openviking/gateway", // 只能是本地磁盘
- "encryption_key_env": "OPENVIKING_GATEWAY_ENCRYPTION_KEY",
- "admin_token_env": "OPENVIKING_GATEWAY_ADMIN_TOKEN",
- "min_server_version": "0.4.16",
- "session_ttl_days": 30,
- "response_ttl_seconds": 2592000,
- "log_retention_days": 30,
- "max_body_bytes": 33554432,
- "upstream_timeout_seconds": 600,
- "health_interval_seconds": 60
- }
-}
-```
+- **嵌入**:写在 `ov.conf` 的 `gateway` 段,由 `openviking-server init` 生成。host、port 和 workers 跟随 Server。
+- **独立**:写在 `gateway.conf` 的根层,没有 `gateway` 外层,由 `openviking-gateway init` 生成。设置了 `--config` 或 `OPENVIKING_GATEWAY_CONFIG_FILE` 时,它必须指向已存在的文件;两者都没设置时,网关读取 `~/.openviking/gateway.conf` 和 `/etc/openviking/gateway.conf` 中第一个存在的文件。`OPENVIKING_CONFIG_FILE` 只用来选择 Server 的配置。
-| 键 | 默认值 | 说明 |
-| --- | --- | --- |
-| `enabled` | `false` | 开启网关。为 false 时网关拒绝启动,Studio 的 OpenViking 网关页面显示设置卡片。 |
-| `host` | `127.0.0.1` | 监听地址。OpenViking 运行在 dev 模式时,必须是回环地址。 |
-| `port` | `1935` | 网关端口。 |
-| `workers` | `1` | 本机上的网关进程数,1–64。 |
-| `url` | `http://127.0.0.1:1935` | OpenViking Server 用来管理网关和删除数据的地址。`public_url` 为空时,Studio 也显示这个地址。 |
-| `openviking_url` | `http://127.0.0.1:1933` | 网关访问 OpenViking Server 的地址。 |
-| `public_url` | 空 | 客户端使用的地址。Studio 的接入说明显示它,OpenViking 工具的上传链接也用它。所有共享部署都应设置。 |
-| `storage_path` | `~/.openviking/gateway` | 两个数据库所在的目录,必须位于本地磁盘。 |
-| `encryption_key_env` | `OPENVIKING_GATEWAY_ENCRYPTION_KEY` | 保存加密密钥的环境变量。 |
-| `admin_token_env` | `OPENVIKING_GATEWAY_ADMIN_TOKEN` | 保存管理令牌的环境变量。 |
-| `min_server_version` | `0.4.16` | 网关支持的最低 OpenViking Server 版本。版本更低或无法解析时,记忆搜索和保存都会停止,也无法签发密钥。 |
-| `session_ttl_days` | `30` | 对话闲置多少天后删除它的状态。 |
-| `response_ttl_seconds` | `2592000` | Responses ID 到上游的映射保留多久(至少 60)。 |
-| `log_retention_days` | `30` | 请求日志的保留天数。 |
-| `max_body_bytes` | `33554432` | 请求体和上传的最大字节数(至少 1,024)。超出时返回 413。 |
-| `upstream_timeout_seconds` | `600` | 单次调用服务商的总时限。 |
-| `health_interval_seconds` | `60` | 网关检查 OpenViking 的间隔(至少 1)。 |
-
-URL 类设置必须是普通的 `http` 或 `https` 地址,不能包含账号密码、查询参数或片段;末尾的 `/` 会被去掉。
-
-**环境变量:**
-
-| 变量 | 读取方 | 用途 |
-| --- | --- | --- |
-| `OPENVIKING_GATEWAY_ENCRYPTION_KEY` | 网关 | 加密密钥(见[加密密钥和管理令牌](#加密密钥和管理令牌))。 |
-| `OPENVIKING_GATEWAY_ADMIN_TOKEN` | 网关和 OpenViking Server | 管理令牌,至少 32 个字符。 |
-| `OPENVIKING_CONFIG_FILE` | 网关和 OpenViking Server | 没有指定 `--config` 时使用的 `ov.conf` 路径。 |
+| 字段 | 适用于 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `enabled` | 嵌入 | `false` | 在 Server 中开启网关 |
+| `openviking_url` | 独立 | —(必填) | OpenViking Server 的地址 |
+| `host` | 独立 | `127.0.0.1` | 监听地址 |
+| `port` | 独立 | `1935` | 监听端口 |
+| `workers` | 独立 | `1` | worker 进程数,1–64 |
+| `encryption` | 独立 | 不设置(明文) | 字段同 `ov.conf` 的 `encryption` 段,见[加密](#加密);嵌入网关沿用 Server 的设置 |
+| `public_url` | 两者 | 空 | 客户端访问的对外地址,不带 `/gateway`(网关自己加);嵌入时为空则沿用 Server 的对外地址;都没有时接入指南用请求来源地址,文件上传不可用 |
+| `storage_path` | 两者 | `~/.openviking/gateway` | 本地存储目录 |
+| `management_key` | 两者 | 空 | 可选的网关管理密钥,至少 32 个字符 |
+| `min_server_version` | 两者 | `0.4.16` | 独立网关要求的 OpenViking Server 最低版本 |
+| `session_ttl_days` | 两者 | `30` | 对话闲置多少天后过期,最小 1 |
+| `response_ttl_seconds` | 两者 | `2592000` | Responses 响应与上游的对应关系保留多少秒,最小 60 |
+| `log_retention_days` | 两者 | `30` | 请求日志保留天数,最小 1 |
+| `max_body_bytes` | 两者 | `33554432` | 请求和上传的大小上限,至少 1,024 字节 |
+| `upstream_timeout_seconds` | 两者 | `600` | 服务商请求超时,必须大于 0 |
+| `health_interval_seconds` | 两者 | `60` | 检查 OpenViking 状态的间隔秒数,最小 1 |
+
+**环境变量优先于配置文件。** 两种部署规则相同:非空的 `OPENVIKING_GATEWAY_<字段名大写>` 环境变量(例如 `OPENVIKING_GATEWAY_PUBLIC_URL`、`OPENVIKING_GATEWAY_MANAGEMENT_KEY`)覆盖文件中的值,值为空等于没有设置。文件中的值也可以写成 `"$VAR"` 引用环境变量。`encryption` 块只能写在文件里。容器通常不需要配置文件,用环境变量设置需要的字段即可。
+
+URL 必须是 HTTP(S),不能含凭证、查询参数或 fragment。未知字段会导致校验失败;已删除的字段除外,它们会被忽略并在启动时打印警告,包括 `encryption_key_env`,以及 `ov.conf` 中[迁移](#迁移)列出的 v0.5 字段。
**上下文配置的设置。** 先列 Studio 中的名称,再列管理 API 中的名称(管理 API 把上下文配置称为 `policies`):
| Studio 名称 | API 名称 | 默认值 | 取值范围 | 含义 |
| --- | --- | --- | --- | --- |
| 名称 | `name` | `Default` | | 显示名称。 |
-| 召回记忆 | `recall` | `true` | | 为每条新的用户消息搜索记忆。 |
+| 召回记忆 | `recall` | `true` | | 为每条新的用户消息检索记忆。 |
| 会话开头提供用户画像 | `profile` | `true` | | 新对话开始时提供画像,独立于召回。 |
-| 开头内容预算 | `profile_max_tokens` | `4000` | 0–32,000 | 画像和目录的独立预算;0 表示省略。目录需要启用读取工具。 |
-| 显示召回摘要 | `show_recall` | `false` | | 在回复开头用一行说明 OpenViking 补充了什么,或召回失败的原因。模型看不到这一行。 |
-| 检索范围 | `context_types` | `memory`、`resource`、`skill` | 至少一个 | 搜索范围:记忆、资源、技能。 |
+| 开头内容预算 | `profile_max_tokens` | `4000` | 0–32,000 | 画像和目录的独立预算;0 表示省略。目录需要提供 `read` 工具。 |
+| 显示召回摘要 | `show_recall` | `false` | | 在回复开头说明 OpenViking 补充了什么,或召回失败的原因。模型看不到。 |
+| 检索范围 | `context_types` | `memory`、`resource`、`skill` | 至少一个 | 检索哪些内容:记忆、资源、技能。 |
| 单条消息预算 | `max_tokens` | `1600` | 64–32,000 | 一条消息最多补充的 token 数。 |
| 单个上下文窗口预算 | `session_max_tokens` | `30000` | ≥ 0 | 一个上下文窗口内最多补充的 token 数,每次压缩后重新计算;0 表示关闭召回。 |
| 相关度阈值 | `score_threshold` | `0.35` | 0–1 | 接受的最低相关度分数。 |
-| 超时时间 | `recall_timeout` | `2`(秒) | 最多 30 | 搜索最多等待多久,超时后消息不带记忆继续发送。 |
-| 检索文本长度 | `query_max_chars` | `8000` | 3–32,000 | 用作检索文本的消息字符数。 |
-| 按分类限量 | `quotas` | `{}`(关闭) | 键:`events`、`entities`、`preferences`、`experiences`、`resources`、`skills` | 每个分类最多取的条数;只搜索大于 0 的分类。 |
-| 保存对话 | `capture` | `true` | | 把已完成的轮次保存到 OpenViking。 |
+| 超时时间 | `recall_timeout` | `2`(秒) | 最多 30 | 检索最多等多久,超时后消息不带记忆继续发送。 |
+| 检索文本长度 | `query_max_chars` | `8000` | 3–32,000 | 取消息的多少个字符作为检索文本。 |
+| 按分类限量 | `quotas` | `{}`(关闭) | 键:`events`、`entities`、`preferences`、`experiences`、`resources`、`skills` | 每个分类最多取的条数;只检索大于 0 的分类。 |
+| 保存对话 | `capture` | `true` | | 把完成的轮次保存到 OpenViking。 |
| 最新回复等待时长 | `idle_seconds` | `600`(秒) | ≥ 1 | 停顿多久之后保存最后一轮并提交会话。 |
| 提交阈值 | `commit_tokens` | `20000` | ≥ 1 | 会话中待提交的 token 数达到这个值时提交。 |
| 保留最近消息 | `keep_recent_messages` | `10` | 0–1,000 | 提交后会话中保留的消息数。 |
@@ -755,12 +700,12 @@ URL 类设置必须是普通的 `http` 或 `https` 地址,不能包含账号
| 摘要长度上限 | `summary_max_tokens` | `8000` | 1,000–32,000 | 一份摘要最多多少 token。 |
| 默认上下文窗口 | `context_window` | 未设置(按 1,000,000 计算) | ≥ 1,024 | 上游没有列出该模型时使用的窗口。 |
| Agent 自管上下文窗口 | `agent_windows` | `false` | | 实验性。让模型自己开启新的上下文窗口;需要 OpenViking 工具。 |
-| 软提醒时机 | `window_soft_ratio` | `0.7` | 0.3–0.95,须低于 `window_hard_ratio` | 上下文窗口用到这个比例时,提醒模型尽快开启新窗口。 |
-| 硬提醒时机 | `window_hard_ratio` | `0.85` | 0.4–0.97 | 上下文窗口用到这个比例时,要求模型立即开启新窗口。 |
-| OpenViking 工具 | `gateway_tools` | `true` | | 为 Chat、完整历史的 Responses 和 Anthropic Messages 提供 OpenViking 工具。 |
-| 取消勾选的工具 | `disabled_tools` | 会修改数据的 8 个工具:`remember`、`write`、`edit`、`add_resource`、`add_skill`、`forget`、`set_acl` 和 `cancel_watch` | OpenViking 工具原名,不带 `openviking_` | 新对话不提供这些工具,其余可用工具都会提供,包括以后新增的。API 请求省略这个字段时使用默认列表;列表为空且总开关开启时,提供全部可用工具。 |
+| 软提醒时机 | `window_soft_ratio` | `0.7` | 0.3–0.95,须低于 `window_hard_ratio` | 窗口用到这个比例时,提醒模型尽快开启新窗口。 |
+| 硬提醒时机 | `window_hard_ratio` | `0.85` | 0.4–0.97 | 窗口用到这个比例时,要求模型立即开启新窗口。 |
+| OpenViking 工具 | `gateway_tools` | `true` | | 为 Chat Completions、完整历史的 Responses 和 Anthropic Messages 提供 OpenViking 工具。 |
+| 取消勾选的工具 | `disabled_tools` | 会修改数据的 8 个工具,见[选择工具](#选择工具) | OpenViking 工具原名,不带 `openviking_` | 新对话不提供这些工具,其余可用工具都提供,包括以后新增的。API 请求省略这个字段时使用默认列表;列表为空且总开关开启时,提供全部可用工具。 |
| 显示工具调用 | `show_tool_calls` | `true` | | 每次 OpenViking 工具调用都在回复里加一行提示。 |
-| 每次请求的工具轮数 | `tool_max_rounds` | `null`(不限) | 1 及以上 | 见 [OpenViking 工具](#openviking-工具)。 |
+| 每次请求的工具轮数 | `tool_max_rounds` | `null`(不限) | 1 及以上 | 见[上限](#上限)。 |
| 单次调用超时 | `tool_timeout_seconds` | `30` | 最多 120 | |
| 结果大小上限 | `tool_result_bytes` | `65536` | 1,024–1,048,576 | |
| 总时长 | `tool_total_seconds` | `null`(不限) | 大于 0 | |
@@ -773,10 +718,10 @@ URL 类设置必须是普通的 `http` 或 `https` 地址,不能包含账号
| 名称 | `name` | | 显示名称。 |
| 协议 | `protocol` | | `anthropic`(Anthropic Messages)、`chat`(Chat Completions)或 `responses`(Responses)。 |
| 服务商 | `vendor` | `generic` | `generic`、`anthropic`、`openai`、`deepseek`、`ark`(火山方舟)或 `byteplus`(BytePlus 方舟)。Studio 只提供服务商支持的协议,API 接受任意组合。 |
-| Base URL | `base_url` | | 服务商地址;各服务商的默认地址和路径规则见[上游](#上游)。 |
+| Base URL | `base_url` | | 服务商地址;默认地址和拼接规则见[上游](#上游)。 |
| API Key 由谁提供 | `auth_mode` | `managed` | `managed`(由网关保管 API Key)或 `passthrough`(每个客户端自带 API Key)。 |
-| API Key | `api_key` | | 只能写入。编辑时留空表示保留已保存的密钥。 |
-| 额外请求头 | `headers` | `{}` | 值只能写入,名称可见。 |
+| API Key | `api_key` | | 只写,见[凭证](#凭证)。 |
+| 额外请求头 | `headers` | `{}` | 只写,见[凭证](#凭证)。 |
| 模型 | `models` | `[]` | 提供的模型名;留空表示接受任何名称。 |
| 模型别名 | `aliases` | `{}` | 客户端使用的名称 → 发给上游的模型。 |
| 上下文窗口 | `context_windows` | `{}` | 模型 → token 数,每项至少 1,024。 |
@@ -785,12 +730,29 @@ URL 类设置必须是普通的 `http` 或 `https` 地址,不能包含账号
| 允许 OpenViking 工具 | `allow_gateway_tools` | `true` | 能否通过这个上游提供 OpenViking 工具。 |
| 补全推理内容回传 | `replay_reasoning` | `null`(跟随服务商) | 把客户端丢掉的推理内容补回之前的回复。`null` 时 `deepseek`、`ark` 和 `byteplus` 开启,其他服务商关闭;`true` 或 `false` 覆盖服务商默认值。Studio 中开关与服务商默认值一致时保存为 `null`。 |
| 这是 Coding Plan 或订阅密钥 | `coding_plan` | `false` | 除非另外允许,否则拒绝发往这个上游的请求。 |
-| 仍然允许 | `allow_coding_plan` | `false` | 允许使用被标记为 Coding Plan 的密钥。 |
+| 允许通过网关使用这个套餐 | `allow_coding_plan` | `false` | 允许使用被标记为 Coding Plan 的密钥。 |
| 最小可缓存长度 | `cache_min_tokens` | `1024` | 仅火山方舟和 BytePlus 方舟;影响缓存资格的报告。 |
-**网关密钥字段:** 名称(`name`)、OpenViking 密钥(`openviking_key`)、上下文配置(`policy_id`)、上游(`upstream_ids`,至少一个)和允许的模型(`models`)。通过 OpenViking Server 签发时,可以用本账号用户的 `user_id` 代替 `openviking_key`,由 OpenViking Server 读取这个用户的密钥;两者只能提供一个。
+网关密钥的字段、全部管理操作、权限规则和错误原因见[管理 API](../api/25-gateway.md)。
+
+## 迁移
+
+以下步骤适用于从早期版本的 sidecar 或独立网关迁移到嵌入网关。
-Studio 通过 OpenViking Server 上 `/api/v1/admin/gateway/` 下的管理 API 操作网关,资源包括 `overview`、`logs`、`guides`、`upstreams`、`policies`、`keys` 和 `users/{user_id}/data`。脚本也可以用账号管理员密钥调用这些路径。
+1. **先备份。** 备份 `storage_path`(两个数据库,以及存在的话 `encryption.key`)。停止旧的网关进程或 sidecar,再启用嵌入网关。
+2. **删掉旧字段。** 从 `ov.conf` 的 `gateway` 段删除 `host`、`port`、`workers`、`url`、`openviking_url`、`admin_token_env` 和 `encryption_key_env`。Server 会忽略这些字段并在启动时打印警告,旧的 `ov.conf` 仍能启动,但还是应该清理掉。`openviking-server init` → **Update gateway** 会自动删除它们。想继续独立运行网关,就运行 `openviking-gateway init`,或者把设置移到单独的 `gateway.conf`,去掉 `gateway` 外层和 `enabled`。独立网关的命令不再接受 `--openviking-url`、`--host`、`--port`、`--workers` 和 `--storage-path`,这些设置改写到 `gateway.conf` 或环境变量中。
+3. **改对外地址。** 把 `public_url` 改为 Server 的对外地址(不带 `/gateway`),或者删掉。旧版快速开始把它设成了 `http://127.0.0.1:1935`,嵌入网关不再监听这个端口,接入指南和上传链接都会指向一个不存在的地址。`openviking-server init` → **Update gateway** 发现 `public_url` 指向别的端口时,会询问是否清除。
+4. **改客户端地址和部署配置。** 网关的所有 URL 现在都在 `/gateway` 下,所以客户端要同时改端口和路径:`http://host:1935/v1` 改为 `http://host:1933/gateway/v1`,Claude Code 的 `ANTHROPIC_BASE_URL` 从 `http://host:1935` 改为 `http://host:1933/gateway`,方舟 SDK 改用 `http://host:1933/gateway/api/v3`。旧路径不再提供服务。调用管理 API 的脚本把 `/api/v1/admin/gateway/...` 改为 `/gateway/admin/...`。移除旧的 1935 Service 和 Ingress 路由、Compose 的 `gateway` 服务和 profile,以及 Helm 的 sidecar 配置 `gateway.workers`、`gateway.port`、`gateway.resources`。1935 仍是独立运行的默认端口,独立网关也使用同样的 `/gateway` 路径。
+5. **首次启动会转换已存数据。** v0.5 网关用自己的密钥加密数据。新版网关(嵌入或独立)首次启动时,用这把旧密钥解密,再按当前的[加密](#加密)设置重新写入;加密关闭时写成明文,所以想让数据继续加密,要在这次启动前开启 OpenViking 加密。旧密钥从环境变量 `OPENVIKING_GATEWAY_ENCRYPTION_KEY` 读取,或者从 `storage_path` 下的 `encryption.key` 读取。`encryption_key_env` 会被忽略:如果你曾用它指向别的环境变量,这次启动时把密钥导出为 `OPENVIKING_GATEWAY_ENCRYPTION_KEY`。存在旧的加密数据、两处却都没有密钥时,网关拒绝启动,错误信息会写明这两个位置。用 Helm 时,只在这次升级的版本中保留 `existingSecret` 里的 `encryption-key` 字段。启动成功后旧密钥不会再被读取,可以删掉这个环境变量、Secret 字段和 `encryption.key`。
+6. **移除共享 admin token。** `OPENVIKING_GATEWAY_ADMIN_TOKEN` **不会**被当作管理密钥。需要限制谁能修改上游和上下文配置时,显式设置 `management_key`。
+7. **核对上游地址。** 首次启动时,网关会改写一次已存上游的 Base URL,让每个上游继续请求升级前的同一个地址:
+ - 火山方舟和 BytePlus 方舟的 Chat Completions、Responses 上游,只有域名的补上 `/api/v3`。
+ - 其他 Chat Completions、Responses 上游,路径不以 `/v1`、`/v4` 这类版本段结尾的补上 `/v1`。这包括纯域名(`https://api.deepseek.com` → `https://api.deepseek.com/v1`),也包括带路径前缀的地址(`https://openrouter.ai/api` → `https://openrouter.ai/api/v1`,或者挂在 `/litellm` 下的自建代理)。
+ - 方舟和 BytePlus 方舟的 Anthropic 上游,只有域名的补上 `/api/compatible`。
+ - 以 `/v1` 结尾的 Anthropic Base URL 去掉 `/v1`。
+
+ 已经以其他版本段结尾的地址保持不变,例如智谱的 `https://open.bigmodel.cn/api/paas/v4`:升级前它会被拼成 `…/v4/v1` 而请求失败,升级后按填写的地址直接可用。新建和修改的上游按[上游](#上游)中的规则拼接,以 `/v1` 结尾的 Anthropic Base URL 会被拒绝。
+8. **了解日志和吊销的变化。** 请求日志新增用户列,没有用户的旧记录只出现在账号管理员和 root 的视图中。吊销密钥不再删除用户数据,显式删除和保留期照常生效。
## 故障排查
@@ -798,50 +760,49 @@ Studio 通过 OpenViking Server 上 `/api/v1/admin/gateway/` 下的管理 API
| 现象 | 原因 | 处理 |
| --- | --- | --- |
-| 某段对话没有召回,也没有保存 | 检测到 OpenViking 插件,网关让出了这段对话,召回、保存和 OpenViking 工具都交给插件。 | 正常行为,避免同一份内容补充两次、保存两次,见[网关还是插件](15-gateway.md#网关还是插件)。 |
-| 保存显示“重试中”,之后变成“已暂停” | OpenViking 拒绝保存或无法访问,常见原因是用户的 OpenViking 密钥被重新生成过。 | 修好原因后网关会自动恢复;密钥失效时重新签发网关密钥,见[OpenViking 中看不到对话](#openviking-中看不到对话)。 |
-| 上下文配置开启了工具,对话里却没有 | 还没有能用工具的请求、第一个能用的请求加载 OpenViking 工具列表失败、客户端没有回传完整历史,或者客户端自己接了 OpenViking 工具。 | 在请求日志里查看停用原因(见 [OpenViking 工具](#openviking-工具))。客户端接了 OpenViking MCP 服务器时出现 `tool_name_collision` 属于正常;其他原因修正后开始新对话。 |
+| 某段对话没有召回,也没有保存 | 检测到 OpenViking 插件,网关把召回、保存和工具都让给了插件。 | 正常行为,避免同一份内容被补充、保存两次,见[网关还是插件](15-gateway.md#网关还是插件)。 |
+| 保存显示“重试中”,之后变成“已暂停” | OpenViking 拒绝保存或无法访问;或者这段对话的网关密钥已被吊销(`gateway_key_revoked`),例如用户的 OpenViking 密钥被重新生成过。 | OpenViking 恢复后网关会自动恢复保存。密钥被吊销时,重新签发网关密钥,用户的下一个请求会恢复保存。见[OpenViking 中看不到对话](#openviking-中看不到对话)。 |
+| 上下文配置开启了工具,对话里却没有 | 还没有能用工具的请求,第一个能用的请求加载工具清单失败,客户端没有回传完整历史,或者客户端自己接了 OpenViking 工具。 | 在请求日志里查看原因(见[什么时候不提供工具](#什么时候不提供工具))。客户端接了 OpenViking MCP 服务器时出现 `tool_name_collision` 是正常的;其他原因修正后开始新对话。 |
| 请求不带记忆 | OpenViking 无法访问或超时、预算用完、没有相关内容等。 | 见[没有补充记忆](#没有补充记忆)。 |
| 长对话被服务商以过长为由拒绝 | 网关不知道模型的实际窗口,压缩得太晚。 | 见[长对话超出上下文长度](#长对话超出上下文长度)。 |
### 网关无法启动
-| 提示信息 | 原因和处理 |
-| --- | --- |
-| `configure a Fernet encryption key and an admin token of at least 32 characters` | 网关的环境里缺少加密密钥或管理令牌,或者长度不够。把两者(见[加密密钥和管理令牌](#加密密钥和管理令牌))加载到启动网关的 shell、`.env` 或 Secret 中。 |
-| `Set gateway.enabled=true in ov.conf` | 缺少这一部分、没有开启,或者网关读到了别的文件。网关依次读取 `--config`、`OPENVIKING_CONFIG_FILE`、`~/.openviking/ov.conf`,不会读取其他位置。 |
-| `Missing OpenViking Gateway dependencies: …` | 安装可选依赖:`pip install "openviking[gateway]"`。 |
-| 某个 `gateway` 字段的校验错误 | 有未知的键、拼写错误或无效的值。`${VAR}` 占位符不会展开,所以写在数字或 URL 字段里的占位符同样会报错。 |
-| `OpenViking Gateway must bind to loopback when OpenViking uses dev authentication` | OpenViking 运行在 dev 模式,而 `host` 不是回环地址。把 OpenViking 切换到 API Key 模式。 |
-| `Unsupported gateway schema; configure a fresh storage_path` | 存储由不兼容的网关版本写入。把 `storage_path` 指向一个空目录,重新设置网关。 |
+嵌入网关无法启动时,整个 OpenViking Server 都会停止。请在 Server 日志中查看启动错误(Compose 中用 `docker compose logs openviking`)。
-在 Docker Compose 中,网关反复重启通常是因为 `.env` 里的加密密钥或管理令牌为空;`docker compose logs gateway` 会显示具体信息。
+- **v0.5 数据缺少旧密钥**:存储目录里有 v0.5 网关加密的数据,但既没有 `OPENVIKING_GATEWAY_ENCRYPTION_KEY`,`storage_path` 下也没有 `encryption.key`。提供原来的密钥,见[迁移](#迁移)第 5 步。
+- **旧字段**:删除[迁移](#迁移)第 2 步列出的字段。
+- **管理密钥太短**:至少 32 个字符;用 `$VAR` 引用的环境变量没有设置时,也会报这个错。
+- **加密设置**:Server 的 `encryption` 段(嵌入)或 `gateway.conf` 的 `encryption` 块(独立)不合法,或者加载不了根密钥。见[加密指南](08-encryption.md)。
+- **存储格式不支持**(`Unsupported gateway schema`):存储目录由不兼容的网关版本写入(更旧的版本,或降级前更新的版本)。换一个空的 `storage_path`。
+- **独立运行缺少 OpenViking 地址**:运行 `openviking-gateway init`,或者设置 `OPENVIKING_GATEWAY_OPENVIKING_URL`。
+- **独立运行找不到配置文件**:`--config` 或 `OPENVIKING_GATEWAY_CONFIG_FILE` 指定的文件不存在。改正路径,或者用 `openviking-gateway init --config <路径>` 生成它。
+- **独立运行绑定非回环地址**:启动检查必须连上 OpenViking 并确认它使用 `api_key` 认证,否则网关退出。先启动 OpenViking(在容器中要等它就绪),或者绑定 `127.0.0.1`。
### Studio 显示设置卡片
-OpenViking Server 无法使用网关时,OpenViking 网关页面会显示一张设置卡片,而不是各个标签页:
-
-- **OpenViking 网关未开启**:OpenViking Server 的 `ov.conf` 中没有 `gateway.enabled: true`。加上之后重启 OpenViking Server。
-- **缺少管理令牌**:OpenViking Server 的环境里没有管理令牌,或者它短于 32 个字符。设置好之后重启 OpenViking Server;Docker Compose 通过 `.env` 设置,Helm 通过 `gateway.existingSecret` 设置。
-- **OpenViking 连不上网关**:OpenViking Server 访问不到 `gateway.url`。检查网关是否在运行,以及 `url` 是否是 OpenViking Server 能访问的地址,在 Docker Compose 中应为 `http://gateway:1935`(Helm 由 Chart 自动设置)。
-
-如果两个进程都在运行,页面却提示“密钥被拒绝,请检查连接设置”,而同一个管理员密钥在**用户与权限**页面能正常使用,就说明两个进程的管理令牌不一致,网关返回的是 401 "Invalid gateway management credential"。给两者设置相同的令牌,然后都重启。
+| 卡片 | 处理 |
+| --- | --- |
+| 这台 OpenViking 没有开启网关(404) | 运行 `openviking-server init` → **Update gateway**,或者在 `ov.conf` 中设置 `gateway.enabled: true` 后重启。使用 API 密钥的服务端上,root 也可以直接在这个页面点**开启网关**。账号管理员和普通用户看到的卡片只提示联系部署者开启网关。 |
+| 先连接 OpenViking,或者 OpenViking API 密钥无效(401) | 打开连接设置,填入当前的 OpenViking API 密钥。 |
+| 网关不支持 Trusted 模式(`trusted_mode_unsupported`) | 把 Server 改为 `api_key` 认证。 |
+| 网关连不上 OpenViking(`openviking_unreachable`) | 只出现在独立网关:检查 `openviking_url`(`gateway.conf` 或 `OPENVIKING_GATEWAY_OPENVIKING_URL`)和网络。 |
-如果侧边栏里没有**OpenViking 网关**,说明 Studio 没有管理员权限:在**连接设置**中把账号管理员或 root 的密钥填入**管理员 API 密钥**。OpenViking 运行在 dev 模式时,Studio 会隐藏管理页面。
+“上游”和“上下文配置”标签页只读,是因为部署者设置了网关管理密钥:点**输入网关管理密钥**解锁。OpenViking 的 root 或 admin API 密钥不能解锁编辑;管理密钥被更换后(`management_key_invalid`),Studio 会重新锁定。
### 签发密钥失败
-**签发网关密钥**对话框会显示签发失败的原因。括号里的代码是管理 API 返回的原因值。
+**签发密钥**对话框会显示失败原因,括号里是管理 API 返回的 `reason`。
| Studio 中的提示 | 原因和处理 |
| --- | --- |
-| 服务端读不到这个用户的 OpenViking 密钥,请改为粘贴。 | OpenViking Server 读不到所选用户的密钥,通常是因为它只保存密钥的哈希(`encryption.api_key_hashing.enabled`)。选择**粘贴 OpenViking 密钥**,填入该用户自己的密钥。 |
-| 这是 Root 密钥。(`root_key_not_allowed`) | OpenViking 密钥是 root key,或者 OpenViking 运行在 dev 模式,此时任何密钥都按 root 身份处理。请使用用户自己的密钥,并启用 API Key 模式。 |
-| 这个 OpenViking 密钥属于其他账号。 | 密钥所属的账号不是你在 Studio 中管理的账号。 |
-| OpenViking 拒绝了这个密钥。(`openviking_http_401`) | 密钥不完整、已被重新生成,或者它的用户已被删除。请使用该用户当前的密钥。 |
-| OpenViking 无法识别这个密钥所属的用户(`openviking_identity_missing`) | OpenViking 没有返回这个密钥对应的用户。请使用本账号中某个用户的密钥。 |
-| 网关连不上 OpenViking,无法校验这个密钥。(`openviking_unavailable`) | 网关访问不到 `openviking_url`。 |
-| OpenViking 版本低于网关的要求。(`openviking_version_mismatch`) | OpenViking Server 的版本低于 `min_server_version`(0.4.16),请升级。从源码仓库安装、没有版本标签的服务可能报告 `0.1.dev123` 这样的开发版本号;请安装正式版本,或者把 `min_server_version` 改成与之匹配的值。 |
+| 服务端读不到这个用户的用户 API 密钥,请改为粘贴(`user_key_unreadable`) | OpenViking Server 只保存了密钥哈希(`encryption.api_key_hashing.enabled`)。在**粘贴用户 API 密钥**中填入该用户自己的密钥。 |
+| 不接受 Root API 密钥,请使用本账号下的用户 API 密钥(`root_key_not_allowed`) | root API 密钥不能绑定到网关密钥,改用某个用户或账号管理员的 API 密钥。本地 dev 模式的 `default/default` 不受此限。 |
+| 这个 OpenViking API 密钥属于其他账号(`other_account`) | 密钥所属的账号不是你在 Studio 中管理的账号。 |
+| OpenViking 拒绝了这个密钥(`openviking_http_401`) | 密钥不完整、已被重新生成,或者用户已被删除。使用该用户当前的密钥。 |
+| OpenViking 无法识别这个密钥所属的用户(`openviking_identity_missing`) | OpenViking 没有返回这个密钥对应的用户。使用本账号中某个用户的密钥。 |
+| 网关连不上 OpenViking,无法校验这个密钥(`openviking_unavailable`) | 网关访问不到 OpenViking;独立网关检查 `openviking_url`。 |
+| OpenViking 版本低于网关的要求(`openviking_version_mismatch`) | 仅独立网关:OpenViking Server 低于 `min_server_version`(0.4.16),请升级。从源码安装、没有版本标签的服务可能报告 `0.1.dev123` 这样的开发版本号;请安装正式版本,或者把 `min_server_version` 改成与之匹配的值。 |
### 客户端收到网关返回的错误
@@ -849,79 +810,79 @@ OpenViking Server 无法使用网关时,OpenViking 网关页面会显示一张
| 状态码和提示 | 原因和处理 |
| --- | --- |
-| 401 "Invalid or revoked OpenViking Gateway key" | 客户端没有发送网关密钥、发送了已吊销的密钥,或者发送的是服务商的 API Key。检查客户端实际发送的是哪个密钥。 |
-| 403 "Claude subscription OAuth credentials are not supported" | 客户端发送了 Claude 订阅令牌,例如 Claude Code 用订阅账号登录且没有设置 `ANTHROPIC_AUTH_TOKEN`;或者上游保存的就是订阅令牌。请使用 API Key。 |
-| 403 "Model is not allowed by this key" | 模型不在密钥允许的范围内。签发一个允许这个模型的密钥。 |
+| 401 "Invalid gateway key. It may have been revoked, or removed because its OpenViking API key was regenerated…" | 客户端没有发送网关密钥,发送了已吊销的密钥或服务商的 API Key,或者用户的 OpenViking API 密钥重新生成后,网关删除了这把密钥。检查客户端实际发送的密钥,必要时重新签发。 |
+| 403 "Claude subscription OAuth credentials are not supported" | 客户端发送了 Claude 订阅令牌,例如 Claude Code 用订阅账号登录且没有设置 `ANTHROPIC_AUTH_TOKEN`;或者上游保存的就是订阅令牌。请改用 API Key。 |
+| 403 "Model is not allowed by this key" | 模型不在密钥允许的范围内。签发一把允许这个模型的密钥。 |
| 404 "No allowed upstream matches this protocol and model" | 密钥绑定的已启用上游中,没有一个使用客户端调用的 API 并提供所请求的模型。检查上游的协议、模型和别名、是否启用,以及密钥绑定了哪些上游。 |
| 401 "Upstream API key is missing" | 上游要求每个客户端在 `X-OpenViking-Upstream-Key` 中自带 API Key,或者由网关保管 API Key 的上游没有填写。 |
-| 403 "Coding Plan upstreams are disabled; configure a model API key" | 上游被标记为 Coding Plan 密钥。请改用模型 API Key,或者有意勾选**仍然允许**。 |
-| 404 "Unknown response for this key"、403 "Response upstream is no longer allowed" | 查询的 Responses 响应不是这个密钥创建的,或者它的上游已被停用、不再绑定到这个密钥。 |
+| 403 "Coding Plan upstreams are disabled; configure a model API key" | 上游被标记为 Coding Plan 密钥。改用模型 API Key,或者有意勾选**允许通过网关使用这个套餐**。 |
+| 404 "Unknown response for this key"、403 "Response upstream is no longer allowed" | 查询的 Responses 响应不是这把密钥创建的,或者创建它的上游已停用、不再绑定到这把密钥。 |
| 413 | 请求体超过了 `max_body_bytes`,或者超过了代理自己的上限。 |
| 426 | 对 Responses API 发起了 WebSocket 连接。这是预期行为,Codex 会改用 HTTP。 |
-| 502 "Model upstream is unavailable" | 网关连不上服务商,或者调用超过了 `upstream_timeout_seconds`。在上游上运行**测试连接**。 |
-| 503 "Dev authentication requires a loopback gateway" | OpenViking 运行在 dev 模式。把它切换到 API Key 模式。 |
-| 504 "Hidden tool request timed out" | OpenViking 工具的往返超过了上下文配置中工具的**总时长**;未设置**总时长**时,是工具往返中的某次模型请求超过了 `upstream_timeout_seconds`。 |
+| 502 "Model upstream is unavailable" | 网关连不上服务商,或者调用超过了 `upstream_timeout_seconds`。在上游上点**测试**。 |
+| 504 "Hidden tool request timed out" | OpenViking 工具的往返超过了上下文配置中工具的**总时长**;没有设置总时长时,是往返中某次模型请求超过了 `upstream_timeout_seconds`。 |
### 没有补充记忆
-先在请求日志里找到这个请求。找不到,说明客户端没有经过网关,或者请求被网关拒绝了(见上一节)。找到了,就展开它查看记忆搜索结果:
+先在请求日志里找到这个请求。找不到,说明客户端没有经过网关,或者请求被网关拒绝了(见上一节)。找到后展开它,查看记忆检索结果:
-- **没有找到相关内容**(`empty`):新用户通常如此。只有对话被提交、OpenViking 提取之后才会有记忆。
+- **没有找到相关内容**(`empty`):新用户通常如此。对话提交、OpenViking 提取之后才会有记忆。
- **召回已关闭或预算已用完**(`disabled`):上下文配置关闭了召回,这段对话的预算已经用完,或者消息短于 3 个字符。
-- **OpenViking 无法访问或响应超时**(`openviking_unavailable`):查看“概览”标签页上的 OpenViking 卡片。如果 OpenViking 在运行但响应慢,可以考虑调长**超时时间**。
-- **OpenViking 拒绝了这个密钥**(`openviking_http_401`):用户的 OpenViking 密钥已失效。用当前的 OpenViking 密钥签发新的网关密钥。
+- **OpenViking 无法访问或响应超时**(`openviking_unavailable`):查看“概览”标签页上的 OpenViking 卡片。OpenViking 在运行但响应慢时,可以调长**超时时间**。
+- **OpenViking 拒绝了这个密钥**(`openviking_http_401`):用户的 OpenViking 密钥已失效。用当前的密钥签发新的网关密钥。
- **OpenViking 版本低于网关的要求**(`openviking_version_mismatch`):见[签发密钥失败](#签发密钥失败)。
-- **检测到 OpenViking 插件**(`plugin_present`):网关发现了 OpenViking 插件,并让出了这段对话。
-- **类型不是新消息**:工具步骤、辅助请求和子 Agent 请求从不搜索,它们放回之前的消息得到的记忆。
+- **检测到 OpenViking 插件**(`plugin_present`):网关发现了 OpenViking 插件,让出了这段对话。
+- **类型不是新消息**:工具步骤、辅助请求和子 Agent 请求从不检索,它们放回之前的消息得到的记忆。
-搜索失败的消息之后也不会补上记忆;下一条消息会重新搜索。
+检索失败的消息之后也不会补上记忆;下一条消息会重新检索。
### OpenViking 中看不到对话
-- **保存晚一轮。** 下一条消息到达时,上一轮才会出现;最后一轮要等**最新回复等待时长**过去(默认 10 分钟)。
+- **保存晚一轮。** 下一条消息到达时,上一轮才会出现;最后一轮要等**最新回复等待时长**(默认 10 分钟)。
- **上下文配置不保存对话。** 这时**保存**列显示“已关闭”。
-- **保存正在重试或已暂停。** 展开的行会显示原因。修复原因(例如 OpenViking 密钥失效)后,网关会在 5 分钟内重试。如果对话一直暂停,使用**重新同步对话…**。
-- **检测到 OpenViking 插件**(`plugin_present`):网关不会为这段对话保存任何内容。
-- **你用其他用户的身份查看。** 会话属于网关密钥背后的 OpenViking 用户,名称为 `gateway-…`。
-- **记忆比会话出现得晚。** OpenViking 只在提交之后才在后台提取记忆。
+- **保存正在重试或已暂停。** 展开的行会显示原因。原因修复后(例如 OpenViking 恢复访问),网关会在 5 分钟内重试。原因为 `gateway_key_revoked` 时,重新签发网关密钥,下一个请求会恢复保存。对话一直暂停时,用**重新同步对话…**。
+- **检测到 OpenViking 插件**(`plugin_present`):网关不为这段对话保存任何内容。
+- **你用的是其他用户的身份。** 会话属于网关密钥背后的 OpenViking 用户,名称形如 `gateway-…`。
+- **记忆比会话出现得晚。** OpenViking 在提交之后才在后台提取记忆。
### 首次调用缓存命中率下降
-先和不经过网关时服务商能达到的命中率比较,再查看最近请求上标出的异常:
+先和不经过网关时服务商能达到的命中率比较,再看最近请求上标出的异常:
- **记忆记录缺失**(`missing_injection_record`):网关存储丢失、从旧备份恢复,或者记录已过期,之前补充的记忆无法放回。进行中的对话在一次未命中之后就会恢复。
-- **上游已切换**(`upstream_changed`):对话原来的上游被停用、没有绑定到客户端当前使用的密钥,或者不再提供这个模型,于是对话转到了另一个上游。
+- **上游已切换**(`upstream_changed`):对话原来的上游被停用、没有绑定到客户端当前用的密钥,或者不再提供这个模型,于是对话转到了另一个上游。
- **缓存参数有变化**(`ark_cache_parameters_changed`):在火山方舟或 BytePlus 方舟上,客户端在同一段对话里改变了模型、思考模式、采样参数、系统提示词或工具。
-- 没有标出异常:客户端本身可能每轮都在改动之前的消息或系统提示词,例如插入当前时间,网关无法修正这种情况。每次压缩、模型每次开启新的上下文窗口,也都会造成一次未命中,这是预期内的。
+- **没有标出异常**:客户端本身可能每轮都在改动之前的消息或系统提示词,例如插入当前时间,网关无法修正。每次压缩、模型每次开启新的上下文窗口,也都会造成一次未命中,这是预期内的。
### 长对话超出上下文长度
-如果服务商以对话过长为由拒绝长对话的请求:
+服务商以对话过长为由拒绝长对话的请求时,通常是下面三种原因之一:
-- **网关不知道模型的窗口大小。** 上游的**上下文窗口**里没有这个模型,上下文配置也没有设置**默认上下文窗口**时,网关按 1,000,000 token 计算,对窗口更小的模型来说压缩得太晚。请补上模型的窗口大小。
+- **网关不知道模型的窗口大小。** 上游的**上下文窗口**里没有这个模型,上下文配置也没有设置**默认上下文窗口**,网关就按 1,000,000 token 计算,对窗口更小的模型压缩得太晚。补上模型的窗口大小。
- **对话所用的上下文配置关闭了压缩。** 修改配置只对新对话生效。
-- **压缩失败。** 请求详情会显示原因,网关 60 秒后再次尝试。如果摘要总因长度上限被截断,就调大**摘要长度上限**。原因是 `still_over_threshold` 时,说明系统提示词、工具和摘要本身就占满了大部分窗口:调小**摘要长度上限**,或者检查模型的上下文窗口设置。
+- **压缩失败。** 请求详情会显示原因,网关 60 秒后再试。摘要总因长度上限被截断时,调大**摘要长度上限**。原因是 `still_over_threshold` 时,说明系统提示词、工具和摘要本身就占满了大部分窗口:调小**摘要长度上限**,或者检查模型的上下文窗口设置。
### 文件导入失败
- "Set gateway.public_url for client uploads":把 `public_url` 设为客户端能访问的地址。
-- 上传链接无法访问,或者返回 404:在代理中把 `/gateway/uploads` 转发给网关。
+- 上传链接无法访问或返回 404:确认 `public_url` 不是旧的 `:1935` 地址,也没有以 `/gateway` 结尾,并且代理像其他路径一样转发 `/gateway/uploads`。
- 413:文件超过了 `max_body_bytes` 或代理的上限。
- 502 "OpenViking upload is unavailable":网关连不上 OpenViking Server。
-- 没有提供导入工具:OpenViking 服务未提供该工具、上下文配置中取消了勾选,或当前请求无法使用网关工具。请检查工具清单和请求详情。
+- 模型没有导入工具:OpenViking 服务没有提供该工具,上下文配置没有勾选,或者当前请求不能使用网关工具。检查工具清单和请求详情。
### 降级请求的异常
-“请求日志”和“概览”标签页会标出网关没能完整处理的请求。Studio 显示异常名称,括号里的代码是管理 API 中对应的值:
+“请求日志”和“概览”标签页会标出网关没能完整处理的请求。Studio 显示异常名称,括号里是管理 API 中对应的值:
| 异常 | 发生了什么 | 怎么处理 |
| --- | --- | --- |
-| 记忆不可用(`memory_store_failure`) | 网关无法读写自己的存储,或者该用户的网关数据刚被删除。请求不带记忆发给了模型;对 Claude 来说,之前的思考内容被去掉了。 | 检查磁盘空间、权限和网关日志。刚删除过该用户的网关数据时出现这一项是正常的。 |
-| 原样转发(`unsafe_json`) | 请求中有无法精确重新编码的数字或重复的键,所以网关逐字节原样转发,没有补充记忆。 | 通常只与某个客户端有关,网关这边无需调整。 |
+| 记忆不可用(`memory_store_failure`) | 网关无法读写自己的存储,或者该用户的网关数据刚被删除。请求不带记忆发给了模型;Claude 对话中之前的思考内容被去掉。 | 检查磁盘空间、权限和网关日志。刚删除过该用户的网关数据时出现属于正常。 |
+| 原样转发(`unsafe_json`) | 请求中有无法精确重新编码的数字或重复的键,网关逐字节原样转发,没有补充记忆。 | 通常只与某个客户端有关,网关这边无需调整。 |
| 上游已切换(`upstream_changed`) | 对话原来的上游无法再服务,转到了另一个上游,造成一次缓存未命中,之前的 Claude 思考内容也被去掉。 | 重新启用这个上游,或者让客户端改用包含它的密钥;也可以接受这次切换。 |
-| 记忆记录缺失(`missing_injection_record`) | Claude 对话中,之前补充的记忆已经没有记录,所以之前的思考内容被去掉了一次。 | 存储丢失后,或者在很久以前的对话里出现,都在预期之内。反复出现时,开始一段新对话。 |
-| 检测到 OpenViking 插件(`plugin_present`) | 检测到了 OpenViking 插件,这段对话不再使用网关记忆。 | 使用插件时出现这一项是正常的。同一个客户端在插件和网关之间二选一。 |
-| 缓存参数有变化(`ark_cache_parameters_changed`) | 在火山方舟或 BytePlus 方舟上,影响缓存的参数与对话的第一个请求不同,提示词缓存很可能没有命中。 | 在同一段对话里保持模型、思考模式、采样参数、系统提示词和工具不变。 |
-| 工具历史无法继续使用(`hidden_tool_history_unavailable`) | Claude 对话曾使用 OpenViking 工具,但当前请求无法使用这些工具,之前的思考内容已被去掉。 | 查看请求详情中的工具停用原因,恢复原设置,或开始一段新对话。 |
-| OpenViking 工具调用失败(`hidden_tool_loop_failed`) | 模型使用 OpenViking 工具时未能完成回答,客户端收到了错误。 | 见 [OpenViking 工具](#openviking-工具)。 |
-| 回复未保存(`capture_parse_failure`) | 流式回复无法解析,这条回复没有保存。客户端不受影响。 | 无需处理,仅供了解。 |
+| 记忆记录缺失(`missing_injection_record`) | Claude 对话中,之前补充的记忆已经没有记录,之前的思考内容被去掉一次。 | 存储丢失后,或者在很久以前的对话里出现,都在预期之内。反复出现时,开始新对话。 |
+| 检测到 OpenViking 插件(`plugin_present`) | 检测到 OpenViking 插件,这段对话不再使用网关记忆。 | 使用插件时出现属于正常。同一个客户端在插件和网关之间二选一。 |
+| 缓存参数有变化(`ark_cache_parameters_changed`) | 在火山方舟或 BytePlus 方舟上,影响缓存的参数与对话的第一个请求不同,提示缓存很可能没有命中。 | 在同一段对话里保持模型、思考模式、采样参数、系统提示词和工具不变。 |
+| 工具历史无法继续使用(`hidden_tool_history_unavailable`) | Claude 对话用过 OpenViking 工具,但当前请求不能使用这些工具,之前的思考内容已被去掉。 | 查看请求详情中的工具停用原因,恢复原设置,或者开始新对话。 |
+| OpenViking 工具调用失败(`hidden_tool_loop_failed`) | 模型使用 OpenViking 工具时未能完成回答,客户端收到错误。 | 见[失败处理](#失败处理)。 |
+| 回复未保存(`capture_parse_failure`) | 流式回复无法解析,这条回复没有保存,客户端不受影响。 | 无需处理,仅供了解。 |
+| 密钥未校验(`revocation_check_unavailable`) | OpenViking 无法确认这把网关密钥,请求在没有检查是否已吊销的情况下照常处理。 | 检查 OpenViking 是否可达、运行是否正常。 |
diff --git a/openviking/config/vlm.py b/openviking/config/vlm.py
index 21bb757a8..156f17969 100644
--- a/openviking/config/vlm.py
+++ b/openviking/config/vlm.py
@@ -46,6 +46,8 @@ class VLMHandle(Protocol):
class VLMResolver(Protocol):
"""Resolve a call-safe model handle for one Account."""
+ async def effective_vlm_config(self, account_id: str) -> VLMConfig: ...
+
async def get_vlm(self, account_id: str) -> VLMHandle: ...
async def get_query_planner(self, account_id: str) -> VLMHandle: ...
@@ -190,6 +192,11 @@ class AccountVLMProvider:
consumer=self._on_cluster_config_change,
)
+ async def effective_vlm_config(self, account_id: str) -> VLMConfig:
+ """Return a detached account-effective configuration without creating clients."""
+ selection = await self._select(account_id, "vlm")
+ return VLMConfig.model_validate(selection.config.model_dump(mode="python"))
+
async def get_vlm(self, account_id: str) -> AccountBoundVLM:
return await self._new_handle(account_id, "vlm")
diff --git a/openviking/models/vlm/backends/glm_vlm.py b/openviking/models/vlm/backends/glm_vlm.py
index 8c80788ac..23900d9cb 100644
--- a/openviking/models/vlm/backends/glm_vlm.py
+++ b/openviking/models/vlm/backends/glm_vlm.py
@@ -12,12 +12,17 @@ DEFAULT_GLM_API_BASE = "https://api.z.ai/api/coding/paas/v4"
DEFAULT_GLM_MODEL = "glm-4.6v"
+def normalize_glm_config(config: Dict[str, Any]) -> Dict[str, Any]:
+ """Apply GLM defaults; the embedded gateway imports credentials through this too."""
+ normalized = dict(config)
+ normalized["provider"] = "glm"
+ normalized["model"] = normalized.get("model") or DEFAULT_GLM_MODEL
+ normalized["api_base"] = str(normalized.get("api_base") or DEFAULT_GLM_API_BASE).rstrip("/")
+ return normalized
+
+
class GLMVLM(OpenAIVLM):
"""First-class GLM backend with Coding Plan defaults."""
def __init__(self, config: Dict[str, Any]):
- normalized = dict(config)
- normalized["provider"] = "glm"
- normalized.setdefault("model", DEFAULT_GLM_MODEL)
- normalized["api_base"] = str(normalized.get("api_base") or DEFAULT_GLM_API_BASE).rstrip("/")
- super().__init__(normalized)
+ super().__init__(normalize_glm_config(config))
diff --git a/openviking/models/vlm/backends/kimi_vlm.py b/openviking/models/vlm/backends/kimi_vlm.py
index 8675069b5..87fe438f9 100644
--- a/openviking/models/vlm/backends/kimi_vlm.py
+++ b/openviking/models/vlm/backends/kimi_vlm.py
@@ -23,14 +23,20 @@ def _normalize_kimi_api_base(api_base: str | None) -> str:
return f"{normalized}/v1"
+def normalize_kimi_config(config: Dict[str, Any]) -> Dict[str, Any]:
+ """Apply Kimi defaults; the embedded gateway imports credentials through this too."""
+ normalized = dict(config)
+ model = str(normalized.get("model") or DEFAULT_KIMI_MODEL).strip() or DEFAULT_KIMI_MODEL
+ normalized["provider"] = "kimi"
+ normalized["api_base"] = _normalize_kimi_api_base(normalized.get("api_base"))
+ normalized["model"] = KIMI_LEGACY_MODEL_ALIASES.get(model, model)
+ extra_headers = dict(normalized.get("extra_headers") or {})
+ if not any(key.lower() == "user-agent" for key in extra_headers):
+ extra_headers["User-Agent"] = DEFAULT_KIMI_USER_AGENT
+ normalized["extra_headers"] = extra_headers
+ return normalized
+
+
class KimiVLM(OpenAIVLM):
def __init__(self, config: Dict[str, Any]):
- normalized = dict(config)
- model = str(normalized.get("model") or DEFAULT_KIMI_MODEL).strip() or DEFAULT_KIMI_MODEL
- normalized["provider"] = "kimi"
- normalized["api_base"] = _normalize_kimi_api_base(normalized.get("api_base"))
- normalized["model"] = KIMI_LEGACY_MODEL_ALIASES.get(model, model)
- extra_headers = dict(normalized.get("extra_headers") or {})
- extra_headers.setdefault("User-Agent", DEFAULT_KIMI_USER_AGENT)
- normalized["extra_headers"] = extra_headers
- super().__init__(normalized)
+ super().__init__(normalize_kimi_config(config))
diff --git a/openviking/models/vlm/backends/volcengine_vlm.py b/openviking/models/vlm/backends/volcengine_vlm.py
index 099cff78e..c62713c31 100644
--- a/openviking/models/vlm/backends/volcengine_vlm.py
+++ b/openviking/models/vlm/backends/volcengine_vlm.py
@@ -26,6 +26,7 @@ logger = get_logger(__name__)
VOLCENGINE_CLIENT_REQUEST_ID_HEADER = "X-Client-Request-Id"
VOLCENGINE_CLIENT_REQUEST_ID = "ToB-direct,OpenViking_Service,openviking-service_cn-beijing"
+DEFAULT_VOLCENGINE_API_BASE = "https://ark.cn-beijing.volces.com/api/v3"
def _build_volcengine_headers(extra_headers: Optional[Dict[str, str]]) -> Dict[str, str]:
@@ -63,7 +64,7 @@ class VolcEngineVLM(OpenAIVLM):
self.extra_headers = _build_volcengine_headers(self.extra_headers)
if not self.api_base:
- self.api_base = "https://ark.cn-beijing.volces.com/api/v3"
+ self.api_base = DEFAULT_VOLCENGINE_API_BASE
if not self.model:
self.model = "doubao-seed-2-0-lite-260428"
diff --git a/openviking/observability/http_observability_middleware.py b/openviking/observability/http_observability_middleware.py
index 2176d35ee..8b21df1c9 100644
--- a/openviking/observability/http_observability_middleware.py
+++ b/openviking/observability/http_observability_middleware.py
@@ -385,6 +385,21 @@ def maybe_apply_root_span_error(root_attrs: RootSpanAttributes, exc: Exception)
)
+def scope_route_template(scope: Scope) -> str:
+ """Return the matched route template, prefixed with the path of any mount it sits under.
+
+ Starlette records the innermost route in ``scope["route"]``; for a mounted sub-app
+ (the embedded gateway at ``/gateway``) its template omits the mount path, which
+ ``root_path`` minus the server's own ``app_root_path`` restores.
+ """
+ path = getattr(scope.get("route"), "path", None)
+ if not path:
+ return "/__unmatched__"
+ root_path = scope.get("root_path", "")
+ mount_path = root_path.removeprefix(scope.get("app_root_path", root_path))
+ return f"{mount_path}{path}"
+
+
def _get_route_template(request: Request) -> str:
"""
Resolve a shared low-cardinality route template for request observability.
@@ -400,11 +415,7 @@ def _get_route_template(request: Request) -> str:
has occurred, otherwise "/__unmatched__".
"""
try:
- route = request.scope.get("route")
- path = getattr(route, "path", None)
- if path:
- return str(path)
- return "/__unmatched__"
+ return scope_route_template(request.scope)
except (TypeError, AttributeError) as e:
logger.debug("Error getting route template: %s", str(e))
return "/__unmatched__"
diff --git a/openviking/server/app.py b/openviking/server/app.py
index 22fdcade8..5c0a8c627 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -5,7 +5,7 @@
import asyncio
import os
from concurrent.futures import ThreadPoolExecutor
-from contextlib import asynccontextmanager
+from contextlib import AsyncExitStack, asynccontextmanager
from pathlib import Path
from typing import Callable, Optional
@@ -25,6 +25,7 @@ from openviking.server.config import (
)
from openviking.server.dependencies import set_server_config, set_service
from openviking.server.error_mapping import map_exception
+from openviking.server.gateway_host import ScopedRoute, create_embedded_gateway
from openviking.server.identity import Role
from openviking.server.models import ERROR_CODE_TO_HTTP_STATUS, ErrorInfo, Response
from openviking.server.profile_middleware import ProfileMiddleware
@@ -57,7 +58,6 @@ from openviking.server.routers import (
watches_router,
webdav_router,
)
-from openviking.server.routers.gateway import router as gateway_router
from openviking.server.timing_middleware import RequestTimingMiddleware
from openviking.service.core import OpenVikingService
from openviking.service.task_tracker import get_task_tracker
@@ -70,9 +70,12 @@ from openviking_cli.utils.config import (
resolve_config_path,
)
from openviking_cli.utils.logger import init_otel_log_handler_from_server_config
+from openviking_gateway.config import MOUNT_PATH as GATEWAY_MOUNT_PATH
logger = get_logger(__name__)
+WORKER_HOST_ENV = "OPENVIKING_WORKER_HOST"
+WORKER_PORT_ENV = "OPENVIKING_WORKER_PORT"
WORKER_WITH_BOT_ENV = "OPENVIKING_WORKER_WITH_BOT"
WORKER_BOT_API_URL_ENV = "OPENVIKING_WORKER_BOT_API_URL"
@@ -111,6 +114,10 @@ def create_worker_app() -> FastAPI:
bot_api_url = os.environ.get(WORKER_BOT_API_URL_ENV)
if bot_api_url is not None:
config.bot_api_url = bot_api_url
+ if WORKER_HOST_ENV in os.environ:
+ config.host = os.environ[WORKER_HOST_ENV] or None
+ if WORKER_PORT_ENV in os.environ:
+ config.port = int(os.environ[WORKER_PORT_ENV])
return create_app(config, config_path=config_path)
@@ -170,6 +177,7 @@ async def _initialize_runtime_state(
manager=app.state.api_key_manager,
oauth_store=getattr(app.state, "oauth_store", None),
usage_audit_runtime=getattr(app.state, "usage_audit_runtime", None),
+ gateway_app=getattr(app.state, "gateway_app", None),
)
logger.info("OpenVikingService initialization complete")
@@ -382,9 +390,18 @@ def create_app(
# Start MCP session manager (must be active before /mcp requests)
from openviking.server.mcp_endpoint import mcp_lifespan
- async with mcp_lifespan():
+ gateway = app.state.gateway_app
+ async with AsyncExitStack() as stack:
+ await stack.enter_async_context(mcp_lifespan())
+ # Deletion setup receives the gateway, so it must be running first.
+ if gateway is not None:
+ await stack.enter_async_context(gateway.router.lifespan_context(gateway))
if service is not None:
await _initialize_runtime_state(app, service, config)
+ if gateway is not None and config.get_effective_auth_mode() == "dev":
+ from openviking_gateway.app import seed_defaults
+
+ await seed_defaults(gateway, "default")
yield
# Cleanup
@@ -457,6 +474,8 @@ def create_app(
@app.middleware("http")
async def dump_http_body(request: Request, call_next: Callable):
+ if request.url.path.startswith(GATEWAY_MOUNT_PATH + "/"):
+ return await call_next(request)
return await _dump_body_fn(request, call_next)
logger.info(
@@ -602,7 +621,6 @@ def create_app(
app.include_router(system_router)
app.include_router(acl_router)
app.include_router(admin_router)
- app.include_router(gateway_router)
app.include_router(agent_evolution_router)
app.include_router(compile_router)
app.include_router(resources_router)
@@ -793,23 +811,17 @@ def create_app(
# MCP endpoint — serves 16 tools (find, search, read, write, edit,
# list, tree, remember, add_resource, add_skill, list_watches, cancel_watch,
# grep, glob, forget, health) via streamable HTTP for MCP clients.
- from starlette.routing import Match, Route
-
from openviking.server.mcp_endpoint import create_mcp_app
- class _ScopedRoute(Route):
- """Expose the selected route through ``scope["route"]``, matching
- ``APIRoute.matches``, so outer observability can resolve the static
- ``/mcp`` route template."""
-
- def matches(self, scope):
- match, child_scope = super().matches(scope)
- if match != Match.NONE:
- child_scope["route"] = self
- return match, child_scope
-
app.routes.append(
- _ScopedRoute("/mcp", endpoint=create_mcp_app(), methods=["GET", "POST", "DELETE"])
+ ScopedRoute("/mcp", endpoint=create_mcp_app(), methods=["GET", "POST", "DELETE"])
+ )
+
+ app.state.gateway_app = create_embedded_gateway(
+ get_openviking_config(), config, lambda: service
)
+ if app.state.gateway_app is not None:
+ # The gateway answers every method and its own WebSocket upgrades below this prefix.
+ app.mount(GATEWAY_MOUNT_PATH, app.state.gateway_app)
return app
diff --git a/openviking/server/bootstrap.py b/openviking/server/bootstrap.py
index e0a95a9ae..ff850605f 100644
--- a/openviking/server/bootstrap.py
+++ b/openviking/server/bootstrap.py
@@ -20,6 +20,8 @@ import uvicorn
from openviking.server.app import (
WORKER_BOT_API_URL_ENV,
+ WORKER_HOST_ENV,
+ WORKER_PORT_ENV,
WORKER_WITH_BOT_ENV,
create_app,
)
@@ -350,6 +352,8 @@ def _main(recovery):
# can independently import the application. We stash the
# resolved config path in an env-var so that the factory can
# pick it up (ServerConfig already reads OPENVIKING_CONFIG_FILE).
+ os.environ[WORKER_HOST_ENV] = config.host or ""
+ os.environ[WORKER_PORT_ENV] = str(config.port)
os.environ[WORKER_WITH_BOT_ENV] = "1" if config.with_bot else "0"
os.environ[WORKER_BOT_API_URL_ENV] = config.bot_api_url
uvicorn.run(
diff --git a/openviking/server/gateway_host.py b/openviking/server/gateway_host.py
new file mode 100644
index 000000000..e747f9e6e
--- /dev/null
+++ b/openviking/server/gateway_host.py
@@ -0,0 +1,55 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Construction of the optional embedded gateway, and the route class /mcp shares."""
+
+import os
+
+from starlette.routing import Match, Route
+
+from openviking.server.config import get_server_url_from_server_data
+
+
+class ScopedRoute(Route):
+ """Expose the selected route through ``scope["route"]``, matching
+ ``APIRoute.matches``, so outer observability can resolve the static route template."""
+
+ def matches(self, scope):
+ match, child_scope = super().matches(scope)
+ if match != Match.NONE:
+ child_scope["route"] = self
+ return match, child_scope
+
+
+def create_embedded_gateway(openviking_config, server_config, service_source):
+ config = openviking_config.gateway
+ if not config.enabled:
+ return None
+ from openviking.crypto.config import bootstrap_encryption
+ from openviking.utils.agfs_utils import _run_coro_blocking
+ from openviking_gateway.app import create_app
+ from openviking_gateway.config import normalize_url
+
+ async def vlm_source(account_id):
+ from openviking.server.gateway_vlm import vlm_upstreams
+
+ resolver = service_source().vlm_resolver
+ if resolver is None:
+ raise RuntimeError("Account VLM configuration is not initialized")
+ return vlm_upstreams(await resolver.effective_vlm_config(account_id))
+
+ # The gateway shares the server's encryption settings; None when OV encryption is disabled.
+ encryption = {"encryption": openviking_config.encryption.model_dump()}
+ # The embedded gateway ships with this server, so the minimum-version gate never applies.
+ update = {"min_server_version": "0"}
+ # Without its own public_url the gateway shares the server's public address, which
+ # MCP upload links already use (env first, then ov.conf).
+ if not config.public_url and (
+ public := os.environ.get("OPENVIKING_PUBLIC_BASE_URL") or server_config.public_base_url
+ ):
+ update["public_url"] = normalize_url(public)
+ return create_app(
+ config.model_copy(update=update),
+ openviking_url=get_server_url_from_server_data(server_config),
+ vlm_source=vlm_source,
+ encryptor=_run_coro_blocking(bootstrap_encryption(encryption)),
+ )
diff --git a/openviking/server/gateway_vlm.py b/openviking/server/gateway_vlm.py
new file mode 100644
index 000000000..352b0cb43
--- /dev/null
+++ b/openviking/server/gateway_vlm.py
@@ -0,0 +1,129 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Translate account-effective VLM credentials into gateway upstream candidates."""
+
+import re
+from urllib.parse import urlsplit
+
+from openviking_cli.utils.config.vlm_config import VLMConfig
+
+# LiteLLM routes that speak OpenAI chat at api_base; LiteLLM sends the model name without them.
+OPENAI_CHAT_ROUTES = (
+ "openai/",
+ "hosted_vllm/",
+ "openrouter/",
+ "deepseek/",
+ "dashscope/",
+ "moonshot/",
+ "nvidia_nim/",
+ "zai/",
+ "groq/",
+ "together_ai/",
+ "fireworks_ai/",
+ "deepinfra/",
+ "xai/",
+ "lm_studio/",
+)
+# LiteLLM routes with their own wire protocol or cloud credentials; the gateway cannot forward them.
+UNSUPPORTED_ROUTES = (
+ "gemini/",
+ "vertex_ai/",
+ "bedrock/",
+ "sagemaker/",
+ "sagemaker_chat/",
+ "sagemaker_nova/",
+ "cohere/",
+ "cohere_chat/",
+ "github_copilot/",
+ "minimax/",
+)
+
+
+def _vendor(base: str) -> str:
+ host = (urlsplit(base).hostname or "").lower()
+ for suffix, vendor in (
+ ("volces.com", "ark"),
+ ("bytepluses.com", "byteplus"),
+ ("byteplus.com", "byteplus"),
+ ("openai.com", "openai"),
+ ("anthropic.com", "anthropic"),
+ ("deepseek.com", "deepseek"),
+ ):
+ if host == suffix or host.endswith("." + suffix):
+ return vendor
+ return "generic"
+
+
+def vlm_upstreams(config: VLMConfig) -> dict:
+ """Produce deterministic candidates; the gateway validates and stores them."""
+ upstreams, skipped = [], []
+ for credential in config.credentials:
+ identifier = "vlm-" + credential.id
+ settings = config.build_vlm_config_dict_for_credential(credential)
+ # Same default as VLMFactory.
+ provider = (settings.get("provider") or "openai").lower()
+ model = settings.get("model") or ""
+ base = settings.get("api_base") or ""
+ api_key = settings.get("api_key") or ""
+ headers = dict(settings.get("extra_headers") or {})
+ route = model.lower()
+ protocol = "chat"
+ reason = None
+ if provider == "openai-codex":
+ reason = "openai_codex"
+ elif provider == "azure" or (provider == "litellm" and route.startswith("azure/")):
+ reason = "azure"
+ elif provider == "volcengine":
+ from openviking.models.vlm.backends.volcengine_vlm import DEFAULT_VOLCENGINE_API_BASE
+
+ base = base or DEFAULT_VOLCENGINE_API_BASE
+ headers = {k: v for k, v in headers.items() if k.lower() != "x-client-request-id"}
+ elif provider == "openai":
+ base = base or "https://api.openai.com/v1"
+ elif provider == "kimi":
+ from openviking.models.vlm.backends.kimi_vlm import normalize_kimi_config
+
+ settings = normalize_kimi_config(settings)
+ base, model, headers = (
+ settings["api_base"],
+ settings["model"],
+ settings["extra_headers"],
+ )
+ elif provider == "glm":
+ from openviking.models.vlm.backends.glm_vlm import normalize_glm_config
+
+ settings = normalize_glm_config(settings)
+ base, model = settings["api_base"], settings["model"]
+ elif route.startswith(("ollama/", "ollama_chat/")):
+ model = model.split("/", 1)[1]
+ base = base or "http://localhost:11434"
+ if not urlsplit(base).path.strip("/"):
+ base = base.rstrip("/") + "/v1"
+ api_key = api_key or "ollama"
+ elif route.startswith("anthropic/"):
+ model = model.split("/", 1)[1]
+ protocol = "anthropic"
+ base = base or "https://api.anthropic.com"
+ elif route.startswith(UNSUPPORTED_ROUTES):
+ reason = "litellm_unsupported_route"
+ elif not base:
+ reason = "litellm_no_api_base"
+ elif route.startswith(OPENAI_CHAT_ROUTES):
+ model = model.split("/", 1)[1]
+ if reason:
+ skipped.append({"id": identifier, "reason": reason})
+ continue
+ upstreams.append(
+ {
+ "id": identifier,
+ "name": credential.id,
+ "protocol": protocol,
+ "base_url": base,
+ "api_key": api_key,
+ "headers": headers,
+ "models": [model] if model else [],
+ "vendor": _vendor(base),
+ "coding_plan": bool(re.search(r"(^|/)(coding|plan)(/|$)", urlsplit(base).path)),
+ }
+ )
+ return {"upstreams": upstreams, "skipped": skipped}
diff --git a/openviking/server/request_id.py b/openviking/server/request_id.py
index c7fcca39a..d8b5f2637 100644
--- a/openviking/server/request_id.py
+++ b/openviking/server/request_id.py
@@ -12,6 +12,7 @@ import uuid
from starlette.types import ASGIApp, Message, Receive, Scope, Send
+from openviking.observability.http_observability_middleware import scope_route_template
from openviking_cli.utils.logger import bind_log_request_id
REQUEST_ID_HEADER = "X-Request-ID"
@@ -36,12 +37,6 @@ def _resolve_request_id(scope: Scope) -> tuple[str, bool]:
return str(uuid.uuid4()), invalid
-def _route_template(scope: Scope) -> str:
- route = scope.get("route")
- path = getattr(route, "path", None)
- return str(path) if path else "/__unmatched__"
-
-
class RequestIdMiddleware:
"""Validate, bind, return, and log one request ID per HTTP request."""
@@ -87,7 +82,7 @@ class RequestIdMiddleware:
finally:
if scope["path"] not in _IGNORED_COMPLETION_ROUTES:
duration_ms = (time.perf_counter() - started_at) * 1000
- route = _route_template(scope)
+ route = scope_route_template(scope)
_completion_logger.info(
"HTTP request completed method=%s route=%s status=%d duration_ms=%.1f",
method,
diff --git a/openviking/server/routers/gateway.py b/openviking/server/routers/gateway.py
deleted file mode 100644
index b7574672b..000000000
--- a/openviking/server/routers/gateway.py
+++ /dev/null
@@ -1,97 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Account-scoped Studio management proxy; model traffic uses the gateway port."""
-
-import json
-import os
-
-import httpx
-from fastapi import APIRouter, Depends, HTTPException, Request
-from fastapi.responses import Response
-
-from openviking.server.account_user_keys import list_account_users, pick_account_user
-from openviking.server.auth import (
- get_api_key_manager_or_raise,
- get_request_context,
- require_auth_root_or_admin,
-)
-from openviking.server.identity import RequestContext, Role
-from openviking_cli.utils.config import get_openviking_config
-
-router = APIRouter(prefix="/api/v1/admin/gateway", tags=["gateway"])
-
-# Roles a gateway key may act as; root is never an account user.
-KEY_USER_ROLES = {"user", "admin"}
-
-
-async def bind_selected_user(request: Request, ctx: RequestContext, body: bytes) -> bytes:
- """Swap `user_id` in a key request for that user's key, so the browser never handles it."""
- try:
- value = json.loads(body)
- except ValueError:
- return body # The gateway rejects it without echoing the input.
- if not isinstance(value, dict) or "user_id" not in value:
- return body
- if "openviking_key" in value:
- raise HTTPException(422, "Send either user_id or openviking_key, not both")
- if ctx.role == Role.ROOT:
- # Root may resolve to another account than the one Studio shows (api_key mode
- # resolves it to `default`), so a user ID could name someone else.
- raise HTTPException(
- 400, "Root cannot choose a user; paste the user's OpenViking key instead"
- )
- rows = await list_account_users(get_api_key_manager_or_raise(request), ctx.account_id)
- row = pick_account_user(
- [row for row in rows if row["role"] in KEY_USER_ROLES],
- value.pop("user_id"),
- missing="Unknown OpenViking user in this account",
- unreadable=(
- "This user's OpenViking key cannot be read on the server; "
- "paste the user's OpenViking key instead"
- ),
- )
- return json.dumps({**value, "openviking_key": row["api_key"]}).encode()
-
-
[email protected]_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
-@require_auth_root_or_admin
-async def proxy_gateway(
- path: str, request: Request, ctx: RequestContext = Depends(get_request_context)
-):
- config = get_openviking_config().gateway
- if not config.enabled:
- raise HTTPException(503, "OpenViking Gateway is not enabled")
- token = os.environ.get(config.admin_token_env, "")
- if len(token) < 32:
- raise HTTPException(503, "OpenViking Gateway management token is not configured")
- # Only fixed management resources. No caller-supplied destination or identity.
- if (
- path.split("/", 1)[0]
- not in {"overview", "logs", "guides", "upstreams", "policies", "keys", "users", "tools"}
- or ".." in path
- ):
- raise HTTPException(404)
- headers = {
- "Authorization": "Bearer " + token,
- "X-OpenViking-Account": ctx.account_id,
- "Content-Type": "application/json",
- }
- body = await request.body()
- if request.method == "POST" and path == "keys":
- body = await bind_selected_user(request, ctx, body)
- try:
- async with httpx.AsyncClient(timeout=30, follow_redirects=False) as client:
- upstream = await client.request(
- request.method,
- config.url + "/admin/" + path,
- params=request.query_params,
- content=body,
- headers=headers,
- )
- except httpx.HTTPError:
- raise HTTPException(502, "OpenViking Gateway management service is unavailable")
- return Response(
- upstream.content,
- status_code=upstream.status_code,
- media_type=upstream.headers.get("content-type", "application/json"),
- )
diff --git a/openviking/service/deletion.py b/openviking/service/deletion.py
index 66dc96b8b..06c525d05 100644
--- a/openviking/service/deletion.py
+++ b/openviking/service/deletion.py
@@ -70,12 +70,14 @@ class DeletionService:
service_loop: asyncio.AbstractEventLoop,
oauth_store: Any = None,
usage_audit_runtime: Any = None,
+ gateway_app: Any = None,
) -> None:
self._service = service
self._manager = manager
self._service_loop = service_loop
self._oauth_store = oauth_store
self._usage_audit_runtime = usage_audit_runtime
+ self._gateway_app = gateway_app
self._request_lock = asyncio.Lock()
async def initialize(self) -> None:
@@ -307,11 +309,10 @@ class DeletionService:
try:
# Settle each started operation before propagating cancellation;
# the durable message can then resume cleanup after restart.
- gateway_config = getattr(getattr(self._service, "_config", None), "gateway", None)
- if gateway_config is not None and gateway_config.enabled:
- from openviking.service.gateway_deletion import delete_gateway_data
+ if self._gateway_app is not None:
+ from openviking_gateway.app import delete_data
- await run_to_completion(lambda: delete_gateway_data(gateway_config, account_id, user_id))
+ await run_to_completion(lambda: delete_data(self._gateway_app, account_id, user_id))
scheduler = self._service.watch_scheduler
if scheduler is not None:
await run_to_completion(lambda: scheduler.delete_tasks(account_id, user_id))
@@ -501,6 +502,7 @@ async def setup_deletion(
manager: Any,
oauth_store: Any = None,
usage_audit_runtime: Any = None,
+ gateway_app: Any = None,
) -> Optional[DeletionService]:
"""Create the deletion service after storage and authentication are ready."""
if manager is None or service.viking_fs is None or service._queue_manager is None:
@@ -511,6 +513,7 @@ async def setup_deletion(
service_loop=asyncio.get_running_loop(),
oauth_store=oauth_store,
usage_audit_runtime=usage_audit_runtime,
+ gateway_app=gateway_app,
)
await deletion_service.initialize()
return deletion_service
diff --git a/openviking/service/gateway_deletion.py b/openviking/service/gateway_deletion.py
deleted file mode 100644
index b1aae6517..000000000
--- a/openviking/service/gateway_deletion.py
+++ /dev/null
@@ -1,24 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Called by OpenViking's durable deletion consumer; failures remain retryable."""
-
-import os
-from urllib.parse import quote
-
-import httpx
-
-
-async def delete_gateway_data(config, account_id, user_id=None):
- if not config.enabled:
- return
- token = os.environ.get(config.admin_token_env, "")
- if len(token) < 32:
- raise RuntimeError("OpenViking Gateway management token is not configured")
- path = f"users/{quote(user_id, safe='')}/data" if user_id is not None else "account/data"
- async with httpx.AsyncClient(timeout=30, follow_redirects=False) as client:
- response = await client.delete(
- config.url + "/admin/" + path,
- headers={"Authorization": "Bearer " + token, "X-OpenViking-Account": account_id},
- )
- if response.status_code != 200:
- raise RuntimeError(f"OpenViking Gateway deletion failed (HTTP {response.status_code})")
diff --git a/openviking_cli/setup_wizard.py b/openviking_cli/setup_wizard.py
index f8d0b71ec..fee68473f 100644
--- a/openviking_cli/setup_wizard.py
+++ b/openviking_cli/setup_wizard.py
@@ -19,6 +19,7 @@ import tempfile
from dataclasses import dataclass
from pathlib import Path
from typing import Any
+from urllib.parse import urlsplit
from openviking_cli.utils.config.consts import DEFAULT_CONFIG_DIR, OPENVIKING_CONFIG_ENV
from openviking_cli.utils.ollama import (
@@ -1899,6 +1900,55 @@ def _wizard_server(current: dict[str, Any] | None = None) -> dict[str, Any] | No
return {"host": "0.0.0.0", "port": port, "root_api_key": root_api_key}
+def _wizard_gateway(
+ server: dict[str, Any], current: dict[str, Any] | None = None
+) -> dict[str, Any]:
+ """Enable the gateway on the server port and choose who may configure it."""
+ from openviking_gateway.config import EmbeddedGatewayConfig
+
+ # Settings the embedded gateway no longer reads are dropped on save.
+ removed = EmbeddedGatewayConfig.removed_fields
+ gateway = {k: v for k, v in (current or {}).items() if k not in removed}
+ _rule("OpenViking Gateway")
+ gateway["enabled"] = _prompt_confirm(
+ "Enable OpenViking Gateway on the same port?", default=gateway.get("enabled", False)
+ )
+ if gateway["enabled"]:
+ _check_gateway_public_url(server, gateway)
+ _prompt_gateway_access(server, gateway)
+ return gateway
+
+
+def _check_gateway_public_url(server: dict[str, Any], gateway: dict[str, Any]) -> None:
+ """Offer to clear a public_url left over from the old 1935 gateway port."""
+ public_url = str(gateway.get("public_url") or "")
+ port = urlsplit(public_url).port
+ server_port = int(server.get("port") or 1933)
+ if port is None or port == server_port:
+ return
+ print(f"\n {_yellow(f'gateway.public_url points at port {port}:')} {public_url}")
+ print(f" {_dim(f'The gateway now serves on the server port ({server_port}).')}")
+ if _prompt_confirm("Clear gateway.public_url?", default=port == 1935):
+ gateway.pop("public_url")
+
+
+def _prompt_gateway_access(server: dict[str, Any], gateway: dict[str, Any]) -> None:
+ """Remote servers choose whether users may configure upstreams themselves."""
+ if not (server.get("root_api_key") or server.get("auth_mode") == "api_key"):
+ return
+ allow_users = _prompt_confirm(
+ "Allow users to configure their own gateway upstreams?",
+ default=not bool(gateway.get("management_key")),
+ )
+ if allow_users:
+ gateway.pop("management_key", None)
+ elif not gateway.get("management_key"):
+ gateway["management_key"] = "ovgm_" + secrets.token_urlsafe(32)
+ print(f"\n {_green('Generated gateway management key — copy it to unlock editing:')}")
+ print(f"\n {_bold(gateway['management_key'])}\n")
+ print(f" {_dim('Saved in ov.conf (gateway.management_key).')}")
+
+
def _wizard_query_planner(config_dict: dict[str, Any], ollama_running: bool | None = None) -> None:
"""Optionally configure a lightweight local query-planner model.
@@ -2047,7 +2097,7 @@ def _prompt_embedding_flow(
def _update_existing_config(config_path: Path, section: str) -> int:
- """Update a single section (vlm / embedding / server) of an existing ov.conf."""
+ """Update a single section of an existing ov.conf."""
try:
data = json.loads(config_path.read_text(encoding="utf-8-sig"))
except (OSError, json.JSONDecodeError, UnicodeDecodeError) as exc:
@@ -2089,6 +2139,14 @@ def _update_existing_config(config_path: Path, section: str) -> int:
return 0
old_summary, new_summary = _summarize_model(old_dense), _summarize_model(dense)
data.setdefault("embedding", {})["dense"] = dense
+ elif section == "gateway":
+ current_gateway = _config_section(data, "gateway")
+ gateway = _wizard_gateway(_config_section(data, "server"), current_gateway)
+ old_summary, new_summary = (
+ _summarize_gateway(current_gateway),
+ _summarize_gateway(gateway),
+ )
+ data["gateway"] = gateway
else: # server
current_server = _config_section(data, "server")
server_dict = _wizard_server(current=current_server)
@@ -2104,6 +2162,14 @@ def _update_existing_config(config_path: Path, section: str) -> int:
updated_server.pop("auth_mode", None)
updated_server.pop("root_api_key", None)
data["server"] = updated_server
+ gateway = _config_section(data, "gateway")
+ if gateway.get("enabled"):
+ # Local dev has no restricted configuration; remote asks who may configure.
+ if server_dict.get("host") == "127.0.0.1":
+ gateway.pop("management_key", None)
+ else:
+ _prompt_gateway_access(updated_server, gateway)
+ data["gateway"] = gateway
print(f"\n {_bold('Change:')} {old_summary}")
print(f" {_cyan('→')} {new_summary}")
@@ -2171,6 +2237,13 @@ def _summarize_server(server: dict[str, Any]) -> str:
return f"{host}:{port} · auth {auth}"
+def _summarize_gateway(gateway: dict[str, Any]) -> str:
+ if not gateway.get("enabled"):
+ return "disabled"
+ access = "management key required" if gateway.get("management_key") else "users can configure"
+ return f"enabled on server port · {access}"
+
+
def _config_section(data: dict[str, Any], *keys: str) -> dict[str, Any]:
"""Safely walk nested dict keys, returning {} on any non-dict hop."""
node: Any = data
@@ -2197,6 +2270,7 @@ def _print_current_config(data: dict[str, Any]) -> None:
print(f" VLM: {_summarize_model(_config_section(data, 'vlm'))}")
print(f" Query planner: {_summarize_model(_config_section(data, 'query_planner'))}")
print(f" Server: {_summarize_server(_config_section(data, 'server'))}")
+ print(f" Gateway: {_summarize_gateway(_config_section(data, 'gateway'))}")
def run_init() -> int:
@@ -2212,12 +2286,13 @@ def run_init() -> int:
if config_path.exists():
print(f" {_yellow('Existing config found:')} {config_path}")
data = _load_config_data(config_path)
- vlm_now = emb_now = server_now = ""
+ vlm_now = emb_now = server_now = gateway_now = ""
if data is not None:
_print_current_config(data)
vlm_now = f"(now: {_summarize_model(_config_section(data, 'vlm'))})"
emb_now = f"(now: {_summarize_model(_config_section(data, 'embedding', 'dense'))})"
server_now = f"(now: {_summarize_server(_config_section(data, 'server'))})"
+ gateway_now = f"(now: {_summarize_gateway(_config_section(data, 'gateway'))})"
action = _prompt_choice(
"What would you like to do?",
[
@@ -2225,15 +2300,16 @@ def run_init() -> int:
("Update VLM", vlm_now),
("Update embedding", emb_now),
("Update server & auth", server_now),
+ ("Update gateway", gateway_now),
("Cancel", ""),
],
default=1,
)
- if action == 5:
+ if action == 6:
print(" Setup cancelled.\n")
return 0
- if action in (2, 3, 4):
- section = {2: "vlm", 3: "embedding", 4: "server"}[action]
+ if action in (2, 3, 4, 5):
+ section = {2: "vlm", 3: "embedding", 4: "server", 5: "gateway"}[action]
return _update_existing_config(config_path, section)
config_dict: dict[str, Any] | None = None
@@ -2282,6 +2358,7 @@ def run_init() -> int:
print("\n Setup cancelled.\n")
return 0
config_dict["server"] = server_dict
+ config_dict["gateway"] = _wizard_gateway(server_dict)
# Summary — providers/models/dimensions are shown, secrets never are.
emb = config_dict.get("embedding", {}).get("dense", {})
@@ -2295,6 +2372,7 @@ def run_init() -> int:
planner = config_dict.get("query_planner", {})
print(f" Query planner: {_summarize_model(planner)}")
print(f" Server: {_summarize_server(server_dict)}")
+ print(f" Gateway: {_summarize_gateway(config_dict['gateway'])}")
if server_dict.get("root_api_key"):
print(" Root API key: configured (hidden)")
print(" Workspace: configured (hidden)")
diff --git a/openviking_cli/utils/config/open_viking_config.py b/openviking_cli/utils/config/open_viking_config.py
index d27f84285..478a3cae4 100644
--- a/openviking_cli/utils/config/open_viking_config.py
+++ b/openviking_cli/utils/config/open_viking_config.py
@@ -36,7 +36,7 @@ from .ingest_config import IngestConfig
from .log_config import LogConfig
from .memory_config import MemoryConfig
from .oauth_config import OAuthConfig
-from .openviking_gateway_config import OpenVikingGatewayConfig
+from .openviking_gateway_config import EmbeddedGatewayConfig
from .parser_config import (
AnydocConfig,
AudioConfig,
@@ -319,7 +319,7 @@ class OpenVikingConfig(BaseModel):
description="External Connector service configuration for data import",
)
- gateway: OpenVikingGatewayConfig = Field(default_factory=OpenVikingGatewayConfig)
+ gateway: EmbeddedGatewayConfig = Field(default_factory=EmbeddedGatewayConfig)
enable_watch_scheduler: bool = Field(
default=True,
diff --git a/openviking_cli/utils/config/openviking_gateway_config.py b/openviking_cli/utils/config/openviking_gateway_config.py
index 7655e3410..b625cb7c8 100644
--- a/openviking_cli/utils/config/openviking_gateway_config.py
+++ b/openviking_cli/utils/config/openviking_gateway_config.py
@@ -1,5 +1,5 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
-from openviking_gateway.config import OpenVikingGatewayConfig
+from openviking_gateway.config import EmbeddedGatewayConfig
-__all__ = ["OpenVikingGatewayConfig"]
+__all__ = ["EmbeddedGatewayConfig"]
diff --git a/openviking_cli/utils/config/vlm_config.py b/openviking_cli/utils/config/vlm_config.py
index 832d9a53e..eed0c6ae1 100644
--- a/openviking_cli/utils/config/vlm_config.py
+++ b/openviking_cli/utils/config/vlm_config.py
@@ -721,6 +721,10 @@ class VLMConfig(BaseModel):
except Exception:
pass
+ def build_vlm_config_dict_for_credential(self, credential: VLMCredential) -> Dict[str, Any]:
+ """Return the effective backend settings for one normalized credential."""
+ return self._build_vlm_config_dict_for_credential(credential)
+
def _build_vlm_config_dict_for_credential(self, credential: VLMCredential) -> Dict[str, Any]:
"""Build VLM instance config dict for a specific credential."""
result = {
diff --git a/openviking_gateway/app.py b/openviking_gateway/app.py
index b80add9ca..25ba79310 100644
--- a/openviking_gateway/app.py
+++ b/openviking_gateway/app.py
@@ -1,160 +1,80 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
-"""Standalone ASGI host: authentication, routing, management and byte streaming."""
+"""Gateway ASGI app and the small API its hosts use.
+
+Hosts mount ``create_app`` at ``MOUNT_PATH`` and call ``seed_defaults``,
+``import_vlm_objects`` and ``delete_data``; ``standalone`` and the OpenViking server add
+their own routes and startup checks.
+"""
import asyncio
import contextlib
-import copy
-import hmac
import logging
-import secrets
import time
from contextlib import asynccontextmanager
import aiohttp
from fastapi import FastAPI, HTTPException, Request, WebSocket
+from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse, Response
-from pydantic import ValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
-from .capture import CaptureWorker, reset_capture
+from .capture import CaptureWorker
from .client import VikingClient, VikingError
-from .config import OpenVikingGatewayConfig
+from .config import PUBLIC_OPENVIKING_URLS, GatewayConfig, normalize_url
from .kernel import MemoryKernel
-from .models import CaptureReset, KeyRequest, Policy, Upstream
-from .proxy import ProxyRequest, filtered_headers, upstream_headers, upstream_url
-from .records import RecordKind as K
-from .storage import ManagementStore, SQLiteKernelStore, digest
+from .management import import_vlm_objects, register_management, request_credential
+from .models import Policy
+from .proxy import ProxyRequest, filtered_headers
+from .storage import ManagementStore, SQLiteKernelStore, delete_account_data, delete_user_data
logger = logging.getLogger(__name__)
+VIKING_DETAILS = {
+ "openviking_unavailable": "OpenViking is unreachable.",
+ "openviking_unreachable": "OpenViking is unreachable.",
+ "openviking_http_401": "OpenViking rejected the API key.",
+ "openviking_identity_missing": "OpenViking returned no identity for the API key.",
+ "trusted_mode_unsupported": "OpenViking Gateway does not support trusted authentication.",
+ "root_key_not_allowed": "A root API key cannot back a gateway key; use a user's API key.",
+ "openviking_version_mismatch": "OpenViking Server is older than this gateway requires.",
+}
-def public_object(kind, value):
- value = copy.deepcopy(value)
- if kind == "upstreams":
- value["has_api_key"] = bool(value.pop("api_key", ""))
- value["header_names"] = list(value.pop("headers", {}))
- if kind == "keys":
- value.pop("openviking_key", None)
- return value
-
+def create_app(config: GatewayConfig, *, openviking_url: str, vlm_source=None, encryptor=None):
+ """Build the gateway; ``vlm_source(account_id)`` returns ``{upstreams, skipped}`` dicts.
-def keep_upstream_secrets(payload, previous):
- """Fill write-only upstream secrets the admin left blank from the stored upstream.
-
- A blank ``api_key`` keeps the stored key. ``headers`` omitted keeps every stored header;
- otherwise the submitted names are the new header set, and a blank value keeps the stored
- value for that name (or drops the name when nothing is stored).
+ ``encryptor`` is an OpenViking ``FileEncryptor``; without one, values are stored as plaintext.
"""
- if not isinstance(payload, dict):
- raise ValueError("expected an upstream object")
- if not payload.get("api_key"):
- payload["api_key"] = previous.get("api_key", "")
- stored = previous.get("headers", {})
- headers = payload.get("headers")
- if headers is None:
- payload["headers"] = stored
- elif isinstance(headers, dict):
- payload["headers"] = {
- name: value or stored[name]
- for name, value in headers.items()
- if value or name in stored
- }
- return payload
-
-
-def overview_summary(logs):
- """Aggregate newest-first request-log records into the management overview."""
- requests = [log for log in logs if log.get("kind") != "capture"]
- groups = {}
- for label, kinds in (("first_call", {"user"}), ("continuation", {"continuation"})):
- subset = [log for log in requests if log.get("kind") in kinds]
- total = sum(
- log.get("first_upstream_input_tokens", log.get("input_tokens", 0)) for log in subset
- )
- cached = sum(
- log.get("first_upstream_cached_tokens", log.get("cached_tokens", 0)) for log in subset
- )
- hidden_calls = 0
- if label == "continuation":
- total += sum(log.get("hidden_upstream_input_tokens", 0) for log in requests)
- cached += sum(log.get("hidden_upstream_cached_tokens", 0) for log in requests)
- hidden_calls = sum(log.get("hidden_upstream_calls", 0) for log in requests)
- groups[label] = {
- "requests": len(subset) + hidden_calls,
- "input_tokens": total,
- "cached_tokens": cached,
- "cache_hit_ratio": cached / total if total else 0,
- }
- degradations = {}
- for log in logs:
- if reason := log.get("degradation"):
- degradations[reason] = degradations.get(reason, 0) + 1
- # "disabled" means recall was skipped (off, budget spent or query too short).
- recalls = [log for log in requests if log.get("recall_reason", "disabled") != "disabled"]
- capture = {}
- for log in logs:
- if log.get("session") and log.get("capture_status"):
- capture.setdefault((log["session"], log.get("protocol")), log["capture_status"])
- return {
- "requests": len(requests),
- "last_request_at": requests[0].get("time") if requests else None,
- "output_tokens": sum(log.get("output_tokens", 0) for log in requests),
- "cache": groups,
- "degradations": degradations,
- "recall_count": sum(log.get("recall_count", 0) for log in requests),
- "recall_requests": len(recalls),
- "recall_ms": sum(log.get("recall_ms", 0) for log in recalls) / len(recalls)
- if recalls
- else 0,
- "capture_issues": {
- status: sum(1 for value in capture.values() if value == status)
- for status in ("retrying", "paused")
- },
- "sample_limit": 10000,
- }
-
-
-def create_app(config: OpenVikingGatewayConfig | None = None):
- if config is None:
- from .cli import load_config
-
- config = load_config()
- encryption_key, admin_token = config.secrets()
- store = SQLiteKernelStore(config.directory / "kernel.sqlite3", encryption_key)
- management = ManagementStore(config.directory / "management.sqlite3", encryption_key)
+ store = SQLiteKernelStore(config.directory / "kernel.sqlite3", encryptor)
+ management = ManagementStore(config.directory / "management.sqlite3", encryptor)
@asynccontextmanager
async def lifespan(app):
- await store.initialize()
- await management.initialize()
- async with aiohttp.ClientSession(
- auto_decompress=False,
- trust_env=False,
- connector=aiohttp.TCPConnector(limit=1024, limit_per_host=512),
- ) as http:
- app.state.http = http
- app.state.viking = VikingClient(http, config.openviking_url, config.min_server_version)
- app.state.kernel = MemoryKernel(store, app.state.viking)
- app.state.worker = CaptureWorker(store, management, app.state.viking)
- app.state.health = {"status": "starting"}
- await refresh_health(app)
- if app.state.health.get("auth_mode") == "dev" and config.host not in {
- "127.0.0.1",
- "::1",
- "localhost",
- }:
- raise ValueError(
- "OpenViking Gateway must bind to loopback when OpenViking uses dev authentication"
- )
- task = asyncio.create_task(maintenance(app))
- try:
- yield
- finally:
- task.cancel()
- with contextlib.suppress(asyncio.CancelledError):
- await task
- store.close()
- management.close()
+ try:
+ await store.initialize()
+ await management.initialize()
+ async with aiohttp.ClientSession(
+ auto_decompress=False,
+ trust_env=False,
+ connector=aiohttp.TCPConnector(limit=1024, limit_per_host=512),
+ ) as http:
+ app.state.http = http
+ app.state.viking = VikingClient(http, openviking_url, config.min_server_version)
+ app.state.kernel = MemoryKernel(store, app.state.viking)
+ app.state.worker = CaptureWorker(store, management, app.state.viking)
+ # The first probe runs in maintenance: an embedded server is not listening yet.
+ app.state.health = {"status": "starting"}
+ task = asyncio.create_task(maintenance(app))
+ try:
+ yield
+ finally:
+ task.cancel()
+ with contextlib.suppress(asyncio.CancelledError):
+ await task
+ finally:
+ # Storage threads may still wait on this loop for the encryptor.
+ await asyncio.to_thread(store.close)
+ await asyncio.to_thread(management.close)
app = FastAPI(
title="OpenViking Gateway",
@@ -164,6 +84,13 @@ def create_app(config: OpenVikingGatewayConfig | None = None):
openapi_url=None,
)
app.state.store, app.state.management, app.state.config = store, management, config
+ app.state.openviking_url = openviking_url.rstrip("/")
+ app.state.vlm_source = vlm_source
+ app.state.warnings = (
+ ["public_openviking_without_management_key"]
+ if not config.management_key and normalize_url(openviking_url) in PUBLIC_OPENVIKING_URLS
+ else []
+ )
async def refresh_health(app):
try:
@@ -176,11 +103,20 @@ def create_app(config: OpenVikingGatewayConfig | None = None):
async def maintenance(app):
health_at = 0
cleanup_at = 0
+ retry = 1
+ reached = False
while True:
try:
if time.monotonic() >= health_at:
await refresh_health(app)
- health_at = time.monotonic() + config.health_interval_seconds
+ if app.state.health.get("status") == "degraded":
+ health_at = time.monotonic() + retry
+ # An embedded host starts OV after this loop: poll every second until then.
+ if reached:
+ retry = min(retry * 2, config.health_interval_seconds)
+ else:
+ health_at = time.monotonic() + config.health_interval_seconds
+ retry, reached = 1, True
if time.monotonic() >= cleanup_at:
await store.expire(time.time() - config.session_ttl_days * 86400)
await management.expire_logs(time.time() - config.log_retention_days * 86400)
@@ -193,214 +129,78 @@ def create_app(config: OpenVikingGatewayConfig | None = None):
logger.exception("OpenViking Gateway maintenance failed")
await asyncio.sleep(1)
+ @app.exception_handler(RequestValidationError)
+ async def invalid_request(_request, error):
+ return JSONResponse(
+ {
+ "reason": "invalid_configuration",
+ "detail": "; ".join(item["msg"] for item in error.errors()),
+ },
+ status_code=422,
+ )
+
@app.exception_handler(VikingError)
async def viking_error(_request, error):
- return JSONResponse({"error": {"message": error.reason}}, status_code=error.status)
+ return JSONResponse(
+ {
+ "reason": error.reason,
+ "detail": VIKING_DETAILS.get(error.reason, "OpenViking request failed."),
+ **(
+ {"required_version": config.min_server_version}
+ if error.reason == "openviking_version_mismatch"
+ else {}
+ ),
+ },
+ status_code=error.status,
+ )
- @app.get("/health")
- async def health():
- return {"status": "ok", "service": "openviking-gateway", "openviking": app.state.health}
+ @app.exception_handler(StarletteHTTPException)
+ async def http_error(_request, error):
+ detail = (
+ error.detail
+ if isinstance(error.detail, dict)
+ else {"reason": "gateway_http_" + str(error.status_code), "detail": error.detail}
+ )
+ return JSONResponse(detail, status_code=error.status_code, headers=error.headers)
async def authenticate(request):
- if app.state.health.get("auth_mode") == "dev" and config.host not in {
- "127.0.0.1",
- "::1",
- "localhost",
- }:
- raise HTTPException(503, "Dev authentication requires a loopback gateway")
- key = request.headers.get("x-api-key") or request.headers.get(
- "authorization", ""
- ).removeprefix("Bearer ")
+ """Return the gateway key and a degradation when OV could not confirm it."""
+ key = request_credential(request)
if key.startswith("sk-ant-oat"):
raise HTTPException(403, "Claude subscription OAuth credentials are not supported")
credential = await management.authenticate(key)
+ invalid = "Invalid gateway key. It may have been revoked, or removed because its OpenViking API key was regenerated. Issue a new key in OpenViking Studio → Gateway → Keys."
if not credential:
- raise HTTPException(401, "Invalid or revoked OpenViking Gateway key")
- return credential
-
- def admin_account(request):
- supplied = request.headers.get("authorization", "").removeprefix("Bearer ")
- if not hmac.compare_digest(supplied, admin_token):
- raise HTTPException(401, "Invalid gateway management credential")
- account = request.headers.get("x-openviking-account", "")
- if not account:
- raise HTTPException(400, "Management requires a verified account")
- return account
-
- @app.get("/admin/overview")
- async def overview(request: Request):
- logs = await management.logs(admin_account(request), 10000)
- return {
- **overview_summary(logs),
- "openviking": app.state.health,
- "log_retention_days": config.log_retention_days,
- }
-
- @app.get("/admin/logs")
- async def logs(request: Request, limit: int = 200):
- return await management.logs(admin_account(request), max(1, min(limit, 1000)))
-
- @app.post("/admin/keys/{identifier}/capture/reset")
- async def reset_session_capture(identifier: str, data: CaptureReset, request: Request):
- account = admin_account(request)
- key = await management.get(account, "keys", identifier)
- if not key:
- raise HTTPException(404, "Gateway key not found")
- scope = digest(account + "\0" + key["user_id"] + "\0" + data.protocol)
- # A session header value, or the hashed id request logs show.
- for session in (digest(data.session), data.session):
- if (K.ROOT, "") in await store.replay.read(scope, session, [""]):
- break
- else:
- raise HTTPException(404, "Gateway session not found")
- await reset_capture(store.capture, scope, session, "manual_reset")
- return {"status": "ready", "message": "Capture will resync from the next request history"}
-
- @app.get("/admin/guides")
- async def guides(request: Request):
- admin_account(request)
- return {
- "base_url": config.public_url or config.url,
- "public_url_configured": bool(config.public_url),
- }
-
- # Registered before /admin/{kind}/{identifier}, which would otherwise shadow account/data.
- @app.delete("/admin/users/{user_id}/data")
- async def delete_user_data(user_id: str, request: Request):
- account = admin_account(request)
- for key in await management.list(account, "keys"):
- if key["user_id"] == user_id:
- await management.delete(account, "keys", key["id"])
- for protocol in ("anthropic", "chat", "responses"):
- await store.expire(0, digest(account + "\0" + user_id + "\0" + protocol))
- await management.delete(account, "users", user_id)
- return {"deleted": True}
-
- @app.delete("/admin/account/data")
- async def delete_account_data(request: Request):
- account = admin_account(request)
- users = {user["user_id"] for user in await management.list(account, "users")}
- for user in users:
- await delete_user_data(user, request)
- await management.delete_account(account)
- return {"deleted": True}
-
- @app.get("/admin/tools")
- async def list_tools(request: Request):
- # Every user sees the same MCP tools, so any key OpenViking accepts will do.
- catalog, failure = [], None
- for key in await management.list(admin_account(request), "keys"):
- try:
- catalog, failure = await app.state.viking.tools(key["openviking_key"]), None
- break
- except VikingError as error:
- failure = error
- if error.status not in {401, 403}:
- break
- if failure:
- # Studio would take a passed-through 401 for its own sign-in failing.
- raise VikingError(failure.reason, 502)
- return [
- {
- "name": tool["name"],
- "description": tool.get("description", ""),
- **({"annotations": tool["annotations"]} if "annotations" in tool else {}),
- }
- for tool in catalog
- ]
-
- @app.get("/admin/{kind}")
- async def list_objects(kind: str, request: Request):
- if kind not in {"upstreams", "policies", "keys"}:
- raise HTTPException(404)
- return [public_object(kind, v) for v in await management.list(admin_account(request), kind)]
-
- @app.api_route("/admin/{kind}/{identifier}", methods=["PUT", "DELETE"])
- async def change_object(kind: str, identifier: str, request: Request):
- account = admin_account(request)
- if kind not in {"upstreams", "policies", "keys"}:
- raise HTTPException(404)
- if request.method == "DELETE":
- if kind != "keys":
- keys = await management.list(account, "keys")
- if any(
- k["policy_id"] == identifier
- if kind == "policies"
- else identifier in k["upstream_ids"]
- for k in keys
- ):
- raise HTTPException(
- 409, "Revoke or update dependent keys before deleting this object"
- )
- await management.delete(account, kind, identifier)
- return {"deleted": True}
- if kind == "keys":
- raise HTTPException(405, "Issue a replacement key using POST /admin/keys")
+ raise HTTPException(401, invalid)
+ if app.state.viking.unavailable_reason:
+ # Like recall, skip the check while OV is down instead of waiting for its timeout.
+ return credential, "revocation_check_unavailable"
try:
- payload = await request.json()
- previous = await management.get(account, kind, identifier)
- if kind == "upstreams":
- payload = keep_upstream_secrets(payload, previous or {})
- value = Upstream.model_validate(payload).model_dump()
- else:
- value = Policy.model_validate(payload).model_dump()
- except (ValidationError, ValueError):
- # Validation messages can contain the submitted secret. Do not echo input.
- raise HTTPException(
- 422, "Invalid gateway configuration; check field names, types and limits"
+ identity = await app.state.viking.identify(credential["openviking_key"])
+ except VikingError as error:
+ if error.reason != "openviking_http_401":
+ # Unconfirmed is not revoked: like recall, the request degrades instead.
+ return credential, "revocation_check_unavailable"
+ identity = None
+ # Dev identities are always default/default, so they say nothing about this key.
+ if identity is None or (
+ identity.get("auth_mode") != "dev"
+ and (
+ identity["account_id"] != credential["account"]
+ or identity["user_id"] != credential["user_id"]
)
- return public_object(kind, await management.save(account, kind, identifier, value))
+ ):
+ await management.delete(credential["account"], "keys", credential["id"])
+ raise HTTPException(401, invalid)
+ return credential, None
- @app.post("/admin/keys")
- async def issue_key(request: Request):
- account = admin_account(request)
- try:
- value = KeyRequest.model_validate(await request.json())
- except (ValidationError, ValueError):
- raise HTTPException(422, "Invalid key configuration")
- identity = await app.state.viking.health(value.openviking_key)
- if identity["account_id"] != account:
- raise HTTPException(403, "OpenViking key belongs to another account")
- if not await management.get(account, "policies", value.policy_id):
- raise HTTPException(400, "Unknown context policy")
- for identifier in value.upstream_ids:
- if not await management.get(account, "upstreams", identifier):
- raise HTTPException(400, "Unknown upstream")
- secret = "ovgw_" + secrets.token_urlsafe(32)
- stored = {
- **value.model_dump(),
- "user_id": identity["user_id"],
- "prefix": secret[:12],
- "created_at": time.time(),
- }
- result = await management.save(account, "keys", digest(secret), stored)
- for protocol in ("anthropic", "chat", "responses"):
- await store.allow_scope(digest(account + "\0" + identity["user_id"] + "\0" + protocol))
- await management.save(
- account, "users", identity["user_id"], {"user_id": identity["user_id"]}
- )
- return {**public_object("keys", result), "key": secret}
-
- @app.post("/admin/upstreams/{identifier}/test")
- async def test_upstream(identifier: str, request: Request):
- upstream = await management.get(admin_account(request), "upstreams", identifier)
- if not upstream:
- raise HTTPException(404)
- try:
- async with app.state.http.get(
- upstream_url(upstream, "/v1/models"),
- headers=upstream_headers(upstream, {}),
- timeout=aiohttp.ClientTimeout(total=10),
- allow_redirects=False,
- ) as response:
- return {"ok": response.status < 400, "status": response.status}
- except (aiohttp.ClientError, asyncio.TimeoutError):
- return {"ok": False, "reason": "upstream_unavailable"}
+ register_management(app)
+ @app.get("/api/compatible/v1/models")
@app.get("/api/v3/models")
@app.get("/v1/models")
async def models(request: Request):
- credential = await authenticate(request)
+ credential, _ = await authenticate(request)
values = await management.list(credential["account"], "upstreams")
names = sorted(
{
@@ -425,7 +225,7 @@ def create_app(config: OpenVikingGatewayConfig | None = None):
Response(status_code=426, headers={"Upgrade": "HTTP/1.1"})
)
- @app.post("/gateway/uploads")
+ @app.post("/uploads")
async def proxy_upload(request: Request):
token = request.query_params.get("token", "")
if not token or len(token) > 16384:
@@ -440,7 +240,7 @@ def create_app(config: OpenVikingGatewayConfig | None = None):
raise HTTPException(413, "Upload exceeds configured body limit")
try:
async with app.state.http.post(
- config.openviking_url + "/api/v1/resources/temp_upload",
+ openviking_url + "/api/v1/resources/temp_upload",
params={"token": token},
data=bytes(raw),
headers={"content-type": content_type, "accept-encoding": "identity"},
@@ -455,9 +255,35 @@ def create_app(config: OpenVikingGatewayConfig | None = None):
except (aiohttp.ClientError, asyncio.TimeoutError):
raise HTTPException(502, "OpenViking upload is unavailable")
- @app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE"])
+ @app.api_route("/v1/{path:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE"])
+ @app.api_route("/api/v3/{path:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE"])
+ @app.api_route(
+ "/api/compatible/v1/{path:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE"]
+ )
async def proxy(path: str, request: Request):
- credential = await authenticate(request)
- return await ProxyRequest(app, request, path, credential).run()
+ credential, degradation = await authenticate(request)
+ # The path below the host's mount, with its /v1, /api/v3 or /api/compatible/v1 prefix.
+ route_path = request.url.path.removeprefix(request.scope.get("root_path", ""))
+ proxied = ProxyRequest(app, request, route_path.lstrip("/"), credential)
+ if degradation:
+ proxied.metrics["degradation"] = degradation
+ return await proxied.run()
return app
+
+
+async def seed_defaults(app, account_id):
+ """Import VLM upstreams into an empty account and add the fixed "default" profile."""
+ management = app.state.management
+ if app.state.vlm_source and not await management.list(account_id, "upstreams"):
+ await import_vlm_objects(app, account_id)
+ if not await management.get(account_id, "policies", "default"):
+ await management.save(account_id, "policies", "default", Policy().model_dump())
+
+
+async def delete_data(app, account_id, user_id=None):
+ """Erase gateway state for a deleted OpenViking user, or the whole account."""
+ if user_id is None:
+ await delete_account_data(app.state.management, app.state.store, account_id)
+ else:
+ await delete_user_data(app.state.management, app.state.store, account_id, user_id)
diff --git a/openviking_gateway/capture.py b/openviking_gateway/capture.py
index e8d108f92..781b373dd 100644
--- a/openviking_gateway/capture.py
+++ b/openviking_gateway/capture.py
@@ -150,11 +150,14 @@ class CapturePipeline:
True,
0,
)
+ if value.get("error", {}).get("reason") == "gateway_key_revoked":
+ value["error"] = {}
# Reusing a prepared prompt does not generate another queue write.
value.update(
request_anchor=user_anchor,
credential_id=credential["id"],
account=credential["account"],
+ user_id=credential["user_id"],
protocol=request.protocol,
policy=policy.model_dump(),
)
@@ -213,7 +216,11 @@ class CapturePipeline:
value = request.capture.value
error = value.get("error", {})
request.metrics.update(
- capture_status=("paused" if error["attempts"] >= MAX_ATTEMPTS else "retrying")
+ capture_status=(
+ "paused"
+ if error.get("retry_at") is None or error["attempts"] >= MAX_ATTEMPTS
+ else "retrying"
+ )
if error
else ("active" if policy.capture else "disabled"),
capture_reason=error.get("reason", value.get("reason", "")),
@@ -344,6 +351,8 @@ class CaptureWorker:
"capture_status": status,
"capture_reason": reason,
},
+ # Capture states written before schema 6 carry no user.
+ user_id=state.get("user_id"),
)
async def deliver(self, item):
@@ -353,12 +362,22 @@ class CaptureWorker:
return
disabled = await self.replay.read(item["scope"], item["session"], [""])
key = await self.management.get(state["account"], "keys", state["credential_id"])
- if (K.DISABLED, "") in disabled or not key:
+ if (K.DISABLED, "") in disabled:
state["pending"] = []
state["archive"] = None
state["error"] = {}
await self.save(item, doc, state)
return
+ if not key:
+ # No retries: periodic saves would refresh touched and defeat TTL expiry.
+ # A new authenticated request supplies a key and clears this pause.
+ state["error"] = {"attempts": 0, "reason": "gateway_key_revoked", "retry_at": None}
+ if not await self.queue.swap(
+ item["scope"], item["session"], doc, state, None, owner=item["owner"]
+ ):
+ raise BranchChanged
+ await self.log(item, state, "paused", "gateway_key_revoked")
+ return
token, session = key["openviking_key"], state["ov_session"]
policy = Policy.model_validate(state["policy"])
if state.get("error"):
diff --git a/openviking_gateway/cli.py b/openviking_gateway/cli.py
index a8dee1c2f..a8cbc7530 100644
--- a/openviking_gateway/cli.py
+++ b/openviking_gateway/cli.py
@@ -1,53 +1,163 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
+"""Standalone gateway entry point; it never reads the server's ov.conf."""
+
import argparse
+import asyncio
import json
import os
-from importlib.util import find_spec
+import secrets
+import sys
from pathlib import Path
-from .config import OpenVikingGatewayConfig
+import aiohttp
+
+from .client import VikingClient, VikingError
+from .config import ENVIRONMENT_PREFIX, StandaloneGatewayConfig, normalize_url
+from .standalone import build_encryptor, check_openviking, create_standalone_app
+
+CONFIG_ENVIRONMENT = ENVIRONMENT_PREFIX + "CONFIG_FILE"
+USER_CONFIG = Path("~/.openviking/gateway.conf")
+DEFAULT_CONFIGS = (USER_CONFIG, Path("/etc/openviking/gateway.conf"))
+
+
+def config_path() -> Path | None:
+ """``--config`` (exported by ``main``), then the variable, then the first default file."""
+ if path := os.environ.get(CONFIG_ENVIRONMENT):
+ return Path(path).expanduser()
+ return next((p.expanduser() for p in DEFAULT_CONFIGS if p.expanduser().is_file()), None)
+
+
+def load_config() -> StandaloneGatewayConfig:
+ path = config_path()
+ if path and not path.is_file():
+ raise SystemExit(f"Gateway config file not found: {path}")
+ # As in ov.conf, "$VAR" references resolve from the environment.
+ raw = json.loads(os.path.expandvars(path.read_text())) if path else {}
+ if not raw.get("openviking_url") and not os.environ.get(ENVIRONMENT_PREFIX + "OPENVIKING_URL"):
+ raise SystemExit(
+ "OpenViking Gateway needs an OpenViking server URL: run `openviking-gateway init` "
+ "or set OPENVIKING_GATEWAY_OPENVIKING_URL"
+ )
+ return StandaloneGatewayConfig.model_validate(raw)
+
+def factory():
+ """uvicorn factory: every worker rebuilds the configuration from the environment."""
+ return create_standalone_app(load_config())
-def load_config():
- path = Path(os.environ.get("OPENVIKING_CONFIG_FILE", "~/.openviking/ov.conf")).expanduser()
- raw = json.loads(path.read_text()) if path.exists() else {}
- config = OpenVikingGatewayConfig.model_validate(raw.get("gateway", {}))
- if not config.enabled:
- raise ValueError("Set gateway.enabled=true in ov.conf")
- return config
+
+async def probe(url: str) -> dict:
+ async with aiohttp.ClientSession(trust_env=False) as http:
+ return await VikingClient(http, url, "0").health(require_identity=False)
+
+
+def init(path: Path) -> int:
+ """Write gateway.conf interactively; a re-run offers the current values as defaults."""
+ from openviking_cli.setup_wizard import (
+ _bold,
+ _dim,
+ _green,
+ _mask_secret,
+ _prompt_confirm,
+ _prompt_required_input,
+ _prompt_required_int,
+ _red,
+ _rule,
+ _write_config,
+ )
+
+ current = json.loads(path.read_text()) if path.is_file() else {}
+ _rule("OpenViking Gateway")
+ url = current.get("openviking_url") or "http://127.0.0.1:1933"
+ while True:
+ url = _prompt_required_input("OpenViking server URL", url)
+ if url.startswith("$"):
+ break # Resolved from the environment when the gateway starts.
+ try:
+ url = normalize_url(url)
+ except ValueError as error:
+ print(f" {_red(str(error))}")
+ if sys.stdin.isatty():
+ continue
+ return 1
+ try:
+ health = asyncio.run(probe(url))
+ except VikingError as error:
+ print(f" {_red('OpenViking check failed: ' + error.reason)}")
+ # Without a terminal every prompt returns its default; retrying would loop.
+ if _prompt_confirm("Enter a different URL?", default=sys.stdin.isatty()):
+ continue
+ else:
+ print(
+ f" {_dim('Auth mode: ' + str(health.get('auth_mode', 'unknown')))}"
+ f" {_dim('Version: ' + str(health.get('version', 'unknown')))}"
+ )
+ break
+ current["openviking_url"] = url
+ current["host"] = _prompt_required_input("Listen host", current.get("host", "127.0.0.1"))
+ current["port"] = _prompt_required_int("Listen port", current.get("port", 1935))
+
+ key = current.get("management_key", "")
+ if _prompt_confirm(
+ "Require a management key to change upstreams and profiles?", default=bool(key)
+ ):
+ if not key or not _prompt_confirm(f"Keep the current key ({_mask_secret(key)})?"):
+ key = "ovgm_" + secrets.token_urlsafe(32)
+ print(f"\n {_green('Generated management key — copy it now, it is shown once:')}")
+ print(f"\n {_bold(key)}\n")
+ current["management_key"] = key
+ else:
+ current.pop("management_key", None)
+
+ if not _write_config(current, path):
+ return 1
+ print(f"\n {_green('Saved ' + str(path))}")
+ start = "openviking-gateway" + ("" if path == USER_CONFIG.expanduser() else f" --config {path}")
+ print(f" {_dim('Start it with: ' + start)}")
+ return 0
def main():
- parser = argparse.ArgumentParser(
- description="OpenViking Gateway (separate from VikingBot Gateway)"
+ common = argparse.ArgumentParser(add_help=False)
+ common.add_argument(
+ "--config",
+ default=argparse.SUPPRESS,
+ help="gateway.conf path (default: $OPENVIKING_GATEWAY_CONFIG_FILE, "
+ "~/.openviking/gateway.conf, /etc/openviking/gateway.conf)",
)
- parser.add_argument("--config", help="Path to ov.conf")
- args = parser.parse_args()
- if args.config:
- os.environ["OPENVIKING_CONFIG_FILE"] = str(Path(args.config).resolve())
- missing = [
- name
- for name in ("aiohttp", "async_timeout", "orjson", "packaging")
- if find_spec(name) is None
- ]
- if missing:
- raise SystemExit(
- "Missing OpenViking Gateway dependencies: "
- + ", ".join(missing)
- + ". Install with: pip install 'openviking[gateway]'"
+ parser = argparse.ArgumentParser(description="OpenViking Gateway", parents=[common])
+ commands = parser.add_subparsers(dest="command")
+ commands.add_parser("init", parents=[common], help="Create or update gateway.conf")
+ # Checked before parsing: the init subcommand would otherwise swallow a removed
+ # flag's value (--port 1935) and report it as an invalid command.
+ known = ("--config", "--help")
+ if flags := [a for a in sys.argv[1:] if a[:2] == "--" and a.split("=")[0] not in known]:
+ parser.error(
+ f"unrecognized argument {flags[0]}; settings now live in gateway.conf "
+ f"(openviking-gateway init) or {ENVIRONMENT_PREFIX}<FIELD> environment variables"
)
+ args = parser.parse_args()
+ if config := getattr(args, "config", None):
+ os.environ[CONFIG_ENVIRONMENT] = str(Path(config).expanduser().resolve())
+ if args.command == "init":
+ raise SystemExit(init(Path(os.environ.get(CONFIG_ENVIRONMENT) or USER_CONFIG).expanduser()))
config = load_config()
import uvicorn
+ asyncio.run(check_openviking(config))
+ if encryptor := build_encryptor(config):
+ # Load (or create) the root key once, before workers start, so bad encryption
+ # settings stop startup and workers never race to create the key file.
+ asyncio.run(encryptor.provider.get_root_key())
uvicorn.run(
- "openviking_gateway.app:create_app",
+ "openviking_gateway.cli:factory",
factory=True,
host=config.host,
port=config.port,
workers=config.workers,
log_level="info",
- # Signed upload tokens live in query strings; use metadata-only gateway logs.
+ # Signed upload tokens live in query strings; log request metadata only.
access_log=False,
)
diff --git a/openviking_gateway/client.py b/openviking_gateway/client.py
index 640d32b40..76839e20e 100644
--- a/openviking_gateway/client.py
+++ b/openviking_gateway/client.py
@@ -3,6 +3,7 @@
"""OpenViking HTTP adapter. No imports from the server/service implementation."""
import asyncio
+import hashlib
from urllib.parse import urlencode
import aiohttp
@@ -21,6 +22,7 @@ class VikingClient:
def __init__(self, http: aiohttp.ClientSession, base_url: str, min_version: str):
self.http, self.base_url, self.min_version = http, base_url.rstrip("/"), min_version
self.unavailable_reason = ""
+ self.identities = TTLCache(ttl=30, capacity=4096)
# Every caller sees the same MCP tools; the last good list outlives failures.
self.tools_cache, self.last_tools = TTLCache(ttl=300, capacity=1), None
@@ -43,18 +45,44 @@ class VikingClient:
except (aiohttp.ClientError, asyncio.TimeoutError, ValueError) as error:
raise VikingError("openviking_unavailable") from error
+ async def identify(self, credential=""):
+ """Identify a caller; only successful identities are cached, for 30 seconds."""
+
+ async def load():
+ result = await self.request("GET", "/health", credential, timeout=5)
+ if result.get("auth_mode") == "trusted":
+ raise VikingError("trusted_mode_unsupported", 403)
+ if result.get("auth_mode") == "dev":
+ result = {**result, "role": "root", "account_id": "default", "user_id": "default"}
+ if result.get("role", "").lower() not in {"root", "admin", "user"} or not all(
+ result.get(field) for field in ("account_id", "user_id")
+ ):
+ raise VikingError("openviking_identity_missing", 401)
+ # OV answered, so recall and revocation checks may resume before the next probe.
+ self.unavailable_reason = ""
+ return {**result, "role": result["role"].lower()}
+
+ return await self.identities.get(hashlib.sha256(credential.encode()).hexdigest(), load)
+
async def health(self, key="", require_identity=True):
- result = await self.request("GET", "/health", key, timeout=5)
- try:
- if Version(result.get("version", "0")) < Version(self.min_version):
- raise VikingError("openviking_version_mismatch")
- except InvalidVersion as error:
- raise VikingError("openviking_version_mismatch") from error
if require_identity:
- if result.get("role", "").lower() == "root":
+ result = await self.identify(key)
+ if result["role"] == "root" and result.get("auth_mode") != "dev":
raise VikingError("root_key_not_allowed", 403)
- if not result.get("user_id") or not result.get("account_id"):
- raise VikingError("openviking_identity_missing", 401)
+ try:
+ if Version(result.get("version", "0")) < Version(self.min_version):
+ raise VikingError("openviking_version_mismatch")
+ except InvalidVersion as error:
+ raise VikingError("openviking_version_mismatch") from error
+ return result
+ try:
+ result = await self.request("GET", "/health", key, timeout=5)
+ except VikingError as error:
+ if error.status == 401 and not key:
+ return {"status": "ok", "auth_mode": "api_key", "requires_authentication": True}
+ raise
+ if result.get("auth_mode") == "trusted":
+ raise VikingError("trusted_mode_unsupported", 403)
return result
async def recall(self, key, query, policy, exclude, budget):
diff --git a/openviking_gateway/config.py b/openviking_gateway/config.py
index dbc0efca4..8444b2dcc 100644
--- a/openviking_gateway/config.py
+++ b/openviking_gateway/config.py
@@ -1,27 +1,47 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
-"""Configuration shared by the standalone gateway and the server admin proxy."""
+"""Configuration for embedded and standalone gateway hosts."""
+import logging
import os
from pathlib import Path
-from urllib.parse import urlsplit
+from typing import ClassVar
+from urllib.parse import urlsplit, urlunsplit
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+logger = logging.getLogger(__name__)
-class OpenVikingGatewayConfig(BaseModel):
+ENVIRONMENT_PREFIX = "OPENVIKING_GATEWAY_"
+PUBLIC_OPENVIKING_URLS = frozenset({"https://api.vikingdb.cn-beijing.volces.com/openviking"})
+# Both hosts mount the gateway here; public_url is the origin in front of it.
+MOUNT_PATH = "/gateway"
+
+
+def normalize_url(value: str) -> str:
+ parsed = urlsplit(value)
+ if (
+ parsed.scheme not in {"http", "https"}
+ or not parsed.hostname
+ or parsed.username
+ or parsed.password
+ or parsed.query
+ or parsed.fragment
+ # Reading the port also rejects malformed ones.
+ or parsed.port == 0
+ ):
+ raise ValueError("expected an HTTP(S) URL without credentials, query or fragment")
+ return urlunsplit((parsed.scheme, parsed.netloc.lower(), parsed.path.rstrip("/"), "", ""))
+
+
+class GatewayConfig(BaseModel):
model_config = ConfigDict(extra="forbid")
+ # Settings an upgraded configuration may still carry; rejecting them would stop the host.
+ removed_fields: ClassVar[frozenset[str]] = frozenset({"encryption_key_env"})
- enabled: bool = False
- host: str = "127.0.0.1"
- port: int = Field(default=1935, ge=1, le=65535)
- workers: int = Field(default=1, ge=1, le=64)
- url: str = "http://127.0.0.1:1935"
- openviking_url: str = "http://127.0.0.1:1933"
public_url: str = ""
storage_path: str = "~/.openviking/gateway"
- encryption_key_env: str = "OPENVIKING_GATEWAY_ENCRYPTION_KEY"
- admin_token_env: str = "OPENVIKING_GATEWAY_ADMIN_TOKEN"
+ management_key: str = Field(default="", repr=False)
min_server_version: str = "0.4.16"
session_ttl_days: int = Field(default=30, ge=1)
response_ttl_seconds: int = Field(default=30 * 86400, ge=60)
@@ -30,32 +50,75 @@ class OpenVikingGatewayConfig(BaseModel):
upstream_timeout_seconds: float = Field(default=600, gt=0)
health_interval_seconds: float = Field(default=60, ge=1)
- @field_validator("url", "openviking_url", "public_url")
+ @model_validator(mode="before")
@classmethod
- def validate_url(cls, value: str) -> str:
- if not value:
+ def apply_environment(cls, value):
+ if not isinstance(value, dict):
return value
- parsed = urlsplit(value)
- if (
- parsed.scheme not in {"http", "https"}
- or not parsed.hostname
- or parsed.username
- or parsed.password
- or parsed.query
- or parsed.fragment
- ):
- raise ValueError("expected an HTTP(S) URL without credentials, query or fragment")
- return value.rstrip("/")
-
- def secrets(self) -> tuple[str, str]:
- key = os.environ.get(self.encryption_key_env, "")
- token = os.environ.get(self.admin_token_env, "")
- if not key or len(token) < 32:
- raise ValueError(
- "configure a Fernet encryption key and an admin token of at least 32 characters"
+ if found := cls.removed_fields.intersection(value):
+ logger.warning(
+ "Ignoring removed gateway settings %s. "
+ "See docs/en/guides/22-gateway-operations.md#migration",
+ ", ".join(sorted(found)),
)
- return key, token
+ value = {key: item for key, item in value.items() if key not in found}
+ for field in cls.model_fields:
+ # An empty variable, such as a compose default, never overrides the file.
+ override = os.environ.get(ENVIRONMENT_PREFIX + field.upper(), "")
+ # Kubernetes service links set OPENVIKING_GATEWAY_PORT=tcp://... for such a Service.
+ if override and not override.startswith(("tcp://", "udp://")):
+ value[field] = override
+ return value
+
+ @field_validator("public_url")
+ @classmethod
+ def validate_url(cls, value: str) -> str:
+ return normalize_url(value) if value else ""
+
+ @field_validator("management_key")
+ @classmethod
+ def validate_management_key(cls, value: str) -> str:
+ value = os.path.expandvars(value)
+ if value and (len(value) < 32 or value.startswith("$")):
+ raise ValueError("management_key must resolve to at least 32 characters")
+ return value
@property
def directory(self) -> Path:
return Path(self.storage_path).expanduser()
+
+
+class EmbeddedGatewayConfig(GatewayConfig):
+ # v0.5.0 sidecar settings: the gateway now runs inside the server on the server port.
+ removed_fields = GatewayConfig.removed_fields | {
+ "host",
+ "port",
+ "workers",
+ "url",
+ "openviking_url",
+ "admin_token_env",
+ }
+
+ enabled: bool = False
+
+
+class StandaloneGatewayConfig(GatewayConfig):
+ openviking_url: str = Field(min_length=1)
+ host: str = "127.0.0.1"
+ port: int = Field(default=1935, ge=1, le=65535)
+ workers: int = Field(default=1, ge=1, le=64)
+ # Same schema as ov.conf's top-level "encryption"; absent or disabled stores plaintext.
+ encryption: dict | None = Field(default=None, repr=False)
+
+ @field_validator("openviking_url")
+ @classmethod
+ def validate_openviking_url(cls, value: str) -> str:
+ return normalize_url(value)
+
+ @field_validator("encryption")
+ @classmethod
+ def validate_encryption(cls, value: dict | None) -> dict | None:
+ # Imported here because the server's config package imports this module.
+ from openviking_cli.utils.config.encryption_config import EncryptionConfig
+
+ return None if value is None else EncryptionConfig.model_validate(value).model_dump()
diff --git a/openviking_gateway/management.py b/openviking_gateway/management.py
new file mode 100644
index 000000000..691337ecb
--- /dev/null
+++ b/openviking_gateway/management.py
@@ -0,0 +1,542 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Gateway management: OV identity and independent object-write authorization."""
+
+import asyncio
+import copy
+import hmac
+import secrets
+import time
+from dataclasses import dataclass
+from urllib.parse import quote
+
+import aiohttp
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import ValidationError
+
+from .capture import reset_capture
+from .client import VikingError
+from .config import MOUNT_PATH
+from .models import CaptureReset, KeyRequest, Policy, Upstream
+from .proxy import upstream_headers, upstream_url
+from .records import RecordKind as K
+from .storage import delete_account_data, delete_user_data, digest
+
+PREFIX = "/admin"
+MANAGEMENT_HEADER = "x-openviking-gateway-management-key"
+# Fields a VLM re-import refreshes; everything else may have been edited in the gateway.
+VLM_SOURCE_FIELDS = ("base_url", "api_key", "headers", "protocol", "vendor", "coding_plan")
+DETAILS = {
+ "management_key_invalid": "The gateway management key is incorrect.",
+ "management_key_required": "Changing upstreams and profiles requires the management key.",
+ "other_account": "This OpenViking API key cannot access the selected account.",
+ "forbidden": "This OpenViking role cannot perform the operation.",
+ "not_found": "The object does not exist.",
+ "in_use": "Gateway keys still use this object; revoke them first.",
+ "invalid_configuration": "The request body is invalid.",
+ "unknown_user": "The user does not exist in this account.",
+ "user_required": "OpenViking root is not an account user; choose the user to issue for.",
+ "user_key_unreadable": "OpenViking stores only a hash of this user's API key; paste the key.",
+ "unknown_policy": "The context profile does not exist.",
+ "unknown_upstream": "An upstream does not exist.",
+ "vlm_import_unavailable": "This gateway cannot read OpenViking model settings.",
+ "vlm_import_forbidden": "Importing OpenViking model settings requires the management key "
+ "or, without one, OpenViking root.",
+}
+
+
+def fail(status, reason, detail=None, **extra):
+ raise HTTPException(status, {"reason": reason, "detail": detail or DETAILS[reason], **extra})
+
+
+async def read_body(request, model, prepare=None):
+ """Validate a JSON body; error details never echo submitted values."""
+ try:
+ payload = await request.json()
+ return model.model_validate(prepare(payload) if prepare else payload)
+ except ValidationError as error:
+ fail(
+ 422,
+ "invalid_configuration",
+ "; ".join(
+ item["msg"] for item in error.errors(include_input=False, include_context=False)
+ ),
+ )
+ except ValueError:
+ fail(422, "invalid_configuration")
+
+
+def request_credential(request):
+ return request.headers.get("x-api-key") or request.headers.get(
+ "authorization", ""
+ ).removeprefix("Bearer ")
+
+
+@dataclass
+class Caller:
+ account_id: str
+ credential: str
+ identity: dict | None
+ manager: bool
+ can_write: bool
+
+ @property
+ def role(self):
+ return self.identity.get("role") if self.identity else None
+
+ @property
+ def user_id(self):
+ return self.identity.get("user_id") if self.identity else None
+
+ @property
+ def log_user(self):
+ return self.user_id if self.role == "user" else None
+
+
+async def caller(request, *, require_identity=True, write=False):
+ state = request.app.state
+ configured = state.config.management_key
+ supplied = request.headers.get(MANAGEMENT_HEADER)
+ manager = bool(
+ configured and supplied and hmac.compare_digest(supplied.encode(), configured.encode())
+ )
+ if supplied is not None and not manager:
+ fail(401, "management_key_invalid")
+ credential = request_credential(request)
+ identity = None
+ if credential or require_identity or not manager:
+ try:
+ identity = await state.viking.identify(credential)
+ except VikingError as error:
+ if error.reason == "openviking_unavailable":
+ raise VikingError("openviking_unreachable", 503) from error
+ raise
+ account = request.query_params.get("account_id") or (identity or {}).get(
+ "account_id", "default"
+ )
+ # A management key may select any account for objects only. It cannot elevate OV operations.
+ if identity and account != identity["account_id"] and identity["role"] != "root":
+ if require_identity or not manager:
+ fail(403, "other_account")
+ can_write = manager or not configured
+ if write and not can_write:
+ fail(403, "management_key_required")
+ return Caller(account, credential, identity, manager, can_write)
+
+
+async def import_vlm_objects(app, account_id):
+ """Save the host's VLM candidates as upstreams; a re-import keeps gateway-side edits."""
+ management = app.state.management
+ result = await app.state.vlm_source(account_id)
+ imported, confirmation, skipped = [], [], list(result.get("skipped", []))
+ for candidate in result.get("upstreams", []):
+ payload = dict(candidate)
+ identifier = payload.pop("id")
+ if previous := await management.get(account_id, "upstreams", identifier):
+ kept = {k: v for k, v in previous.items() if k not in {"id", "revision"}}
+ payload = {**kept, **{k: payload[k] for k in VLM_SOURCE_FIELDS if k in payload}}
+ try:
+ value = Upstream.model_validate(payload).model_dump()
+ except ValueError:
+ # Validation errors can include secrets from the input; never expose them.
+ skipped.append({"id": identifier, "reason": "invalid_configuration"})
+ continue
+ await management.save(account_id, "upstreams", identifier, value)
+ row = {"id": identifier, "name": value["name"]}
+ (
+ confirmation if value["coding_plan"] and not value["allow_coding_plan"] else imported
+ ).append(row)
+ return {"imported": imported, "needs_confirmation": confirmation, "skipped": skipped}
+
+
+def can_import(app, who):
+ return bool(
+ app.state.vlm_source
+ and (who.manager if app.state.config.management_key else who.role == "root")
+ )
+
+
+def register_management(app):
+ router = APIRouter(prefix=PREFIX, tags=["gateway"])
+ management, store = app.state.management, app.state.store
+
+ @router.get("/access")
+ async def access(request: Request):
+ who = await caller(request, require_identity=False)
+ return {
+ "managed": bool(app.state.config.management_key),
+ "can_write_objects": who.can_write,
+ "can_import_vlm": can_import(app, who),
+ "can_issue_for_others": who.role in {"root", "admin"}
+ and (who.identity or {}).get("auth_mode") != "dev",
+ "role": who.role,
+ "account_id": who.account_id,
+ "user_id": who.user_id,
+ "warnings": app.state.warnings,
+ }
+
+ @router.get("/overview")
+ async def overview(request: Request):
+ who = await caller(request)
+ logs = await management.logs(who.account_id, 10000, user_id=who.log_user)
+ return {
+ **overview_summary(logs),
+ "openviking": app.state.health,
+ "log_retention_days": app.state.config.log_retention_days,
+ }
+
+ @router.get("/logs")
+ async def logs(request: Request, limit: int = 200):
+ who = await caller(request)
+ return await management.logs(who.account_id, max(1, min(limit, 1000)), user_id=who.log_user)
+
+ @router.get("/guides")
+ async def guides(request: Request):
+ await caller(request)
+ return {
+ "base_url": (
+ app.state.config.public_url or f"{request.url.scheme}://{request.url.netloc}"
+ )
+ + MOUNT_PATH,
+ "public_url_configured": bool(app.state.config.public_url),
+ }
+
+ @router.get("/tools")
+ async def tools(request: Request):
+ who = await caller(request)
+ key = who.credential
+ if who.role == "root" and who.identity.get("auth_mode") != "dev":
+ # OV refuses root on /mcp. Every caller sees the same catalog, so read it with
+ # a key issued in this account, or fall back to the last catalog read.
+ keys = await management.list(who.account_id, "keys")
+ key = next((k["openviking_key"] for k in keys), "")
+ catalog = await app.state.viking.tools(key) if key else app.state.viking.last_tools or []
+ return [
+ {
+ "name": t["name"],
+ "description": t.get("description", ""),
+ **({"annotations": t["annotations"]} if "annotations" in t else {}),
+ }
+ for t in catalog
+ ]
+
+ @router.delete("/users/{user_id}/data")
+ async def delete_user(user_id: str, request: Request):
+ who = await caller(request)
+ if who.role not in {"root", "admin"}:
+ fail(403, "forbidden")
+ await delete_user_data(management, store, who.account_id, user_id)
+ return {"deleted": True}
+
+ @router.delete("/account/data")
+ async def delete_account(request: Request):
+ who = await caller(request)
+ if who.role != "root":
+ fail(403, "forbidden")
+ await delete_account_data(management, store, who.account_id)
+ return {"deleted": True}
+
+ @router.post("/upstreams/import-vlm")
+ async def import_vlm(request: Request):
+ who = await caller(request, require_identity=False)
+ if app.state.vlm_source is None:
+ fail(404, "vlm_import_unavailable")
+ if not can_import(app, who):
+ fail(403, "vlm_import_forbidden")
+ return await import_vlm_objects(app, who.account_id)
+
+ def object_routes(kind, model):
+ @router.get(f"/{kind}")
+ async def list_objects(request: Request):
+ who = await caller(request, require_identity=False)
+ values = await management.list(who.account_id, kind)
+ return [public_object(kind, value, read_only=not who.can_write) for value in values]
+
+ @router.get(f"/{kind}/{{identifier}}")
+ async def get_object(identifier: str, request: Request):
+ who = await caller(request, require_identity=False)
+ value = await management.get(who.account_id, kind, identifier)
+ if not value:
+ fail(404, "not_found")
+ return public_object(kind, value, read_only=not who.can_write)
+
+ @router.put(f"/{kind}/{{identifier}}")
+ async def save_object(identifier: str, request: Request):
+ who = await caller(request, require_identity=False, write=True)
+ if kind == "upstreams":
+ previous = await management.get(who.account_id, kind, identifier) or {}
+ value = await read_body(
+ request, model, lambda payload: keep_upstream_secrets(payload, previous)
+ )
+ else:
+ value = await read_body(request, model)
+ saved = await management.save(who.account_id, kind, identifier, value.model_dump())
+ return public_object(kind, saved)
+
+ @router.delete(f"/{kind}/{{identifier}}")
+ async def delete_object(identifier: str, request: Request):
+ who = await caller(request, require_identity=False, write=True)
+ count = sum(
+ key["policy_id"] == identifier
+ if kind == "policies"
+ else identifier in key["upstream_ids"]
+ for key in await management.list(who.account_id, "keys")
+ )
+ if count:
+ fail(409, "in_use", key_count=count)
+ await management.delete(who.account_id, kind, identifier)
+ return {"deleted": True}
+
+ object_routes("upstreams", Upstream)
+ object_routes("policies", Policy)
+
+ def hidden(who, key):
+ """A user sees only the keys issued for that user."""
+ return who.role == "user" and key["user_id"] != who.user_id
+
+ @router.get("/keys")
+ async def list_keys(request: Request):
+ who = await caller(request)
+ values = await management.list(who.account_id, "keys", user_id=who.log_user)
+ return [public_object("keys", value) for value in values]
+
+ @router.get("/keys/{identifier}")
+ async def get_key(identifier: str, request: Request):
+ who = await caller(request)
+ value = await management.get(who.account_id, "keys", identifier)
+ if not value or hidden(who, value):
+ fail(404, "not_found")
+ return public_object("keys", value)
+
+ # Keys are immutable: no PUT route, so a replacement must be issued.
+ @router.delete("/keys/{identifier}")
+ async def revoke_key(identifier: str, request: Request):
+ who = await caller(request)
+ value = await management.get(who.account_id, "keys", identifier)
+ if value and hidden(who, value):
+ fail(404, "not_found")
+ await management.delete(who.account_id, "keys", identifier)
+ return {"deleted": True}
+
+ @router.post("/keys")
+ async def issue_key(request: Request):
+ who = await caller(request)
+ value = await read_body(request, KeyRequest)
+ root = who.role == "root" and who.identity.get("auth_mode") != "dev"
+ if root and not value.user_id and not value.openviking_key:
+ fail(400, "user_required")
+ user_id = value.user_id or who.user_id
+ if who.role == "user" and user_id != who.user_id:
+ fail(403, "forbidden")
+ key = value.openviking_key
+ if not key:
+ if user_id == who.user_id and who.identity["account_id"] == who.account_id and not root:
+ key = who.credential
+ else:
+ # name matches by pattern; the exact user_id comparison below picks the row.
+ rows = await app.state.viking.request(
+ "GET",
+ f"/api/v1/admin/accounts/{quote(who.account_id, safe='')}/users"
+ f"?include_credentials=true&name={quote(user_id, safe='')}",
+ who.credential,
+ )
+ if isinstance(rows, dict):
+ rows = rows.get("users", [])
+ selected = next(
+ (
+ r
+ for r in rows
+ if r["user_id"] == user_id and r.get("role") in {"admin", "user"}
+ ),
+ None,
+ )
+ if not selected:
+ fail(400, "unknown_user")
+ key = selected.get("api_key")
+ if not key:
+ fail(409, "user_key_unreadable")
+ identity = await app.state.viking.health(key)
+ if identity["account_id"] != who.account_id:
+ fail(403, "other_account")
+ if (value.user_id or who.role == "user") and identity["user_id"] != user_id:
+ fail(403, "forbidden")
+ if not await management.get(who.account_id, "policies", value.policy_id):
+ fail(400, "unknown_policy")
+ for identifier in value.upstream_ids:
+ if not await management.get(who.account_id, "upstreams", identifier):
+ fail(400, "unknown_upstream")
+ secret = "ovgw_" + secrets.token_urlsafe(32)
+ stored = {
+ **value.model_dump(),
+ "openviking_key": key,
+ "user_id": identity["user_id"],
+ "prefix": secret[:12],
+ "created_at": time.time(),
+ }
+ result = await management.save(who.account_id, "keys", digest(secret), stored)
+ for protocol in ("anthropic", "chat", "responses"):
+ await store.allow_scope(
+ digest(who.account_id + "\0" + identity["user_id"] + "\0" + protocol)
+ )
+ await management.save(
+ who.account_id, "users", identity["user_id"], {"user_id": identity["user_id"]}
+ )
+ return {**public_object("keys", result), "key": secret}
+
+ @router.post("/keys/{identifier}/capture/reset")
+ async def reset(identifier: str, data: CaptureReset, request: Request):
+ who = await caller(request)
+ key = await management.get(who.account_id, "keys", identifier)
+ if not key or hidden(who, key):
+ fail(404, "not_found")
+ scope = digest(who.account_id + "\0" + key["user_id"] + "\0" + data.protocol)
+ for session in (digest(data.session), data.session):
+ if (K.ROOT, "") in await store.replay.read(scope, session, [""]):
+ break
+ else:
+ fail(404, "not_found")
+ await reset_capture(store.capture, scope, session, "manual_reset")
+ return {"status": "ready", "message": "Capture will resync from the next request history"}
+
+ @router.post("/upstreams/{identifier}/test")
+ async def test_upstream(identifier: str, request: Request):
+ who = await caller(request, require_identity=False)
+ upstream = await management.get(who.account_id, "upstreams", identifier)
+ if not upstream:
+ fail(404, "not_found")
+ url = upstream_url(upstream, "/v1/models")
+ try:
+ headers = upstream_headers(upstream, {})
+ except HTTPException as error:
+ if error.status_code != 401:
+ raise
+ # No stored key (passthrough keys come from clients): nothing is sent.
+ return {"ok": False, "reason": "upstream_key_missing", "url": url}
+ try:
+ async with app.state.http.get(
+ url,
+ headers=headers,
+ timeout=aiohttp.ClientTimeout(total=10),
+ allow_redirects=False,
+ ) as response:
+ status = response.status
+ if status in {404, 405}:
+ reason, ok = "models_unavailable", True
+ elif status == 429:
+ reason, ok = "rate_limited", True
+ elif 200 <= status < 300:
+ try:
+ body = await response.json(content_type=None)
+ except ValueError:
+ body = {}
+ ok = (
+ isinstance(body, dict)
+ and isinstance(body.get("data"), list)
+ and not body.get("error")
+ )
+ reason = "passed" if ok else "upstream_key_rejected"
+ else:
+ reason, ok = (
+ (
+ "upstream_key_rejected"
+ if status in {401, 403}
+ else "upstream_unavailable"
+ ),
+ False,
+ )
+ return {"ok": ok, "status": status, "reason": reason, "url": url}
+ except (aiohttp.ClientError, asyncio.TimeoutError):
+ return {"ok": False, "reason": "upstream_unavailable", "url": url}
+
+ app.include_router(router)
+
+
+def public_object(kind, value, *, read_only=False):
+ value = copy.deepcopy(value)
+ if kind == "upstreams":
+ value["has_api_key"] = bool(value.pop("api_key", ""))
+ headers = value.pop("headers", {})
+ if not read_only:
+ value["header_names"] = list(headers)
+ if kind == "keys":
+ value.pop("openviking_key", None)
+ return value
+
+
+def keep_upstream_secrets(payload, previous):
+ """Preserve omitted secrets only while the destination remains unchanged.
+
+ A blank ``api_key`` keeps the stored key. ``headers`` omitted keeps every stored header;
+ otherwise the submitted names are the new header set, and a blank value keeps the stored
+ value for that name (or drops the name when nothing is stored).
+ """
+ if not isinstance(payload, dict):
+ raise ValueError("expected an upstream object")
+ same_base = str(payload.get("base_url") or "").rstrip("/") == previous.get(
+ "base_url", ""
+ ).rstrip("/")
+ if not payload.get("api_key"):
+ payload["api_key"] = previous.get("api_key", "") if same_base else ""
+ stored = previous.get("headers", {}) if same_base else {}
+ headers = payload.get("headers")
+ if headers is None:
+ payload["headers"] = stored
+ elif isinstance(headers, dict):
+ payload["headers"] = {
+ name: value or stored[name]
+ for name, value in headers.items()
+ if value or name in stored
+ }
+ return payload
+
+
+def overview_summary(logs):
+ """Aggregate newest-first request-log records into the management overview."""
+ requests = [log for log in logs if log.get("kind") != "capture"]
+ groups = {}
+ for label, kinds in (("first_call", {"user"}), ("continuation", {"continuation"})):
+ subset = [log for log in requests if log.get("kind") in kinds]
+ total = sum(
+ log.get("first_upstream_input_tokens", log.get("input_tokens", 0)) for log in subset
+ )
+ cached = sum(
+ log.get("first_upstream_cached_tokens", log.get("cached_tokens", 0)) for log in subset
+ )
+ hidden_calls = 0
+ if label == "continuation":
+ total += sum(log.get("hidden_upstream_input_tokens", 0) for log in requests)
+ cached += sum(log.get("hidden_upstream_cached_tokens", 0) for log in requests)
+ hidden_calls = sum(log.get("hidden_upstream_calls", 0) for log in requests)
+ groups[label] = {
+ "requests": len(subset) + hidden_calls,
+ "input_tokens": total,
+ "cached_tokens": cached,
+ "cache_hit_ratio": cached / total if total else 0,
+ }
+ degradations = {}
+ for log in logs:
+ if reason := log.get("degradation"):
+ degradations[reason] = degradations.get(reason, 0) + 1
+ # "disabled" means recall was skipped (off, budget spent or query too short).
+ recalls = [log for log in requests if log.get("recall_reason", "disabled") != "disabled"]
+ capture = {}
+ for log in logs:
+ if log.get("session") and log.get("capture_status"):
+ capture.setdefault((log["session"], log.get("protocol")), log["capture_status"])
+ return {
+ "requests": len(requests),
+ "last_request_at": requests[0].get("time") if requests else None,
+ "output_tokens": sum(log.get("output_tokens", 0) for log in requests),
+ "cache": groups,
+ "degradations": degradations,
+ "recall_count": sum(log.get("recall_count", 0) for log in requests),
+ "recall_requests": len(recalls),
+ "recall_ms": sum(log.get("recall_ms", 0) for log in recalls) / len(recalls)
+ if recalls
+ else 0,
+ "capture_issues": {
+ status: sum(1 for value in capture.values() if value == status)
+ for status in ("retrying", "paused")
+ },
+ "sample_limit": 10000,
+ }
diff --git a/openviking_gateway/models.py b/openviking_gateway/models.py
index 3dd745c6a..9abb42c47 100644
--- a/openviking_gateway/models.py
+++ b/openviking_gateway/models.py
@@ -129,6 +129,14 @@ class Upstream(BaseModel):
)
return value.rstrip("/")
+ @model_validator(mode="after")
+ def validate_protocol_base(self):
+ if self.protocol == "anthropic" and urlsplit(self.base_url).path.endswith("/v1"):
+ raise ValueError(
+ "Anthropic base_url must not end in /v1; the gateway appends /v1/messages"
+ )
+ return self
+
@field_validator("headers")
@classmethod
def validate_headers(cls, value: dict[str, str]) -> dict[str, str]:
@@ -145,7 +153,8 @@ class Upstream(BaseModel):
class KeyRequest(BaseModel):
model_config = ConfigDict(extra="forbid")
name: str
- openviking_key: str
+ openviking_key: str = ""
+ user_id: str | None = None
policy_id: str
upstream_ids: list[str] = Field(min_length=1)
models: list[str] = Field(default_factory=list)
diff --git a/openviking_gateway/proxy.py b/openviking_gateway/proxy.py
index a9a2536cc..2a110ac9f 100644
--- a/openviking_gateway/proxy.py
+++ b/openviking_gateway/proxy.py
@@ -7,7 +7,6 @@ import json
import logging
import time
import uuid
-from urllib.parse import urlsplit
import aiohttp
import orjson
@@ -21,7 +20,7 @@ from .tool_executor import ToolExecutor
from .tool_loop import HiddenToolLoop, ToolLoopError
from .tool_protocols import ResponseCapture, tool_protocol
from .tool_protocols.common import SummaryError
-from .vendors import ARK_PATHS, ARK_VENDORS, apply_vendor, ark_url
+from .vendors import ARK_VENDORS, apply_vendor
logger = logging.getLogger(__name__)
HOP_HEADERS = {
@@ -63,18 +62,20 @@ def filtered_headers(headers, request=False):
def upstream_url(upstream, path):
- if upstream.get("vendor") in ARK_VENDORS:
- return ark_url(upstream, path)
base = upstream["base_url"].rstrip("/")
- # Accept both https://host and https://host/v1 as a configured base URL.
- if urlsplit(base).path.endswith("/v1") and path.startswith("/v1/"):
- path = path[3:]
+ if upstream["protocol"] != "anthropic":
+ path = path.removeprefix("/v1")
return base + path
def upstream_headers(upstream, incoming):
headers = filtered_headers(incoming, request=True)
headers.update(upstream.get("headers", {}))
+ # Drop configured copies of the auth headers set below; other protocols keep x-api-key.
+ own = (
+ {"authorization", "x-api-key"} if upstream["protocol"] == "anthropic" else {"authorization"}
+ )
+ headers = {k: v for k, v in headers.items() if k.lower() not in own}
key = (
upstream.get("api_key", "")
if upstream.get("auth_mode") != "passthrough"
@@ -86,7 +87,10 @@ def upstream_headers(upstream, incoming):
)
if not key:
raise HTTPException(401, "Upstream API key is missing")
- headers.update(tool_protocol(upstream["protocol"]).auth_header(key))
+ # Anthropic-compatible services accept either header; some require Bearer.
+ headers["Authorization"] = "Bearer " + key
+ if upstream["protocol"] == "anthropic":
+ headers["x-api-key"] = key
headers["accept-encoding"] = "identity"
return headers
@@ -118,9 +122,10 @@ class ProxyRequest:
app.state.management,
)
self.path = "/" + path
- if self.path.startswith("/api/v3/responses/"):
- self.path = "/v1/responses/" + self.path.removeprefix("/api/v3/responses/")
- self.path = ARK_PATHS.get(self.path, self.path)
+ for prefix in ("/api/v3/", "/api/compatible/v1/"):
+ if self.path.startswith(prefix):
+ self.path = "/v1/" + self.path.removeprefix(prefix)
+ break
self.protocol = PATH_PROTOCOL.get(self.path)
self.prepared = None
self.metrics = {"request_id": uuid.uuid4().hex, "kind": "passthrough"}
@@ -128,8 +133,6 @@ class ProxyRequest:
async def run(self):
if self.request.headers.get("upgrade", "").lower() == "websocket":
return Response(status_code=426, headers={"Upgrade": "HTTP/1.1"})
- if self.path.startswith("/admin") or self.path == "/health":
- raise HTTPException(404)
raw = bytearray()
async for chunk in self.request.stream():
raw.extend(chunk)
@@ -319,10 +322,12 @@ class ProxyRequest:
self.credential["account"],
"responses",
digest(self.credential["id"] + self.capture.response_id),
- {"upstream_id": self.upstream["id"]},
+ {"upstream_id": self.upstream["id"], "user_id": self.credential["user_id"]},
ttl=self.config.response_ttl_seconds,
)
- await self.management.log(self.credential["account"], self.metrics)
+ await self.management.log(
+ self.credential["account"], self.metrics, user_id=self.credential["user_id"]
+ )
except Exception:
logger.exception("OpenViking Gateway response bookkeeping failed")
diff --git a/openviking_gateway/standalone.py b/openviking_gateway/standalone.py
new file mode 100644
index 000000000..d1b3f0964
--- /dev/null
+++ b/openviking_gateway/standalone.py
@@ -0,0 +1,157 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Standalone host: startup checks, Studio, read-only OV administration and /health."""
+
+import asyncio
+import logging
+import os
+from concurrent.futures import ThreadPoolExecutor
+from importlib.util import find_spec
+from pathlib import Path
+from urllib.parse import quote, urlencode
+
+import aiohttp
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import FileResponse, RedirectResponse
+
+from .app import create_app
+from .client import VikingClient, VikingError
+from .config import MOUNT_PATH, StandaloneGatewayConfig
+from .management import request_credential
+
+logger = logging.getLogger(__name__)
+LOOPBACK_HOSTS = {"127.0.0.1", "::1", "localhost"}
+WARNINGS = {
+ "public_openviking_without_management_key": "This gateway is open to every OpenViking "
+ "Cloud user. Set OPENVIKING_GATEWAY_MANAGEMENT_KEY to restrict changes to upstreams and "
+ "profiles.",
+}
+
+
+async def check_openviking(config: StandaloneGatewayConfig) -> dict:
+ """Probe OV once before serving; refuse trusted auth and unconfirmed public binds."""
+ async with aiohttp.ClientSession(trust_env=False) as http:
+ viking = VikingClient(http, config.openviking_url, config.min_server_version)
+ try:
+ health = await viking.health(require_identity=False)
+ except VikingError as error:
+ health = {"status": "degraded", "reason": error.reason}
+ if health.get("reason") == "trusted_mode_unsupported":
+ raise ValueError("OpenViking Gateway does not support trusted authentication")
+ if config.host not in LOOPBACK_HOSTS and health.get("auth_mode") != "api_key":
+ raise ValueError(
+ "A publicly bound OpenViking Gateway requires a successful synchronous "
+ "probe confirming API-key authentication; use a loopback host until "
+ "OpenViking is reachable and its authentication mode is known"
+ )
+ return health
+
+
+def studio_directory() -> Path | None:
+ if path := os.environ.get("OPENVIKING_WEB_STUDIO_DIR"):
+ return Path(path).expanduser()
+ spec = find_spec("openviking")
+ if spec and spec.submodule_search_locations:
+ path = Path(next(iter(spec.submodule_search_locations))) / "web_studio" / "dist"
+ if path.is_dir():
+ return path
+ return None
+
+
+def build_encryptor(config: StandaloneGatewayConfig):
+ """OpenViking's encryptor for the optional ``encryption`` block; None stores plaintext."""
+ if not (config.encryption or {}).get("enabled"):
+ return None
+ from openviking.crypto.config import bootstrap_encryption
+
+ # uvicorn builds the app inside its running loop, so bootstrap on a separate thread.
+ with ThreadPoolExecutor(max_workers=1) as pool:
+ return pool.submit(
+ asyncio.run, bootstrap_encryption({"encryption": config.encryption})
+ ).result()
+
+
+def create_standalone_app(config: StandaloneGatewayConfig, studio_dir=None):
+ """Mount the gateway at ``MOUNT_PATH``; Studio, /health and the OV proxy stay at the root."""
+ gateway = create_app(
+ config, openviking_url=config.openviking_url, encryptor=build_encryptor(config)
+ )
+ for warning in gateway.state.warnings:
+ logger.warning("%s: %s", warning, WARNINGS[warning])
+ # A mounted app's lifespan does not run on its own; its error shapes apply here too.
+ app = FastAPI(
+ lifespan=lambda _app: gateway.router.lifespan_context(gateway),
+ exception_handlers=gateway.exception_handlers,
+ docs_url=None,
+ redoc_url=None,
+ openapi_url=None,
+ )
+ state = gateway.state
+
+ @app.get("/health")
+ async def health(request: Request):
+ result = {
+ "status": "ok",
+ "service": "openviking-gateway",
+ "auth_mode": state.health.get("auth_mode", "api_key"),
+ "openviking_url": state.openviking_url,
+ "openviking": state.health,
+ }
+ if key := request_credential(request):
+ # Studio learns of an invalid OV key from /access, not from host detection.
+ try:
+ identity = await state.viking.identify(key)
+ except VikingError:
+ identity = {}
+ result.update(
+ {
+ field: identity[field]
+ for field in ("account_id", "user_id", "role", "auth_mode")
+ if field in identity
+ }
+ )
+ return result
+
+ @app.get("/api/v1/admin/accounts")
+ @app.get("/api/v1/admin/accounts/{account_id}/users")
+ async def administration(request: Request, account_id: str | None = None):
+ credential = request_credential(request)
+ # Rejects trusted mode, where OV would authorize identity headers this route drops.
+ await state.viking.identify(credential)
+ path = "/api/v1/admin/accounts"
+ if account_id is not None:
+ path += "/" + quote(account_id, safe="") + "/users"
+ params = dict(request.query_params)
+ if account_id is not None:
+ params["include_credentials"] = "false"
+ if params:
+ path += "?" + urlencode(params)
+ result = await state.viking.request("GET", path, credential)
+ return {"status": "ok", "result": result}
+
+ directory = studio_dir or studio_directory()
+ root = Path(directory).resolve() if directory else None
+
+ @app.get("/")
+ async def home():
+ return RedirectResponse("/studio/")
+
+ @app.get("/studio")
+ async def studio_redirect():
+ return RedirectResponse("/studio/")
+
+ @app.get("/studio/{path:path}")
+ async def studio(path: str):
+ if root is None or not (root / "index.html").is_file():
+ raise HTTPException(503, "OpenViking Studio bundle is unavailable")
+ candidate = (root / path).resolve()
+ if not candidate.is_relative_to(root):
+ raise HTTPException(404)
+ if candidate.is_file():
+ return FileResponse(candidate)
+ if path.startswith("assets/"):
+ raise HTTPException(404)
+ return FileResponse(root / "index.html")
+
+ app.mount(MOUNT_PATH, gateway)
+ return app
diff --git a/openviking_gateway/storage.py b/openviking_gateway/storage.py
index 09cea642d..9486b1890 100644
--- a/openviking_gateway/storage.py
+++ b/openviking_gateway/storage.py
@@ -1,11 +1,12 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
-"""SQLite adapters and encrypted management data. Writes have a dedicated executor."""
+"""SQLite adapters with optionally encrypted values. Writes have a dedicated executor."""
import asyncio
import hashlib
import os
import queue
+import re
import sqlite3
import time
from concurrent.futures import ThreadPoolExecutor
@@ -13,9 +14,11 @@ from contextlib import contextmanager
from functools import partial
from pathlib import Path
from typing import Any, Protocol
+from urllib.parse import urlsplit
import orjson
-from cryptography.fernet import Fernet
+
+from openviking.crypto.encryptor import MAGIC
from .cache import TTLCache
from .capture_store import CaptureQueue, SQLiteCaptureQueue
@@ -24,7 +27,10 @@ from .state_store import SQLiteStateStore, StateStore
# Pre-release builds stamped versions 1-4 on incompatible layouts; reusing
# one of them would let old files through and fail on the first write.
-SCHEMA_VERSION = 5
+SCHEMA_VERSION = 6
+# Gateway data is not an OpenViking account's; it derives its own key from the root key.
+ENCRYPTION_ACCOUNT = "_gateway"
+LEGACY_KEY_ENVIRONMENT = "OPENVIKING_GATEWAY_ENCRYPTION_KEY"
def digest(value: str) -> str:
@@ -43,14 +49,15 @@ class KernelStore(Protocol):
class Database:
- def __init__(self, path: Path, encryption_key: str):
+ def __init__(self, path: Path, encryptor=None):
path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
self.path = path
# Protect the file before SQLite opens it, not once per operation.
fd = os.open(path, os.O_CREAT | os.O_RDWR, 0o600)
os.fchmod(fd, 0o600)
os.close(fd)
- self.cipher = Fernet(encryption_key.encode())
+ self.encryptor = encryptor
+ self.loop = None
self.pool = queue.LifoQueue(maxsize=6)
self.readers = ThreadPoolExecutor(max_workers=4, thread_name_prefix="gateway-read")
self.writer = ThreadPoolExecutor(max_workers=1, thread_name_prefix="gateway-write")
@@ -75,6 +82,31 @@ class Database:
except queue.Full:
connection.close()
+ @staticmethod
+ def use_wal(connection):
+ # Leaving rollback mode needs an exclusive lock, and SQLite reports a concurrent
+ # switch as "database is locked" at once instead of waiting out the busy timeout.
+ # Workers opening a new or v5 store together retry until one has converted it.
+ for _ in range(200):
+ try:
+ connection.execute("PRAGMA journal_mode=WAL")
+ return
+ except sqlite3.OperationalError as error:
+ if "locked" not in str(error):
+ raise
+ time.sleep(0.05)
+ connection.execute("PRAGMA journal_mode=WAL")
+
+ @staticmethod
+ def begin_migration(connection):
+ """Serialize the one-time migration across standalone/server workers."""
+ # Re-encoding a large v5 store outlasts the 30 s busy timeout of workers waiting here.
+ connection.execute("PRAGMA busy_timeout=600000")
+ try:
+ connection.execute("BEGIN IMMEDIATE")
+ finally:
+ connection.execute("PRAGMA busy_timeout=30000")
+
def close(self):
self.readers.shutdown(wait=True)
self.writer.shutdown(wait=True)
@@ -85,20 +117,67 @@ class Database:
return
def encode(self, value: Any) -> bytes:
- return self.cipher.encrypt(orjson.dumps(value))
+ data = orjson.dumps(value)
+ if self.encryptor is None:
+ return data
+ return self.crypt(self.encryptor.encrypt(ENCRYPTION_ACCOUNT, data))
def decode(self, value: bytes) -> Any:
- return orjson.loads(self.cipher.decrypt(value))
+ # Values written before encryption was enabled stay readable as plaintext.
+ if value.startswith(MAGIC):
+ if self.encryptor is None:
+ raise RuntimeError(
+ "Gateway data is encrypted; configure the encryption settings it was "
+ "written with"
+ )
+ value = self.crypt(self.encryptor.decrypt(ENCRYPTION_ACCOUNT, value))
+ return orjson.loads(value)
+
+ def crypt(self, coroutine):
+ """Run an encryptor coroutine on the app loop from a storage thread."""
+ return asyncio.run_coroutine_threadsafe(coroutine, self.loop).result()
async def run(self, fn, *args, write=False):
- return await asyncio.get_running_loop().run_in_executor(
+ self.loop = asyncio.get_running_loop()
+ return await self.loop.run_in_executor(
self.writer if write else self.readers, partial(fn, *args)
)
+ def migrate_legacy_values(self, c, tables):
+ """Rewrite v0.5.0 values, which were Fernet-encrypted with a gateway-owned key."""
+ from cryptography.fernet import Fernet
+
+ cipher = None
+ for table in tables:
+ last = 0
+ while rows := c.execute(
+ f"SELECT rowid,value FROM {table} WHERE rowid>? ORDER BY rowid LIMIT 500",
+ (last,),
+ ).fetchall():
+ cipher = cipher or Fernet(self.legacy_key())
+ for rowid, value in rows:
+ c.execute(
+ f"UPDATE {table} SET value=? WHERE rowid=?",
+ (self.encode(orjson.loads(cipher.decrypt(value))), rowid),
+ )
+ last = rows[-1][0]
+
+ def legacy_key(self) -> bytes:
+ if key := os.environ.get(LEGACY_KEY_ENVIRONMENT):
+ return key.encode()
+ try:
+ return (self.path.parent / "encryption.key").read_bytes().strip()
+ except FileNotFoundError:
+ raise ValueError(
+ f"{self.path} holds data encrypted by OpenViking Gateway 0.5; set "
+ f"{LEGACY_KEY_ENVIRONMENT} or restore {self.path.parent / 'encryption.key'} "
+ "with the original key to migrate it"
+ ) from None
+
class SQLiteKernelStore(Database):
- def __init__(self, path, encryption_key):
- super().__init__(path, encryption_key)
+ def __init__(self, path, encryptor=None):
+ super().__init__(path, encryptor)
self.replay = SQLiteReplayStore(self)
self.capture = SQLiteCaptureQueue(self)
self.state = SQLiteStateStore(self)
@@ -107,9 +186,9 @@ class SQLiteKernelStore(Database):
async def initialize(self):
def initialize():
with self.connect() as c:
- if c.execute("PRAGMA user_version").fetchone()[0] not in (0, SCHEMA_VERSION):
+ if c.execute("PRAGMA user_version").fetchone()[0] not in (0, 5, SCHEMA_VERSION):
raise ValueError("Unsupported gateway schema; configure a fresh storage_path")
- c.execute("PRAGMA journal_mode=WAL")
+ self.use_wal(c)
c.executescript("""
CREATE TABLE IF NOT EXISTS sessions (
scope TEXT, session TEXT, touched REAL NOT NULL,
@@ -132,7 +211,11 @@ class SQLiteKernelStore(Database):
CREATE INDEX IF NOT EXISTS capture_ready ON capture(ready,lease);
CREATE TABLE IF NOT EXISTS deleted_scopes (scope TEXT PRIMARY KEY);
""")
+ self.begin_migration(c)
+ if c.execute("PRAGMA user_version").fetchone()[0] == 5:
+ self.migrate_legacy_values(c, ("replay", "state", "capture"))
c.execute(f"PRAGMA user_version={SCHEMA_VERSION}")
+ c.commit()
await self.run(initialize, write=True)
@@ -237,34 +320,67 @@ class SQLiteKernelStore(Database):
class ManagementStore(Database):
- def __init__(self, path, encryption_key):
- super().__init__(path, encryption_key)
+ def __init__(self, path, encryptor=None):
+ super().__init__(path, encryptor)
self.cache = TTLCache(ttl=2, capacity=2048)
async def initialize(self):
def initialize():
with self.connect() as c:
- if c.execute("PRAGMA user_version").fetchone()[0] not in (0, SCHEMA_VERSION):
+ if c.execute("PRAGMA user_version").fetchone()[0] not in (0, 5, SCHEMA_VERSION):
raise ValueError("Unsupported gateway schema; configure a fresh storage_path")
- c.execute("PRAGMA journal_mode=WAL")
+ self.use_wal(c)
c.executescript("""
CREATE TABLE IF NOT EXISTS objects (
account TEXT, kind TEXT, id TEXT, revision INTEGER, value BLOB,
PRIMARY KEY(account,kind,id));
CREATE INDEX IF NOT EXISTS object_identity ON objects(kind,id);
CREATE TABLE IF NOT EXISTS request_logs (
- id INTEGER PRIMARY KEY, account TEXT, time REAL, value BLOB);
- CREATE INDEX IF NOT EXISTS log_account ON request_logs(account,time);
+ id INTEGER PRIMARY KEY, account TEXT, time REAL, value BLOB, user TEXT);
CREATE TABLE IF NOT EXISTS object_expiry (
account TEXT, kind TEXT, id TEXT, expires REAL,
PRIMARY KEY(account,kind,id));
CREATE INDEX IF NOT EXISTS expiry_time ON object_expiry(expires);
""")
+ self.begin_migration(c)
+ if c.execute("PRAGMA user_version").fetchone()[0] == 5:
+ c.execute("ALTER TABLE request_logs ADD COLUMN user TEXT")
+ self.migrate_legacy_values(c, ("objects", "request_logs"))
+ for row in c.execute("SELECT * FROM objects WHERE kind='upstreams'").fetchall():
+ value = self.decode(row["value"])
+ # Keep v5 request URLs: v5 appended /v1 to non-Ark bases lacking it.
+ # Bases already ending in another version (/api/paas/v4) produced
+ # .../v4/v1 in v5, which no provider serves; leave them as entered.
+ base = value["base_url"].rstrip("/")
+ path = urlsplit(base).path
+ ark = value.get("vendor") in {"ark", "byteplus"}
+ if value["protocol"] == "anthropic":
+ if ark and not path:
+ base += "/api/compatible"
+ if base.endswith("/v1"):
+ base = base[:-3]
+ elif ark:
+ if not path:
+ base += "/api/v3"
+ elif not re.search(r"/v\d+$", path):
+ base += "/v1"
+ if base != value["base_url"]:
+ value["base_url"] = base
+ c.execute(
+ "UPDATE objects SET value=?,revision=revision+1 "
+ "WHERE account=? AND kind=? AND id=?",
+ (self.encode(value), row["account"], row["kind"], row["id"]),
+ )
+ c.execute("DROP INDEX IF EXISTS log_account")
+ c.execute(
+ "CREATE INDEX IF NOT EXISTS log_account_user ON request_logs(account,user,time)"
+ )
c.execute(f"PRAGMA user_version={SCHEMA_VERSION}")
+ c.commit()
await self.run(initialize, write=True)
- async def list(self, account, kind):
+ async def list(self, account, kind, user_id=None):
def read():
with self.connect() as c:
return [
@@ -276,8 +392,14 @@ class ManagementStore(Database):
]
if kind in {"keys", "upstreams"}:
- return await self.cache.get(("list", account, kind), lambda: self.run(read))
- return await self.run(read)
+ values = await self.cache.get(("list", account, kind), lambda: self.run(read))
+ else:
+ values = await self.run(read)
+ return (
+ [value for value in values if value.get("user_id") == user_id]
+ if user_id is not None
+ else values
+ )
async def get(self, account, kind, identifier):
def read():
@@ -352,29 +474,57 @@ class ManagementStore(Database):
return await self.cache.get(("auth", identifier), lambda: self.run(read))
- async def log(self, account, value):
+ async def log(self, account, value, user_id=None):
def log():
with self.connect() as c:
c.execute(
- "INSERT INTO request_logs(account,time,value) VALUES (?,?,?)",
- (account, time.time(), self.encode(value)),
+ "INSERT INTO request_logs(account,time,value,user) VALUES (?,?,?,?)",
+ (account, time.time(), self.encode(value), user_id),
)
await self.run(log, write=True)
- async def logs(self, account, limit=200):
+ async def logs(self, account, limit=200, user_id=None):
def read():
with self.connect() as c:
+ where, args = "account=?", [account]
+ if user_id is not None:
+ where += " AND user=?"
+ args.append(user_id)
return [
{"time": r["time"], **self.decode(r["value"])}
for r in c.execute(
- "SELECT time,value FROM request_logs WHERE account=? ORDER BY id DESC LIMIT ?",
- (account, limit),
+ f"SELECT time,value FROM request_logs WHERE {where} ORDER BY id DESC LIMIT ?",
+ (*args, limit),
)
]
return await self.run(read)
+ async def delete_user(self, account, user_id):
+ def delete():
+ with self.connect() as c:
+ c.execute("BEGIN IMMEDIATE")
+ for row in c.execute(
+ "SELECT kind,id,value FROM objects WHERE account=? "
+ "AND kind IN ('keys','users','responses')",
+ (account,),
+ ).fetchall():
+ if self.decode(row["value"]).get("user_id") == user_id:
+ identity = (account, row["kind"], row["id"])
+ c.execute(
+ "DELETE FROM objects WHERE account=? AND kind=? AND id=?", identity
+ )
+ c.execute(
+ "DELETE FROM object_expiry WHERE account=? AND kind=? AND id=?",
+ identity,
+ )
+ c.execute("DELETE FROM request_logs WHERE account=? AND user=?", (account, user_id))
+ c.commit()
+
+ await self.run(delete, write=True)
+ self.cache.clear()
+
async def expire_logs(self, before):
def expire():
with self.connect() as c:
@@ -401,3 +551,23 @@ class ManagementStore(Database):
await self.run(delete, write=True)
self.cache.clear()
+
+
+async def delete_user_data(management, store, account, user_id):
+ """Revoke keys and erase gateway state; OpenViking memory is unaffected."""
+ # Keys go first, so a response finishing meanwhile no longer finds one to record state for.
+ await management.delete_user(account, user_id)
+ for protocol in ("chat", "responses", "anthropic"):
+ await store.expire(0, digest(account + "\0" + user_id + "\0" + protocol))
+
+
+async def delete_account_data(management, store, account):
+ users = {
+ value["user_id"]
+ for kind in ("users", "keys")
+ for value in await management.list(account, kind)
+ if value.get("user_id")
+ }
+ for user_id in users:
+ await delete_user_data(management, store, account, user_id)
+ await management.delete_account(account)
diff --git a/openviking_gateway/tool_executor.py b/openviking_gateway/tool_executor.py
index 98b5bc450..a4861e6e6 100644
--- a/openviking_gateway/tool_executor.py
+++ b/openviking_gateway/tool_executor.py
@@ -17,6 +17,7 @@ import orjson
from .capture_store import Document
from .client import VikingError
+from .config import MOUNT_PATH
from .state_store import get_state
from .storage import digest
from .tool_catalog import PREFIX, TOOL_OVERRIDES
@@ -270,7 +271,7 @@ class ToolExecutor:
if token:
if not self.public_url:
raise ValueError("Set gateway.public_url for client uploads")
- url = self.public_url + "/gateway/uploads?token=" + quote(token, safe="")
+ url = self.public_url + MOUNT_PATH + "/uploads?token=" + quote(token, safe="")
for block in value.get("content", []):
if block.get("type") == "text":
block["text"] = UPLOAD_URL.sub(lambda _: url, block["text"])
diff --git a/openviking_gateway/tool_protocols/anthropic.py b/openviking_gateway/tool_protocols/anthropic.py
index f7af5127b..f41a4e0d7 100644
--- a/openviking_gateway/tool_protocols/anthropic.py
+++ b/openviking_gateway/tool_protocols/anthropic.py
@@ -26,10 +26,6 @@ class AnthropicProtocol(ToolProtocol):
reply_ends = frozenset({"end_turn", "stop_sequence", "tool_use"})
signed_thinking = True
- @staticmethod
- def auth_header(key):
- return {"x-api-key": key}
-
@staticmethod
def thinking_as_text(message):
content = message.get("content")
diff --git a/openviking_gateway/tool_protocols/common.py b/openviking_gateway/tool_protocols/common.py
index 08494321e..8690f8a68 100644
--- a/openviking_gateway/tool_protocols/common.py
+++ b/openviking_gateway/tool_protocols/common.py
@@ -208,10 +208,6 @@ class ToolProtocol(ABC):
"""Whether the body carries the whole history, which recall and replay need."""
return True
- @staticmethod
- def auth_header(key: str) -> dict:
- return {"authorization": "Bearer " + key}
-
@staticmethod
def is_reply(message: dict) -> bool:
"""Whether a history item belongs to a model reply, so a reply can end at it."""
diff --git a/openviking_gateway/vendors.py b/openviking_gateway/vendors.py
index 6acad6338..9a72ba053 100644
--- a/openviking_gateway/vendors.py
+++ b/openviking_gateway/vendors.py
@@ -3,19 +3,12 @@
"""Vendor differences without converting or dropping protocol fields."""
import hashlib
-from urllib.parse import urlsplit
import orjson
# Volcano Engine Ark and BytePlus ModelArk, its international edition, share
# paths and caching behavior.
ARK_VENDORS = {"ark", "byteplus"}
-ARK_PATHS = {
- "/api/v3/chat/completions": "/v1/chat/completions",
- "/api/v3/responses": "/v1/responses",
- "/api/compatible/v1/messages": "/v1/messages",
- "/api/compatible/v1/messages/count_tokens": "/v1/messages/count_tokens",
-}
STABLE_PARAMETERS = (
"model",
"thinking",
@@ -38,20 +31,6 @@ def parameter_fingerprint(body):
).hexdigest()
-def ark_url(upstream, path):
- base = upstream["base_url"].rstrip("/")
- base_path = urlsplit(base).path
- if path.startswith("/v1/messages"):
- suffix = path.removeprefix("/v1")
- return (
- base + suffix
- if base_path.endswith("/api/compatible/v1")
- else base + "/api/compatible/v1" + suffix
- )
- suffix = path.removeprefix("/v1")
- return base + suffix if base_path.endswith("/api/v3") else base + "/api/v3" + suffix
-
-
async def apply_vendor(body, upstream, prepared, store):
if upstream.get("vendor") not in ARK_VENDORS or prepared is None:
return body
diff --git a/pyproject.toml b/pyproject.toml
index 40b31531d..4d8cdf316 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -29,6 +29,10 @@ classifiers = [
"Programming Language :: Python :: 3.14",
]
dependencies = [
+ "aiohttp>=3.13.3",
+ "async-timeout>=5.0.1",
+ "orjson>=3.11.7",
+ "packaging>=24.0",
"openviking-sdk>=0.1.15",
"pydantic>=2.0.0",
"typing-extensions>=4.5.0",
@@ -89,12 +93,6 @@ dependencies = [
[project.optional-dependencies]
-gateway = [
- "aiohttp>=3.13.3",
- "async-timeout>=5.0.1",
- "orjson>=3.11.7",
- "packaging>=24.0",
-]
gateway-fast = [
"uvloop>=0.21; sys_platform != 'win32'",
"httptools>=0.6",
diff --git a/scripts/gateway_benchmark.py b/scripts/gateway_benchmark.py
index e15812435..2fbb0f177 100644
--- a/scripts/gateway_benchmark.py
+++ b/scripts/gateway_benchmark.py
@@ -8,7 +8,6 @@ provider latency or cache hit rates. Run with PYTHONPATH set to the tested tree.
import argparse
import asyncio
import json
-import os
import platform
import socket
import statistics
@@ -20,11 +19,11 @@ import aiohttp
import orjson
import uvicorn
from aiohttp import web
-from cryptography.fernet import Fernet
from gateway_profile import RuntimeProfile
+from openviking.crypto import FileEncryptor, LocalFileProvider
from openviking_gateway.app import create_app
-from openviking_gateway.config import OpenVikingGatewayConfig
+from openviking_gateway.config import GatewayConfig
from openviking_gateway.kernel import MemoryKernel
from openviking_gateway.models import Policy, Upstream
from openviking_gateway.protocols import parse_body
@@ -92,10 +91,12 @@ async def benchmark(args):
times.append((time.perf_counter() - started) * 1000)
result["parse_8mib"] = distribution(times)
with tempfile.TemporaryDirectory(prefix="ovgw-bench-") as directory:
- encryption = Fernet.generate_key().decode()
- store = SQLiteKernelStore(Path(directory) / "replay.sqlite3", encryption)
+ encryptor = FileEncryptor(LocalFileProvider(str(Path(directory) / "master.key")))
+ store = SQLiteKernelStore(Path(directory) / "replay.sqlite3", encryptor)
await store.initialize()
- policy = Policy(recall=False, capture=False, takeover=False).model_dump()
+ policy = Policy(
+ recall=False, profile=False, capture=False, gateway_tools=False
+ ).model_dump()
credential = {
"account": "bench",
"user_id": "bench",
@@ -116,15 +117,18 @@ async def benchmark(args):
headers = {"x-openviking-session": str(turns)}
body = {"model": "benchmark", "messages": messages}
await kernel.prepare(body, "chat", headers, credential, {"id": "upstream"}, policy)
+ # Encryption runs on this loop, so encode on a storage thread.
+ receipt = await store.run(store.encode, {"content": "old receipt"})
with store.connect() as c:
c.execute("BEGIN IMMEDIATE")
c.executemany(
- "INSERT OR IGNORE INTO state VALUES (?,?,?,1)",
+ "INSERT OR IGNORE INTO state VALUES (?,?,?,1,?)",
(
(
digest("bench\0bench\0chat"),
f"tool:{turns}:{i}",
- store.encode({"content": "old receipt"}),
+ receipt,
+ time.time(),
)
for i in range(turns * 10)
),
@@ -202,15 +206,9 @@ async def benchmark(args):
site = web.TCPSite(runner, "127.0.0.1", 0, backlog=2048)
await site.start()
base = f"http://127.0.0.1:{site._server.sockets[0].getsockname()[1]}"
- os.environ["OVGW_BENCH_ENCRYPTION"] = encryption
- os.environ["OVGW_BENCH_ADMIN"] = "synthetic-benchmark-admin-token-000000"
- config = OpenVikingGatewayConfig(
- storage_path=directory,
- openviking_url=base,
- encryption_key_env="OVGW_BENCH_ENCRYPTION",
- admin_token_env="OVGW_BENCH_ADMIN",
+ app = create_app(
+ GatewayConfig(storage_path=directory), openviking_url=base, encryptor=encryptor
)
- app = create_app(config)
listener = socket.socket()
listener.bind(("127.0.0.1", 0))
listener.listen(2048)
diff --git a/tests/cli/test_setup_wizard.py b/tests/cli/test_setup_wizard.py
index ab4283a25..76264f141 100644
--- a/tests/cli/test_setup_wizard.py
+++ b/tests/cli/test_setup_wizard.py
@@ -6,6 +6,8 @@ import json
import os
from unittest.mock import MagicMock, patch
+import pytest
+
from openviking_cli.setup_wizard import (
_CUSTOM_SETUP,
_DEFAULT_KIMI_MODEL,
@@ -1022,6 +1024,162 @@ class TestServerWizardCurrentDefaults:
assert len(result["root_api_key"]) == 64
+class TestGatewayWizard:
+ def test_local_enable_needs_no_management_key(self):
+ from openviking_cli.setup_wizard import _wizard_gateway
+
+ with patch("openviking_cli.setup_wizard._prompt_confirm", return_value=True) as prompt:
+ assert _wizard_gateway({"host": "127.0.0.1"}) == {"enabled": True}
+ assert prompt.call_count == 1
+
+ def test_remote_restricted_generates_key_and_preserves_it_on_update(self):
+ from openviking_cli.setup_wizard import _wizard_gateway
+
+ server = {"root_api_key": "root-secret"}
+ with (
+ patch("openviking_cli.setup_wizard._prompt_confirm", side_effect=[True, False]),
+ patch("builtins.print"),
+ ):
+ gateway = _wizard_gateway(server)
+ assert gateway["management_key"].startswith("ovgm_")
+ assert len(gateway["management_key"]) >= 32
+ with (
+ patch("openviking_cli.setup_wizard._prompt_confirm", side_effect=[True, False]),
+ patch("builtins.print") as output,
+ ):
+ assert _wizard_gateway(server, gateway) == gateway
+ assert gateway["management_key"] not in str(output.call_args_list)
+
+ def test_open_configuration_removes_management_key(self):
+ from openviking_cli.setup_wizard import _wizard_gateway
+
+ with patch("openviking_cli.setup_wizard._prompt_confirm", side_effect=[True, True]):
+ assert _wizard_gateway(
+ {"auth_mode": "api_key"},
+ {"enabled": True, "management_key": "old-secret", "storage_path": "/gateway"},
+ ) == {"enabled": True, "storage_path": "/gateway"}
+
+ def test_gateway_update_preserves_other_sections_and_redacts_summary(self, tmp_path):
+ config_path = tmp_path / "ov.conf"
+ original = _existing_config()
+ original["gateway"] = {"enabled": False, "management_key": "ovgm_saved-secret"}
+ config_path.write_text(json.dumps(original))
+ with (
+ patch("openviking_cli.setup_wizard._prompt_confirm", return_value=True),
+ patch("openviking_cli.setup_wizard._post_save_actions"),
+ patch("builtins.print") as output,
+ ):
+ assert _update_existing_config(config_path, "gateway") == 0
+ updated = json.loads(config_path.read_text())
+ assert updated == {**original, "gateway": {**original["gateway"], "enabled": True}}
+ assert "ovgm_saved-secret" not in str(output.call_args_list)
+
+ def test_update_drops_legacy_fields_and_stale_public_url(self):
+ from openviking_cli.setup_wizard import _wizard_gateway
+
+ legacy = {
+ "enabled": True,
+ "host": "0.0.0.0",
+ "port": 1935,
+ "workers": 2,
+ "url": "http://127.0.0.1:1935",
+ "openviking_url": "http://127.0.0.1:1933",
+ "admin_token_env": "OPENVIKING_GATEWAY_ADMIN_TOKEN",
+ "encryption_key_env": "OPENVIKING_GATEWAY_ENCRYPTION_KEY",
+ "public_url": "http://127.0.0.1:1935",
+ "storage_path": "/gateway",
+ }
+ with (
+ patch(
+ "openviking_cli.setup_wizard._prompt_confirm", side_effect=[True, True]
+ ) as prompt,
+ patch("builtins.print"),
+ ):
+ gateway = _wizard_gateway({"host": "127.0.0.1", "port": 1933}, legacy)
+ assert gateway == {"enabled": True, "storage_path": "/gateway"}
+ assert prompt.call_args_list[1].kwargs["default"] is True
+
+ def test_public_url_on_server_port_is_kept_without_asking(self):
+ from openviking_cli.setup_wizard import _wizard_gateway
+
+ current = {"enabled": True, "public_url": "https://ov.example.com"}
+ with patch("openviking_cli.setup_wizard._prompt_confirm", return_value=True) as prompt:
+ assert _wizard_gateway({"host": "127.0.0.1"}, current) == current
+ assert prompt.call_count == 1
+
+ def test_server_switch_to_local_drops_management_key(self, tmp_path):
+ config_path = tmp_path / "ov.conf"
+ original = _existing_config()
+ original["server"] = {"host": "0.0.0.0", "port": 1933, "root_api_key": "rk"}
+ original["gateway"] = {"enabled": True, "management_key": "ovgm_saved-secret"}
+ config_path.write_text(json.dumps(original))
+ with (
+ patch(
+ "openviking_cli.setup_wizard._wizard_server",
+ return_value={"host": "127.0.0.1", "port": 1933},
+ ),
+ patch("openviking_cli.setup_wizard._prompt_confirm", return_value=True),
+ patch("openviking_cli.setup_wizard._post_save_actions"),
+ patch("builtins.print"),
+ ):
+ assert _update_existing_config(config_path, "server") == 0
+ assert json.loads(config_path.read_text())["gateway"] == {"enabled": True}
+
+ def test_server_switch_to_remote_asks_who_may_configure(self, tmp_path):
+ config_path = tmp_path / "ov.conf"
+ original = _existing_config()
+ original["gateway"] = {"enabled": True}
+ config_path.write_text(json.dumps(original))
+ with (
+ patch(
+ "openviking_cli.setup_wizard._wizard_server",
+ return_value={"host": "0.0.0.0", "port": 1933, "root_api_key": "rk"},
+ ),
+ patch("openviking_cli.setup_wizard._prompt_confirm", side_effect=[False, True]),
+ patch("openviking_cli.setup_wizard._post_save_actions"),
+ patch("builtins.print"),
+ ):
+ assert _update_existing_config(config_path, "server") == 0
+ gateway = json.loads(config_path.read_text())["gateway"]
+ assert gateway["enabled"] is True
+ assert gateway["management_key"].startswith("ovgm_")
+
+ def test_new_config_writes_gateway_and_summary_hides_management_key(self, tmp_path):
+ config_path = tmp_path / "ov.conf"
+ config = {
+ "embedding": {"dense": {"provider": "ollama", "model": "qwen", "dimension": 1024}}
+ }
+ with (
+ patch.dict(os.environ, {"OPENVIKING_CONFIG_FILE": str(config_path)}, clear=False),
+ patch("openviking_cli.setup_wizard._prompt_choice", return_value=2),
+ patch("openviking_cli.setup_wizard._wizard_ollama", return_value=(config, True)),
+ patch("openviking_cli.setup_wizard._wizard_query_planner", return_value=None),
+ patch(
+ "openviking_cli.setup_wizard._wizard_server",
+ return_value={"host": "0.0.0.0", "port": 1933, "root_api_key": "root-secret"},
+ ),
+ patch(
+ "openviking_cli.setup_wizard._prompt_confirm",
+ side_effect=lambda prompt, default=True: "Allow users" not in prompt,
+ ),
+ patch("openviking_cli.setup_wizard._write_config", return_value=True) as mock_write,
+ patch("openviking_cli.setup_wizard._post_save_actions", return_value=None),
+ patch("builtins.print") as mock_print,
+ ):
+ assert run_init() == 0
+
+ written = mock_write.call_args.args[0]
+ key = written["gateway"]["management_key"]
+ assert written["gateway"] == {"enabled": True, "management_key": key}
+ output = "\n".join(
+ " ".join(str(arg) for arg in call.args) for call in mock_print.call_args_list
+ )
+ # Shown once when generated; never in the summary.
+ assert output.count(key) == 1
+ assert "root-secret" not in output
+ assert "Gateway: enabled on server port · management key required" in output
+
+
class TestCurrentConfigSeeding:
def test_cloud_embedding_keeps_existing_key_and_model(self):
from openviking_cli.setup_wizard import _prompt_cloud_embedding
@@ -1080,7 +1238,7 @@ class TestCurrentConfigSeeding:
config_path.write_text(json.dumps(_existing_config()), encoding="utf-8")
with (
patch.dict(os.environ, {"OPENVIKING_CONFIG_FILE": str(config_path)}, clear=False),
- patch("openviking_cli.setup_wizard._prompt_choice", return_value=5) as mock_choice,
+ patch("openviking_cli.setup_wizard._prompt_choice", return_value=6) as mock_choice,
patch("builtins.print") as mock_print,
):
assert run_init() == 0
@@ -1387,19 +1545,20 @@ class TestPartialUpdate:
class TestRunInitExistingConfigMenu:
- def test_dispatches_partial_update(self, tmp_path):
+ @pytest.mark.parametrize("choice,section", [(2, "vlm"), (5, "gateway")])
+ def test_dispatches_partial_update(self, tmp_path, choice, section):
config_path = tmp_path / "ov.conf"
config_path.write_text(json.dumps(_existing_config()), encoding="utf-8")
with (
patch.dict(os.environ, {"OPENVIKING_CONFIG_FILE": str(config_path)}, clear=False),
- patch("openviking_cli.setup_wizard._prompt_choice", return_value=2),
+ patch("openviking_cli.setup_wizard._prompt_choice", return_value=choice),
patch(
"openviking_cli.setup_wizard._update_existing_config", return_value=0
) as mock_update,
patch("builtins.print"),
):
assert run_init() == 0
- mock_update.assert_called_once_with(config_path, "vlm")
+ mock_update.assert_called_once_with(config_path, section)
def test_cancel_leaves_config_untouched(self, tmp_path):
config_path = tmp_path / "ov.conf"
@@ -1407,7 +1566,7 @@ class TestRunInitExistingConfigMenu:
config_path.write_text(original, encoding="utf-8")
with (
patch.dict(os.environ, {"OPENVIKING_CONFIG_FILE": str(config_path)}, clear=False),
- patch("openviking_cli.setup_wizard._prompt_choice", return_value=5),
+ patch("openviking_cli.setup_wizard._prompt_choice", return_value=6),
patch("builtins.print"),
):
assert run_init() == 0
diff --git a/tests/fixtures/gateway_upstream_urls.json b/tests/fixtures/gateway_upstream_urls.json
new file mode 100644
index 000000000..314f69cf8
--- /dev/null
+++ b/tests/fixtures/gateway_upstream_urls.json
@@ -0,0 +1,22 @@
+[
+ {"name":"openai-chat","protocol":"chat","base_url":"https://api.openai.com/v1","path":"/v1/chat/completions","expected":"https://api.openai.com/v1/chat/completions"},
+ {"name":"openai-responses","protocol":"responses","base_url":"https://api.openai.com/v1","path":"/v1/responses","expected":"https://api.openai.com/v1/responses"},
+ {"name":"openai-models","protocol":"chat","base_url":"https://api.openai.com/v1","path":"/v1/models","expected":"https://api.openai.com/v1/models"},
+ {"name":"deepseek-root","protocol":"chat","base_url":"https://api.deepseek.com","path":"/v1/chat/completions","expected":"https://api.deepseek.com/chat/completions"},
+ {"name":"root-is-literal","protocol":"responses","base_url":"https://custom.example","path":"/v1/responses","expected":"https://custom.example/responses"},
+ {"name":"ark-chat","protocol":"chat","base_url":"https://ark.cn-beijing.volces.com/api/v3","path":"/v1/chat/completions","expected":"https://ark.cn-beijing.volces.com/api/v3/chat/completions"},
+ {"name":"ark-embeddings","protocol":"chat","base_url":"https://ark.cn-beijing.volces.com/api/v3","path":"/v1/embeddings","expected":"https://ark.cn-beijing.volces.com/api/v3/embeddings"},
+ {"name":"byteplus-responses","protocol":"responses","base_url":"https://ark.ap-southeast.bytepluses.com/api/v3","path":"/v1/responses/resp_123","expected":"https://ark.ap-southeast.bytepluses.com/api/v3/responses/resp_123"},
+ {"name":"ark-coding-chat","protocol":"chat","base_url":"https://ark.cn-beijing.volces.com/api/coding/v3","path":"/v1/chat/completions","expected":"https://ark.cn-beijing.volces.com/api/coding/v3/chat/completions"},
+ {"name":"glm-chat","protocol":"chat","base_url":"https://open.bigmodel.cn/api/paas/v4","path":"/v1/chat/completions","expected":"https://open.bigmodel.cn/api/paas/v4/chat/completions"},
+ {"name":"glm-responses","protocol":"responses","base_url":"https://open.bigmodel.cn/api/v1","path":"/v1/responses","expected":"https://open.bigmodel.cn/api/v1/responses"},
+ {"name":"glm-coding","protocol":"chat","base_url":"https://api.z.ai/api/coding/paas/v4","path":"/v1/chat/completions","expected":"https://api.z.ai/api/coding/paas/v4/chat/completions"},
+ {"name":"anthropic-messages","protocol":"anthropic","base_url":"https://api.anthropic.com","path":"/v1/messages","expected":"https://api.anthropic.com/v1/messages"},
+ {"name":"anthropic-count","protocol":"anthropic","base_url":"https://api.anthropic.com","path":"/v1/messages/count_tokens","expected":"https://api.anthropic.com/v1/messages/count_tokens"},
+ {"name":"anthropic-models","protocol":"anthropic","base_url":"https://api.anthropic.com","path":"/v1/models","expected":"https://api.anthropic.com/v1/models"},
+ {"name":"deepseek-anthropic","protocol":"anthropic","base_url":"https://api.deepseek.com/anthropic","path":"/v1/messages","expected":"https://api.deepseek.com/anthropic/v1/messages"},
+ {"name":"ark-anthropic","protocol":"anthropic","base_url":"https://ark.cn-beijing.volces.com/api/compatible","path":"/v1/messages","expected":"https://ark.cn-beijing.volces.com/api/compatible/v1/messages"},
+ {"name":"ark-coding-anthropic","protocol":"anthropic","base_url":"https://ark.cn-beijing.volces.com/api/coding","path":"/v1/messages","expected":"https://ark.cn-beijing.volces.com/api/coding/v1/messages"},
+ {"name":"kimi-trailing-slash","protocol":"anthropic","base_url":"https://api.kimi.com/coding/","path":"/v1/messages","expected":"https://api.kimi.com/coding/v1/messages"},
+ {"name":"ollama","protocol":"chat","base_url":"http://localhost:11434/v1","path":"/v1/chat/completions","expected":"http://localhost:11434/v1/chat/completions"}
+]
diff --git a/tests/gateway/README.md b/tests/gateway/README.md
index 462dc153a..7b112d84c 100644
--- a/tests/gateway/README.md
+++ b/tests/gateway/README.md
@@ -8,10 +8,10 @@ process. For what the gateway does and how to deploy it, see the user guides
## Run the suite
-Install the gateway extra and the test dependencies in your development environment:
+Install the core package and test dependencies in your development environment:
```bash
-pip install -e ".[gateway,test]"
+pip install -e ".[test]"
```
Run from the repository root:
@@ -27,6 +27,12 @@ test as usual, for example `tests/gateway/test_kernel.py::<test_name>`.
`fixtures/` holds sanitized requests recorded from real clients; see
[fixtures/README.md](fixtures/README.md) before updating them.
+## Host, management and migration coverage
+
+Management tests call `/gateway/admin/*` directly with OpenViking identities and the optional `X-OpenViking-Gateway-Management-Key`; there is no shared admin token. Cover root/admin/user/dev account and user scope, management-key-only object access, read-only secret redaction, key issuance, revocation only on an explicit OpenViking 401, VLM import permissions and re-import preserving edits, and changing base_url clearing retained credentials and headers.
+
+`tests/fixtures/gateway_upstream_urls.json` is shared with Studio URL tests. Keep SDK-style base joins, alternate client prefixes and Anthropic validation in sync. Storage tests cover the schema v5 → v6 migration, which re-encodes v0.5.0 Fernet values with the OpenViking encryptor (or as plaintext when encryption is off). Stores run the encryptor on the event loop, so tests that encode or decode directly must do it through `store.run`. Embedded host and VLM mapping integration tests live under `tests/server/`; standalone startup reads `gateway.conf` and `OPENVIKING_GATEWAY_*` variables, never `ov.conf`. Run those host tests separately with the full server test environment.
+
## Hidden tool protocol contracts
`test_native_tools.py` exercises native Responses and Anthropic wire messages through the
@@ -76,7 +82,7 @@ connection through environment variables:
| Variable | Value |
| --- | --- |
-| `OV_GW_TEST_BASE_URL` | Gateway origin without `/v1`, for example `http://127.0.0.1:1935` |
+| `OV_GW_TEST_BASE_URL` | Gateway address without `/v1`, for example `http://127.0.0.1:1933/gateway` (embedded) or `http://127.0.0.1:1935/gateway` (standalone) |
| `OV_GW_TEST_KEY` | Gateway key (`ovgw_…`) |
| `OV_GW_TEST_MODEL` | A model name the key allows |
diff --git a/tests/gateway/conftest.py b/tests/gateway/conftest.py
index d8d9722f8..cbdebb9e9 100644
--- a/tests/gateway/conftest.py
+++ b/tests/gateway/conftest.py
@@ -9,15 +9,20 @@ import orjson
import pytest
import pytest_asyncio
from aiohttp import web
-from cryptography.fernet import Fernet
+from openviking.crypto import FileEncryptor, LocalFileProvider
from openviking_gateway.app import create_app
-from openviking_gateway.config import OpenVikingGatewayConfig
+from openviking_gateway.config import GatewayConfig
from openviking_gateway.kernel import MemoryKernel
from openviking_gateway.models import Policy
from openviking_gateway.storage import SQLiteKernelStore
+def local_encryptor(key_file):
+ """OpenViking's local-provider encryptor; it creates the root key file on first use."""
+ return FileEncryptor(LocalFileProvider(str(key_file)))
+
+
def mcp_tool(name, properties, required=()):
return {
"name": name,
@@ -97,6 +102,9 @@ class FakeViking:
return [{"name": "alice", "isDir": True}]
return self.preferences if uri.endswith("/preferences") else self.entities
+ async def identify(self, key=""):
+ return await self.health(key)
+
async def health(self, key="", require_identity=True):
return {"version": "0.4.16", "role": "user", "account_id": "tenant", "user_id": "alice"}
@@ -139,12 +147,12 @@ def credential():
@pytest_asyncio.fixture
async def setup_kernel(tmp_path):
- key = Fernet.generate_key().decode()
- store = SQLiteKernelStore(tmp_path / "kernel.sqlite3", key)
+ encryptor = local_encryptor(tmp_path / "master.key")
+ store = SQLiteKernelStore(tmp_path / "kernel.sqlite3", encryptor)
await store.initialize()
viking = FakeViking()
kernel = MemoryKernel(store, viking)
- yield kernel, store, viking, key
+ yield kernel, store, viking, encryptor
store.close()
@@ -189,7 +197,7 @@ async def make_due(store):
@pytest_asyncio.fixture
-async def running_gateway(tmp_path, monkeypatch):
+async def running_gateway(tmp_path):
captured = []
writes = []
override = {}
@@ -200,7 +208,8 @@ async def running_gateway(tmp_path, monkeypatch):
key = request.headers.get("X-API-Key")
override.setdefault("tools_calls", []).append(key)
# Maps an OpenViking key to the HTTP status its tools/list gets.
- status = override.get("tools_status", {}).get(key, 200)
+ # Like OV, /mcp refuses root keys.
+ status = override.get("tools_status", {}).get(key, 403 if key == "root" else 200)
if status != 200:
return web.json_response({"error": "private server detail"}, status=status)
return web.json_response(
@@ -213,17 +222,47 @@ async def running_gateway(tmp_path, monkeypatch):
raw = await request.read()
body = json.loads(raw) if raw else {}
if request.path == "/health":
- key = request.headers.get("X-API-Key")
+ key = request.headers.get("X-API-Key", "")
+ status = override.get("health_status", {}).get(key, 200)
+ if status != 200:
+ return web.json_response({}, status=status)
+ if override.get("auth_mode") in {"dev", "trusted"}:
+ return web.json_response({"version": "0.4.16", "auth_mode": override["auth_mode"]})
return web.json_response(
{
"version": "0.4.16",
"status": "ok",
"auth_mode": "api_key",
- "role": "root" if key == "root" else "user",
+ "role": "root" if key == "root" else "admin" if key == "admin-key" else "user",
"account_id": "other" if key == "other" else "tenant",
- "user_id": "alice",
+ "user_id": "bob" if key == "bob-key" else "alice",
}
)
+ if request.path == "/api/v1/admin/accounts":
+ return web.json_response({"status": "ok", "result": [{"account_id": "tenant"}]})
+ if request.path.startswith("/api/v1/admin/accounts/") and request.path.endswith("/users"):
+ override.setdefault("users_calls", []).append(
+ (str(request.rel_url), request.headers.get("X-API-Key"))
+ )
+ users = override.get(
+ "users",
+ [
+ {"user_id": "alice", "role": "user", "api_key": "user-key"},
+ {"user_id": "bob", "role": "user", "api_key": "bob-key"},
+ ],
+ )
+ if name := request.query.get("name"):
+ users = [u for u in users if u["user_id"] == name]
+ if request.query.get("include_credentials") == "false":
+ users = [
+ {
+ "user_id": u["user_id"],
+ "role": u["role"],
+ "api_key_available": bool(u.get("api_key")),
+ }
+ for u in users
+ ]
+ return web.json_response({"status": "ok", "result": users})
if request.path == "/api/v1/search/search":
assert body["mode"] == "context" and "session_id" not in body
return web.json_response(
@@ -255,6 +294,8 @@ async def running_gateway(tmp_path, monkeypatch):
if request.path == "/api/v1/content/read":
return web.json_response({"status": "error"}, status=404)
captured.append((request.path, raw, dict(request.headers)))
+ if request.path.endswith("/models"):
+ return web.json_response({"data": []})
if body.get("model") == "error":
return web.Response(
body=b'{"error":{"raw":"provider error"}}',
@@ -318,16 +359,18 @@ async def running_gateway(tmp_path, monkeypatch):
site = web.TCPSite(runner, "127.0.0.1", 0)
await site.start()
base = f"http://127.0.0.1:{site._server.sockets[0].getsockname()[1]}"
- monkeypatch.setenv("OPENVIKING_GATEWAY_ENCRYPTION_KEY", Fernet.generate_key().decode())
- monkeypatch.setenv("OPENVIKING_GATEWAY_ADMIN_TOKEN", "admin-" + "x" * 32)
- config = OpenVikingGatewayConfig(enabled=True, storage_path=str(tmp_path), openviking_url=base)
- app = create_app(config)
+ config = GatewayConfig(storage_path=str(tmp_path))
+ app = create_app(
+ config, openviking_url=base, encryptor=local_encryptor(tmp_path / "master.key")
+ )
app.state.test_backend = override
async with app.router.lifespan_context(app):
+ # Requests arrive as the hosts mount the gateway: below root_path /gateway.
async with httpx.AsyncClient(
- transport=httpx.ASGITransport(app=app), base_url="http://gateway"
+ transport=httpx.ASGITransport(app=app, root_path="/gateway"),
+ base_url="http://gateway/gateway",
) as client:
- admin = {"Authorization": "Bearer admin-" + "x" * 32, "X-OpenViking-Account": "tenant"}
+ admin = {"X-API-Key": "admin-key"}
for protocol in ("chat", "anthropic", "responses"):
response = await client.put(
f"/admin/upstreams/{protocol}",
@@ -335,7 +378,7 @@ async def running_gateway(tmp_path, monkeypatch):
json={
"name": protocol,
"protocol": protocol,
- "base_url": base,
+ "base_url": base if protocol == "anthropic" else base + "/v1",
"api_key": "model-secret",
"models": ["model", "error"],
},
diff --git a/tests/gateway/test_app.py b/tests/gateway/test_app.py
index d8d7af87d..b5e3539cb 100644
--- a/tests/gateway/test_app.py
+++ b/tests/gateway/test_app.py
@@ -200,7 +200,7 @@ async def test_key_scope_revocation_and_root_rejection(running_gateway):
},
)
assert response.status_code == expected
- other_admin = {**admin, "X-OpenViking-Account": "other"}
+ other_admin = {"X-API-Key": "other"}
assert (await client.get("/admin/keys", headers=other_admin)).json() == []
listed = (await client.get("/admin/keys", headers=admin)).json()
assert key["key"] not in str(listed) and "user-key" not in str(listed)
@@ -606,6 +606,10 @@ async def test_ark_paths_unknown_fields_and_cache_key(
if k not in {"id", "revision", "has_api_key", "header_names", "account"}
}
payload["vendor"] = vendor
+ payload["base_url"] = payload["base_url"].removesuffix("/v1") + (
+ "/api/compatible" if payload["protocol"] == "anthropic" else "/api/v3"
+ )
+ payload["api_key"] = "model-secret"
response = await client.put("/admin/upstreams/" + protocol, headers=admin, json=payload)
assert response.status_code == 200, response.text
field = "input" if protocol == "responses" else "messages"
@@ -730,15 +734,13 @@ async def test_attachment_import_and_signed_upload_proxy(running_gateway, name):
assert "viking://resources/imported" in model_requests[1]["messages"][-1]["content"]
# The token is the sole upload authorization, and the destination is fixed.
response = await client.post(
- "/gateway/uploads?token=signed-once&url=http://attacker",
+ "/uploads?token=signed-once&url=http://attacker",
files={"file": ("notes.txt", b"upload")},
headers={"Authorization": "Bearer not-forwarded"},
)
assert response.status_code == 200, response.text
assert uploads[-1] == ("file", "notes.txt", b"upload")
- assert (
- await client.post("/gateway/uploads", files={"file": ("x.txt", b"x")})
- ).status_code == 400
+ assert (await client.post("/uploads", files={"file": ("x.txt", b"x")})).status_code == 400
async def test_shell_upload_instructions_use_public_proxy(running_gateway):
@@ -818,6 +820,10 @@ async def test_ark_responses_stream_keeps_native_fields_and_done(running_gateway
allowed = {"name", "protocol", "base_url", "models", "aliases", "vendor"}
payload = {k: v for k, v in upstream.items() if k in allowed}
payload["vendor"] = vendor
+ payload["base_url"] = payload["base_url"].removesuffix("/v1") + (
+ "/api/compatible" if payload["protocol"] == "anthropic" else "/api/v3"
+ )
+ payload["api_key"] = "model-secret"
assert (
await client.put("/admin/upstreams/responses", headers=admin, json=payload)
).status_code == 200
@@ -887,16 +893,34 @@ async def test_large_first_tool_request_keeps_client_token_limit(running_gateway
async def test_ark_connection_test_lists_models_under_api_v3(running_gateway, vendor):
app, client, admin, _, seen, _ = running_gateway
upstream = await app.state.management.get("tenant", "upstreams", "chat")
- await app.state.management.save("tenant", "upstreams", "chat", {**upstream, "vendor": vendor})
+ await app.state.management.save(
+ "tenant",
+ "upstreams",
+ "chat",
+ {
+ **upstream,
+ "vendor": vendor,
+ "base_url": upstream["base_url"].removesuffix("/v1") + "/api/v3",
+ },
+ )
response = await client.post("/admin/upstreams/chat/test", headers=admin)
- assert response.json() == {"ok": True, "status": 200}
+ assert response.json()["ok"] and response.json()["status"] == 200
assert seen[-1][0] == "/api/v3/models"
async def test_ark_burst_is_forwarded_without_local_429(running_gateway):
app, client, admin, key, seen, _ = running_gateway
upstream = await app.state.management.get("tenant", "upstreams", "chat")
- await app.state.management.save("tenant", "upstreams", "chat", {**upstream, "vendor": "ark"})
+ await app.state.management.save(
+ "tenant",
+ "upstreams",
+ "chat",
+ {
+ **upstream,
+ "vendor": "ark",
+ "base_url": upstream["base_url"].removesuffix("/v1") + "/api/v3",
+ },
+ )
headers = {"Authorization": "Bearer " + key["key"], "X-OpenViking-Session": "ark-burst"}
for _ in range(20):
response = await client.post(
@@ -1058,7 +1082,7 @@ async def test_capture_reset_is_scoped_to_the_key_account(running_gateway):
log = (await client.get("/admin/logs", headers=admin)).json()[0]
path = "/admin/keys/" + log["credential_id"] + "/capture/reset"
body = {"session": log["session"], "protocol": "chat"}
- wrong = await client.post(path, headers={**admin, "X-OpenViking-Account": "other"}, json=body)
+ wrong = await client.post(path, headers={"X-API-Key": "other"}, json=body)
assert wrong.status_code == 404
assert (await client.post(path, headers=admin, json=body)).status_code == 200
# The session header value the client sent names the same session.
@@ -1072,10 +1096,16 @@ async def test_capture_reset_is_scoped_to_the_key_account(running_gateway):
async def test_guides_report_the_client_facing_address(running_gateway):
app, client, admin, _, _, _ = running_gateway
response = await client.get("/admin/guides", headers=admin)
- assert response.json() == {"base_url": "http://127.0.0.1:1935", "public_url_configured": False}
+ assert response.json() == {
+ "base_url": "http://gateway/gateway",
+ "public_url_configured": False,
+ }
app.state.config.public_url = "https://ov.example.com"
response = await client.get("/admin/guides", headers=admin)
- assert response.json() == {"base_url": "https://ov.example.com", "public_url_configured": True}
+ assert response.json() == {
+ "base_url": "https://ov.example.com/gateway",
+ "public_url_configured": True,
+ }
async def test_upstream_save_keeps_blank_secrets_per_header(running_gateway):
@@ -1140,7 +1170,9 @@ async def test_user_and_account_data_deletion_routes(running_gateway):
response = await client.delete("/admin/users/bob/data", headers=admin)
assert response.json() == {"deleted": True}
assert (await client.get("/admin/keys", headers=admin)).json()
- response = await client.delete("/admin/account/data", headers=admin)
+ response = await client.delete(
+ "/admin/account/data?account_id=tenant", headers={"X-API-Key": "root"}
+ )
assert response.status_code == 200 and response.json() == {"deleted": True}
assert (await client.get("/admin/keys", headers=admin)).json() == []
response = await client.get("/v1/models", headers={"Authorization": "Bearer " + key["key"]})
@@ -1157,40 +1189,20 @@ async def test_admin_tools_list_the_mcp_tools_for_profiles(running_gateway):
{"name": "find", "description": "OpenViking find", "annotations": {"readOnlyHint": True}},
{"name": "list", "description": "OpenViking list"},
]
- assert backend["tools_calls"] == ["user-key"]
- # An account without gateway keys has no OpenViking key to list tools with.
- response = await client.get("/admin/tools", headers={**admin, "X-OpenViking-Account": "new"})
- assert response.status_code == 200 and response.json() == []
- assert backend["tools_calls"] == ["user-key"]
+ assert backend["tools_calls"] == ["admin-key"]
+ # Tools use the caller's credential and do not require a gateway key.
+ await app.state.management.delete("tenant", "keys", running_gateway[3]["id"])
+ response = await client.get("/admin/tools", headers=admin)
+ assert response.status_code == 200 and len(response.json()) == 2
-async def test_admin_tools_skip_rejected_keys_and_report_failures_cleanly(running_gateway):
+async def test_admin_tools_report_callers_failure_cleanly(running_gateway):
app, client, admin, _, _, _ = running_gateway
backend = app.state.test_backend
- response = await client.post(
- "/admin/keys",
- headers=admin,
- json={
- "name": "second",
- "openviking_key": "second-key",
- "policy_id": "default",
- "upstream_ids": ["chat"],
- },
- )
- assert response.status_code == 200, response.text
- # A 401 here would read as the admin's own Studio sign-in failing.
- backend["tools_status"] = {"user-key": 401, "second-key": 401}
- response = await client.get("/admin/tools", headers=admin)
- assert response.status_code == 502 and "private server detail" not in response.text
- # An outage is not retried with every key.
- backend["tools_status"] = {"user-key": 503, "second-key": 503}
- backend["tools_calls"] = []
- response = await client.get("/admin/tools", headers=admin)
- assert response.status_code == 502 and len(backend["tools_calls"]) == 1
- backend["tools_status"] = {"user-key": 401}
+ backend["tools_status"] = {"admin-key": 401}
response = await client.get("/admin/tools", headers=admin)
- assert response.status_code == 200 and len(response.json()) == len(MCP_TOOLS)
- assert backend["tools_calls"][-1] == "second-key"
+ assert response.status_code == 401 and "private server detail" not in response.text
+ assert backend["tools_calls"] == ["admin-key"]
async def test_model_restricted_key_rejects_bodies_without_a_readable_model(running_gateway):
diff --git a/tests/gateway/test_capture_lifecycle.py b/tests/gateway/test_capture_lifecycle.py
index cdc247ff8..6237ac89f 100644
--- a/tests/gateway/test_capture_lifecycle.py
+++ b/tests/gateway/test_capture_lifecycle.py
@@ -252,15 +252,6 @@ async def test_archive_state_uses_server_terminal_markers(marker, expected):
assert all("/api/v1/content/read?uri=viking%3A" in path for path in paths)
-def test_missing_optional_dependencies_explain_install(monkeypatch):
- from openviking_gateway import cli
-
- monkeypatch.setattr("sys.argv", ["openviking-gateway"])
- monkeypatch.setattr(cli, "find_spec", lambda _: None)
- with pytest.raises(SystemExit, match=r"openviking\[gateway\]"):
- cli.main()
-
-
async def test_capture_mailboxes_are_independent_and_lease_safe(setup_kernel):
_, store, _, _ = setup_kernel
await store.capture.swap("scope", "one", Document(), {"anchor": "same"}, 0)
diff --git a/tests/gateway/test_compaction.py b/tests/gateway/test_compaction.py
index 0368760f8..ab35dea8e 100644
--- a/tests/gateway/test_compaction.py
+++ b/tests/gateway/test_compaction.py
@@ -581,7 +581,7 @@ async def test_proxy_sends_the_summary_with_vendor_alias_and_headers(running_gat
json={
"name": "chat",
"protocol": "chat",
- "base_url": str(app.state.config.openviking_url),
+ "base_url": app.state.openviking_url + "/v1",
"models": ["model"],
"aliases": {"alias": "model"},
"context_windows": {"model": 1024},
diff --git a/tests/gateway/test_gateway_config.py b/tests/gateway/test_gateway_config.py
new file mode 100644
index 000000000..8a849564f
--- /dev/null
+++ b/tests/gateway/test_gateway_config.py
@@ -0,0 +1,282 @@
+"""Configuration schema, environment overrides and the standalone command line."""
+
+import json
+import sys
+
+import pytest
+from pydantic import ValidationError
+
+from openviking.crypto import FileEncryptor
+from openviking_gateway import cli
+from openviking_gateway.cli import load_config
+from openviking_gateway.client import VikingError
+from openviking_gateway.config import (
+ PUBLIC_OPENVIKING_URLS,
+ EmbeddedGatewayConfig,
+ GatewayConfig,
+ StandaloneGatewayConfig,
+)
+from openviking_gateway.standalone import build_encryptor
+
+
[email protected](autouse=True)
+def clean_environment(monkeypatch, tmp_path):
+ for field in {*EmbeddedGatewayConfig.model_fields, *StandaloneGatewayConfig.model_fields}:
+ monkeypatch.delenv("OPENVIKING_GATEWAY_" + field.upper(), raising=False)
+ monkeypatch.delenv("OPENVIKING_GATEWAY_CONFIG_FILE", raising=False)
+ monkeypatch.setattr(
+ cli, "DEFAULT_CONFIGS", (tmp_path / "home" / "gateway.conf", tmp_path / "etc.conf")
+ )
+ monkeypatch.setattr(cli, "USER_CONFIG", tmp_path / "home" / "gateway.conf")
+
+
+def test_removed_fields_are_ignored_with_one_warning(caplog):
+ legacy = {
+ "enabled": True,
+ "url": "http://127.0.0.1:1935",
+ "port": 1935,
+ "workers": 2,
+ "encryption_key_env": "MY_KEY",
+ }
+ config = EmbeddedGatewayConfig.model_validate(legacy)
+ assert config.enabled
+ assert "Ignoring removed gateway settings encryption_key_env, port, url, workers" in caplog.text
+ caplog.clear()
+ StandaloneGatewayConfig(openviking_url="http://localhost:1933", encryption_key_env="MY_KEY")
+ assert "Ignoring removed gateway settings encryption_key_env" in caplog.text
+ with pytest.raises(ValidationError):
+ EmbeddedGatewayConfig.model_validate({"enabled": True, "urll": "typo"})
+ with pytest.raises(ValidationError):
+ StandaloneGatewayConfig(openviking_url="http://localhost:1933", url="http://other")
+
+
+def test_standalone_requires_own_url_and_rejects_server_config():
+ with pytest.raises(ValidationError):
+ StandaloneGatewayConfig()
+ with pytest.raises(ValidationError):
+ StandaloneGatewayConfig(openviking_url="http://localhost:1933", enabled=True)
+ with pytest.raises(ValidationError):
+ EmbeddedGatewayConfig(encryption={"enabled": True})
+
+
+def test_standalone_encryption_block_uses_openviking_schema(tmp_path):
+ with pytest.raises(ValidationError):
+ StandaloneGatewayConfig(openviking_url="http://ov.test", encryption={"enabled": "maybe"})
+ config = StandaloneGatewayConfig(openviking_url="http://ov.test", encryption={"enabled": False})
+ assert build_encryptor(config) is None
+ assert build_encryptor(StandaloneGatewayConfig(openviking_url="http://ov.test")) is None
+ key_file = tmp_path / "master.key"
+ config = StandaloneGatewayConfig(
+ openviking_url="http://ov.test",
+ encryption={"enabled": True, "provider": "local", "local": {"key_file": str(key_file)}},
+ )
+ assert "encryption" not in repr(config)
+ assert isinstance(build_encryptor(config), FileEncryptor)
+
+
+async def test_encryptor_bootstraps_inside_a_running_loop(tmp_path):
+ # uvicorn calls the app factory from inside its event loop.
+ config = StandaloneGatewayConfig(
+ openviking_url="http://ov.test",
+ encryption={"enabled": True, "local": {"key_file": str(tmp_path / "master.key")}},
+ )
+ assert isinstance(build_encryptor(config), FileEncryptor)
+
+
+def test_management_key_expansion_and_length(monkeypatch):
+ monkeypatch.setenv("MANAGEMENT_SECRET", "ovgm_" + "a" * 32)
+ assert (
+ EmbeddedGatewayConfig(management_key="$MANAGEMENT_SECRET").management_key
+ == "ovgm_" + "a" * 32
+ )
+ with pytest.raises(ValidationError, match="at least 32"):
+ GatewayConfig(management_key="short")
+ with pytest.raises(ValidationError, match="at least 32"):
+ GatewayConfig(management_key="$UNDEFINED_MANAGEMENT_SECRET_THAT_IS_LONG")
+
+
+def test_embedded_environment_overrides_ov_conf(monkeypatch):
+ monkeypatch.setenv("OPENVIKING_GATEWAY_MANAGEMENT_KEY", "e" * 32)
+ monkeypatch.setenv("OPENVIKING_GATEWAY_ENABLED", "true")
+ monkeypatch.setenv("OPENVIKING_GATEWAY_STORAGE_PATH", "")
+ config = EmbeddedGatewayConfig.model_validate({"storage_path": "/data/gateway"})
+ assert config.enabled and config.management_key == "e" * 32
+ assert config.storage_path == "/data/gateway"
+ # A server whose ov.conf has no gateway section builds the default the same way.
+ assert EmbeddedGatewayConfig().management_key == "e" * 32
+
+
+def test_standalone_config_file_and_env_precedence(tmp_path, monkeypatch):
+ monkeypatch.setenv("OPENVIKING_CONFIG_FILE", str(tmp_path / "ignored-ov.conf"))
+ (tmp_path / "ignored-ov.conf").write_text('{"gateway":{"enabled":true}}')
+ config_file = tmp_path / "gateway.conf"
+ config_file.write_text(
+ json.dumps(
+ {
+ "openviking_url": "https://example.test/ov/",
+ "port": 9001,
+ "storage_path": "$GATEWAY_DATA",
+ }
+ )
+ )
+ monkeypatch.setenv("GATEWAY_DATA", str(tmp_path / "data"))
+ monkeypatch.setenv("OPENVIKING_GATEWAY_CONFIG_FILE", str(config_file))
+ monkeypatch.setenv("OPENVIKING_GATEWAY_PORT", "9002")
+ monkeypatch.setenv("OPENVIKING_GATEWAY_MANAGEMENT_KEY", "m" * 32)
+ config = load_config()
+ assert config.openviking_url == "https://example.test/ov"
+ assert config.port == 9002
+ assert config.management_key == "m" * 32
+ assert config.storage_path == str(tmp_path / "data")
+
+
+def test_empty_environment_values_keep_file_values(tmp_path, monkeypatch):
+ for field in StandaloneGatewayConfig.model_fields:
+ monkeypatch.setenv("OPENVIKING_GATEWAY_" + field.upper(), "")
+ config_file = tmp_path / "gateway.conf"
+ config_file.write_text(
+ json.dumps({"openviking_url": "https://example.test", "management_key": "f" * 32})
+ )
+ monkeypatch.setenv("OPENVIKING_GATEWAY_CONFIG_FILE", str(config_file))
+ config = load_config()
+ assert config.openviking_url == "https://example.test"
+ assert config.management_key == "f" * 32
+
+
+def test_kubernetes_service_link_variables_are_ignored(monkeypatch):
+ # A Service named openviking-gateway injects this into every pod in its namespace.
+ monkeypatch.setenv("OPENVIKING_GATEWAY_PORT", "tcp://10.96.0.12:1935")
+ config = StandaloneGatewayConfig.model_validate({"openviking_url": "http://openviking:1933"})
+ assert config.port == StandaloneGatewayConfig.model_fields["port"].default
+
+
+def test_config_lookup_order(tmp_path, monkeypatch):
+ home, etc = cli.DEFAULT_CONFIGS
+ assert cli.config_path() is None
+ etc.write_text(json.dumps({"openviking_url": "http://etc.test"}))
+ assert load_config().openviking_url == "http://etc.test"
+ home.parent.mkdir()
+ home.write_text(json.dumps({"openviking_url": "http://home.test"}))
+ assert load_config().openviking_url == "http://home.test"
+ explicit = tmp_path / "explicit.conf"
+ explicit.write_text(json.dumps({"openviking_url": "http://explicit.test"}))
+ monkeypatch.setenv("OPENVIKING_GATEWAY_CONFIG_FILE", str(explicit))
+ assert load_config().openviking_url == "http://explicit.test"
+ monkeypatch.setenv("OPENVIKING_GATEWAY_CONFIG_FILE", str(tmp_path / "missing.conf"))
+ with pytest.raises(SystemExit, match="not found"):
+ load_config()
+
+
+def test_environment_alone_configures_a_container(monkeypatch):
+ with pytest.raises(SystemExit, match="openviking-gateway init"):
+ load_config()
+ monkeypatch.setenv("OPENVIKING_GATEWAY_OPENVIKING_URL", "http://openviking:1933")
+ monkeypatch.setenv("OPENVIKING_GATEWAY_HOST", "0.0.0.0")
+ config = load_config()
+ assert (config.openviking_url, config.host) == ("http://openviking:1933", "0.0.0.0")
+
+
[email protected]("argv", [["--config", "{}", "init"], ["init", "--config", "{}"]])
+def test_init_accepts_config_before_or_after_the_command(tmp_path, monkeypatch, argv):
+ target = tmp_path / "custom.conf"
+ calls = []
+ monkeypatch.setattr(cli, "init", lambda path: calls.append(path) or 0)
+ argv = [str(target) if a == "{}" else a for a in argv]
+ monkeypatch.setattr(sys, "argv", ["openviking-gateway", *argv])
+ with pytest.raises(SystemExit) as exit_:
+ cli.main()
+ assert exit_.value.code == 0 and calls == [target]
+
+
+def answer(monkeypatch, *answers):
+ replies = iter(answers)
+ monkeypatch.setattr("builtins.input", lambda prompt="": next(replies))
+
+
+def test_init_writes_and_rewrites_gateway_conf(monkeypatch):
+ path = cli.USER_CONFIG
+ probes = []
+
+ async def probe(url):
+ probes.append(url)
+ if len(probes) == 1:
+ raise VikingError("openviking_unreachable")
+ return {"status": "ok", "auth_mode": "api_key", "version": "0.5.1"}
+
+ monkeypatch.setattr(cli, "probe", probe)
+ monkeypatch.setattr(sys.stdin, "isatty", lambda: True)
+ # Bad URL, unreachable URL (retry), reachable URL, host, default port, management key.
+ answer(monkeypatch, "ftp://ov", "http://down.test", "y", "https://OV.test/", "0.0.0.0", "", "y")
+ assert cli.init(path) == 0
+ saved = json.loads(path.read_text())
+ assert path.stat().st_mode & 0o777 == 0o600
+ assert probes == ["http://down.test", "https://ov.test"]
+ assert {k: saved[k] for k in ("openviking_url", "host", "port")} == {
+ "openviking_url": "https://ov.test",
+ "host": "0.0.0.0",
+ "port": 1935,
+ }
+ key = saved["management_key"]
+ assert key.startswith("ovgm_") and len(key) >= 37
+ assert StandaloneGatewayConfig.model_validate(saved).management_key == key
+
+ # A re-run keeps every value and secret on Enter, and fields init does not ask about.
+ path.write_text(json.dumps({**saved, "storage_path": "/data/gateway"}))
+ answer(monkeypatch, "", "", "", "", "")
+ assert cli.init(path) == 0
+ assert json.loads(path.read_text()) == {**saved, "storage_path": "/data/gateway"}
+
+ # Declining the management key removes it.
+ answer(monkeypatch, "", "", "", "n")
+ assert cli.init(path) == 0
+ assert "management_key" not in json.loads(path.read_text())
+
+
+def test_init_keeps_env_reference_and_stops_without_terminal(monkeypatch):
+ path = cli.USER_CONFIG
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(json.dumps({"openviking_url": "$OV_URL"}))
+ monkeypatch.setattr(cli, "probe", lambda url: pytest.fail("a $VAR URL is not probed"))
+ answer(monkeypatch, "", "", "", "n")
+ assert cli.init(path) == 0
+ assert json.loads(path.read_text())["openviking_url"] == "$OV_URL"
+
+ # Without a terminal every prompt returns its default; an invalid one must not loop.
+ path.write_text(json.dumps({"openviking_url": "ftp://ov"}))
+ monkeypatch.setattr(sys.stdin, "isatty", lambda: False)
+ answer(monkeypatch, "")
+ assert cli.init(path) == 1
+
+
+def test_main_loads_root_key_before_workers_start(monkeypatch):
+ loaded = []
+
+ class Provider:
+ async def get_root_key(self):
+ loaded.append(True)
+ return b"k"
+
+ class Encryptor:
+ provider = Provider()
+
+ async def check(config):
+ pass
+
+ monkeypatch.setattr(sys, "argv", ["openviking-gateway"])
+ monkeypatch.setenv("OPENVIKING_GATEWAY_OPENVIKING_URL", "http://openviking:1933")
+ monkeypatch.setattr(cli, "check_openviking", check)
+ monkeypatch.setattr(cli, "build_encryptor", lambda config: Encryptor())
+ monkeypatch.setattr("uvicorn.run", lambda *args, **kwargs: loaded.append("run"))
+ cli.main()
+ assert loaded == [True, "run"]
+
+
+def test_public_url_normalization():
+ config = StandaloneGatewayConfig(
+ openviking_url="https://API.VIKINGDB.CN-BEIJING.VOLCES.COM/openviking/"
+ )
+ assert config.openviking_url in PUBLIC_OPENVIKING_URLS
+ ipv6 = StandaloneGatewayConfig(openviking_url="http://[::1]:1933/")
+ assert ipv6.openviking_url == "http://[::1]:1933"
+ with pytest.raises(ValidationError):
+ StandaloneGatewayConfig(openviking_url="http://localhost:99999")
diff --git a/tests/gateway/test_management.py b/tests/gateway/test_management.py
new file mode 100644
index 000000000..bb6362810
--- /dev/null
+++ b/tests/gateway/test_management.py
@@ -0,0 +1,838 @@
+"""Identity, independent management authorization, and standalone hosting contracts."""
+
+import httpx
+import pytest
+from aiohttp import web
+
+from openviking_gateway.app import create_app, seed_defaults
+from openviking_gateway.config import StandaloneGatewayConfig
+from openviking_gateway.standalone import check_openviking, create_standalone_app
+from openviking_gateway.storage import digest
+
+P = "/admin"
+MANAGER = {"X-OpenViking-Gateway-Management-Key": "ovgm_" + "m" * 40}
+
+
+ "role,key",
+ [("user", "user-key"), ("admin", "admin-key"), ("root", "root"), ("dev", "")],
+)
[email protected]("managed", [False, True])
+async def test_permissions_matrix(running_gateway, role, key, managed):
+ app, client, _, _, _, _ = running_gateway
+ if managed:
+ app.state.config.management_key = MANAGER[next(iter(MANAGER))]
+ if role == "dev":
+ app.state.test_backend["auth_mode"] = "dev"
+ app.state.viking.identities.clear()
+ chat = await app.state.management.get("tenant", "upstreams", "chat")
+ await app.state.management.save("default", "upstreams", "chat", chat)
+ headers = {"X-API-Key": key} if key else {}
+ access = (await client.get(P + "/access", headers=headers)).json()
+ assert access["role"] == ("root" if role == "dev" else role)
+ assert access["can_write_objects"] is not managed
+ # Dev has a single default user, so there is nobody else to issue for.
+ assert access["can_issue_for_others"] is (role in {"admin", "root"})
+ response = await client.put(P + "/policies/matrix", headers=headers, json={"name": "matrix"})
+ assert response.status_code == (403 if managed else 200)
+ if managed:
+ response = await client.put(
+ P + "/policies/matrix", headers={**headers, **MANAGER}, json={"name": "matrix"}
+ )
+ assert response.status_code == 200
+ issue = await client.post(
+ P + "/keys",
+ headers=headers,
+ json={
+ "name": "self",
+ "openviking_key": "user-key",
+ "policy_id": "matrix",
+ "upstream_ids": ["chat"],
+ },
+ )
+ assert issue.status_code == 200, issue.text
+ keys = (await client.get(P + "/keys", headers=headers)).json()
+ assert issue.json()["id"] in [key["id"] for key in keys]
+
+
+async def test_management_key_alone_never_grants_ov_data_access(running_gateway):
+ app, client, _, _, _, _ = running_gateway
+ app.state.config.management_key = MANAGER[next(iter(MANAGER))]
+ app.state.test_backend["health_status"] = {"": 401}
+ path = P + "/policies/automation?account_id=separate"
+ assert (await client.put(path, headers=MANAGER, json={"name": "automation"})).status_code == 200
+ assert (await client.get(P + "/access?account_id=separate", headers=MANAGER)).json()[
+ "can_write_objects"
+ ]
+ for path in ("/logs", "/overview", "/keys"):
+ assert (await client.get(P + path, headers=MANAGER)).status_code == 401
+ assert (await client.post(P + "/keys", headers=MANAGER, json={})).status_code == 401
+ bad = await client.get(
+ P + "/access",
+ headers={"X-API-Key": "user-key", "X-OpenViking-Gateway-Management-Key": "wrong"},
+ )
+ assert bad.status_code == 401 and bad.json()["reason"] == "management_key_invalid"
+
+
+async def test_manager_cannot_elevate_user_scope(running_gateway):
+ app, client, _, _, _, _ = running_gateway
+ app.state.config.management_key = MANAGER[next(iter(MANAGER))]
+ headers = {"X-API-Key": "user-key", **MANAGER}
+ assert (
+ await client.put(P + "/policies/p?account_id=other", headers=headers, json={})
+ ).status_code == 200
+ assert (await client.get(P + "/logs?account_id=other", headers=headers)).status_code == 403
+ issued = await client.post(
+ P + "/keys",
+ headers=headers,
+ json={"name": "x", "user_id": "bob", "policy_id": "default", "upstream_ids": ["chat"]},
+ )
+ assert issued.status_code == 403
+
+
+async def test_readonly_secret_redaction_and_base_change(running_gateway):
+ app, client, admin, _, _, _ = running_gateway
+ old = await app.state.management.get("tenant", "upstreams", "chat")
+ await app.state.management.save(
+ "tenant", "upstreams", "chat", {**old, "headers": {"Secret-Header": "hidden"}}
+ )
+ app.state.config.management_key = MANAGER[next(iter(MANAGER))]
+ view = (await client.get(P + "/upstreams/chat", headers=admin)).json()
+ assert view["has_api_key"] and view["auth_mode"] == "managed"
+ assert not {"api_key", "headers", "header_names"} & view.keys()
+ changed = await client.put(
+ P + "/upstreams/chat",
+ headers={**admin, **MANAGER},
+ json={"name": "chat", "protocol": "chat", "base_url": "https://new.example/v1"},
+ )
+ assert changed.status_code == 200 and not changed.json()["has_api_key"]
+ assert not (await app.state.management.get("tenant", "upstreams", "chat"))["api_key"]
+
+
+async def test_user_keys_logs_and_revoke_are_scoped(running_gateway):
+ app, client, admin, alice, _, _ = running_gateway
+ minted = await client.post(
+ P + "/keys",
+ headers=admin,
+ json={"name": "bob", "user_id": "bob", "policy_id": "default", "upstream_ids": ["chat"]},
+ )
+ assert minted.status_code == 200 and minted.json()["user_id"] == "bob"
+ bob = minted.json()
+ for user in ("alice", "bob", None):
+ await app.state.management.log(
+ "tenant", {"kind": "user", "session": str(user)}, user_id=user
+ )
+ headers = {"X-API-Key": "user-key"}
+ assert [row["id"] for row in (await client.get(P + "/keys", headers=headers)).json()] == [
+ alice["id"]
+ ]
+ assert [row["session"] for row in (await client.get(P + "/logs", headers=headers)).json()] == [
+ "alice"
+ ]
+ assert (await client.get(P + "/overview", headers=headers)).json()["requests"] == 1
+ assert (await client.delete(P + "/keys/" + bob["id"], headers=headers)).status_code == 404
+ assert (await client.delete(P + "/users/bob/data", headers=headers)).status_code == 403
+ assert (await client.delete(P + "/keys/" + alice["id"], headers=headers)).status_code == 200
+
+
[email protected]("caller_key", ["admin-key", "root"])
+async def test_user_selection_and_unreadable_key(running_gateway, caller_key):
+ app, client, _, _, _, _ = running_gateway
+ headers = {"X-API-Key": caller_key}
+ payload = {"name": "bob", "user_id": "bob", "policy_id": "default", "upstream_ids": ["chat"]}
+ response = await client.post(P + "/keys?account_id=tenant", headers=headers, json=payload)
+ assert response.status_code == 200 and response.json()["user_id"] == "bob"
+ assert app.state.test_backend["users_calls"][-1][1] == caller_key
+ assert "&name=bob" in app.state.test_backend["users_calls"][-1][0]
+ # OpenViking omits api_key when it stores only a hash.
+ app.state.test_backend["users"] = [{"user_id": "bob", "role": "user"}]
+ response = await client.post(P + "/keys", headers=headers, json=payload)
+ assert response.status_code == 409 and response.json()["reason"] == "user_key_unreadable"
+ response = await client.post(
+ P + "/keys", headers=headers, json={**payload, "openviking_key": "bob-key"}
+ )
+ assert response.status_code == 200
+
+
+async def test_root_must_name_the_user_it_issues_for(running_gateway):
+ _, client, _, _, _, _ = running_gateway
+ payload = {"name": "k", "policy_id": "default", "upstream_ids": ["chat"]}
+ response = await client.post(
+ P + "/keys?account_id=tenant", headers={"X-API-Key": "root"}, json=payload
+ )
+ assert response.status_code == 400 and response.json()["reason"] == "user_required"
+
+
+async def test_root_reads_tools_with_an_account_key(running_gateway):
+ app, client, _, _, _, _ = running_gateway
+ response = await client.get(P + "/tools?account_id=tenant", headers={"X-API-Key": "root"})
+ assert response.status_code == 200 and response.json()
+ assert app.state.test_backend["tools_calls"] == ["user-key"]
+
+
+async def test_unavailable_openviking_skips_the_revocation_check(running_gateway):
+ app, client, _, key, _, _ = running_gateway
+ health_keys = []
+
+ async def handler(request):
+ if request.path == "/health":
+ health_keys.append(request.headers.get("X-API-Key"))
+
+ app.state.test_backend["handler"] = handler
+ app.state.viking.identities.clear()
+ app.state.viking.unavailable_reason = "openviking_unavailable"
+ response = await client.get("/v1/models", headers={"X-API-Key": key["key"]})
+ assert response.status_code == 200 and health_keys == []
+ # Any successful identify shows OV is back, before the next health probe.
+ await app.state.viking.identify("admin-key")
+ assert not app.state.viking.unavailable_reason
+
+
+async def test_revocation_removes_only_key_and_keeps_user_data(running_gateway):
+ app, client, admin, key, _, _ = running_gateway
+ await app.state.management.log("tenant", {"kind": "user"}, user_id="alice")
+ await client.post(
+ "/v1/chat/completions",
+ headers={"X-API-Key": key["key"]},
+ json={
+ "model": "model",
+ "messages": [{"role": "user", "content": "Remember the blue cluster"}],
+ },
+ )
+ scope = digest("tenant\0alice\0chat")
+ with app.state.store.connect() as c:
+ before = c.execute("SELECT count(*) FROM sessions WHERE scope=?", (scope,)).fetchone()[0]
+ assert before
+ app.state.test_backend["health_status"] = {"user-key": 401}
+ app.state.viking.identities.clear()
+ response = await client.get("/v1/models", headers={"X-API-Key": key["key"]})
+ assert response.status_code == 401 and "regenerated" in response.text
+ assert await app.state.management.get("tenant", "keys", key["id"]) is None
+ assert await app.state.management.logs("tenant", user_id="alice")
+ with app.state.store.connect() as c:
+ assert (
+ c.execute("SELECT count(*) FROM sessions WHERE scope=?", (scope,)).fetchone()[0]
+ == before
+ )
+ assert (await client.delete(P + "/users/alice/data", headers=admin)).status_code == 200
+ assert not await app.state.management.logs("tenant", user_id="alice")
+
+
[email protected]("failure", ["unreachable", "server_error", "identity_missing"])
+async def test_unconfirmed_revocation_keeps_key_and_serves(running_gateway, failure):
+ app, client, _, key, _, _ = running_gateway
+ backend = app.state.test_backend
+
+ async def handler(request):
+ if request.path == "/health" and request.headers.get("X-API-Key") == "user-key":
+ if failure == "server_error":
+ return web.json_response({}, status=503)
+ # OV swallows account-store errors and answers without an identity.
+ return web.json_response({"status": "ok", "auth_mode": "api_key"})
+
+ backend["handler"] = handler
+ if failure == "unreachable":
+ app.state.viking.base_url = "http://127.0.0.1:9"
+ app.state.viking.identities.clear()
+ response = await client.post(
+ "/v1/chat/completions",
+ headers={"X-API-Key": key["key"]},
+ json={"model": "model", "messages": [{"role": "user", "content": "hello"}]},
+ )
+ assert response.status_code == 200
+ assert await app.state.management.get("tenant", "keys", key["id"])
+ degradation = (await app.state.management.logs("tenant"))[0]["degradation"]
+ # With OV down, recall reports its own failure instead.
+ assert degradation == "revocation_check_unavailable" or failure == "unreachable"
+ # Nothing unconfirmed is cached: OV recovering takes effect on the next request.
+ assert not app.state.viking.identities.entries
+
+
+async def test_dev_mode_does_not_revoke_keys_of_named_users(running_gateway):
+ app, client, _, key, _, _ = running_gateway
+ app.state.test_backend["auth_mode"] = "dev"
+ app.state.viking.identities.clear()
+ response = await client.get("/v1/models", headers={"X-API-Key": key["key"]})
+ assert response.status_code == 200
+ assert await app.state.management.get("tenant", "keys", key["id"])
+
+
+async def test_health_401_is_reachable_and_recall_works(running_gateway):
+ app, client, _, key, _, _ = running_gateway
+ app.state.test_backend["health_status"] = {"": 401}
+ health = await app.state.viking.health(require_identity=False)
+ assert health["requires_authentication"] and not app.state.viking.unavailable_reason
+ response = await client.post(
+ "/v1/chat/completions",
+ headers={"X-API-Key": key["key"]},
+ json={
+ "model": "model",
+ "messages": [{"role": "user", "content": "Remember our deploy blue cluster"}],
+ },
+ )
+ assert response.status_code == 200
+ # The request log carries the key's user, so that user's own view finds it.
+ logs = await app.state.management.logs("tenant", user_id="alice")
+ assert any(row.get("recall_count", 0) for row in logs)
+
+
+async def test_dev_and_trusted_identity(running_gateway):
+ app, client, _, _, _, _ = running_gateway
+ app.state.test_backend["auth_mode"] = "dev"
+ app.state.viking.identities.clear()
+ identity = await app.state.viking.health()
+ assert identity["user_id"] == identity["account_id"] == "default"
+ access = (await client.get(P + "/access")).json()
+ assert access["role"] == "root" and access["can_write_objects"]
+ await client.put(P + "/policies/default", json={})
+ await client.put(
+ P + "/upstreams/local",
+ json={"name": "local", "protocol": "chat", "base_url": "http://localhost/v1"},
+ )
+ response = await client.post(
+ P + "/keys", json={"name": "dev", "policy_id": "default", "upstream_ids": ["local"]}
+ )
+ assert response.status_code == 200 and response.json()["user_id"] == "default"
+ app.state.test_backend["auth_mode"] = "trusted"
+ app.state.viking.identities.clear()
+ response = await client.get(P + "/access")
+ assert response.status_code == 403 and response.json()["reason"] == "trusted_mode_unsupported"
+
+
+ "path", ["/api/v1/admin/gateway/keys", "/arbitrary", "/api/v1/sessions", "/api/v3evil/models"]
+)
+async def test_data_catchall_is_narrow(running_gateway, path):
+ _, client, _, key, _, _ = running_gateway
+ assert (await client.get(path, headers={"X-API-Key": key["key"]})).status_code == 404
+
+
+ "status,body,ok,reason",
+ [
+ (200, {"data": []}, True, "passed"),
+ (200, {"error": {"code": "bad"}}, False, "upstream_key_rejected"),
+ (401, {}, False, "upstream_key_rejected"),
+ (403, {}, False, "upstream_key_rejected"),
+ (404, {}, True, "models_unavailable"),
+ (405, {}, True, "models_unavailable"),
+ (429, {}, True, "rate_limited"),
+ (503, {}, False, "upstream_unavailable"),
+ ],
+)
+async def test_upstream_test_status_contract(running_gateway, status, body, ok, reason):
+ app, client, admin, _, _, _ = running_gateway
+
+ async def handler(request):
+ if request.path == "/v1/models":
+ return web.json_response(body, status=status)
+
+ app.state.test_backend["handler"] = handler
+ result = (await client.post(P + "/upstreams/chat/test", headers=admin)).json()
+ assert (
+ result["ok"] is ok and result["reason"] == reason and result["url"].endswith("/v1/models")
+ )
+
+
+async def test_vlm_permissions_idempotency_and_confirmation(running_gateway):
+ app, client, admin, _, _, _ = running_gateway
+
+ async def source(account):
+ return {
+ "upstreams": [
+ {
+ "id": "vlm-plan",
+ "name": "Plan",
+ "protocol": "chat",
+ "base_url": "https://model.example/coding",
+ "coding_plan": True,
+ }
+ ],
+ "skipped": [{"id": "azure", "reason": "azure_unsupported"}],
+ }
+
+ app.state.vlm_source = source
+ assert not (await client.get(P + "/access", headers=admin)).json()["can_import_vlm"]
+ assert (await client.post(P + "/upstreams/import-vlm", headers=admin)).status_code == 403
+ root = {"X-API-Key": "root"}
+ for _ in range(2):
+ result = (await client.post(P + "/upstreams/import-vlm", headers=root)).json()
+ assert result["needs_confirmation"] == [{"id": "vlm-plan", "name": "Plan"}]
+ assert (
+ len(
+ [
+ u
+ for u in await app.state.management.list("tenant", "upstreams")
+ if u["id"] == "vlm-plan"
+ ]
+ )
+ == 1
+ )
+ app.state.config.management_key = MANAGER[next(iter(MANAGER))]
+ assert (await client.post(P + "/upstreams/import-vlm", headers=root)).status_code == 403
+ assert (
+ await client.post(P + "/upstreams/import-vlm?account_id=elsewhere", headers=MANAGER)
+ ).status_code == 200
+
+
+async def test_standalone_health_studio_and_readonly_forwarding(running_gateway, tmp_path):
+ upstream, _, _, _, _, _ = running_gateway
+ studio = tmp_path / "studio"
+ studio.mkdir()
+ (studio / "index.html").write_text("<html>Studio</html>")
+ config = StandaloneGatewayConfig(
+ storage_path=str(tmp_path / "standalone"), openviking_url=upstream.state.openviking_url
+ )
+ upstream.state.test_backend["health_status"] = {"stale-key": 401}
+ app = create_standalone_app(config, studio_dir=studio)
+ async with (
+ app.router.lifespan_context(app),
+ httpx.AsyncClient(
+ transport=httpx.ASGITransport(app=app), base_url="http://gateway"
+ ) as client,
+ ):
+ result = (await client.get("/health")).json()
+ assert (
+ result["service"] == "openviking-gateway"
+ and result["openviking_url"] == config.openviking_url
+ )
+ assert "role" not in result and result["auth_mode"] == "api_key"
+ assert (await client.get("/health", headers={"X-API-Key": "root"})).json()["role"] == "root"
+ stale = await client.get("/health", headers={"X-API-Key": "stale-key"})
+ assert stale.status_code == 200 and "role" not in stale.json()
+ access = await client.get("/gateway" + P + "/access", headers={"X-API-Key": "stale-key"})
+ assert access.status_code == 401 and access.json()["reason"] == "openviking_http_401"
+ assert (await client.get("/")).headers["location"] == "/studio/"
+ assert "Studio" in (await client.get("/studio/gateway/keys")).text
+ response = await client.get(
+ "/api/v1/admin/accounts/tenant/users?include_credentials=true",
+ headers={"X-API-Key": "admin-key"},
+ )
+ assert response.status_code == 200 and "api_key" not in response.json()["result"][0]
+ assert "include_credentials=false" in upstream.state.test_backend["users_calls"][-1][0]
+ assert (
+ await client.post("/api/v1/admin/accounts", headers={"X-API-Key": "root"})
+ ).status_code == 405
+ assert (await client.get("/api/v1/admin/accounts/tenant/secrets")).status_code == 404
+ guides = await client.get("/gateway" + P + "/guides", headers={"X-API-Key": "user-key"})
+ assert guides.json()["base_url"] == "http://gateway/gateway"
+ # The gateway lives only under /gateway; the root keeps Studio and the OV proxy.
+ assert (await client.get(P + "/access", headers={"X-API-Key": "root"})).status_code == 404
+
+
+async def test_base_change_drops_all_retained_secrets(running_gateway):
+ app, client, admin, _, _, _ = running_gateway
+ previous = await app.state.management.get("tenant", "upstreams", "chat")
+ previous["headers"] = {"Authorization": "Bearer private", "X-Private": "private"}
+ await app.state.management.save("tenant", "upstreams", "chat", previous)
+ response = await client.put(
+ P + "/upstreams/chat",
+ headers=admin,
+ json={
+ "name": "new",
+ "protocol": "chat",
+ "base_url": "https://other.example/v1",
+ "headers": {"Authorization": "", "New-Header": "explicit"},
+ },
+ )
+ assert response.status_code == 200
+ saved = await app.state.management.get("tenant", "upstreams", "chat")
+ assert saved["api_key"] == "" and saved["headers"] == {"New-Header": "explicit"}
+
+
+async def test_safe_validation_detail_and_typed_request_reason(running_gateway):
+ _, client, admin, key, _, _ = running_gateway
+ response = await client.put(
+ P + "/upstreams/bad",
+ headers=admin,
+ json={
+ "name": "bad",
+ "protocol": "anthropic",
+ "base_url": "https://example.com/v1",
+ "api_key": "never-echo-this-secret",
+ },
+ )
+ assert response.status_code == 422 and response.json()["reason"] == "invalid_configuration"
+ assert "/v1/messages" in response.json()["detail"] and "never-echo" not in response.text
+ response = await client.post(
+ P + "/keys/" + key["id"] + "/capture/reset",
+ headers=admin,
+ json={"session": "s", "protocol": "invalid"},
+ )
+ assert response.status_code == 422 and response.json()["reason"] == "invalid_configuration"
+
+
+async def test_revoked_key_keeps_pending_capture(running_gateway):
+ from conftest import make_due
+
+ app, client, admin, key, _, _ = running_gateway
+ await client.post(
+ "/v1/chat/completions",
+ headers={"X-API-Key": key["key"], "X-OpenViking-Session": "pending"},
+ json={
+ "model": "model",
+ "messages": [{"role": "user", "content": "Keep this unsaved conversation"}],
+ },
+ )
+ scope, session = digest("tenant\0alice\0chat"), digest("pending")
+ before = (await app.state.store.capture.get(scope, session)).value
+ assert before["pending"]
+ await client.delete(P + "/keys/" + key["id"], headers=admin)
+ await make_due(app.state.store)
+ assert await app.state.worker.once()
+ after = (await app.state.store.capture.get(scope, session)).value
+ assert after["pending"][0]["messages"] == before["pending"][0]["messages"]
+ assert after["error"]["reason"] == "gateway_key_revoked"
+ logs = await app.state.management.logs("tenant", user_id="alice")
+ assert logs[0]["capture_status"] == "paused"
+ assert logs[0]["capture_reason"] == "gateway_key_revoked"
+ overview = (await client.get(P + "/overview", headers=admin)).json()
+ assert overview["capture_issues"]["paused"] == 1
+
+
+async def test_identity_cache_accepts_root_does_not_cache_failures():
+ from openviking_gateway.client import VikingClient, VikingError
+
+ client = VikingClient(None, "http://unused", "0.4.16")
+ calls = []
+
+ async def request(method, path, key, **kwargs):
+ calls.append(key)
+ if key == "invalid":
+ raise VikingError("openviking_http_401", 401)
+ return {"role": "root", "account_id": "default", "user_id": "root", "version": "0.4.16"}
+
+ client.request = request
+ assert (await client.identify("root"))["role"] == "root"
+ assert (await client.identify("root"))["role"] == "root"
+ for _ in range(2):
+ with pytest.raises(VikingError):
+ await client.identify("invalid")
+ assert calls == ["root", "invalid", "invalid"]
+ assert "root" not in client.identities.entries
+ with pytest.raises(VikingError, match="root_key_not_allowed"):
+ await client.health("root")
+
+
+async def test_first_probe_does_not_block_startup(tmp_path, monkeypatch):
+ import asyncio
+
+ from openviking_gateway.client import VikingClient
+ from openviking_gateway.config import GatewayConfig
+
+ entered = asyncio.Event()
+
+ async def health(self, *args, **kwargs):
+ entered.set()
+ await asyncio.Event().wait()
+
+ monkeypatch.setattr(VikingClient, "health", health)
+ app = create_app(GatewayConfig(storage_path=str(tmp_path)), openviking_url="http://unused")
+ async with app.router.lifespan_context(app):
+ await asyncio.wait_for(entered.wait(), 1)
+ assert app.state.health == {"status": "starting"}
+
+
+async def test_standalone_dev_requires_loopback(tmp_path, monkeypatch):
+ from openviking_gateway.client import VikingClient
+
+ async def health(self, *args, **kwargs):
+ return {"auth_mode": "dev"}
+
+ monkeypatch.setattr(VikingClient, "health", health)
+ config = StandaloneGatewayConfig(
+ storage_path=str(tmp_path), openviking_url="http://localhost:1933", host="0.0.0.0"
+ )
+ with pytest.raises(ValueError, match="loopback"):
+ await check_openviking(config)
+
+
+async def test_connection_test_is_available_for_missing_key_and_blocked_plan(running_gateway):
+ app, client, admin, _, captured, _ = running_gateway
+ upstream = await app.state.management.get("tenant", "upstreams", "chat")
+ for change in ({"api_key": ""}, {"auth_mode": "passthrough"}):
+ await app.state.management.save("tenant", "upstreams", "chat", {**upstream, **change})
+ response = await client.post(P + "/upstreams/chat/test", headers=admin)
+ assert response.status_code == 200 and response.json()["reason"] == "upstream_key_missing"
+ assert not [path for path, _, _ in captured if path.endswith("/models")]
+ await app.state.management.save(
+ "tenant", "upstreams", "chat", {**upstream, "coding_plan": True, "allow_coding_plan": False}
+ )
+ response = await client.post(P + "/upstreams/chat/test", headers=admin)
+ assert response.status_code == 200 and response.json()["ok"]
+
+
[email protected]("mode", ["unavailable", "trusted", "unknown"])
+async def test_public_standalone_requires_confirmed_api_key_auth(tmp_path, monkeypatch, mode):
+ from openviking_gateway.client import VikingClient, VikingError
+
+ async def health(self, *args, **kwargs):
+ if mode == "unavailable":
+ raise VikingError("openviking_unavailable")
+ if mode == "trusted":
+ raise VikingError("trusted_mode_unsupported", 403)
+ return {"status": "ok"}
+
+ monkeypatch.setattr(VikingClient, "health", health)
+ config = StandaloneGatewayConfig(
+ storage_path=str(tmp_path), openviking_url="http://localhost:1933", host="0.0.0.0"
+ )
+ with pytest.raises(ValueError, match="trusted|successful synchronous probe"):
+ await check_openviking(config)
+
+
+async def test_public_standalone_accepts_auth_required_health(tmp_path, monkeypatch):
+ from openviking_gateway.client import VikingClient
+
+ async def health(self, *args, **kwargs):
+ return {"status": "ok", "auth_mode": "api_key", "requires_authentication": True}
+
+ monkeypatch.setattr(VikingClient, "health", health)
+ config = StandaloneGatewayConfig(
+ storage_path=str(tmp_path), openviking_url="http://localhost:1933", host="0.0.0.0"
+ )
+ assert (await check_openviking(config))["requires_authentication"]
+
+
+async def test_loopback_standalone_refuses_trusted_only(tmp_path, monkeypatch):
+ from openviking_gateway.client import VikingClient, VikingError
+
+ failure = VikingError("openviking_unavailable")
+
+ async def health(self, *args, **kwargs):
+ raise failure
+
+ monkeypatch.setattr(VikingClient, "health", health)
+ config = StandaloneGatewayConfig(storage_path=str(tmp_path), openviking_url="http://ov.test")
+ assert (await check_openviking(config))["reason"] == "openviking_unavailable"
+ failure = VikingError("trusted_mode_unsupported", 403)
+ with pytest.raises(ValueError, match="trusted"):
+ await check_openviking(config)
+
+
+async def test_non_ascii_management_header_is_rejected_cleanly(running_gateway):
+ app, client, _, _, _, _ = running_gateway
+ app.state.config.management_key = MANAGER[next(iter(MANAGER))]
+ response = await client.get(
+ P + "/access",
+ headers=[
+ (b"X-API-Key", b"user-key"),
+ (b"X-OpenViking-Gateway-Management-Key", b"wrong-\xff"),
+ ],
+ )
+ assert response.status_code == 401 and response.json()["reason"] == "management_key_invalid"
+
+
+async def test_revoked_capture_is_idle_until_ttl_expires(running_gateway):
+ import time
+
+ from conftest import make_due
+
+ app, client, admin, key, _, _ = running_gateway
+ headers = {"X-API-Key": key["key"], "X-OpenViking-Session": "ttl-pending"}
+ await client.post(
+ "/v1/chat/completions",
+ headers=headers,
+ json={
+ "model": "model",
+ "messages": [{"role": "user", "content": "Preserve until retention expires"}],
+ },
+ )
+ scope, session = digest("tenant\0alice\0chat"), digest("ttl-pending")
+ await client.delete(P + "/keys/" + key["id"], headers=admin)
+ await make_due(app.state.store)
+ assert await app.state.worker.once()
+ paused = (await app.state.store.capture.get(scope, session)).value
+ assert paused["pending"] and paused["error"]["retry_at"] is None
+ with app.state.store.connect() as connection:
+ touched = connection.execute(
+ "SELECT touched FROM sessions WHERE scope=? AND session=?", (scope, session)
+ ).fetchone()[0]
+ assert not await app.state.worker.once()
+ with app.state.store.connect() as connection:
+ assert (
+ connection.execute(
+ "SELECT touched FROM sessions WHERE scope=? AND session=?", (scope, session)
+ ).fetchone()[0]
+ == touched
+ )
+ await app.state.store.expire(time.time() + app.state.config.session_ttl_days * 86400)
+ assert not (await app.state.store.capture.get(scope, session)).value
+
+
+async def test_replacement_key_resumes_paused_capture(running_gateway):
+ from conftest import make_due
+
+ app, client, admin, key, _, writes = running_gateway
+ messages = [{"role": "user", "content": "Remember this retained conversation"}]
+ headers = {"X-API-Key": key["key"], "X-OpenViking-Session": "resume-paused"}
+ body = {"model": "model", "messages": messages}
+ assert (
+ await client.post("/v1/chat/completions", headers=headers, json=body)
+ ).status_code == 200
+ await client.delete(P + "/keys/" + key["id"], headers=admin)
+ await make_due(app.state.store)
+ assert await app.state.worker.once()
+ scope, session = digest("tenant\0alice\0chat"), digest("resume-paused")
+ assert (await app.state.store.capture.get(scope, session)).value["error"]["retry_at"] is None
+ replacement = (
+ await client.post(
+ P + "/keys",
+ headers=admin,
+ json={
+ "name": "replacement",
+ "user_id": "alice",
+ "policy_id": "default",
+ "upstream_ids": ["chat"],
+ },
+ )
+ ).json()
+ headers["X-API-Key"] = replacement["key"]
+ body["messages"] = [
+ *messages,
+ {"role": "assistant", "content": "hello"},
+ {"role": "user", "content": "Continue this conversation"},
+ ]
+ assert (
+ await client.post("/v1/chat/completions", headers=headers, json=body)
+ ).status_code == 200
+ state = (await app.state.store.capture.get(scope, session)).value
+ assert not state["error"] and state["credential_id"] == replacement["id"]
+ assert await app.state.worker.once()
+ assert writes
+
+
+async def test_version_error_includes_required_version(running_gateway):
+ app, client, admin, _, _, _ = running_gateway
+ app.state.config.min_server_version = app.state.viking.min_version = "99.0.0"
+ response = await client.post(
+ P + "/keys",
+ headers=admin,
+ json={
+ "name": "version",
+ "openviking_key": "user-key",
+ "policy_id": "default",
+ "upstream_ids": ["chat"],
+ },
+ )
+ assert response.status_code == 503 and response.json()["required_version"] == "99.0.0"
+
+
+async def test_vlm_reimport_refreshes_source_fields_and_keeps_edits(running_gateway):
+ app, client, _, _, _, _ = running_gateway
+ candidate = {
+ "id": "vlm-main",
+ "name": "main",
+ "protocol": "chat",
+ "base_url": "https://model.example/v1",
+ "api_key": "first",
+ "models": ["model-a"],
+ }
+
+ async def source(account):
+ return {
+ "upstreams": [
+ candidate,
+ {"id": "vlm-bad", "name": "bad", "protocol": "chat", "base_url": "ftp://x"},
+ ],
+ "skipped": [],
+ }
+
+ app.state.vlm_source = source
+ root = {"X-API-Key": "root"}
+ result = (await client.post(P + "/upstreams/import-vlm", headers=root)).json()
+ assert result["skipped"] == [{"id": "vlm-bad", "reason": "invalid_configuration"}]
+ previous = await app.state.management.get("tenant", "upstreams", "vlm-main")
+ edited = {**previous, "name": "renamed", "enabled": False, "priority": 5, "aliases": {"a": "b"}}
+ await app.state.management.save("tenant", "upstreams", "vlm-main", edited)
+ candidate.update(api_key="second", base_url="https://model.example/v2", models=["model-b"])
+ await client.post(P + "/upstreams/import-vlm", headers=root)
+ value = await app.state.management.get("tenant", "upstreams", "vlm-main")
+ assert value["api_key"] == "second" and value["base_url"] == "https://model.example/v2"
+ assert value["name"] == "renamed" and value["enabled"] is False and value["priority"] == 5
+ assert value["models"] == ["model-a"] and value["aliases"] == {"a": "b"}
+
+
+async def test_seed_defaults_is_idempotent(running_gateway):
+ app, _, _, _, _, _ = running_gateway
+ calls = []
+
+ async def source(account):
+ calls.append(account)
+ return {
+ "upstreams": [
+ {"id": "vlm-x", "name": "x", "protocol": "chat", "base_url": "https://x.test"}
+ ]
+ }
+
+ app.state.vlm_source = source
+ for _ in range(2):
+ await seed_defaults(app, "fresh")
+ assert calls == ["fresh"]
+ assert [u["id"] for u in await app.state.management.list("fresh", "upstreams")] == ["vlm-x"]
+ assert await app.state.management.get("fresh", "policies", "default")
+
+
[email protected]("base_url", [5, None, ["https://x.test"]])
+async def test_non_string_base_url_is_invalid_configuration(running_gateway, base_url):
+ _, client, admin, _, _, _ = running_gateway
+ response = await client.put(
+ P + "/upstreams/chat",
+ headers=admin,
+ json={"name": "chat", "protocol": "chat", "base_url": base_url},
+ )
+ assert response.status_code == 422 and response.json()["reason"] == "invalid_configuration"
+
+
+async def test_keys_are_immutable_and_errors_explain_themselves(running_gateway):
+ app, client, admin, key, _, _ = running_gateway
+ response = await client.put(P + "/keys/" + key["id"], headers=admin, json={})
+ assert response.status_code == 405 and response.json()["reason"] == "gateway_http_405"
+ response = await client.get(P + "/upstreams/missing", headers=admin)
+ body = response.json()
+ assert response.status_code == 404 and body["reason"] == "not_found"
+ assert body["detail"] != body["reason"]
+ app.state.test_backend["health_status"] = {"stale-key": 401}
+ response = await client.get(P + "/keys", headers={"X-API-Key": "stale-key"})
+ assert response.json() == {
+ "reason": "openviking_http_401",
+ "detail": "OpenViking rejected the API key.",
+ }
+
+
+async def test_degraded_probe_backs_off_until_success(tmp_path, monkeypatch):
+ import asyncio
+ import time
+ from types import SimpleNamespace
+
+ from openviking_gateway import app as module
+ from openviking_gateway.client import VikingClient, VikingError
+ from openviking_gateway.config import GatewayConfig
+
+ clock, probes, results = [0.0], [], [False, False, True, False, False, False, False]
+
+ def monotonic():
+ clock[0] += 0.125
+ return clock[0]
+
+ async def health(self, *args, **kwargs):
+ probes.append(clock[0])
+ if results and not results.pop(0):
+ raise VikingError("openviking_unavailable")
+ return {"status": "ok"}
+
+ async def once():
+ await asyncio.sleep(0)
+ return True
+
+ monkeypatch.setattr(VikingClient, "health", health)
+ monkeypatch.setattr(module, "time", SimpleNamespace(monotonic=monotonic, time=time.time))
+ config = GatewayConfig(storage_path=str(tmp_path), health_interval_seconds=4)
+ app = create_app(config, openviking_url="http://unused")
+ async with app.router.lifespan_context(app):
+ app.state.worker.once = once
+ while results:
+ await asyncio.sleep(0)
+ gaps = [round(b - a) for a, b in zip(probes, probes[1:], strict=False)]
+ # Every second until OV first answers; later outages back off 1, 2, 4 capped at the interval.
+ assert gaps[:6] == [1, 1, 4, 1, 2, 4]
diff --git a/tests/gateway/test_reasoning_replay.py b/tests/gateway/test_reasoning_replay.py
index c0d8f3edc..5404ffcc0 100644
--- a/tests/gateway/test_reasoning_replay.py
+++ b/tests/gateway/test_reasoning_replay.py
@@ -103,7 +103,7 @@ async def chat_turns(client, key, session, turns, streaming, keep_reasoning=Fals
@pytest.mark.parametrize("streaming", [False, True])
async def test_chat_restores_dropped_reasoning_byte_for_byte(running_gateway, streaming):
app, client, admin, key, captured, _ = running_gateway
- await configure_chat(client, admin, base_url=str(app.state.config.openviking_url))
+ await configure_chat(client, admin, base_url=app.state.openviking_url + "/v1")
requests = []
reasoning_backend(app, requests)
await chat_turns(client, key, "deepseek", ["One?", "Two?", "Three?"], streaming)
@@ -121,7 +121,7 @@ async def test_chat_restores_dropped_reasoning_byte_for_byte(running_gateway, st
async def test_chat_keeps_reasoning_the_client_sent(running_gateway):
app, client, admin, key, _, _ = running_gateway
- await configure_chat(client, admin, base_url=str(app.state.config.openviking_url))
+ await configure_chat(client, admin, base_url=app.state.openviking_url + "/v1")
requests = []
reasoning_backend(app, requests)
await chat_turns(client, key, "kept", ["One?", "Two?"], False, keep_reasoning=True)
@@ -130,7 +130,7 @@ async def test_chat_keeps_reasoning_the_client_sent(running_gateway):
async def test_option_off_restores_nothing_and_keeps_the_deepseek_gate(running_gateway):
app, client, admin, key, _, _ = running_gateway
- url = str(app.state.config.openviking_url)
+ url = app.state.openviking_url + "/v1"
await enable_tools(client, admin)
requests = []
reasoning_backend(app, requests)
@@ -147,7 +147,7 @@ async def test_option_off_restores_nothing_and_keeps_the_deepseek_gate(running_g
async def test_generic_upstream_restores_nothing(running_gateway):
app, client, admin, key, _, _ = running_gateway
- url = str(app.state.config.openviking_url)
+ url = app.state.openviking_url + "/v1"
await configure_chat(client, admin, base_url=url, vendor="generic")
requests = []
reasoning_backend(app, requests)
diff --git a/tests/gateway/test_recall_notice.py b/tests/gateway/test_recall_notice.py
index 5402a96f1..94bbb5958 100644
--- a/tests/gateway/test_recall_notice.py
+++ b/tests/gateway/test_recall_notice.py
@@ -495,7 +495,9 @@ async def test_anthropic_reasoning_restore_ignores_the_notice(running_gateway):
if k not in {"id", "revision", "has_api_key", "header_names", "account"}
}
response = await client.put(
- "/admin/upstreams/anthropic", headers=admin, json={**payload, "replay_reasoning": True}
+ "/admin/upstreams/anthropic",
+ headers=admin,
+ json={**payload, "replay_reasoning": True},
)
assert response.status_code == 200, response.text
requests, upstream = [], []
diff --git a/tests/gateway/test_review_regressions.py b/tests/gateway/test_review_regressions.py
index e4fdbf054..15a50fa66 100644
--- a/tests/gateway/test_review_regressions.py
+++ b/tests/gateway/test_review_regressions.py
@@ -300,14 +300,19 @@ async def test_hot_read_ignores_unrelated_operational_documents(
kernel, store, _, _ = setup_kernel
policy.update(recall=False)
p = await prepare(kernel, credential, policy, history(1)[:1])
- with store.connect() as c:
- c.executemany(
- "INSERT INTO state(scope,key,value,version,touched) VALUES (?,?,?,1,?)",
- [
- (p.scope, f"tool:unrelated-{i}", store.encode({"content": "old"}), time.time())
- for i in range(1500)
- ],
- )
+
+ def insert():
+ # Encoding runs the encryptor on the event loop, so it must happen off the loop thread.
+ with store.connect() as c:
+ c.executemany(
+ "INSERT INTO state(scope,key,value,version,touched) VALUES (?,?,?,1,?)",
+ [
+ (p.scope, f"tool:unrelated-{i}", store.encode({"content": "old"}), time.time())
+ for i in range(1500)
+ ],
+ )
+
+ await store.run(insert, write=True)
decoded = []
original = store.decode
diff --git a/tests/gateway/test_storage_migration.py b/tests/gateway/test_storage_migration.py
new file mode 100644
index 000000000..fc427dabb
--- /dev/null
+++ b/tests/gateway/test_storage_migration.py
@@ -0,0 +1,317 @@
+"""Upgrade real v5 SQLite layouts, re-encrypt their values and keep tenant boundaries."""
+
+import asyncio
+import sqlite3
+import time
+
+import orjson
+import pytest
+from conftest import local_encryptor
+from cryptography.fernet import Fernet, InvalidToken
+
+from openviking.crypto.encryptor import MAGIC
+from openviking_gateway.storage import (
+ ManagementStore,
+ SQLiteKernelStore,
+ delete_account_data,
+ delete_user_data,
+ digest,
+)
+
+UPSTREAMS = [
+ ("openai", "chat", "https://api.openai.com", "https://api.openai.com/v1"),
+ ("ark", "chat", "https://ark.test", "https://ark.test/api/v3"),
+ ("byteplus", "responses", "https://byteplus.test", "https://byteplus.test/api/v3"),
+ ("ark", "anthropic", "https://ark.test", "https://ark.test/api/compatible"),
+ ("byteplus", "anthropic", "https://byteplus.test", "https://byteplus.test/api/compatible"),
+ ("anthropic", "anthropic", "https://anthropic.test/v1", "https://anthropic.test"),
+ ("ark", "anthropic", "https://ark.test/api/compatible/v1", "https://ark.test/api/compatible"),
+ # v5 requested base + /v1/...; this GLM base was already wrong and stays so.
+ ("generic", "chat", "https://glm.test/api/paas/v4", "https://glm.test/api/paas/v4"),
+ ("generic", "chat", "https://openrouter.ai/api", "https://openrouter.ai/api/v1"),
+ ("generic", "responses", "https://api.groq.com/openai", "https://api.groq.com/openai/v1"),
+ ("openai", "chat", "https://proxy.test/v1", "https://proxy.test/v1"),
+ ("ark", "chat", "https://ark.test/custom", "https://ark.test/custom"),
+ ("generic", "anthropic", "https://anthropic.test", "https://anthropic.test"),
+]
+# The v0.5.0 layouts, every value Fernet-encrypted with the gateway's own key.
+V5_MANAGEMENT = """
+ PRAGMA user_version=5;
+ CREATE TABLE objects (account TEXT,kind TEXT,id TEXT,revision INTEGER,value BLOB,
+ PRIMARY KEY(account,kind,id));
+ CREATE INDEX object_identity ON objects(kind,id);
+ CREATE TABLE request_logs (id INTEGER PRIMARY KEY,account TEXT,time REAL,value BLOB);
+ CREATE INDEX log_account ON request_logs(account,time);
+ CREATE TABLE object_expiry (account TEXT,kind TEXT,id TEXT,expires REAL,
+ PRIMARY KEY(account,kind,id));
+"""
+V5_KERNEL = """
+ PRAGMA user_version=5;
+ CREATE TABLE sessions (scope TEXT,session TEXT,touched REAL NOT NULL,
+ PRIMARY KEY(scope,session));
+ CREATE TABLE replay (scope TEXT,session TEXT,kind TEXT,anchor TEXT,value BLOB NOT NULL,
+ PRIMARY KEY(scope,session,kind,anchor),
+ FOREIGN KEY(scope,session) REFERENCES sessions ON DELETE CASCADE);
+ CREATE TABLE state (scope TEXT,key TEXT,value BLOB NOT NULL,version INTEGER NOT NULL,
+ touched REAL NOT NULL, PRIMARY KEY(scope,key));
+ CREATE TABLE capture (scope TEXT,session TEXT,value BLOB NOT NULL,version INTEGER NOT NULL,
+ ready REAL,lease REAL NOT NULL DEFAULT 0,owner TEXT,PRIMARY KEY(scope,session),
+ FOREIGN KEY(scope,session) REFERENCES sessions ON DELETE CASCADE);
+ CREATE TABLE deleted_scopes (scope TEXT PRIMARY KEY);
+"""
+ENCRYPTED_TABLES = {
+ "management.sqlite3": ("objects", "request_logs"),
+ "kernel.sqlite3": ("replay", "state", "capture"),
+}
+
+
[email protected](autouse=True)
+def no_legacy_key_environment(monkeypatch):
+ monkeypatch.delenv("OPENVIKING_GATEWAY_ENCRYPTION_KEY", raising=False)
+
+
+def v5_storage(tmp_path):
+ """A v0.5.0 storage directory whose key sits in encryption.key."""
+ key = Fernet.generate_key()
+ (tmp_path / "encryption.key").write_bytes(key + b"\n")
+ cipher = Fernet(key)
+
+ def seal(value):
+ return cipher.encrypt(orjson.dumps(value))
+
+ with sqlite3.connect(tmp_path / "management.sqlite3") as c:
+ c.executescript(V5_MANAGEMENT)
+ for index, (vendor, protocol, base, _) in enumerate(UPSTREAMS):
+ value = {"vendor": vendor, "protocol": protocol, "base_url": base}
+ c.execute(
+ "INSERT INTO objects VALUES ('a','upstreams',?,7,?)",
+ (str(index), seal({**value, "api_key": "kept-secret"})),
+ )
+ c.execute(
+ "INSERT INTO objects VALUES ('a','keys',?,1,?)",
+ (digest("gateway-key"), seal({"user_id": "alice", "openviking_key": "ov-secret"})),
+ )
+ c.execute(
+ "INSERT INTO request_logs(account,time,value) VALUES ('a',?,?)",
+ (time.time(), seal({"request_id": "old"})),
+ )
+ with sqlite3.connect(tmp_path / "kernel.sqlite3") as c:
+ c.executescript(V5_KERNEL)
+ c.execute("INSERT INTO sessions VALUES ('scope','session',1000)")
+ c.execute(
+ "INSERT INTO replay VALUES ('scope','session','injection','anchor',?)",
+ (seal({"text": "private memory"}),),
+ )
+ c.execute("INSERT INTO state VALUES ('scope','key',?,3,1000)", (seal({"budget": 9}),))
+ c.execute(
+ "INSERT INTO capture VALUES ('scope','session',?,4,NULL,0,NULL)",
+ (seal({"pending": ["turn"]}),),
+ )
+ return tmp_path, key
+
+
+def raw_values(directory):
+ values = []
+ for name, tables in ENCRYPTED_TABLES.items():
+ with sqlite3.connect(directory / name) as c:
+ for table in tables:
+ values += [row[0] for row in c.execute(f"SELECT value FROM {table}")]
+ return values
+
+
+def user_version(path):
+ with sqlite3.connect(path) as c:
+ return c.execute("PRAGMA user_version").fetchone()[0]
+
+
+def migrated(values):
+ return {v["id"]: (v["base_url"], v["revision"]) for v in values}
+
+
+EXPECTED = {str(i): (r[3], 7 + (r[2] != r[3])) for i, r in enumerate(UPSTREAMS)}
+
+
[email protected]("encrypted", [True, False], ids=["ov-encryption", "plaintext"])
+async def test_v5_migration_reencodes_every_table(v5_storage, encrypted):
+ directory, _ = v5_storage
+ encryptor = local_encryptor(directory / "master.key") if encrypted else None
+ management = ManagementStore(directory / "management.sqlite3", encryptor)
+ kernel = SQLiteKernelStore(directory / "kernel.sqlite3", encryptor)
+ try:
+ await management.initialize()
+ await kernel.initialize()
+ values = await management.list("a", "upstreams")
+ assert migrated(values) == EXPECTED
+ assert all(v["api_key"] == "kept-secret" for v in values)
+ assert (await management.authenticate("gateway-key"))["openviking_key"] == "ov-secret"
+ assert [log["request_id"] for log in await management.logs("a")] == ["old"]
+ assert await kernel.replay.read("scope", "session", ["anchor"]) == {
+ ("injection", "anchor"): {"text": "private memory"}
+ }
+ state = (await kernel.state.read("scope", ["key"]))["key"]
+ assert (state.value, state.version) == ({"budget": 9}, 3)
+ capture = await kernel.capture.get("scope", "session")
+ assert (capture.value, capture.version) == ({"pending": ["turn"]}, 4)
+ # A second start finds v6 and leaves the data alone.
+ await management.initialize()
+ await kernel.initialize()
+ assert await management.list("a", "upstreams") == values
+ finally:
+ management.close()
+ kernel.close()
+ raw = raw_values(directory)
+ # Upstreams, the gateway key and the log, then replay, state and capture.
+ assert len(raw) == len(UPSTREAMS) + 2 + 3
+ if encrypted:
+ assert all(value.startswith(MAGIC) for value in raw)
+ else:
+ assert [orjson.loads(value) for value in raw]
+ assert user_version(directory / "management.sqlite3") == 6
+ with sqlite3.connect(directory / "management.sqlite3") as c:
+ columns = [r[2] for r in c.execute("PRAGMA index_info(log_account_user)")]
+ assert columns == ["account", "user", "time"]
+
+
+async def test_legacy_key_from_environment(v5_storage, monkeypatch):
+ directory, key = v5_storage
+ (directory / "encryption.key").unlink()
+ monkeypatch.setenv("OPENVIKING_GATEWAY_ENCRYPTION_KEY", key.decode())
+ kernel = SQLiteKernelStore(directory / "kernel.sqlite3")
+ try:
+ await kernel.initialize()
+ assert (await kernel.state.read("scope", ["key"]))["key"].value == {"budget": 9}
+ finally:
+ kernel.close()
+
+
[email protected]("name", list(ENCRYPTED_TABLES))
+async def test_missing_legacy_key_refuses_startup(v5_storage, name):
+ directory, _ = v5_storage
+ (directory / "encryption.key").unlink()
+ store = (ManagementStore if name == "management.sqlite3" else SQLiteKernelStore)(
+ directory / name
+ )
+ try:
+ with pytest.raises(ValueError, match="OPENVIKING_GATEWAY_ENCRYPTION_KEY") as error:
+ await store.initialize()
+ assert "encryption.key" in str(error.value)
+ finally:
+ store.close()
+ assert user_version(directory / name) == 5
+
+
+async def test_empty_v5_stores_need_no_legacy_key(tmp_path):
+ for name, layout in (("management.sqlite3", V5_MANAGEMENT), ("kernel.sqlite3", V5_KERNEL)):
+ with sqlite3.connect(tmp_path / name) as c:
+ c.executescript(layout)
+ management = ManagementStore(tmp_path / "management.sqlite3")
+ kernel = SQLiteKernelStore(tmp_path / "kernel.sqlite3")
+ try:
+ await management.initialize()
+ await kernel.initialize()
+ finally:
+ management.close()
+ kernel.close()
+ assert user_version(tmp_path / "kernel.sqlite3") == 6
+
+
+async def test_failed_migration_rolls_back_schema_and_objects(v5_storage):
+ directory, key = v5_storage
+ path = directory / "management.sqlite3"
+ with sqlite3.connect(path) as c:
+ c.execute("UPDATE objects SET value=? WHERE id='8'", (b"corrupt",))
+ store = ManagementStore(path)
+ try:
+ with pytest.raises(InvalidToken):
+ await store.initialize()
+ finally:
+ store.close()
+ assert user_version(path) == 5
+ with sqlite3.connect(path) as c:
+ assert "user" not in [r[1] for r in c.execute("PRAGMA table_info(request_logs)")]
+ value, revision = c.execute("SELECT value,revision FROM objects WHERE id='0'").fetchone()
+ assert orjson.loads(Fernet(key).decrypt(value))["base_url"] == "https://api.openai.com"
+ assert revision == 7
+
+
+async def test_workers_can_migrate_same_v5_database(v5_storage):
+ directory, _ = v5_storage
+ encryptor = local_encryptor(directory / "master.key")
+ workers = [ManagementStore(directory / "management.sqlite3", encryptor) for _ in range(6)]
+ try:
+ await asyncio.gather(*(worker.initialize() for worker in workers))
+ for worker in workers:
+ assert migrated(await worker.list("a", "upstreams")) == EXPECTED
+ finally:
+ for worker in workers:
+ worker.close()
+
+
+async def test_enabling_encryption_later_keeps_plaintext_readable(tmp_path):
+ path = tmp_path / "management.sqlite3"
+ plain = ManagementStore(path)
+ try:
+ await plain.initialize()
+ await plain.save("a", "upstreams", "old", {"name": "old"})
+ finally:
+ plain.close()
+ encrypted = ManagementStore(path, local_encryptor(tmp_path / "master.key"))
+ try:
+ await encrypted.initialize()
+ await encrypted.save("a", "upstreams", "new", {"name": "new"})
+ assert [v["name"] for v in await encrypted.list("a", "upstreams")] == ["new", "old"]
+ finally:
+ encrypted.close()
+ with sqlite3.connect(path) as c:
+ rows = dict(c.execute("SELECT id,value FROM objects"))
+ assert rows["new"].startswith(MAGIC) and orjson.loads(rows["old"]) == {"name": "old"}
+ # Disabling encryption again cannot silently read the encrypted rows.
+ plain = ManagementStore(path)
+ try:
+ with pytest.raises(RuntimeError, match="encrypted"):
+ await plain.list("a", "upstreams")
+ finally:
+ plain.close()
+
+
+async def test_user_filtering_and_deletion_preserves_other_users(tmp_path):
+ management = ManagementStore(tmp_path / "management.sqlite3")
+ kernel = SQLiteKernelStore(tmp_path / "kernel.sqlite3")
+ try:
+ await management.initialize()
+ await kernel.initialize()
+ await management.save("a", "upstreams", "shared", {"name": "shared"})
+ for account, user in [("a", "alice"), ("a", "bob"), ("b", "alice")]:
+ await management.save(account, "keys", user, {"user_id": user})
+ await management.save(account, "users", user, {"user_id": user})
+ await management.save(account, "responses", user, {"user_id": user}, ttl=3600)
+ await management.log(account, {"request_id": user}, user_id=user)
+ for protocol in ("chat", "responses", "anthropic"):
+ scope = digest(account + "\0" + user + "\0" + protocol)
+ with kernel.connect() as connection:
+ kernel.touch(connection, scope, "session")
+ with management.connect() as connection:
+ users = [r[0] for r in connection.execute("SELECT user FROM request_logs ORDER BY id")]
+ assert users == ["alice", "bob", "alice"]
+ assert len(await management.list("a", "keys", user_id="alice")) == 1
+ assert len(await management.logs("a", user_id="alice")) == 1
+ await delete_user_data(management, kernel, "a", "alice")
+ assert await management.list("a", "keys", user_id="alice") == []
+ assert await management.logs("a", user_id="alice") == []
+ assert await management.get("a", "responses", "alice") is None
+ assert len(await management.logs("a")) == 1
+ assert len(await management.logs("b")) == 1
+ assert len(await management.list("a", "upstreams")) == 1
+ with kernel.connect() as connection:
+ assert connection.execute("SELECT count(*) FROM sessions").fetchone()[0] == 6
+ await delete_account_data(management, kernel, "a")
+ assert await management.list("a", "upstreams") == []
+ assert await management.logs("a") == []
+ assert len(await management.list("b", "keys")) == 1
+ with kernel.connect() as connection:
+ assert connection.execute("SELECT count(*) FROM sessions").fetchone()[0] == 3
+ finally:
+ management.close()
+ kernel.close()
diff --git a/tests/gateway/test_storage_ports.py b/tests/gateway/test_storage_ports.py
index 27989a1e0..1cfa0b62f 100644
--- a/tests/gateway/test_storage_ports.py
+++ b/tests/gateway/test_storage_ports.py
@@ -130,7 +130,7 @@ async def test_kernel_and_capture_work_with_kv_ports(credential, protocol):
async def get(self, *_):
return credential
- async def log(self, *_):
+ async def log(self, *_, **__):
pass
worker = CaptureWorker(ports, Management(), viking)
@@ -271,7 +271,8 @@ async def test_batched_reads_keep_scope_isolation_and_handle_cancellation(
async def test_corrupt_record_does_not_fail_other_reads_in_batch(setup_kernel):
- from cryptography.fernet import InvalidToken
+ from openviking.crypto import CorruptedCiphertextError
+ from openviking.crypto.encryptor import MAGIC
_, store, _, _ = setup_kernel
for scope in ("damaged", "healthy"):
@@ -280,7 +281,8 @@ async def test_corrupt_record_does_not_fail_other_reads_in_batch(setup_kernel):
def corrupt():
with store.connect() as connection:
connection.execute(
- "UPDATE replay SET value=? WHERE scope=?", (b"invalid ciphertext", "damaged")
+ "UPDATE replay SET value=? WHERE scope=?",
+ (MAGIC + b"invalid ciphertext", "damaged"),
)
await store.run(corrupt, write=True)
@@ -289,7 +291,7 @@ async def test_corrupt_record_does_not_fail_other_reads_in_batch(setup_kernel):
store.load("healthy", "session", [""]),
return_exceptions=True,
)
- assert isinstance(damaged, InvalidToken)
+ assert isinstance(damaged, CorruptedCiphertextError)
assert healthy[0][K.ROOT, ""] == {"scope": "healthy"}
diff --git a/tests/gateway/test_tools.py b/tests/gateway/test_tools.py
index b47c3cfc8..1caad03df 100644
--- a/tests/gateway/test_tools.py
+++ b/tests/gateway/test_tools.py
@@ -10,14 +10,12 @@ from conftest import MCP_TOOLS, mcp_tool
from openviking_gateway.capture import capture_messages
from openviking_gateway.models import Policy, Upstream
from openviking_gateway.notices import TOOL_NOTICE, tool_tail
-from openviking_gateway.proxy import upstream_url
from openviking_gateway.storage import SQLiteKernelStore
from openviking_gateway.tool_catalog import notice_head, select_tools, tool_block_reason
from openviking_gateway.tool_executor import ToolExecutor, attachment_bytes, attachments
from openviking_gateway.tool_loop import HiddenToolLoop
from openviking_gateway.tool_protocols import ResponseCapture, hidden_chain, tool_protocol
from openviking_gateway.tool_protocols.common import sse
-from openviking_gateway.vendors import ark_url
@pytest.mark.parametrize(
@@ -432,39 +430,6 @@ def test_omitted_hidden_history_drops_tool_notices(protocol):
]
- "base,path,expected",
- [
- ("https://ark/api/v3", "/v1/chat/completions", "https://ark/api/v3/chat/completions"),
- ("https://ark", "/v1/responses/resp_1", "https://ark/api/v3/responses/resp_1"),
- ("https://ark/api/compatible/v1", "/v1/messages", "https://ark/api/compatible/v1/messages"),
- ],
-)
-def test_ark_base_paths(base, path, expected):
- assert ark_url({"base_url": base}, path) == expected
-
-
[email protected]("vendor", ["ark", "byteplus"])
- "base,path,expected",
- [
- ("https://ark", "/v1/chat/completions", "https://ark/api/v3/chat/completions"),
- ("https://ark", "/v1/responses", "https://ark/api/v3/responses"),
- ("https://ark", "/v1/messages", "https://ark/api/compatible/v1/messages"),
- (
- "https://ark",
- "/v1/messages/count_tokens",
- "https://ark/api/compatible/v1/messages/count_tokens",
- ),
- ("https://ark", "/v1/models", "https://ark/api/v3/models"),
- ("https://ark/api/v3", "/v1/responses", "https://ark/api/v3/responses"),
- ("https://ark/api/compatible/v1", "/v1/messages", "https://ark/api/compatible/v1/messages"),
- ],
-)
-def test_ark_vendors_share_upstream_paths(vendor, base, path, expected):
- assert upstream_url({"base_url": base, "vendor": vendor}, path) == expected
-
-
@pytest.mark.parametrize("json_response", [False, True])
async def test_real_stateless_fastmcp_transport(json_response):
import socket
diff --git a/tests/gateway/test_upstream_urls.py b/tests/gateway/test_upstream_urls.py
new file mode 100644
index 000000000..006c6e8f6
--- /dev/null
+++ b/tests/gateway/test_upstream_urls.py
@@ -0,0 +1,58 @@
+"""Shared SDK URL vectors and protocol authentication."""
+
+import json
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from pydantic import ValidationError
+
+from openviking_gateway.models import Upstream
+from openviking_gateway.proxy import ProxyRequest, upstream_headers, upstream_url
+
+VECTORS = json.loads(
+ (Path(__file__).parents[1] / "fixtures/gateway_upstream_urls.json").read_text()
+)
+
+
[email protected]("vector", VECTORS, ids=lambda value: value["name"])
+def test_upstream_url_vectors(vector):
+ upstream = {"protocol": vector["protocol"], "base_url": vector["base_url"]}
+ assert upstream_url(upstream, vector["path"]) == vector["expected"]
+
+
[email protected]("prefix", ["api/v3", "api/compatible/v1", "v1"])
+ "suffix", ["embeddings", "models", "responses/id/cancel", "messages/count_tokens"]
+)
+def test_all_client_prefixes_normalize(prefix, suffix):
+ app = SimpleNamespace(state=SimpleNamespace(config=None, store=None, management=None))
+ request = ProxyRequest(app, None, prefix + "/" + suffix, {})
+ assert request.path == "/v1/" + suffix
+
+
[email protected]("base", ["https://example.test/v1", "https://example.test/api/v1/"])
+def test_anthropic_base_rejects_v1_suffix(base):
+ with pytest.raises(ValidationError, match="appends /v1/messages"):
+ Upstream(name="test", protocol="anthropic", base_url=base)
+
+
[email protected]("protocol", ["chat", "responses", "anthropic"])
+def test_upstream_auth_headers(protocol):
+ headers = upstream_headers(
+ {
+ "protocol": protocol,
+ "api_key": "secret",
+ "headers": {"authorization": "wrong", "x-api-key": "gateway-plan-key"},
+ },
+ {
+ "authorization": "Bearer ovgw_fake",
+ "x-api-key": "wrong",
+ "anthropic-version": "2023-06-01",
+ },
+ )
+ assert headers["Authorization"] == "Bearer secret"
+ assert "authorization" not in headers
+ # A configured x-api-key reaches Bearer upstreams; Anthropic's own header replaces it.
+ assert headers.get("x-api-key") == ("secret" if protocol == "anthropic" else "gateway-plan-key")
+ assert headers["anthropic-version"] == "2023-06-01"
diff --git a/tests/gateway/test_windows.py b/tests/gateway/test_windows.py
index 2890d72e9..d302ceaed 100644
--- a/tests/gateway/test_windows.py
+++ b/tests/gateway/test_windows.py
@@ -153,11 +153,16 @@ def visible_text(messages):
)
-def stored(app, kind):
+async def stored(app, kind):
store = app.state.store
- with store.connect() as c:
- rows = c.execute("SELECT anchor, value FROM replay WHERE kind=?", (kind,)).fetchall()
- return {anchor: store.decode(value) for anchor, value in rows}
+
+ def read():
+ # Decoding waits on the event loop for the encryptor, so it runs on a storage thread.
+ with store.connect() as c:
+ rows = c.execute("SELECT anchor, value FROM replay WHERE kind=?", (kind,)).fetchall()
+ return {anchor: store.decode(value) for anchor, value in rows}
+
+ return await store.run(read)
def round_output(protocol, value):
@@ -634,11 +639,11 @@ async def test_reset_continues_in_the_new_window(
assert header.endswith("</openviking-context>\n\n" + opening)
# The cut follows the last client message; the hidden record holds only the new window.
anchor = hidden_chain(run.body[field], protocol)[-1]
- assert stored(app, "replacement") == {
+ assert await stored(app, "replacement") == {
anchor: {"source": "window", "text": header, "tokens": token_estimate(header)}
}
assert confirmed_cuts == [anchor]
- assert stored(app, "hidden") == {
+ assert await stored(app, "hidden") == {
hidden_chain([*run.body[field], *visible], protocol)[-1]: {
"messages": round_output(protocol, run.upstream[1]),
"visible_count": len(visible),
@@ -659,8 +664,8 @@ async def test_last_reset_in_a_request_wins(running_gateway, confirmed_cuts):
assert run.response.status_code == 200, run.response.text
header = run.requests[2]["messages"][-1]["content"]
assert "This is context window 2." in header and "Second notes." in header
- assert [r["text"] for r in stored(app, "replacement").values()] == [header]
- (record,) = stored(app, "hidden").values()
+ assert [r["text"] for r in (await stored(app, "replacement")).values()] == [header]
+ (record,) = (await stored(app, "hidden")).values()
assert record["messages"] == round_output("chat", run.upstream[2])
assert len(confirmed_cuts) == 1
@@ -682,7 +687,7 @@ async def test_new_context_must_be_the_only_call(running_gateway, confirmed_cuts
assert [(b["content"], b["is_error"]) for b in message["content"]] == [(ALONE, True)] * 2
else:
assert [r["content"] for r in results] == [ALONE, ALONE]
- assert not run.mcp and not stored(app, "replacement") and not confirmed_cuts
+ assert not run.mcp and not await stored(app, "replacement") and not confirmed_cuts
text = visible_text(visible_messages(protocol, run.response, False))
assert "> OpenViking new_context — failed" in text
@@ -693,7 +698,11 @@ async def test_failed_loop_after_a_reset_writes_nothing(running_gateway, confirm
await enable_tools(client, admin, agent_windows=True)
run = await send(running_gateway, protocol, False, [[(NEW_CONTEXT, NOTES)]], fail=True)
assert run.response.status_code == 503 and len(run.requests) == 2
- assert not stored(app, "replacement") and not stored(app, "hidden") and not confirmed_cuts
+ assert (
+ not await stored(app, "replacement")
+ and not await stored(app, "hidden")
+ and not confirmed_cuts
+ )
async def test_context_remaining_reads_the_latest_round(running_gateway):
@@ -709,7 +718,7 @@ async def test_context_remaining_reads_the_latest_round(running_gateway):
"User messages in this window: 1.\n"
"Advice: no action needed; keep working.",
}
- assert not stored(app, "replacement")
+ assert not await stored(app, "replacement")
@pytest.mark.parametrize("protocol", ["chat", "anthropic", "responses"])
@@ -722,9 +731,13 @@ async def test_reset_replays_on_the_next_request(running_gateway, protocol):
# The history up to the cut is queued for delivery at once.
anchor = hidden_chain(run.body[field], protocol)[-1]
store = app.state.store
- with store.connect() as c:
- (value,) = c.execute("SELECT value FROM capture").fetchone()
- state = store.decode(value)
+
+ def read():
+ with store.connect() as c:
+ (value,) = c.execute("SELECT value FROM capture").fetchone()
+ return store.decode(value)
+
+ state = await store.run(read)
confirmed = [turn["anchor"] for turn in state["pending"] if turn["confirmed"]]
assert anchor in [state["delivered"], *confirmed]
run.body[field] += [
diff --git a/tests/server/test_admin_api.py b/tests/server/test_admin_api.py
index 365a7f6f1..ac43dd73c 100644
--- a/tests/server/test_admin_api.py
+++ b/tests/server/test_admin_api.py
@@ -2688,8 +2688,16 @@ async def test_remove_user(
admin_client: httpx.AsyncClient,
admin_service: OpenVikingService,
admin_app: FastAPI,
+ monkeypatch,
):
- """Deletion revokes the user and removes only their private data, uploads, and tasks."""
+ """Deletion revokes the user and removes only their private data, uploads, tasks,
+ and embedded gateway state."""
+ import openviking_gateway.app as gateway_module
+
+ gateway = object()
+ delete_gateway_data = AsyncMock()
+ monkeypatch.setattr(gateway_module, "delete_data", delete_gateway_data)
+ monkeypatch.setattr(admin_app.state.deletion_service, "_gateway_app", gateway)
acct = _uid()
await admin_client.post(
"/api/v1/admin/accounts",
@@ -2739,6 +2747,7 @@ async def test_remove_user(
assert not await admin_service.viking_fs.exists(bob_upload_uri, ctx=upload_ctx)
assert await admin_service.viking_fs.exists(alice_upload_uri, ctx=upload_ctx)
assert not await admin_app.state.api_key_manager.has_user(acct, "bob")
+ delete_gateway_data.assert_awaited_once_with(gateway, acct, "bob")
assert (
await get_task_tracker().get(
bob_task.task_id,
diff --git a/tests/server/test_bootstrap.py b/tests/server/test_bootstrap.py
index d60932c75..98cd1bdf4 100644
--- a/tests/server/test_bootstrap.py
+++ b/tests/server/test_bootstrap.py
@@ -211,6 +211,8 @@ def test_bot_alias_propagates_resolved_config_to_workers(monkeypatch):
)
with monkeypatch.context() as worker_env:
+ worker_env.delenv(app_module.WORKER_HOST_ENV, raising=False)
+ worker_env.delenv(app_module.WORKER_PORT_ENV, raising=False)
worker_env.delenv(app_module.WORKER_WITH_BOT_ENV, raising=False)
worker_env.delenv(app_module.WORKER_BOT_API_URL_ENV, raising=False)
@@ -218,6 +220,8 @@ def test_bot_alias_propagates_resolved_config_to_workers(monkeypatch):
assert captured["with_bot"] is True
assert captured["app"] == "openviking.server.app:create_worker_app"
+ assert os.environ[app_module.WORKER_HOST_ENV] == config.host
+ assert os.environ[app_module.WORKER_PORT_ENV] == str(config.port)
assert os.environ[app_module.WORKER_WITH_BOT_ENV] == "1"
assert os.environ[app_module.WORKER_BOT_API_URL_ENV] == "http://127.0.0.1:19000"
@@ -267,6 +271,8 @@ def test_main_prints_config_diagnostics_on_validation_error(monkeypatch, capsys)
def test_worker_factory_replays_bot_overrides(monkeypatch):
config = ServerConfig(with_bot=False, bot_api_url="http://from-config")
captured = {}
+ monkeypatch.setenv(app_module.WORKER_HOST_ENV, "::")
+ monkeypatch.setenv(app_module.WORKER_PORT_ENV, "1999")
monkeypatch.setenv(app_module.WORKER_WITH_BOT_ENV, "1")
monkeypatch.setenv(app_module.WORKER_BOT_API_URL_ENV, "http://127.0.0.1:19000")
monkeypatch.setattr(
@@ -293,6 +299,8 @@ def test_worker_factory_replays_bot_overrides(monkeypatch):
worker_config = app_module.create_worker_app()
+ assert worker_config.host == "::"
+ assert worker_config.port == 1999
assert worker_config.with_bot is True
assert worker_config.bot_api_url == "http://127.0.0.1:19000"
assert captured == {
diff --git a/tests/server/test_gateway_embedded.py b/tests/server/test_gateway_embedded.py
new file mode 100644
index 000000000..0563a92dc
--- /dev/null
+++ b/tests/server/test_gateway_embedded.py
@@ -0,0 +1,258 @@
+"""The embedded gateway owns /gateway and starts before deletion recovery."""
+
+import sqlite3
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import httpx
+import pytest
+from starlette.testclient import TestClient, WebSocketDenialResponse
+
+from openviking.crypto.encryptor import MAGIC, FileEncryptor
+from openviking.server import gateway_host
+from openviking_cli.utils.config.encryption_config import EncryptionConfig
+from openviking_gateway.config import EmbeddedGatewayConfig
+
+
+def openviking_config(gateway, encryption=None):
+ return SimpleNamespace(
+ gateway=gateway,
+ encryption=encryption or EncryptionConfig(),
+ oauth=SimpleNamespace(enabled=False),
+ )
+
+
[email protected]("host,expected", [("0.0.0.0", "127.0.0.1"), ("::", "[::1]")])
+def test_embedded_gateway_targets_loopback_without_version_gate(host, expected, monkeypatch):
+ monkeypatch.setattr(
+ "openviking_gateway.app.create_app", lambda config, **kwargs: {"config": config, **kwargs}
+ )
+ options = gateway_host.create_embedded_gateway(
+ openviking_config(EmbeddedGatewayConfig(enabled=True)),
+ SimpleNamespace(host=host, port=1987, public_base_url=None),
+ lambda: None,
+ )
+ assert options["openviking_url"] == f"http://{expected}:1987"
+ assert options["config"].min_server_version == "0"
+ assert options["encryptor"] is None
+
+
+async def test_embedded_gateway_uses_server_encryption(tmp_path, monkeypatch):
+ monkeypatch.setattr(
+ "openviking_gateway.app.create_app", lambda config, **kwargs: {"config": config, **kwargs}
+ )
+ encryption = EncryptionConfig(enabled=True, local={"key_file": str(tmp_path / "master.key")})
+ options = gateway_host.create_embedded_gateway(
+ openviking_config(EmbeddedGatewayConfig(enabled=True), encryption),
+ SimpleNamespace(host="127.0.0.1", port=1987, public_base_url=None),
+ lambda: None,
+ )
+ assert isinstance(options["encryptor"], FileEncryptor)
+
+
+def test_embedded_gateway_falls_back_to_server_public_url(monkeypatch):
+ monkeypatch.setattr(
+ "openviking_gateway.app.create_app", lambda config, **kwargs: {"config": config, **kwargs}
+ )
+ monkeypatch.delenv("OPENVIKING_PUBLIC_BASE_URL", raising=False)
+ server = SimpleNamespace(host="0.0.0.0", port=1933, public_base_url="https://ov.example.com/")
+
+ def public_url(gateway):
+ options = gateway_host.create_embedded_gateway(
+ openviking_config(gateway), server, lambda: None
+ )
+ return options["config"].public_url
+
+ assert public_url(EmbeddedGatewayConfig(enabled=True)) == "https://ov.example.com"
+ monkeypatch.setenv("OPENVIKING_PUBLIC_BASE_URL", "https://edge.example.com")
+ assert public_url(EmbeddedGatewayConfig(enabled=True)) == "https://edge.example.com"
+ own = EmbeddedGatewayConfig(enabled=True, public_url="https://gw.example.com")
+ assert public_url(own) == "https://gw.example.com"
+
+
+async def model_server():
+ from aiohttp import web
+
+ app = web.Application()
+
+ async def chat(request):
+ assert request.headers["Authorization"] == "Bearer secret"
+ assert (await request.json())["model"] == "gpt"
+ return web.json_response(
+ {
+ "id": "chat-1",
+ "choices": [
+ {"message": {"role": "assistant", "content": "hello"}, "finish_reason": "stop"}
+ ],
+ }
+ )
+
+ seen = []
+
+ async def other(request):
+ seen.append((request.method, request.path, request.query_string))
+ return web.json_response({"ok": True})
+
+ app.router.add_post("/v1/chat/completions", chat)
+ app.router.add_route("*", "/v1/{tail:.*}", other)
+ runner = web.AppRunner(app)
+ await runner.setup()
+ site = web.TCPSite(runner, "127.0.0.1", 0)
+ await site.start()
+ try:
+ yield SimpleNamespace(
+ url=f"http://127.0.0.1:{site._server.sockets[0].getsockname()[1]}/v1", seen=seen
+ )
+ finally:
+ await runner.cleanup()
+
+
+async def test_server_lifespan_routes_defaults_and_cors(tmp_path, monkeypatch, model_server):
+ from openviking.metrics import global_api
+ from openviking.observability import usage_audit
+ from openviking.server import app as server_module
+ from openviking.server.config import ServerConfig
+ from openviking.server.mcp_endpoint import mcp
+ from openviking_cli.utils.config.vlm_config import VLMConfig
+ from openviking_gateway.client import VikingClient
+
+ gateway_config = EmbeddedGatewayConfig(enabled=True, storage_path=str(tmp_path / "gateway"))
+ encryption = EncryptionConfig(enabled=True, local={"key_file": str(tmp_path / "master.key")})
+ # FastMCP's session manager is single-use; keep this lifespan isolated from other tests.
+ monkeypatch.setattr(mcp, "_session_manager", None)
+ monkeypatch.setattr(
+ server_module,
+ "get_openviking_config",
+ lambda: openviking_config(gateway_config, encryption),
+ )
+ monkeypatch.setattr(global_api, "init_metrics_from_server_config", lambda *args, **kwargs: None)
+ monkeypatch.setattr(global_api, "shutdown_metrics_async", AsyncMock())
+ monkeypatch.setattr(usage_audit, "init_usage_audit_from_server_config", AsyncMock())
+ monkeypatch.setattr(usage_audit, "shutdown_usage_audit", AsyncMock())
+ # Calls back to OV are represented by its public health response, including dev identity rules.
+ # A source checkout reports a dev version, which must not trip the minimum-version gate.
+ monkeypatch.setattr(
+ VikingClient,
+ "request",
+ AsyncMock(return_value={"status": "ok", "auth_mode": "dev", "version": "0.1.dev1"}),
+ )
+ service = SimpleNamespace(
+ vlm_resolver=SimpleNamespace(
+ effective_vlm_config=AsyncMock(
+ return_value=VLMConfig(
+ model="gpt", provider="openai", api_key="secret", api_base=model_server.url
+ )
+ )
+ )
+ )
+ initialized = []
+ monkeypatch.setattr(
+ server_module,
+ "get_task_tracker",
+ lambda: SimpleNamespace(start_cleanup_loop=lambda: None, stop_cleanup_loop=lambda: None),
+ )
+
+ async def initialize(app, _service, config):
+ # The gateway is running before deletion setup receives it.
+ assert await app.state.gateway_app.state.management.list("default", "upstreams") == []
+ initialized.append(True)
+ await server_module._initialize_auth_plugin(app, service, config)
+
+ monkeypatch.setattr(server_module, "_initialize_runtime_state", initialize)
+ from openviking.server import body_dump_middleware
+
+ dumped = []
+
+ async def dump(request, call_next):
+ dumped.append(request.url.path)
+ return await call_next(request)
+
+ monkeypatch.setattr(
+ body_dump_middleware, "create_dump_http_body_middleware", lambda **kwargs: dump
+ )
+ server_config = ServerConfig(host="127.0.0.1", port=1999)
+ server_config.observability.dump_body.enabled = True
+ app = server_module.create_app(server_config, service=service)
+ assert app.state.gateway_app.state.openviking_url == "http://127.0.0.1:1999"
+ async with app.router.lifespan_context(app):
+ assert initialized == [True]
+ async with httpx.AsyncClient(
+ transport=httpx.ASGITransport(app), base_url="http://test"
+ ) as client:
+ access = await client.get("/gateway/admin/access")
+ assert access.status_code == 200
+ assert access.json()["can_import_vlm"] is True
+ assert access.json()["role"] == "root"
+ upstreams = (await client.get("/gateway/admin/upstreams")).json()
+ assert len(upstreams) == 1
+ policy = await app.state.gateway_app.state.management.get(
+ "default", "policies", "default"
+ )
+ assert policy["name"] == "Default"
+ created = await client.post(
+ "/gateway/admin/keys",
+ json={"name": "test", "policy_id": "default", "upstream_ids": [upstreams[0]["id"]]},
+ )
+ assert created.status_code == 200, created.text
+ key = created.json()["key"]
+ bearer = {"Authorization": "Bearer " + key}
+ response = await client.get("/gateway/v1/models", headers=bearer)
+ assert response.status_code == 200, response.text
+ assert response.json()["data"][0]["id"] == "gpt"
+ # The server no longer claims the model-API prefixes at its root.
+ for old in ("/v1/models", "/api/v3/models", "/api/v1/admin/gateway/access"):
+ assert (await client.get(old, headers=bearer)).status_code == 404, old
+ await app.state.gateway_app.state.management.save(
+ "default",
+ "policies",
+ "default",
+ {
+ **policy,
+ "capture": False,
+ "recall": False,
+ "profile": False,
+ "gateway_tools": False,
+ },
+ )
+ # Both model discovery and chat pass through the server to the embedded gateway.
+ response = await client.post(
+ "/gateway/v1/chat/completions",
+ headers={"Authorization": "Bearer " + key},
+ json={"model": "gpt", "messages": [{"role": "user", "content": "hello"}]},
+ )
+ assert response.status_code == 200, response.text
+ assert response.json()["choices"][0]["message"]["content"] == "hello"
+ # Other methods, the remaining path and the query string reach the upstream unchanged.
+ response = await client.patch("/gateway/v1/files/f-1?purpose=batch", headers=bearer)
+ assert response.status_code == 200, response.text
+ assert model_server.seen == [("PATCH", "/v1/files/f-1", "purpose=batch")]
+ assert (await client.get("/admin")).status_code == 404
+ assert "service" not in (await client.get("/health")).json()
+ preflight = await client.options(
+ "/gateway/v1/chat/completions",
+ headers={
+ "Origin": "https://studio.example",
+ "Access-Control-Request-Method": "POST",
+ },
+ )
+ assert preflight.status_code == 200
+ assert preflight.headers["access-control-allow-origin"] == "https://studio.example"
+ assert dumped == [
+ "/v1/models",
+ "/api/v3/models",
+ "/api/v1/admin/gateway/access",
+ "/admin",
+ "/health",
+ ]
+ # The gateway refuses Responses WebSocket upgrades itself.
+ for path in ("/gateway/v1/responses", "/gateway/api/v3/responses"):
+ with pytest.raises(WebSocketDenialResponse) as exc:
+ with TestClient(app).websocket_connect(path):
+ pass
+ assert exc.value.status_code == 426
+ assert exc.value.headers["upgrade"] == "HTTP/1.1"
+ # Gateway objects are stored with the server's encryption.
+ with sqlite3.connect(tmp_path / "gateway" / "management.sqlite3") as db:
+ values = [row[0] for row in db.execute("SELECT value FROM objects")]
+ assert values and all(value.startswith(MAGIC) for value in values)
diff --git a/tests/server/test_gateway_proxy.py b/tests/server/test_gateway_proxy.py
deleted file mode 100644
index 74b647f49..000000000
--- a/tests/server/test_gateway_proxy.py
+++ /dev/null
@@ -1,162 +0,0 @@
-"""Studio binds a gateway key to a chosen user; the user's key stays on the server."""
-
-import json
-from types import SimpleNamespace
-from unittest.mock import AsyncMock
-
-import httpx
-import pytest
-from fastapi import FastAPI
-
-from openviking.server.auth import get_request_context
-from openviking.server.identity import RequestContext, Role
-from openviking.server.routers import gateway
-from openviking_cli.session.user_id import UserIdentifier
-
-TOKEN_ENV = "TEST_GATEWAY_ADMIN_TOKEN"
-USERS = {
- "a": [
- {"user_id": "alice", "role": "user", "api_key": "alice-key"},
- {"user_id": "boss", "role": "admin", "api_key": "boss-key"},
- {"user_id": "hashed", "role": "user", "key_prefix": "prefix"},
- {"user_id": "root", "role": "root", "api_key": "root-key"},
- ],
- "b": [{"user_id": "carol", "role": "user", "api_key": "carol-key"}],
-}
-SETTINGS = {"name": "Laptop", "policy_id": "p", "upstream_ids": ["u"], "models": []}
-
-
-def app():
- app = FastAPI()
- app.include_router(gateway.router)
- app.state.api_key_manager = SimpleNamespace(
- list_users_page=AsyncMock(
- side_effect=lambda account_id, **_kwargs: {"users": USERS[account_id]}
- ),
- )
- app.dependency_overrides[get_request_context] = lambda: RequestContext(
- user=UserIdentifier("a", "boss"), role=Role.ADMIN
- )
- return app
-
-
-def forwarded(monkeypatch):
- """Requests that reached the gateway's management API."""
- calls = []
-
- def management_api(request):
- calls.append(request)
- return httpx.Response(200, json={"id": "k", "key": "ovgw_secret"})
-
- monkeypatch.setenv(TOKEN_ENV, "t" * 32)
- config = SimpleNamespace(enabled=True, admin_token_env=TOKEN_ENV, url="http://gateway")
- monkeypatch.setattr(
- gateway,
- "get_openviking_config",
- lambda: SimpleNamespace(gateway=config),
- )
- monkeypatch.setattr(
- gateway,
- "httpx",
- SimpleNamespace(
- AsyncClient=lambda **kwargs: httpx.AsyncClient(
- transport=httpx.MockTransport(management_api), **kwargs
- ),
- HTTPError=httpx.HTTPError,
- ),
- )
- return calls
-
-
-async def send(app, method, path, **kwargs):
- async with httpx.AsyncClient(
- transport=httpx.ASGITransport(app=app), base_url="http://test"
- ) as client:
- return await client.request(method, "/api/v1/admin/gateway/" + path, **kwargs)
-
-
[email protected]("user_id,key", [("alice", "alice-key"), ("boss", "boss-key")])
-async def test_selected_user_is_replaced_with_their_stored_key(app, forwarded, user_id, key):
- response = await send(app, "POST", "keys", json={**SETTINGS, "user_id": user_id})
- assert response.status_code == 200
- (request,) = forwarded
- assert str(request.url) == "http://gateway/admin/keys"
- assert request.headers["X-OpenViking-Account"] == "a"
- assert json.loads(request.content) == {**SETTINGS, "openviking_key": key}
- assert key not in response.text
- app.state.api_key_manager.list_users_page.assert_awaited_with(
- "a",
- limit=None,
- role_filter=None,
- expose_key=True,
- fresh=True,
- )
-
-
[email protected]("user_id", ["missing", "carol", "root"])
-async def test_only_users_and_admins_of_the_current_account_can_be_selected(
- app, forwarded, user_id
-):
- response = await send(app, "POST", "keys", json={**SETTINGS, "user_id": user_id})
- assert response.status_code == 400
- assert response.json()["detail"] == "Unknown OpenViking user in this account"
- assert forwarded == []
-
-
-async def test_unreadable_key_asks_for_a_pasted_key(app, forwarded):
- response = await send(app, "POST", "keys", json={**SETTINGS, "user_id": "hashed"})
- assert response.status_code == 409
- assert "paste the user's OpenViking key" in response.json()["detail"]
- assert "prefix" not in response.text
- assert forwarded == []
-
-
-async def test_root_cannot_choose_a_user(app, forwarded):
- # Root's request account need not be the account Studio shows.
- app.dependency_overrides[get_request_context] = lambda: RequestContext(
- user=UserIdentifier("a", "default"), role=Role.ROOT
- )
- response = await send(app, "POST", "keys", json={**SETTINGS, "user_id": "alice"})
- assert response.status_code == 400
- assert "paste the user's OpenViking key" in response.json()["detail"]
- assert forwarded == []
- app.state.api_key_manager.list_users_page.assert_not_called()
-
-
-async def test_user_and_pasted_key_together_are_rejected_without_echo(app, forwarded):
- response = await send(
- app, "POST", "keys", json={**SETTINGS, "user_id": "alice", "openviking_key": "pasted"}
- )
- assert response.status_code == 422
- assert "pasted" not in response.text
- assert forwarded == []
-
-
- "method,path,body",
- [
- ("POST", "keys", json.dumps({**SETTINGS, "openviking_key": "pasted"}).encode()),
- ("POST", "keys", b'{"user_id": '),
- ("POST", "keys/k/capture/reset", b'{"user_id": "alice"}'),
- ("PUT", "upstreams/u", b'{"user_id": "alice"}'),
- ("GET", "keys", b""),
- ("GET", "tools", b""),
- ],
-)
-async def test_other_requests_pass_through_unchanged(app, forwarded, method, path, body):
- response = await send(app, method, path, content=body)
- assert response.status_code == 200
- (request,) = forwarded
- assert request.method == method
- assert request.url.path == "/admin/" + path
- assert request.content == body
- app.state.api_key_manager.list_users_page.assert_not_called()
-
-
[email protected]("path", ["uploads", "v1/models"])
-async def test_only_management_resources_are_forwarded(app, forwarded, path):
- response = await send(app, "GET", path)
- assert response.status_code == 404
- assert forwarded == []
diff --git a/tests/server/test_gateway_vlm.py b/tests/server/test_gateway_vlm.py
new file mode 100644
index 000000000..209849c3b
--- /dev/null
+++ b/tests/server/test_gateway_vlm.py
@@ -0,0 +1,152 @@
+"""VLM imports use the same endpoint semantics and identities as OV backends."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from openviking.config.vlm import AccountVLMProvider
+from openviking.server.gateway_vlm import vlm_upstreams
+from openviking_cli.utils.config.vlm_config import VLMConfig
+
+
+def configured(provider, model="model", **kwargs):
+ return VLMConfig(
+ model=model,
+ credentials=[{"id": "primary", "provider": provider, "api_key": "secret", **kwargs}],
+ )
+
+
+ "provider,model,base,protocol,vendor",
+ [
+ ("openai", "gpt", "https://api.openai.com/v1", "chat", "openai"),
+ ("volcengine", "ep-123", "https://ark.cn-beijing.volces.com/api/v3", "chat", "ark"),
+ ("litellm", "anthropic/claude", "https://api.anthropic.com", "anthropic", "anthropic"),
+ ("litellm", "ollama/qwen", "http://localhost:11434/v1", "chat", "generic"),
+ ("litellm", "ollama_chat/qwen", "http://localhost:11434/v1", "chat", "generic"),
+ (None, "gpt", "https://api.openai.com/v1", "chat", "openai"),
+ ],
+)
+def test_default_provider_mapping(provider, model, base, protocol, vendor):
+ result = vlm_upstreams(configured(provider, model))
+ assert result["skipped"] == []
+ (upstream,) = result["upstreams"]
+ assert (upstream["id"], upstream["base_url"], upstream["protocol"], upstream["vendor"]) == (
+ "vlm-primary",
+ base,
+ protocol,
+ vendor,
+ )
+ assert upstream["models"] == [model.split("/", 1)[-1]]
+
+
+ "path,expected",
+ [("/coding/paas/v4", True), ("/plan", True), ("/myplan/v1", False), ("/coding-plan", False)],
+)
+def test_coding_plan_requires_explicit_consent(path, expected):
+ (upstream,) = vlm_upstreams(configured("openai", api_base="https://example.com" + path))[
+ "upstreams"
+ ]
+ assert upstream["coding_plan"] == expected
+
+
+def test_kimi_alias_base_and_custom_user_agent():
+ (upstream,) = vlm_upstreams(
+ configured("kimi", "kimi-code", extra_headers={"user-agent": "mine"})
+ )["upstreams"]
+ assert upstream["base_url"] == "https://api.kimi.com/coding/v1"
+ assert upstream["headers"] == {"user-agent": "mine"}
+ assert upstream["models"] == ["kimi-for-coding"]
+ (default,) = vlm_upstreams(configured("kimi"))["upstreams"]
+ assert default["headers"]["User-Agent"] == "KimiCLI/1.30.0"
+
+
+def test_glm_and_byteplus():
+ (glm,) = vlm_upstreams(configured("glm"))["upstreams"]
+ assert glm["base_url"] == "https://api.z.ai/api/coding/paas/v4"
+ assert glm["coding_plan"] is True
+ (ark,) = vlm_upstreams(
+ configured(
+ "volcengine",
+ api_base="https://ark.ap-southeast.bytepluses.com/api/v3",
+ extra_headers={"X-Client-Request-Id": "ov", "custom": "value"},
+ )
+ )["upstreams"]
+ assert ark["vendor"] == "byteplus"
+ assert ark["headers"] == {"custom": "value"}
+
+
+ "provider,model,reason",
+ [
+ ("azure", "deployment", "azure"),
+ ("openai-codex", "gpt", "openai_codex"),
+ ("litellm", "some/model", "litellm_no_api_base"),
+ ("litellm", "gemini/gemini-2.0-flash", "litellm_unsupported_route"),
+ ("litellm", "bedrock/anthropic.claude-3", "litellm_unsupported_route"),
+ ],
+)
+def test_skipped_credentials_have_actionable_reasons(provider, model, reason):
+ # Every route except the generic one has an api_base, so only the route decides the skip.
+ base = None if reason == "litellm_no_api_base" else "https://example.com/v1"
+ result = vlm_upstreams(configured(provider, model, api_base=base))
+ assert result["upstreams"] == []
+ assert result["skipped"] == [{"id": "vlm-primary", "reason": reason}]
+
+
+def test_litellm_openai_routes_send_the_bare_model_name():
+ (upstream,) = vlm_upstreams(
+ configured(
+ "litellm",
+ "openai/qwen-plus",
+ api_base="https://dashscope.aliyuncs.com/compatible-mode/v1",
+ )
+ )["upstreams"]
+ assert upstream["models"] == ["qwen-plus"]
+ (served,) = vlm_upstreams(
+ configured("litellm", "Qwen/Qwen2.5-7B", api_base="http://vllm.local/v1")
+ )["upstreams"]
+ assert served["models"] == ["Qwen/Qwen2.5-7B"]
+
+
+def test_all_credentials_and_legacy_config_are_imported():
+ config = VLMConfig(model="gpt", provider="openai", api_key="secret")
+ assert len(vlm_upstreams(config)["upstreams"]) == 1
+ config = VLMConfig(
+ model="gpt",
+ credentials=[{"id": key, "provider": "openai", "api_key": key} for key in ("a", "b")],
+ )
+ assert [u["id"] for u in vlm_upstreams(config)["upstreams"]] == ["vlm-a", "vlm-b"]
+
+
+async def test_effective_configuration_respects_account_credentials_and_cluster_fallback():
+ from openviking.config.account_config import AccountVLMConfig
+
+ cluster = configured("openai", api_base="https://cluster.example/v1")
+ account = AccountVLMConfig(
+ model="account-model",
+ credentials=[
+ {
+ "id": "own",
+ "provider": "openai",
+ "api_key": "account-secret",
+ "api_base": "https://account.example/v1",
+ }
+ ],
+ )
+ provider = AccountVLMProvider(SimpleNamespace(add_update_consumer=lambda **kwargs: None))
+ provider._view = AsyncMock(
+ return_value=SimpleNamespace(
+ account=SimpleNamespace(vlm=account), cluster=SimpleNamespace(vlm=cluster)
+ )
+ )
+ effective = await provider.effective_vlm_config("a")
+ assert effective.model == "account-model"
+ assert effective.credentials[0].api_key == "account-secret"
+ assert effective.credentials[0].api_base == "https://account.example/v1"
+ provider._view.return_value.account.vlm = None
+ fallback = await provider.effective_vlm_config("b")
+ assert fallback.credentials[0].api_key == "secret"
+ assert fallback.credentials[0].api_base == "https://cluster.example/v1"
diff --git a/tests/telemetry/test_http_observability_middleware.py b/tests/telemetry/test_http_observability_middleware.py
index e19a6db15..fc4422333 100644
--- a/tests/telemetry/test_http_observability_middleware.py
+++ b/tests/telemetry/test_http_observability_middleware.py
@@ -142,3 +142,36 @@ def test_http_observability_captures_public_error_without_reading_response_body(
assert completed[2]["error_code"] == "PROCESSING_ERROR"
assert completed[2]["error_message"] == "Resource processing failed"
assert completed[2]["error_details"] == {"stage": "parse"}
+
+
+def test_route_template_keeps_mount_path_for_mounted_apps() -> None:
+ """A mounted sub-app (the embedded gateway) is labelled with its mount path, while
+ a root_path set before the server (a proxy prefix) stays out of the template."""
+ from openviking.observability.http_observability_middleware import scope_route_template
+
+ inner = FastAPI()
+
+ @inner.get("/admin/keys")
+ async def keys():
+ return {}
+
+ app = FastAPI()
+
+ @app.get("/health")
+ async def health():
+ return {}
+
+ seen = []
+
+ @app.middleware("http")
+ async def record(request, call_next):
+ response = await call_next(request)
+ seen.append(scope_route_template(request.scope))
+ return response
+
+ app.mount("/gateway", inner)
+ for root_path in ("", "/proxy"):
+ with TestClient(app, root_path=root_path) as client:
+ for path in ("/gateway/admin/keys", "/gateway/missing", "/health"):
+ client.get(root_path + path)
+ assert seen == ["/gateway/admin/keys", "/__unmatched__", "/health"] * 2
diff --git a/uv.lock b/uv.lock
index 3e53745ca..7eb82a11f 100644
--- a/uv.lock
+++ b/uv.lock
@@ -3458,8 +3458,10 @@ wheels = [
name = "openviking"
source = { editable = "." }
dependencies = [
+ { name = "aiohttp" },
{ name = "apscheduler" },
{ name = "argon2-cffi" },
+ { name = "async-timeout" },
{ name = "charset-normalizer" },
{ name = "cryptography" },
{ name = "defusedxml" },
@@ -3481,6 +3483,8 @@ dependencies = [
{ name = "opentelemetry-instrumentation-asyncio" },
{ name = "opentelemetry-sdk" },
{ name = "openviking-sdk" },
+ { name = "orjson" },
+ { name = "packaging" },
{ name = "pathspec" },
{ name = "pdfminer-six" },
{ name = "pdfplumber" },
@@ -3591,12 +3595,6 @@ eval = [
{ name = "pandas", version = "3.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
{ name = "ragas" },
]
-gateway = [
- { name = "aiohttp" },
- { name = "async-timeout" },
- { name = "orjson" },
- { name = "packaging" },
-]
gateway-fast = [
{ name = "httptools" },
{ name = "uvloop", marker = "sys_platform != 'win32'" },
@@ -3639,11 +3637,11 @@ dev = [
[package.metadata]
requires-dist = [
{ name = "agent-sandbox", marker = "extra == 'bot'", specifier = ">=0.0.23" },
- { name = "aiohttp", marker = "extra == 'gateway'", specifier = ">=3.13.3" },
+ { name = "aiohttp", specifier = ">=3.13.3" },
{ name = "anyio", marker = "extra == 'gemini-async'", specifier = ">=4.0.0" },
{ name = "apscheduler", specifier = ">=3.11.0" },
{ name = "argon2-cffi", specifier = ">=23.0.0" },
- { name = "async-timeout", marker = "extra == 'gateway'", specifier = ">=5.0.1" },
+ { name = "async-timeout", specifier = ">=5.0.1" },
{ name = "beautifulsoup4", marker = "extra == 'bot'", specifier = ">=4.12.0" },
{ name = "boto3", marker = "extra == 'test'", specifier = ">=1.42.44" },
{ name = "build", marker = "extra == 'build'" },
@@ -3697,8 +3695,8 @@ requires-dist = [
{ name = "opentelemetry-instrumentation-asyncio", specifier = ">=0.61b0" },
{ name = "opentelemetry-sdk", specifier = ">=1.14" },
{ name = "openviking-sdk", specifier = ">=0.1.15" },
- { name = "orjson", marker = "extra == 'gateway'", specifier = ">=3.11.7" },
- { name = "packaging", marker = "extra == 'gateway'", specifier = ">=24.0" },
+ { name = "orjson", specifier = ">=3.11.7" },
+ { name = "packaging", specifier = ">=24.0" },
{ name = "pandas", marker = "extra == 'benchmark'", specifier = ">=2.0.0" },
{ name = "pandas", marker = "extra == 'eval'", specifier = ">=2.0.0" },
{ name = "pandas", marker = "extra == 'test'", specifier = ">=2.0.0" },
@@ -3771,7 +3769,7 @@ requires-dist = [
{ name = "wheel", marker = "extra == 'build'" },
{ name = "xxhash", specifier = ">=3.0.0" },
]
-provides-extras = ["gateway", "gateway-fast", "test", "auth", "dev", "doc", "eval", "gemini", "gemini-async", "ocr", "build", "bot", "benchmark", "local-embed", "opengauss"]
+provides-extras = ["gateway-fast", "test", "auth", "dev", "doc", "eval", "gemini", "gemini-async", "ocr", "build", "bot", "benchmark", "local-embed", "opengauss"]
[package.metadata.requires-dev]
dev = [{ name = "pytest", specifier = ">=9.0.2" }]
diff --git a/web-studio/src/components/account-switcher.gateway.test.tsx b/web-studio/src/components/account-switcher.gateway.test.tsx
new file mode 100644
index 000000000..3d89ddc6d
--- /dev/null
+++ b/web-studio/src/components/account-switcher.gateway.test.tsx
@@ -0,0 +1,76 @@
+// @vitest-environment jsdom
+import {
+ cleanup,
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+} from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { afterEach, expect, it, vi } from 'vitest'
+import { AccountSwitcher } from './account-switcher'
+
+const { fetchAccounts, fetchUsers, switchAccount, switchIdentity } = vi.hoisted(
+ () => ({
+ fetchAccounts: vi.fn(),
+ fetchUsers: vi.fn(),
+ switchAccount: vi.fn(),
+ switchIdentity: vi.fn(),
+ }),
+)
+vi.mock('#/lib/admin', () => ({
+ fetchAdminAccounts: fetchAccounts,
+ fetchAdminUsers: fetchUsers,
+ createAdminAccount: vi.fn(),
+}))
+vi.mock('#/hooks/use-app-connection', () => ({
+ useAppConnection: () => ({
+ connection: {
+ accountId: 'default',
+ userId: 'root',
+ apiKey: 'root-login-key',
+ adminApiKey: '',
+ baseUrl: 'http://gateway.test',
+ },
+ connectionRole: 'root',
+ isGatewayHost: true,
+ isConnectionRoleLoading: false,
+ serverMode: 'api_key',
+ switchManagementAccount: switchAccount,
+ switchIdentity,
+ setGeneratedCredential: vi.fn(),
+ }),
+}))
+vi.mock('react-i18next', () => ({
+ useTranslation: () => ({ t: (key: string) => key }),
+}))
+afterEach(cleanup)
+it('root selects an account through the read-only list without requesting user credentials or offering creation', async () => {
+ fetchAccounts.mockResolvedValue([
+ { accountId: 'default', userCount: 1 },
+ { accountId: 'team', userCount: 2 },
+ ])
+ switchAccount.mockResolvedValue(undefined)
+ const client = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ })
+ render(
+ <QueryClientProvider client={client}>
+ <AccountSwitcher />
+ </QueryClientProvider>,
+ )
+ fireEvent.click(screen.getByText('default'))
+ await waitFor(() => expect(screen.getByText('team')).toBeTruthy())
+ expect(screen.queryByText('create')).toBeNull()
+ expect(fetchAccounts).toHaveBeenCalledWith(
+ expect.objectContaining({
+ apiKey: 'root-login-key',
+ baseUrl: 'http://gateway.test',
+ }),
+ )
+ fireEvent.click(screen.getByText('team'))
+ await waitFor(() => expect(switchAccount).toHaveBeenCalledWith('team'))
+ expect(fetchUsers).not.toHaveBeenCalled()
+ expect(switchIdentity).not.toHaveBeenCalled()
+ client.clear()
+})
diff --git a/web-studio/src/components/account-switcher.tsx b/web-studio/src/components/account-switcher.tsx
index d95424cd5..a5a22479f 100644
--- a/web-studio/src/components/account-switcher.tsx
+++ b/web-studio/src/components/account-switcher.tsx
@@ -60,6 +60,7 @@ export function AccountSwitcher() {
connection,
connectionRole,
isConnectionRoleLoading,
+ isGatewayHost,
setGeneratedCredential,
serverMode,
switchIdentity,
@@ -79,23 +80,30 @@ export function AccountSwitcher() {
adminUserId: DEFAULT_USER_ID,
})
- const { canManageAccounts } = resolveStudioManagementCapabilities({
+ const capabilities = resolveStudioManagementCapabilities({
hasControlCredential: Boolean(connection.adminApiKey.trim()),
isRoleLoading: isConnectionRoleLoading,
role: connectionRole,
serverMode,
})
+ const canManageAccounts = isGatewayHost
+ ? connectionRole === 'root' && !isConnectionRoleLoading
+ : capabilities.canManageAccounts
+
const adminConnection = React.useMemo<AdminConnection>(
() => ({
accountId: connection.accountId,
- apiKey: connection.adminApiKey,
+ apiKey:
+ connection.adminApiKey || (isGatewayHost ? connection.apiKey : ''),
baseUrl: connection.baseUrl,
userId: connection.userId,
}),
[
connection.accountId,
connection.adminApiKey,
+ connection.apiKey,
+ isGatewayHost,
connection.baseUrl,
connection.userId,
],
@@ -131,6 +139,12 @@ export function AccountSwitcher() {
setSwitchingAccountId(accountId)
try {
+ if (isGatewayHost) {
+ await switchManagementAccount(accountId)
+ setOpen(false)
+ toast.success(t('toast.switched', { account: accountId }))
+ return
+ }
const users = await fetchAdminUsers(adminConnection, accountId)
const firstUser = selectAccountUser(users, connection.userId, false)
if (!firstUser) {
@@ -329,21 +343,23 @@ export function AccountSwitcher() {
})
)}
</div>
- <div className="border-t p-1.5">
- <Button
- type="button"
- variant="ghost"
- size="sm"
- className="w-full justify-start px-2.5"
- onClick={() => {
- setOpen(false)
- setCreateOpen(true)
- }}
- >
- <PlusIcon />
- {t('create')}
- </Button>
- </div>
+ {!isGatewayHost && (
+ <div className="border-t p-1.5">
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ className="w-full justify-start px-2.5"
+ onClick={() => {
+ setOpen(false)
+ setCreateOpen(true)
+ }}
+ >
+ <PlusIcon />
+ {t('create')}
+ </Button>
+ </div>
+ )}
</PopoverContent>
</Popover>
diff --git a/web-studio/src/components/app-shell.test.tsx b/web-studio/src/components/app-shell.test.tsx
index 1a82b157d..3c38c5682 100644
--- a/web-studio/src/components/app-shell.test.tsx
+++ b/web-studio/src/components/app-shell.test.tsx
@@ -3,7 +3,10 @@
import { cleanup, render, screen } from '@testing-library/react'
import { afterEach, describe, expect, it } from 'vitest'
-import { ConnectionScopedRouteContent } from './app-shell'
+import {
+ ConnectionScopedRouteContent,
+ shouldShowGatewayNavigation,
+} from './app-shell'
afterEach(cleanup)
@@ -31,3 +34,32 @@ describe('ConnectionScopedRouteContent', () => {
},
)
})
+
+describe('gateway navigation', () => {
+ it.each([
+ ['dev', true, true],
+ ['api_key', true, true],
+ ['trusted', true, true],
+ ['api_key', false, false],
+ ['offline', true, false],
+ ['checking', true, false],
+ ] as const)('%s allowed %s: %s', (serverMode, allowed, visible) => {
+ expect(
+ shouldShowGatewayNavigation({
+ isGatewayHost: false,
+ serverMode,
+ allowed,
+ }),
+ ).toBe(visible)
+ })
+
+ it('always shows the entry on a standalone gateway', () => {
+ expect(
+ shouldShowGatewayNavigation({
+ isGatewayHost: true,
+ serverMode: 'offline',
+ allowed: false,
+ }),
+ ).toBe(true)
+ })
+})
diff --git a/web-studio/src/components/app-shell.tsx b/web-studio/src/components/app-shell.tsx
index 2956baced..ac2efda7a 100644
--- a/web-studio/src/components/app-shell.tsx
+++ b/web-studio/src/components/app-shell.tsx
@@ -61,6 +61,7 @@ import {
} from '#/hooks/use-app-connection'
import type { ServerMode } from '#/hooks/use-server-mode'
import { cn } from '#/lib/utils'
+import { useGateway } from '#/routes/gateway/-lib/use-gateway'
import { resolveStudioManagementCapabilities } from '#/lib/studio-permissions'
type NavItem = {
@@ -295,6 +296,26 @@ export function ConnectionScopedRouteContent({
return serverMode === 'checking' ? null : children
}
+/**
+ * Every signed-in user of an OpenViking server sees the gateway entry, even
+ * while the gateway is off: the page explains how to turn it on.
+ */
+export function shouldShowGatewayNavigation({
+ isGatewayHost,
+ serverMode,
+ allowed,
+}: {
+ isGatewayHost: boolean
+ serverMode: ServerMode
+ /** `useGateway().allowed`: the gateway can be asked for /access. */
+ allowed: boolean
+}): boolean {
+ return (
+ isGatewayHost ||
+ (serverMode !== 'checking' && serverMode !== 'offline' && allowed)
+ )
+}
+
function AppShellInner({ children }: { children: React.ReactNode }) {
const { i18n, t } = useTranslation(['appShell', 'common'])
const navigate = useNavigate()
@@ -313,13 +334,18 @@ function AppShellInner({ children }: { children: React.ReactNode }) {
}/api/01-overview`
const [crossDeviceVerifyOpen, setCrossDeviceVerifyOpen] =
React.useState(false)
- const { connection, connectionRole, isConnectionRoleLoading, serverMode } =
- useAppConnection()
+ const {
+ connection,
+ connectionRole,
+ isConnectionRoleLoading,
+ isGatewayHost,
+ serverMode,
+ } = useAppConnection()
const settingsActive = pathname === '/settings'
const usersActive = pathname === '/users' || pathname.startsWith('/users/')
const gatewayActive =
pathname === '/gateway' || pathname.startsWith('/gateway/')
- const { canManageUsers } = resolveStudioManagementCapabilities({
+ const capabilities = resolveStudioManagementCapabilities({
hasControlCredential: Boolean(connection.adminApiKey.trim()),
isRoleLoading: isConnectionRoleLoading,
role: connectionRole,
@@ -328,6 +354,15 @@ function AppShellInner({ children }: { children: React.ReactNode }) {
const crossDeviceVerifyActive =
pathname === '/oauth/verify' || pathname.startsWith('/oauth/verify/')
const visibleNavItems = NAV_ITEMS
+ const gateway = useGateway()
+ const showGateway = shouldShowGatewayNavigation({
+ isGatewayHost,
+ serverMode,
+ allowed: gateway.allowed,
+ })
+ // A standalone gateway serves only its own pages and the connection page.
+ const navSections = isGatewayHost ? [] : NAV_SECTIONS
+ const canManageUsers = !isGatewayHost && capabilities.canManageUsers
function openCrossDeviceVerify(): void {
if (crossDeviceVerifyActive) {
@@ -363,7 +398,7 @@ function AppShellInner({ children }: { children: React.ReactNode }) {
</SidebarHeader>
<SidebarContent className="gap-0 py-1">
- {NAV_SECTIONS.map((section) => (
+ {navSections.map((section) => (
<SidebarGroup key={section.id} className="pb-1">
<SidebarGroupLabel className="h-7 px-2 pt-2 text-[11px] font-semibold uppercase tracking-[0.12em] text-sidebar-foreground/45">
{t(section.titleKey, { ns: 'appShell' })}
@@ -432,7 +467,7 @@ function AppShellInner({ children }: { children: React.ReactNode }) {
<span>{t('footer.connection', { ns: 'appShell' })}</span>
</SidebarMenuButton>
</SidebarMenuItem>
- {canManageUsers ? (
+ {showGateway ? (
<SidebarMenuItem>
<SidebarMenuButton
render={<Link to="/gateway" />}
@@ -464,7 +499,7 @@ function AppShellInner({ children }: { children: React.ReactNode }) {
</SidebarMenuButton>
</SidebarMenuItem>
) : null}
- <SidebarMenuItem>
+ <SidebarMenuItem hidden={isGatewayHost}>
<SidebarMenuButton
onClick={openCrossDeviceVerify}
isActive={crossDeviceVerifyActive}
@@ -485,7 +520,7 @@ function AppShellInner({ children }: { children: React.ReactNode }) {
</SidebarGroupContent>
</SidebarGroup>
- <SidebarGroup className="pb-1">
+ <SidebarGroup className="pb-1" hidden={isGatewayHost}>
<SidebarGroupLabel className="h-7 px-2 pt-2 text-[11px] font-semibold uppercase tracking-[0.12em] text-sidebar-foreground/45">
{t('sidebar.groups.resources', { ns: 'appShell' })}
</SidebarGroupLabel>
@@ -608,7 +643,7 @@ function AppShellInner({ children }: { children: React.ReactNode }) {
<div className="h-6 w-px bg-border/80" aria-hidden="true" />
- <CurrentUserMenu />
+ {isGatewayHost ? null : <CurrentUserMenu />}
</div>
</header>
diff --git a/web-studio/src/hooks/use-app-connection.bootstrap.test.tsx b/web-studio/src/hooks/use-app-connection.bootstrap.test.tsx
index 22c649099..3669ebfc1 100644
--- a/web-studio/src/hooks/use-app-connection.bootstrap.test.tsx
+++ b/web-studio/src/hooks/use-app-connection.bootstrap.test.tsx
@@ -103,3 +103,74 @@ it.each(['', 'root-key'])(
}
},
)
+
+it.each(['', 'invalid'])(
+ 'recognizes gateway health with saved OV key %j',
+ async (apiKey) => {
+ const requests: string[] = []
+ const server = createServer((req, res) => {
+ res.setHeader('Access-Control-Allow-Origin', '*')
+ res.setHeader(
+ 'Access-Control-Allow-Headers',
+ 'X-OpenViking-Account, X-OpenViking-User, X-API-Key',
+ )
+ if (req.method === 'OPTIONS') {
+ res.end()
+ return
+ }
+ requests.push(req.url || '')
+ res.setHeader('Content-Type', 'application/json')
+ // An invalid key only leaves out the identity fields.
+ res.end(
+ JSON.stringify({
+ status: 'ok',
+ service: 'openviking-gateway',
+ auth_mode: 'api_key',
+ openviking_url: 'https://ov.example',
+ }),
+ )
+ })
+ server.listen(0, '127.0.0.1')
+ await once(server, 'listening')
+ const { port } = server.address() as { port: number }
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ })
+ localStorage.setItem(
+ 'ov_console_connection',
+ JSON.stringify({
+ baseUrl: `http://127.0.0.1:${port}`,
+ accountId: 'default',
+ userId: 'default',
+ apiKey,
+ adminApiKey: '',
+ }),
+ )
+ function Host() {
+ const { isGatewayHost, openvikingUrl, serverMode } = useAppConnection()
+ return (
+ <output>{`${isGatewayHost}:${openvikingUrl}:${serverMode}`}</output>
+ )
+ }
+ try {
+ render(
+ <QueryClientProvider client={queryClient}>
+ <AppConnectionProvider>
+ <Host />
+ </AppConnectionProvider>
+ </QueryClientProvider>,
+ )
+ await waitFor(() =>
+ expect(
+ screen.getByText('true:https://ov.example:api_key'),
+ ).toBeTruthy(),
+ )
+ expect(requests.every((path) => path === '/health')).toBe(true)
+ } finally {
+ cleanup()
+ queryClient.clear()
+ localStorage.removeItem('ov_console_connection')
+ await new Promise<void>((resolve) => server.close(() => resolve()))
+ }
+ },
+)
diff --git a/web-studio/src/hooks/use-app-connection.host.test.tsx b/web-studio/src/hooks/use-app-connection.host.test.tsx
new file mode 100644
index 000000000..89743a0ee
--- /dev/null
+++ b/web-studio/src/hooks/use-app-connection.host.test.tsx
@@ -0,0 +1,78 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { afterEach, expect, it, vi } from 'vitest'
+import { AppConnectionProvider, useAppConnection } from './use-app-connection'
+
+const { health } = vi.hoisted(() => ({ health: vi.fn() }))
+vi.mock('./use-server-mode', async (importOriginal) => ({
+ ...(await importOriginal<object>()),
+ fetchServerHealth: health,
+}))
+vi.mock('@tanstack/react-router', () => ({
+ useNavigate: () => vi.fn(),
+ useRouterState: () => '/',
+}))
+afterEach(() => {
+ cleanup()
+ localStorage.removeItem('ov_console_connection')
+ window.history.replaceState(null, '', '/')
+})
+
+it('discovers the Studio gateway origin before using a stale saved Base URL or key', async () => {
+ window.history.replaceState(null, '', '/studio/')
+ localStorage.setItem(
+ 'ov_console_connection',
+ JSON.stringify({
+ baseUrl: 'https://previous-ov.example',
+ adminApiKey: 'previous-root-key',
+ apiKey: 'previous-user-key',
+ accountId: 'old',
+ userId: 'old',
+ }),
+ )
+ health.mockResolvedValue({
+ service: 'openviking-gateway',
+ auth_mode: 'api_key',
+ openviking_url: 'https://ov.example',
+ })
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ })
+ function State() {
+ const { connection, isGatewayHost, serverMode } = useAppConnection()
+ return (
+ <output>
+ {JSON.stringify({ connection, isGatewayHost, serverMode })}
+ </output>
+ )
+ }
+ render(
+ <QueryClientProvider client={queryClient}>
+ <AppConnectionProvider>
+ <State />
+ </AppConnectionProvider>
+ </QueryClientProvider>,
+ )
+ await waitFor(() =>
+ expect(screen.getByRole('status').textContent).toContain(
+ '"serverMode":"api_key"',
+ ),
+ )
+ const state = JSON.parse(screen.getByRole('status').textContent || '{}')
+ expect(state.isGatewayHost).toBe(true)
+ expect(state.connection).toEqual({
+ baseUrl: window.location.origin,
+ accountId: 'default',
+ userId: 'default',
+ apiKey: '',
+ adminApiKey: '',
+ })
+ expect(
+ health.mock.calls.every(
+ ([baseUrl, headers]) =>
+ baseUrl === window.location.origin && !headers?.['X-API-Key'],
+ ),
+ ).toBe(true)
+ queryClient.clear()
+})
diff --git a/web-studio/src/hooks/use-app-connection.test.ts b/web-studio/src/hooks/use-app-connection.test.ts
index 8bcfa3281..c3fe5a347 100644
--- a/web-studio/src/hooks/use-app-connection.test.ts
+++ b/web-studio/src/hooks/use-app-connection.test.ts
@@ -249,6 +249,22 @@ describe('createManagementAccountConnection', () => {
})
})
+it('preserves a root login key and caller identity when selecting a gateway account', () => {
+ const connection = {
+ accountId: 'account-a',
+ userId: 'root',
+ apiKey: 'root-login-key',
+ adminApiKey: '',
+ baseUrl: 'http://localhost:1935',
+ }
+ expect(
+ createManagementAccountConnection(connection, ' account-b ', true),
+ ).toEqual({
+ ...connection,
+ accountId: 'account-b',
+ })
+})
+
describe('synchronizeConnectionRuntime', () => {
it('updates the imperative client before React state consumers remount', () => {
const next = synchronizeConnectionRuntime(
diff --git a/web-studio/src/hooks/use-app-connection.tsx b/web-studio/src/hooks/use-app-connection.tsx
index 591b8caad..5fde6df61 100644
--- a/web-studio/src/hooks/use-app-connection.tsx
+++ b/web-studio/src/hooks/use-app-connection.tsx
@@ -7,7 +7,7 @@ import { fetchAdminAccounts } from '#/lib/admin'
import { isOvClientError, ovClient } from '#/lib/ov-client'
import {
- detectServerMode,
+ isServerAuthMode,
fetchServerHealth,
normalizeBaseUrl,
} from './use-server-mode'
@@ -43,6 +43,8 @@ type AppConnectionContextValue = {
generatedCredential: GeneratedCredential | null
identityScopeKey: string
isConnectionRoleLoading: boolean
+ isGatewayHost: boolean
+ openvikingUrl: string
openConnectionSettings: () => void
saveConnection: (next: ConnectionDraft) => void
setGeneratedCredential: (credential: GeneratedCredential) => void
@@ -158,7 +160,7 @@ function normalizeConnectionDraft(
// slash here ran on every keystroke and fought the input: typing the "//"
// of "http://" kept collapsing back to "http:". Trailing slashes are
// stripped where the URL is actually used instead (ovClient.setOptions,
- // detectServerMode, detectConnectionRole, and the admin client).
+ // fetchServerHealth, detectConnectionRole, and the admin client).
baseUrl: connection.baseUrl.trim(),
userId: connection.userId.trim(),
}
@@ -417,7 +419,11 @@ export function resolveSwitchedIdentity(
export function createManagementAccountConnection(
connection: ConnectionDraft,
accountId: string,
+ isGatewayHost = false,
): ConnectionDraft {
+ if (isGatewayHost) {
+ return { ...connection, accountId: accountId.trim() }
+ }
return {
...connection,
accountId: accountId.trim(),
@@ -496,6 +502,10 @@ export function AppConnectionProvider({
}) {
const queryClient = useQueryClient()
const authPromptSuppressedUntilRef = React.useRef(0)
+ const hostDiscoveryRef = React.useRef<Promise<Record<
+ string,
+ unknown
+ > | null> | null>(null)
const navigate = useNavigate()
const pathname = useRouterState({
select: (state) => state.location.pathname,
@@ -524,6 +534,8 @@ export function AppConnectionProvider({
),
)
const [serverMode, setServerMode] = React.useState<ServerMode>('checking')
+ const [isGatewayHost, setIsGatewayHost] = React.useState(false)
+ const [openvikingUrl, setOpenvikingUrl] = React.useState('')
const [generatedCredential, setGeneratedCredential] =
React.useState<GeneratedCredential | null>(null)
@@ -541,15 +553,65 @@ export function AppConnectionProvider({
React.useEffect(() => {
let cancelled = false
+ const isCancelled = () => cancelled
setServerMode('checking')
- void detectServerMode(
- connection.baseUrl,
- createConnectionHealthHeaders(connection),
- ).then((mode) => {
- if (!cancelled) {
- setServerMode(mode)
+ void (async () => {
+ // A standalone Studio is bound to the gateway serving /studio. Discover
+ // that host without forwarding credentials saved for another server.
+ if (
+ isBrowser() &&
+ window.location.pathname.startsWith('/studio') &&
+ normalizeBaseUrl(connection.baseUrl) !== window.location.origin
+ ) {
+ hostDiscoveryRef.current ??= fetchServerHealth(
+ window.location.origin,
+ ).catch(() => null)
+ const host = await hostDiscoveryRef.current
+ if (isCancelled()) return
+ if (host?.service === 'openviking-gateway') {
+ setIsGatewayHost(true)
+ setOpenvikingUrl(
+ typeof host.openviking_url === 'string' ? host.openviking_url : '',
+ )
+ const next = synchronizeConnectionRuntime(
+ {
+ ...connection,
+ baseUrl: window.location.origin,
+ apiKey: '',
+ adminApiKey: '',
+ accountId: 'default',
+ userId: 'default',
+ },
+ 'checking',
+ )
+ queryClient.clear()
+ setConnection(next)
+ return
+ }
}
- })
+ let health: Record<string, unknown>
+ try {
+ // The gateway answers an invalid OV key with health minus identity.
+ health = await fetchServerHealth(
+ connection.baseUrl,
+ createConnectionHealthHeaders(connection),
+ )
+ } catch {
+ if (!isCancelled()) setServerMode('offline')
+ return
+ }
+ if (!isCancelled()) {
+ setIsGatewayHost(health.service === 'openviking-gateway')
+ setOpenvikingUrl(
+ typeof health.openviking_url === 'string'
+ ? health.openviking_url
+ : '',
+ )
+ setServerMode(
+ isServerAuthMode(health.auth_mode) ? health.auth_mode : 'api_key',
+ )
+ }
+ })()
return () => {
cancelled = true
@@ -560,6 +622,7 @@ export function AppConnectionProvider({
connection.apiKey,
connection.baseUrl,
connection.userId,
+ queryClient,
])
React.useEffect(() => {
@@ -703,6 +766,8 @@ export function AppConnectionProvider({
generatedCredential,
identityScopeKey: createIdentityScopeKey(connection, serverMode),
isConnectionRoleLoading,
+ isGatewayHost,
+ openvikingUrl,
openConnectionSettings,
saveConnection: commitConnection,
setGeneratedCredential,
@@ -750,7 +815,11 @@ export function AppConnectionProvider({
throw createConnectionError('rootRequired')
}
commitConnection(
- createManagementAccountConnection(connection, accountId),
+ createManagementAccountConnection(
+ connection,
+ accountId,
+ isGatewayHost,
+ ),
)
},
}
@@ -759,6 +828,8 @@ export function AppConnectionProvider({
connectionRole,
generatedCredential,
isConnectionRoleLoading,
+ isGatewayHost,
+ openvikingUrl,
navigate,
openConnectionSettings,
pathname,
diff --git a/web-studio/src/hooks/use-server-mode.ts b/web-studio/src/hooks/use-server-mode.ts
index d151b7bcc..a070bf609 100644
--- a/web-studio/src/hooks/use-server-mode.ts
+++ b/web-studio/src/hooks/use-server-mode.ts
@@ -26,7 +26,7 @@ export function normalizeBaseUrl(baseUrl: string): string {
return baseUrl.trim().replace(/\/+$/, '')
}
-function isServerAuthMode(value: unknown): value is ServerAuthMode {
+export function isServerAuthMode(value: unknown): value is ServerAuthMode {
return (
typeof value === 'string' && SERVER_AUTH_MODES.has(value as ServerAuthMode)
)
@@ -82,15 +82,3 @@ export async function fetchServerHealth(
throw error
}
}
-
-export async function detectServerMode(
- baseUrl: string,
- headers?: Record<string, string>,
-): Promise<ServerMode> {
- try {
- const data = await fetchServerHealth(baseUrl, headers)
- return isServerAuthMode(data.auth_mode) ? data.auth_mode : 'api_key'
- } catch {
- return 'offline'
- }
-}
diff --git a/web-studio/src/i18n/locales/en/gateway/common.ts b/web-studio/src/i18n/locales/en/gateway/common.ts
index 18273be16..3282eb497 100644
--- a/web-studio/src/i18n/locales/en/gateway/common.ts
+++ b/web-studio/src/i18n/locales/en/gateway/common.ts
@@ -31,7 +31,10 @@ const common = {
retry: 'Retry',
revoke: 'Revoke',
save: 'Save',
+ view: 'View',
+ back: 'Back',
viewAll: 'View all',
+ viewKeys: 'View keys',
},
states: {
loading: 'Loading…',
@@ -46,41 +49,64 @@ const common = {
failed: "Couldn't copy. Select the text and copy it manually.",
},
access: {
- title: 'Account administrator access required',
+ title: 'Connect to OpenViking first',
+ invalid: 'Your OpenViking API key is invalid',
description:
- 'Managing the OpenViking Gateway needs an account administrator or root key for this account. Add one in Connection settings.',
+ 'The gateway uses your OpenViking API key to identify you. Add it in Connection settings first.',
+ invalidDescription:
+ 'OpenViking rejected the API key in Connection settings. It may have been regenerated or deleted. Enter a valid key.',
action: 'Open connection settings',
},
+ management: {
+ title: 'Enter gateway management key',
+ label: 'Gateway management key',
+ description:
+ "Whoever deployed this gateway sets the gateway management key. It's needed only to change upstreams and profiles, and it's neither your OpenViking API key nor a gateway key used by clients.",
+ where: 'Where can I find it?',
+ prefix:
+ 'Keys generated by openviking-server init or openviking-gateway init start with ovgm_.',
+ environment: 'Or this environment variable, which overrides both files:',
+ keyPlaceholder: '<at least 32 characters>',
+ session:
+ 'Kept only in this browser tab. Closing the tab locks editing again.',
+ wrongKey:
+ "That's a gateway key for clients. Enter the gateway management key instead.",
+ invalid:
+ "That gateway management key is incorrect. Check with whoever deployed this gateway. Note that it isn't your OpenViking admin API key.",
+ unlock: 'Unlock',
+ unlocked: 'Unlocked. You can now edit upstreams and profiles.',
+ lock: 'Lock',
+ editing: 'Editing upstreams and profiles',
+ expired:
+ 'The gateway management key is no longer valid. Upstreams and profiles are read-only again.',
+ readOnly:
+ 'Upstreams and profiles are provided by your gateway admin. You can view and test them, and pick them when issuing a key.',
+ adminReadOnly:
+ 'OpenViking admins and root also need the gateway management key to change them.',
+ shared:
+ "You're editing settings shared by everyone in this account. Changes apply to every key that uses them as soon as you save.",
+ publicTitle: 'This gateway is open to every OpenViking Cloud user',
+ publicDescription:
+ 'It connects to the public OpenViking service and has no gateway management key, so anyone with an OpenViking Cloud API key can sign in, relay model requests through it and change the upstreams in their account. If this gateway is only for you or your team, set a gateway management key and restart the gateway.',
+ generate: 'Generate a key with:',
+ dismiss: 'Dismiss',
+ },
unavailable: {
notEnabled: {
- title: 'The OpenViking Gateway is turned off',
- description:
- 'This server has the OpenViking Gateway turned off. Turn it on in ov.conf, restart OpenViking, then start the gateway.',
- },
- tokenMissing: {
- title: 'The management token is missing',
- description:
- 'OpenViking needs the same management token as the gateway to manage it. Set this environment variable (at least 32 characters) for both OpenViking and the gateway, then restart them.',
- },
- tokenMismatch: {
- title: "The management tokens don't match",
+ title: 'The gateway is not enabled on this OpenViking server',
description:
- 'OpenViking and the gateway were started with different management tokens, so the gateway turns OpenViking away. Set this environment variable to the same value for both, then restart them.',
+ 'Run openviking-server init and choose Update gateway, or add the configuration below to ov.conf and restart OpenViking.',
},
- unsupported: {
- title: "This OpenViking server can't manage an OpenViking Gateway",
+ contact: 'Ask the person who deployed OpenViking to enable it.',
+ trusted: {
+ title: 'The gateway does not support Trusted mode',
description:
- 'Studio is connected to an OpenViking server without gateway support. Upgrade OpenViking Server, restart it, then retry.',
+ 'The gateway tells users apart by their API keys. Set server.auth_mode to api_key in ov.conf, then restart OpenViking.',
},
- devMode: {
- title: 'OpenViking runs in development mode',
+ openvikingUnreachable: {
+ title: 'The gateway cannot reach OpenViking ({{url}})',
description:
- 'In development mode every key acts as root, and the gateway refuses root keys, so no gateway key can be issued. Switch OpenViking to API key mode, restart it, then add an account admin key in Connection settings.',
- },
- unreachable: {
- title: "OpenViking can't reach the gateway",
- description:
- 'The gateway is not running, or gateway.url in ov.conf points to the wrong address. Start the gateway and check that OpenViking can reach that address.',
+ "Make sure OpenViking is running and that the gateway's openviking_url (in gateway.conf or OPENVIKING_GATEWAY_OPENVIKING_URL) points to it, then retry.",
},
failed: {
title: "Couldn't load the OpenViking Gateway",
@@ -89,23 +115,75 @@ const common = {
terminal: 'Terminal',
environment: 'Environment variable',
docs: 'How to deploy',
+ enable: {
+ description:
+ 'Studio can turn it on for you: it saves the setting to ov.conf and restarts the server.',
+ descriptionManualRestart:
+ "Studio can save the setting to ov.conf. This server can't be restarted from Studio, so restart it yourself afterwards.",
+ action: 'Enable gateway',
+ confirmTitle: 'Enable the gateway?',
+ confirmRestart:
+ 'Studio writes gateway.enabled: true to ov.conf and restarts the server. Requests are interrupted for a few seconds while it restarts.',
+ confirmManualRestart:
+ 'Studio writes gateway.enabled: true to ov.conf. The gateway turns on after you restart the server.',
+ protect:
+ 'Only people with the gateway management key can change upstreams and context profiles',
+ protectHint:
+ 'Studio generates the key and saves it as gateway.management_key in ov.conf, then shows it to you once.',
+ checking: 'Reading ov.conf…',
+ saving: 'Saving ov.conf…',
+ restarting: 'Saving ov.conf and restarting the server…',
+ savedRestart:
+ 'Saved to ov.conf. Restart the server to turn the gateway on, then choose Retry.',
+ readOnly:
+ "ov.conf on this server is read-only (for example, mounted from a Helm ConfigMap), so Studio can't change it. Turn the gateway on in your deployment, then restart the server:",
+ helm: 'Helm values',
+ stillOff:
+ 'The server restarted, but the gateway is still off. Check whether OPENVIKING_GATEWAY_ENABLED is set to a false value; it overrides ov.conf.',
+ rolledBack:
+ 'The server rejected the new configuration and kept the old one, so the gateway is still off. Check the server log for the reason.',
+ conflict:
+ 'ov.conf changed after this page loaded. Reload it and try again.',
+ reload: 'Reload ov.conf',
+ failed: "Couldn't enable the gateway: {{message}}",
+ restartFailed:
+ "ov.conf was saved, but Studio couldn't confirm the restart: {{message}}. Check the server, then choose Retry.",
+ keyTitle: 'Save your gateway management key',
+ keyOnce:
+ 'Studio shows it only this once. You need it to change upstreams and context profiles; this browser tab stays unlocked until you close it.',
+ copyKey: 'Copy gateway management key',
+ copyFailed:
+ "Couldn't copy. The key is selected; press Ctrl+C or ⌘C to copy it.",
+ keyOnceManual:
+ 'Studio shows it only this once. You need it to change upstreams and context profiles; after you restart the server, choose Enter gateway management key on the gateway page and paste it.',
+ keySaved: 'I saved it',
+ continue: 'I saved it, open the gateway',
+ },
},
errors: {
reasons: {
- not_enabled: 'The OpenViking Gateway is turned off on this server.',
- token_missing:
- "OpenViking can't manage the gateway because the management token isn't set.",
- token_mismatch:
- "The gateway rejected OpenViking's management token. Both must use the same token.",
- unreachable: "OpenViking can't reach the gateway.",
- unsupported:
- "This OpenViking server doesn't support the OpenViking Gateway.",
+ management_key_required:
+ 'Upstreams and profiles are provided by your gateway admin. Enter the gateway management key to change them.',
+ management_key_invalid:
+ 'The gateway management key is incorrect. Check with whoever deployed this gateway.',
+ vlm_import_forbidden:
+ 'You do not have permission to import OpenViking model settings.',
+ vlm_import_unavailable:
+ "This gateway doesn't run inside OpenViking, so it can't read the server's model settings. Add upstreams manually.",
+ in_use_one: '{{count}} key still uses this.',
+ in_use_other: '{{count}} keys still use this.',
+ upstream_key_missing:
+ "This upstream has no stored API key (or clients send their own), so the gateway can't run a test.",
+ trusted_mode_unsupported: 'The gateway does not support Trusted mode.',
+
+ not_enabled: 'The gateway is not enabled on this OpenViking server.',
conflict: 'This change conflicts with existing settings.',
invalid:
'The gateway rejected these settings. Check the values and try again.',
forbidden: "You don't have permission to do this.",
not_found: 'This item no longer exists. Refresh and try again.',
- unauthorized: 'Your key was rejected. Check Connection settings.',
+ unauthorized:
+ 'Your OpenViking API key was rejected. Check Connection settings.',
other: 'Something went wrong. Try again.',
},
inUse: 'Keys still use this. Revoke those keys first.',
@@ -118,12 +196,11 @@ const common = {
keyNotFound:
'The gateway key this conversation used has been revoked, so it can no longer be resynced.',
sessionNotFound: 'The gateway no longer has this conversation.',
- upstreamKeyMissing:
- 'There is no stored API key to test with. Clients of this upstream send their own key, or the key has not been set.',
subscriptionKey:
"Claude subscription logins aren't supported. Use a model API key.",
},
validation: {
+ anthropicBaseUrl: 'Remove the trailing /v1 to save',
required: 'Required',
number: 'Enter a number',
integer: 'Enter a whole number',
@@ -170,6 +247,7 @@ const common = {
keyValue: {
add: 'Add',
remove: 'Remove',
+ none: 'None',
duplicate: 'Listed twice; only the last one is kept',
},
tags: {
diff --git a/web-studio/src/i18n/locales/en/gateway/connect.ts b/web-studio/src/i18n/locales/en/gateway/connect.ts
index 69e5e5551..b8c66b5de 100644
--- a/web-studio/src/i18n/locales/en/gateway/connect.ts
+++ b/web-studio/src/i18n/locales/en/gateway/connect.ts
@@ -10,13 +10,17 @@ const connect = {
openai: 'OpenAI-compatible clients and SDKs',
loopback: {
title: "Only the gateway's own machine can use this address",
- description:
- "Clients on other machines can't reach it. Set `gateway.public_url` in `ov.conf` to an address they can reach, then restart the gateway.",
+ embedded:
+ "Clients on other machines can't reach it. Set `gateway.public_url` in `ov.conf` to an address they can reach (without `/gateway`), then restart the server.",
+ standalone:
+ "Clients on other machines can't reach it. Set `public_url` in `gateway.conf`, or `OPENVIKING_GATEWAY_PUBLIC_URL`, to an address they can reach (without `/gateway`), then restart the gateway.",
},
notPublic: {
title: 'Clients may not be able to reach this address',
- description:
- 'This is the address OpenViking uses to reach the gateway. Set `gateway.public_url` in `ov.conf` to the address clients should use, then restart the gateway.',
+ embedded:
+ 'This is the address your browser used to open Studio. Set `gateway.public_url` in `ov.conf` to the address clients should use (without `/gateway`), then restart the server.',
+ standalone:
+ 'This is the address your browser used to open Studio. Set `public_url` in `gateway.conf`, or `OPENVIKING_GATEWAY_PUBLIC_URL`, to the address clients should use (without `/gateway`), then restart the gateway.',
},
keys: 'Clients authenticate with a gateway key (`ovgw_…`) in place of a provider API key.',
manageKeys: 'Manage keys',
diff --git a/web-studio/src/i18n/locales/en/gateway/enums.ts b/web-studio/src/i18n/locales/en/gateway/enums.ts
index 6310acb27..66ebacead 100644
--- a/web-studio/src/i18n/locales/en/gateway/enums.ts
+++ b/web-studio/src/i18n/locales/en/gateway/enums.ts
@@ -85,8 +85,9 @@ const enums = {
errorCode: 'OpenViking reported error {{code}}',
versionMismatch: 'OpenViking is older than the gateway requires',
identityMissing: "OpenViking couldn't tell which user this key belongs to",
- rootKey: "Root keys aren't accepted. Use a user key from this account.",
- otherAccount: 'This OpenViking key belongs to another account.',
+ rootKey:
+ "Root API keys aren't accepted. Use a user API key from this account.",
+ otherAccount: 'This OpenViking API key belongs to another account.',
},
degradation: {
memory_store_failure: {
@@ -155,6 +156,12 @@ const enums = {
"The streamed reply couldn't be read, so it wasn't saved to OpenViking. The client wasn't affected.",
action: 'No action needed unless it happens often.',
},
+ revocation_check_unavailable: {
+ label: 'Key not verified',
+ explanation:
+ "OpenViking couldn't confirm the gateway key, so the request was served without checking whether the key was revoked.",
+ action: 'Check that OpenViking is reachable and healthy.',
+ },
},
}
diff --git a/web-studio/src/i18n/locales/en/gateway/keys.ts b/web-studio/src/i18n/locales/en/gateway/keys.ts
index 4f5541f8b..e180ba237 100644
--- a/web-studio/src/i18n/locales/en/gateway/keys.ts
+++ b/web-studio/src/i18n/locales/en/gateway/keys.ts
@@ -1,9 +1,12 @@
const keys = {
description:
- "Each gateway key belongs to one OpenViking user and uses one context profile and a set of upstreams. Keys can't be edited — issue a new key and revoke the old one.",
+ "Each gateway key (starting with ovgw_) belongs to one OpenViking user and uses one context profile and a set of upstreams. Keys can't be edited — issue a new key and revoke the old one.",
issue: 'Issue key',
loadFailed: "Couldn't load gateway keys",
prerequisites: {
+ managed:
+ "Your gateway admin hasn't added upstreams or context profiles yet.",
+ unlock: 'Enter gateway management key',
upstream: 'Add an upstream before issuing a key.',
profile: 'Create a context profile before issuing a key.',
both: 'Add an upstream and create a context profile before issuing a key.',
@@ -44,9 +47,9 @@ const keys = {
deleteUser: {
title: "Delete {{user}}'s gateway data?",
description_one:
- "This revokes {{user}}'s gateway key and deletes the conversation state the gateway keeps for this user, including turns not yet saved to OpenViking. Their clients lose access immediately. Memories already in OpenViking are not affected.",
+ "This revokes {{user}}'s gateway key and deletes their request logs and the conversation state the gateway keeps for this user, including turns not yet saved to OpenViking. Their clients lose access immediately. Memories already in OpenViking are not affected.",
description_other:
- 'This revokes all {{count}} gateway keys of {{user}} and deletes the conversation state the gateway keeps for this user, including turns not yet saved to OpenViking. Their clients lose access immediately. Memories already in OpenViking are not affected.',
+ 'This revokes all {{count}} gateway keys of {{user}} and deletes their request logs and the conversation state the gateway keeps for this user, including turns not yet saved to OpenViking. Their clients lose access immediately. Memories already in OpenViking are not affected.',
confirm: 'Delete gateway data',
done: "Deleted {{user}}'s gateway data",
},
@@ -61,29 +64,34 @@ const keys = {
'Helps you tell keys apart. The person and the client make a good name.',
},
user: {
- label: 'OpenViking user',
+ self: 'Read and write memory as you ({{user}}).',
+ developmentIdentity: 'Read and write memory as {{user}}.',
+ label: 'Who is this for?',
placeholder: 'Choose an OpenViking user',
loading: 'Loading users…',
description:
- 'The gateway recalls and saves memory as this user. Their OpenViking key is read on the server, stored encrypted by the gateway and never shown.',
+ 'The gateway recalls and saves memory as this user. Their user API key is read on the server, stored encrypted by the gateway and never shown.',
roles: {
admin: 'Admin',
user: 'User',
},
- unavailable: "Key can't be read on the server; paste it instead",
+ unavailable:
+ "The server can't read this user's API key; paste it instead",
loadFailed:
- "Couldn't load this account's users, so paste the key instead.",
- none: "The server can't read the keys of this account's users, so paste the key instead.",
- root: "With the root key you can't choose a user here, so paste the key instead.",
+ "Couldn't load this account's users, so paste the user API key instead.",
+ none: "The server can't read the user API keys of this account's users, so paste one instead.",
choose: 'Choose a user',
},
openvikingKey: {
- label: 'OpenViking key',
+ forUser: "Paste {{user}}'s user API key",
+ managementKey:
+ "This is a gateway management key. Paste this user's user API key instead.",
+ label: 'OpenViking API key',
description:
- "An OpenViking user key from this account. The gateway recalls and saves memory as this user. Root keys aren't accepted. Stored encrypted and never shown again.",
+ "The user API key of a user in this account. The gateway recalls and saves memory as this user. Root API keys aren't accepted. Stored encrypted and never shown again.",
gatewayKey:
- "This is a gateway key. Enter the OpenViking user's own key instead.",
- paste: 'Paste an OpenViking key',
+ "This is a gateway key (for clients). Paste this user's user API key instead.",
+ paste: 'Paste a user API key',
},
profile: {
label: 'Context profile',
@@ -100,6 +108,7 @@ const keys = {
required: 'Choose at least one upstream',
empty: 'There are no upstreams yet.',
create: 'Add one',
+ blocked: 'Blocked',
off: 'Off',
},
models: {
@@ -111,11 +120,12 @@ const keys = {
submit: 'Issue key',
},
errors: {
+ requiredVersion: 'Required version: {{version}}.',
title: "Couldn't issue the key",
rootKey:
- 'This is a root key. Use the key of an OpenViking user in this account.',
+ 'This is a root API key. Use the user API key of a user in this account.',
otherAccount:
- 'This OpenViking key belongs to another account. Use a user key from this account.',
+ 'This OpenViking API key belongs to another account. Use a user API key from this account.',
invalidKey:
"OpenViking rejected this key. Check that it's complete and hasn't been regenerated.",
unavailable:
@@ -123,14 +133,18 @@ const keys = {
versionMismatch:
'OpenViking is older than the gateway requires. Upgrade OpenViking, then try again.',
unknownUser: 'This user is no longer in this account. Choose another user.',
+ userRequired:
+ 'A root API key has no user of its own. Choose the user this key is for.',
userKeyUnreadable:
- "The server can't read this user's OpenViking key. Paste the key instead.",
+ 'The server only stores a hash of this user’s API key and cannot read it. Paste their user API key instead.',
},
secret: {
+ identity: 'This key reads and writes memory as {{user}}.',
+ dependency:
+ "It's tied to {{user}}'s current user API key. If that key is regenerated, this gateway key stops working and you'll need to issue a new one.",
title: 'Copy your gateway key',
once: 'This is the only time the full key is shown.',
copyKey: 'Copy gateway key',
- user: 'OpenViking user',
profile: 'Context profile',
connectTitle: 'Connect a client',
clients: {
diff --git a/web-studio/src/i18n/locales/en/gateway/overview.ts b/web-studio/src/i18n/locales/en/gateway/overview.ts
index a37359156..ef89438bf 100644
--- a/web-studio/src/i18n/locales/en/gateway/overview.ts
+++ b/web-studio/src/i18n/locales/en/gateway/overview.ts
@@ -8,6 +8,23 @@ const overview = {
sampleNote_other:
'Figures cover the latest {{limit}} entries of the request log. Entries are kept for {{count}} days.',
setup: {
+ providedUpstreams_one: '{{count}} upstream provided by your gateway admin',
+ providedUpstreams_other:
+ '{{count}} upstreams provided by your gateway admin',
+ importedUpstreams_one:
+ "{{count}} upstream, imported from OpenViking's model settings",
+ importedUpstreams_other:
+ "{{count}} upstreams, imported from OpenViking's model settings",
+ someImportedUpstreams:
+ "{{count}} upstreams, {{imported}} of them imported from OpenViking's model settings",
+ waitUpstreams: 'Waiting for your gateway admin to add an upstream',
+ providedProfiles_one: '{{count}} profile provided by your gateway admin',
+ providedProfiles_other: '{{count}} profiles provided by your gateway admin',
+ waitProfiles: 'Waiting for your gateway admin to add a profile',
+ codingPlan:
+ '{{name}} is a Coding Plan upstream. Requests to it are blocked until you confirm the plan allows it.',
+ confirm: 'Review',
+
title: 'Get started',
description:
'Four steps to the first conversation with memory. This card goes away once a client sends its first request.',
@@ -34,6 +51,8 @@ const overview = {
description:
'Clients use this key to call the gateway. It belongs to one OpenViking user, whose memory the gateway reads and writes.',
blocked: 'Add an upstream and a context profile first.',
+ waiting:
+ 'You can issue a key once your gateway admin adds an upstream and a profile.',
done_one: '{{count}} key issued',
done_other: '{{count}} keys issued',
action: 'Issue key',
@@ -78,14 +97,6 @@ const overview = {
description:
'Finds memory for new messages and stores saved conversations.',
version: 'Version',
- authMode: 'Authentication',
- authModes: {
- api_key: 'API key mode',
- trusted: 'Trusted mode',
- dev: 'Development mode',
- oidc: 'OIDC mode',
- ldap: 'LDAP mode',
- },
unreachable:
"While OpenViking can't be reached, requests still go to the model without memory, and saving conversations is retried until it's back.",
starting:
diff --git a/web-studio/src/i18n/locales/en/gateway/profiles.ts b/web-studio/src/i18n/locales/en/gateway/profiles.ts
index 116b6393b..30f311638 100644
--- a/web-studio/src/i18n/locales/en/gateway/profiles.ts
+++ b/web-studio/src/i18n/locales/en/gateway/profiles.ts
@@ -1,4 +1,6 @@
const profiles = {
+ inUseHelp:
+ 'To delete it, revoke those keys first. If they are still needed, issue replacements that use another profile.',
description:
'How conversations use OpenViking memory and tools. Saved changes apply only to conversations that start afterwards.',
defaultName: 'Default',
@@ -18,6 +20,7 @@ const profiles = {
title: 'No context profiles yet',
description:
'Every gateway key needs a context profile. The recommended settings recall memory for each new message, save conversations, summarize long ones and let the model use the read-only OpenViking tools. You can change them at any time.',
+ readOnly: 'Waiting for your gateway admin to add a profile.',
},
summary: {
recallOn: 'On · {{tokens}} tokens per message',
diff --git a/web-studio/src/i18n/locales/en/gateway/upstreams.ts b/web-studio/src/i18n/locales/en/gateway/upstreams.ts
index 4a256e7f7..951049a42 100644
--- a/web-studio/src/i18n/locales/en/gateway/upstreams.ts
+++ b/web-studio/src/i18n/locales/en/gateway/upstreams.ts
@@ -1,4 +1,42 @@
const upstreams = {
+ import: {
+ action: 'Import from OpenViking',
+ useSettings: "Use OpenViking's model settings",
+ hint: "Uses the server's VLM settings",
+ running: 'Importing…',
+ summary_one: 'Imported or updated {{count}} upstream.',
+ summary_other: 'Imported or updated {{count}} upstreams.',
+ nothing: "OpenViking's model settings have nothing to import.",
+ needsConfirmation:
+ 'These Coding Plan upstreams stay blocked until you confirm the plan allows use through the gateway:',
+ skipped_one: '{{count}} credential was not imported:',
+ skipped_other: '{{count}} credentials were not imported:',
+ confirm: 'Review',
+ dismiss: 'Dismiss',
+ repeat:
+ "Importing again updates addresses and credentials from OpenViking's settings without creating duplicates. Your changes to the enabled state, priority and models are kept.",
+ reasons: {
+ invalid_configuration:
+ 'The model configuration is invalid. Check the server settings and import again.',
+ openai_codex:
+ 'Codex OAuth credentials refresh periodically and cannot be used long term by the gateway. Add an upstream manually.',
+ azure:
+ 'Azure OpenAI requires an api-version parameter that the gateway does not support yet. Add an upstream manually.',
+ litellm_no_api_base:
+ 'This LiteLLM credential has no api_base. Add api_base to the server configuration and import again.',
+ litellm_unsupported_route:
+ "This LiteLLM route doesn't speak an OpenAI-compatible protocol, so the gateway can't forward to it. Add an upstream manually.",
+ unknown:
+ 'This credential could not be imported. Check the server model settings.',
+ },
+ },
+ readOnly: {
+ empty: 'Waiting for your gateway admin to add an upstream.',
+ managedKey: 'Your gateway admin keeps the API key.',
+ clientKey: 'Each client sends its own API key.',
+ codingAllowed: 'Coding Plan, allowed by your gateway admin',
+ codingBlocked: 'Coding Plan, requests blocked',
+ },
description:
'Model providers the gateway forwards requests to. Each upstream speaks one protocol; requests are never converted.',
add: 'Add upstream',
@@ -50,6 +88,7 @@ const upstreams = {
'Each client sends its own key, so there is no stored key to test with.',
noKey: 'Add an API key first.',
result: {
+ unverified: 'Reachable, key unverified · {{status}}',
ok: 'Reachable · {{status}}',
failed: 'Failed · {{status}}',
unreachable: 'Unreachable',
@@ -58,20 +97,27 @@ const upstreams = {
explain: {
ok: 'The provider accepted the key and returned its model list.',
auth: 'The provider rejected the API key or one of the headers.',
+ rateLimited:
+ 'The address is reachable, but the provider is rate limiting requests. The key has not been verified.',
notFound:
- "There is no model list at this address. Check the base URL; if the provider doesn't offer a model list, real requests may still work.",
+ 'The address is reachable, but the provider does not offer a model list. The API key has not been verified.',
status: 'The provider answered with HTTP {{status}}.',
unreachable:
"The gateway couldn't connect within 10 seconds. Check the base URL and the network between the gateway and the provider.",
},
},
delete: {
+ disable: 'Disable',
+ disableHint:
+ 'You can disable it instead; those keys stop reaching it right away.',
+ inUse_one: '{{count}} key still uses this upstream.',
+ inUse_other: '{{count}} keys still use this upstream.',
action: 'Delete',
blocked_one: 'Used by {{count}} key — revoke it first',
blocked_other: 'Used by {{count}} keys — revoke them first',
title: 'Delete “{{name}}”?',
description:
- 'The upstream is deleted together with its stored API key and headers. No gateway key uses it, so no client is affected.',
+ "The upstream is deleted together with its stored API key and headers. It can't be deleted while keys still use it.",
confirm: 'Delete upstream',
},
toast: {
@@ -91,7 +137,7 @@ const upstreams = {
description:
'It may have been deleted. Go back to the list to see the current upstreams.',
},
- missing: 'Still needed: {{fields}}',
+ missing: 'Still to fill in or fix: {{fields}}',
separator: ', ',
create: 'Add upstream',
},
@@ -138,16 +184,22 @@ const upstreams = {
hints: {
deepseek:
'With tools present, DeepSeek needs the reasoning of every earlier reply. The gateway restores what clients drop, so OpenViking tools work; if you turn that off below, they are only offered when a request turns thinking off.',
- ark: "Enter the Ark address without a path, such as https://ark.cn-beijing.volces.com. The gateway adds /api/v3 or /api/compatible/v1 for each protocol and keeps each conversation's prompt_cache_key stable so the cache keeps hitting.",
+ ark: 'For Chat and Responses use https://ark.cn-beijing.volces.com/api/v3; for Anthropic use https://ark.cn-beijing.volces.com/api/compatible. Coding Plan paths are /api/coding/v3 and /api/coding respectively. The gateway keeps each conversation’s prompt_cache_key stable for cache hits.',
byteplus:
- "Enter the ModelArk address without a path, such as https://ark.ap-southeast.bytepluses.com. The gateway adds /api/v3 or /api/compatible/v1 for each protocol and keeps each conversation's prompt_cache_key stable so the cache keeps hitting.",
+ 'For Chat and Responses use https://ark.ap-southeast.bytepluses.com/api/v3; for Anthropic use https://ark.ap-southeast.bytepluses.com/api/compatible. Coding Plan paths are /api/coding/v3 and /api/coding respectively. The gateway keeps each conversation’s prompt_cache_key stable for cache hits.',
},
},
baseUrl: {
label: 'Base URL',
description:
- "The provider's API address, filled in when you choose a provider. It works with or without a trailing /v1.",
+ "Use base_url from the provider's SDK documentation. The gateway appends /chat/completions, /responses or /v1/messages. Add separate upstreams when a provider uses different base URLs for different protocols.",
preview: 'Requests go to',
+ missingPath:
+ 'This provider needs a path in base_url. A domain alone sends requests to the wrong address.',
+ anthropicVersion:
+ 'Anthropic base_url must omit /v1. The gateway appends /v1/messages.',
+ removeVersion: 'Remove /v1',
+ correctPath: 'Use {{url}}',
useDefault: 'Use default',
},
authMode: {
@@ -167,6 +219,8 @@ const upstreams = {
placeholder: 'Paste the provider API key',
stored: 'Key stored',
description: 'Stored encrypted and never shown again.',
+ addressChanged:
+ 'The address has changed. Enter the API key again. The stored API key will not be sent to the new address.',
storedDescription:
'Stored encrypted. Leave blank to keep it, or paste a new key to replace it.',
},
@@ -177,16 +231,18 @@ const upstreams = {
name: 'Header name',
value: 'Value',
add: 'Add header',
+ addressChanged:
+ "The address changed, so enter the header values again. Values stored for the old address aren't sent to the new one.",
},
codingPlan: {
label: 'This key is a Coding Plan or subscription key',
description:
"Subscription keys are usually licensed for the provider's own tools only.",
warning:
- 'While this is checked, the gateway rejects every request to this upstream. Use a model API key instead, or allow it if your plan permits use from other clients.',
- allow: 'Allow it anyway',
+ 'By default the gateway rejects every request to this upstream. Use a model API key instead, or, if your plan permits use outside the provider’s tools, turn on the option below.',
+ allow: 'Allow this plan through the gateway',
allowDescription:
- 'Requests are forwarded with this key. Make sure your plan allows it.',
+ 'Some Coding Plans only authorize use in the provider’s own tools. Check that your plan permits this before enabling it, or the provider may restrict your account.',
},
models: {
label: 'Models',
diff --git a/web-studio/src/i18n/locales/en/workspace.ts b/web-studio/src/i18n/locales/en/workspace.ts
index 972091f85..0eeb430c5 100644
--- a/web-studio/src/i18n/locales/en/workspace.ts
+++ b/web-studio/src/i18n/locales/en/workspace.ts
@@ -782,6 +782,22 @@ const workspace = {
},
},
settings: {
+ gatewayConnection: {
+ title: 'Sign in to OpenViking Gateway',
+ openvikingUrl: 'This gateway uses OpenViking at {{url}}',
+ apiKey: 'OpenViking API key',
+ keyHint: 'A user, account admin or root API key all work.',
+ wrongKey:
+ "Gateway keys (ovgw_) and gateway management keys (ovgm_) can't be used to sign in. Enter an OpenViking API key.",
+ invalidKey:
+ 'OpenViking rejected this API key. Check the key and try again.',
+ unreachable:
+ "The gateway can't reach OpenViking ({{url}}). Make sure OpenViking is running and the gateway's openviking_url (in gateway.conf or OPENVIKING_GATEWAY_OPENVIKING_URL) points to it, then try again.",
+ gatewayUnreachable:
+ "Can't reach this gateway. Make sure it is running, then try again.",
+ connect: 'Sign in',
+ connecting: 'Signing in…',
+ },
pageTitle: 'Settings',
tabs: { connection: 'Connection', configuration: 'Server configuration' },
models: {
diff --git a/web-studio/src/i18n/locales/zh-CN/gateway/common.ts b/web-studio/src/i18n/locales/zh-CN/gateway/common.ts
index 81b5517de..c7d4f3904 100644
--- a/web-studio/src/i18n/locales/zh-CN/gateway/common.ts
+++ b/web-studio/src/i18n/locales/zh-CN/gateway/common.ts
@@ -31,7 +31,10 @@ const common = {
retry: '重试',
revoke: '吊销',
save: '保存',
+ view: '查看',
+ back: '返回',
viewAll: '查看全部',
+ viewKeys: '查看密钥',
},
states: {
loading: '加载中…',
@@ -46,41 +49,60 @@ const common = {
failed: '复制失败,请选中文本后手动复制。',
},
access: {
- title: '需要账号管理员权限',
+ title: '先连接 OpenViking',
+ invalid: 'OpenViking API 密钥无效',
description:
- '管理 OpenViking 网关需要本账号的账号管理员密钥或 Root 密钥。请先在连接设置中填写。',
+ '网关用你的 OpenViking API 密钥确认你是谁。请先在连接设置中填写它。',
+ invalidDescription:
+ 'OpenViking 拒绝了连接设置中的 API 密钥,它可能已被重新生成或删除。请换一个有效的密钥。',
action: '打开连接设置',
},
+ management: {
+ title: '输入网关管理密钥',
+ label: '网关管理密钥',
+ description:
+ '网关管理密钥由部署这台网关的人设置,用来修改上游和上下文配置。它不是 OpenViking API 密钥,也不是客户端用的网关密钥。',
+ where: '在哪里找?',
+ prefix:
+ 'openviking-server init 和 openviking-gateway init 生成的值以 ovgm_ 开头。',
+ environment: '也可能设在环境变量里,它优先于配置文件:',
+ keyPlaceholder: '<至少 32 个字符>',
+ session: '只保存在当前浏览器标签页,关闭后自动锁定。',
+ wrongKey: '这是网关密钥(给客户端用的),请输入网关管理密钥。',
+ invalid:
+ '网关管理密钥不正确。请向部署这台网关的人确认。注意,这里要填的不是 OpenViking 的管理员 API 密钥。',
+ unlock: '解锁',
+ unlocked: '已解锁,现在可以修改上游和上下文配置',
+ lock: '锁定',
+ editing: '可修改上游和上下文配置',
+ expired: '网关管理密钥已失效,上游和上下文配置恢复为只读。',
+ readOnly:
+ '上游和上下文配置由网关管理员统一提供。你可以查看、测试连接,并在签发密钥时选用。',
+ adminReadOnly: 'OpenViking 的管理员和 Root 也需要网关管理密钥才能修改。',
+ shared:
+ '你正在修改本账号所有用户共用的配置,保存后立即对使用它的密钥生效。',
+ publicTitle: '这台网关对所有 OpenViking 商业版用户开放',
+ publicDescription:
+ '它连接的是公共 OpenViking 服务,又没有设置网关管理密钥,所以任何持有商业版 API 密钥的人都能登录这台网关、用它转发模型请求,还能修改自己账号下的上游。如果这台网关只给你自己或团队使用,请设置网关管理密钥,然后重启网关。',
+ generate: '可以用这条命令生成密钥:',
+ dismiss: '关闭提示',
+ },
unavailable: {
notEnabled: {
- title: 'OpenViking 网关未开启',
- description:
- '这台服务器没有开启 OpenViking 网关。请在 ov.conf 中开启它,重启 OpenViking,再启动网关。',
- },
- tokenMissing: {
- title: '缺少管理令牌',
- description:
- 'OpenViking 需要和网关使用同一个管理令牌才能管理网关。请为 OpenViking 和网关设置下面的环境变量(至少 32 个字符),然后重启两者。',
- },
- tokenMismatch: {
- title: '管理令牌不一致',
- description:
- 'OpenViking 和网关启动时用的管理令牌不同,所以网关拒绝了 OpenViking 的请求。请把下面的环境变量设成同一个值,然后重启两者。',
- },
- unsupported: {
- title: '这台 OpenViking 服务器无法管理 OpenViking 网关',
+ title: '这台 OpenViking 没有开启网关',
description:
- 'Studio 连接的 OpenViking 服务器不支持 OpenViking 网关。请升级 OpenViking Server 并重启,然后重试。',
+ '运行 openviking-server init 并选择 Update gateway;也可以在 ov.conf 中加入下面的配置,然后重启 OpenViking。',
},
- devMode: {
- title: 'OpenViking 运行在开发模式',
+ contact: '请联系部署 OpenViking 的人开启网关。',
+ trusted: {
+ title: '网关不支持 Trusted 模式',
description:
- '开发模式下每个密钥都以 Root 身份操作,而网关不接受 Root 密钥,所以签发不了网关密钥。请把 OpenViking 切换到 API 密钥模式并重启,再到连接设置中填写账号管理员密钥。',
+ '网关要靠 API 密钥识别每个用户。请在 ov.conf 中把 server.auth_mode 改为 api_key,然后重启 OpenViking。',
},
- unreachable: {
- title: 'OpenViking 连不上网关',
+ openvikingUnreachable: {
+ title: '网关连不上 OpenViking({{url}})',
description:
- '网关没有运行,或者 ov.conf 里的 gateway.url 指向了错误的地址。请启动网关,并确认 OpenViking 能访问这个地址。',
+ '确认 OpenViking 正在运行,并检查网关的 openviking_url(gateway.conf 或 OPENVIKING_GATEWAY_OPENVIKING_URL)是否指向它,然后重试。',
},
failed: {
title: '无法加载 OpenViking 网关',
@@ -89,20 +111,67 @@ const common = {
terminal: '终端',
environment: '环境变量',
docs: '部署说明',
+ enable: {
+ description: 'Studio 可以直接开启:把设置写入 ov.conf,然后重启服务。',
+ descriptionManualRestart:
+ 'Studio 可以把设置写入 ov.conf。这台服务不能从 Studio 重启,保存后请自行重启。',
+ action: '开启网关',
+ confirmTitle: '开启网关?',
+ confirmRestart:
+ 'Studio 会在 ov.conf 中写入 gateway.enabled: true,然后重启服务。重启期间请求会中断几秒。',
+ confirmManualRestart:
+ 'Studio 会在 ov.conf 中写入 gateway.enabled: true。重启服务后网关才会开启。',
+ protect: '只有持有网关管理密钥的人才能修改上游和上下文配置',
+ protectHint:
+ 'Studio 会生成密钥,写入 ov.conf 的 gateway.management_key,保存后只显示一次。',
+ checking: '正在读取 ov.conf…',
+ saving: '正在保存 ov.conf…',
+ restarting: '正在保存 ov.conf 并重启服务…',
+ savedRestart:
+ '已保存到 ov.conf。重启服务后网关才会开启,重启完成后点“重试”。',
+ readOnly:
+ '这台服务的 ov.conf 是只读的(例如由 Helm ConfigMap 挂载),Studio 改不了它。请在部署配置中开启网关,然后重启服务:',
+ helm: 'Helm values',
+ stillOff:
+ '服务已重启,但网关仍未开启。请检查 OPENVIKING_GATEWAY_ENABLED 是否设成了 false 之类的值,它会覆盖 ov.conf。',
+ rolledBack:
+ '服务拒绝了新配置,继续使用原来的配置,所以网关仍未开启。原因请查看服务日志。',
+ conflict: 'ov.conf 在页面加载后被改过,请重新读取后再试。',
+ reload: '重新读取 ov.conf',
+ failed: '开启网关失败:{{message}}',
+ restartFailed:
+ 'ov.conf 已保存,但无法确认服务是否重启成功:{{message}}。请检查服务状态,然后点“重试”。',
+ keyTitle: '保存网关管理密钥',
+ keyOnce:
+ '密钥只显示这一次。修改上游和上下文配置时需要它;关闭这个浏览器标签页之前,当前页面保持解锁。',
+ copyKey: '复制网关管理密钥',
+ copyFailed: '复制失败,密钥已选中,请按 Ctrl+C 或 ⌘C 复制。',
+ keyOnceManual:
+ '密钥只显示这一次。修改上游和上下文配置时需要它;重启服务后,在网关页面点“输入网关管理密钥”并粘贴。',
+ keySaved: '已保存',
+ continue: '已保存,打开网关',
+ },
},
errors: {
reasons: {
- not_enabled: '这台服务器没有开启 OpenViking 网关。',
- token_missing: '没有设置管理令牌,OpenViking 无法管理网关。',
- token_mismatch:
- '网关拒绝了 OpenViking 的管理令牌,两者必须使用同一个令牌。',
- unreachable: 'OpenViking 连不上网关。',
- unsupported: '这台 OpenViking 服务器不支持 OpenViking 网关。',
+ management_key_required:
+ '上游和上下文配置由网关管理员统一提供,输入网关管理密钥后才能修改。',
+ management_key_invalid: '网关管理密钥不正确,请向部署这台网关的人确认。',
+ vlm_import_forbidden: '你没有导入 OpenViking 模型配置的权限。',
+ vlm_import_unavailable:
+ '这台网关不在 OpenViking 服务内运行,读不到服务端的模型配置,请手动添加上游。',
+ in_use_one: '仍有 {{count}} 个密钥在使用它。',
+ in_use_other: '仍有 {{count}} 个密钥在使用它。',
+ upstream_key_missing:
+ '这个上游没有保存 API Key,或者由客户端自带 API Key,网关无法发起测试。',
+ trusted_mode_unsupported: '网关不支持 Trusted 模式。',
+
+ not_enabled: '这台 OpenViking 没有开启网关。',
conflict: '这项修改与现有配置冲突。',
invalid: '网关拒绝了这些设置,请检查填写的值后重试。',
forbidden: '没有执行此操作的权限。',
not_found: '该项已不存在,请刷新后重试。',
- unauthorized: '密钥被拒绝,请检查连接设置。',
+ unauthorized: 'OpenViking API 密钥被拒绝,请检查连接设置。',
other: '操作失败,请重试。',
},
inUse: '仍有密钥在使用它,请先吊销这些密钥。',
@@ -112,11 +181,10 @@ const common = {
unknownUpstream: '所选的上游中有一个已不存在。',
keyNotFound: '这段对话使用的网关密钥已被吊销,无法再重新同步。',
sessionNotFound: '网关中已没有这段对话的记录。',
- upstreamKeyMissing:
- '没有可用于测试的已保存 API Key:这个上游由客户端自带 API Key,或者还没有填写 API Key。',
subscriptionKey: '不支持 Claude 订阅登录,请使用模型 API Key。',
},
validation: {
+ anthropicBaseUrl: '去掉末尾的 /v1 才能保存',
required: '必填',
number: '请输入数字',
integer: '请输入整数',
@@ -162,6 +230,7 @@ const common = {
keyValue: {
add: '添加',
remove: '移除',
+ none: '未设置',
duplicate: '名称重复,只保留最后一项',
},
tags: {
diff --git a/web-studio/src/i18n/locales/zh-CN/gateway/connect.ts b/web-studio/src/i18n/locales/zh-CN/gateway/connect.ts
index f17a1654b..fe0cd13ae 100644
--- a/web-studio/src/i18n/locales/zh-CN/gateway/connect.ts
+++ b/web-studio/src/i18n/locales/zh-CN/gateway/connect.ts
@@ -10,13 +10,17 @@ const connect = {
openai: 'OpenAI 兼容的客户端和 SDK',
loopback: {
title: '只有网关所在的机器能使用这个地址',
- description:
- '其他机器上的客户端连不上它。请在 `ov.conf` 中把 `gateway.public_url` 设为它们能访问的地址,然后重启网关。',
+ embedded:
+ '其他机器上的客户端连不上它。请在 `ov.conf` 中把 `gateway.public_url` 设为它们能访问的地址(不带 `/gateway`),然后重启服务。',
+ standalone:
+ '其他机器上的客户端连不上它。请把 `gateway.conf` 中的 `public_url` 或环境变量 `OPENVIKING_GATEWAY_PUBLIC_URL` 设为它们能访问的地址(不带 `/gateway`),然后重启网关。',
},
notPublic: {
title: '客户端可能连不上这个地址',
- description:
- '这是 OpenViking 访问网关用的地址。请在 `ov.conf` 中把 `gateway.public_url` 设为客户端应该使用的地址,然后重启网关。',
+ embedded:
+ '这是浏览器打开 Studio 时使用的地址。请在 `ov.conf` 中把 `gateway.public_url` 设为客户端应该使用的地址(不带 `/gateway`),然后重启服务。',
+ standalone:
+ '这是浏览器打开 Studio 时使用的地址。请把 `gateway.conf` 中的 `public_url` 或环境变量 `OPENVIKING_GATEWAY_PUBLIC_URL` 设为客户端应该使用的地址(不带 `/gateway`),然后重启网关。',
},
keys: '客户端用网关密钥(`ovgw_…`)认证,代替服务商的 API Key。',
manageKeys: '管理密钥',
diff --git a/web-studio/src/i18n/locales/zh-CN/gateway/enums.ts b/web-studio/src/i18n/locales/zh-CN/gateway/enums.ts
index fa5d8d7c4..b9874540a 100644
--- a/web-studio/src/i18n/locales/zh-CN/gateway/enums.ts
+++ b/web-studio/src/i18n/locales/zh-CN/gateway/enums.ts
@@ -81,8 +81,8 @@ const enums = {
errorCode: 'OpenViking 报告了错误 {{code}}',
versionMismatch: 'OpenViking 版本低于网关的要求',
identityMissing: 'OpenViking 无法识别这个密钥所属的用户',
- rootKey: '不接受 Root 密钥,请使用本账号下的用户密钥。',
- otherAccount: '这个 OpenViking 密钥属于其他账号。',
+ rootKey: '不接受 Root API 密钥,请使用本账号下的用户 API 密钥。',
+ otherAccount: '这个 OpenViking API 密钥属于其他账号。',
},
degradation: {
memory_store_failure: {
@@ -148,6 +148,12 @@ const enums = {
'流式回复无法解析,这条回复没有保存到 OpenViking。客户端不受影响。',
action: '偶尔出现无需处理;频繁出现时再排查。',
},
+ revocation_check_unavailable: {
+ label: '密钥未校验',
+ explanation:
+ 'OpenViking 无法确认这个网关密钥,请求在未检查密钥是否已吊销的情况下照常处理。',
+ action: '检查 OpenViking 是否可达、运行是否正常。',
+ },
},
}
diff --git a/web-studio/src/i18n/locales/zh-CN/gateway/keys.ts b/web-studio/src/i18n/locales/zh-CN/gateway/keys.ts
index 7984d892b..ea8a1f5cc 100644
--- a/web-studio/src/i18n/locales/zh-CN/gateway/keys.ts
+++ b/web-studio/src/i18n/locales/zh-CN/gateway/keys.ts
@@ -1,9 +1,11 @@
const keys = {
description:
- '每个密钥属于一个 OpenViking 用户,使用一份上下文配置和一组上游。密钥不能修改,需要调整时请签发新密钥并吊销旧密钥。',
+ '每个网关密钥(以 ovgw_ 开头)属于一个 OpenViking 用户,使用一份上下文配置和一组上游。密钥不能修改,需要调整时请签发新密钥并吊销旧密钥。',
issue: '签发密钥',
loadFailed: '无法加载网关密钥',
prerequisites: {
+ managed: '网关管理员还没有添加上游或上下文配置。',
+ unlock: '输入网关管理密钥',
upstream: '签发密钥前,请先添加上游。',
profile: '签发密钥前,请先创建上下文配置。',
both: '签发密钥前,请先添加上游并创建上下文配置。',
@@ -44,9 +46,9 @@ const keys = {
deleteUser: {
title: '删除 {{user}} 的网关数据?',
description_one:
- '这会吊销 {{user}} 的网关密钥,并删除网关为该用户保存的对话状态,其中包括尚未保存到 OpenViking 的对话内容。该用户的客户端会立即失去访问权限。已经存入 OpenViking 的记忆不受影响。',
+ '这会吊销 {{user}} 的网关密钥,并删除网关为该用户保存的对话状态(包括尚未保存到 OpenViking 的内容)和请求日志。该用户的客户端会立即失去访问权限。已经存入 OpenViking 的记忆不受影响。',
description_other:
- '这会吊销 {{user}} 的全部 {{count}} 个网关密钥,并删除网关为该用户保存的对话状态,其中包括尚未保存到 OpenViking 的对话内容。该用户的客户端会立即失去访问权限。已经存入 OpenViking 的记忆不受影响。',
+ '这会吊销 {{user}} 的全部 {{count}} 个网关密钥,并删除网关为该用户保存的对话状态(包括尚未保存到 OpenViking 的内容)和请求日志。该用户的客户端会立即失去访问权限。已经存入 OpenViking 的记忆不受影响。',
confirm: '删除网关数据',
done: '已删除 {{user}} 的网关数据',
},
@@ -59,27 +61,30 @@ const keys = {
description: '用来区分不同的密钥,写上使用者和客户端最清楚。',
},
user: {
- label: 'OpenViking 用户',
+ self: '以你的身份({{user}})读写记忆。',
+ developmentIdentity: '以 {{user}} 的身份读写记忆。',
+ label: '给谁用',
placeholder: '选择 OpenViking 用户',
loading: '正在加载用户…',
description:
- '网关会以这个用户的身份召回和保存记忆。该用户的 OpenViking 密钥在服务端读取,由网关加密保存,不会显示。',
+ '网关会以这个用户的身份召回和保存记忆。该用户的用户 API 密钥在服务端读取,由网关加密保存,不会显示。',
roles: {
admin: '管理员',
user: '用户',
},
- unavailable: '服务端读不到这个用户的密钥,请改为粘贴',
- loadFailed: '无法加载本账号的用户,请直接粘贴密钥。',
- none: '服务端读不到本账号用户的密钥,请直接粘贴。',
- root: '使用 Root 密钥时无法在这里选择用户,请直接粘贴密钥。',
+ unavailable: '服务端读不到这个用户的用户 API 密钥,请改为粘贴',
+ loadFailed: '无法加载本账号的用户,请直接粘贴用户 API 密钥。',
+ none: '服务端读不到本账号用户的用户 API 密钥,请直接粘贴。',
choose: '选择用户',
},
openvikingKey: {
- label: 'OpenViking 密钥',
+ forUser: '粘贴 {{user}} 的用户 API 密钥',
+ managementKey: '这是网关管理密钥,请粘贴该用户的用户 API 密钥。',
+ label: 'OpenViking API 密钥',
description:
- '本账号中某个 OpenViking 用户的密钥。网关会以这个用户的身份召回和保存记忆。不接受 Root 密钥。密钥加密保存,之后不再显示。',
- gatewayKey: '这是网关密钥,请填写 OpenViking 用户自己的密钥。',
- paste: '粘贴 OpenViking 密钥',
+ '本账号中某个用户的用户 API 密钥。网关会以这个用户的身份召回和保存记忆。不接受 Root API 密钥。密钥加密保存,之后不再显示。',
+ gatewayKey: '这是网关密钥(给客户端用的),请粘贴该用户的用户 API 密钥。',
+ paste: '粘贴用户 API 密钥',
},
profile: {
label: '上下文配置',
@@ -95,6 +100,7 @@ const keys = {
required: '至少选择一个上游',
empty: '还没有上游。',
create: '去添加',
+ blocked: '已拦截',
off: '已停用',
},
models: {
@@ -106,22 +112,28 @@ const keys = {
submit: '签发密钥',
},
errors: {
+ requiredVersion: '要求版本:{{version}}。',
title: '无法签发密钥',
- rootKey: '这是 Root 密钥。请改用本账号中某个 OpenViking 用户的密钥。',
- otherAccount: '这个 OpenViking 密钥属于其他账号,请使用本账号的用户密钥。',
+ rootKey: '这是 Root API 密钥,请改用本账号中某个用户的用户 API 密钥。',
+ otherAccount:
+ '这个 OpenViking API 密钥属于其他账号,请使用本账号的用户 API 密钥。',
invalidKey:
'OpenViking 拒绝了这个密钥。请检查密钥是否完整,以及是否已被重新生成。',
unavailable: '网关连不上 OpenViking,无法校验这个密钥。请稍后重试。',
versionMismatch:
'OpenViking 版本低于网关的要求。请升级 OpenViking 后重试。',
unknownUser: '这个用户已不在本账号中,请重新选择。',
- userKeyUnreadable: '服务端读不到这个用户的 OpenViking 密钥,请改为粘贴。',
+ userRequired: 'root API 密钥不属于任何用户,请选择这把密钥对应的用户。',
+ userKeyUnreadable:
+ '服务端只保存了这个用户 API 密钥的哈希,无法自动读取。请粘贴该用户的用户 API 密钥。',
},
secret: {
+ identity: '这把密钥以 {{user}} 的身份读写记忆。',
+ dependency:
+ '它绑定 {{user}} 当前的用户 API 密钥。那个密钥重新生成后,这把网关密钥会自动失效,需要重新签发。',
title: '复制网关密钥',
once: '完整密钥只显示这一次。',
copyKey: '复制网关密钥',
- user: 'OpenViking 用户',
profile: '上下文配置',
connectTitle: '接入客户端',
clients: {
diff --git a/web-studio/src/i18n/locales/zh-CN/gateway/overview.ts b/web-studio/src/i18n/locales/zh-CN/gateway/overview.ts
index e83ac7199..ae39e9bfa 100644
--- a/web-studio/src/i18n/locales/zh-CN/gateway/overview.ts
+++ b/web-studio/src/i18n/locales/zh-CN/gateway/overview.ts
@@ -8,6 +8,21 @@ const overview = {
sampleNote_other:
'以上数据统计自请求日志中最新的 {{limit}} 条记录。日志保留 {{count}} 天。',
setup: {
+ providedUpstreams_one: '网关管理员已提供 {{count}} 个上游',
+ providedUpstreams_other: '网关管理员已提供 {{count}} 个上游',
+ importedUpstreams_one: '已有 {{count}} 个上游,来自 OpenViking 的模型配置',
+ importedUpstreams_other:
+ '已有 {{count}} 个上游,来自 OpenViking 的模型配置',
+ someImportedUpstreams:
+ '已有 {{count}} 个上游,其中 {{imported}} 个来自 OpenViking 的模型配置',
+ waitUpstreams: '等待网关管理员添加上游',
+ providedProfiles_one: '网关管理员已提供 {{count}} 个上下文配置',
+ providedProfiles_other: '网关管理员已提供 {{count}} 个上下文配置',
+ waitProfiles: '等待网关管理员添加上下文配置',
+ codingPlan:
+ '{{name}} 是 Coding Plan 上游,确认套餐允许之前,发往它的请求都会被拦截。',
+ confirm: '去确认',
+
title: '快速开始',
description:
'完成下面四步,就能让第一段对话用上记忆。客户端发出第一个请求后,这张卡片会自动隐藏。',
@@ -34,6 +49,7 @@ const overview = {
description:
'客户端用这个密钥调用网关。每个密钥属于一个 OpenViking 用户,网关读写的就是这个用户的记忆。',
blocked: '请先添加上游并创建上下文配置。',
+ waiting: '网关管理员添加上游和上下文配置后,才能签发密钥。',
done_one: '已签发 {{count}} 个密钥',
done_other: '已签发 {{count}} 个密钥',
action: '签发密钥',
@@ -77,14 +93,6 @@ const overview = {
title: 'OpenViking',
description: '为新消息检索记忆,并保存对话。',
version: '版本',
- authMode: '认证方式',
- authModes: {
- api_key: 'API 密钥模式',
- trusted: 'Trusted 模式',
- dev: '开发模式',
- oidc: 'OIDC 模式',
- ldap: 'LDAP 模式',
- },
unreachable:
'连不上 OpenViking 期间,请求照常发给模型,只是不带记忆;保存对话会一直重试,直到 OpenViking 恢复。',
starting: '网关还没完成对 OpenViking 的首次检查,请稍后刷新。',
diff --git a/web-studio/src/i18n/locales/zh-CN/gateway/profiles.ts b/web-studio/src/i18n/locales/zh-CN/gateway/profiles.ts
index 8bbb1a972..816f54be6 100644
--- a/web-studio/src/i18n/locales/zh-CN/gateway/profiles.ts
+++ b/web-studio/src/i18n/locales/zh-CN/gateway/profiles.ts
@@ -1,4 +1,6 @@
const profiles = {
+ inUseHelp:
+ '要删除它,请先吊销这些密钥;如果还需要它们,先签发使用其他上下文配置的新密钥来替换。',
description:
'决定对话如何使用 OpenViking 的记忆和工具。保存后的修改只对之后开始的对话生效。',
defaultName: '默认',
@@ -18,6 +20,7 @@ const profiles = {
title: '还没有上下文配置',
description:
'每个网关密钥都需要一份上下文配置。推荐设置会为每条新消息召回记忆、保存对话、为长对话生成摘要,并让模型使用只读的 OpenViking 工具,之后可以随时修改。',
+ readOnly: '等待网关管理员添加上下文配置。',
},
summary: {
recallOn: '开启 · 每条消息 {{tokens}} Token',
diff --git a/web-studio/src/i18n/locales/zh-CN/gateway/upstreams.ts b/web-studio/src/i18n/locales/zh-CN/gateway/upstreams.ts
index dd99c9780..bd5cd3d04 100644
--- a/web-studio/src/i18n/locales/zh-CN/gateway/upstreams.ts
+++ b/web-studio/src/i18n/locales/zh-CN/gateway/upstreams.ts
@@ -1,4 +1,40 @@
const upstreams = {
+ import: {
+ action: '从 OpenViking 导入',
+ useSettings: '使用 OpenViking 的模型配置',
+ hint: '即服务端的 VLM 配置',
+ running: '导入中…',
+ summary_one: '已导入或更新 {{count}} 个上游。',
+ summary_other: '已导入或更新 {{count}} 个上游。',
+ nothing: 'OpenViking 的模型配置里没有可导入的凭证。',
+ needsConfirmation:
+ '以下 Coding Plan 上游会拦截所有请求,确认套餐允许通过网关使用后才能启用:',
+ skipped_one: '{{count}} 个凭证未导入:',
+ skipped_other: '{{count}} 个凭证未导入:',
+ confirm: '去确认',
+ dismiss: '关闭',
+ repeat:
+ '再次导入会按 OpenViking 的配置更新地址和凭证,不会重复创建;你改过的启用状态、优先级和模型设置会保留。',
+ reasons: {
+ invalid_configuration: '模型配置无效,请检查服务端配置后重新导入。',
+ openai_codex:
+ 'Codex 的 OAuth 凭证会定期刷新,网关无法长期使用。请手动添加上游。',
+ azure:
+ 'Azure OpenAI 需要 api-version 参数,网关暂不支持。请手动添加上游。',
+ litellm_no_api_base:
+ '这个 LiteLLM 凭证没有填写 api_base,网关无法确定地址。请在服务端配置里补上 api_base 后重新导入。',
+ litellm_unsupported_route:
+ '这个 LiteLLM 路由不是 OpenAI 兼容协议,网关无法直接转发。请手动添加上游。',
+ unknown: '无法导入这个凭证,请检查服务端模型配置。',
+ },
+ },
+ readOnly: {
+ empty: '等待网关管理员添加上游。',
+ managedKey: 'API Key 由网关管理员保管。',
+ clientKey: 'API Key 由每个客户端自带。',
+ codingAllowed: 'Coding Plan,网关管理员已允许',
+ codingBlocked: 'Coding Plan,请求已拦截',
+ },
description:
'网关把请求转发给这些模型服务商。每个上游只支持一种协议,网关不做协议转换。',
add: '添加上游',
@@ -49,6 +85,7 @@ const upstreams = {
passthrough: '这个上游由客户端自带 API Key,网关没有可用于测试的 API Key。',
noKey: '请先填写 API Key。',
result: {
+ unverified: '可达,密钥未验证 · {{status}}',
ok: '可连通 · {{status}}',
failed: '失败 · {{status}}',
unreachable: '无法连接',
@@ -57,20 +94,24 @@ const upstreams = {
explain: {
ok: '服务商接受了密钥,并返回了模型列表。',
auth: '服务商拒绝了 API Key 或某个请求头。',
- notFound:
- '这个地址下没有模型列表。请检查 Base URL;如果服务商本来就不提供模型列表,实际请求可能仍然正常。',
+ rateLimited: '地址可达,但服务商限制了请求频率,密钥尚未验证。',
+ notFound: '地址可达,但服务商不提供模型列表,API Key 尚未验证。',
status: '服务商返回了 HTTP {{status}}。',
unreachable:
'网关在 10 秒内没有连上服务商。请检查 Base URL,以及网关到服务商之间的网络。',
},
},
delete: {
+ disable: '停用',
+ disableHint: '也可以先停用它,停用后这些密钥会立即请求不到这个上游。',
+ inUse_one: '仍有 {{count}} 个密钥在使用它。',
+ inUse_other: '仍有 {{count}} 个密钥在使用它。',
action: '删除',
blocked_one: '有 {{count}} 个密钥在使用,请先吊销',
blocked_other: '有 {{count}} 个密钥在使用,请先吊销',
title: '删除“{{name}}”?',
description:
- '上游会连同保存的 API Key 和请求头一起删除。目前没有网关密钥使用它,不会影响任何客户端。',
+ '上游会连同保存的 API Key 和请求头一起删除。还有密钥在使用它时无法删除。',
confirm: '删除上游',
},
toast: {
@@ -88,7 +129,7 @@ const upstreams = {
title: '这个上游已不存在',
description: '它可能已被删除。请返回列表查看现有的上游。',
},
- missing: '还需填写:{{fields}}',
+ missing: '还需填写或修正:{{fields}}',
separator: '、',
create: '添加上游',
},
@@ -133,16 +174,22 @@ const upstreams = {
hints: {
deepseek:
'请求带工具时,DeepSeek 要求回传之前每条回复的推理内容。网关会补回客户端丢掉的部分,所以 OpenViking 工具可以正常使用;如果在下方关闭补全,只有请求关闭了思考模式才会提供这些工具。',
- ark: '填写不带路径的方舟地址,例如 https://ark.cn-beijing.volces.com。网关会按协议补上 /api/v3 或 /api/compatible/v1,并让每段对话的 prompt_cache_key 保持不变,缓存才能持续命中。',
+ ark: 'Chat 和 Responses 填写 https://ark.cn-beijing.volces.com/api/v3,Anthropic 填写 https://ark.cn-beijing.volces.com/api/compatible;Coding Plan 分别填写 https://ark.cn-beijing.volces.com/api/coding/v3 和 https://ark.cn-beijing.volces.com/api/coding。网关会保持每段对话的 prompt_cache_key 不变,让缓存持续命中。',
byteplus:
- '填写不带路径的 BytePlus 方舟地址,例如 https://ark.ap-southeast.bytepluses.com。网关会按协议补上 /api/v3 或 /api/compatible/v1,并让每段对话的 prompt_cache_key 保持不变,缓存才能持续命中。',
+ 'Chat 和 Responses 填写 https://ark.ap-southeast.bytepluses.com/api/v3,Anthropic 填写 https://ark.ap-southeast.bytepluses.com/api/compatible;Coding Plan 分别填写 https://ark.ap-southeast.bytepluses.com/api/coding/v3 和 https://ark.ap-southeast.bytepluses.com/api/coding。网关会保持每段对话的 prompt_cache_key 不变,让缓存持续命中。',
},
},
baseUrl: {
label: 'Base URL',
description:
- '服务商的 API 地址,选择服务商时会自动填入。末尾带不带 /v1 都可以。',
+ '照服务商 SDK 文档填写 base_url,网关在后面拼接 /chat/completions、/responses 或 /v1/messages。同一服务商的不同协议地址不同时,请分别添加上游。',
preview: '请求将发往',
+ missingPath:
+ '这个服务商的 base_url 需要带路径,只填域名会请求到错误地址。',
+ anthropicVersion:
+ 'Anthropic 的 base_url 不需要 /v1,网关会自动拼接 /v1/messages。',
+ removeVersion: '去掉 /v1',
+ correctPath: '改用 {{url}}',
useDefault: '使用默认地址',
},
authMode: {
@@ -162,6 +209,8 @@ const upstreams = {
placeholder: '粘贴服务商的 API Key',
stored: '已保存',
description: '加密保存,之后不再显示。',
+ addressChanged:
+ '地址已修改,请重新填写 API Key。原来保存的 API Key 不会发往新地址。',
storedDescription: '已加密保存。留空则保留原密钥,填写新密钥会替换它。',
},
headers: {
@@ -171,14 +220,17 @@ const upstreams = {
name: '请求头名称',
value: '取值',
add: '添加请求头',
+ addressChanged:
+ '地址已修改,请重新填写请求头的取值。原来保存的取值不会发往新地址。',
},
codingPlan: {
label: '这是 Coding Plan 或订阅密钥',
description: '订阅类密钥通常只授权在服务商自己的工具里使用。',
warning:
- '勾选后,网关会拒绝所有发往这个上游的请求。请改用模型 API Key;如果套餐允许在其他客户端使用,可以选择仍然允许。',
- allow: '仍然允许',
- allowDescription: '网关会用这个密钥转发请求,请先确认套餐允许这样使用。',
+ '网关默认拒绝所有发往这个上游的请求。请改用模型 API Key;如果套餐条款允许在服务商自己的工具之外使用,可以打开下面的选项。',
+ allow: '允许通过网关使用这个套餐',
+ allowDescription:
+ '部分 Coding Plan 只授权在服务商自己的工具里使用。打开前请确认套餐条款允许,否则账号可能被服务商限制。',
},
models: {
label: '模型',
diff --git a/web-studio/src/i18n/locales/zh-CN/workspace.ts b/web-studio/src/i18n/locales/zh-CN/workspace.ts
index 8416aec09..a77ae6630 100644
--- a/web-studio/src/i18n/locales/zh-CN/workspace.ts
+++ b/web-studio/src/i18n/locales/zh-CN/workspace.ts
@@ -750,6 +750,20 @@ const workspace = {
},
},
settings: {
+ gatewayConnection: {
+ title: '登录 OpenViking 网关',
+ openvikingUrl: '这台网关连接的 OpenViking:{{url}}',
+ apiKey: 'OpenViking API 密钥',
+ keyHint: '用户、账号管理员或 Root 的 API 密钥都可以。',
+ wrongKey:
+ '网关密钥(ovgw_)和网关管理密钥(ovgm_)不能用来登录,请输入 OpenViking API 密钥。',
+ invalidKey: 'OpenViking 拒绝了这个 API 密钥。请确认密钥正确后重试。',
+ unreachable:
+ '网关连不上 OpenViking({{url}})。确认 OpenViking 正在运行、网关的 openviking_url(gateway.conf 或 OPENVIKING_GATEWAY_OPENVIKING_URL)指向它,然后重试。',
+ gatewayUnreachable: '连不上这台网关。确认网关正在运行后重试。',
+ connect: '登录',
+ connecting: '正在登录…',
+ },
pageTitle: '设置',
tabs: { connection: '连接设置', configuration: '服务端配置' },
models: {
diff --git a/web-studio/src/lib/admin.ts b/web-studio/src/lib/admin.ts
index cc508e5bb..3500945a8 100644
--- a/web-studio/src/lib/admin.ts
+++ b/web-studio/src/lib/admin.ts
@@ -1,4 +1,5 @@
import axios from 'axios'
+import type { ServerMode } from '#/hooks/use-server-mode'
import { createClient } from '#/gen/ov-client/client'
import {
@@ -91,7 +92,7 @@ export type ProbeConnectionInput = {
adminApiKey: string
apiKey: string
baseUrl: string
- serverMode: 'api_key' | 'trusted' | 'dev' | 'checking' | 'offline'
+ serverMode: ServerMode
userId: string
}
diff --git a/web-studio/src/routes/-index.test.tsx b/web-studio/src/routes/-index.test.tsx
new file mode 100644
index 000000000..ddd46e708
--- /dev/null
+++ b/web-studio/src/routes/-index.test.tsx
@@ -0,0 +1,25 @@
+// @vitest-environment jsdom
+import type { ComponentType } from 'react'
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, expect, it, vi } from 'vitest'
+import { Route } from './index'
+
+const state = vi.hoisted(() => ({ isGatewayHost: false }))
+vi.mock('#/hooks/use-app-connection', () => ({ useAppConnection: () => state }))
+vi.mock('@tanstack/react-router', async (importOriginal) => ({
+ ...(await importOriginal<object>()),
+ Navigate: ({ to }: { to: string }) => <output>{to}</output>,
+}))
+afterEach(cleanup)
+it.each([false, true])(
+ 'routes the host home appropriately: gateway=%s',
+ async (isGatewayHost) => {
+ state.isGatewayHost = isGatewayHost
+ const Index = Route.options.component as ComponentType & {
+ preload?: () => Promise<unknown>
+ }
+ await Index.preload?.()
+ render(<Index />)
+ expect(screen.getByText(isGatewayHost ? '/gateway' : '/home')).toBeTruthy()
+ },
+)
diff --git a/web-studio/src/routes/gateway/-components/access-notices.tsx b/web-studio/src/routes/gateway/-components/access-notices.tsx
new file mode 100644
index 000000000..6e265aa1d
--- /dev/null
+++ b/web-studio/src/routes/gateway/-components/access-notices.tsx
@@ -0,0 +1,98 @@
+import * as React from 'react'
+import { useTranslation } from 'react-i18next'
+import { Button } from '#/components/ui/button'
+import { gatewayDocsUrl } from '../-lib/client-guides'
+import { requestManagementUnlock } from '../-lib/management-key'
+import { useGateway } from '../-lib/use-gateway'
+import { CodeBlock } from './code-block'
+import { Notice } from './notice'
+
+const GENERATE_KEY_COMMAND = 'openssl rand -base64 32'
+
+export function ManagementUnlockButton() {
+ const { t } = useTranslation('gateway')
+ return (
+ <Button
+ type="button"
+ size="sm"
+ variant="outline"
+ onClick={requestManagementUnlock}
+ >
+ {t('management.title')}
+ </Button>
+ )
+}
+
+export function AccessNotices({ objectsTab }: { objectsTab: boolean }) {
+ const { t, i18n } = useTranslation('gateway')
+ const { access, connection, readOnly } = useGateway()
+ const dismissedKey = `gateway-public-warning:${connection.baseUrl}`
+ const [dismissed, setDismissed] = React.useState(() => {
+ try {
+ return sessionStorage.getItem(dismissedKey) === '1'
+ } catch {
+ return false
+ }
+ })
+ const dismiss = () => {
+ setDismissed(true)
+ try {
+ sessionStorage.setItem(dismissedKey, '1')
+ } catch {
+ /* Storage may be unavailable. */
+ }
+ }
+ return (
+ <>
+ {!dismissed &&
+ access?.warnings.includes('public_openviking_without_management_key') ? (
+ <Notice
+ tone="warning"
+ title={t('management.publicTitle')}
+ action={
+ <div className="flex gap-2">
+ <Button
+ size="sm"
+ variant="outline"
+ nativeButton={false}
+ render={
+ <a
+ href={gatewayDocsUrl('operations', i18n.resolvedLanguage)}
+ target="_blank"
+ rel="noreferrer"
+ />
+ }
+ >
+ {t('unavailable.docs')}
+ </Button>
+ <Button size="sm" variant="ghost" onClick={dismiss}>
+ {t('management.dismiss')}
+ </Button>
+ </div>
+ }
+ >
+ <p>{t('management.publicDescription')}</p>
+ <CodeBlock
+ code={`OPENVIKING_GATEWAY_MANAGEMENT_KEY=${t('management.keyPlaceholder')}`}
+ label={t('unavailable.environment')}
+ />
+ <p>
+ {t('management.generate')} <code>{GENERATE_KEY_COMMAND}</code>
+ </p>
+ </Notice>
+ ) : null}
+ {objectsTab && access?.managed ? (
+ readOnly ? (
+ <Notice tone="info" action={<ManagementUnlockButton />}>
+ <p>{t('management.readOnly')}</p>
+ {['admin', 'root'].includes(access.role) ? (
+ <p>{t('management.adminReadOnly')}</p>
+ ) : null}
+ </Notice>
+ ) : (
+ <Notice tone="info">{t('management.shared')}</Notice>
+ )
+ ) : null}
+ </>
+ )
+}
diff --git a/web-studio/src/routes/gateway/-components/confirm-dialog.tsx b/web-studio/src/routes/gateway/-components/confirm-dialog.tsx
index 3b1977595..746632eb3 100644
--- a/web-studio/src/routes/gateway/-components/confirm-dialog.tsx
+++ b/web-studio/src/routes/gateway/-components/confirm-dialog.tsx
@@ -25,6 +25,8 @@ type ConfirmDialogProps = {
icon?: React.ReactNode
/** Soft-red confirm button; on by default. */
destructive?: boolean
+ /** Extra controls between the description and the buttons. */
+ children?: React.ReactNode
/**
* Runs on confirm. Return a promise (e.g. `mutateAsync`) to show a spinner
* and close on success; a rejection keeps the dialog open.
@@ -45,6 +47,7 @@ export function ConfirmDialog({
confirmLabel,
icon,
destructive = true,
+ children,
onConfirm,
}: ConfirmDialogProps) {
const { t } = useTranslation('gateway')
@@ -80,6 +83,7 @@ export function ConfirmDialog({
{open ? description : shown.description}
</AlertDialogDescription>
</AlertDialogHeader>
+ {children}
<AlertDialogFooter>
<AlertDialogCancel disabled={pending}>
{t('actions.cancel')}
diff --git a/web-studio/src/routes/gateway/-components/connect-page.test.tsx b/web-studio/src/routes/gateway/-components/connect-page.test.tsx
index 5cae4f843..deca14989 100644
--- a/web-studio/src/routes/gateway/-components/connect-page.test.tsx
+++ b/web-studio/src/routes/gateway/-components/connect-page.test.tsx
@@ -44,8 +44,11 @@ const api = vi.hoisted(() => ({
listUpstreams: vi.fn(),
}))
+const host = vi.hoisted(() => ({ isGatewayHost: false }))
+
vi.mock('#/hooks/use-app-connection', () => ({
useAppConnection: () => ({
+ isGatewayHost: host.isGatewayHost,
connection: {
baseUrl: 'http://localhost:1933',
accountId: 'acme',
@@ -65,7 +68,7 @@ vi.mock('../-lib/api', async (importOriginal) => ({
}))
const PUBLIC: ConnectionInfo = {
- base_url: 'https://gw.example.com',
+ base_url: 'https://gw.example.com/gateway',
public_url_configured: true,
}
@@ -188,8 +191,10 @@ describe('ConnectPage', () => {
it('shows the address for both client families and links keys and docs', async () => {
renderPage()
- expect(await screen.findByText('https://gw.example.com')).toBeTruthy()
- expect(screen.getByText('https://gw.example.com/v1')).toBeTruthy()
+ expect(
+ await screen.findByText('https://gw.example.com/gateway'),
+ ).toBeTruthy()
+ expect(screen.getByText('https://gw.example.com/gateway/v1')).toBeTruthy()
expect(screen.queryByText(/public_url/)).toBeNull()
expect(linkTo('Manage keys')).toBe('/gateway/keys')
expect(linkTo('Full guide')).toBe(gatewayDocsUrl('guide', 'en'))
@@ -198,12 +203,15 @@ describe('ConnectPage', () => {
it.each([
[
'a loopback address',
- { base_url: 'http://127.0.0.1:1935', public_url_configured: false },
+ {
+ base_url: 'http://127.0.0.1:1933/gateway',
+ public_url_configured: false,
+ },
"Only the gateway's own machine can use this address",
],
[
'an address that is not the public one',
- { base_url: 'http://gateway:1935', public_url_configured: false },
+ { base_url: 'http://gateway:1933/gateway', public_url_configured: false },
'Clients may not be able to reach this address',
],
])('warns about %s', async (_, info, title) => {
@@ -213,6 +221,27 @@ describe('ConnectPage', () => {
expect(screen.getAllByText('gateway.public_url')).toHaveLength(1)
})
+ it('points a standalone gateway at gateway.conf instead of ov.conf', async () => {
+ host.isGatewayHost = true
+ api.getConnectionInfo.mockResolvedValue({
+ base_url: 'http://gateway:1935/gateway',
+ public_url_configured: false,
+ })
+ try {
+ renderPage()
+ expect(
+ await screen.findByText(
+ 'Clients may not be able to reach this address',
+ ),
+ ).toBeTruthy()
+ expect(screen.getByText('gateway.conf')).toBeTruthy()
+ expect(screen.getByText('OPENVIKING_GATEWAY_PUBLIC_URL')).toBeTruthy()
+ expect(screen.queryByText('ov.conf')).toBeNull()
+ } finally {
+ host.isGatewayHost = false
+ }
+ })
+
it('starts with Claude Code and warns when no enabled upstream speaks its protocol', async () => {
renderPage()
expect(
@@ -220,7 +249,7 @@ describe('ConnectPage', () => {
).toBeTruthy()
expect(snippetTexts()).toContain(
[
- 'export ANTHROPIC_BASE_URL=https://gw.example.com',
+ 'export ANTHROPIC_BASE_URL=https://gw.example.com/gateway',
"export ANTHROPIC_AUTH_TOKEN='<gateway-key>'",
'export CLAUDE_CODE_GATEWAY_HINT_HEADERS=1',
].join('\n'),
@@ -246,7 +275,7 @@ describe('ConnectPage', () => {
).toBeTruthy()
expect(
snippetTexts().some((code) =>
- code.includes('base_url = "https://gw.example.com/v1"'),
+ code.includes('base_url = "https://gw.example.com/gateway/v1"'),
),
).toBe(true)
expect(
diff --git a/web-studio/src/routes/gateway/-components/connect-page.tsx b/web-studio/src/routes/gateway/-components/connect-page.tsx
index d53c40ae8..c914f539e 100644
--- a/web-studio/src/routes/gateway/-components/connect-page.tsx
+++ b/web-studio/src/routes/gateway/-components/connect-page.tsx
@@ -16,6 +16,7 @@ import {
CardHeader,
CardTitle,
} from '#/components/ui/card'
+import { useAppConnection } from '#/hooks/use-app-connection'
import type { ConnectionInfo, Upstream } from '../-lib/api'
import {
@@ -103,6 +104,7 @@ export function ConnectPage() {
function AddressCard({ info }: { info: ConnectionInfo }) {
const { t } = useTranslation('gateway')
+ const { isGatewayHost } = useAppConnection()
const base = info.base_url.replace(/\/+$/, '')
const warning = isLoopbackUrl(base)
? 'loopback'
@@ -131,7 +133,11 @@ function AddressCard({ info }: { info: ConnectionInfo }) {
{warning ? (
<Notice tone="warning" title={t(`connect.address.${warning}.title`)}>
<p>
- <CodeText text={t(`connect.address.${warning}.description`)} />
+ <CodeText
+ text={t(
+ `connect.address.${warning}.${isGatewayHost ? 'standalone' : 'embedded'}`,
+ )}
+ />
</p>
</Notice>
) : null}
diff --git a/web-studio/src/routes/gateway/-components/gateway-enable.test.tsx b/web-studio/src/routes/gateway/-components/gateway-enable.test.tsx
new file mode 100644
index 000000000..462f0d2df
--- /dev/null
+++ b/web-studio/src/routes/gateway/-components/gateway-enable.test.tsx
@@ -0,0 +1,382 @@
+// @vitest-environment jsdom
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+ Outlet,
+ RouterProvider,
+ createMemoryHistory,
+ createRootRoute,
+ createRoute,
+ createRouter,
+} from '@tanstack/react-router'
+import {
+ cleanup,
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+} from '@testing-library/react'
+import type * as ReactI18next from 'react-i18next'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type * as ConfigFileApi from '#/routes/settings/-lib/config-file-api'
+import { GatewayError } from '../-lib/api'
+import type * as Api from '../-lib/api'
+import type { GatewayConnection } from '../-lib/api'
+import { getManagementKey } from '../-lib/management-key'
+import { GatewayLayout } from './gateway-layout'
+
+const BASE_URL = 'http://ov.example.com'
+
+const state = vi.hoisted(() => ({
+ role: 'root',
+ serverMode: 'api_key',
+ gatewayOn: false,
+ get: vi.fn(),
+ save: vi.fn(),
+ restart: vi.fn(),
+ copy: vi.fn(),
+ getAccess: vi.fn(),
+ getConnectionInfo: vi.fn(),
+}))
+vi.mock('#/hooks/use-app-connection', () => ({
+ useAppConnection: () => ({
+ connection: {
+ baseUrl: 'http://ov.example.com',
+ accountId: 'acme',
+ userId: 'root',
+ apiKey: '',
+ adminApiKey: 'root-key',
+ },
+ connectionRole: state.role,
+ isConnectionRoleLoading: false,
+ serverMode: state.serverMode,
+ identityScopeKey: 'scope',
+ isGatewayHost: false,
+ openvikingUrl: '',
+ }),
+}))
+vi.mock('#/routes/settings/-lib/config-file-api', async (original) => ({
+ ...(await original<typeof ConfigFileApi>()),
+ createConfigFileApi: () => ({
+ get: state.get,
+ save: state.save,
+ restart: state.restart,
+ }),
+}))
+vi.mock('../-lib/api', async (original) => ({
+ ...(await original<typeof Api>()),
+ getAccess: state.getAccess,
+ getConnectionInfo: state.getConnectionInfo,
+}))
+vi.mock('#/lib/clipboard', () => ({ copyTextToClipboard: state.copy }))
+vi.mock('react-i18next', async (original) => ({
+ ...(await original<typeof ReactI18next>()),
+ useTranslation: () => ({
+ t: (key: string) => key,
+ i18n: { resolvedLanguage: 'en' },
+ }),
+}))
+vi.mock('sonner', () => ({ toast: { success: vi.fn(), error: vi.fn() } }))
+
+const CONTENT =
+ '{\n "server": {"port": 1933},\n "gateway": {"storage_path": "/data"}\n}\n'
+
+function file(overrides: Record<string, unknown> = {}) {
+ return {
+ content: CONTENT,
+ revision: 'r1',
+ writable: true,
+ models: { vlm: { config: {} }, embedding: { config: {} } },
+ restart: { supported: true, instance_id: 'old', restarting: false },
+ ...overrides,
+ }
+}
+
+const restarted = (extra: Record<string, unknown> = {}) =>
+ file({
+ revision: 'r2',
+ restart: {
+ supported: true,
+ instance_id: 'new',
+ restarting: false,
+ ...extra,
+ },
+ })
+
+/** Renders the card the way users see it: inside the gateway layout. */
+function renderGateway() {
+ const root = createRootRoute({ component: Outlet })
+ const router = createRouter({
+ routeTree: root.addChildren([
+ createRoute({
+ getParentRoute: () => root,
+ path: '/gateway',
+ component: GatewayLayout,
+ }),
+ createRoute({ getParentRoute: () => root, path: '/settings' }),
+ ]),
+ history: createMemoryHistory({ initialEntries: ['/gateway'] }),
+ })
+ const client = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ })
+ render(
+ <QueryClientProvider client={client}>
+ <RouterProvider router={router} />
+ </QueryClientProvider>,
+ )
+}
+
+async function confirmEnable({ protect = false } = {}) {
+ fireEvent.click(
+ await screen.findByRole('button', { name: 'unavailable.enable.action' }),
+ )
+ if (protect) fireEvent.click(screen.getByRole('checkbox'))
+ const buttons = screen.getAllByRole('button', {
+ name: 'unavailable.enable.action',
+ })
+ fireEvent.click(buttons[buttons.length - 1])
+}
+
+/** Whether a gateway call carried this management key. */
+const accessedWith = (key: string) =>
+ state.getAccess.mock.calls.some(
+ (call) => (call[0] as GatewayConnection).managementKey === key,
+ )
+
+beforeEach(() => {
+ vi.clearAllMocks()
+ vi.spyOn(window, 'scrollTo').mockImplementation(() => {})
+ sessionStorage.clear()
+ state.role = 'root'
+ state.serverMode = 'api_key'
+ state.gatewayOn = false
+ state.get.mockResolvedValue(file())
+ state.save.mockResolvedValue({ revision: 'r2', restart_required: true })
+ state.restart.mockResolvedValue({
+ supported: true,
+ instance_id: 'old',
+ restarting: true,
+ })
+ state.getAccess.mockImplementation(async () => {
+ if (!state.gatewayOn)
+ throw new GatewayError('Not Found', 404, undefined, 'not_enabled')
+ return {
+ managed: true,
+ can_write_objects: true,
+ can_import_vlm: true,
+ can_issue_for_others: true,
+ role: 'root',
+ account_id: 'acme',
+ user_id: 'root',
+ warnings: [],
+ }
+ })
+ state.getConnectionInfo.mockResolvedValue({
+ base_url: 'https://gateway.example.com',
+ public_url_configured: true,
+ })
+})
+afterEach(cleanup)
+
+describe('enabling the gateway from Studio', () => {
+ it('writes ov.conf, restarts, shows the new management key once and then opens the gateway with it', async () => {
+ state.get.mockResolvedValueOnce(file()).mockResolvedValue(restarted())
+ state.restart.mockImplementation(async () => {
+ state.gatewayOn = true
+ return { supported: true, instance_id: 'old', restarting: true }
+ })
+ state.copy.mockRejectedValue(new Error('denied'))
+ renderGateway()
+ expect(
+ await screen.findByText('unavailable.enable.description'),
+ ).toBeTruthy()
+ await confirmEnable({ protect: true })
+
+ const key = await screen.findByLabelText<HTMLInputElement>(
+ 'unavailable.enable.keyTitle',
+ )
+ expect(state.restart).toHaveBeenCalledWith('r2')
+ const [content, revision] = state.save.mock.calls[0]
+ expect(revision).toBe('r1')
+ const written = JSON.parse(content)
+ expect(written.server).toEqual({ port: 1933 })
+ expect(written.gateway).toMatchObject({
+ storage_path: '/data',
+ enabled: true,
+ })
+ expect(written.gateway.management_key).toMatch(/^ovgm_[A-Za-z0-9_-]{43}$/)
+ expect(key.value).toBe(written.gateway.management_key)
+ expect(screen.getByText('unavailable.enable.keyOnce')).toBeTruthy()
+ // Storing the key would switch the gateway queries and drop this card.
+ expect(getManagementKey(BASE_URL)).toBe('')
+
+ fireEvent.click(
+ screen.getByRole('button', { name: 'unavailable.enable.copyKey' }),
+ )
+ expect(
+ await screen.findByText('unavailable.enable.copyFailed'),
+ ).toBeTruthy()
+ expect(document.activeElement).toBe(key)
+ expect(screen.queryByText('tabs.overview')).toBeNull()
+
+ fireEvent.click(
+ screen.getByRole('button', { name: 'unavailable.enable.continue' }),
+ )
+ expect(await screen.findByText('tabs.overview')).toBeTruthy()
+ // This tab is unlocked with the key root just set.
+ expect(getManagementKey(BASE_URL)).toBe(key.value)
+ await waitFor(() => expect(accessedWith(key.value)).toBe(true))
+ expect(screen.getByText('management.editing')).toBeTruthy()
+ })
+
+ it('opens the gateway right after the restart when no key was generated', async () => {
+ state.get.mockResolvedValueOnce(file()).mockResolvedValue(restarted())
+ state.restart.mockImplementation(async () => {
+ state.gatewayOn = true
+ return { supported: true, instance_id: 'old', restarting: true }
+ })
+ renderGateway()
+ await confirmEnable()
+ expect(await screen.findByText('tabs.overview')).toBeTruthy()
+ expect(getManagementKey(BASE_URL)).toBe('')
+ expect(JSON.parse(state.save.mock.calls[0][0]).gateway).not.toHaveProperty(
+ 'management_key',
+ )
+ })
+
+ it('saves without restarting and keeps the key and the restart step on screen', async () => {
+ state.get.mockResolvedValue(
+ file({
+ restart: { supported: false, instance_id: 'old', restarting: false },
+ }),
+ )
+ renderGateway()
+ expect(
+ await screen.findByText('unavailable.enable.descriptionManualRestart'),
+ ).toBeTruthy()
+ await confirmEnable({ protect: true })
+
+ const key = await screen.findByLabelText<HTMLInputElement>(
+ 'unavailable.enable.keyTitle',
+ )
+ expect(key.value).toMatch(/^ovgm_/)
+ expect(screen.getByText('unavailable.enable.keyOnceManual')).toBeTruthy()
+ expect(screen.getByText('unavailable.enable.savedRestart')).toBeTruthy()
+ expect(state.save).toHaveBeenCalledOnce()
+ expect(state.restart).not.toHaveBeenCalled()
+ expect(
+ screen.queryByRole('button', { name: 'unavailable.enable.action' }),
+ ).toBeNull()
+
+ fireEvent.click(
+ screen.getByRole('button', { name: 'unavailable.enable.keySaved' }),
+ )
+ expect(screen.queryByLabelText('unavailable.enable.keyTitle')).toBeNull()
+ expect(screen.getByText('unavailable.enable.savedRestart')).toBeTruthy()
+ // The server still runs without the key; root enters it after restarting.
+ expect(getManagementKey(BASE_URL)).toBe('')
+ })
+
+ it('says the gateway is still off when it is off after the restart', async () => {
+ state.get.mockResolvedValueOnce(file()).mockResolvedValue(restarted())
+ renderGateway()
+ await confirmEnable()
+ expect(await screen.findByText('unavailable.enable.stillOff')).toBeTruthy()
+ expect(screen.queryByText('tabs.overview')).toBeNull()
+ })
+
+ it('keeps the key on screen when the gateway is still off after the restart', async () => {
+ state.get.mockResolvedValueOnce(file()).mockResolvedValue(restarted())
+ renderGateway()
+ await confirmEnable({ protect: true })
+ const key = await screen.findByLabelText<HTMLInputElement>(
+ 'unavailable.enable.keyTitle',
+ )
+ fireEvent.click(
+ screen.getByRole('button', { name: 'unavailable.enable.continue' }),
+ )
+ expect(await screen.findByText('unavailable.enable.stillOff')).toBeTruthy()
+ expect(
+ screen.getByLabelText<HTMLInputElement>('unavailable.enable.keyTitle')
+ .value,
+ ).toBe(key.value)
+ expect(getManagementKey(BASE_URL)).toBe('')
+ })
+
+ it('shows the saved key when the restart cannot be confirmed', async () => {
+ state.restart.mockRejectedValue(new Error('connection reset'))
+ renderGateway()
+ await confirmEnable({ protect: true })
+ expect(
+ await screen.findByText('unavailable.enable.restartFailed'),
+ ).toBeTruthy()
+ const key = screen.getByLabelText<HTMLInputElement>(
+ 'unavailable.enable.keyTitle',
+ )
+ expect(key.value).toBe(
+ JSON.parse(state.save.mock.calls[0][0]).gateway.management_key,
+ )
+ expect(getManagementKey(BASE_URL)).toBe('')
+ })
+
+ it('explains the deployment settings when ov.conf is read-only', async () => {
+ state.get.mockResolvedValue(file({ writable: false }))
+ renderGateway()
+ expect(await screen.findByText('unavailable.enable.readOnly')).toBeTruthy()
+ expect(screen.getByText('OPENVIKING_GATEWAY_ENABLED=true')).toBeTruthy()
+ expect(screen.getByText(/enabled: true/)).toBeTruthy()
+ expect(
+ screen.queryByRole('button', { name: 'unavailable.enable.action' }),
+ ).toBeNull()
+ })
+
+ it('reports a rejected configuration that the server rolled back', async () => {
+ state.get
+ .mockResolvedValueOnce(file())
+ .mockResolvedValue(restarted({ rolled_back: true }))
+ renderGateway()
+ await confirmEnable({ protect: true })
+ expect(
+ await screen.findByText('unavailable.enable.rolledBack'),
+ ).toBeTruthy()
+ expect(screen.queryByLabelText('unavailable.enable.keyTitle')).toBeNull()
+ expect(getManagementKey(BASE_URL)).toBe('')
+ })
+
+ it('asks to reload when ov.conf changed since it was read', async () => {
+ state.save.mockRejectedValue(
+ new Error('ov.conf changed; reload before saving'),
+ )
+ renderGateway()
+ await confirmEnable()
+ expect(await screen.findByText('unavailable.enable.conflict')).toBeTruthy()
+ fireEvent.click(
+ screen.getByRole('button', { name: 'unavailable.enable.reload' }),
+ )
+ await waitFor(() => expect(state.get).toHaveBeenCalledTimes(2))
+ expect(state.restart).not.toHaveBeenCalled()
+ })
+
+ it.each(['admin', 'user'])(
+ 'asks %s to contact the deployer without an enable button',
+ async (role) => {
+ state.role = role
+ renderGateway()
+ expect(await screen.findByText('unavailable.contact')).toBeTruthy()
+ expect(
+ screen.queryByRole('button', { name: 'unavailable.enable.action' }),
+ ).toBeNull()
+ expect(state.get).not.toHaveBeenCalled()
+ },
+ )
+
+ it('shows the manual steps when ov.conf cannot be read', async () => {
+ state.get.mockRejectedValue(new Error('forbidden'))
+ renderGateway()
+ expect(
+ await screen.findByText('unavailable.notEnabled.description'),
+ ).toBeTruthy()
+ expect(screen.getByText(/"enabled":true/)).toBeTruthy()
+ })
+})
diff --git a/web-studio/src/routes/gateway/-components/gateway-enable.tsx b/web-studio/src/routes/gateway/-components/gateway-enable.tsx
new file mode 100644
index 000000000..778b8a212
--- /dev/null
+++ b/web-studio/src/routes/gateway/-components/gateway-enable.tsx
@@ -0,0 +1,368 @@
+import * as React from 'react'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { CopyIcon, LoaderCircleIcon, PowerIcon } from 'lucide-react'
+import { useTranslation } from 'react-i18next'
+import { toast } from 'sonner'
+
+import { Button } from '#/components/ui/button'
+import { Checkbox } from '#/components/ui/checkbox'
+import { Input } from '#/components/ui/input'
+import { useAppConnection } from '#/hooks/use-app-connection'
+import { copyTextToClipboard } from '#/lib/clipboard'
+import {
+ createConfigFileApi,
+ waitForServerRestart,
+} from '#/routes/settings/-lib/config-file-api'
+import type { ConfigFileConfiguration } from '#/routes/settings/-lib/config-file-api'
+
+import {
+ enableGatewayContent,
+ generateManagementKey,
+ isRevisionConflict,
+} from '../-lib/enable-gateway'
+import { setManagementKey } from '../-lib/management-key'
+import { CodeBlock } from './code-block'
+import { ConfirmDialog } from './confirm-dialog'
+import { Notice } from './notice'
+import { SetupCard } from './setup-card'
+
+/** The file was saved, but the restart could not be confirmed. */
+class RestartError extends Error {}
+
+type Outcome = 'saved' | 'restarted' | 'rolledBack'
+
+function errorMessage(error: unknown): string {
+ return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Shows a new gateway management key once, with a copy button. With
+ * `openGateway` the key unlocks this tab once the gateway opens; otherwise
+ * root enters it after restarting the server.
+ */
+function ManagementKeyReveal({
+ value,
+ openGateway,
+ onDismiss,
+}: {
+ value: string
+ openGateway?: () => void
+ onDismiss: () => void
+}) {
+ const { t } = useTranslation('gateway')
+ const input = React.useRef<HTMLInputElement>(null)
+ const [copyFailed, setCopyFailed] = React.useState(false)
+
+ async function copy() {
+ try {
+ await copyTextToClipboard(value)
+ setCopyFailed(false)
+ toast.success(t('copy.done'))
+ } catch {
+ // Leave the key selected so it can be copied by hand.
+ setCopyFailed(true)
+ input.current?.focus()
+ input.current?.select()
+ }
+ }
+
+ return (
+ <Notice
+ tone="warning"
+ title={t('unavailable.enable.keyTitle')}
+ action={
+ <Button size="sm" onClick={openGateway ?? onDismiss}>
+ {t(
+ openGateway
+ ? 'unavailable.enable.continue'
+ : 'unavailable.enable.keySaved',
+ )}
+ </Button>
+ }
+ >
+ <p>
+ {t(
+ openGateway
+ ? 'unavailable.enable.keyOnce'
+ : 'unavailable.enable.keyOnceManual',
+ )}
+ </p>
+ <div className="flex min-w-0 items-center gap-2">
+ <Input
+ ref={input}
+ readOnly
+ value={value}
+ aria-label={t('unavailable.enable.keyTitle')}
+ className="bg-background font-mono text-xs text-foreground"
+ onFocus={(event) => event.currentTarget.select()}
+ />
+ <Button
+ variant="outline"
+ size="sm"
+ aria-label={t('unavailable.enable.copyKey')}
+ onClick={() => void copy()}
+ >
+ <CopyIcon />
+ {t('actions.copy')}
+ </Button>
+ </div>
+ {copyFailed ? (
+ <p role="alert">{t('unavailable.enable.copyFailed')}</p>
+ ) : null}
+ </Notice>
+ )
+}
+
+/**
+ * The "not enabled" card for root on an OpenViking server: turns the gateway
+ * on by writing `gateway.enabled` to ov.conf and restarting the server, with
+ * the same configuration API the settings page uses.
+ */
+export function EnableGatewayCard({
+ retry,
+ retrying,
+ onOpenGateway,
+ fallback,
+}: {
+ /** Retry button that asks the gateway for /access again. */
+ retry: React.ReactNode
+ retrying: boolean
+ /**
+ * Asks for /access again once the server runs with the gateway on;
+ * resolves true when the gateway answers.
+ */
+ onOpenGateway: () => Promise<boolean>
+ /** Shown when ov.conf can't be read through the configuration API. */
+ fallback: React.ReactNode
+}) {
+ const { t } = useTranslation('gateway')
+ const { connection, serverMode, identityScopeKey } = useAppConnection()
+ const queryClient = useQueryClient()
+ const api = React.useMemo(
+ () => createConfigFileApi(connection, serverMode === 'trusted'),
+ [connection, serverMode],
+ )
+ // Shared with the settings page, which reads the same file.
+ const queryKey = React.useMemo(
+ () => ['server-configuration', identityScopeKey],
+ [identityScopeKey],
+ )
+ const config = useQuery({
+ queryKey,
+ queryFn: () => api.get(),
+ retry: false,
+ })
+ const [confirming, setConfirming] = React.useState(false)
+ const [protect, setProtect] = React.useState(false)
+ const [issuedKey, setIssuedKey] = React.useState<string | null>(null)
+ const [restarted, setRestarted] = React.useState(false)
+ const restartAbort = React.useRef<AbortController | null>(null)
+ React.useEffect(() => () => restartAbort.current?.abort(), [])
+
+ const enable = useMutation({
+ mutationFn: async ({
+ file,
+ key,
+ }: {
+ file: ConfigFileConfiguration
+ key?: string
+ }): Promise<Outcome> => {
+ const saved = await api.save(
+ enableGatewayContent(file.content, key),
+ file.revision,
+ )
+ if (!file.restart?.supported) return 'saved'
+ const controller = new AbortController()
+ restartAbort.current = controller
+ try {
+ const accepted = await api.restart(saved.revision)
+ const result = await waitForServerRestart(
+ () => api.get(3000),
+ accepted.instance_id,
+ controller.signal,
+ )
+ queryClient.setQueryData(queryKey, result)
+ return result.restart?.rolled_back ? 'rolledBack' : 'restarted'
+ } catch (error) {
+ if (isRevisionConflict(error)) throw error
+ throw new RestartError(errorMessage(error), { cause: error })
+ }
+ },
+ onSuccess: (outcome, { key }) => {
+ if (outcome === 'saved') void queryClient.invalidateQueries({ queryKey })
+ if (outcome === 'rolledBack') return
+ // The key is stored only when the reveal is dismissed: storing it
+ // changes the gateway query scope, which replaces this card.
+ if (key) setIssuedKey(key)
+ else if (outcome === 'restarted') void openGateway()
+ },
+ onError: (error, { key }) => {
+ // ov.conf already holds the key; this is the only chance to show it.
+ if (key && error instanceof RestartError) setIssuedKey(key)
+ },
+ })
+
+ async function openGateway(key?: string) {
+ const baseUrl = connection.baseUrl
+ if (await onOpenGateway()) {
+ // Unlock this tab: root set the key and can edit right away. The card
+ // is usually gone by now, so this touches no component state.
+ if (key) setManagementKey(baseUrl, key)
+ } else setRestarted(true)
+ }
+
+ if (config.isPending)
+ return (
+ <SetupCard
+ title={t('unavailable.notEnabled.title')}
+ description={t('unavailable.enable.checking')}
+ actions={retry}
+ />
+ )
+ if (config.isError) return fallback
+ const file = config.data
+
+ if (file.writable === false)
+ return (
+ <SetupCard
+ title={t('unavailable.notEnabled.title')}
+ description={t('unavailable.enable.readOnly')}
+ actions={retry}
+ >
+ <CodeBlock
+ label={t('unavailable.environment')}
+ code="OPENVIKING_GATEWAY_ENABLED=true"
+ />
+ <CodeBlock
+ label={t('unavailable.enable.helm')}
+ code={'gateway:\n enabled: true'}
+ />
+ </SetupCard>
+ )
+
+ const canRestart = Boolean(file.restart?.supported)
+ const outcome = enable.data
+ const done = enable.isSuccess && outcome !== 'rolledBack'
+
+ return (
+ <SetupCard
+ title={t('unavailable.notEnabled.title')}
+ description={t(
+ canRestart
+ ? 'unavailable.enable.description'
+ : 'unavailable.enable.descriptionManualRestart',
+ )}
+ actions={
+ // Asking for /access mid-restart would replace this card with an error.
+ enable.isPending ? null : (
+ <>
+ {done ? null : (
+ <Button size="sm" onClick={() => setConfirming(true)}>
+ <PowerIcon />
+ {t('unavailable.enable.action')}
+ </Button>
+ )}
+ {retry}
+ </>
+ )
+ }
+ >
+ {enable.isPending ? (
+ <p
+ role="status"
+ className="flex items-center gap-2 text-sm text-muted-foreground"
+ >
+ <LoaderCircleIcon className="size-4 animate-spin" />
+ {t(
+ canRestart
+ ? 'unavailable.enable.restarting'
+ : 'unavailable.enable.saving',
+ )}
+ </p>
+ ) : null}
+ {enable.isError ? (
+ isRevisionConflict(enable.error) ? (
+ <Notice
+ tone="danger"
+ action={
+ <Button
+ variant="outline"
+ size="sm"
+ onClick={() => {
+ enable.reset()
+ void config.refetch()
+ }}
+ >
+ {t('unavailable.enable.reload')}
+ </Button>
+ }
+ >
+ {t('unavailable.enable.conflict')}
+ </Notice>
+ ) : (
+ <Notice tone="danger">
+ {t(
+ enable.error instanceof RestartError
+ ? 'unavailable.enable.restartFailed'
+ : 'unavailable.enable.failed',
+ { message: errorMessage(enable.error) },
+ )}
+ </Notice>
+ )
+ ) : null}
+ {outcome === 'rolledBack' ? (
+ <Notice tone="danger">{t('unavailable.enable.rolledBack')}</Notice>
+ ) : null}
+ {outcome === 'saved' ? (
+ <Notice tone="info">{t('unavailable.enable.savedRestart')}</Notice>
+ ) : null}
+ {issuedKey ? (
+ <ManagementKeyReveal
+ value={issuedKey}
+ openGateway={
+ outcome === 'restarted'
+ ? () => void openGateway(issuedKey)
+ : undefined
+ }
+ onDismiss={() => setIssuedKey(null)}
+ />
+ ) : null}
+ {restarted && !retrying ? (
+ <Notice tone="warning">{t('unavailable.enable.stillOff')}</Notice>
+ ) : null}
+ <ConfirmDialog
+ open={confirming}
+ onOpenChange={setConfirming}
+ destructive={false}
+ title={t('unavailable.enable.confirmTitle')}
+ description={t(
+ canRestart
+ ? 'unavailable.enable.confirmRestart'
+ : 'unavailable.enable.confirmManualRestart',
+ )}
+ confirmLabel={t('unavailable.enable.action')}
+ icon={<PowerIcon />}
+ onConfirm={() =>
+ enable.mutate({
+ file,
+ key: protect ? generateManagementKey() : undefined,
+ })
+ }
+ >
+ <label className="flex items-start gap-2.5 text-sm leading-6">
+ <Checkbox
+ className="mt-1"
+ checked={protect}
+ onCheckedChange={(checked) => setProtect(checked === true)}
+ />
+ <span className="grid gap-0.5">
+ <span>{t('unavailable.enable.protect')}</span>
+ <span className="text-muted-foreground">
+ {t('unavailable.enable.protectHint')}
+ </span>
+ </span>
+ </label>
+ </ConfirmDialog>
+ </SetupCard>
+ )
+}
diff --git a/web-studio/src/routes/gateway/-components/gateway-layout.tsx b/web-studio/src/routes/gateway/-components/gateway-layout.tsx
index 8a687cb71..a89ccd8ca 100644
--- a/web-studio/src/routes/gateway/-components/gateway-layout.tsx
+++ b/web-studio/src/routes/gateway/-components/gateway-layout.tsx
@@ -1,29 +1,18 @@
+import { useAppConnection } from '#/hooks/use-app-connection'
import * as React from 'react'
-import {
- Link,
- Outlet,
- useNavigate,
- useRouterState,
-} from '@tanstack/react-router'
+import { Outlet, useNavigate, useRouterState } from '@tanstack/react-router'
import {
ActivityIcon,
KeyRoundIcon,
LayoutDashboardIcon,
PlugIcon,
ServerIcon,
- ShieldAlertIcon,
+ LockOpenIcon,
SlidersHorizontalIcon,
} from 'lucide-react'
import { useTranslation } from 'react-i18next'
import { Button } from '#/components/ui/button'
-import {
- Card,
- CardContent,
- CardDescription,
- CardHeader,
- CardTitle,
-} from '#/components/ui/card'
import { Tabs, TabsContent, TabsList, TabsTrigger } from '#/components/ui/tabs'
import {
Tooltip,
@@ -34,7 +23,10 @@ import {
import { useConnectionInfo, useGateway } from '../-lib/use-gateway'
import { CopyButton } from './copy-button'
import { LoadingState } from './empty-state'
-import { GatewayDevMode, GatewayUnavailable } from './gateway-unavailable'
+import { GatewayConnect, GatewayUnavailable } from './gateway-unavailable'
+import { ManagementKeyDialog } from './management-key-dialog'
+import { AccessNotices } from './access-notices'
+import { lockManagementKey } from '../-lib/management-key'
import { ToneBadge } from './status-badges'
/** Sections in tab order; editor routes belong to their list's tab. */
@@ -64,27 +56,6 @@ export function gatewayTabFor(pathname: string): GatewayTab {
const tabTriggerClassName =
'h-full flex-none rounded-none border-0 px-4 text-sm data-active:bg-transparent data-active:font-semibold dark:data-active:border-transparent dark:data-active:bg-transparent focus-visible:border-transparent focus-visible:bg-transparent focus-visible:ring-0 focus-visible:outline-none focus-visible:after:h-1 focus-visible:after:bg-ring focus-visible:after:opacity-100 after:bg-primary group-data-horizontal/tabs:after:bottom-0'
-function AccessDenied() {
- const { t } = useTranslation('gateway')
- return (
- <Card className="mx-auto mt-10 w-full max-w-xl">
- <CardHeader className="items-center text-center">
- <div className="mb-2 flex size-12 items-center justify-center rounded-xl border bg-muted/40 text-muted-foreground">
- <ShieldAlertIcon className="size-5" />
- </div>
- <CardTitle>{t('access.title')}</CardTitle>
- <CardDescription>{t('access.description')}</CardDescription>
- </CardHeader>
- <CardContent className="flex justify-center">
- <Button nativeButton={false} render={<Link to="/settings" />}>
- <KeyRoundIcon />
- {t('access.action')}
- </Button>
- </CardContent>
- </Card>
- )
-}
-
function AddressChip({ address }: { address: string }) {
const { t } = useTranslation('gateway')
return (
@@ -163,16 +134,38 @@ function SectionTabs({ activeTab }: { activeTab: GatewayTab }) {
*/
export function GatewayLayout() {
const { t } = useTranslation('gateway')
+ const navigate = useNavigate()
+ const { isGatewayHost } = useAppConnection()
const pathname = useRouterState({
select: (state) => state.location.pathname,
})
- const { allowed, devMode, isRoleLoading } = useGateway()
- const probe = useConnectionInfo()
+ const {
+ allowed,
+ isRoleLoading,
+ accessQuery,
+ access,
+ managementKey,
+ connection,
+ } = useGateway()
+ const probe = useConnectionInfo({ enabled: Boolean(access) })
+ React.useEffect(() => {
+ if (isGatewayHost && !allowed && !isRoleLoading)
+ void navigate({ to: '/settings' })
+ }, [isGatewayHost, allowed, isRoleLoading, navigate])
if (isRoleLoading) return <LoadingState />
- // No key helps in development mode, so don't ask for one.
- if (devMode) return <GatewayDevMode />
- if (!allowed) return <AccessDenied />
+ if (!allowed) return <GatewayConnect />
+ if (accessQuery.isError)
+ return (
+ <GatewayUnavailable
+ error={accessQuery.error}
+ retrying={accessQuery.isFetching}
+ onRetry={() => void accessQuery.refetch()}
+ checkAccess={async () => (await accessQuery.refetch()).isSuccess}
+ />
+ )
+ if (!access) return <LoadingState />
+ const activeTab = gatewayTabFor(pathname)
return (
<div className="flex w-full min-w-0 flex-col gap-5">
@@ -188,19 +181,31 @@ export function GatewayLayout() {
{t('description')}
</p>
</div>
- {probe.data ? <AddressChip address={probe.data.base_url} /> : null}
+ <div className="flex flex-wrap items-center gap-2">
+ {probe.data ? <AddressChip address={probe.data.base_url} /> : null}
+ {access.managed && access.can_write_objects && managementKey ? (
+ <>
+ <ToneBadge tone="success">
+ <LockOpenIcon className="size-3.5" />
+ {t('management.editing')}
+ </ToneBadge>
+ <Button
+ variant="ghost"
+ size="sm"
+ onClick={() => lockManagementKey(connection.baseUrl)}
+ >
+ {t('management.lock')}
+ </Button>
+ </>
+ ) : null}
+ </div>
</header>
- {probe.data ? (
- <SectionTabs activeTab={gatewayTabFor(pathname)} />
- ) : probe.isError ? (
- <GatewayUnavailable
- error={probe.error}
- retrying={probe.isFetching}
- onRetry={() => void probe.refetch()}
- />
- ) : (
- <LoadingState />
- )}
+ <ManagementKeyDialog />
+ <AccessNotices
+ key={connection.baseUrl}
+ objectsTab={activeTab === 'upstreams' || activeTab === 'profiles'}
+ />
+ <SectionTabs activeTab={activeTab} />
</div>
)
}
diff --git a/web-studio/src/routes/gateway/-components/gateway-unavailable.tsx b/web-studio/src/routes/gateway/-components/gateway-unavailable.tsx
index 6994f3e11..748656851 100644
--- a/web-studio/src/routes/gateway/-components/gateway-unavailable.tsx
+++ b/web-studio/src/routes/gateway/-components/gateway-unavailable.tsx
@@ -1,193 +1,26 @@
-import type * as React from 'react'
import { Link } from '@tanstack/react-router'
-import {
- CircleAlertIcon,
- CodeIcon,
- ExternalLinkIcon,
- KeyRoundIcon,
- PowerOffIcon,
- RefreshCwIcon,
- ServerOffIcon,
- UnplugIcon,
-} from 'lucide-react'
+import { KeyRoundIcon, RefreshCwIcon } from 'lucide-react'
import { useTranslation } from 'react-i18next'
-
-import { Alert, AlertDescription, AlertTitle } from '#/components/ui/alert'
import { Button } from '#/components/ui/button'
-import {
- Card,
- CardContent,
- CardDescription,
- CardHeader,
- CardTitle,
-} from '#/components/ui/card'
-
-import type { GatewayError, GatewayErrorReason } from '../-lib/api'
-import { gatewayDocsUrl } from '../-lib/client-guides'
+import { useAppConnection } from '#/hooks/use-app-connection'
+import type { GatewayError } from '../-lib/api'
import { gatewayErrorMessage } from '../-lib/localize'
import { CodeBlock } from './code-block'
-
-type SetupReason = Extract<
- GatewayErrorReason,
- | 'not_enabled'
- | 'token_missing'
- | 'token_mismatch'
- | 'unreachable'
- | 'unsupported'
->
+import { EnableGatewayCard } from './gateway-enable'
+import { SetupCard } from './setup-card'
const CONFIG_FILE = 'ov.conf'
-const START_COMMAND = 'openviking-gateway --config ~/.openviking/ov.conf'
-const TOKEN_VARIABLE = 'OPENVIKING_GATEWAY_ADMIN_TOKEN=<management-token>'
-
-/** Where a fix goes: a key in ov.conf, a shell command or an environment variable. */
-type FixTarget = 'ovConf' | 'terminal' | 'environment'
-type Fix = { target: FixTarget; code: string }
-
-/** Per reason: copy keys, icon, and the exact configuration to fix. */
-const SETUP: Record<
- SetupReason,
- { copy: string; icon: React.ReactNode; fixes: Fix[] }
-> = {
- not_enabled: {
- copy: 'notEnabled',
- icon: <PowerOffIcon />,
- fixes: [
- {
- target: 'ovConf',
- code: JSON.stringify({ gateway: { enabled: true } }, null, 2),
- },
- { target: 'terminal', code: START_COMMAND },
- ],
- },
- token_missing: {
- copy: 'tokenMissing',
- icon: <KeyRoundIcon />,
- fixes: [{ target: 'environment', code: TOKEN_VARIABLE }],
- },
- token_mismatch: {
- copy: 'tokenMismatch',
- icon: <KeyRoundIcon />,
- fixes: [{ target: 'environment', code: TOKEN_VARIABLE }],
- },
- unreachable: {
- copy: 'unreachable',
- icon: <UnplugIcon />,
- fixes: [
- { target: 'terminal', code: START_COMMAND },
- {
- target: 'ovConf',
- code: JSON.stringify(
- { gateway: { url: 'http://127.0.0.1:1935' } },
- null,
- 2,
- ),
- },
- ],
- },
- unsupported: {
- copy: 'unsupported',
- icon: <ServerOffIcon />,
- fixes: [
- {
- target: 'terminal',
- code: 'pip install --upgrade "openviking[gateway]"',
- },
- ],
- },
-}
-
-/** Card with an icon tile, an explanation, the exact fix and actions. */
-function SetupCard({
- icon,
- title,
- description,
- fixes,
- actions,
-}: {
- icon: React.ReactNode
- title: string
- description: string
- fixes: Fix[]
- actions?: React.ReactNode
-}) {
- const { t, i18n } = useTranslation('gateway')
- return (
- <Card className="mx-auto w-full max-w-2xl">
- <CardHeader className="gap-3">
- <div className="flex size-11 items-center justify-center rounded-xl border bg-muted/40 text-muted-foreground [&_svg]:size-5">
- {icon}
- </div>
- <CardTitle className="text-lg">{title}</CardTitle>
- <CardDescription className="leading-6">{description}</CardDescription>
- </CardHeader>
- <CardContent className="grid gap-4">
- <div className="grid gap-2">
- <p className="text-sm font-medium">{t('unavailable.fixLabel')}</p>
- {fixes.map((fix) => (
- <CodeBlock
- key={fix.code}
- label={
- fix.target === 'ovConf'
- ? CONFIG_FILE
- : t(`unavailable.${fix.target}`)
- }
- code={fix.code}
- />
- ))}
- </div>
- <div className="flex flex-wrap items-center gap-2">
- {actions}
- <Button
- variant="ghost"
- size="sm"
- nativeButton={false}
- render={
- <a
- href={gatewayDocsUrl('operations', i18n.resolvedLanguage)}
- target="_blank"
- rel="noreferrer"
- />
- }
- >
- <ExternalLinkIcon />
- {t('unavailable.docs')}
- </Button>
- </div>
- </CardContent>
- </Card>
- )
-}
-
-/**
- * Shown instead of the gateway pages while OpenViking runs in development
- * mode: every key acts as root there, which the gateway refuses.
- */
-export function GatewayDevMode() {
+export function GatewayConnect({ invalid = false }: { invalid?: boolean }) {
const { t } = useTranslation('gateway')
return (
<SetupCard
- icon={<CodeIcon />}
- title={t('unavailable.devMode.title')}
- description={t('unavailable.devMode.description')}
- fixes={[
- {
- target: 'ovConf',
- code: JSON.stringify(
- { server: { auth_mode: 'api_key', root_api_key: '<root-key>' } },
- null,
- 2,
- ),
- },
- ]}
+ title={t(invalid ? 'access.invalid' : 'access.title')}
+ description={t(
+ invalid ? 'access.invalidDescription' : 'access.description',
+ )}
actions={
- <Button
- variant="outline"
- size="sm"
- nativeButton={false}
- render={<Link to="/settings" />}
- >
+ <Button nativeButton={false} render={<Link to="/settings" />}>
<KeyRoundIcon />
{t('access.action')}
</Button>
@@ -196,55 +29,94 @@ export function GatewayDevMode() {
)
}
-type GatewayUnavailableProps = {
- error: GatewayError
- onRetry: () => void
- retrying?: boolean
-}
-
-/**
- * What the layout shows when the gateway can't be managed: a setup card with
- * the exact fix when it is off, misconfigured or down, otherwise the error.
- */
export function GatewayUnavailable({
error,
onRetry,
+ checkAccess,
retrying = false,
-}: GatewayUnavailableProps) {
+}: {
+ error: GatewayError
+ onRetry: () => void
+ /** Asks for /access again; resolves true when the gateway answers. */
+ checkAccess: () => Promise<boolean>
+ retrying?: boolean
+}) {
const { t } = useTranslation('gateway')
+ const { connectionRole, serverMode, openvikingUrl, isGatewayHost } =
+ useAppConnection()
+ const isRoot = serverMode === 'dev' || connectionRole === 'root'
+ // On an OpenViking server only root can change ov.conf; a standalone
+ // gateway host keeps showing the instructions to its admins as well.
+ const canConfigure = isRoot || (isGatewayHost && connectionRole === 'admin')
const retry = (
- <Button
- type="button"
- variant="outline"
- size="sm"
- disabled={retrying}
- onClick={onRetry}
- >
+ <Button variant="outline" size="sm" disabled={retrying} onClick={onRetry}>
<RefreshCwIcon className={retrying ? 'animate-spin' : undefined} />
{t('actions.retry')}
</Button>
)
-
- if (!error.unavailable) {
+ if (error.status === 401 && error.reason !== 'management_key_invalid')
+ return <GatewayConnect invalid />
+ if (error.reason === 'not_enabled' || error.status === 404) {
+ if (!canConfigure)
+ return (
+ <SetupCard
+ title={t('unavailable.notEnabled.title')}
+ description={t('unavailable.contact')}
+ actions={retry}
+ />
+ )
+ const instructions = (
+ <SetupCard
+ title={t('unavailable.notEnabled.title')}
+ description={t('unavailable.notEnabled.description')}
+ actions={retry}
+ >
+ <CodeBlock
+ label={t('unavailable.terminal')}
+ code="openviking-server init"
+ />
+ <CodeBlock label={CONFIG_FILE} code={'{"gateway":{"enabled":true}}'} />
+ </SetupCard>
+ )
+ // Studio edits ov.conf through the admin API, which needs a root key.
+ if (isGatewayHost || serverMode !== 'api_key') return instructions
return (
- <Alert variant="destructive">
- <CircleAlertIcon />
- <AlertTitle>{t('unavailable.failed.title')}</AlertTitle>
- <AlertDescription className="grid gap-3">
- <p>{gatewayErrorMessage(t, error)}</p>
- <div>{retry}</div>
- </AlertDescription>
- </Alert>
+ <EnableGatewayCard
+ retry={retry}
+ retrying={retrying}
+ onOpenGateway={checkAccess}
+ fallback={instructions}
+ />
)
}
-
- const setup = SETUP[error.reason as SetupReason]
+ if (error.reason === 'trusted_mode_unsupported')
+ return (
+ <SetupCard
+ title={t('unavailable.trusted.title')}
+ description={t('unavailable.trusted.description')}
+ actions={retry}
+ >
+ <CodeBlock
+ label={CONFIG_FILE}
+ code={'{"server":{"auth_mode":"api_key"}}'}
+ />
+ </SetupCard>
+ )
+ // Only a standalone gateway has an OpenViking URL and gateway.conf to fix.
+ if (error.reason === 'openviking_unreachable' && isGatewayHost)
+ return (
+ <SetupCard
+ title={t('unavailable.openvikingUnreachable.title', {
+ url: openvikingUrl,
+ })}
+ description={t('unavailable.openvikingUnreachable.description')}
+ actions={retry}
+ />
+ )
return (
<SetupCard
- icon={setup.icon}
- title={t(`unavailable.${setup.copy}.title`)}
- description={t(`unavailable.${setup.copy}.description`)}
- fixes={setup.fixes}
+ title={t('unavailable.failed.title')}
+ description={gatewayErrorMessage(t, error)}
actions={retry}
/>
)
diff --git a/web-studio/src/routes/gateway/-components/key-value-editor.tsx b/web-studio/src/routes/gateway/-components/key-value-editor.tsx
index eee3ba294..72b9d70bf 100644
--- a/web-studio/src/routes/gateway/-components/key-value-editor.tsx
+++ b/web-studio/src/routes/gateway/-components/key-value-editor.tsx
@@ -1,3 +1,4 @@
+import { useReadOnly } from './read-only'
import * as React from 'react'
import { PlusIcon, Trash2Icon } from 'lucide-react'
import { useTranslation } from 'react-i18next'
@@ -9,6 +10,7 @@ import { PLAIN_INPUT_PROPS } from '#/lib/form-input'
type Row = { id: number; key: string; value: string }
type CommonProps = {
+ disabled?: boolean
keyPlaceholder: string
valuePlaceholder: string
/** Label of the add button; defaults to "Add". */
@@ -55,6 +57,8 @@ function sameRecord(a: object, b: object): boolean {
* out of the value; when a name repeats, the last row wins and is flagged.
*/
export function KeyValueEditor(props: KeyValueEditorProps) {
+ const readOnly = useReadOnly()
+ const disabled = props.disabled || readOnly
const { t } = useTranslation('gateway')
const { storedKeys = [], maskValues } = props
const [rows, setRows] = React.useState(() => toRows(props.value))
@@ -105,6 +109,7 @@ export function KeyValueEditor(props: KeyValueEditorProps) {
<div key={row.id} className="grid gap-1">
<div className="grid grid-cols-[minmax(0,1fr)_minmax(0,1fr)_auto] items-center gap-2">
<Input
+ disabled={disabled}
{...PLAIN_INPUT_PROPS}
value={row.key}
placeholder={props.keyPlaceholder}
@@ -116,6 +121,7 @@ export function KeyValueEditor(props: KeyValueEditorProps) {
}
/>
<Input
+ disabled={disabled}
{...PLAIN_INPUT_PROPS}
type={
maskValues ? 'password' : props.numeric ? 'number' : 'text'
@@ -133,18 +139,21 @@ export function KeyValueEditor(props: KeyValueEditorProps) {
change(row.id, { value: event.target.value })
}
/>
- <Button
- type="button"
- variant="ghost"
- size="icon-sm"
- aria-label={t('keyValue.remove')}
- className="text-muted-foreground hover:bg-destructive/10 hover:text-destructive"
- onClick={() =>
- update(rows.filter((other) => other.id !== row.id))
- }
- >
- <Trash2Icon />
- </Button>
+ {readOnly ? null : (
+ <Button
+ disabled={disabled}
+ type="button"
+ variant="ghost"
+ size="icon-sm"
+ aria-label={t('keyValue.remove')}
+ className="text-muted-foreground hover:bg-destructive/10 hover:text-destructive"
+ onClick={() =>
+ update(rows.filter((other) => other.id !== row.id))
+ }
+ >
+ <Trash2Icon />
+ </Button>
+ )}
</div>
{duplicate ? (
<p className="text-xs text-amber-600 dark:text-amber-300">
@@ -154,19 +163,27 @@ export function KeyValueEditor(props: KeyValueEditorProps) {
</div>
)
})}
- <div>
- <Button
- type="button"
- variant="outline"
- size="sm"
- onClick={() =>
- setRows([...rows, { id: nextRowId++, key: '', value: '' }])
- }
- >
- <PlusIcon />
- {props.addLabel ?? t('keyValue.add')}
- </Button>
- </div>
+ {/* A read-only view shows what is set, not how to add more. */}
+ {readOnly ? (
+ rows.length ? null : (
+ <p className="text-sm text-muted-foreground">{t('keyValue.none')}</p>
+ )
+ ) : (
+ <div>
+ <Button
+ disabled={disabled}
+ type="button"
+ variant="outline"
+ size="sm"
+ onClick={() =>
+ setRows([...rows, { id: nextRowId++, key: '', value: '' }])
+ }
+ >
+ <PlusIcon />
+ {props.addLabel ?? t('keyValue.add')}
+ </Button>
+ </div>
+ )}
</div>
)
}
diff --git a/web-studio/src/routes/gateway/-components/keys-dialogs.test.tsx b/web-studio/src/routes/gateway/-components/keys-dialogs.test.tsx
index d18d32e30..a3d0e2740 100644
--- a/web-studio/src/routes/gateway/-components/keys-dialogs.test.tsx
+++ b/web-studio/src/routes/gateway/-components/keys-dialogs.test.tsx
@@ -24,13 +24,18 @@ import {
} from './keys-issue-dialog'
import { KeysSecretDialog, snippetModel } from './keys-secret-dialog'
-const api = vi.hoisted(() => ({ issueKey: vi.fn(), listKeyUsers: vi.fn() }))
-const state = vi.hoisted(() => ({ role: 'admin' }))
+const api = vi.hoisted(() => ({
+ issueKey: vi.fn(),
+ listKeyUsers: vi.fn(),
+ getAccess: vi.fn(),
+}))
+const state = vi.hoisted(() => ({ role: 'admin', devMode: false }))
vi.mock('../-lib/api', async (importOriginal) => ({
...(await importOriginal<typeof Api>()),
issueKey: api.issueKey,
listKeyUsers: api.listKeyUsers,
+ getAccess: api.getAccess,
}))
vi.mock('sonner', () => ({ toast: { success: vi.fn(), error: vi.fn() } }))
vi.mock('react-i18next', () => ({
@@ -50,7 +55,7 @@ vi.mock('#/hooks/use-app-connection', () => ({
},
connectionRole: state.role,
isConnectionRoleLoading: false,
- serverMode: 'api_key',
+ serverMode: state.devMode ? 'dev' : 'api_key',
}),
}))
vi.mock('@tanstack/react-router', async (importOriginal) => ({
@@ -64,6 +69,16 @@ afterEach(cleanup)
beforeEach(() => {
vi.clearAllMocks()
state.role = 'admin'
+ state.devMode = false
+ api.getAccess.mockImplementation(async () => ({
+ managed: false,
+ can_write_objects: true,
+ can_issue_for_others: state.role !== 'user' && !state.devMode,
+ role: state.role,
+ account_id: 'acme',
+ user_id: 'admin',
+ warnings: [],
+ }))
api.listKeyUsers.mockResolvedValue([alice])
})
@@ -118,7 +133,7 @@ const settings = {
models: [],
}
const request = { ...settings, user_id: 'alice' }
-const pasted = { ...settings, openviking_key: 'ov-key' }
+const pasted = { ...settings, user_id: 'alice', openviking_key: 'ov-key' }
describe('validateKeyRequest', () => {
it('accepts a complete request for a user or with a pasted key', () => {
@@ -143,6 +158,16 @@ describe('validateKeyRequest', () => {
})
})
+ it('accepts self issuance with no owner', () => {
+ expect(validateKeyRequest(settings)).toEqual({})
+ })
+
+ it('rejects a management key pasted as the user API key', () => {
+ expect(
+ validateKeyRequest({ ...settings, openviking_key: 'ovgm_abc' }),
+ ).toEqual({ openviking_key: 'keys.form.openvikingKey.managementKey' })
+ })
+
it('rejects a gateway key pasted as the OpenViking key', () => {
expect(
validateKeyRequest({ ...settings, openviking_key: 'ovgw_abc' }),
@@ -152,25 +177,11 @@ describe('validateKeyRequest', () => {
describe('issueProblem', () => {
it.each([
- [
- 'Unknown OpenViking user in this account',
- 400,
- 'keys.errors.unknownUser',
- true,
- ],
- [
- "This user's OpenViking key cannot be read on the server; paste the user's OpenViking key instead",
- 409,
- 'keys.errors.userKeyUnreadable',
- true,
- ],
+ ['unknown_user', 400, 'keys.errors.unknownUser', true],
+ ['user_required', 400, 'keys.errors.userRequired', true],
+ ['user_key_unreadable', 409, 'keys.errors.userKeyUnreadable', true],
['root_key_not_allowed', 403, 'keys.errors.rootKey', true],
- [
- 'OpenViking key belongs to another account',
- 403,
- 'keys.errors.otherAccount',
- true,
- ],
+ ['other_account', 403, 'keys.errors.otherAccount', true],
['openviking_http_401', 401, 'keys.errors.invalidKey', true],
[
'openviking_identity_missing',
@@ -180,12 +191,42 @@ describe('issueProblem', () => {
],
['openviking_unavailable', 503, 'keys.errors.unavailable', false],
['openviking_version_mismatch', 503, 'keys.errors.versionMismatch', false],
- ['Unknown upstream', 400, 'errors.unknownUpstream', false],
- ])('maps %s', (detail, status, message, keyField) => {
- expect(issueProblem(t, new GatewayError(detail, status))).toEqual({
- message,
- keyField,
- })
+ ])(
+ 'maps stable reason %s independent of detail',
+ (reason, status, message, keyField) => {
+ expect(
+ issueProblem(
+ t,
+ new GatewayError(
+ 'arbitrary server wording',
+ status,
+ undefined,
+ reason,
+ ),
+ ),
+ ).toEqual({ message, keyField })
+ },
+ )
+ it('includes the required version', () => {
+ const translate = ((key: string, values?: { version?: string }) =>
+ values?.version ?? key) as Translate
+ expect(
+ issueProblem(
+ translate,
+ new GatewayError(
+ 'upgrade',
+ 503,
+ undefined,
+ 'openviking_version_mismatch',
+ { required_version: '0.5.0' },
+ ),
+ ).message,
+ ).toContain('0.5.0')
+ })
+ it('does not infer a reason from English detail', () => {
+ expect(
+ issueProblem(t, new GatewayError('root_key_not_allowed', 400)).keyField,
+ ).toBe(false)
})
})
@@ -237,16 +278,19 @@ function pasteKey(value: string) {
fireEvent.click(
screen.getByRole('button', { name: 'keys.form.openvikingKey.paste' }),
)
- fireEvent.change(screen.getByLabelText('keys.form.openvikingKey.label'), {
- target: { value },
- })
+ fireEvent.change(
+ screen.getByLabelText(/keys.form.openvikingKey.(forUser|label)/),
+ {
+ target: { value },
+ },
+ )
}
const submit = () =>
fireEvent.click(screen.getByRole('button', { name: 'keys.form.submit' }))
describe('KeysIssueDialog', () => {
- it('lists the account users and disables those whose key the server cannot read', async () => {
+ it('lists every account user including users whose key must be pasted', async () => {
api.listKeyUsers.mockResolvedValue([hashed, boss, alice])
api.issueKey.mockResolvedValue({})
renderIssueDialog()
@@ -266,7 +310,7 @@ describe('KeysIssueDialog', () => {
'bosskeys.form.user.roles.admin',
'hashedkeys.form.user.roles.userkeys.form.user.unavailable',
])
- expect(options[2].getAttribute('aria-disabled')).toBe('true')
+ expect(options[2].getAttribute('aria-disabled')).not.toBe('true')
expect(options[1].getAttribute('aria-disabled')).not.toBe('true')
// Base UI selects only the highlighted option; hovering highlights it.
fireEvent.mouseMove(options[1])
@@ -281,15 +325,22 @@ describe('KeysIssueDialog', () => {
)
})
- it('preselects the only user whose key the server can read', async () => {
- api.listKeyUsers.mockResolvedValue([alice, hashed])
+ it('defaults to the signed-in user when other users exist', async () => {
+ api.listKeyUsers.mockResolvedValue([
+ { ...boss, user_id: 'admin' },
+ alice,
+ hashed,
+ ])
api.issueKey.mockResolvedValue({})
renderIssueDialog()
- await fillRequiredFields()
+ fillName()
+ await waitFor(() => expect(userPicker().textContent).toContain('admin'))
submit()
-
await waitFor(() =>
- expect(api.issueKey).toHaveBeenCalledWith(expect.anything(), request),
+ expect(api.issueKey).toHaveBeenCalledWith(expect.anything(), {
+ ...request,
+ user_id: 'admin',
+ }),
)
})
@@ -324,7 +375,7 @@ describe('KeysIssueDialog', () => {
)
await waitFor(() =>
expect(document.activeElement).toBe(
- screen.getByLabelText('keys.form.openvikingKey.label'),
+ screen.getByLabelText(/keys.form.openvikingKey.(forUser|label)/),
),
)
fireEvent.click(
@@ -333,32 +384,139 @@ describe('KeysIssueDialog', () => {
await waitFor(() => expect(document.activeElement).toBe(userPicker()))
})
- it('asks root for a pasted key without listing users', async () => {
- // A root key may act on another account than the one Studio shows.
+ it('lets root choose a user in the selected account', async () => {
state.role = 'root'
api.issueKey.mockResolvedValue({})
renderIssueDialog()
+ await fillRequiredFields()
+ submit()
+ await waitFor(() =>
+ expect(api.issueKey).toHaveBeenCalledWith(expect.anything(), request),
+ )
+ expect(api.listKeyUsers).toHaveBeenCalledWith(
+ expect.objectContaining({ accountId: 'acme' }),
+ )
+ })
+
+ it.each([false, true])(
+ 'issues for the current identity without an owner (dev: %s)',
+ async (devMode) => {
+ state.role = devMode ? 'root' : 'user'
+ state.devMode = devMode
+ api.issueKey.mockResolvedValue({})
+ renderIssueDialog()
+ fillName()
+ await screen.findByText(
+ devMode ? 'keys.form.user.developmentIdentity' : 'keys.form.user.self',
+ )
+ expect(
+ screen.queryByRole('combobox', { name: 'keys.form.user.label' }),
+ ).toBeNull()
+ submit()
+ await waitFor(() =>
+ expect(api.issueKey).toHaveBeenCalledWith(expect.anything(), settings),
+ )
+ expect(api.listKeyUsers).not.toHaveBeenCalled()
+ },
+ )
+
+ it('focuses the paste field when a selected user key is unreadable', async () => {
+ api.listKeyUsers.mockResolvedValue([hashed])
+ renderIssueDialog()
+ const field = await screen.findByLabelText(
+ 'keys.form.openvikingKey.forUser',
+ )
+ await waitFor(() => expect(document.activeElement).toBe(field))
+ })
+
+ it('asks for a pasted key while an unreadable user is selected', async () => {
+ api.listKeyUsers.mockResolvedValue([alice, hashed])
+ api.issueKey.mockResolvedValue({})
+ renderIssueDialog()
fillName()
+ await waitFor(() =>
+ expect(userPicker().hasAttribute('disabled')).toBe(false),
+ )
+ const pick = async (name: RegExp) => {
+ fireEvent.click(userPicker())
+ const option = await screen.findByRole('option', { name })
+ fireEvent.mouseMove(option)
+ fireEvent.click(option)
+ }
+ await pick(/hashed/)
+ const field = await screen.findByLabelText(
+ 'keys.form.openvikingKey.forUser',
+ )
+ await waitFor(() => expect(document.activeElement).toBe(field))
+ // Choosing a user whose key the server can read drops the paste field.
+ await pick(/alice/)
+ await waitFor(() =>
+ expect(
+ screen.queryByLabelText('keys.form.openvikingKey.forUser'),
+ ).toBeNull(),
+ )
+ submit()
+ await waitFor(() =>
+ expect(api.issueKey).toHaveBeenCalledWith(expect.anything(), request),
+ )
+ })
- expect(screen.getByText('keys.form.user.root')).toBeTruthy()
+ it('never asks an admin to paste their own key', async () => {
+ api.listKeyUsers.mockResolvedValue([
+ { ...hashed, user_id: 'admin', role: 'admin' },
+ alice,
+ ])
+ api.issueKey.mockResolvedValue({})
+ renderIssueDialog()
+ fillName()
+ await waitFor(() => expect(userPicker().textContent).toContain('admin'))
expect(
- screen.queryByRole('button', { name: 'keys.form.user.choose' }),
+ screen.queryByLabelText('keys.form.openvikingKey.forUser'),
).toBeNull()
- fireEvent.change(screen.getByLabelText('keys.form.openvikingKey.label'), {
- target: { value: 'ov-key' },
- })
submit()
+ await waitFor(() =>
+ expect(api.issueKey).toHaveBeenCalledWith(expect.anything(), {
+ ...request,
+ user_id: 'admin',
+ }),
+ )
+ })
+ it('switches and focuses the paste field on user_key_unreadable, then retries', async () => {
+ api.issueKey
+ .mockRejectedValueOnce(
+ new GatewayError(
+ 'changed wording',
+ 409,
+ undefined,
+ 'user_key_unreadable',
+ ),
+ )
+ .mockResolvedValueOnce({})
+ renderIssueDialog()
+ await fillRequiredFields()
+ submit()
+ const field = await screen.findByLabelText(
+ 'keys.form.openvikingKey.forUser',
+ )
+ await waitFor(() => expect(document.activeElement).toBe(field))
+ expect(screen.getByText('keys.errors.userKeyUnreadable')).toBeTruthy()
+ fireEvent.change(field, { target: { value: 'ov-key' } })
+ submit()
await waitFor(() =>
- expect(api.issueKey).toHaveBeenCalledWith(expect.anything(), pasted),
+ expect(api.issueKey).toHaveBeenLastCalledWith(expect.anything(), pasted),
)
- expect(api.listKeyUsers).not.toHaveBeenCalled()
})
it('keeps a removed user unselected instead of choosing another', async () => {
api.listKeyUsers.mockResolvedValue([alice, boss])
api.issueKey.mockRejectedValue(
- new GatewayError('Unknown OpenViking user in this account', 400),
+ new GatewayError(
+ 'Unknown OpenViking user in this account',
+ 400,
+ undefined,
+ 'unknown_user',
+ ),
)
renderIssueDialog()
fillName()
@@ -385,7 +543,12 @@ describe('KeysIssueDialog', () => {
it('retries a preselected user rather than another one', async () => {
api.issueKey.mockRejectedValue(
- new GatewayError('Unknown OpenViking user in this account', 400),
+ new GatewayError(
+ 'Unknown OpenViking user in this account',
+ 400,
+ undefined,
+ 'unknown_user',
+ ),
)
renderIssueDialog()
await fillRequiredFields()
@@ -404,35 +567,19 @@ describe('KeysIssueDialog', () => {
['the users cannot be listed', 'keys.form.user.loadFailed', false],
['no user key can be read', 'keys.form.user.none', true],
])('asks for a pasted key when %s', async (_case, reason, listed) => {
- if (listed) api.listKeyUsers.mockResolvedValue([hashed])
+ if (listed) api.listKeyUsers.mockResolvedValue([])
else api.listKeyUsers.mockRejectedValue(new GatewayError('Forbidden', 403))
renderIssueDialog()
expect(await screen.findByText(reason)).toBeTruthy()
- expect(screen.getByLabelText('keys.form.openvikingKey.label')).toBeTruthy()
+ expect(
+ screen.getByLabelText(/keys.form.openvikingKey.(forUser|label)/),
+ ).toBeTruthy()
expect(
screen.queryByRole('button', { name: 'keys.form.user.choose' }),
).toBeNull()
})
- it('explains an unreadable user key next to the picker', async () => {
- api.issueKey.mockRejectedValue(
- new GatewayError(
- "This user's OpenViking key cannot be read on the server; paste the user's OpenViking key instead",
- 409,
- ),
- )
- renderIssueDialog()
- await fillRequiredFields()
- submit()
-
- expect(
- await screen.findByText('keys.errors.userKeyUnreadable'),
- ).toBeTruthy()
- expect(userPicker().getAttribute('aria-invalid')).toBe('true')
- expect(screen.queryByText('keys.errors.title')).toBeNull()
- })
-
it('shows what is missing instead of sending an incomplete request', async () => {
renderIssueDialog([deepseek, openai])
await fillRequiredFields()
@@ -474,32 +621,71 @@ describe('KeysIssueDialog', () => {
it('explains a rejected OpenViking key next to that field', async () => {
api.issueKey.mockRejectedValue(
- new GatewayError('root_key_not_allowed', 403),
+ new GatewayError(
+ 'root_key_not_allowed',
+ 403,
+ undefined,
+ 'root_key_not_allowed',
+ ),
)
const { onIssued } = renderIssueDialog()
- fillName()
+ await fillRequiredFields()
pasteKey('ov-key')
submit()
expect(await screen.findByText('keys.errors.rootKey')).toBeTruthy()
expect(
screen
- .getByLabelText('keys.form.openvikingKey.label')
+ .getByLabelText('keys.form.openvikingKey.forUser')
.getAttribute('aria-invalid'),
).toBe('true')
expect(screen.queryByText('keys.errors.title')).toBeNull()
expect(onIssued).not.toHaveBeenCalled()
// Editing the key clears the server's verdict.
- fireEvent.change(screen.getByLabelText('keys.form.openvikingKey.label'), {
- target: { value: 'another-key' },
- })
+ fireEvent.change(
+ screen.getByLabelText(/keys.form.openvikingKey.(forUser|label)/),
+ {
+ target: { value: 'another-key' },
+ },
+ )
expect(screen.queryByText('keys.errors.rootKey')).toBeNull()
})
+ it('rejects a management key pasted into the user-key field before sending', async () => {
+ renderIssueDialog()
+ await fillRequiredFields()
+ pasteKey('ovgm_wrong_place')
+ submit()
+ expect(
+ screen.getByText('keys.form.openvikingKey.managementKey'),
+ ).toBeTruthy()
+ expect(api.issueKey).not.toHaveBeenCalled()
+ })
+
+ it('labels blocked Coding Plan upstreams and keeps them selectable', async () => {
+ api.issueKey.mockResolvedValue({})
+ renderIssueDialog([
+ { ...deepseek, coding_plan: true, allow_coding_plan: false },
+ ])
+ await fillRequiredFields()
+ expect(screen.getByText('keys.form.upstreams.blocked')).toBeTruthy()
+ const checkbox = screen.getByRole('checkbox')
+ expect(checkbox.getAttribute('aria-disabled')).not.toBe('true')
+ submit()
+ await waitFor(() =>
+ expect(api.issueKey).toHaveBeenCalledWith(expect.anything(), request),
+ )
+ })
+
it('shows other failures in an alert inside the dialog', async () => {
api.issueKey.mockRejectedValue(
- new GatewayError('openviking_unavailable', 503),
+ new GatewayError(
+ 'openviking_unavailable',
+ 503,
+ undefined,
+ 'openviking_unavailable',
+ ),
)
renderIssueDialog()
await fillRequiredFields()
@@ -531,7 +717,7 @@ describe('KeysSecretDialog', () => {
<KeysSecretDialog
open
issued={issued}
- baseUrl="https://gw.example.com"
+ baseUrl="https://gw.example.com/gateway"
profileName="Coding"
upstreams={upstreams}
onDone={onDone}
@@ -555,11 +741,12 @@ describe('KeysSecretDialog', () => {
it('opens on a client the key can serve, with the real key and address', () => {
renderSecret()
- expect(screen.getByText('alice')).toBeTruthy()
+ expect(screen.getByText('keys.secret.identity')).toBeTruthy()
+ expect(screen.getByText('keys.secret.dependency')).toBeTruthy()
expect(screen.getByText('Coding')).toBeTruthy()
// Only a Chat Completions upstream: the chat client tab is selected.
const snippet = screen.getByText(/chat\.completions\.create/)
- expect(snippet.textContent).toContain('https://gw.example.com/v1')
+ expect(snippet.textContent).toContain('https://gw.example.com/gateway/v1')
expect(snippet.textContent).toContain('ovgw_theSecret')
expect(snippet.textContent).toContain('deepseek-chat')
expect(screen.queryByText('keys.secret.noProtocol')).toBeNull()
diff --git a/web-studio/src/routes/gateway/-components/keys-issue-dialog.tsx b/web-studio/src/routes/gateway/-components/keys-issue-dialog.tsx
index 7fdb48d60..e170aee3c 100644
--- a/web-studio/src/routes/gateway/-components/keys-issue-dialog.tsx
+++ b/web-studio/src/routes/gateway/-components/keys-issue-dialog.tsx
@@ -43,6 +43,7 @@ import type {
} from '../-lib/api'
import { gatewayErrorMessage } from '../-lib/localize'
import type { Translate } from '../-lib/localize'
+import { requestManagementUnlock } from '../-lib/management-key'
import { NEW_ID } from '../-lib/search'
import { servedModels } from '../-lib/upstream-schema'
import { useGateway, useKeyUsers } from '../-lib/use-gateway'
@@ -70,11 +71,14 @@ export function validateKeyRequest(request: KeyRequest): KeyRequestErrors {
if (!request.name.trim()) errors.name = 'validation.required'
if (request.user_id !== undefined) {
if (!request.user_id) errors.user_id = 'validation.required'
- } else {
+ }
+ if (request.openviking_key !== undefined) {
const secret = request.openviking_key.trim()
if (!secret) errors.openviking_key = 'validation.required'
else if (secret.startsWith(GATEWAY_KEY_PREFIX)) {
errors.openviking_key = 'keys.form.openvikingKey.gatewayKey'
+ } else if (secret.startsWith('ovgm_')) {
+ errors.openviking_key = 'keys.form.openvikingKey.managementKey'
}
}
if (!request.policy_id) errors.policy_id = 'validation.required'
@@ -84,29 +88,20 @@ export function validateKeyRequest(request: KeyRequest): KeyRequestErrors {
return errors
}
-/** Issuance failures about the user or their key, with copy that says what to do. */
-const ISSUE_ERRORS: Array<[RegExp, string, boolean]> = [
- [
- /^Unknown OpenViking user in this account$/,
- 'keys.errors.unknownUser',
- true,
- ],
- [
- /^This user's OpenViking key cannot be read/,
- 'keys.errors.userKeyUnreadable',
- true,
- ],
- [/^root_key_not_allowed$/, 'keys.errors.rootKey', true],
- [
- /^OpenViking key belongs to another account/i,
- 'keys.errors.otherAccount',
- true,
- ],
- [/^openviking_http_40[13]$/, 'keys.errors.invalidKey', true],
- [/^openviking_identity_missing$/, 'enums.openviking.identityMissing', true],
- [/^openviking_unavailable$/, 'keys.errors.unavailable', false],
- [/^openviking_version_mismatch$/, 'keys.errors.versionMismatch', false],
-]
+/** Stable backend reasons; server wording is deliberately not used for matching. */
+const ISSUE_REASONS: Partial<Record<string, [string, boolean]>> = {
+ unknown_user: ['keys.errors.unknownUser', true],
+ user_required: ['keys.errors.userRequired', true],
+ user_key_unreadable: ['keys.errors.userKeyUnreadable', true],
+ root_key_not_allowed: ['keys.errors.rootKey', true],
+ other_account: ['keys.errors.otherAccount', true],
+ openviking_http_401: ['keys.errors.invalidKey', true],
+ openviking_http_403: ['keys.errors.invalidKey', true],
+ openviking_identity_missing: ['enums.openviking.identityMissing', true],
+ openviking_unavailable: ['keys.errors.unavailable', false],
+ openviking_unreachable: ['keys.errors.unavailable', false],
+ openviking_version_mismatch: ['keys.errors.versionMismatch', false],
+}
export type IssueProblem = {
message: string
@@ -116,9 +111,17 @@ export type IssueProblem = {
/** A localized explanation of why issuing a key failed. */
export function issueProblem(t: Translate, error: unknown): IssueProblem {
- const { detail } = toGatewayError(error)
- const known = ISSUE_ERRORS.find(([pattern]) => pattern.test(detail))
- if (known) return { message: t(known[1]), keyField: known[2] }
+ const { reason, requiredVersion } = toGatewayError(error)
+ const known = ISSUE_REASONS[reason]
+ if (known)
+ return {
+ message:
+ t(known[0]) +
+ (requiredVersion
+ ? ` ${t('keys.errors.requiredVersion', { version: requiredVersion })}`
+ : ''),
+ keyField: known[1],
+ }
return { message: gatewayErrorMessage(t, error), keyField: false }
}
@@ -127,7 +130,7 @@ function byName<T extends { name: string }>(items: T[]): T[] {
}
/** Whether the admin picks the key's user or pastes that user's OpenViking key. */
-type OwnerMode = 'user' | 'key'
+type OwnerMode = 'self' | 'user' | 'key'
/** Form state; keeps the picked user and the pasted key while switching modes. */
type KeyDraft = Omit<KeyRequest, keyof KeyOwner> & {
@@ -158,16 +161,19 @@ export function KeysIssueDialog({
onIssued,
}: KeysIssueDialogProps) {
const { t } = useTranslation('gateway')
- const { connection, invalidate, role } = useGateway()
- // OpenViking may resolve a root key to another account than the one Studio
- // shows, so only an account admin picks the user; root pastes their key.
- const canPickUser = role === 'admin'
+ const {
+ connection,
+ invalidate,
+ access,
+ devMode,
+ readOnly,
+ canIssueForOthers: canPickUser,
+ } = useGateway()
+ const selfId = access?.user_id ?? connection.userId
const usersQuery = useKeyUsers({ enabled: open && canPickUser })
const formId = React.useId()
const userTriggerRef = React.useRef<HTMLButtonElement>(null)
const keyInputRef = React.useRef<HTMLInputElement>(null)
- /** Set by a switch the admin makes, so the new field gets focus. */
- const focusOwner = React.useRef(false)
const [draft, setDraft] = React.useState<KeyDraft>(() => ({
name: '',
user_id: '',
@@ -176,7 +182,8 @@ export function KeysIssueDialog({
upstream_ids: upstreams.length === 1 ? [upstreams[0].id] : [],
models: [],
}))
- const [chosenMode, setChosenMode] = React.useState<OwnerMode>('user')
+ /** 'key' once the admin switches to pasting, or the server asks for it. */
+ const [chosenMode, setChosenMode] = React.useState<'user' | 'key'>('user')
const [submitted, setSubmitted] = React.useState(false)
const issue = useMutation({
@@ -187,7 +194,8 @@ export function KeysIssueDialog({
},
onError: (error) => {
// A user, profile or upstream changed meanwhile; show the current lists.
- const { status } = toGatewayError(error)
+ const { status, reason } = toGatewayError(error)
+ if (reason === 'user_key_unreadable') setChosenMode('key')
if (status === 400 || status === 409) {
void invalidate('users', 'profiles', 'upstreams')
}
@@ -198,31 +206,41 @@ export function KeysIssueDialog({
const users = [...(usersQuery.data ?? [])].sort((a, b) =>
a.user_id.localeCompare(b.user_id),
)
- const available = users.filter((user) => user.api_key_available)
- // Without a user whose key the server can read, pasting is the only way.
- const fallback = !canPickUser
- ? 'root'
- : usersQuery.isError
+ const fallback =
+ canPickUser && usersQuery.isError
? 'loadFailed'
- : usersQuery.isSuccess && !available.length
+ : canPickUser && usersQuery.isSuccess && !users.length
? 'none'
: undefined
- const mode: OwnerMode = fallback ? 'key' : chosenMode
- // Only an empty choice is filled in; a chosen user who disappears leaves
- // the picker empty rather than switching to someone else.
+ const mode: OwnerMode =
+ fallback || chosenMode === 'key' ? 'key' : canPickUser ? 'user' : 'self'
+ // Prefer the current identity, and preserve an explicit selection across retries.
const userId = draft.user_id
- ? available.some((user) => user.user_id === draft.user_id)
+ ? users.some((user) => user.user_id === draft.user_id)
? draft.user_id
: ''
- : available.length === 1
- ? available[0].user_id
- : ''
+ : users.some((user) => user.user_id === selfId)
+ ? selfId
+ : users.length === 1
+ ? users[0].user_id
+ : ''
const selectedUser = users.find((user) => user.user_id === userId)
+ // The server can't read this user's key; the caller's own (non-root) key
+ // is used as is, so issuing for yourself never needs one.
+ const pasteForUser =
+ mode === 'user' &&
+ selectedUser?.api_key_available === false &&
+ (userId !== selfId || access?.role === 'root')
const owner: KeyOwner =
- mode === 'user'
- ? { user_id: userId }
- : { openviking_key: draft.openviking_key.trim() }
+ mode === 'self'
+ ? {}
+ : mode === 'user' && !pasteForUser
+ ? { user_id: userId }
+ : {
+ openviking_key: draft.openviking_key.trim(),
+ ...(userId ? { user_id: userId } : {}),
+ }
const request: KeyRequest = {
...owner,
name: draft.name.trim(),
@@ -259,17 +277,19 @@ export function KeysIssueDialog({
if (issue.isError) issue.reset()
}
- // The switch button goes away with its field; move focus to the new one.
+ // A field that appears (a mode switch, a user whose key must be pasted)
+ // takes focus; the switch button goes away with the previous field.
+ const focusField = mode === 'key' || pasteForUser ? 'key' : mode
+ const focusedField = React.useRef(focusField)
React.useEffect(() => {
- if (!focusOwner.current) return
- focusOwner.current = false
- const field = mode === 'user' ? userTriggerRef : keyInputRef
+ if (focusedField.current === focusField) return
+ focusedField.current = focusField
+ const field = focusField === 'user' ? userTriggerRef : keyInputRef
field.current?.focus()
- }, [mode])
+ }, [focusField])
- function switchMode(next: OwnerMode) {
+ function switchMode(next: 'user' | 'key') {
setChosenMode(next)
- focusOwner.current = true
if (issue.isError) issue.reset()
}
@@ -330,7 +350,18 @@ export function KeysIssueDialog({
/>
</SettingField>
- {mode === 'user' ? (
+ {mode === 'self' ? (
+ <SettingField label={t('keys.form.user.label')}>
+ <p className="text-sm text-muted-foreground">
+ {t(
+ devMode
+ ? 'keys.form.user.developmentIdentity'
+ : 'keys.form.user.self',
+ { user: selfId },
+ )}
+ </p>
+ </SettingField>
+ ) : mode === 'user' ? (
<SettingField
label={t('keys.form.user.label')}
htmlFor={id('user')}
@@ -345,7 +376,7 @@ export function KeysIssueDialog({
</ModeSwitch>
</>
}
- error={keyError}
+ error={pasteForUser ? undefined : keyError}
>
<Select
value={userId || null}
@@ -358,7 +389,7 @@ export function KeysIssueDialog({
ref={userTriggerRef}
id={id('user')}
className="w-full"
- aria-invalid={Boolean(keyError)}
+ aria-invalid={!pasteForUser && Boolean(keyError)}
>
<SelectValue>
{selectedUser ? (
@@ -374,20 +405,22 @@ export function KeysIssueDialog({
</SelectTrigger>
<SelectContent className="max-h-[min(18rem,var(--available-height))]">
{users.map((user) => (
- <SelectItem
- key={user.user_id}
- value={user.user_id}
- disabled={!user.api_key_available}
- >
+ <SelectItem key={user.user_id} value={user.user_id}>
<KeyUserLabel user={user} />
</SelectItem>
))}
</SelectContent>
</Select>
</SettingField>
- ) : (
+ ) : null}
+ {mode === 'key' || pasteForUser ? (
<SettingField
- label={t('keys.form.openvikingKey.label')}
+ label={t(
+ userId
+ ? 'keys.form.openvikingKey.forUser'
+ : 'keys.form.openvikingKey.label',
+ { user: userId },
+ )}
htmlFor={id('openviking-key')}
description={
fallback ? (
@@ -400,12 +433,14 @@ export function KeysIssueDialog({
) : (
<>
{t('keys.form.openvikingKey.description')}{' '}
- <ModeSwitch
- disabled={pending}
- onClick={() => switchMode('user')}
- >
- {t('keys.form.user.choose')}
- </ModeSwitch>
+ {canPickUser && mode === 'key' ? (
+ <ModeSwitch
+ disabled={pending}
+ onClick={() => switchMode('user')}
+ >
+ {t('keys.form.user.choose')}
+ </ModeSwitch>
+ ) : null}
</>
)
}
@@ -426,7 +461,7 @@ export function KeysIssueDialog({
}
/>
</SettingField>
- )}
+ ) : null}
<SettingField
label={t('keys.form.profile.label')}
@@ -436,14 +471,27 @@ export function KeysIssueDialog({
t('keys.form.profile.description')
) : (
<>
- {t('keys.form.profile.empty')}{' '}
- <Link
- to="/gateway/profiles/$profileId"
- params={{ profileId: NEW_ID }}
- className="font-medium text-foreground underline underline-offset-4"
- >
- {t('keys.form.profile.create')}
- </Link>
+ {t(
+ readOnly
+ ? 'keys.prerequisites.managed'
+ : 'keys.form.profile.empty',
+ )}{' '}
+ {readOnly ? (
+ <ModeSwitch
+ disabled={pending}
+ onClick={requestManagementUnlock}
+ >
+ {t('keys.prerequisites.unlock')}
+ </ModeSwitch>
+ ) : (
+ <Link
+ to="/gateway/profiles/$profileId"
+ params={{ profileId: NEW_ID }}
+ className="font-medium text-foreground underline underline-offset-4"
+ >
+ {t('keys.form.profile.create')}
+ </Link>
+ )}
</>
)
}
@@ -509,14 +557,27 @@ export function KeysIssueDialog({
t('keys.form.upstreams.description')
) : (
<>
- {t('keys.form.upstreams.empty')}{' '}
- <Link
- to="/gateway/upstreams/$upstreamId"
- params={{ upstreamId: NEW_ID }}
- className="font-medium text-foreground underline underline-offset-4"
- >
- {t('keys.form.upstreams.create')}
- </Link>
+ {t(
+ readOnly
+ ? 'keys.prerequisites.managed'
+ : 'keys.form.upstreams.empty',
+ )}{' '}
+ {readOnly ? (
+ <ModeSwitch
+ disabled={pending}
+ onClick={requestManagementUnlock}
+ >
+ {t('keys.prerequisites.unlock')}
+ </ModeSwitch>
+ ) : (
+ <Link
+ to="/gateway/upstreams/$upstreamId"
+ params={{ upstreamId: NEW_ID }}
+ className="font-medium text-foreground underline underline-offset-4"
+ >
+ {t('keys.form.upstreams.create')}
+ </Link>
+ )}
</>
)}
</FieldDescription>
@@ -610,11 +671,12 @@ function KeyUserLabel({ user }: { user: KeyUser }) {
<span className="text-xs text-muted-foreground">
{t(`keys.form.user.roles.${user.role}`)}
</span>
- {user.api_key_available ? null : (
+ {/* Older OpenViking servers omit the field; only `false` is known. */}
+ {user.api_key_available === false ? (
<span className="text-xs text-muted-foreground">
{t('keys.form.user.unavailable')}
</span>
- )}
+ ) : null}
</span>
)
}
@@ -652,6 +714,11 @@ function UpstreamOption({
<span className="flex min-w-0 flex-wrap items-center gap-2">
<span className="truncate text-sm font-medium">{upstream.name}</span>
<ProtocolBadge protocol={upstream.protocol} />
+ {upstream.coding_plan && !upstream.allow_coding_plan ? (
+ <ToneBadge tone="neutral">
+ {t('keys.form.upstreams.blocked')}
+ </ToneBadge>
+ ) : null}
{upstream.enabled ? null : (
<ToneBadge tone="neutral">{t('keys.form.upstreams.off')}</ToneBadge>
)}
diff --git a/web-studio/src/routes/gateway/-components/keys-page.test.tsx b/web-studio/src/routes/gateway/-components/keys-page.test.tsx
index 84f54cf16..4c802bc78 100644
--- a/web-studio/src/routes/gateway/-components/keys-page.test.tsx
+++ b/web-studio/src/routes/gateway/-components/keys-page.test.tsx
@@ -20,6 +20,7 @@ import { KeysPage } from './keys-page'
const api = vi.hoisted(() => ({
getConnectionInfo: vi.fn(),
+ getAccess: vi.fn(),
listKeys: vi.fn(),
listProfiles: vi.fn(),
listUpstreams: vi.fn(),
@@ -146,6 +147,15 @@ function renderPage() {
beforeEach(() => {
vi.clearAllMocks()
+ api.getAccess.mockResolvedValue({
+ managed: false,
+ can_write_objects: true,
+ can_issue_for_others: true,
+ role: 'admin',
+ account_id: 'acme',
+ user_id: 'admin',
+ warnings: [],
+ })
api.getConnectionInfo.mockResolvedValue({
base_url: BASE_URL,
public_url_configured: true,
@@ -236,6 +246,79 @@ describe('KeysPage', () => {
expect((issue as HTMLButtonElement).disabled).toBe(true)
})
+ it('offers management unlock when shared prerequisites are missing', async () => {
+ api.getAccess.mockResolvedValue({
+ managed: true,
+ can_write_objects: false,
+ can_issue_for_others: false,
+ role: 'user',
+ user_id: 'alice',
+ })
+ api.listKeys.mockResolvedValue([])
+ api.listUpstreams.mockResolvedValue([])
+ const unlock = vi.fn()
+ window.addEventListener('gateway-management-unlock', unlock)
+ renderPage()
+ const button = await screen.findByRole('button', {
+ name: 'keys.prerequisites.unlock',
+ })
+ expect(screen.getByText('keys.prerequisites.managed')).toBeTruthy()
+ expect(
+ screen.queryByRole('link', { name: /keys.prerequisites.addUpstream/ }),
+ ).toBeNull()
+ fireEvent.click(button)
+ expect(unlock).toHaveBeenCalledTimes(1)
+ window.removeEventListener('gateway-management-unlock', unlock)
+ })
+
+ it('hides the user column and user-data deletion for ordinary users', async () => {
+ api.getAccess.mockResolvedValue({
+ managed: true,
+ can_write_objects: false,
+ can_issue_for_others: false,
+ role: 'user',
+ user_id: 'alice',
+ })
+ renderPage()
+ await screen.findByText('Alice laptop')
+ expect(
+ screen.queryByRole('columnheader', { name: 'keys.table.user' }),
+ ).toBeNull()
+ expect(
+ screen.queryByRole('button', { name: 'keys.actions.more' }),
+ ).toBeNull()
+ expect(
+ screen.getAllByRole('button', { name: 'keys.actions.revokeKey' }),
+ ).toHaveLength(2)
+ })
+
+ it.each(['admin', 'root'])(
+ 'offers user-data deletion for %s',
+ async (role) => {
+ api.getAccess.mockResolvedValue({
+ managed: true,
+ can_write_objects: false,
+ can_issue_for_others: true,
+ role,
+ user_id: 'admin',
+ })
+ renderPage()
+ const buttons = await screen.findAllByRole('button', {
+ name: 'keys.actions.more',
+ })
+ expect(
+ screen.getByRole('columnheader', { name: 'keys.table.user' }),
+ ).toBeTruthy()
+ fireEvent.click(buttons[0])
+ fireEvent.click(
+ await screen.findByRole('menuitem', {
+ name: 'keys.actions.deleteUserData',
+ }),
+ )
+ expect(screen.getByText('keys.deleteUser.title')).toBeTruthy()
+ },
+ )
+
it('issues a key and shows the secret once with ready-to-use snippets', async () => {
api.listUpstreams.mockResolvedValue([claude])
const issued: IssuedKey = {
diff --git a/web-studio/src/routes/gateway/-components/keys-page.tsx b/web-studio/src/routes/gateway/-components/keys-page.tsx
index 08415ea2e..d68f6273a 100644
--- a/web-studio/src/routes/gateway/-components/keys-page.tsx
+++ b/web-studio/src/routes/gateway/-components/keys-page.tsx
@@ -37,6 +37,7 @@ import { deleteUserData, revokeKey } from '../-lib/api'
import type { GatewayKey, IssuedKey, Profile, Upstream } from '../-lib/api'
import { formatDateTime, formatRelativeTime, shortenId } from '../-lib/format'
import { gatewayErrorMessage, protocolLabel } from '../-lib/localize'
+import { requestManagementUnlock } from '../-lib/management-key'
import { NEW_ID } from '../-lib/search'
import {
useConnectionInfo,
@@ -68,7 +69,7 @@ type Missing = 'upstream' | 'profile' | 'both'
/** Issue and revoke gateway keys. */
export function KeysPage() {
const { t } = useTranslation('gateway')
- const { connection, invalidate } = useGateway()
+ const { connection, invalidate, readOnly, canIssueForOthers } = useGateway()
const keysQuery = useKeys()
const profilesQuery = useProfiles()
const upstreamsQuery = useUpstreams()
@@ -118,6 +119,14 @@ export function KeysPage() {
? 'profile'
: null
const canIssue = listsReady && !missing
+ // Only someone who can't add upstreams or profiles waits for the gateway admin.
+ const missingReason = missing
+ ? t(
+ readOnly
+ ? 'keys.prerequisites.managed'
+ : `keys.prerequisites.${missing}`,
+ )
+ : undefined
const refreshing =
keysQuery.isFetching ||
profilesQuery.isFetching ||
@@ -138,11 +147,53 @@ export function KeysPage() {
const issueButton = (
<IssueButton
disabled={!canIssue}
- reason={missing ? t(`keys.prerequisites.${missing}`) : undefined}
+ reason={missingReason}
onClick={openIssue}
/>
)
+ const prerequisiteActions = (
+ <>
+ {!readOnly && (missing === 'upstream' || missing === 'both') ? (
+ <Button
+ variant="outline"
+ size="sm"
+ nativeButton={false}
+ render={
+ <Link
+ to="/gateway/upstreams/$upstreamId"
+ params={{ upstreamId: NEW_ID }}
+ />
+ }
+ >
+ <ServerIcon />
+ {t('keys.prerequisites.addUpstream')}
+ </Button>
+ ) : null}
+ {!readOnly && (missing === 'profile' || missing === 'both') ? (
+ <Button
+ variant="outline"
+ size="sm"
+ nativeButton={false}
+ render={
+ <Link
+ to="/gateway/profiles/$profileId"
+ params={{ profileId: NEW_ID }}
+ />
+ }
+ >
+ <SlidersHorizontalIcon />
+ {t('keys.prerequisites.createProfile')}
+ </Button>
+ ) : null}
+ {missing && readOnly ? (
+ <Button variant="outline" size="sm" onClick={requestManagementUnlock}>
+ {t('keys.prerequisites.unlock')}
+ </Button>
+ ) : null}
+ </>
+ )
+
return (
<div className="flex w-full min-w-0 flex-col gap-5">
<SectionHeader
@@ -185,47 +236,16 @@ export function KeysPage() {
description={
<>
<span className="block">{t('keys.empty.description')}</span>
- {missing ? (
+ {missingReason ? (
<span className="mt-2 block font-medium text-foreground">
- {t(`keys.prerequisites.${missing}`)}
+ {missingReason}
</span>
) : null}
</>
}
action={
<>
- {missing === 'upstream' || missing === 'both' ? (
- <Button
- variant="outline"
- size="sm"
- nativeButton={false}
- render={
- <Link
- to="/gateway/upstreams/$upstreamId"
- params={{ upstreamId: NEW_ID }}
- />
- }
- >
- <ServerIcon />
- {t('keys.prerequisites.addUpstream')}
- </Button>
- ) : null}
- {missing === 'profile' || missing === 'both' ? (
- <Button
- variant="outline"
- size="sm"
- nativeButton={false}
- render={
- <Link
- to="/gateway/profiles/$profileId"
- params={{ profileId: NEW_ID }}
- />
- }
- >
- <SlidersHorizontalIcon />
- {t('keys.prerequisites.createProfile')}
- </Button>
- ) : null}
+ {prerequisiteActions}
{issueButton}
</>
}
@@ -238,9 +258,11 @@ export function KeysPage() {
<TableHead className={DESKTOP_ONLY}>
{t('keys.table.key')}
</TableHead>
- <TableHead className={DESKTOP_ONLY}>
- {t('keys.table.user')}
- </TableHead>
+ {canIssueForOthers ? (
+ <TableHead className={DESKTOP_ONLY}>
+ {t('keys.table.user')}
+ </TableHead>
+ ) : null}
<TableHead className={DESKTOP_ONLY}>
{t('keys.table.profile')}
</TableHead>
@@ -265,8 +287,13 @@ export function KeysPage() {
gatewayKey={key}
profiles={profilesQuery.isSuccess ? profiles : undefined}
upstreams={upstreamsQuery.isSuccess ? upstreams : undefined}
+ showUser={canIssueForOthers}
onRevoke={() => setRevokeTarget(key)}
- onDeleteUser={() => setUserTarget(key.user_id)}
+ onDeleteUser={
+ canIssueForOthers
+ ? () => setUserTarget(key.user_id)
+ : undefined
+ }
/>
))}
</TableBody>
@@ -392,6 +419,7 @@ function KeyRow({
gatewayKey: key,
profiles,
upstreams,
+ showUser,
onRevoke,
onDeleteUser,
}: {
@@ -399,8 +427,10 @@ function KeyRow({
/** Undefined while the list isn't loaded, so nothing shows as missing. */
profiles?: Profile[]
upstreams?: Upstream[]
+ /** Admins see whose identity each key acts as. */
+ showUser: boolean
onRevoke: () => void
- onDeleteUser: () => void
+ onDeleteUser?: () => void
}) {
const { t, i18n } = useTranslation('gateway')
const locale = i18n.resolvedLanguage
@@ -416,7 +446,7 @@ function KeyRow({
className="block max-w-56 truncate font-mono text-xs text-muted-foreground md:hidden"
title={key.user_id}
>
- {`${key.prefix}… · ${key.user_id}`}
+ {showUser ? `${key.prefix}… · ${key.user_id}` : `${key.prefix}…`}
</span>
</TableCell>
<TableCell
@@ -424,14 +454,16 @@ function KeyRow({
>
{`${key.prefix}…`}
</TableCell>
- <TableCell className={DESKTOP_ONLY}>
- <span
- className="block max-w-40 truncate font-mono text-xs"
- title={key.user_id}
- >
- {key.user_id}
- </span>
- </TableCell>
+ {showUser ? (
+ <TableCell className={DESKTOP_ONLY}>
+ <span
+ className="block max-w-40 truncate font-mono text-xs"
+ title={key.user_id}
+ >
+ {key.user_id}
+ </span>
+ </TableCell>
+ ) : null}
<TableCell className={DESKTOP_ONLY}>
{profile ? (
<Link
@@ -533,27 +565,29 @@ function KeyRow({
<Trash2Icon />
{t('actions.revoke')}
</Button>
- <DropdownMenu>
- <DropdownMenuTrigger
- render={
- <Button
- type="button"
- variant="ghost"
- size="icon-sm"
- className="text-muted-foreground"
- aria-label={t('keys.actions.more', { name: key.name })}
- />
- }
- >
- <EllipsisIcon />
- </DropdownMenuTrigger>
- <DropdownMenuContent align="end" className="w-auto min-w-48">
- <DropdownMenuItem variant="destructive" onClick={onDeleteUser}>
- <UserXIcon />
- {t('keys.actions.deleteUserData')}
- </DropdownMenuItem>
- </DropdownMenuContent>
- </DropdownMenu>
+ {onDeleteUser ? (
+ <DropdownMenu>
+ <DropdownMenuTrigger
+ render={
+ <Button
+ type="button"
+ variant="ghost"
+ size="icon-sm"
+ className="text-muted-foreground"
+ aria-label={t('keys.actions.more', { name: key.name })}
+ />
+ }
+ >
+ <EllipsisIcon />
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end" className="w-auto min-w-48">
+ <DropdownMenuItem variant="destructive" onClick={onDeleteUser}>
+ <UserXIcon />
+ {t('keys.actions.deleteUserData')}
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ ) : null}
</div>
</TableCell>
</TableRow>
diff --git a/web-studio/src/routes/gateway/-components/keys-secret-dialog.tsx b/web-studio/src/routes/gateway/-components/keys-secret-dialog.tsx
index 1378e5165..37be39fa8 100644
--- a/web-studio/src/routes/gateway/-components/keys-secret-dialog.tsx
+++ b/web-studio/src/routes/gateway/-components/keys-secret-dialog.tsx
@@ -121,23 +121,15 @@ export function KeysSecretDialog({
size="icon-sm"
/>
</div>
- <dl className="flex flex-wrap gap-x-6 gap-y-1 text-sm">
- <div className="flex min-w-0 items-baseline gap-2">
- <dt className="text-muted-foreground">
- {t('keys.secret.user')}
- </dt>
- <dd className="truncate font-mono text-xs">
- {issued.user_id}
- </dd>
- </div>
- <div className="flex min-w-0 items-baseline gap-2">
- <dt className="text-muted-foreground">
- {t('keys.secret.profile')}
- </dt>
- <dd className="truncate">
- {profileName ?? issued.policy_id}
- </dd>
- </div>
+ <Notice tone="info">
+ <p>{t('keys.secret.identity', { user: issued.user_id })}</p>
+ <p>{t('keys.secret.dependency', { user: issued.user_id })}</p>
+ </Notice>
+ <dl className="flex min-w-0 items-baseline gap-2 text-sm">
+ <dt className="text-muted-foreground">
+ {t('keys.secret.profile')}
+ </dt>
+ <dd className="truncate">{profileName ?? issued.policy_id}</dd>
</dl>
</div>
diff --git a/web-studio/src/routes/gateway/-components/management-key-dialog.test.tsx b/web-studio/src/routes/gateway/-components/management-key-dialog.test.tsx
new file mode 100644
index 000000000..140395300
--- /dev/null
+++ b/web-studio/src/routes/gateway/-components/management-key-dialog.test.tsx
@@ -0,0 +1,115 @@
+// @vitest-environment jsdom
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+ cleanup,
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+} from '@testing-library/react'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import type * as Api from '../-lib/api'
+import { GatewayError } from '../-lib/api'
+import {
+ getManagementKey,
+ lockManagementKey,
+ requestManagementUnlock,
+ setManagementKey,
+} from '../-lib/management-key'
+import { ManagementKeyDialog } from './management-key-dialog'
+
+const state = vi.hoisted(() => ({
+ getAccess: vi.fn(),
+ success: vi.fn(),
+ error: vi.fn(),
+}))
+vi.mock('../-lib/api', async (original) => ({
+ ...(await original<typeof Api>()),
+ getAccess: state.getAccess,
+}))
+vi.mock('../-lib/use-gateway', () => ({
+ useGateway: () => ({
+ connection: {
+ baseUrl: 'https://gateway.example.com',
+ accountId: 'acme',
+ userId: 'alice',
+ apiKey: 'ov-key',
+ },
+ }),
+}))
+vi.mock('react-i18next', () => ({
+ useTranslation: () => ({ t: (key: string) => key }),
+}))
+vi.mock('sonner', () => ({
+ toast: { success: state.success, error: state.error },
+}))
+
+beforeEach(() => {
+ sessionStorage.clear()
+ vi.clearAllMocks()
+})
+afterEach(cleanup)
+function open() {
+ const client = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ })
+ render(
+ <QueryClientProvider client={client}>
+ <ManagementKeyDialog />
+ </QueryClientProvider>,
+ )
+ requestManagementUnlock()
+}
+it('rejects client keys in the management field without sending them', async () => {
+ open()
+ const input = await screen.findByLabelText('management.label')
+ fireEvent.change(input, { target: { value: 'ovgw_client_secret' } })
+ expect(screen.getByText('management.wrongKey')).toBeTruthy()
+ expect(
+ screen.getByRole<HTMLButtonElement>('button', {
+ name: 'management.unlock',
+ }).disabled,
+ ).toBe(true)
+ expect(state.getAccess).not.toHaveBeenCalled()
+})
+it('keeps incorrect candidates out of session storage, then unlocks after server verification', async () => {
+ state.getAccess
+ .mockRejectedValueOnce(
+ new GatewayError('bad', 401, undefined, 'management_key_invalid'),
+ )
+ .mockResolvedValueOnce({ can_write_objects: true })
+ open()
+ const input = await screen.findByLabelText('management.label')
+ fireEvent.change(input, { target: { value: 'wrong-key' } })
+ fireEvent.click(screen.getByRole('button', { name: 'management.unlock' }))
+ expect(await screen.findByText('management.invalid')).toBeTruthy()
+ expect(getManagementKey('https://gateway.example.com')).toBe('')
+ fireEvent.change(input, { target: { value: 'ovgm-correct' } })
+ fireEvent.click(screen.getByRole('button', { name: 'management.unlock' }))
+ await waitFor(() =>
+ expect(getManagementKey('https://gateway.example.com')).toBe(
+ 'ovgm-correct',
+ ),
+ )
+ expect(state.getAccess).toHaveBeenLastCalledWith(
+ expect.objectContaining({ managementKey: 'ovgm-correct' }),
+ )
+ expect(state.success).toHaveBeenCalledWith('management.unlocked')
+})
+it('reports automatic locking only when a stored management key expires', () => {
+ lockManagementKey('https://gateway.example.com', true)
+ expect(state.error).not.toHaveBeenCalled()
+ setManagementKey('https://gateway.example.com', 'ovgm-old')
+ lockManagementKey('https://gateway.example.com', true)
+ expect(getManagementKey('https://gateway.example.com')).toBe('')
+ expect(state.error).toHaveBeenCalledTimes(1)
+})
+it('tolerates browsers that reject session storage', () => {
+ const getter = vi
+ .spyOn(Storage.prototype, 'getItem')
+ .mockImplementation(() => {
+ throw new Error('storage disabled')
+ })
+ expect(getManagementKey('https://gateway.example.com')).toBe('')
+ getter.mockRestore()
+})
diff --git a/web-studio/src/routes/gateway/-components/management-key-dialog.tsx b/web-studio/src/routes/gateway/-components/management-key-dialog.tsx
new file mode 100644
index 000000000..7c1970774
--- /dev/null
+++ b/web-studio/src/routes/gateway/-components/management-key-dialog.tsx
@@ -0,0 +1,133 @@
+import * as React from 'react'
+import { useMutation } from '@tanstack/react-query'
+import { useTranslation } from 'react-i18next'
+import { toast } from 'sonner'
+import { Button } from '#/components/ui/button'
+import { Input } from '#/components/ui/input'
+import {
+ Dialog,
+ DialogContent,
+ DialogHeader,
+ DialogTitle,
+ DialogDescription,
+ DialogFooter,
+} from '#/components/ui/dialog'
+import { getAccess, toGatewayError } from '../-lib/api'
+import {
+ MANAGEMENT_UNLOCK_EVENT,
+ setManagementKey,
+} from '../-lib/management-key'
+import { useGateway } from '../-lib/use-gateway'
+import { gatewayErrorMessage } from '../-lib/localize'
+import { SettingField } from './setting-field'
+
+const MANAGEMENT_CONFIGS = [
+ 'ov.conf: gateway.management_key',
+ 'gateway.conf: management_key',
+]
+
+export function ManagementKeyDialog() {
+ const { t } = useTranslation('gateway')
+ const { connection } = useGateway()
+ const [open, setOpen] = React.useState(false)
+ const [key, setKey] = React.useState('')
+ const [error, setError] = React.useState('')
+ React.useEffect(() => {
+ const show = () => {
+ setKey('')
+ setError('')
+ setOpen(true)
+ }
+ window.addEventListener(MANAGEMENT_UNLOCK_EVENT, show)
+ return () => window.removeEventListener(MANAGEMENT_UNLOCK_EVENT, show)
+ }, [])
+ const unlock = useMutation({
+ mutationFn: () => getAccess({ ...connection, managementKey: key.trim() }),
+ // Storing the key changes the query scope, so gateway data reloads with it.
+ onSuccess: (access) => {
+ if (!access.can_write_objects) {
+ setError(t('management.invalid'))
+ return
+ }
+ setManagementKey(connection.baseUrl, key.trim())
+ setOpen(false)
+ setKey('')
+ toast.success(t('management.unlocked'))
+ },
+ onError: (failure) =>
+ setError(
+ toGatewayError(failure).reason === 'management_key_invalid'
+ ? t('management.invalid')
+ : gatewayErrorMessage(t, failure),
+ ),
+ })
+ const wrongKey = key.trim().startsWith('ovgw_')
+ return (
+ <Dialog open={open} onOpenChange={setOpen}>
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>{t('management.title')}</DialogTitle>
+ <DialogDescription>{t('management.description')}</DialogDescription>
+ </DialogHeader>
+ <form
+ className="grid gap-4"
+ onSubmit={(event) => {
+ event.preventDefault()
+ if (key.trim() && !wrongKey) unlock.mutate()
+ }}
+ >
+ <details className="text-sm">
+ <summary className="cursor-pointer">
+ {t('management.where')}
+ </summary>
+ <ul className="mt-2 list-disc space-y-1 pl-5 text-muted-foreground">
+ {MANAGEMENT_CONFIGS.map((config) => (
+ <li key={config}>
+ <code>{config}</code>
+ </li>
+ ))}
+ <li>
+ {t('management.environment')}{' '}
+ <code>OPENVIKING_GATEWAY_MANAGEMENT_KEY</code>
+ </li>
+ <li>{t('management.prefix')}</li>
+ </ul>
+ </details>
+ <SettingField
+ label={t('management.label')}
+ htmlFor="gateway-management-key"
+ error={wrongKey ? t('management.wrongKey') : error}
+ description={t('management.session')}
+ >
+ <Input
+ id="gateway-management-key"
+ autoFocus
+ type="password"
+ autoComplete="off"
+ value={key}
+ onChange={(event) => {
+ setKey(event.target.value)
+ setError('')
+ }}
+ />
+ </SettingField>
+ <DialogFooter>
+ <Button
+ type="button"
+ variant="outline"
+ onClick={() => setOpen(false)}
+ >
+ {t('actions.cancel')}
+ </Button>
+ <Button
+ type="submit"
+ disabled={!key.trim() || wrongKey || unlock.isPending}
+ >
+ {t('management.unlock')}
+ </Button>
+ </DialogFooter>
+ </form>
+ </DialogContent>
+ </Dialog>
+ )
+}
diff --git a/web-studio/src/routes/gateway/-components/overview-page.test.tsx b/web-studio/src/routes/gateway/-components/overview-page.test.tsx
index a45902328..045e45d44 100644
--- a/web-studio/src/routes/gateway/-components/overview-page.test.tsx
+++ b/web-studio/src/routes/gateway/-components/overview-page.test.tsx
@@ -37,6 +37,7 @@ import { PROFILE_DEFAULTS } from '../-lib/profile-schema'
import { OverviewPage } from './overview-page'
const api = vi.hoisted(() => ({
+ getAccess: vi.fn(),
getOverview: vi.fn(),
listLogs: vi.fn(),
listUpstreams: vi.fn(),
@@ -204,6 +205,16 @@ afterAll(async () => {
beforeEach(() => {
vi.spyOn(window, 'scrollTo').mockImplementation(() => {})
for (const mock of Object.values(api)) mock.mockReset()
+ api.getAccess.mockResolvedValue({
+ managed: false,
+ can_write_objects: true,
+ can_import_vlm: true,
+ can_issue_for_others: true,
+ role: 'admin',
+ account_id: 'acme',
+ user_id: 'admin',
+ warnings: [],
+ })
api.listLogs.mockResolvedValue([])
api.listUpstreams.mockResolvedValue([])
api.listProfiles.mockResolvedValue([])
@@ -272,7 +283,7 @@ describe('OverviewPage', () => {
)
await waitFor(() =>
expect(toast.error).toHaveBeenCalledWith(
- 'The gateway rejected these settings. Check the values and limits.',
+ 'The gateway rejected these settings. Check the values and try again.',
),
)
expect(
diff --git a/web-studio/src/routes/gateway/-components/overview-setup.tsx b/web-studio/src/routes/gateway/-components/overview-setup.tsx
index 3bac03024..30093c7e2 100644
--- a/web-studio/src/routes/gateway/-components/overview-setup.tsx
+++ b/web-studio/src/routes/gateway/-components/overview-setup.tsx
@@ -1,6 +1,11 @@
import type * as React from 'react'
import { Link } from '@tanstack/react-router'
-import { ArrowRightIcon, CheckIcon, ListChecksIcon } from 'lucide-react'
+import {
+ ArrowRightIcon,
+ CheckIcon,
+ ListChecksIcon,
+ TriangleAlertIcon,
+} from 'lucide-react'
import { useTranslation } from 'react-i18next'
import { Button } from '#/components/ui/button'
@@ -15,7 +20,13 @@ import {
import { cn } from '#/lib/utils'
import { NEW_ID } from '../-lib/search'
-import { useKeys, useProfiles, useUpstreams } from '../-lib/use-gateway'
+import {
+ useGateway,
+ useKeys,
+ useProfiles,
+ useUpstreams,
+} from '../-lib/use-gateway'
+import { ManagementUnlockButton } from './access-notices'
import { RecommendedProfileButton } from './recommended-profile-button'
type StepState = 'done' | 'current' | 'todo'
@@ -92,6 +103,7 @@ function SetupStep({
*/
export function OverviewSetup() {
const { t } = useTranslation('gateway')
+ const { readOnly } = useGateway()
const upstreams = useUpstreams()
const profiles = useProfiles()
const keys = useKeys()
@@ -103,10 +115,22 @@ export function OverviewSetup() {
const done = [...counts.map((count) => Boolean(count)), false]
const current = loaded ? done.indexOf(false) : -1
const stateOf = (index: number): StepState =>
- done[index] ? 'done' : index === current ? 'current' : 'todo'
+ done[index]
+ ? 'done'
+ : readOnly && index < 2
+ ? 'todo'
+ : index === current
+ ? 'current'
+ : 'todo'
const variantOf = (index: number) =>
index === current ? 'default' : 'outline'
const [upstreamCount = 0, profileCount = 0, keyCount = 0] = counts
+ // Upstreams imported from the server's VLM settings carry a `vlm-` id.
+ const importedCount =
+ upstreams.data?.filter((item) => item.id.startsWith('vlm-')).length ?? 0
+ const blockedUpstreams = (upstreams.data ?? []).filter(
+ (item) => item.coding_plan && !item.allow_coding_plan,
+ )
const viewButton = (
to: '/gateway/upstreams' | '/gateway/profiles' | '/gateway/keys',
@@ -150,13 +174,52 @@ export function OverviewSetup() {
state={stateOf(0)}
title={t('overview.setup.upstream.title')}
description={
- done[0]
- ? t('overview.setup.upstream.done', { count: upstreamCount })
- : t('overview.setup.upstream.description')
+ <>
+ <p>
+ {done[0]
+ ? t(
+ readOnly
+ ? 'overview.setup.providedUpstreams'
+ : !importedCount
+ ? 'overview.setup.upstream.done'
+ : importedCount < upstreamCount
+ ? 'overview.setup.someImportedUpstreams'
+ : 'overview.setup.importedUpstreams',
+ { count: upstreamCount, imported: importedCount },
+ )
+ : t(
+ readOnly
+ ? 'overview.setup.waitUpstreams'
+ : 'overview.setup.upstream.description',
+ )}
+ </p>
+ {readOnly
+ ? null
+ : blockedUpstreams.map((item) => (
+ <p
+ key={item.id}
+ className="mt-1 flex items-start gap-1.5 text-xs text-amber-800 dark:text-amber-200"
+ >
+ <TriangleAlertIcon className="mt-0.5 size-3.5 shrink-0" />
+ <span>
+ {t('overview.setup.codingPlan', { name: item.name })}{' '}
+ <Link
+ to="/gateway/upstreams/$upstreamId"
+ params={{ upstreamId: item.id }}
+ className="font-medium underline underline-offset-4"
+ >
+ {t('overview.setup.confirm')}
+ </Link>
+ </span>
+ </p>
+ ))}
+ </>
}
>
{done[0] ? (
viewButton('/gateway/upstreams')
+ ) : readOnly ? (
+ <ManagementUnlockButton />
) : (
<Button
size="sm"
@@ -179,12 +242,23 @@ export function OverviewSetup() {
title={t('overview.setup.profile.title')}
description={
done[1]
- ? t('overview.setup.profile.done', { count: profileCount })
- : t('overview.setup.profile.description')
+ ? t(
+ readOnly
+ ? 'overview.setup.providedProfiles'
+ : 'overview.setup.profile.done',
+ { count: profileCount },
+ )
+ : t(
+ readOnly
+ ? 'overview.setup.waitProfiles'
+ : 'overview.setup.profile.description',
+ )
}
>
{done[1] ? (
viewButton('/gateway/profiles')
+ ) : readOnly ? (
+ <ManagementUnlockButton />
) : (
<>
<RecommendedProfileButton
@@ -219,7 +293,11 @@ export function OverviewSetup() {
<p>{t('overview.setup.key.description')}</p>
{loaded && !(done[0] && done[1]) ? (
<p className="mt-1 text-xs">
- {t('overview.setup.key.blocked')}
+ {t(
+ readOnly
+ ? 'overview.setup.key.waiting'
+ : 'overview.setup.key.blocked',
+ )}
</p>
) : null}
</>
diff --git a/web-studio/src/routes/gateway/-components/overview-status.tsx b/web-studio/src/routes/gateway/-components/overview-status.tsx
index 918b0dff0..1300f894e 100644
--- a/web-studio/src/routes/gateway/-components/overview-status.tsx
+++ b/web-studio/src/routes/gateway/-components/overview-status.tsx
@@ -77,7 +77,7 @@ export function OpenVikingCard({
captureIssues: Overview['capture_issues']
}) {
const { t } = useTranslation('gateway')
- const { status, version, auth_mode: authMode, reason } = health
+ const { status, version, reason } = health
return (
<Card className="gap-4">
<CardHeader>
@@ -98,18 +98,6 @@ export function OpenVikingCard({
<dd className="truncate font-mono text-xs leading-5">
{version || <EmptyValue />}
</dd>
- <dt className="text-muted-foreground">
- {t('overview.openviking.authMode')}
- </dt>
- <dd>
- {authMode ? (
- t(`overview.openviking.authModes.${authMode}`, {
- defaultValue: authMode,
- })
- ) : (
- <EmptyValue />
- )}
- </dd>
</dl>
) : null}
{status === 'degraded' ? (
diff --git a/web-studio/src/routes/gateway/-components/profiles-editor.tsx b/web-studio/src/routes/gateway/-components/profiles-editor.tsx
index 345025634..297fd0491 100644
--- a/web-studio/src/routes/gateway/-components/profiles-editor.tsx
+++ b/web-studio/src/routes/gateway/-components/profiles-editor.tsx
@@ -1,3 +1,4 @@
+import { ReadOnlyProvider } from './read-only'
import * as React from 'react'
import { useMutation } from '@tanstack/react-query'
import { Link, getRouteApi, useNavigate } from '@tanstack/react-router'
@@ -25,7 +26,7 @@ import { cn } from '#/lib/utils'
import { keysUsing, newObjectId, saveProfile } from '../-lib/api'
import type { Profile, ProfileSettings } from '../-lib/api'
-import { gatewayErrorMessage } from '../-lib/localize'
+import { toastGatewayError } from '../-lib/error-toast'
import {
PROFILE_DEFAULTS,
duplicateProfile,
@@ -136,7 +137,7 @@ function ProfileEditorForm({
}: ProfileEditorFormProps) {
const { t } = useTranslation('gateway')
const navigate = useNavigate()
- const { connection, invalidate } = useGateway()
+ const { connection, invalidate, readOnly } = useGateway()
const isNew = profileId === NEW_ID
const [targetId] = React.useState(() => (isNew ? newObjectId() : profileId))
const baseline = React.useMemo(
@@ -173,9 +174,9 @@ function ProfileEditorForm({
await invalidate('profiles')
void navigate({ to: '/gateway/profiles' })
},
- onError: (error) => toast.error(gatewayErrorMessage(t, error)),
+ onError: (error) => toastGatewayError(t, error),
})
- const canSave = valid && dirty && !save.isPending
+ const canSave = !readOnly && valid && dirty && !save.isPending
function submit(event: React.FormEvent) {
event.preventDefault()
@@ -218,94 +219,107 @@ function ProfileEditorForm({
title={isNew || !source ? t('profiles.editor.newTitle') : source.name}
description={description}
actions={
- <DropdownMenu>
- <DropdownMenuTrigger
- render={
- <Button
- type="button"
- variant="outline"
- size="icon-sm"
- aria-label={t('actions.more')}
- title={t('actions.more')}
- />
- }
- >
- <EllipsisIcon />
- </DropdownMenuTrigger>
- <DropdownMenuContent align="end" className="w-auto min-w-52">
- <DropdownMenuItem onClick={resetToRecommended}>
- <RotateCcwIcon />
- {t('profiles.actions.reset')}
- </DropdownMenuItem>
- {isNew ? null : (
- <DropdownMenuItem
- onClick={() =>
- void navigate({
- to: '/gateway/profiles/$profileId',
- params: { profileId: NEW_ID },
- search: { from: profileId },
- })
- }
- >
- <CopyPlusIcon />
- {t('actions.duplicate')}
+ readOnly ? undefined : (
+ <DropdownMenu>
+ <DropdownMenuTrigger
+ render={
+ <Button
+ type="button"
+ variant="outline"
+ size="icon-sm"
+ aria-label={t('actions.more')}
+ title={t('actions.more')}
+ />
+ }
+ >
+ <EllipsisIcon />
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end" className="w-auto min-w-52">
+ <DropdownMenuItem onClick={resetToRecommended}>
+ <RotateCcwIcon />
+ {t('profiles.actions.reset')}
</DropdownMenuItem>
- )}
- </DropdownMenuContent>
- </DropdownMenu>
+ {isNew ? null : (
+ <DropdownMenuItem
+ onClick={() =>
+ void navigate({
+ to: '/gateway/profiles/$profileId',
+ params: { profileId: NEW_ID },
+ search: { from: profileId },
+ })
+ }
+ >
+ <CopyPlusIcon />
+ {t('actions.duplicate')}
+ </DropdownMenuItem>
+ )}
+ </DropdownMenuContent>
+ </DropdownMenu>
+ )
}
/>
<form noValidate className="flex flex-col gap-5" onSubmit={submit}>
- <Notice tone="info">{t('profiles.editor.banner')}</Notice>
+ {!readOnly ? (
+ <Notice tone="info">{t('profiles.editor.banner')}</Notice>
+ ) : null}
{sourceMissing ? (
<Notice tone="warning">{t('profiles.editor.sourceMissing')}</Notice>
) : null}
- <div className="grid gap-6 lg:grid-cols-[12rem_minmax(0,1fr)]">
- <SectionNav settings={draft} errors={errors} />
- <div className="grid min-w-0 gap-4">
- <Card className="gap-0 py-0">
- <CardContent className="py-5">
- <SettingField
- label={t('profiles.name.label')}
- htmlFor="profile-name"
- description={t('profiles.name.description')}
- error={
- showNameError && errors.name
- ? t(errors.name.key, errors.name.values)
- : undefined
- }
- className="max-w-md"
- >
- <Input
- id="profile-name"
- value={draft.name}
- autoComplete="off"
- placeholder={t('profiles.name.placeholder')}
- aria-invalid={showNameError}
- onBlur={() => setNameTouched(true)}
- onChange={(event) => update({ name: event.target.value })}
- />
- </SettingField>
- </CardContent>
- </Card>
- <ProfileSettingsForm
- value={draft}
- onChange={update}
- errors={errors}
- />
- </div>
- </div>
-
- <EditorFooter
- status={status}
- invalid={!valid && !needsNameOnly}
- cancelTo="/gateway/profiles"
- saveLabel={t(isNew ? 'profiles.editor.create' : 'actions.save')}
- saving={save.isPending}
- disabled={!canSave}
- />
+ <ReadOnlyProvider value={readOnly}>
+ <fieldset disabled={readOnly} className="contents">
+ <div className="grid gap-6 lg:grid-cols-[12rem_minmax(0,1fr)]">
+ <SectionNav settings={draft} errors={errors} />
+ <div className="grid min-w-0 gap-4">
+ <Card className="gap-0 py-0">
+ <CardContent className="py-5">
+ <SettingField
+ label={t('profiles.name.label')}
+ htmlFor="profile-name"
+ description={t('profiles.name.description')}
+ error={
+ showNameError && errors.name
+ ? t(errors.name.key, errors.name.values)
+ : undefined
+ }
+ className="max-w-md"
+ >
+ <Input
+ id="profile-name"
+ value={draft.name}
+ autoComplete="off"
+ placeholder={t('profiles.name.placeholder')}
+ aria-invalid={showNameError}
+ onBlur={() => setNameTouched(true)}
+ onChange={(event) =>
+ update({ name: event.target.value })
+ }
+ />
+ </SettingField>
+ </CardContent>
+ </Card>
+ <ProfileSettingsForm
+ value={draft}
+ onChange={update}
+ errors={errors}
+ />
+ </div>
+ </div>
+ </fieldset>
+ </ReadOnlyProvider>
+ {readOnly ? (
+ <BackLink to="/gateway/profiles" label={t('actions.back')} />
+ ) : (
+ <EditorFooter
+ status={status}
+ invalid={!valid && !needsNameOnly}
+ cancelTo="/gateway/profiles"
+ saveLabel={t(isNew ? 'profiles.editor.create' : 'actions.save')}
+ saving={save.isPending}
+ disabled={!canSave}
+ />
+ )}
</form>
</div>
)
@@ -324,6 +338,7 @@ type ProfileEditorProps = {
*/
export function ProfileEditor({ profileId, from }: ProfileEditorProps) {
const { t } = useTranslation('gateway')
+ const { readOnly } = useGateway()
const isNew = profileId === NEW_ID
const sourceId = isNew ? from : profileId
const profiles = useProfiles({ enabled: Boolean(sourceId) })
@@ -333,6 +348,9 @@ export function ProfileEditor({ profileId, from }: ProfileEditorProps) {
<BackLink to="/gateway/profiles" label={t('profiles.editor.back')} />
)
+ // The read-only notice above the tabs explains why and offers to unlock.
+ if (isNew && readOnly) return backLink
+
if (sourceId && !profiles.data) {
return (
<div className="flex w-full min-w-0 flex-col gap-5">
diff --git a/web-studio/src/routes/gateway/-components/profiles-page.tsx b/web-studio/src/routes/gateway/-components/profiles-page.tsx
index b6d15fdd0..5113711a9 100644
--- a/web-studio/src/routes/gateway/-components/profiles-page.tsx
+++ b/web-studio/src/routes/gateway/-components/profiles-page.tsx
@@ -1,8 +1,10 @@
+import { Notice } from './notice'
import * as React from 'react'
import { useMutation } from '@tanstack/react-query'
import { Link } from '@tanstack/react-router'
import {
CopyPlusIcon,
+ EyeIcon,
KeyRoundIcon,
PencilIcon,
PlusIcon,
@@ -23,10 +25,10 @@ import {
} from '#/components/ui/card'
import { cn } from '#/lib/utils'
-import { deleteProfile, keysUsing } from '../-lib/api'
+import { deleteProfile, keysUsing, toGatewayError } from '../-lib/api'
import type { GatewayTool, Profile } from '../-lib/api'
import { EMPTY_VALUE, formatNumber, formatPercent } from '../-lib/format'
-import { gatewayErrorMessage } from '../-lib/localize'
+import { toastGatewayError } from '../-lib/error-toast'
import type { Translate } from '../-lib/localize'
import { offeredTools, toProfileSettings } from '../-lib/profile-schema'
import { NEW_ID } from '../-lib/search'
@@ -87,11 +89,13 @@ function ProfileCard({
usedBy,
tools,
onDelete,
+ readOnly,
}: {
profile: Profile
/** Keys using the profile; undefined while keys are loading. */
usedBy?: number
tools: GatewayTool[] | undefined
+ readOnly: boolean
onDelete: () => void
}) {
const { t, i18n } = useTranslation('gateway')
@@ -157,37 +161,41 @@ function ProfileCard({
/>
}
>
- <PencilIcon />
- {t('actions.edit')}
+ {readOnly ? <EyeIcon /> : <PencilIcon />}
+ {t(readOnly ? 'actions.view' : 'actions.edit')}
</Button>
- <Button
- variant="ghost"
- size="sm"
- className="h-8 px-2 text-xs"
- nativeButton={false}
- render={
- <Link
- to="/gateway/profiles/$profileId"
- params={{ profileId: NEW_ID }}
- search={{ from: profile.id }}
- />
- }
- >
- <CopyPlusIcon />
- {t('actions.duplicate')}
- </Button>
- <ExplainedButton
- type="button"
- variant="ghost"
- size="icon-sm"
- disabled={inUse}
- explanation={deleteHint}
- aria-label={t('actions.delete')}
- className="text-muted-foreground hover:bg-destructive/10 hover:text-destructive"
- onClick={onDelete}
- >
- <Trash2Icon />
- </ExplainedButton>
+ {!readOnly ? (
+ <>
+ <Button
+ variant="ghost"
+ size="sm"
+ className="h-8 px-2 text-xs"
+ nativeButton={false}
+ render={
+ <Link
+ to="/gateway/profiles/$profileId"
+ params={{ profileId: NEW_ID }}
+ search={{ from: profile.id }}
+ />
+ }
+ >
+ <CopyPlusIcon />
+ {t('actions.duplicate')}
+ </Button>
+ <ExplainedButton
+ type="button"
+ variant="ghost"
+ size="icon-sm"
+ disabled={inUse}
+ explanation={deleteHint}
+ aria-label={t('actions.delete')}
+ className="text-muted-foreground hover:bg-destructive/10 hover:text-destructive"
+ onClick={onDelete}
+ >
+ <Trash2Icon />
+ </ExplainedButton>
+ </>
+ ) : null}
</div>
</CardFooter>
</Card>
@@ -197,7 +205,8 @@ function ProfileCard({
/** Context profiles: recall, saving, long conversations and tools. */
export function ProfilesPage() {
const { t } = useTranslation('gateway')
- const { connection, invalidate } = useGateway()
+ const { connection, invalidate, readOnly } = useGateway()
+ const [inUseCount, setInUseCount] = React.useState<number | null>(null)
const profiles = useProfiles()
const keys = useKeys()
const tools = useTools({
@@ -216,10 +225,16 @@ export function ProfilesPage() {
const remove = useMutation({
mutationFn: (profile: Profile) => deleteProfile(connection, profile.id),
onSuccess: async (_result, profile) => {
+ setInUseCount(null)
toast.success(t('profiles.toast.deleted', { name: profile.name }))
await invalidate('profiles')
},
- onError: (error) => toast.error(gatewayErrorMessage(t, error)),
+ // A profile still in use gets the notice with its next steps instead.
+ onError: (error) => {
+ const failure = toGatewayError(error)
+ if (failure.reason === 'in_use') setInUseCount(failure.keyCount ?? 0)
+ else toastGatewayError(t, error)
+ },
})
const refreshing = profiles.isFetching || keys.isFetching || tools.isFetching
@@ -248,25 +263,29 @@ export function ProfilesPage() {
<EmptyState
icon={<SlidersHorizontalIcon />}
title={t('profiles.empty.title')}
- description={t('profiles.empty.description')}
+ description={t(
+ readOnly ? 'profiles.empty.readOnly' : 'profiles.empty.description',
+ )}
action={
- <>
- <RecommendedProfileButton />
- <Button
- variant="outline"
- size="sm"
- nativeButton={false}
- render={
- <Link
- to="/gateway/profiles/$profileId"
- params={{ profileId: NEW_ID }}
- />
- }
- >
- <SlidersHorizontalIcon />
- {t('profiles.actions.customize')}
- </Button>
- </>
+ readOnly ? undefined : (
+ <>
+ <RecommendedProfileButton />
+ <Button
+ variant="outline"
+ size="sm"
+ nativeButton={false}
+ render={
+ <Link
+ to="/gateway/profiles/$profileId"
+ params={{ profileId: NEW_ID }}
+ />
+ }
+ >
+ <SlidersHorizontalIcon />
+ {t('profiles.actions.customize')}
+ </Button>
+ </>
+ )
}
/>
</Card>
@@ -278,6 +297,7 @@ export function ProfilesPage() {
<ProfileCard
key={profile.id}
profile={profile}
+ readOnly={readOnly}
tools={tools.data}
usedBy={keysUsing(keys.data, { profileId: profile.id })}
onDelete={() => setDeleteTarget(profile)}
@@ -305,19 +325,21 @@ export function ProfilesPage() {
/>
{t('actions.refresh')}
</Button>
- <Button
- size="sm"
- nativeButton={false}
- render={
- <Link
- to="/gateway/profiles/$profileId"
- params={{ profileId: NEW_ID }}
- />
- }
- >
- <PlusIcon />
- {t('profiles.actions.new')}
- </Button>
+ {!readOnly ? (
+ <Button
+ size="sm"
+ nativeButton={false}
+ render={
+ <Link
+ to="/gateway/profiles/$profileId"
+ params={{ profileId: NEW_ID }}
+ />
+ }
+ >
+ <PlusIcon />
+ {t('profiles.actions.new')}
+ </Button>
+ ) : null}
</>
}
/>
@@ -332,6 +354,24 @@ export function ProfilesPage() {
/>
</Card>
) : null}
+ {inUseCount !== null ? (
+ <Notice
+ tone="warning"
+ action={
+ <Button
+ variant="outline"
+ size="sm"
+ nativeButton={false}
+ render={<Link to="/gateway/keys" />}
+ >
+ {t('actions.viewKeys')}
+ </Button>
+ }
+ >
+ <p>{t('errors.reasons.in_use', { count: inUseCount })}</p>
+ <p>{t('profiles.inUseHelp')}</p>
+ </Notice>
+ ) : null}
{content}
<ConfirmDialog
open={deleteTarget !== null}
diff --git a/web-studio/src/routes/gateway/-components/profiles-pages.test.tsx b/web-studio/src/routes/gateway/-components/profiles-pages.test.tsx
index 30fff7757..8a5aba5ed 100644
--- a/web-studio/src/routes/gateway/-components/profiles-pages.test.tsx
+++ b/web-studio/src/routes/gateway/-components/profiles-pages.test.tsx
@@ -34,6 +34,7 @@ import { ProfilesPage } from './profiles-page'
import { ProfileEditor } from './profiles-editor'
const api = vi.hoisted(() => ({
+ getAccess: vi.fn(),
listProfiles: vi.fn(),
listKeys: vi.fn(),
listTools: vi.fn(),
@@ -195,6 +196,16 @@ const sectionSwitch = (section: string) =>
const toolName = (name: string) => new RegExp(`^${name}\\b`)
beforeEach(() => {
+ api.getAccess.mockResolvedValue({
+ managed: false,
+ can_write_objects: true,
+ can_import_vlm: true,
+ can_issue_for_others: true,
+ role: 'admin',
+ account_id: 'acme',
+ user_id: 'admin',
+ warnings: [],
+ })
vi.spyOn(window, 'scrollTo').mockImplementation(() => {})
api.listProfiles.mockResolvedValue([coding, chat])
api.listKeys.mockResolvedValue([key('k1', 'p1'), key('k2', 'p1')])
@@ -702,3 +713,53 @@ describe('profile editor', () => {
).toBeTruthy()
})
})
+
+it('shows a read-only profile with disabled custom controls and no save action', async () => {
+ api.getAccess.mockResolvedValue({
+ managed: true,
+ can_write_objects: false,
+ can_import_vlm: false,
+ can_issue_for_others: false,
+ role: 'user',
+ account_id: 'acme',
+ user_id: 'alice',
+ warnings: [],
+ })
+ renderAt('/gateway/profiles/p1')
+ const name = await screen.findByDisplayValue<HTMLInputElement>('Coding')
+ await waitFor(() => expect(name.disabled).toBe(true))
+ for (const control of screen.getAllByRole('switch'))
+ expect(
+ control.getAttribute('data-disabled') !== null ||
+ (control as HTMLButtonElement).disabled,
+ ).toBe(true)
+ for (const control of screen.queryAllByRole('checkbox'))
+ expect(
+ control.getAttribute('data-disabled') !== null ||
+ (control as HTMLButtonElement).disabled,
+ ).toBe(true)
+ expect(screen.queryByRole('button', { name: 'actions.save' })).toBeNull()
+ expect(screen.getByRole('button', { name: 'actions.back' })).toBeTruthy()
+ expect(api.saveProfile).not.toHaveBeenCalled()
+})
+
+it('does not expose creation or duplicate actions to read-only users', async () => {
+ api.getAccess.mockResolvedValue({
+ managed: true,
+ can_write_objects: false,
+ can_import_vlm: false,
+ can_issue_for_others: false,
+ role: 'user',
+ account_id: 'acme',
+ user_id: 'alice',
+ warnings: [],
+ })
+ renderAt('/gateway/profiles')
+ await screen.findByText('Coding')
+ expect(
+ screen.queryByRole('link', { name: 'profiles.actions.new' }),
+ ).toBeNull()
+ expect(screen.queryByRole('link', { name: 'actions.duplicate' })).toBeNull()
+ expect(screen.queryByRole('button', { name: 'actions.delete' })).toBeNull()
+ expect(screen.getAllByRole('button', { name: 'actions.view' }).length).toBe(2)
+})
diff --git a/web-studio/src/routes/gateway/-components/profiles-settings.tsx b/web-studio/src/routes/gateway/-components/profiles-settings.tsx
index 40be9766c..08af2ec12 100644
--- a/web-studio/src/routes/gateway/-components/profiles-settings.tsx
+++ b/web-studio/src/routes/gateway/-components/profiles-settings.tsx
@@ -1,3 +1,4 @@
+import { useReadOnly } from './read-only'
import * as React from 'react'
import {
BrainIcon,
@@ -230,10 +231,12 @@ function OptionCheckbox({
/** Shown after the label, such as a tool's read-only mark. */
badge?: React.ReactNode
}) {
+ const readOnly = useReadOnly()
if (!description && !badge) {
return (
<Label className="font-normal">
<Checkbox
+ disabled={readOnly}
checked={checked}
aria-label={label}
onCheckedChange={(value) => onCheckedChange(Boolean(value))}
@@ -245,6 +248,7 @@ function OptionCheckbox({
return (
<Label className="cursor-pointer items-start gap-3 rounded-lg border p-3 leading-normal font-normal transition-colors hover:bg-muted/30">
<Checkbox
+ disabled={readOnly}
checked={checked}
aria-label={label}
className="mt-0.5"
diff --git a/web-studio/src/routes/gateway/-components/read-only.tsx b/web-studio/src/routes/gateway/-components/read-only.tsx
new file mode 100644
index 000000000..e696bb9e9
--- /dev/null
+++ b/web-studio/src/routes/gateway/-components/read-only.tsx
@@ -0,0 +1,5 @@
+import { createContext, useContext } from 'react'
+
+const ReadOnlyContext = createContext(false)
+export const ReadOnlyProvider = ReadOnlyContext.Provider
+export const useReadOnly = () => useContext(ReadOnlyContext)
diff --git a/web-studio/src/routes/gateway/-components/recommended-profile-button.tsx b/web-studio/src/routes/gateway/-components/recommended-profile-button.tsx
index a59f3661d..6a65da72a 100644
--- a/web-studio/src/routes/gateway/-components/recommended-profile-button.tsx
+++ b/web-studio/src/routes/gateway/-components/recommended-profile-button.tsx
@@ -6,7 +6,7 @@ import { toast } from 'sonner'
import { Button } from '#/components/ui/button'
import { newObjectId, saveProfile } from '../-lib/api'
-import { gatewayErrorMessage } from '../-lib/localize'
+import { toastGatewayError } from '../-lib/error-toast'
import { PROFILE_DEFAULTS } from '../-lib/profile-schema'
import { useGateway } from '../-lib/use-gateway'
@@ -22,7 +22,7 @@ export function RecommendedProfileButton({
disabled = false,
}: RecommendedProfileButtonProps) {
const { t } = useTranslation('gateway')
- const { connection, invalidate } = useGateway()
+ const { connection, invalidate, readOnly } = useGateway()
const create = useMutation({
mutationFn: () =>
saveProfile(connection, newObjectId(), {
@@ -33,8 +33,9 @@ export function RecommendedProfileButton({
toast.success(t('profiles.toast.created', { name: profile.name }))
await invalidate('profiles')
},
- onError: (error) => toast.error(gatewayErrorMessage(t, error)),
+ onError: (error) => toastGatewayError(t, error),
})
+ if (readOnly) return null
return (
<Button
type="button"
diff --git a/web-studio/src/routes/gateway/-components/setting-field.tsx b/web-studio/src/routes/gateway/-components/setting-field.tsx
index 6414e20c0..626c5f49f 100644
--- a/web-studio/src/routes/gateway/-components/setting-field.tsx
+++ b/web-studio/src/routes/gateway/-components/setting-field.tsx
@@ -1,4 +1,5 @@
-import type * as React from 'react'
+import { useReadOnly } from './read-only'
+import * as React from 'react'
import { useTranslation } from 'react-i18next'
import {
@@ -38,17 +39,25 @@ export function SettingField({
children,
}: SettingFieldProps) {
const { t } = useTranslation('gateway')
+ const readOnly = useReadOnly()
+ const control = readOnly
+ ? React.Children.map(children, (child) =>
+ React.isValidElement<{ disabled?: boolean }>(child)
+ ? React.cloneElement(child, { disabled: true })
+ : child,
+ )
+ : children
const hasDefault = Boolean(defaultValue)
return (
<Field data-invalid={Boolean(error)} className={cn('gap-2', className)}>
<FieldLabel htmlFor={htmlFor}>{label}</FieldLabel>
{unit ? (
<div className="flex items-center gap-2">
- <div className="min-w-0 flex-1">{children}</div>
+ <div className="min-w-0 flex-1">{control}</div>
<span className="shrink-0 text-sm text-muted-foreground">{unit}</span>
</div>
) : (
- children
+ control
)}
{description || hasDefault ? (
<FieldDescription className="text-xs">
diff --git a/web-studio/src/routes/gateway/-components/setting-section.tsx b/web-studio/src/routes/gateway/-components/setting-section.tsx
index 39304d210..4b5988229 100644
--- a/web-studio/src/routes/gateway/-components/setting-section.tsx
+++ b/web-studio/src/routes/gateway/-components/setting-section.tsx
@@ -1,3 +1,4 @@
+import { useReadOnly } from './read-only'
import * as React from 'react'
import { ChevronRightIcon, CircleAlertIcon } from 'lucide-react'
import { useTranslation } from 'react-i18next'
@@ -62,9 +63,10 @@ export function SettingSection({
children,
}: SettingSectionProps) {
const { t } = useTranslation('gateway')
+ const readOnly = useReadOnly()
const [advancedOpen, setAdvancedOpen] = React.useState(false)
// Save checks every setting, so one that needs fixing must stay visible.
- const open = checked !== false || invalid
+ const open = readOnly || checked !== false || invalid
const hasBody = open && Boolean(children || advanced)
return (
<Card id={id} className="scroll-mt-20 gap-0 py-0">
@@ -82,7 +84,7 @@ export function SettingSection({
<CardAction>
<Switch
checked={checked}
- disabled={switchDisabled}
+ disabled={switchDisabled || readOnly}
aria-label={title}
onCheckedChange={(value) => onCheckedChange?.(value)}
/>
@@ -102,7 +104,7 @@ export function SettingSection({
{advanced ? (
<Collapsible
className="grid gap-5"
- open={advancedOpen || advancedInvalid}
+ open={readOnly || advancedOpen || advancedInvalid}
onOpenChange={setAdvancedOpen}
>
<CollapsibleTrigger className="group/advanced flex w-fit items-center gap-1.5 rounded-sm text-sm font-medium text-muted-foreground hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none">
diff --git a/web-studio/src/routes/gateway/-components/setup-card.tsx b/web-studio/src/routes/gateway/-components/setup-card.tsx
new file mode 100644
index 000000000..b72ed0eec
--- /dev/null
+++ b/web-studio/src/routes/gateway/-components/setup-card.tsx
@@ -0,0 +1,37 @@
+import type * as React from 'react'
+import { ServerOffIcon } from 'lucide-react'
+
+import {
+ Card,
+ CardContent,
+ CardDescription,
+ CardHeader,
+ CardTitle,
+} from '#/components/ui/card'
+
+/** Full-page card that explains why the gateway can't be shown and what to do. */
+export function SetupCard({
+ title,
+ description,
+ children,
+ actions,
+}: {
+ title: string
+ description: string
+ children?: React.ReactNode
+ actions?: React.ReactNode
+}) {
+ return (
+ <Card className="mx-auto mt-6 w-full max-w-2xl">
+ <CardHeader className="gap-3">
+ <ServerOffIcon className="size-6 text-muted-foreground" />
+ <CardTitle>{title}</CardTitle>
+ <CardDescription className="leading-6">{description}</CardDescription>
+ </CardHeader>
+ <CardContent className="grid gap-4">
+ {children}
+ <div className="flex flex-wrap gap-2">{actions}</div>
+ </CardContent>
+ </Card>
+ )
+}
diff --git a/web-studio/src/routes/gateway/-components/tag-input.tsx b/web-studio/src/routes/gateway/-components/tag-input.tsx
index 0156dde46..53f7b1e6b 100644
--- a/web-studio/src/routes/gateway/-components/tag-input.tsx
+++ b/web-studio/src/routes/gateway/-components/tag-input.tsx
@@ -1,3 +1,4 @@
+import { useReadOnly } from './read-only'
import * as React from 'react'
import { PlusIcon, XIcon } from 'lucide-react'
import { useTranslation } from 'react-i18next'
@@ -38,9 +39,11 @@ export function TagInput({
suggestions = [],
placeholder,
id,
- disabled,
+ disabled: explicitlyDisabled,
...aria
}: TagInputProps) {
+ const readOnly = useReadOnly()
+ const disabled = explicitlyDisabled || readOnly
const { t } = useTranslation('gateway')
const [text, setText] = React.useState('')
@@ -90,14 +93,19 @@ export function TagInput({
className="h-6 max-w-full gap-1 pr-1 font-mono font-normal"
>
<span className="truncate">{item}</span>
- <button
- type="button"
- aria-label={t('tags.remove', { value: item })}
- className="rounded-sm text-muted-foreground hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
- onClick={() => onChange(value.filter((other) => other !== item))}
- >
- <XIcon className="size-3" />
- </button>
+ {readOnly ? null : (
+ <button
+ type="button"
+ disabled={disabled}
+ aria-label={t('tags.remove', { value: item })}
+ className="rounded-sm text-muted-foreground hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
+ onClick={() =>
+ onChange(value.filter((other) => other !== item))
+ }
+ >
+ <XIcon className="size-3" />
+ </button>
+ )}
</Badge>
))}
<input
@@ -106,7 +114,7 @@ export function TagInput({
id={id}
value={text}
disabled={disabled}
- placeholder={value.length ? undefined : placeholder}
+ placeholder={value.length || readOnly ? undefined : placeholder}
className="h-6 min-w-24 flex-1 bg-transparent font-mono text-sm outline-none placeholder:font-sans placeholder:text-muted-foreground"
onChange={(event) => setText(event.target.value)}
onKeyDown={onKeyDown}
@@ -123,6 +131,7 @@ export function TagInput({
<button
key={item}
type="button"
+ disabled={disabled}
className="inline-flex h-6 items-center gap-1 rounded-full border border-dashed px-2 font-mono text-xs text-muted-foreground transition-colors hover:border-solid hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
onClick={() => add([item])}
>
diff --git a/web-studio/src/routes/gateway/-components/toggle-row.tsx b/web-studio/src/routes/gateway/-components/toggle-row.tsx
index e3f9456b0..f0a52c62a 100644
--- a/web-studio/src/routes/gateway/-components/toggle-row.tsx
+++ b/web-studio/src/routes/gateway/-components/toggle-row.tsx
@@ -1,3 +1,4 @@
+import { useReadOnly } from './read-only'
import type * as React from 'react'
import { Label } from '#/components/ui/label'
@@ -28,6 +29,7 @@ export function ToggleRow({
invalid = false,
children,
}: ToggleRowProps) {
+ const readOnly = useReadOnly()
return (
<div className="grid rounded-lg border">
<div className="flex items-start justify-between gap-4 px-4 py-3">
@@ -41,6 +43,7 @@ export function ToggleRow({
</p>
</div>
<Switch
+ disabled={readOnly}
id={id}
checked={checked}
aria-label={label}
diff --git a/web-studio/src/routes/gateway/-components/upstreams-actions.tsx b/web-studio/src/routes/gateway/-components/upstreams-actions.tsx
index 1f1301687..d19b8aa60 100644
--- a/web-studio/src/routes/gateway/-components/upstreams-actions.tsx
+++ b/web-studio/src/routes/gateway/-components/upstreams-actions.tsx
@@ -1,3 +1,14 @@
+import * as React from 'react'
+import { Link } from '@tanstack/react-router'
+import { Button } from '#/components/ui/button'
+import {
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from '#/components/ui/dialog'
import { useMutation } from '@tanstack/react-query'
import { LoaderCircleIcon, PlugZapIcon, Trash2Icon } from 'lucide-react'
import { useTranslation } from 'react-i18next'
@@ -5,12 +16,19 @@ import { toast } from 'sonner'
import { cn } from '#/lib/utils'
-import { deleteUpstream, testUpstream, toGatewayError } from '../-lib/api'
+import {
+ deleteUpstream,
+ saveUpstream,
+ testUpstream,
+ toGatewayError,
+} from '../-lib/api'
import type { Upstream, UpstreamTestResult } from '../-lib/api'
+import { toastGatewayError } from '../-lib/error-toast'
import { gatewayErrorMessage } from '../-lib/localize'
import type { Translate } from '../-lib/localize'
import { useGateway } from '../-lib/use-gateway'
-import { ConfirmDialog } from './confirm-dialog'
+import { toUpstreamInput } from '../-lib/upstream-schema'
+import { Notice } from './notice'
import { ExplainedButton } from './explained-button'
import { ToneBadge } from './status-badges'
import type { Tone } from './status-badges'
@@ -40,31 +58,60 @@ export function describeTest(t: Translate, outcome: TestOutcome): TestSummary {
explanation: gatewayErrorMessage(t, outcome.error),
}
}
+ const withUrl = (message: string) =>
+ result.url ? `${message} ${result.url}` : message
+ if (
+ result.reason === 'models_unavailable' ||
+ result.status === 404 ||
+ result.status === 405 ||
+ result.reason === 'rate_limited' ||
+ result.status === 429
+ ) {
+ return {
+ tone: 'neutral',
+ label: t('upstreams.test.result.unverified', { status: result.status }),
+ explanation: withUrl(
+ t(
+ result.reason === 'rate_limited' || result.status === 429
+ ? 'upstreams.test.explain.rateLimited'
+ : 'upstreams.test.explain.notFound',
+ ),
+ ),
+ }
+ }
+ if (result.reason === 'upstream_key_missing') {
+ return {
+ tone: 'danger',
+ label: t('upstreams.credentials.keyMissing'),
+ explanation: t('errors.reasons.upstream_key_missing'),
+ }
+ }
if (result.status === undefined) {
return {
tone: 'danger',
label: t('upstreams.test.result.unreachable'),
- explanation: t('upstreams.test.explain.unreachable'),
+ explanation: withUrl(t('upstreams.test.explain.unreachable')),
}
}
const { status } = result
- if (result.ok) {
+ if (result.ok && result.reason !== 'upstream_key_rejected') {
return {
tone: 'success',
label: t('upstreams.test.result.ok', { status }),
explanation: t('upstreams.test.explain.ok'),
}
}
+ // 404 and 405 were answered above as reachable but unverified.
const explanation =
- status === 401 || status === 403
+ result.reason === 'upstream_key_rejected' ||
+ status === 401 ||
+ status === 403
? t('upstreams.test.explain.auth')
- : status === 404
- ? t('upstreams.test.explain.notFound')
- : t('upstreams.test.explain.status', { status })
+ : t('upstreams.test.explain.status', { status })
return {
tone: 'danger',
label: t('upstreams.test.result.failed', { status }),
- explanation,
+ explanation: withUrl(explanation),
}
}
@@ -145,12 +192,12 @@ export function UpstreamTest({
}
type DeleteUpstreamButtonProps = {
- /** Keys that use the upstream; deleting is blocked while there are any. */
+ /** Known keys that use the upstream; the server confirms conflicts. */
usedBy: number | undefined
onClick: () => void
}
-/** Header Delete button, disabled with the reason while keys use the upstream. */
+/** Header Delete button; the server checks whether keys still use it. */
export function DeleteUpstreamButton({
usedBy,
onClick,
@@ -162,7 +209,6 @@ export function DeleteUpstreamButton({
type="button"
variant="destructive"
size="sm"
- disabled={blocked}
explanation={
blocked ? t('upstreams.delete.blocked', { count: usedBy }) : undefined
}
@@ -189,27 +235,101 @@ export function DeleteUpstreamDialog({
}: DeleteUpstreamDialogProps) {
const { t } = useTranslation('gateway')
const { connection, invalidate } = useGateway()
+ const [conflict, setConflict] = React.useState<number | null>(null)
+ React.useEffect(() => setConflict(null), [upstream?.id])
+ const disable = useMutation({
+ mutationFn: (target: Upstream) =>
+ saveUpstream(connection, target.id, {
+ ...toUpstreamInput(target),
+ enabled: false,
+ }),
+ onSuccess: async () => {
+ onOpenChange(false)
+ await invalidate('upstreams')
+ },
+ onError: (error) => toastGatewayError(t, error),
+ })
const remove = useMutation({
mutationFn: (target: Upstream) => deleteUpstream(connection, target.id),
onSuccess: async (_result, target) => {
toast.success(t('upstreams.toast.deleted', { name: target.name }))
+ onOpenChange(false)
onDeleted?.()
await invalidate('upstreams')
},
onError: async (error) => {
- toast.error(gatewayErrorMessage(t, error))
- if (toGatewayError(error).reason === 'conflict') await invalidate('keys')
+ const failure = toGatewayError(error)
+ if (failure.reason === 'in_use') {
+ setConflict(failure.keyCount ?? 0)
+ await invalidate('keys')
+ } else toastGatewayError(t, error)
},
})
+ const pending = remove.isPending || disable.isPending
return (
- <ConfirmDialog
+ <Dialog
open={upstream !== null}
- onOpenChange={onOpenChange}
- title={t('upstreams.delete.title', { name: upstream?.name ?? '' })}
- description={t('upstreams.delete.description')}
- confirmLabel={t('upstreams.delete.confirm')}
- icon={<Trash2Icon />}
- onConfirm={() => (upstream ? remove.mutateAsync(upstream) : undefined)}
- />
+ onOpenChange={(open) => {
+ if (!pending) onOpenChange(open)
+ }}
+ >
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>
+ {t('upstreams.delete.title', { name: upstream?.name ?? '' })}
+ </DialogTitle>
+ <DialogDescription>
+ {t('upstreams.delete.description')}
+ </DialogDescription>
+ </DialogHeader>
+ {conflict !== null ? (
+ <Notice tone="warning">
+ <p>{t('upstreams.delete.inUse', { count: conflict })}</p>
+ {upstream?.enabled ? (
+ <p>{t('upstreams.delete.disableHint')}</p>
+ ) : null}
+ <Link
+ to="/gateway/keys"
+ className="justify-self-start font-medium underline underline-offset-4"
+ >
+ {t('actions.viewKeys')}
+ </Link>
+ </Notice>
+ ) : null}
+ <DialogFooter>
+ <Button
+ type="button"
+ variant="outline"
+ disabled={pending}
+ onClick={() => onOpenChange(false)}
+ >
+ {t('actions.cancel')}
+ </Button>
+ {conflict !== null ? (
+ upstream?.enabled ? (
+ <Button
+ type="button"
+ disabled={pending}
+ onClick={() => disable.mutate(upstream)}
+ >
+ {t('upstreams.delete.disable')}
+ </Button>
+ ) : null
+ ) : (
+ <Button
+ type="button"
+ variant="destructive"
+ disabled={pending}
+ onClick={() => {
+ if (upstream) remove.mutate(upstream)
+ }}
+ >
+ <Trash2Icon />
+ {t('upstreams.delete.confirm')}
+ </Button>
+ )}
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
)
}
diff --git a/web-studio/src/routes/gateway/-components/upstreams-editor.tsx b/web-studio/src/routes/gateway/-components/upstreams-editor.tsx
index 7de0fa0c4..13e7040e3 100644
--- a/web-studio/src/routes/gateway/-components/upstreams-editor.tsx
+++ b/web-studio/src/routes/gateway/-components/upstreams-editor.tsx
@@ -10,7 +10,7 @@ import { Card } from '#/components/ui/card'
import { keysUsing, newObjectId, saveUpstream } from '../-lib/api'
import type { Upstream, UpstreamInput } from '../-lib/api'
-import { gatewayErrorMessage } from '../-lib/localize'
+import { toastGatewayError } from '../-lib/error-toast'
import { NEW_ID } from '../-lib/search'
import {
UPSTREAM_DEFAULTS,
@@ -19,6 +19,7 @@ import {
} from '../-lib/upstream-schema'
import { useGateway, useKeys, useUpstreams } from '../-lib/use-gateway'
import { isValid } from '../-lib/validation'
+import { ReadOnlyProvider } from './read-only'
import { EditorFooter } from './editor-footer'
import { EmptyState, ErrorState, LoadingState } from './empty-state'
import { BackLink, SectionHeader } from './section-header'
@@ -41,16 +42,23 @@ export function UpstreamEditorPage() {
/** Loads the upstream (unless creating one) and shows the editor or a state. */
export function UpstreamEditor({ upstreamId }: { upstreamId: string }) {
const { t } = useTranslation('gateway')
+ const { readOnly } = useGateway()
const isNew = upstreamId === NEW_ID
const upstreams = useUpstreams({ enabled: !isNew })
const keys = useKeys({ enabled: !isNew })
+ // The read-only notice above the tabs explains why and offers to unlock.
+ if (isNew && readOnly)
+ return (
+ <BackLink to="/gateway/upstreams" label={t('upstreams.editor.back')} />
+ )
if (isNew) return <UpstreamEditorForm />
const stored = upstreams.data?.find((item) => item.id === upstreamId)
if (stored) {
return (
<UpstreamEditorForm
+ key={`${stored.id}:${stored.revision}:${readOnly}`}
stored={stored}
usedBy={keysUsing(keys.data, { upstreamId: stored.id })}
/>
@@ -117,7 +125,7 @@ type UpstreamEditorFormProps = {
function UpstreamEditorForm({ stored, usedBy }: UpstreamEditorFormProps) {
const { t } = useTranslation('gateway')
const navigate = useNavigate()
- const { connection, invalidate } = useGateway()
+ const { connection, invalidate, readOnly } = useGateway()
const [id] = React.useState(() => stored?.id ?? newObjectId())
const [initial] = React.useState(() =>
stored ? toUpstreamInput(stored) : UPSTREAM_DEFAULTS,
@@ -182,10 +190,10 @@ function UpstreamEditorForm({ stored, usedBy }: UpstreamEditorFormProps) {
await invalidate('upstreams')
await navigate({ to: '/gateway/upstreams' })
},
- onError: (error) => toast.error(gatewayErrorMessage(t, error)),
+ onError: (error) => toastGatewayError(t, error),
})
- const canSave = dirty && valid && !save.isPending
+ const canSave = !readOnly && dirty && valid && !save.isPending
const missing = Object.keys(errors)
.map((field) => UPSTREAM_FIELD_LABELS[field as UpstreamField])
.filter((label): label is string => Boolean(label))
@@ -212,13 +220,17 @@ function UpstreamEditorForm({ stored, usedBy }: UpstreamEditorFormProps) {
/>
}
title={stored ? stored.name : t('upstreams.editor.newTitle')}
- description={t(
- stored
- ? 'upstreams.editor.editDescription'
- : 'upstreams.editor.newDescription',
- )}
+ description={
+ readOnly
+ ? undefined
+ : t(
+ stored
+ ? 'upstreams.editor.editDescription'
+ : 'upstreams.editor.newDescription',
+ )
+ }
actions={
- stored ? (
+ stored && !readOnly ? (
<>
<UpstreamTest
upstream={stored}
@@ -234,26 +246,46 @@ function UpstreamEditorForm({ stored, usedBy }: UpstreamEditorFormProps) {
}
/>
- <UpstreamForm
- draft={draft}
- stored={stored}
- onChange={change}
- onFill={fill}
- onBlur={visit}
- error={errorFor}
- />
+ <ReadOnlyProvider value={readOnly}>
+ <fieldset disabled={readOnly} className="min-w-0">
+ <UpstreamForm
+ draft={draft}
+ stored={stored}
+ onChange={change}
+ onFill={fill}
+ onBlur={visit}
+ error={readOnly ? () => undefined : errorFor}
+ />
+ </fieldset>
+ </ReadOnlyProvider>
- <EditorFooter
- status={
- dirty && missing
- ? t('upstreams.editor.missing', { fields: missing })
- : undefined
- }
- cancelTo="/gateway/upstreams"
- saveLabel={t(stored ? 'actions.save' : 'upstreams.editor.create')}
- saving={save.isPending}
- disabled={!canSave}
- />
+ {readOnly ? (
+ <div className="flex items-center justify-between gap-3">
+ <Button
+ type="button"
+ nativeButton={false}
+ variant="outline"
+ render={<Link to="/gateway/upstreams" />}
+ >
+ {t('actions.back')}
+ </Button>
+ {stored ? (
+ <UpstreamTest upstream={stored} variant="header" />
+ ) : null}
+ </div>
+ ) : (
+ <EditorFooter
+ status={
+ dirty && missing
+ ? t('upstreams.editor.missing', { fields: missing })
+ : undefined
+ }
+ cancelTo="/gateway/upstreams"
+ saveLabel={t(stored ? 'actions.save' : 'upstreams.editor.create')}
+ saving={save.isPending}
+ disabled={!canSave}
+ />
+ )}
</form>
<DeleteUpstreamDialog
upstream={deleting}
diff --git a/web-studio/src/routes/gateway/-components/upstreams-form.tsx b/web-studio/src/routes/gateway/-components/upstreams-form.tsx
index 1ecfd7af0..e5ad75aa2 100644
--- a/web-studio/src/routes/gateway/-components/upstreams-form.tsx
+++ b/web-studio/src/routes/gateway/-components/upstreams-form.tsx
@@ -8,6 +8,7 @@ import {
} from 'lucide-react'
import { useTranslation } from 'react-i18next'
+import { Button } from '#/components/ui/button'
import { Checkbox } from '#/components/ui/checkbox'
import { Input } from '#/components/ui/input'
import { RadioGroup, RadioGroupItem } from '#/components/ui/radio-group'
@@ -38,6 +39,8 @@ import {
UPSTREAM_KEY_HEADER,
VENDORS,
baseUrlAfterSwitch,
+ baseUrlChanged,
+ baseUrlCorrection,
defaultBaseUrl,
endpointPreview,
protocolFor,
@@ -47,6 +50,7 @@ import {
usesDefaultBaseUrl,
} from '../-lib/upstream-schema'
import { KeyValueEditor } from './key-value-editor'
+import { useReadOnly } from './read-only'
import { Notice } from './notice'
import { NumberInput } from './number-input'
import { SettingField } from './setting-field'
@@ -116,6 +120,7 @@ function ChoiceCard({
/** Why the option can't be picked; disables it and replaces `detail`. */
unavailable?: string
}) {
+ const readOnly = useReadOnly()
return (
<label
className={cn(
@@ -127,7 +132,7 @@ function ChoiceCard({
>
<RadioGroupItem
value={value}
- disabled={Boolean(unavailable)}
+ disabled={readOnly || Boolean(unavailable)}
className="mt-0.5 data-disabled:opacity-50"
/>
<span className="grid min-w-0 gap-1">
@@ -166,9 +171,11 @@ function CheckRow({
label: string
description: string
}) {
+ const readOnly = useReadOnly()
return (
<label className="flex cursor-pointer items-start gap-3">
<Checkbox
+ disabled={readOnly}
checked={checked}
className="mt-0.5"
onCheckedChange={(value) => onCheckedChange(value)}
@@ -193,6 +200,10 @@ export function UpstreamForm({
error,
}: UpstreamFormProps) {
const { t, i18n } = useTranslation('gateway')
+ const readOnly = useReadOnly()
+ const correction = baseUrlCorrection(draft)
+ const addressChanged = baseUrlChanged(draft, stored)
+ const headersCleared = addressChanged && Boolean(stored?.header_names?.length)
const preview = endpointPreview(draft)
const defaultUrl = defaultBaseUrl(draft.vendor, draft.protocol)
const keyStored = Boolean(stored?.has_api_key)
@@ -333,7 +344,33 @@ export function UpstreamForm({
</code>
</p>
) : null}
- {defaultUrl && !usesDefaultBaseUrl(draft) ? (
+ {correction && !readOnly ? (
+ <Notice
+ tone="warning"
+ action={
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ onClick={() => onChange('base_url', correction.url)}
+ >
+ {t(
+ correction.reason === 'anthropicVersion'
+ ? 'upstreams.form.baseUrl.removeVersion'
+ : 'upstreams.form.baseUrl.correctPath',
+ { url: correction.url },
+ )}
+ </Button>
+ }
+ >
+ <p>{t(`upstreams.form.baseUrl.${correction.reason}`)}</p>
+ </Notice>
+ ) : null}
+ {/* The correction button already offers the default address. */}
+ {!readOnly &&
+ defaultUrl &&
+ !usesDefaultBaseUrl(draft) &&
+ correction?.url !== defaultUrl ? (
<button
type="button"
className="flex max-w-full min-w-0 gap-1 justify-self-start text-xs font-medium whitespace-nowrap text-foreground underline underline-offset-4"
@@ -352,108 +389,142 @@ export function UpstreamForm({
title={t('upstreams.sections.credentials.title')}
description={t('upstreams.sections.credentials.description')}
>
- <SettingField label={t('upstreams.form.authMode.label')}>
- <RadioGroup
- value={draft.auth_mode}
- aria-label={t('upstreams.form.authMode.label')}
- className="grid gap-2 md:grid-cols-2"
- onValueChange={(value) => {
- const mode = AUTH_MODES.find((item) => item === value)
- if (mode) onChange('auth_mode', mode)
- }}
- >
- {AUTH_MODES.map((mode) => (
- <ChoiceCard
- key={mode}
- value={mode}
- title={t(`upstreams.form.authMode.${mode}.title`)}
- description={t(`upstreams.form.authMode.${mode}.description`, {
- header: UPSTREAM_KEY_HEADER,
- })}
- />
- ))}
- </RadioGroup>
- </SettingField>
- {draft.auth_mode === 'managed' ? (
- <SettingField
- label={
- <>
- {t('upstreams.form.apiKey.label')}
- {keyStored ? (
- <ToneBadge tone="success">
- {t('upstreams.form.apiKey.stored')}
- </ToneBadge>
- ) : null}
- </>
- }
- htmlFor="upstream-api-key"
- description={t(
- keyStored
- ? 'upstreams.form.apiKey.storedDescription'
- : 'upstreams.form.apiKey.description',
- )}
- error={error('api_key')}
- >
- <Input
- {...PLAIN_INPUT_PROPS}
- id="upstream-api-key"
- type="password"
- autoComplete="new-password"
- value={draft.api_key}
- placeholder={t(
- keyStored
- ? 'field.storedSecret'
- : 'upstreams.form.apiKey.placeholder',
+ {readOnly ? (
+ <div className="flex flex-wrap items-center gap-2 text-sm">
+ <span>
+ {t(
+ draft.auth_mode === 'passthrough'
+ ? 'upstreams.readOnly.clientKey'
+ : 'upstreams.readOnly.managedKey',
)}
- aria-invalid={Boolean(error('api_key'))}
- className="font-mono sm:max-w-md"
- onChange={(event) => onChange('api_key', event.target.value)}
- onBlur={() => onBlur('api_key')}
- />
- </SettingField>
- ) : null}
- <SettingField
- label={t('upstreams.form.headers.label')}
- description={t('upstreams.form.headers.description')}
- error={error('headers')}
- >
- <KeyValueEditor
- value={draft.headers}
- storedKeys={stored?.header_names}
- maskValues
- keyPlaceholder={t('upstreams.form.headers.name')}
- valuePlaceholder={t('upstreams.form.headers.value')}
- addLabel={t('upstreams.form.headers.add')}
- aria-invalid={Boolean(error('headers'))}
- onChange={(headers) => onChange('headers', headers)}
- />
- </SettingField>
- <div className="grid gap-3">
- <CheckRow
- checked={draft.coding_plan}
- label={t('upstreams.form.codingPlan.label')}
- description={t('upstreams.form.codingPlan.description')}
- onCheckedChange={(checked) => {
- onChange('coding_plan', checked)
- if (!checked) onChange('allow_coding_plan', false)
- }}
- />
- {draft.coding_plan ? (
- <Notice tone="warning" className="ml-7">
- <p>{t('upstreams.form.codingPlan.warning')}</p>
- <div className="mt-2">
- <CheckRow
- checked={draft.allow_coding_plan}
- label={t('upstreams.form.codingPlan.allow')}
- description={t('upstreams.form.codingPlan.allowDescription')}
- onCheckedChange={(checked) =>
- onChange('allow_coding_plan', checked)
- }
+ </span>
+ {draft.coding_plan ? (
+ <ToneBadge tone="neutral">
+ {t(
+ draft.allow_coding_plan
+ ? 'upstreams.readOnly.codingAllowed'
+ : 'upstreams.readOnly.codingBlocked',
+ )}
+ </ToneBadge>
+ ) : null}
+ </div>
+ ) : (
+ <>
+ <SettingField label={t('upstreams.form.authMode.label')}>
+ <RadioGroup
+ value={draft.auth_mode}
+ aria-label={t('upstreams.form.authMode.label')}
+ className="grid gap-2 md:grid-cols-2"
+ onValueChange={(value) => {
+ const mode = AUTH_MODES.find((item) => item === value)
+ if (mode) onChange('auth_mode', mode)
+ }}
+ >
+ {AUTH_MODES.map((mode) => (
+ <ChoiceCard
+ key={mode}
+ value={mode}
+ title={t(`upstreams.form.authMode.${mode}.title`)}
+ description={t(
+ `upstreams.form.authMode.${mode}.description`,
+ {
+ header: UPSTREAM_KEY_HEADER,
+ },
+ )}
+ />
+ ))}
+ </RadioGroup>
+ </SettingField>
+ {draft.auth_mode === 'managed' ? (
+ <SettingField
+ label={
+ <>
+ {t('upstreams.form.apiKey.label')}
+ {keyStored && !addressChanged ? (
+ <ToneBadge tone="success">
+ {t('upstreams.form.apiKey.stored')}
+ </ToneBadge>
+ ) : null}
+ </>
+ }
+ htmlFor="upstream-api-key"
+ description={t(
+ addressChanged && !draft.api_key.trim()
+ ? 'upstreams.form.apiKey.addressChanged'
+ : keyStored
+ ? 'upstreams.form.apiKey.storedDescription'
+ : 'upstreams.form.apiKey.description',
+ )}
+ error={error('api_key')}
+ >
+ <Input
+ {...PLAIN_INPUT_PROPS}
+ id="upstream-api-key"
+ type="password"
+ autoComplete="new-password"
+ value={draft.api_key}
+ placeholder={t(
+ keyStored && !addressChanged
+ ? 'field.storedSecret'
+ : 'upstreams.form.apiKey.placeholder',
+ )}
+ aria-invalid={Boolean(error('api_key'))}
+ className="font-mono sm:max-w-md"
+ onChange={(event) => onChange('api_key', event.target.value)}
+ onBlur={() => onBlur('api_key')}
/>
- </div>
- </Notice>
- ) : null}
- </div>
+ </SettingField>
+ ) : null}
+ <SettingField
+ label={t('upstreams.form.headers.label')}
+ description={t(
+ headersCleared
+ ? 'upstreams.form.headers.addressChanged'
+ : 'upstreams.form.headers.description',
+ )}
+ error={error('headers')}
+ >
+ <KeyValueEditor
+ value={draft.headers}
+ storedKeys={addressChanged ? undefined : stored?.header_names}
+ maskValues
+ keyPlaceholder={t('upstreams.form.headers.name')}
+ valuePlaceholder={t('upstreams.form.headers.value')}
+ addLabel={t('upstreams.form.headers.add')}
+ aria-invalid={Boolean(error('headers'))}
+ onChange={(headers) => onChange('headers', headers)}
+ />
+ </SettingField>
+ <div className="grid gap-3">
+ <CheckRow
+ checked={draft.coding_plan}
+ label={t('upstreams.form.codingPlan.label')}
+ description={t('upstreams.form.codingPlan.description')}
+ onCheckedChange={(checked) => {
+ onChange('coding_plan', checked)
+ if (!checked) onChange('allow_coding_plan', false)
+ }}
+ />
+ {draft.coding_plan ? (
+ <Notice tone="warning" className="ml-7">
+ <p>{t('upstreams.form.codingPlan.warning')}</p>
+ <div className="mt-2">
+ <CheckRow
+ checked={draft.allow_coding_plan}
+ label={t('upstreams.form.codingPlan.allow')}
+ description={t(
+ 'upstreams.form.codingPlan.allowDescription',
+ )}
+ onCheckedChange={(checked) =>
+ onChange('allow_coding_plan', checked)
+ }
+ />
+ </div>
+ </Notice>
+ ) : null}
+ </div>
+ </>
+ )}
</SettingSection>
<SettingSection
diff --git a/web-studio/src/routes/gateway/-components/upstreams-page.tsx b/web-studio/src/routes/gateway/-components/upstreams-page.tsx
index abbf4dd15..0e8efed1e 100644
--- a/web-studio/src/routes/gateway/-components/upstreams-page.tsx
+++ b/web-studio/src/routes/gateway/-components/upstreams-page.tsx
@@ -15,7 +15,6 @@ import {
TriangleAlertIcon,
} from 'lucide-react'
import { useTranslation } from 'react-i18next'
-import { toast } from 'sonner'
import { Badge } from '#/components/ui/badge'
import { Button } from '#/components/ui/button'
@@ -37,9 +36,10 @@ import {
} from '#/components/ui/table'
import { cn } from '#/lib/utils'
-import { keysUsing, saveUpstream } from '../-lib/api'
-import type { Upstream } from '../-lib/api'
+import { importVlm, keysUsing, saveUpstream, toGatewayError } from '../-lib/api'
+import type { Upstream, VlmImportResult } from '../-lib/api'
import { formatNumber, hostFromUrl } from '../-lib/format'
+import { toastGatewayError } from '../-lib/error-toast'
import {
authModeLabel,
gatewayErrorMessage,
@@ -54,6 +54,7 @@ import {
useUpstreams,
} from '../-lib/use-gateway'
import { EmptyState, ErrorState, LoadingState } from './empty-state'
+import { Notice } from './notice'
import { SectionHeader } from './section-header'
import { EmptyValue, ProtocolBadge, ToneBadge } from './status-badges'
import { DeleteUpstreamDialog, UpstreamTest } from './upstreams-actions'
@@ -98,7 +99,7 @@ function useToggleUpstream() {
onError: (error, { upstream }) => {
// `upstream` is the row as it was before the switch was flipped.
setEnabled(upstream.id, upstream.enabled)
- toast.error(gatewayErrorMessage(t, error))
+ toastGatewayError(t, error)
},
// Refetch after the last running toggle only (this one still counts), so
// the fresh list doesn't undo switches whose save hasn't finished.
@@ -118,6 +119,22 @@ function useToggleUpstream() {
/** Model providers the gateway forwards requests to. */
export function UpstreamsPage() {
const { t } = useTranslation('gateway')
+ const { connection, access, invalidate, scope, readOnly } = useGateway()
+ const [importResult, setImportResult] =
+ React.useState<VlmImportResult | null>(null)
+ React.useEffect(() => setImportResult(null), [scope])
+ const importer = useMutation({
+ mutationFn: () => importVlm(connection),
+ onSuccess: async (result) => {
+ setImportResult(result)
+ await invalidate('upstreams')
+ },
+ // A stale /access offered the import; the refreshed one hides it.
+ onError: (error) =>
+ toGatewayError(error).reason === 'vlm_import_forbidden'
+ ? invalidate('access')
+ : undefined,
+ })
const upstreams = useUpstreams()
const keys = useKeys()
const { toggle, pending: toggling } = useToggleUpstream()
@@ -130,7 +147,7 @@ export function UpstreamsPage() {
)
const refreshing = upstreams.isFetching || keys.isFetching
- const addButton = (
+ const addButton = !readOnly ? (
<Button
size="sm"
nativeButton={false}
@@ -144,7 +161,26 @@ export function UpstreamsPage() {
<PlusIcon />
{t('upstreams.add')}
</Button>
- )
+ ) : null
+ const importButton = (empty = false) =>
+ access?.can_import_vlm ? (
+ <Button
+ type="button"
+ size="sm"
+ variant="outline"
+ disabled={importer.isPending}
+ title={t('upstreams.import.hint')}
+ onClick={() => importer.mutate()}
+ >
+ {t(
+ importer.isPending
+ ? 'upstreams.import.running'
+ : empty
+ ? 'upstreams.import.useSettings'
+ : 'upstreams.import.action',
+ )}
+ </Button>
+ ) : null
let body: React.ReactNode
if (upstreams.isPending) {
@@ -163,8 +199,15 @@ export function UpstreamsPage() {
<EmptyState
icon={<ServerIcon />}
title={t('upstreams.empty.title')}
- description={t('upstreams.empty.description')}
- action={addButton}
+ description={t(
+ readOnly ? 'upstreams.readOnly.empty' : 'upstreams.empty.description',
+ )}
+ action={
+ <div className="flex flex-wrap gap-2">
+ {importButton(true)}
+ {addButton}
+ </div>
+ }
/>
)
} else {
@@ -204,6 +247,7 @@ export function UpstreamsPage() {
<UpstreamRow
key={upstream.id}
upstream={upstream}
+ readOnly={readOnly}
usedBy={keysUsing(keys.data, { upstreamId: upstream.id })}
toggling={toggling.has(upstream.id)}
onToggle={(enabled) => toggle({ upstream, enabled })}
@@ -236,10 +280,29 @@ export function UpstreamsPage() {
/>
{t('actions.refresh')}
</Button>
+ {importButton()}
{addButton}
</>
}
/>
+ {importer.isError ? (
+ <Notice
+ tone="danger"
+ action={
+ toGatewayError(importer.error).reason === 'vlm_import_unavailable'
+ ? addButton
+ : undefined
+ }
+ >
+ {gatewayErrorMessage(t, importer.error)}
+ </Notice>
+ ) : null}
+ {importResult ? (
+ <ImportResultNotice
+ result={importResult}
+ onDismiss={() => setImportResult(null)}
+ />
+ ) : null}
<Card className="gap-0 overflow-hidden py-0">
<CardContent className="p-0">{body}</CardContent>
</Card>
@@ -253,8 +316,76 @@ export function UpstreamsPage() {
)
}
+/** What an import of OpenViking's model settings saved, and what needs a look. */
+function ImportResultNotice({
+ result,
+ onDismiss,
+}: {
+ result: VlmImportResult
+ onDismiss: () => void
+}) {
+ const { t } = useTranslation('gateway')
+ const { imported, needs_confirmation: confirm, skipped } = result
+ // Upstreams awaiting Coding Plan confirmation are saved too.
+ const saved = imported.length + confirm.length
+ return (
+ <Notice
+ tone={confirm.length || skipped.length ? 'warning' : 'info'}
+ action={
+ <Button type="button" size="sm" variant="outline" onClick={onDismiss}>
+ {t('upstreams.import.dismiss')}
+ </Button>
+ }
+ >
+ {saved ? (
+ <p className="font-medium">
+ {t('upstreams.import.summary', { count: saved })}
+ </p>
+ ) : skipped.length ? null : (
+ <p className="font-medium">{t('upstreams.import.nothing')}</p>
+ )}
+ {confirm.length ? (
+ <div>
+ <p>{t('upstreams.import.needsConfirmation')}</p>
+ <ul className="list-inside list-disc">
+ {confirm.map((item) => (
+ <li key={item.id}>
+ {item.name}{' '}
+ <Link
+ className="font-medium underline underline-offset-4"
+ to="/gateway/upstreams/$upstreamId"
+ params={{ upstreamId: item.id }}
+ >
+ {t('upstreams.import.confirm')}
+ </Link>
+ </li>
+ ))}
+ </ul>
+ </div>
+ ) : null}
+ {skipped.length ? (
+ <div>
+ <p>{t('upstreams.import.skipped', { count: skipped.length })}</p>
+ <ul className="list-inside list-disc">
+ {skipped.map((item) => (
+ <li key={item.id}>
+ {item.id}:{' '}
+ {t(`upstreams.import.reasons.${item.reason}`, {
+ defaultValue: t('upstreams.import.reasons.unknown'),
+ })}
+ </li>
+ ))}
+ </ul>
+ </div>
+ ) : null}
+ {saved ? <p className="text-xs">{t('upstreams.import.repeat')}</p> : null}
+ </Notice>
+ )
+}
+
type UpstreamRowProps = {
upstream: Upstream
+ readOnly: boolean
/** Keys that use this upstream; undefined while keys are loading. */
usedBy: number | undefined
toggling: boolean
@@ -264,6 +395,7 @@ type UpstreamRowProps = {
function UpstreamRow({
upstream,
+ readOnly,
usedBy,
toggling,
onToggle,
@@ -340,7 +472,7 @@ function UpstreamRow({
<Switch
size="sm"
checked={upstream.enabled}
- disabled={toggling}
+ disabled={readOnly || toggling}
aria-label={t(
upstream.enabled
? 'upstreams.toggle.disable'
@@ -353,49 +485,52 @@ function UpstreamRow({
<TableCell className="pr-4">
<div className="flex items-center justify-end gap-1">
<UpstreamTest upstream={upstream} />
- <Button
- size="sm"
- variant="ghost"
- className="h-8 px-2 text-xs"
- nativeButton={false}
- render={editLink}
- >
- <PencilIcon />
- <span className="max-md:sr-only">{t('actions.edit')}</span>
- </Button>
- <DropdownMenu>
- <DropdownMenuTrigger
- render={
- <Button
- type="button"
- size="icon-sm"
- variant="ghost"
- aria-label={t('actions.more')}
- title={t('actions.more')}
- />
- }
- >
- <EllipsisIcon />
- </DropdownMenuTrigger>
- <DropdownMenuContent align="end" className="w-auto min-w-48">
- <DropdownMenuItem
- variant="destructive"
- disabled={Boolean(usedBy)}
- className="items-start"
- onClick={onDelete}
+ {!readOnly ? (
+ <>
+ <Button
+ size="sm"
+ variant="ghost"
+ className="h-8 px-2 text-xs"
+ nativeButton={false}
+ render={editLink}
>
- <Trash2Icon className="mt-0.5" />
- <span className="grid gap-0.5">
- <span>{t('upstreams.delete.action')}</span>
- {usedBy ? (
- <span className="text-xs">
- {t('upstreams.delete.blocked', { count: usedBy })}
+ <PencilIcon />
+ <span className="max-md:sr-only">{t('actions.edit')}</span>
+ </Button>
+ <DropdownMenu>
+ <DropdownMenuTrigger
+ render={
+ <Button
+ type="button"
+ size="icon-sm"
+ variant="ghost"
+ aria-label={t('actions.more')}
+ title={t('actions.more')}
+ />
+ }
+ >
+ <EllipsisIcon />
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end" className="w-auto min-w-48">
+ <DropdownMenuItem
+ variant="destructive"
+ className="items-start"
+ onClick={onDelete}
+ >
+ <Trash2Icon className="mt-0.5" />
+ <span className="grid gap-0.5">
+ <span>{t('upstreams.delete.action')}</span>
+ {usedBy ? (
+ <span className="text-xs">
+ {t('upstreams.delete.blocked', { count: usedBy })}
+ </span>
+ ) : null}
</span>
- ) : null}
- </span>
- </DropdownMenuItem>
- </DropdownMenuContent>
- </DropdownMenu>
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ </>
+ ) : null}
</div>
</TableCell>
</TableRow>
diff --git a/web-studio/src/routes/gateway/-components/upstreams-pages.test.tsx b/web-studio/src/routes/gateway/-components/upstreams-pages.test.tsx
index 55a8b335b..50c51b2b0 100644
--- a/web-studio/src/routes/gateway/-components/upstreams-pages.test.tsx
+++ b/web-studio/src/routes/gateway/-components/upstreams-pages.test.tsx
@@ -29,6 +29,8 @@ import { UpstreamsPage } from './upstreams-page'
import { describeTest } from './upstreams-actions'
const api = vi.hoisted(() => ({
+ getAccess: vi.fn(),
+ importVlm: vi.fn(),
listUpstreams: vi.fn(),
listKeys: vi.fn(),
saveUpstream: vi.fn(),
@@ -203,6 +205,16 @@ beforeEach(() => {
for (const fn of [...Object.values(api), ...Object.values(toast)]) {
fn.mockReset()
}
+ api.getAccess.mockResolvedValue({
+ managed: false,
+ can_write_objects: true,
+ can_import_vlm: false,
+ can_issue_for_others: true,
+ role: 'admin',
+ account_id: 'acme',
+ user_id: 'admin',
+ warnings: [],
+ })
api.listUpstreams.mockResolvedValue([openai, claude, ark])
api.listKeys.mockResolvedValue([
gatewayKey('k1', ['u1']),
@@ -347,7 +359,7 @@ describe('UpstreamsPage', () => {
expect(toast.success).toHaveBeenCalledWith('upstreams.toast.deleted Ark')
})
- it('blocks deleting an upstream that keys use', async () => {
+ it('explains deleting an upstream that keys use', async () => {
renderAt('/gateway/upstreams')
await screen.findByText('OpenAI')
await waitFor(() =>
@@ -360,7 +372,7 @@ describe('UpstreamsPage', () => {
const item = (await screen.findByText('upstreams.delete.action')).closest(
'[role="menuitem"]',
)
- expect(item?.getAttribute('aria-disabled')).toBe('true')
+ expect(item?.getAttribute('aria-disabled')).not.toBe('true')
expect(screen.getByText('upstreams.delete.blocked')).toBeTruthy()
})
})
@@ -386,40 +398,88 @@ describe('UpstreamEditor', () => {
const save = screen.getByRole('button', { name: 'actions.save' })
expect(save.hasAttribute('disabled')).toBe(true)
- fireEvent.change(screen.getByLabelText('upstreams.form.baseUrl.label'), {
- target: { value: 'https://llm.example.com' },
+ fireEvent.change(screen.getByLabelText('upstreams.form.name.label'), {
+ target: { value: 'OpenAI EU' },
})
- expect(
- screen.getByText('https://llm.example.com/v1/chat/completions'),
- ).toBeTruthy()
await waitFor(() => expect(save.hasAttribute('disabled')).toBe(false))
fireEvent.click(save)
await waitFor(() => expect(api.saveUpstream).toHaveBeenCalledTimes(1))
expect(api.saveUpstream.mock.lastCall?.[1]).toBe('u1')
expect(lastSavedBody()).toMatchObject({
- name: 'OpenAI',
- base_url: 'https://llm.example.com',
+ name: 'OpenAI EU',
api_key: '',
headers: { 'OpenAI-Organization': '' },
priority: 5,
})
- expect(toast.success).toHaveBeenCalledWith('upstreams.toast.saved OpenAI')
+ expect(toast.success).toHaveBeenCalledWith(
+ 'upstreams.toast.saved OpenAI EU',
+ )
await waitFor(() =>
expect(router.state.location.pathname).toBe('/gateway/upstreams'),
)
})
- it('blocks deleting while keys use the upstream', async () => {
+ it('asks for the API key and header values again after the address changes', async () => {
renderAt('/gateway/upstreams/u1')
await screen.findByLabelText('upstreams.form.name.label')
+ const save = screen.getByRole('button', { name: 'actions.save' })
+ fireEvent.change(screen.getByLabelText('upstreams.form.baseUrl.label'), {
+ target: { value: 'https://llm.example.com' },
+ })
+ expect(
+ screen.getByText('https://llm.example.com/chat/completions'),
+ ).toBeTruthy()
+ expect(
+ screen.getByText('upstreams.form.apiKey.addressChanged'),
+ ).toBeTruthy()
+ expect(
+ screen.getByText('upstreams.form.headers.addressChanged'),
+ ).toBeTruthy()
+ expect(save.hasAttribute('disabled')).toBe(true)
+
+ fireEvent.change(
+ screen.getByLabelText('upstreams.form.apiKey.label', { exact: false }),
+ { target: { value: 'sk-new' } },
+ )
+ fireEvent.change(
+ screen.getByPlaceholderText('upstreams.form.headers.value'),
+ { target: { value: 'org-1' } },
+ )
+ await waitFor(() => expect(save.hasAttribute('disabled')).toBe(false))
+ fireEvent.click(save)
await waitFor(() =>
- expect(screen.getByTitle('upstreams.delete.blocked')).toBeTruthy(),
+ expect(lastSavedBody()).toMatchObject({
+ base_url: 'https://llm.example.com',
+ api_key: 'sk-new',
+ headers: { 'OpenAI-Organization': 'org-1' },
+ }),
)
- const button = screen.getByRole('button', {
- name: 'upstreams.delete.action',
- })
- expect(button.hasAttribute('disabled')).toBe(true)
+ })
+
+ it('offers disabling after the server reports keys still use the upstream', async () => {
+ api.deleteUpstream.mockRejectedValue(
+ new GatewayError('In use', 409, undefined, 'in_use', { key_count: 2 }),
+ )
+ renderAt('/gateway/upstreams/u1')
+ await screen.findByLabelText('upstreams.form.name.label')
+ fireEvent.click(
+ await screen.findByRole('button', { name: 'upstreams.delete.action' }),
+ )
+ fireEvent.click(
+ screen.getByRole('button', { name: 'upstreams.delete.confirm' }),
+ )
+ expect(await screen.findByText('upstreams.delete.inUse')).toBeTruthy()
+ expect(
+ screen
+ .getByRole('link', { name: 'actions.viewKeys' })
+ .getAttribute('href'),
+ ).toBe('/gateway/keys')
+ fireEvent.click(
+ screen.getByRole('button', { name: 'upstreams.delete.disable' }),
+ )
+ await waitFor(() => expect(api.saveUpstream).toHaveBeenCalledTimes(1))
+ expect(lastSavedBody().enabled).toBe(false)
})
it('creates an upstream once the required fields are valid', async () => {
@@ -631,7 +691,7 @@ describe('UpstreamEditor', () => {
fireEvent.click(useDefaultButton() as HTMLElement)
await waitFor(() =>
expect(baseUrlInput().value).toBe(
- 'https://ark.ap-southeast.bytepluses.com',
+ 'https://ark.ap-southeast.bytepluses.com/api/v3',
),
)
expect(useDefaultButton()).toBeNull()
@@ -679,8 +739,28 @@ describe('describeTest', () => {
it.each([
[{ ok: true, status: 200 }, 'success', 'upstreams.test.explain.ok'],
[{ ok: false, status: 401 }, 'danger', 'upstreams.test.explain.auth'],
- [{ ok: false, status: 404 }, 'danger', 'upstreams.test.explain.notFound'],
+ [{ ok: true, status: 404 }, 'neutral', 'upstreams.test.explain.notFound'],
+ [
+ { ok: true, status: 405, reason: 'models_unavailable' },
+ 'neutral',
+ 'upstreams.test.explain.notFound',
+ ],
+ [
+ { ok: true, status: 429, reason: 'rate_limited' },
+ 'neutral',
+ 'upstreams.test.explain.rateLimited',
+ ],
+ [
+ { ok: false, status: 200, reason: 'upstream_key_rejected' },
+ 'danger',
+ 'upstreams.test.explain.auth',
+ ],
[{ ok: false, status: 500 }, 'danger', 'upstreams.test.explain.status'],
+ [
+ { ok: false, reason: 'upstream_key_missing' },
+ 'danger',
+ 'errors.reasons.upstream_key_missing',
+ ],
[
{ ok: false, reason: 'upstream_unavailable' },
'danger',
@@ -692,12 +772,238 @@ describe('describeTest', () => {
it('explains a failed call with the gateway message', () => {
const summary = describeTest(t, {
- error: new GatewayError('Upstream API key is missing', 401),
+ error: new GatewayError(
+ 'Upstream API key is missing',
+ 401,
+ undefined,
+ 'upstream_key_missing',
+ ),
})
expect(summary).toEqual({
tone: 'danger',
label: 'upstreams.test.result.error',
- explanation: 'errors.upstreamKeyMissing',
+ explanation: 'errors.reasons.upstream_key_missing',
+ })
+ })
+})
+
+describe('upstream access and import', () => {
+ function readOnly() {
+ api.getAccess.mockResolvedValue({
+ managed: true,
+ can_write_objects: false,
+ can_import_vlm: false,
+ can_issue_for_others: false,
+ role: 'user',
+ account_id: 'acme',
+ user_id: 'alice',
+ warnings: [],
})
+ }
+
+ it('shows read-only list details and retains connection testing', async () => {
+ readOnly()
+ api.testUpstream.mockResolvedValue({
+ ok: true,
+ status: 404,
+ reason: 'models_unavailable',
+ })
+ renderAt('/gateway/upstreams')
+ await screen.findByText('OpenAI')
+ expect(screen.queryByText('upstreams.add')).toBeNull()
+ expect(screen.queryByText('upstreams.import.action')).toBeNull()
+ expect(screen.queryByText('actions.edit')).toBeNull()
+ expect(screen.queryByRole('button', { name: 'actions.more' })).toBeNull()
+ const toggle = rowOf('OpenAI').getByRole('switch')
+ expect(toggle.hasAttribute('data-disabled')).toBe(true)
+ fireEvent.click(toggle)
+ expect(api.saveUpstream).not.toHaveBeenCalled()
+ fireEvent.click(
+ rowOf('OpenAI').getByRole('button', { name: 'upstreams.test.action' }),
+ )
+ expect(
+ await screen.findByText('upstreams.test.result.unverified'),
+ ).toBeTruthy()
+ })
+
+ it('disables read-only editor controls, hides credentials, and tests outside the fieldset', async () => {
+ readOnly()
+ api.listUpstreams.mockResolvedValue([
+ { ...openai, header_names: undefined, coding_plan: true },
+ ])
+ api.testUpstream.mockResolvedValue({
+ ok: true,
+ status: 200,
+ reason: 'passed',
+ })
+ renderAt('/gateway/upstreams/u1')
+ expect(
+ await screen.findByText('upstreams.readOnly.managedKey'),
+ ).toBeTruthy()
+ expect(screen.getByText('upstreams.readOnly.codingBlocked')).toBeTruthy()
+ expect(
+ screen.queryByLabelText('upstreams.form.apiKey.label', { exact: false }),
+ ).toBeNull()
+ expect(screen.queryByText('upstreams.form.headers.label')).toBeNull()
+ expect(screen.queryByRole('button', { name: 'actions.save' })).toBeNull()
+ expect(
+ screen.queryByRole('button', { name: 'upstreams.delete.action' }),
+ ).toBeNull()
+ expect(screen.getByRole('combobox').hasAttribute('disabled')).toBe(true)
+ for (const control of screen.getAllByRole('switch'))
+ expect(control.hasAttribute('data-disabled')).toBe(true)
+ expect(
+ screen.getByLabelText<HTMLInputElement>('upstreams.form.models.label')
+ .disabled,
+ ).toBe(true)
+ expect(
+ screen.getByLabelText<HTMLInputElement>('upstreams.form.name.label')
+ .disabled,
+ ).toBe(true)
+ const test = screen.getByRole('button', {
+ name: 'upstreams.test.connection',
+ })
+ expect(test.closest('fieldset')).toBeNull()
+ fireEvent.click(test)
+ await waitFor(() => expect(api.testUpstream).toHaveBeenCalledTimes(1))
+ })
+
+ it('blocks the direct create URL for read-only users', async () => {
+ readOnly()
+ renderAt('/gateway/upstreams/new')
+ expect(
+ (await screen.findByText('upstreams.editor.back'))
+ .closest('a')
+ ?.getAttribute('href'),
+ ).toBe('/gateway/upstreams')
+ expect(screen.queryByLabelText('upstreams.form.name.label')).toBeNull()
+ })
+
+ it('warns about a stored key after editing the address and offers a path correction', async () => {
+ renderAt('/gateway/upstreams/u1')
+ await screen.findByLabelText('upstreams.form.name.label')
+ fireEvent.change(baseUrlInput(), {
+ target: { value: 'https://other.example' },
+ })
+ expect(
+ screen.getByText('upstreams.form.apiKey.addressChanged'),
+ ).toBeTruthy()
+ expect(screen.getByText('upstreams.form.baseUrl.missingPath')).toBeTruthy()
+ fireEvent.click(
+ screen.getByRole('button', {
+ name: 'upstreams.form.baseUrl.correctPath',
+ }),
+ )
+ expect(baseUrlInput().value).toBe('https://other.example/v1')
+ fireEvent.change(
+ screen.getByLabelText('upstreams.form.apiKey.label', { exact: false }),
+ { target: { value: 'replacement' } },
+ )
+ expect(
+ screen.queryByText('upstreams.form.apiKey.addressChanged'),
+ ).toBeNull()
+ })
+
+ it('shows import results, confirmation links and skipped reasons, then dismisses the notice', async () => {
+ api.getAccess.mockResolvedValue({
+ can_write_objects: true,
+ can_import_vlm: true,
+ })
+ api.importVlm.mockResolvedValue({
+ imported: [{ id: 'vlm-a', name: 'A' }],
+ needs_confirmation: [{ id: 'vlm-coding', name: 'Coding account' }],
+ skipped: [
+ { id: 'oauth', reason: 'openai_codex' },
+ { id: 'azure', reason: 'azure' },
+ { id: 'lite', reason: 'litellm_no_api_base' },
+ ],
+ })
+ renderAt('/gateway/upstreams')
+ fireEvent.click(
+ await screen.findByRole('button', { name: 'upstreams.import.action' }),
+ )
+ expect(await screen.findByText('upstreams.import.summary')).toBeTruthy()
+ expect(
+ screen
+ .getByRole('link', { name: 'upstreams.import.confirm' })
+ .getAttribute('href'),
+ ).toBe('/gateway/upstreams/vlm-coding')
+ expect(
+ screen.getByText('oauth: upstreams.import.reasons.openai_codex'),
+ ).toBeTruthy()
+ expect(
+ screen.getByText('azure: upstreams.import.reasons.azure'),
+ ).toBeTruthy()
+ expect(
+ screen.getByText('lite: upstreams.import.reasons.litellm_no_api_base'),
+ ).toBeTruthy()
+ expect(screen.getByText('upstreams.import.repeat')).toBeTruthy()
+ fireEvent.click(
+ screen.getByRole('button', { name: 'upstreams.import.dismiss' }),
+ )
+ expect(screen.queryByText('upstreams.import.summary')).toBeNull()
+ expect(api.importVlm).toHaveBeenCalledTimes(1)
+ })
+
+ it('lists only the skipped credentials when an import saves nothing', async () => {
+ api.getAccess.mockResolvedValue({
+ can_write_objects: true,
+ can_import_vlm: true,
+ })
+ api.importVlm.mockResolvedValue({
+ imported: [],
+ needs_confirmation: [],
+ skipped: [{ id: 'oauth', reason: 'openai_codex' }],
+ })
+ renderAt('/gateway/upstreams')
+ fireEvent.click(
+ await screen.findByRole('button', { name: 'upstreams.import.action' }),
+ )
+ expect(
+ await screen.findByText('oauth: upstreams.import.reasons.openai_codex'),
+ ).toBeTruthy()
+ expect(screen.queryByText('upstreams.import.summary')).toBeNull()
+ expect(screen.queryByText('upstreams.import.nothing')).toBeNull()
+ expect(screen.queryByText('upstreams.import.repeat')).toBeNull()
+ })
+
+ it('offers manual setup when the server cannot import VLM settings', async () => {
+ api.getAccess.mockResolvedValue({
+ can_write_objects: true,
+ can_import_vlm: true,
+ })
+ api.importVlm.mockRejectedValue(
+ new GatewayError('Unavailable', 409, undefined, 'vlm_import_unavailable'),
+ )
+ renderAt('/gateway/upstreams')
+ fireEvent.click(
+ await screen.findByRole('button', { name: 'upstreams.import.action' }),
+ )
+ expect(
+ await screen.findByText('errors.reasons.vlm_import_unavailable'),
+ ).toBeTruthy()
+ expect(screen.getAllByText('upstreams.add')).toHaveLength(2)
+ })
+
+ it('hides a forbidden import entry once /access is refreshed', async () => {
+ api.getAccess
+ .mockResolvedValueOnce({ can_write_objects: true, can_import_vlm: true })
+ .mockResolvedValue({ can_write_objects: true, can_import_vlm: false })
+ api.importVlm.mockRejectedValue(
+ new GatewayError('Forbidden', 403, undefined, 'vlm_import_forbidden'),
+ )
+ renderAt('/gateway/upstreams')
+ fireEvent.click(
+ await screen.findByRole('button', { name: 'upstreams.import.action' }),
+ )
+ expect(
+ await screen.findByText('errors.reasons.vlm_import_forbidden'),
+ ).toBeTruthy()
+ await waitFor(() =>
+ expect(
+ screen.queryByRole('button', { name: 'upstreams.import.action' }),
+ ).toBeNull(),
+ )
+ expect(api.getAccess).toHaveBeenCalledTimes(2)
})
})
diff --git a/web-studio/src/routes/gateway/-lib/api.test.ts b/web-studio/src/routes/gateway/-lib/api.test.ts
index 9e5ebd9da..b9787c7c2 100644
--- a/web-studio/src/routes/gateway/-lib/api.test.ts
+++ b/web-studio/src/routes/gateway/-lib/api.test.ts
@@ -1,9 +1,11 @@
+// @vitest-environment jsdom
import { AxiosError } from 'axios'
import type { AxiosResponse } from 'axios'
import { beforeEach, describe, expect, it, vi } from 'vitest'
import {
GatewayError,
+ getAccess,
deleteUserData,
getConnectionInfo,
issueKey,
@@ -15,6 +17,7 @@ import {
saveUpstream,
toGatewayError,
} from './api'
+import { getManagementKey, setManagementKey } from './management-key'
import { UPSTREAM_DEFAULTS } from './upstream-schema'
const { request } = vi.hoisted(() => ({ request: vi.fn() }))
@@ -45,6 +48,7 @@ function failure(status: number, data: unknown) {
beforeEach(() => {
request.mockReset()
+ sessionStorage.clear()
})
describe('gateway calls', () => {
@@ -55,7 +59,7 @@ describe('gateway calls', () => {
const [options] = request.mock.calls[0]
expect(options).toMatchObject({
method: 'PUT',
- url: '/api/v1/admin/gateway/upstreams/a%2Fb',
+ url: '/gateway/admin/upstreams/a%2Fb',
body: input,
headers: { 'Content-Type': 'application/json' },
})
@@ -70,7 +74,7 @@ describe('gateway calls', () => {
])
expect(request.mock.calls[0][0]).toMatchObject({
method: 'GET',
- url: '/api/v1/admin/gateway/logs',
+ url: '/gateway/admin/logs',
query: { limit: 50 },
})
expect(request.mock.calls[0][0]).not.toHaveProperty('body')
@@ -89,7 +93,7 @@ describe('gateway calls', () => {
await expect(listTools(connection)).resolves.toEqual(tools)
expect(request.mock.calls[0][0]).toMatchObject({
method: 'GET',
- url: '/api/v1/admin/gateway/tools',
+ url: '/gateway/admin/tools',
})
request.mockResolvedValue(ok([]))
await expect(listTools(connection)).resolves.toEqual([])
@@ -114,9 +118,9 @@ describe('gateway calls', () => {
expect(
request.mock.calls.map(([options]) => [options.method, options.url]),
).toEqual([
- ['POST', '/api/v1/admin/gateway/keys/key-1/capture/reset'],
- ['POST', '/api/v1/admin/gateway/keys'],
- ['DELETE', '/api/v1/admin/gateway/users/alice/data'],
+ ['POST', '/gateway/admin/keys/key-1/capture/reset'],
+ ['POST', '/gateway/admin/keys'],
+ ['DELETE', '/gateway/admin/users/alice/data'],
])
})
})
@@ -150,73 +154,40 @@ describe('listKeyUsers', () => {
describe('toGatewayError', () => {
it.each([
[
- 'a FastAPI detail',
+ 'explicit in-use reason',
409,
- { detail: 'Revoke or update dependent keys before deleting this object' },
- 'conflict',
- 'Revoke or update dependent keys before deleting this object',
+ { reason: 'in_use', key_count: 3, detail: 'dependent keys' },
+ 'in_use',
+ 'dependent keys',
],
[
- 'a disabled gateway (OpenViking envelope)',
- 503,
- {
- status: 'error',
- error: {
- code: 'UNAVAILABLE',
- message: 'OpenViking Gateway is not enabled',
- },
- },
+ 'disabled gateway',
+ 404,
+ { reason: 'not_enabled', detail: 'disabled' },
'not_enabled',
- 'OpenViking Gateway is not enabled',
+ 'disabled',
],
[
- 'a missing management token',
- 503,
- {
- status: 'error',
- error: {
- code: 'UNAVAILABLE',
- message: 'OpenViking Gateway management token is not configured',
- },
- },
- 'token_missing',
- 'OpenViking Gateway management token is not configured',
- ],
- [
- 'an unreachable gateway',
- 503,
- {
- status: 'error',
- error: {
- code: 'UNAVAILABLE',
- message: 'OpenViking Gateway management service is unavailable',
- details: { original_http_status_code: 502 },
- },
- },
- 'unreachable',
- 'OpenViking Gateway management service is unavailable',
- ],
- [
- 'a management token that differs from the gateway',
+ 'invalid management key',
401,
- { detail: 'Invalid gateway management credential' },
- 'token_mismatch',
- 'Invalid gateway management credential',
- ],
- [
- 'an OpenViking reason from key issuance',
- 403,
- { error: { message: 'root_key_not_allowed' } },
- 'forbidden',
- 'root_key_not_allowed',
+ { reason: 'management_key_invalid', detail: 'invalid management key' },
+ 'management_key_invalid',
+ 'invalid management key',
],
[
- 'a validation list',
+ 'validation list',
422,
{ detail: [{ msg: 'Field required' }, { msg: 'Input too long' }] },
'invalid',
'Field required; Input too long',
],
+ [
+ 'unknown wording without a reason',
+ 503,
+ { detail: 'OpenViking Gateway management token is not configured' },
+ 'other',
+ 'OpenViking Gateway management token is not configured',
+ ],
])('reads %s', async (_, status, body, reason, detail) => {
request.mockRejectedValue(failure(status, body))
const thrown = await listLogs(connection).catch((caught) => caught)
@@ -226,14 +197,7 @@ describe('toGatewayError', () => {
reason,
detail,
])
- expect(thrown.unavailable).toBe(
- [
- 'not_enabled',
- 'token_missing',
- 'token_mismatch',
- 'unreachable',
- ].includes(reason),
- )
+ expect(thrown.unavailable).toBe(reason === 'not_enabled')
})
it('reads a missing gateway route as a server without gateway support', async () => {
@@ -243,7 +207,7 @@ describe('toGatewayError', () => {
const thrown = await getConnectionInfo(connection).catch((caught) => caught)
expect([thrown.status, thrown.reason, thrown.unavailable]).toEqual([
404,
- 'unsupported',
+ 'not_enabled',
true,
])
// Elsewhere a 404 still means the item is gone.
@@ -271,3 +235,45 @@ it('creates distinct hex ids without crypto.randomUUID', () => {
expect(ids.size).toBe(50)
for (const id of ids) expect(id).toMatch(/^[0-9a-f]{16}$/)
})
+
+it('sends management secrets only to gateway calls, with account scope', async () => {
+ setManagementKey(connection.baseUrl, 'ovgm-management-secret')
+ request.mockResolvedValue(ok([]))
+ await listLogs(connection)
+ expect(request.mock.calls[0][0]).toMatchObject({
+ query: { account_id: 'acme' },
+ headers: {
+ 'X-OpenViking-Gateway-Management-Key': 'ovgm-management-secret',
+ },
+ })
+ await listKeyUsers(connection)
+ expect(request.mock.calls[1][0].headers).toBeUndefined()
+})
+it('locks an expired stored key but does not store an unverified candidate', async () => {
+ setManagementKey(connection.baseUrl, 'old-key')
+ request.mockRejectedValue(
+ failure(401, { reason: 'management_key_invalid', detail: 'rotated' }),
+ )
+ await expect(
+ getAccess({ ...connection, managementKey: 'wrong-candidate' }),
+ ).rejects.toMatchObject({
+ reason: 'management_key_invalid',
+ })
+ expect(getManagementKey(connection.baseUrl)).toBe('old-key')
+ await expect(getAccess(connection)).rejects.toMatchObject({
+ reason: 'management_key_invalid',
+ })
+ expect(getManagementKey(connection.baseUrl)).toBe('')
+})
+
+it('uses the query credential snapshot even after the tab is unlocked or locked', async () => {
+ request.mockResolvedValue(ok([]))
+ setManagementKey(connection.baseUrl, 'new-management-key')
+ await listLogs({ ...connection, managementKey: '' })
+ expect(request.mock.calls[0][0].headers).toBeUndefined()
+ sessionStorage.clear()
+ await listLogs({ ...connection, managementKey: 'captured-key' })
+ expect(request.mock.calls[1][0].headers).toEqual({
+ 'X-OpenViking-Gateway-Management-Key': 'captured-key',
+ })
+})
diff --git a/web-studio/src/routes/gateway/-lib/api.ts b/web-studio/src/routes/gateway/-lib/api.ts
index 9d278221a..3957a1aa2 100644
--- a/web-studio/src/routes/gateway/-lib/api.ts
+++ b/web-studio/src/routes/gateway/-lib/api.ts
@@ -1,7 +1,12 @@
+import { getManagementKey, lockManagementKey } from './management-key'
import { createAdminClient } from '#/lib/admin'
import type { AdminConnection } from '#/lib/admin'
+
import { getOvResult, isOvClientError } from '#/lib/ov-client'
+/** Credentials captured with the query scope; undefined reads the current tab key. */
+export type GatewayConnection = AdminConnection & { managementKey?: string }
+
/** Wire protocol an upstream speaks; the gateway never converts between them. */
export type Protocol = 'anthropic' | 'chat' | 'responses'
export type Vendor =
@@ -78,12 +83,13 @@ export type Upstream = UpstreamSettings & {
id: string
revision: number
has_api_key: boolean
- header_names: string[]
+ header_names?: string[]
}
/**
* Body of `PUT upstreams/{id}`. A blank `api_key` keeps the stored key; a
- * header with a blank value keeps its stored value; omitted headers are removed.
+ * header with a blank value keeps its stored value; omitted headers are retained.
+ * Changing base_url clears retained API-key and header secrets.
*/
export type UpstreamInput = UpstreamSettings & {
api_key: string
@@ -160,9 +166,7 @@ export function keysUsing(
* Who a new key acts as: a user of this account, whose key OpenViking Server
* looks up itself, or that user's OpenViking key pasted by the admin.
*/
-export type KeyOwner =
- | { user_id: string; openviking_key?: never }
- | { openviking_key: string; user_id?: never }
+export type KeyOwner = { user_id?: string; openviking_key?: string }
export type KeyRequest = KeyOwner & {
name: string
@@ -175,8 +179,11 @@ export type KeyRequest = KeyOwner & {
export type KeyUser = {
user_id: string
role: 'admin' | 'user'
- /** False when the server can't read the user's key, e.g. it keeps only a hash. */
- api_key_available: boolean
+ /**
+ * False when the server can't read the user's key, e.g. it keeps only a
+ * hash. OpenViking servers that predate the field omit it.
+ */
+ api_key_available?: boolean
}
export type CacheStats = {
@@ -279,7 +286,25 @@ export type ConnectionInfo = {
public_url_configured: boolean
}
+export type GatewayAccess = {
+ managed: boolean
+ can_write_objects: boolean
+ can_import_vlm: boolean
+ can_issue_for_others: boolean
+ role: string
+ account_id: string
+ user_id: string
+ warnings: string[]
+}
+
+export type VlmImportResult = {
+ imported: Array<{ id: string; name: string }>
+ needs_confirmation: Array<{ id: string; name: string }>
+ skipped: Array<{ id: string; reason: string }>
+}
+
export type UpstreamTestResult = {
+ url?: string
ok: boolean
status?: number
reason?: string
@@ -288,26 +313,12 @@ export type UpstreamTestResult = {
/** Conversation to resync, taken from a log record. */
export type ResyncTarget = { session: string; protocol: Protocol }
-export type GatewayErrorReason =
- | 'not_enabled'
- | 'token_missing'
- | 'token_mismatch'
- | 'unreachable'
- | 'unsupported'
- | 'conflict'
- | 'invalid'
- | 'forbidden'
- | 'not_found'
- | 'unauthorized'
- | 'other'
-
-/** Reasons the layout answers with a setup card instead of the gateway pages. */
-const UNAVAILABLE: GatewayErrorReason[] = [
+export type GatewayErrorReason = string
+
+const UNAVAILABLE = [
'not_enabled',
- 'token_missing',
- 'token_mismatch',
- 'unreachable',
- 'unsupported',
+ 'trusted_mode_unsupported',
+ 'openviking_unreachable',
]
/** A failed gateway call: HTTP status, the server's own message, and a category. */
@@ -315,18 +326,27 @@ export class GatewayError extends Error {
readonly status?: number
readonly detail: string
readonly reason: GatewayErrorReason
+ readonly keyCount?: number
+ readonly requiredVersion?: string
constructor(
detail: string,
status?: number,
cause?: unknown,
reason?: GatewayErrorReason,
+ metadata?: Record<string, unknown>,
) {
super(detail, cause ? { cause } : undefined)
this.name = 'GatewayError'
this.detail = detail
this.status = status
- this.reason = reason ?? classify(detail, status)
+ this.reason = reason ?? classify(status)
+ this.keyCount =
+ typeof metadata?.key_count === 'number' ? metadata.key_count : undefined
+ this.requiredVersion =
+ typeof metadata?.required_version === 'string'
+ ? metadata.required_version
+ : undefined
}
/** True when the gateway itself is off, misconfigured, down or missing. */
@@ -335,14 +355,6 @@ export class GatewayError extends Error {
}
}
-const AVAILABILITY: Array<[RegExp, GatewayErrorReason]> = [
- [/gateway is not enabled/i, 'not_enabled'],
- [/management token is not configured/i, 'token_missing'],
- // The gateway's answer when OpenViking sends a different management token.
- [/invalid gateway management credential/i, 'token_mismatch'],
- [/management service is unavailable/i, 'unreachable'],
-]
-
const STATUS_REASONS: Partial<Record<number, GatewayErrorReason>> = {
400: 'invalid',
401: 'unauthorized',
@@ -352,9 +364,7 @@ const STATUS_REASONS: Partial<Record<number, GatewayErrorReason>> = {
422: 'invalid',
}
-function classify(detail: string, status?: number): GatewayErrorReason {
- const match = AVAILABILITY.find(([pattern]) => pattern.test(detail))
- if (match) return match[1]
+function classify(status?: number): GatewayErrorReason {
return (status === undefined ? undefined : STATUS_REASONS[status]) ?? 'other'
}
@@ -379,6 +389,12 @@ function readDetail(body: unknown): string | undefined {
return undefined
}
+function readReason(body: unknown): string | undefined {
+ return isRecord(body) && typeof body.reason === 'string'
+ ? body.reason
+ : undefined
+}
+
/** Normalizes anything a gateway call can throw into a `GatewayError`. */
export function toGatewayError(error: unknown): GatewayError {
if (error instanceof GatewayError) return error
@@ -387,6 +403,8 @@ export function toGatewayError(error: unknown): GatewayError {
readDetail(error.responseBody) ?? error.message,
error.statusCode,
error,
+ readReason(error.responseBody),
+ isRecord(error.responseBody) ? error.responseBody : undefined,
)
}
return new GatewayError(
@@ -396,15 +414,19 @@ export function toGatewayError(error: unknown): GatewayError {
)
}
-const BASE_PATH = '/api/v1/admin/gateway'
+const BASE_PATH = '/gateway/admin'
type Method = 'GET' | 'POST' | 'PUT' | 'DELETE'
-type RequestOptions = { query?: Record<string, unknown>; body?: unknown }
+type RequestOptions = {
+ query?: Record<string, unknown>
+ body?: unknown
+ headers?: Record<string, string>
+}
/** One OpenViking Server call; any failure becomes a `GatewayError`. */
async function call<T>(
- connection: AdminConnection,
+ connection: GatewayConnection,
method: Method,
url: string,
options: RequestOptions = {},
@@ -414,7 +436,7 @@ async function call<T>(
? {}
: {
body: options.body,
- headers: { 'Content-Type': 'application/json' },
+ headers: { 'Content-Type': 'application/json', ...options.headers },
}
try {
return await getOvResult<T>(
@@ -422,6 +444,7 @@ async function call<T>(
method,
url,
query: options.query,
+ headers: options.headers,
...body,
}),
)
@@ -431,14 +454,34 @@ async function call<T>(
}
/** Calls the gateway's management API through OpenViking Server. */
-function send<T>(
- connection: AdminConnection,
+async function send<T>(
+ connection: GatewayConnection,
method: Method,
segments: string[],
- options?: RequestOptions,
+ options?: Omit<RequestOptions, 'headers'>,
): Promise<T> {
const url = [BASE_PATH, ...segments.map(encodeURIComponent)].join('/')
- return call<T>(connection, method, url, options)
+ const managementKey =
+ connection.managementKey ?? getManagementKey(connection.baseUrl)
+ try {
+ return await call<T>(connection, method, url, {
+ ...options,
+ query: { ...options?.query, account_id: connection.accountId },
+ headers: managementKey
+ ? { 'X-OpenViking-Gateway-Management-Key': managementKey }
+ : undefined,
+ })
+ } catch (error) {
+ const failure = toGatewayError(error)
+ // Lock only a stored key, not a candidate or a key replaced meanwhile.
+ if (
+ failure.reason === 'management_key_invalid' &&
+ managementKey === getManagementKey(connection.baseUrl)
+ ) {
+ lockManagementKey(connection.baseUrl, true)
+ }
+ throw failure
+ }
}
/**
@@ -446,61 +489,78 @@ function send<T>(
* means the OpenViking server has no OpenViking Gateway management at all.
*/
export async function getConnectionInfo(
- connection: AdminConnection,
+ connection: GatewayConnection,
): Promise<ConnectionInfo> {
try {
return await send<ConnectionInfo>(connection, 'GET', ['guides'])
} catch (error) {
const failure = toGatewayError(error)
if (failure.status !== 404) throw failure
- throw new GatewayError(failure.detail, 404, failure, 'unsupported')
+ throw new GatewayError(failure.detail, 404, failure, 'not_enabled')
}
}
-export const getOverview = (connection: AdminConnection) =>
+/** Pass `managementKey` in the connection to check a candidate key. */
+export async function getAccess(
+ connection: GatewayConnection,
+): Promise<GatewayAccess> {
+ try {
+ return await send<GatewayAccess>(connection, 'GET', ['access'])
+ } catch (error) {
+ const failure = toGatewayError(error)
+ if (failure.status === 404)
+ throw new GatewayError(failure.detail, 404, failure, 'not_enabled')
+ throw failure
+ }
+}
+
+export const importVlm = (connection: GatewayConnection) =>
+ send<VlmImportResult>(connection, 'POST', ['upstreams', 'import-vlm'])
+
+export const getOverview = (connection: GatewayConnection) =>
send<Overview>(connection, 'GET', ['overview'])
/** Newest-first request log; the gateway caps `limit` at 1,000. */
-export const listLogs = (connection: AdminConnection, limit = 200) =>
+export const listLogs = (connection: GatewayConnection, limit = 200) =>
send<LogRecord[]>(connection, 'GET', ['logs'], { query: { limit } })
-export const listUpstreams = (connection: AdminConnection) =>
+export const listUpstreams = (connection: GatewayConnection) =>
send<Upstream[]>(connection, 'GET', ['upstreams'])
-/** Available MCP tools; empty until this account has a gateway key. */
-export const listTools = (connection: AdminConnection) =>
+/** OpenViking MCP tools, read with the caller's OpenViking key (root: a key issued in this account). */
+export const listTools = (connection: GatewayConnection) =>
send<GatewayTool[]>(connection, 'GET', ['tools'])
/** Creates or replaces an upstream. Build the body with `toUpstreamInput`. */
export const saveUpstream = (
- connection: AdminConnection,
+ connection: GatewayConnection,
id: string,
input: UpstreamInput,
) => send<Upstream>(connection, 'PUT', ['upstreams', id], { body: input })
/** Fails with reason `conflict` while keys still use the upstream. */
-export const deleteUpstream = (connection: AdminConnection, id: string) =>
+export const deleteUpstream = (connection: GatewayConnection, id: string) =>
send<{ deleted: boolean }>(connection, 'DELETE', ['upstreams', id])
/** Calls the upstream's model list with its stored credentials. */
-export const testUpstream = (connection: AdminConnection, id: string) =>
+export const testUpstream = (connection: GatewayConnection, id: string) =>
send<UpstreamTestResult>(connection, 'POST', ['upstreams', id, 'test'])
-export const listProfiles = (connection: AdminConnection) =>
+export const listProfiles = (connection: GatewayConnection) =>
send<Profile[]>(connection, 'GET', ['policies'])
/** Creates or replaces a profile. Build the body with `toProfileSettings`. */
export const saveProfile = (
- connection: AdminConnection,
+ connection: GatewayConnection,
id: string,
settings: ProfileSettings,
) => send<Profile>(connection, 'PUT', ['policies', id], { body: settings })
/** Fails with reason `conflict` while keys still use the profile. */
-export const deleteProfile = (connection: AdminConnection, id: string) =>
+export const deleteProfile = (connection: GatewayConnection, id: string) =>
send<{ deleted: boolean }>(connection, 'DELETE', ['policies', id])
-export const listKeys = (connection: AdminConnection) =>
+export const listKeys = (connection: GatewayConnection) =>
send<GatewayKey[]>(connection, 'GET', ['keys'])
const KEY_USER_ROLES: readonly string[] = ['admin', 'user']
@@ -510,7 +570,7 @@ const KEY_USER_ROLES: readonly string[] = ['admin', 'user']
* whether it can read each user's key; the key never reaches the browser.
*/
export async function listKeyUsers(
- connection: AdminConnection,
+ connection: GatewayConnection,
): Promise<KeyUser[]> {
const users = await call<Array<Omit<KeyUser, 'role'> & { role: string }>>(
connection,
@@ -527,15 +587,15 @@ export async function listKeyUsers(
* Issues a key; the response is the only time the secret is available. For a
* `user_id`, OpenViking Server sends that user's stored key to the gateway.
*/
-export const issueKey = (connection: AdminConnection, request: KeyRequest) =>
+export const issueKey = (connection: GatewayConnection, request: KeyRequest) =>
send<IssuedKey>(connection, 'POST', ['keys'], { body: request })
-export const revokeKey = (connection: AdminConnection, id: string) =>
+export const revokeKey = (connection: GatewayConnection, id: string) =>
send<{ deleted: boolean }>(connection, 'DELETE', ['keys', id])
/** Starts a fresh OpenViking session for one conversation of a key. */
export const resyncCapture = (
- connection: AdminConnection,
+ connection: GatewayConnection,
keyId: string,
target: ResyncTarget,
) =>
@@ -547,7 +607,7 @@ export const resyncCapture = (
)
/** Revokes every key of an OpenViking user and deletes their gateway conversations. */
-export const deleteUserData = (connection: AdminConnection, userId: string) =>
+export const deleteUserData = (connection: GatewayConnection, userId: string) =>
send<{ deleted: boolean }>(connection, 'DELETE', ['users', userId, 'data'])
/**
diff --git a/web-studio/src/routes/gateway/-lib/client-guides.test.ts b/web-studio/src/routes/gateway/-lib/client-guides.test.ts
index 839288719..ef407fdab 100644
--- a/web-studio/src/routes/gateway/-lib/client-guides.test.ts
+++ b/web-studio/src/routes/gateway/-lib/client-guides.test.ts
@@ -11,7 +11,7 @@ import {
shellQuote,
} from './client-guides'
-const base = 'https://ov.example.com/'
+const base = 'https://ov.example.com/gateway/'
function code(client: Parameters<typeof clientSnippets>[0], id: string) {
const snippet = clientSnippets(client, { baseUrl: base }).find(
@@ -35,7 +35,7 @@ describe('clientSnippets', () => {
it('points Claude Code at the bare gateway address with a quoted placeholder', () => {
expect(code('claude-code', 'env')).toBe(
[
- 'export ANTHROPIC_BASE_URL=https://ov.example.com',
+ 'export ANTHROPIC_BASE_URL=https://ov.example.com/gateway',
"export ANTHROPIC_AUTH_TOKEN='<gateway-key>'",
'export CLAUDE_CODE_GATEWAY_HINT_HEADERS=1',
].join('\n'),
@@ -47,7 +47,7 @@ describe('clientSnippets', () => {
const table = config.indexOf('[model_providers.openviking]')
expect(config.indexOf('model_provider = "openviking"')).toBeLessThan(table)
expect(config.indexOf('model = "<model>"')).toBeLessThan(table)
- expect(config).toContain('base_url = "https://ov.example.com/v1"')
+ expect(config).toContain('base_url = "https://ov.example.com/gateway/v1"')
expect(config).toContain('wire_api = "responses"')
expect(config).toContain('env_key = "OPENVIKING_GATEWAY_KEY"')
})
@@ -76,7 +76,7 @@ describe('clientSnippets', () => {
provider: {
openviking: {
options: {
- baseURL: 'https://ov.example.com/v1',
+ baseURL: 'https://ov.example.com/gateway/v1',
apiKey: '{env:OPENVIKING_GATEWAY_KEY}',
},
models: { '<model>': {} },
@@ -94,7 +94,7 @@ describe('clientSnippets', () => {
"-H 'X-OpenViking-Session: <conversation-id>'",
)
expect(code('chat', 'python')).toContain(
- 'base_url="https://ov.example.com/v1"',
+ 'base_url="https://ov.example.com/gateway/v1"',
)
})
@@ -106,16 +106,16 @@ describe('clientSnippets', () => {
)!.code,
).providers.openviking
expect(config()).toMatchObject({
- baseUrl: 'https://ov.example.com/v1',
+ baseUrl: 'https://ov.example.com/gateway/v1',
apiKey: '$OPENVIKING_GATEWAY_KEY',
api: 'openai-completions',
})
expect(config('responses')).toMatchObject({
- baseUrl: 'https://ov.example.com/v1',
+ baseUrl: 'https://ov.example.com/gateway/v1',
api: 'openai-responses',
})
expect(config('anthropic')).toMatchObject({
- baseUrl: 'https://ov.example.com',
+ baseUrl: 'https://ov.example.com/gateway',
api: 'anthropic-messages',
})
})
@@ -132,14 +132,16 @@ describe('clientSnippets', () => {
' providers:',
' openviking:',
' api: openai-completions',
- ' baseURL: "https://ov.example.com/v1"',
+ ' baseURL: "https://ov.example.com/gateway/v1"',
' apiKeyEnv: OPENVIKING_GATEWAY_KEY',
' models:',
' - id: "<model>"',
].join('\n'),
)
expect(config('anthropic')).toContain('api: anthropic-messages')
- expect(config('anthropic')).toContain('baseURL: "https://ov.example.com"\n')
+ expect(config('anthropic')).toContain(
+ 'baseURL: "https://ov.example.com/gateway"\n',
+ )
})
it('picks the OpenCode SDK package by protocol, always under /v1', () => {
@@ -153,14 +155,16 @@ describe('clientSnippets', () => {
expect(provider('responses').npm).toBe('@ai-sdk/openai')
expect(provider('anthropic')).toMatchObject({
npm: '@ai-sdk/anthropic',
- options: { baseURL: 'https://ov.example.com/v1' },
+ options: { baseURL: 'https://ov.example.com/gateway/v1' },
})
})
it('maps Ark-addressed clients to the native paths', () => {
- expect(code('ark', 'endpoints')).toContain('https://ov.example.com/api/v3')
expect(code('ark', 'endpoints')).toContain(
- 'https://ov.example.com/api/compatible',
+ 'https://ov.example.com/gateway/api/v3',
+ )
+ expect(code('ark', 'endpoints')).toContain(
+ 'https://ov.example.com/gateway/api/compatible',
)
})
})
diff --git a/web-studio/src/routes/gateway/-lib/enable-gateway.test.ts b/web-studio/src/routes/gateway/-lib/enable-gateway.test.ts
new file mode 100644
index 000000000..34070323d
--- /dev/null
+++ b/web-studio/src/routes/gateway/-lib/enable-gateway.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+ enableGatewayContent,
+ generateManagementKey,
+ isRevisionConflict,
+} from './enable-gateway'
+
+const KEY = 'ovgm_0123456789abcdefghijklmnopqrstuvwxyzABCDEFG'
+
+describe('enableGatewayContent', () => {
+ it('keeps every other ov.conf field and the existing gateway fields', () => {
+ const content = `{
+ "server": { "host": "0.0.0.0", "port": 1933, "root_api_key": "root" },
+ "embedding": {
+ "dense": { "provider": "openai", "model": "text-embedding-3-small", "dimension": 1536 }
+ },
+ "gateway": {
+ "enabled": false,
+ "public_url": "https://ov.example.com/gateway",
+ "log_retention_days": 7
+ },
+ "vlm": { "provider": "openai", "model": "gpt-4o" }
+}
+`
+ const updated = enableGatewayContent(content, KEY)
+ const before = JSON.parse(content)
+ const after = JSON.parse(updated)
+ expect(after).toEqual({
+ ...before,
+ gateway: {
+ ...before.gateway,
+ enabled: true,
+ management_key: KEY,
+ },
+ })
+ // Only the gateway section changes; the rest of the text stays byte for byte.
+ expect(
+ updated.startsWith(content.slice(0, content.indexOf('"gateway"'))),
+ ).toBe(true)
+ expect(updated.endsWith(content.slice(content.indexOf(' "vlm"')))).toBe(
+ true,
+ )
+ expect(updated).toContain(
+ ` "log_retention_days": 7,\n "management_key": "${KEY}"\n },`,
+ )
+ })
+
+ it('adds a gateway section after the last member', () => {
+ const content = '{\n "server": {"port": 1933}\n}\n'
+ expect(enableGatewayContent(content)).toBe(
+ '{\n "server": {"port": 1933},\n "gateway": {\n "enabled": true\n }\n}\n',
+ )
+ })
+
+ it('keeps unquoted environment references and replaces a duplicate gateway in place', () => {
+ const content =
+ '{"embedding": {"dense": {"dimension": $DIM, "api_key": "${OPENAI_KEY}"}}, "gateway": {"enabled": false}, "gateway": {"storage_path": "/data", "enabled": false}}'
+ expect(enableGatewayContent(content)).toBe(
+ '{"embedding": {"dense": {"dimension": $DIM, "api_key": "${OPENAI_KEY}"}}, "gateway": {"enabled": false}, "gateway": {"storage_path": "/data", "enabled": true}}',
+ )
+ })
+
+ it('fills an empty or non-object gateway section', () => {
+ expect(JSON.parse(enableGatewayContent('{"gateway": {}}'))).toEqual({
+ gateway: { enabled: true },
+ })
+ expect(JSON.parse(enableGatewayContent('{"gateway": null}', KEY))).toEqual({
+ gateway: { enabled: true, management_key: KEY },
+ })
+ expect(JSON.parse(enableGatewayContent('{}'))).toEqual({
+ gateway: { enabled: true },
+ })
+ })
+
+ it('keeps a leading byte order mark', () => {
+ expect(enableGatewayContent('\uFEFF{"server": {}}')).toBe(
+ '\uFEFF{"server": {}, "gateway": {"enabled": true}}',
+ )
+ })
+
+ it('refuses content that is not a JSON object', () => {
+ expect(() => enableGatewayContent('[]')).toThrow()
+ })
+})
+
+it('generates a management key in the init format', () => {
+ const key = generateManagementKey()
+ expect(key).toMatch(/^ovgm_[A-Za-z0-9_-]{43}$/)
+ expect(generateManagementKey()).not.toBe(key)
+})
+
+it('recognizes revision conflicts from the configuration API', () => {
+ expect(
+ isRevisionConflict(new Error('ov.conf changed; reload before saving')),
+ ).toBe(true)
+ expect(isRevisionConflict(new Error('ov.conf is read-only'))).toBe(false)
+})
diff --git a/web-studio/src/routes/gateway/-lib/enable-gateway.ts b/web-studio/src/routes/gateway/-lib/enable-gateway.ts
new file mode 100644
index 000000000..21343f1ed
--- /dev/null
+++ b/web-studio/src/routes/gateway/-lib/enable-gateway.ts
@@ -0,0 +1,185 @@
+import { isConfigFileObject } from '#/routes/settings/-lib/config-file-api'
+
+/** A gateway management key in the format `openviking-server init` generates. */
+export function generateManagementKey(): string {
+ const bytes = crypto.getRandomValues(new Uint8Array(32))
+ const base64 = btoa(String.fromCharCode(...bytes))
+ return `ovgm_${base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')}`
+}
+
+type Member = {
+ key: string
+ keyStart: number
+ valueStart: number
+ valueEnd: number
+}
+type Edit = { at: number; end: number; text: string }
+
+function skipWhitespace(text: string, index: number): number {
+ while (index < text.length && /\s/.test(text[index])) index += 1
+ return index
+}
+
+function skipString(text: string, index: number): number {
+ index += 1
+ while (index < text.length && text[index] !== '"')
+ index += text[index] === '\\' ? 2 : 1
+ return index + 1
+}
+
+/**
+ * End of the value that starts at `index`. Unquoted `$VAR` and `${VAR}`
+ * references count as values: the server expands them before parsing.
+ */
+function skipValue(text: string, index: number): number {
+ const first = text[index]
+ if (first === '"') return skipString(text, index)
+ if (first === '{' || first === '[') {
+ let depth = 0
+ while (index < text.length) {
+ const char = text[index]
+ if (char === '"') {
+ index = skipString(text, index)
+ continue
+ }
+ if (char === '{' || char === '[') depth += 1
+ if (char === '}' || char === ']') depth -= 1
+ index += 1
+ if (depth === 0) break
+ }
+ return index
+ }
+ if (text.startsWith('${', index)) return text.indexOf('}', index) + 1
+ while (index < text.length && !/[\s,}\]]/.test(text[index])) index += 1
+ return index
+}
+
+/** Members of the object that opens at `start`, with their positions. */
+function objectMembers(text: string, start: number): Member[] {
+ const members: Member[] = []
+ let index = skipWhitespace(text, start + 1)
+ while (text[index] === '"') {
+ const keyStart = index
+ index = skipString(text, index)
+ const key = JSON.parse(text.slice(keyStart, index)) as string
+ // Skip the colon and the whitespace around it.
+ const valueStart = skipWhitespace(text, skipWhitespace(text, index) + 1)
+ const valueEnd = skipValue(text, valueStart)
+ members.push({ key, keyStart, valueStart, valueEnd })
+ index = skipWhitespace(text, valueEnd)
+ if (text[index] === ',') index = skipWhitespace(text, index + 1)
+ }
+ return members
+}
+
+/** JSON parsers keep the last of duplicate keys, so that one counts. */
+function lastMember(members: Member[], key: string): Member | undefined {
+ return members.filter((member) => member.key === key).at(-1)
+}
+
+/** Indentation of the line that `index` is on. */
+function lineIndent(text: string, index: number): string {
+ const lineStart = text.lastIndexOf('\n', index - 1) + 1
+ return /^[ \t]*/.exec(text.slice(lineStart, index))?.[0] ?? ''
+}
+
+/** A new object literal laid out like a member indented by `indent`. */
+function objectText(fields: Array<[string, string]>, indent: string): string {
+ const inner = indent + (indent || ' ')
+ return `{\n${fields
+ .map(([key, value]) => `${inner}${JSON.stringify(key)}: ${value}`)
+ .join(',\n')}\n${indent}}`
+}
+
+/**
+ * Edits that set `fields` (JSON-encoded values) in the object at `start`.
+ * Existing members change in place; new members follow the last one with
+ * the separator the object already uses.
+ */
+function setFields(
+ text: string,
+ start: number,
+ fields: Array<[string, string]>,
+): Edit[] {
+ const members = objectMembers(text, start)
+ const edits: Edit[] = []
+ const missing: Array<[string, string]> = []
+ for (const [key, value] of fields) {
+ const member = lastMember(members, key)
+ if (member)
+ edits.push({ at: member.valueStart, end: member.valueEnd, text: value })
+ else missing.push([key, value])
+ }
+ if (!missing.length) return edits
+ const last = members.at(-1)
+ if (!last) {
+ const indent = lineIndent(text, start)
+ edits.push({
+ at: start,
+ end: skipValue(text, start),
+ text: objectText(missing, indent),
+ })
+ return edits
+ }
+ // The whitespace between `{` and the first member, e.g. "\n ".
+ const separator = text.slice(start + 1, members[0].keyStart) || ' '
+ edits.push({
+ at: last.valueEnd,
+ end: last.valueEnd,
+ text: missing
+ .map(([key, value]) => `,${separator}${JSON.stringify(key)}: ${value}`)
+ .join(''),
+ })
+ return edits
+}
+
+/**
+ * Turns the gateway on in the text of ov.conf, optionally with a gateway
+ * management key. Only the `gateway` section changes: every other member,
+ * the existing gateway fields, formatting and `$VAR` references stay as they are.
+ */
+export function enableGatewayContent(
+ content: string,
+ managementKey?: string,
+): string {
+ if (!isConfigFileObject(content))
+ throw new Error('ov.conf must contain a JSON object')
+ const fields: Array<[string, string]> = [['enabled', 'true']]
+ if (managementKey)
+ fields.push(['management_key', JSON.stringify(managementKey)])
+
+ // A leading byte order mark stays in place; the scanner starts after it.
+ const root = skipWhitespace(content, content.startsWith('\uFEFF') ? 1 : 0)
+ const gateway = lastMember(objectMembers(content, root), 'gateway')
+ let edits: Edit[]
+ if (gateway && content[gateway.valueStart] === '{') {
+ edits = setFields(content, gateway.valueStart, fields)
+ } else if (gateway) {
+ edits = [
+ {
+ at: gateway.valueStart,
+ end: gateway.valueEnd,
+ text: objectText(fields, lineIndent(content, gateway.keyStart)),
+ },
+ ]
+ } else {
+ const first = objectMembers(content, root).at(0)
+ const section = !first
+ ? objectText(fields, ' ')
+ : content.slice(root + 1, first.keyStart).includes('\n')
+ ? objectText(fields, lineIndent(content, first.keyStart))
+ : // A single-line file gets a single-line section.
+ `{${fields.map(([key, value]) => `${JSON.stringify(key)}: ${value}`).join(', ')}}`
+ edits = setFields(content, root, [['gateway', section]])
+ }
+ let result = content
+ for (const edit of edits.sort((left, right) => right.at - left.at))
+ result = result.slice(0, edit.at) + edit.text + result.slice(edit.end)
+ if (!isConfigFileObject(result)) throw new Error('Could not update ov.conf')
+ return result
+}
+
+/** Whether a save or restart was refused because ov.conf changed meanwhile. */
+export function isRevisionConflict(error: unknown): boolean {
+ return error instanceof Error && /ov\.conf changed/i.test(error.message)
+}
diff --git a/web-studio/src/routes/gateway/-lib/error-toast.ts b/web-studio/src/routes/gateway/-lib/error-toast.ts
new file mode 100644
index 000000000..191627d5d
--- /dev/null
+++ b/web-studio/src/routes/gateway/-lib/error-toast.ts
@@ -0,0 +1,24 @@
+import { toast } from 'sonner'
+
+import { toGatewayError } from './api'
+import { gatewayErrorMessage } from './localize'
+import type { Translate } from './localize'
+import { requestManagementUnlock } from './management-key'
+
+/**
+ * Toasts why a gateway call failed. A write refused for lack of the gateway
+ * management key also offers to enter it.
+ */
+export function toastGatewayError(t: Translate, error: unknown) {
+ const message = gatewayErrorMessage(t, error)
+ if (toGatewayError(error).reason === 'management_key_required') {
+ toast.error(message, {
+ action: {
+ label: t('management.title'),
+ onClick: requestManagementUnlock,
+ },
+ })
+ } else {
+ toast.error(message)
+ }
+}
diff --git a/web-studio/src/routes/gateway/-lib/localize.test.ts b/web-studio/src/routes/gateway/-lib/localize.test.ts
index c8d604b98..0872d9c60 100644
--- a/web-studio/src/routes/gateway/-lib/localize.test.ts
+++ b/web-studio/src/routes/gateway/-lib/localize.test.ts
@@ -63,6 +63,9 @@ describe('enum labels', () => {
expect(openVikingReason(t, 'openviking_RATE_LIMITED')).toBe(
'OpenViking reported error RATE_LIMITED',
)
+ expect(openVikingReason(t, 'openviking_unreachable')).toBe(
+ "OpenViking is unreachable or didn't answer in time",
+ )
expect(openVikingReason(t, 'history_changed')).toBeUndefined()
})
@@ -113,18 +116,34 @@ describe('gatewayErrorMessage', () => {
new GatewayError(
'Revoke or update dependent keys before deleting this object',
409,
+ undefined,
+ 'in_use',
+ { key_count: 3 },
),
),
- ).toBe('Keys still use this. Revoke those keys first.')
+ ).toBe('3 keys still use this.')
expect(
- gatewayErrorMessage(zhT, new GatewayError('root_key_not_allowed', 403)),
- ).toBe('不接受 Root 密钥,请使用本账号下的用户密钥。')
+ gatewayErrorMessage(
+ zhT,
+ new GatewayError(
+ 'root_key_not_allowed',
+ 403,
+ undefined,
+ 'root_key_not_allowed',
+ ),
+ ),
+ ).toBe('不接受 Root API 密钥,请使用本账号下的用户 API 密钥。')
expect(
gatewayErrorMessage(
t,
- new GatewayError('OpenViking key belongs to another account', 403),
+ new GatewayError(
+ 'OpenViking key belongs to another account',
+ 403,
+ undefined,
+ 'other_account',
+ ),
),
- ).toBe('This OpenViking key belongs to another account.')
+ ).toBe('This OpenViking API key belongs to another account.')
})
it('summarizes by category and keeps unexplained messages', () => {
@@ -134,9 +153,14 @@ describe('gatewayErrorMessage', () => {
expect(
gatewayErrorMessage(
t,
- new GatewayError('OpenViking Gateway is not enabled', 503),
+ new GatewayError(
+ 'OpenViking Gateway is not enabled',
+ 503,
+ undefined,
+ 'not_enabled',
+ ),
),
- ).toBe('The OpenViking Gateway is turned off on this server.')
+ ).toBe('The gateway is not enabled on this OpenViking server.')
expect(gatewayErrorMessage(t, new Error('socket hang up'))).toBe(
'socket hang up',
)
diff --git a/web-studio/src/routes/gateway/-lib/localize.ts b/web-studio/src/routes/gateway/-lib/localize.ts
index dc37e3d30..454cc1474 100644
--- a/web-studio/src/routes/gateway/-lib/localize.ts
+++ b/web-studio/src/routes/gateway/-lib/localize.ts
@@ -17,6 +17,7 @@ export const DEGRADATIONS = [
'hidden_tool_history_unavailable',
'hidden_reply_without_anchor',
'capture_parse_failure',
+ 'revocation_check_unavailable',
] as const
function label(t: Translate, group: string, value: string): string {
@@ -54,6 +55,7 @@ export const windowReminderLabel = (t: Translate, reminder: string) =>
const OPENVIKING_REASONS: Record<string, string> = {
openviking_unavailable: 'unavailable',
+ openviking_unreachable: 'unavailable',
openviking_http_401: 'unauthorized',
openviking_version_mismatch: 'versionMismatch',
openviking_identity_missing: 'identityMissing',
@@ -117,34 +119,16 @@ export function degradationInfo(t: Translate, reason: string): DegradationInfo {
}
}
-/** Gateway messages the UI recognizes, mapped to friendlier copy. */
-const ERROR_MESSAGES: Array<[RegExp, string]> = [
- [/^Revoke or update dependent keys/i, 'errors.inUse'],
- [/^Invalid gateway configuration/i, 'errors.invalidSettings'],
- [/^Invalid key configuration/i, 'errors.invalidKeyRequest'],
- [/^Unknown context policy/i, 'errors.unknownProfile'],
- [/^Unknown upstream/i, 'errors.unknownUpstream'],
- [/^Gateway key not found/i, 'errors.keyNotFound'],
- [/^Gateway session not found/i, 'errors.sessionNotFound'],
- [/^Upstream API key is missing/i, 'errors.upstreamKeyMissing'],
- [/subscription OAuth credentials/i, 'errors.subscriptionKey'],
- [
- /^OpenViking key belongs to another account/i,
- 'enums.openviking.otherAccount',
- ],
-]
-
-/**
- * A user-facing message for anything a gateway call threw: known server
- * messages and OpenViking reasons first, then a summary by error category,
- * and the raw message when nothing more specific is known.
- */
+/** Stable API reason codes drive copy; raw detail is a fallback for unknown errors. */
export function gatewayErrorMessage(t: Translate, error: unknown): string {
- const { detail, reason } = toGatewayError(error)
- const known = ERROR_MESSAGES.find(([pattern]) => pattern.test(detail))
- if (known) return t(known[1])
- const openViking = openVikingReason(t, detail)
+ const failure = toGatewayError(error)
+ const { detail, reason } = failure
+ if (reason === 'other_account') return t('enums.openviking.otherAccount')
+ const openViking = openVikingReason(t, reason)
if (openViking) return openViking
if (reason === 'other') return detail || t('errors.reasons.other')
- return t(`errors.reasons.${reason}`)
+ return t(`errors.reasons.${reason}`, {
+ count: failure.keyCount,
+ defaultValue: detail || t('errors.reasons.other'),
+ })
}
diff --git a/web-studio/src/routes/gateway/-lib/management-key.ts b/web-studio/src/routes/gateway/-lib/management-key.ts
new file mode 100644
index 000000000..68c18629d
--- /dev/null
+++ b/web-studio/src/routes/gateway/-lib/management-key.ts
@@ -0,0 +1,56 @@
+import { useSyncExternalStore } from 'react'
+import i18next from 'i18next'
+import { toast } from 'sonner'
+
+const EVENT = 'gateway-management-key-changed'
+const storageKey = (baseUrl: string) =>
+ `gateway-management-key:${baseUrl.replace(/\/+$/, '')}`
+
+export function getManagementKey(baseUrl: string): string {
+ try {
+ return sessionStorage.getItem(storageKey(baseUrl)) ?? ''
+ } catch {
+ return ''
+ }
+}
+
+export function setManagementKey(baseUrl: string, key: string) {
+ try {
+ sessionStorage.setItem(storageKey(baseUrl), key)
+ } catch {
+ /* Storage may be unavailable. */
+ }
+ window.dispatchEvent(new Event(EVENT))
+}
+
+export function lockManagementKey(baseUrl: string, expired = false) {
+ const hadKey = Boolean(getManagementKey(baseUrl))
+ try {
+ sessionStorage.removeItem(storageKey(baseUrl))
+ } catch {
+ /* Storage may be unavailable. */
+ }
+ window.dispatchEvent(new Event(EVENT))
+ if (expired && hadKey)
+ toast.error(i18next.t('management.expired', { ns: 'gateway' }))
+}
+
+function subscribe(callback: () => void) {
+ window.addEventListener(EVENT, callback)
+ return () => window.removeEventListener(EVENT, callback)
+}
+
+export function useManagementKey(baseUrl: string) {
+ return useSyncExternalStore(
+ subscribe,
+ () => getManagementKey(baseUrl),
+ () => '',
+ )
+}
+
+/** Opens the unlock dialog that the gateway layout mounts. */
+export const MANAGEMENT_UNLOCK_EVENT = 'gateway-management-unlock'
+
+export function requestManagementUnlock() {
+ window.dispatchEvent(new Event(MANAGEMENT_UNLOCK_EVENT))
+}
diff --git a/web-studio/src/routes/gateway/-lib/profile-schema.ts b/web-studio/src/routes/gateway/-lib/profile-schema.ts
index 4fded2013..77fa251b4 100644
--- a/web-studio/src/routes/gateway/-lib/profile-schema.ts
+++ b/web-studio/src/routes/gateway/-lib/profile-schema.ts
@@ -86,7 +86,12 @@ export const PROFILE_LIMITS: Record<NumericField, NumberRule> = {
unlimited: true,
unit: 'seconds',
},
- tool_total_tokens: { min: 1024, integer: true, unlimited: true, unit: 'tokens' },
+ tool_total_tokens: {
+ min: 1024,
+ integer: true,
+ unlimited: true,
+ unit: 'tokens',
+ },
}
/** Per-category entry limit used by "Limit by category". */
diff --git a/web-studio/src/routes/gateway/-lib/upstream-schema.test.ts b/web-studio/src/routes/gateway/-lib/upstream-schema.test.ts
index 20a4002cd..f38d07c27 100644
--- a/web-studio/src/routes/gateway/-lib/upstream-schema.test.ts
+++ b/web-studio/src/routes/gateway/-lib/upstream-schema.test.ts
@@ -1,12 +1,15 @@
+import urlVectors from '../../../../../tests/fixtures/gateway_upstream_urls.json'
import { describe, expect, it } from 'vitest'
-import type { Upstream, UpstreamInput, Vendor } from './api'
+import type { Protocol, Upstream, UpstreamInput, Vendor } from './api'
import {
PROTOCOLS,
UPSTREAM_DEFAULTS,
VENDORS,
VENDOR_PROTOCOLS,
baseUrlAfterSwitch,
+ baseUrlChanged,
+ baseUrlCorrection,
defaultBaseUrl,
endpointPreview,
isValidBaseUrl,
@@ -117,8 +120,8 @@ describe('default base URLs', () => {
['deepseek', 'chat', 'https://api.deepseek.com'],
['deepseek', 'responses', 'https://api.deepseek.com'],
['deepseek', 'anthropic', 'https://api.deepseek.com/anthropic'],
- ['ark', 'anthropic', 'https://ark.cn-beijing.volces.com'],
- ['byteplus', 'responses', 'https://ark.ap-southeast.bytepluses.com'],
+ ['ark', 'anthropic', 'https://ark.cn-beijing.volces.com/api/compatible'],
+ ['byteplus', 'responses', 'https://ark.ap-southeast.bytepluses.com/api/v3'],
['newcomer', 'chat', ''],
] as const)('%s + %s → %s', (vendor, protocol, url) => {
expect(defaultBaseUrl(vendor as Vendor, protocol)).toBe(url)
@@ -172,64 +175,12 @@ describe('base URLs', () => {
expect(isValidBaseUrl(url)).toBe(valid)
})
- it.each([
- [
- 'https://api.openai.com/v1',
- 'generic',
- '/v1/chat/completions',
- 'https://api.openai.com/v1/chat/completions',
- ],
- [
- 'https://api.anthropic.com/',
- 'anthropic',
- '/v1/messages',
- 'https://api.anthropic.com/v1/messages',
- ],
- [
- 'https://host/api/paas/v4',
- 'generic',
- '/v1/chat/completions',
- 'https://host/api/paas/v4/v1/chat/completions',
- ],
- [
- 'https://ark.cn-beijing.volces.com',
- 'ark',
- '/v1/messages',
- 'https://ark.cn-beijing.volces.com/api/compatible/v1/messages',
- ],
- [
- 'https://ark.cn-beijing.volces.com',
- 'ark',
- '/v1/responses',
- 'https://ark.cn-beijing.volces.com/api/v3/responses',
- ],
- [
- 'https://ark.cn-beijing.volces.com/api/v3',
- 'ark',
- '/v1/chat/completions',
- 'https://ark.cn-beijing.volces.com/api/v3/chat/completions',
- ],
- [
- 'https://ark.cn-beijing.volces.com/api/v3',
- 'ark',
- '/v1/messages',
- 'https://ark.cn-beijing.volces.com/api/v3/api/compatible/v1/messages',
- ],
- [
- 'https://ark.ap-southeast.bytepluses.com',
- 'byteplus',
- '/v1/messages',
- 'https://ark.ap-southeast.bytepluses.com/api/compatible/v1/messages',
- ],
- [
- 'https://ark.ap-southeast.bytepluses.com/api/v3',
- 'byteplus',
- '/v1/responses',
- 'https://ark.ap-southeast.bytepluses.com/api/v3/responses',
- ],
- ] as const)('%s (%s) + %s', (base, vendor, path, expected) => {
- expect(upstreamUrl(base, vendor, path)).toBe(expected)
- })
+ it.each(urlVectors)(
+ 'joins the shared URL vector: $name',
+ ({ base_url, protocol, path, expected }) => {
+ expect(upstreamUrl(base_url, protocol as Protocol, path)).toBe(expected)
+ },
+ )
it('previews the protocol endpoint once the URL is valid', () => {
expect(endpointPreview(input({ protocol: 'responses' }))).toBe(
@@ -248,7 +199,16 @@ describe('validateUpstream', () => {
expect(validateUpstream(input({ api_key: '' })).api_key?.key).toBe(
'validation.apiKeyRequired',
)
- expect(validateUpstream(input({ api_key: '' }), stored)).toEqual({})
+ expect(
+ validateUpstream(
+ input({ api_key: '', base_url: stored.base_url }),
+ stored,
+ ),
+ ).toEqual({})
+ // A new address drops the stored key, so a new one is required.
+ expect(validateUpstream(input({ api_key: '' }), stored).api_key?.key).toBe(
+ 'validation.apiKeyRequired',
+ )
expect(
validateUpstream(input({ api_key: '', auth_mode: 'passthrough' })),
).toEqual({})
@@ -259,8 +219,16 @@ describe('validateUpstream', () => {
it('checks headers, aliases and context windows', () => {
const header = (headers: Record<string, string>) =>
- validateUpstream(input({ headers }), stored).headers
+ validateUpstream(input({ headers, base_url: stored.base_url }), stored)
+ .headers
expect(header({ 'OpenAI-Organization': '' })).toBeUndefined()
+ // Stored values are dropped with a new address.
+ expect(
+ validateUpstream(
+ input({ headers: { 'OpenAI-Organization': '' } }),
+ stored,
+ ).headers?.key,
+ ).toBe('validation.headerValue')
expect(header({ 'X-New': '' })).toEqual({
key: 'validation.headerValue',
values: { name: 'X-New' },
@@ -287,7 +255,13 @@ describe('validateUpstream', () => {
values: { vendor: 'openai', protocol: 'anthropic' },
})
expect(
- validateUpstream(input({ vendor: 'deepseek', protocol: 'anthropic' })),
+ validateUpstream(
+ input({
+ vendor: 'deepseek',
+ protocol: 'anthropic',
+ base_url: 'https://api.deepseek.com/anthropic',
+ }),
+ ),
).toEqual({})
})
@@ -338,3 +312,49 @@ describe('replaysReasoning', () => {
expect(replayReasoningSetting('generic', true)).toBe(true)
})
})
+
+describe('URL corrections and changed secrets', () => {
+ it('preserves custom hosts when adding a provider path', () => {
+ expect(
+ baseUrlCorrection(
+ input({ vendor: 'openai', base_url: 'https://proxy.example/' }),
+ ),
+ ).toEqual({ reason: 'missingPath', url: 'https://proxy.example/v1' })
+ expect(
+ baseUrlCorrection(
+ input({ vendor: 'ark', base_url: 'https://ark.example' }),
+ ),
+ ).toEqual({ reason: 'missingPath', url: 'https://ark.example/api/v3' })
+ expect(
+ baseUrlCorrection(
+ input({ vendor: 'generic', base_url: 'https://proxy.example' }),
+ ),
+ ).toBeUndefined()
+ })
+ it('rejects Anthropic bases with /v1 and suggests removing it', () => {
+ const draft = input({
+ protocol: 'anthropic',
+ base_url: 'https://proxy.example/anthropic/v1/',
+ })
+ expect(baseUrlCorrection(draft)).toEqual({
+ reason: 'anthropicVersion',
+ url: 'https://proxy.example/anthropic',
+ })
+ expect(validateUpstream(draft).base_url?.key).toBe(
+ 'validation.anthropicBaseUrl',
+ )
+ })
+ it('recognizes address changes but ignores trailing slashes', () => {
+ expect(baseUrlChanged({ base_url: stored.base_url + '/' }, stored)).toBe(
+ false,
+ )
+ expect(baseUrlChanged({ base_url: 'https://other.example' }, stored)).toBe(
+ true,
+ )
+ })
+ it('reads redacted upstream details without header names', () => {
+ expect(
+ toUpstreamInput({ ...stored, header_names: undefined }).headers,
+ ).toEqual({})
+ })
+})
diff --git a/web-studio/src/routes/gateway/-lib/upstream-schema.ts b/web-studio/src/routes/gateway/-lib/upstream-schema.ts
index 7cbda91f1..eeb8d38ad 100644
--- a/web-studio/src/routes/gateway/-lib/upstream-schema.ts
+++ b/web-studio/src/routes/gateway/-lib/upstream-schema.ts
@@ -84,8 +84,8 @@ const DEFAULT_BASE_URLS: Partial<Record<Vendor, string>> = {
anthropic: 'https://api.anthropic.com',
openai: 'https://api.openai.com/v1',
deepseek: 'https://api.deepseek.com',
- ark: 'https://ark.cn-beijing.volces.com',
- byteplus: 'https://ark.ap-southeast.bytepluses.com',
+ ark: 'https://ark.cn-beijing.volces.com/api/v3',
+ byteplus: 'https://ark.ap-southeast.bytepluses.com/api/v3',
}
/**
@@ -120,6 +120,9 @@ export function defaultBaseUrl(vendor: Vendor, protocol: Protocol): string {
if (vendor === 'deepseek' && protocol === 'anthropic') {
return 'https://api.deepseek.com/anthropic'
}
+ if (ARK_VENDORS.includes(vendor) && protocol === 'anthropic') {
+ return DEFAULT_BASE_URLS[vendor]!.replace('/api/v3', '/api/compatible')
+ }
const known: Partial<Record<string, string>> = DEFAULT_BASE_URLS
return known[vendor] ?? ''
}
@@ -183,7 +186,7 @@ export function toUpstreamInput(upstream: Upstream): UpstreamInput {
...upstream,
api_key: '',
headers: Object.fromEntries(
- upstream.header_names.map((name) => [name, '']),
+ (upstream.header_names ?? []).map((name) => [name, '']),
),
}
for (const field of ['id', 'revision', 'has_api_key', 'header_names']) {
@@ -218,30 +221,49 @@ export function isValidBaseUrl(value: string): boolean {
)
}
-/**
- * Where the gateway sends a request for `path` (a `/v1/…` client path),
- * following its rules: a base ending in `/v1` does not get a second `/v1`;
- * Ark and ModelArk map Messages to `/api/compatible/v1` and everything else
- * to `/api/v3`.
- */
+/** SDK URL joining: OpenAI paths omit /v1; Anthropic paths retain it. */
export function upstreamUrl(
baseUrl: string,
- vendor: Vendor,
+ protocol: Protocol,
path: string,
): string {
const base = baseUrl.trim().replace(/\/+$/, '')
- const basePath = new URL(base).pathname.replace(/\/+$/, '')
- if (ARK_VENDORS.includes(vendor)) {
- const suffix = path.replace(/^\/v1/, '')
- const prefix = path.startsWith('/v1/messages')
- ? '/api/compatible/v1'
- : '/api/v3'
- return basePath.endsWith(prefix) ? base + suffix : base + prefix + suffix
+ return (
+ base + (protocol === 'anthropic' ? path : path.replace(/^\/v1(?=\/)/, ''))
+ )
+}
+
+/** A likely URL mistake that the editor can fix without replacing a custom host. */
+export function baseUrlCorrection(
+ upstream: Pick<UpstreamInput, 'base_url' | 'vendor' | 'protocol'>,
+): { reason: 'anthropicVersion' | 'missingPath'; url: string } | undefined {
+ if (!isValidBaseUrl(upstream.base_url)) return undefined
+ const base = upstream.base_url.trim().replace(/\/+$/, '')
+ const path = new URL(base).pathname.replace(/\/+$/, '')
+ if (upstream.protocol === 'anthropic' && path.endsWith('/v1')) {
+ return { reason: 'anthropicVersion', url: base.slice(0, -3) }
}
- if (basePath.endsWith('/v1') && path.startsWith('/v1/')) {
- return base + path.slice(3)
+ if (
+ upstream.protocol !== 'anthropic' &&
+ !path &&
+ ['openai', 'ark', 'byteplus'].includes(upstream.vendor)
+ ) {
+ return {
+ reason: 'missingPath',
+ url: base + (upstream.vendor === 'openai' ? '/v1' : '/api/v3'),
+ }
}
- return base + path
+}
+
+/** Matches the backend's normalization when deciding whether stored secrets survive. */
+export function baseUrlChanged(
+ input: Pick<UpstreamInput, 'base_url'>,
+ stored?: Pick<Upstream, 'base_url'>,
+): boolean {
+ const normalize = (url: string) => url.trim().replace(/\/+$/, '')
+ return Boolean(
+ stored && normalize(input.base_url) !== normalize(stored.base_url),
+ )
}
/**
@@ -253,11 +275,7 @@ export function endpointPreview(
protocol: Protocol = upstream.protocol,
): string {
if (!isValidBaseUrl(upstream.base_url)) return ''
- return upstreamUrl(
- upstream.base_url,
- upstream.vendor,
- PROTOCOL_PATHS[protocol],
- )
+ return upstreamUrl(upstream.base_url, protocol, PROTOCOL_PATHS[protocol])
}
/**
@@ -286,14 +304,25 @@ export function validateUpstream(
? undefined
: { key: 'validation.baseUrl' }),
)
+ if (baseUrlCorrection(input)?.reason === 'anthropicVersion') {
+ collect(errors, 'base_url', {
+ key: 'validation.anthropicBaseUrl',
+ })
+ }
const apiKey = input.api_key.trim()
if (apiKey.startsWith('sk-ant-oat')) {
collect(errors, 'api_key', { key: 'validation.subscriptionKey' })
}
- if (input.auth_mode === 'managed' && !apiKey && !stored?.has_api_key) {
+ // A new address drops the stored API key and header values.
+ const addressChanged = baseUrlChanged(input, stored)
+ if (
+ input.auth_mode === 'managed' &&
+ !apiKey &&
+ (addressChanged || !stored?.has_api_key)
+ ) {
collect(errors, 'api_key', { key: 'validation.apiKeyRequired' })
}
- const storedHeaders = stored?.header_names ?? []
+ const storedHeaders = addressChanged ? [] : (stored?.header_names ?? [])
for (const [name, value] of Object.entries(input.headers)) {
const values = { name }
if (!name.trim() || /[\r\n]/.test(name + value)) {
diff --git a/web-studio/src/routes/gateway/-lib/use-gateway.test.tsx b/web-studio/src/routes/gateway/-lib/use-gateway.test.tsx
index 7c33aed52..7e9bc8b41 100644
--- a/web-studio/src/routes/gateway/-lib/use-gateway.test.tsx
+++ b/web-studio/src/routes/gateway/-lib/use-gateway.test.tsx
@@ -1,10 +1,11 @@
// @vitest-environment jsdom
import type * as React from 'react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { cleanup, renderHook, waitFor } from '@testing-library/react'
+import { act, cleanup, renderHook, waitFor } from '@testing-library/react'
import { afterEach, beforeEach, expect, it, vi } from 'vitest'
import type * as Api from './api'
+import { setManagementKey, lockManagementKey } from './management-key'
import {
gatewayQueryKey,
gatewayScope,
@@ -14,8 +15,14 @@ import {
useUpstreams,
} from './use-gateway'
-const state = vi.hoisted(() => ({ role: 'admin' }))
+const state = vi.hoisted(() => ({
+ role: 'admin',
+ serverMode: 'api_key',
+ apiKey: 'data-key',
+ adminApiKey: 'admin-key',
+}))
const api = vi.hoisted(() => ({
+ getAccess: vi.fn(),
listUpstreams: vi.fn(),
listLogs: vi.fn(),
listTools: vi.fn(),
@@ -27,16 +34,17 @@ vi.mock('#/hooks/use-app-connection', () => ({
baseUrl: 'https://ov.example.com',
accountId: 'acme',
userId: 'admin',
- apiKey: 'data-key',
- adminApiKey: 'admin-key',
+ apiKey: state.apiKey,
+ adminApiKey: state.adminApiKey,
},
connectionRole: state.role,
isConnectionRoleLoading: false,
- serverMode: 'api_key',
+ serverMode: state.serverMode,
}),
}))
vi.mock('./api', async (importOriginal) => ({
...(await importOriginal<typeof Api>()),
+ getAccess: api.getAccess,
listUpstreams: api.listUpstreams,
listLogs: api.listLogs,
listTools: api.listTools,
@@ -48,6 +56,20 @@ const wrapper = ({ children }: { children: React.ReactNode }) => (
)
beforeEach(() => {
+ sessionStorage.clear()
+ state.serverMode = 'api_key'
+ state.apiKey = 'data-key'
+ state.adminApiKey = 'admin-key'
+ api.getAccess.mockResolvedValue({
+ managed: false,
+ can_write_objects: true,
+ can_import_vlm: true,
+ can_issue_for_others: true,
+ role: 'admin',
+ account_id: 'acme',
+ user_id: 'admin',
+ warnings: [],
+ })
client = new QueryClient({ defaultOptions: { queries: { retry: false } } })
state.role = 'admin'
api.listUpstreams.mockReset()
@@ -76,19 +98,21 @@ it('manages with the admin key for account administrators', () => {
accountId: 'acme',
userId: 'admin',
apiKey: 'admin-key',
+ managementKey: '',
})
})
-it('does not load anything for regular users', () => {
+it('loads account objects for regular users', async () => {
+ api.listUpstreams.mockResolvedValue([])
+ api.listTools.mockResolvedValue([])
state.role = 'user'
const { result } = renderHook(
() => ({ upstreams: useUpstreams(), tools: useTools() }),
{ wrapper },
)
- expect(result.current.upstreams.fetchStatus).toBe('idle')
- expect(result.current.tools.fetchStatus).toBe('idle')
- expect(api.listUpstreams).not.toHaveBeenCalled()
- expect(api.listTools).not.toHaveBeenCalled()
+ await waitFor(() => expect(result.current.upstreams.isSuccess).toBe(true))
+ expect(api.listUpstreams).toHaveBeenCalled()
+ expect(api.listTools).toHaveBeenCalled()
})
it('scopes and refreshes the tools catalog through the admin connection', async () => {
@@ -139,3 +163,69 @@ it('loads resources with the admin connection and invalidates by resource', asyn
await result.current.gateway.invalidate()
expect(api.listLogs).toHaveBeenCalledTimes(2)
})
+
+it('uses the ordinary OV key without an administrator key', () => {
+ state.adminApiKey = ''
+ state.role = 'user'
+ const { result } = renderHook(() => useGateway(), { wrapper })
+ expect(result.current.allowed).toBe(true)
+ expect(result.current.connection.apiKey).toBe('data-key')
+})
+it.each(['dev', 'trusted'])(
+ 'asks /access in %s mode without either credential',
+ (serverMode) => {
+ state.serverMode = serverMode
+ state.adminApiKey = ''
+ state.apiKey = ''
+ const { result } = renderHook(() => useGateway(), { wrapper })
+ expect(result.current.allowed).toBe(true)
+ },
+)
+it('partitions caches by the management key without storing the secret in query keys', () => {
+ const locked = gatewayScope('http://ov', 'default', 'ov-key')
+ const unlocked = gatewayScope('http://ov', 'default', 'ov-key', 'ovgm-secret')
+ expect(locked).not.toEqual(unlocked)
+ expect(JSON.stringify(unlocked)).not.toContain('ovgm-secret')
+})
+
+it('reloads gateway data in its own scope when the key is unlocked or locked', async () => {
+ const baseUrl = 'https://ov.example.com'
+ api.getAccess.mockImplementation(
+ async (connection: Api.GatewayConnection) => ({
+ managed: true,
+ can_write_objects: Boolean(connection.managementKey),
+ can_issue_for_others: false,
+ }),
+ )
+ api.listUpstreams.mockImplementation(
+ async (connection: Api.GatewayConnection) => [
+ {
+ id: 'u',
+ ...(connection.managementKey ? { header_names: ['X-Secret'] } : {}),
+ },
+ ],
+ )
+ const { result } = renderHook(
+ () => ({ gateway: useGateway(), upstreams: useUpstreams() }),
+ { wrapper },
+ )
+ await waitFor(() => expect(result.current.gateway.access).toBeTruthy())
+ expect(result.current.gateway.readOnly).toBe(true)
+ expect(result.current.gateway.canIssueForOthers).toBe(false)
+ const lockedScope = result.current.gateway.scope
+ act(() => setManagementKey(baseUrl, 'ovgm-test-key'))
+ await waitFor(() => expect(result.current.gateway.readOnly).toBe(false))
+ await waitFor(() =>
+ expect(result.current.upstreams.data?.[0].header_names).toEqual([
+ 'X-Secret',
+ ]),
+ )
+ expect(
+ client.getQueryData<Api.GatewayAccess>(
+ gatewayQueryKey(lockedScope, 'access'),
+ )?.can_write_objects,
+ ).toBe(false)
+ act(() => lockManagementKey(baseUrl))
+ await waitFor(() => expect(result.current.gateway.readOnly).toBe(true))
+ expect(result.current.upstreams.data?.[0].header_names).toBeUndefined()
+})
diff --git a/web-studio/src/routes/gateway/-lib/use-gateway.ts b/web-studio/src/routes/gateway/-lib/use-gateway.ts
index a042f55ca..1f494aeaa 100644
--- a/web-studio/src/routes/gateway/-lib/use-gateway.ts
+++ b/web-studio/src/routes/gateway/-lib/use-gateway.ts
@@ -3,11 +3,11 @@ import { useQuery, useQueryClient } from '@tanstack/react-query'
import type { UseQueryOptions } from '@tanstack/react-query'
import { useAppConnection } from '#/hooks/use-app-connection'
-import type { AdminConnection } from '#/lib/admin'
-import { resolveStudioManagementCapabilities } from '#/lib/studio-permissions'
+import { useManagementKey } from './management-key'
import {
getConnectionInfo,
+ getAccess,
getOverview,
listKeyUsers,
listKeys,
@@ -18,6 +18,8 @@ import {
} from './api'
import type {
ConnectionInfo,
+ GatewayConnection,
+ GatewayAccess,
GatewayError,
GatewayKey,
GatewayTool,
@@ -30,6 +32,7 @@ import type {
/** Cached gateway data, invalidated per resource after a change. */
export type GatewayResource =
+ | 'access'
| 'connection'
| 'overview'
| 'logs'
@@ -39,8 +42,8 @@ export type GatewayResource =
| 'keys'
| 'users'
-/** Whose gateway data a query holds: server, account and a hash of the admin key. */
-export type GatewayScope = readonly [string, string, string]
+/** Cache isolation by server, account and fingerprints of both credentials. */
+export type GatewayScope = readonly [string, string, string, string]
function hashSecret(value: string): string {
let hash = 0x811c9dc5
@@ -55,8 +58,14 @@ export function gatewayScope(
baseUrl: string,
accountId: string,
adminApiKey: string,
+ managementKey = '',
): GatewayScope {
- return [baseUrl, accountId, adminApiKey ? hashSecret(adminApiKey) : 'none']
+ return [
+ baseUrl,
+ accountId,
+ adminApiKey ? hashSecret(adminApiKey) : 'none',
+ managementKey ? hashSecret(managementKey) : 'none',
+ ]
}
/** Query key `['gateway', scope, resource, ...params]`. */
@@ -72,26 +81,21 @@ export function gatewayQueryKey(
/**
* Access and connection for gateway management. `connection` uses the
- * account admin key; `invalidate()` refreshes the listed resources, or all
+ * configured OpenViking credential; `invalidate()` refreshes the listed resources, or all
* gateway data when called without arguments.
*/
-export function useGateway() {
- const { connection, connectionRole, isConnectionRoleLoading, serverMode } =
- useAppConnection()
- const { baseUrl, accountId, userId, adminApiKey } = connection
- const { canManageUsers } = resolveStudioManagementCapabilities({
- hasControlCredential: Boolean(adminApiKey.trim()),
- isRoleLoading: isConnectionRoleLoading,
- role: connectionRole,
- serverMode,
- })
- const admin = useMemo<AdminConnection>(
- () => ({ baseUrl, accountId, userId, apiKey: adminApiKey }),
- [baseUrl, accountId, userId, adminApiKey],
+function useGatewayConnection() {
+ const { connection, isConnectionRoleLoading, serverMode } = useAppConnection()
+ const { baseUrl, accountId, userId } = connection
+ const apiKey = connection.adminApiKey || connection.apiKey
+ const managementKey = useManagementKey(baseUrl)
+ const admin = useMemo<GatewayConnection>(
+ () => ({ baseUrl, accountId, userId, apiKey, managementKey }),
+ [baseUrl, accountId, userId, apiKey, managementKey],
)
const scope = useMemo(
- () => gatewayScope(baseUrl, accountId, adminApiKey),
- [baseUrl, accountId, adminApiKey],
+ () => gatewayScope(baseUrl, accountId, apiKey, managementKey),
+ [baseUrl, accountId, apiKey, managementKey],
)
const queryClient = useQueryClient()
const invalidate = useCallback(
@@ -106,14 +110,20 @@ export function useGateway() {
[queryClient, scope],
)
return {
- allowed: canManageUsers,
- /** OpenViking runs in development mode, where Studio can't manage the gateway. */
+ /**
+ * Dev mode needs no credential; trusted mode lets /access explain that
+ * the gateway doesn't support it.
+ */
+ allowed:
+ serverMode === 'dev' ||
+ serverMode === 'trusted' ||
+ Boolean(apiKey.trim()),
+ /** Local development authenticates as default/default without a credential. */
devMode: serverMode === 'dev',
isRoleLoading: isConnectionRoleLoading,
- /** Role of the admin key; `admin` or `root` whenever `allowed`. */
- role: connectionRole,
connection: admin,
scope,
+ managementKey,
invalidate,
}
}
@@ -127,10 +137,10 @@ export type GatewayQueryOptions<T> = Omit<
function useGatewayQuery<T>(
resource: GatewayResource,
params: unknown[],
- load: (connection: AdminConnection) => Promise<T>,
+ load: (connection: GatewayConnection) => Promise<T>,
options: GatewayQueryOptions<T> = {},
) {
- const { allowed, connection, scope } = useGateway()
+ const { allowed, connection, scope } = useGatewayConnection()
return useQuery<T, GatewayError>({
...options,
queryKey: gatewayQueryKey(scope, resource, ...params),
@@ -139,6 +149,29 @@ function useGatewayQuery<T>(
})
}
+export const useAccess = (options?: GatewayQueryOptions<GatewayAccess>) =>
+ useGatewayQuery('access', [], getAccess, {
+ retry: false,
+ retryOnMount: false,
+ staleTime: 30_000,
+ ...options,
+ })
+
+/** Connection plus the permissions /access grants; pages read only these. */
+export function useGateway() {
+ const gateway = useGatewayConnection()
+ const accessQuery = useAccess()
+ const access = accessQuery.data
+ return {
+ ...gateway,
+ access,
+ accessQuery,
+ /** Upstreams and profiles can be viewed and tested, not changed. */
+ readOnly: !access?.can_write_objects,
+ canIssueForOthers: Boolean(access?.can_issue_for_others),
+ }
+}
+
/** Gateway address for clients (also tells whether the gateway is reachable). */
export const useConnectionInfo = (
options?: GatewayQueryOptions<ConnectionInfo>,
diff --git a/web-studio/src/routes/gateway/route.test.tsx b/web-studio/src/routes/gateway/route.test.tsx
index 50aa7ea12..eb0ae48ab 100644
--- a/web-studio/src/routes/gateway/route.test.tsx
+++ b/web-studio/src/routes/gateway/route.test.tsx
@@ -22,8 +22,12 @@ const state = vi.hoisted(() => ({
role: 'admin',
roleLoading: false,
serverMode: 'api_key',
+ credential: 'admin-key',
+}))
+const api = vi.hoisted(() => ({
+ getConnectionInfo: vi.fn(),
+ getAccess: vi.fn(),
}))
-const api = vi.hoisted(() => ({ getConnectionInfo: vi.fn() }))
vi.mock('#/hooks/use-app-connection', () => ({
useAppConnection: () => ({
@@ -32,7 +36,7 @@ vi.mock('#/hooks/use-app-connection', () => ({
accountId: 'acme',
userId: 'admin',
apiKey: '',
- adminApiKey: 'admin-key',
+ adminApiKey: state.credential,
},
connectionRole: state.role,
isConnectionRoleLoading: state.roleLoading,
@@ -49,6 +53,7 @@ vi.mock('react-i18next', async (importOriginal) => ({
vi.mock('./-lib/api', async (importOriginal) => ({
...(await importOriginal<typeof Api>()),
getConnectionInfo: api.getConnectionInfo,
+ getAccess: api.getAccess,
}))
describe('routes', () => {
@@ -87,7 +92,22 @@ describe('layout gates', () => {
state.role = 'admin'
state.roleLoading = false
state.serverMode = 'api_key'
- api.getConnectionInfo.mockReset()
+ api.getConnectionInfo.mockResolvedValue({
+ base_url: 'https://gateway.example.com',
+ public_url_configured: true,
+ })
+ state.credential = 'admin-key'
+ api.getAccess.mockReset()
+ api.getAccess.mockResolvedValue({
+ managed: false,
+ can_write_objects: true,
+ can_import_vlm: true,
+ can_issue_for_others: true,
+ role: 'admin',
+ account_id: 'acme',
+ user_id: 'admin',
+ warnings: [],
+ })
})
afterEach(cleanup)
@@ -114,53 +134,81 @@ describe('layout gates', () => {
)
}
- it('asks for an account administrator key', async () => {
+ it('asks for an OpenViking key if none is configured', async () => {
state.role = 'user'
+ state.credential = ''
renderLayout()
expect(await screen.findByText('access.title')).toBeTruthy()
expect(screen.queryByText('tabs.overview')).toBeNull()
expect(api.getConnectionInfo).not.toHaveBeenCalled()
})
- it('explains how to turn the gateway on', async () => {
- api.getConnectionInfo.mockRejectedValue(
- new GatewayError('OpenViking Gateway is not enabled', 503),
+ it('explains how to turn the gateway on in development mode', async () => {
+ state.serverMode = 'dev'
+ state.role = 'root'
+ state.credential = ''
+ api.getAccess.mockRejectedValue(
+ new GatewayError(
+ 'OpenViking Gateway is not enabled',
+ 404,
+ undefined,
+ 'not_enabled',
+ ),
)
renderLayout()
expect(await screen.findByText('unavailable.notEnabled.title')).toBeTruthy()
- expect(screen.getByText(/"enabled": true/)).toBeTruthy()
- expect(screen.getByText('unavailable.docs')).toBeTruthy()
+ expect(screen.getByText(/"enabled":true/)).toBeTruthy()
expect(screen.queryByText('tabs.overview')).toBeNull()
})
- it('explains development mode instead of asking for a key', async () => {
+ it('asks an account admin to contact the deployer', async () => {
+ api.getAccess.mockRejectedValue(
+ new GatewayError('Not Found', 404, undefined, 'not_enabled'),
+ )
+ renderLayout()
+ expect(await screen.findByText('unavailable.contact')).toBeTruthy()
+ expect(screen.queryByText(/"enabled":true/)).toBeNull()
+ })
+
+ it('shows gateway pages in development mode without credentials', async () => {
state.serverMode = 'dev'
state.role = 'root'
+ state.credential = ''
renderLayout()
- expect(await screen.findByText('unavailable.devMode.title')).toBeTruthy()
- expect(screen.getByText(/"auth_mode": "api_key"/)).toBeTruthy()
+ expect(await screen.findByText('tabs.overview')).toBeTruthy()
expect(screen.queryByText('access.title')).toBeNull()
- expect(api.getConnectionInfo).not.toHaveBeenCalled()
})
it.each([
[
- new GatewayError('Invalid gateway management credential', 401),
- 'unavailable.tokenMismatch.title',
+ new GatewayError('trusted', 409, undefined, 'trusted_mode_unsupported'),
+ 'unavailable.trusted.title',
],
[
- new GatewayError('Not Found', 404, undefined, 'unsupported'),
- 'unavailable.unsupported.title',
+ new GatewayError('Not Found', 404, undefined, 'not_enabled'),
+ 'unavailable.notEnabled.title',
],
])('shows a setup card for %s', async (error, title) => {
- api.getConnectionInfo.mockRejectedValue(error)
+ api.getAccess.mockRejectedValue(error)
renderLayout()
expect(await screen.findByText(title)).toBeTruthy()
expect(screen.getByText('actions.retry')).toBeTruthy()
})
+ it('shows an unreachable OpenViking on an embedded server as a plain failure', async () => {
+ api.getAccess.mockRejectedValue(
+ new GatewayError('unreachable', 503, undefined, 'openviking_unreachable'),
+ )
+ renderLayout()
+ expect(await screen.findByText('unavailable.failed.title')).toBeTruthy()
+ expect(
+ screen.queryByText('unavailable.openvikingUnreachable.title'),
+ ).toBeNull()
+ expect(screen.getByText('actions.retry')).toBeTruthy()
+ })
+
it('shows other failures as an error with retry', async () => {
- api.getConnectionInfo.mockRejectedValue(new GatewayError('Network Error'))
+ api.getAccess.mockRejectedValue(new GatewayError('Network Error'))
renderLayout()
expect(await screen.findByText('unavailable.failed.title')).toBeTruthy()
expect(screen.getByText('Network Error')).toBeTruthy()
@@ -169,11 +217,13 @@ describe('layout gates', () => {
it('shows the gateway address and the tabs once the gateway answers', async () => {
api.getConnectionInfo.mockResolvedValue({
- base_url: 'https://gw.example.com',
+ base_url: 'https://gw.example.com/gateway',
public_url_configured: true,
})
renderLayout()
- expect(await screen.findByText('https://gw.example.com')).toBeTruthy()
+ expect(
+ await screen.findByText('https://gw.example.com/gateway'),
+ ).toBeTruthy()
expect(
screen.getByRole('button', {
name: 'beta.label',
diff --git a/web-studio/src/routes/index.tsx b/web-studio/src/routes/index.tsx
index c39811878..b13399151 100644
--- a/web-studio/src/routes/index.tsx
+++ b/web-studio/src/routes/index.tsx
@@ -1,9 +1,12 @@
import { Navigate, createFileRoute } from '@tanstack/react-router'
+import { useAppConnection } from '#/hooks/use-app-connection'
+
export const Route = createFileRoute('/')({
component: IndexRoute,
})
function IndexRoute() {
- return <Navigate replace to="/home" />
+ const { isGatewayHost } = useAppConnection()
+ return <Navigate replace to={isGatewayHost ? '/gateway' : '/home'} />
}
diff --git a/web-studio/src/routes/settings/-gateway-connection.test.tsx b/web-studio/src/routes/settings/-gateway-connection.test.tsx
new file mode 100644
index 000000000..b933c4c23
--- /dev/null
+++ b/web-studio/src/routes/settings/-gateway-connection.test.tsx
@@ -0,0 +1,148 @@
+// @vitest-environment jsdom
+import {
+ cleanup,
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+} from '@testing-library/react'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import { GatewayConnectionSettings } from './route'
+
+const { health, saveConnection, navigate, connectionState } = vi.hoisted(
+ () => ({
+ health: vi.fn(),
+ saveConnection: vi.fn(),
+ navigate: vi.fn(),
+ connectionState: {
+ connection: {
+ baseUrl: 'http://gateway.test',
+ apiKey: '',
+ adminApiKey: '',
+ accountId: 'default',
+ userId: 'default',
+ },
+ openvikingUrl: 'https://openviking.example',
+ serverMode: 'api_key',
+ isGatewayHost: true,
+ },
+ }),
+)
+vi.mock('#/hooks/use-app-connection', () => ({
+ useAppConnection: () => ({ ...connectionState, saveConnection }),
+}))
+vi.mock('#/hooks/use-server-mode', async (importOriginal) => ({
+ ...(await importOriginal<object>()),
+ fetchServerHealth: health,
+}))
+vi.mock('@tanstack/react-router', async (importOriginal) => ({
+ ...(await importOriginal<object>()),
+ useNavigate: () => navigate,
+}))
+vi.mock('react-i18next', () => ({
+ useTranslation: () => ({
+ t: (key: string, values?: { url?: string }) =>
+ values?.url ? `${key}: ${values.url}` : key,
+ }),
+}))
+afterEach(cleanup)
+beforeEach(() => vi.clearAllMocks())
+
+it('shows one key input and logs in with the OV key against the gateway host', async () => {
+ health.mockResolvedValue({ role: 'user', account_id: 'a', user_id: 'alice' })
+ const { container } = render(<GatewayConnectionSettings />)
+ expect(container.querySelectorAll('input')).toHaveLength(1)
+ expect(
+ screen.getByText(
+ 'gatewayConnection.openvikingUrl: https://openviking.example',
+ ),
+ ).toBeTruthy()
+ fireEvent.change(screen.getByLabelText('gatewayConnection.apiKey'), {
+ target: { value: 'ov-user-key' },
+ })
+ fireEvent.click(screen.getByText('gatewayConnection.connect'))
+ await waitFor(() => expect(navigate).toHaveBeenCalledWith({ to: '/gateway' }))
+ expect(health).toHaveBeenCalledWith('http://gateway.test', {
+ 'X-API-Key': 'ov-user-key',
+ })
+ expect(saveConnection).toHaveBeenCalledWith({
+ ...connectionState.connection,
+ apiKey: 'ov-user-key',
+ accountId: 'a',
+ userId: 'alice',
+ })
+})
+
+it.each(['ovgw_client', 'ovgm_management'])(
+ 'rejects a misplaced %s key without sending it',
+ (apiKey) => {
+ render(<GatewayConnectionSettings />)
+ fireEvent.change(screen.getByLabelText('gatewayConnection.apiKey'), {
+ target: { value: apiKey },
+ })
+ expect(screen.getByRole('alert').textContent).toBe(
+ 'gatewayConnection.wrongKey',
+ )
+ fireEvent.click(screen.getByText('gatewayConnection.connect'))
+ expect(health).not.toHaveBeenCalled()
+ },
+)
+
+function stubAccess(body: object) {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn().mockResolvedValue({ json: () => Promise.resolve(body) }),
+ )
+}
+afterEach(() => vi.unstubAllGlobals())
+
+it('keeps the current connection when health omits the identity', async () => {
+ health.mockResolvedValue({ service: 'openviking-gateway' })
+ stubAccess({ reason: 'openviking_http_401' })
+ render(<GatewayConnectionSettings />)
+ fireEvent.change(screen.getByLabelText('gatewayConnection.apiKey'), {
+ target: { value: 'invalid' },
+ })
+ fireEvent.click(screen.getByText('gatewayConnection.connect'))
+ await waitFor(() =>
+ expect(screen.getByRole('alert').textContent).toBe(
+ 'gatewayConnection.invalidKey',
+ ),
+ )
+ expect(saveConnection).not.toHaveBeenCalled()
+ expect(navigate).not.toHaveBeenCalled()
+})
+
+it('says OpenViking is down instead of blaming the key', async () => {
+ health.mockResolvedValue({ service: 'openviking-gateway' })
+ stubAccess({ reason: 'openviking_unreachable' })
+ render(<GatewayConnectionSettings />)
+ fireEvent.change(screen.getByLabelText('gatewayConnection.apiKey'), {
+ target: { value: 'valid-but-unverifiable' },
+ })
+ fireEvent.click(screen.getByText('gatewayConnection.connect'))
+ await waitFor(() =>
+ expect(screen.getByRole('alert').textContent).toBe(
+ 'gatewayConnection.unreachable: https://openviking.example',
+ ),
+ )
+ expect(fetch).toHaveBeenCalledWith(
+ 'http://gateway.test/gateway/admin/access',
+ { headers: { 'X-API-Key': 'valid-but-unverifiable' } },
+ )
+ expect(saveConnection).not.toHaveBeenCalled()
+})
+
+it('says the gateway itself is unreachable when health fails', async () => {
+ health.mockRejectedValue(new Error('offline'))
+ render(<GatewayConnectionSettings />)
+ fireEvent.change(screen.getByLabelText('gatewayConnection.apiKey'), {
+ target: { value: 'key' },
+ })
+ fireEvent.click(screen.getByText('gatewayConnection.connect'))
+ await waitFor(() =>
+ expect(screen.getByRole('alert').textContent).toBe(
+ 'gatewayConnection.gatewayUnreachable',
+ ),
+ )
+})
diff --git a/web-studio/src/routes/settings/route.tsx b/web-studio/src/routes/settings/route.tsx
index b61cda17d..7489b5875 100644
--- a/web-studio/src/routes/settings/route.tsx
+++ b/web-studio/src/routes/settings/route.tsx
@@ -1,6 +1,6 @@
import * as React from 'react'
import { keepPreviousData, useQuery } from '@tanstack/react-query'
-import { createFileRoute } from '@tanstack/react-router'
+import { createFileRoute, useNavigate } from '@tanstack/react-router'
import {
CircleAlertIcon,
CircleDashedIcon,
@@ -13,6 +13,8 @@ import {
import { useTranslation } from 'react-i18next'
import { Alert, AlertDescription, AlertTitle } from '#/components/ui/alert'
+import { Button } from '#/components/ui/button'
+import { fetchServerHealth } from '#/hooks/use-server-mode'
import { Badge } from '#/components/ui/badge'
import { Card, CardContent, CardHeader, CardTitle } from '#/components/ui/card'
import {
@@ -39,7 +41,8 @@ export const Route = createFileRoute('/settings')({
function ConnectionSettingsRoute() {
const { t } = useTranslation('settings')
- const { identityScopeKey } = useAppConnection()
+ const { identityScopeKey, isGatewayHost } = useAppConnection()
+ if (isGatewayHost) return <GatewayConnectionSettings />
return (
<div className="flex w-full min-w-0 flex-col gap-5">
<h1 className="text-2xl font-semibold">{t('pageTitle')}</h1>
@@ -61,6 +64,128 @@ function ConnectionSettingsRoute() {
)
}
+/** Whether the gateway reports OpenViking itself unreachable for this key. */
+async function openvikingUnreachable(baseUrl: string, apiKey: string) {
+ try {
+ const response = await fetch(
+ `${baseUrl.replace(/\/+$/, '')}/gateway/admin/access`,
+ { headers: { 'X-API-Key': apiKey } },
+ )
+ const body: unknown = await response.json()
+ return (
+ typeof body === 'object' &&
+ body !== null &&
+ (body as { reason?: unknown }).reason === 'openviking_unreachable'
+ )
+ } catch {
+ return false
+ }
+}
+
+export function GatewayConnectionSettings() {
+ const { t } = useTranslation('settings')
+ const { connection, openvikingUrl, saveConnection, serverMode } =
+ useAppConnection()
+ const navigate = useNavigate()
+ const [apiKey, setApiKey] = React.useState(
+ connection.apiKey || connection.adminApiKey,
+ )
+ const [pending, setPending] = React.useState(false)
+ const [error, setError] = React.useState('')
+ const misplacedKey = apiKey.startsWith('ovgw_') || apiKey.startsWith('ovgm_')
+
+ async function login(event: React.FormEvent) {
+ event.preventDefault()
+ if (misplacedKey) return
+ setPending(true)
+ setError('')
+ try {
+ const health = await fetchServerHealth(
+ connection.baseUrl,
+ apiKey.trim() ? { 'X-API-Key': apiKey.trim() } : {},
+ )
+ // The gateway answers an invalid key with health minus identity, and
+ // so it does while OpenViking is down; /access tells the two apart.
+ if (apiKey.trim() && typeof health.user_id !== 'string') {
+ setError(
+ (await openvikingUnreachable(connection.baseUrl, apiKey.trim()))
+ ? t('gatewayConnection.unreachable', { url: openvikingUrl })
+ : t('gatewayConnection.invalidKey'),
+ )
+ return
+ }
+ saveConnection({
+ ...connection,
+ adminApiKey: '',
+ apiKey: apiKey.trim(),
+ accountId:
+ typeof health.account_id === 'string'
+ ? health.account_id
+ : connection.accountId,
+ userId:
+ typeof health.user_id === 'string'
+ ? health.user_id
+ : connection.userId,
+ })
+ await navigate({ to: '/gateway' })
+ } catch {
+ setError(t('gatewayConnection.gatewayUnreachable'))
+ } finally {
+ setPending(false)
+ }
+ }
+
+ return (
+ <Card className="w-full max-w-xl">
+ <CardHeader>
+ <CardTitle>{t('gatewayConnection.title')}</CardTitle>
+ {openvikingUrl ? (
+ <p className="break-all text-sm text-muted-foreground">
+ {t('gatewayConnection.openvikingUrl', { url: openvikingUrl })}
+ </p>
+ ) : null}
+ </CardHeader>
+ <CardContent>
+ <form className="grid gap-4" onSubmit={(event) => void login(event)}>
+ <Field>
+ <FieldLabel htmlFor="gateway-openviking-key">
+ {t('gatewayConnection.apiKey')}
+ </FieldLabel>
+ <FieldContent>
+ <Input
+ id="gateway-openviking-key"
+ type="password"
+ value={apiKey}
+ required={serverMode !== 'dev'}
+ onChange={(event) => {
+ setApiKey(event.target.value)
+ setError('')
+ }}
+ {...PLAIN_INPUT_PROPS}
+ />
+ <FieldDescription>
+ {t('gatewayConnection.keyHint')}
+ </FieldDescription>
+ {misplacedKey || error ? (
+ <p role="alert" className="text-sm text-destructive">
+ {misplacedKey ? t('gatewayConnection.wrongKey') : error}
+ </p>
+ ) : null}
+ </FieldContent>
+ </Field>
+ <Button type="submit" disabled={pending || misplacedKey}>
+ {t(
+ pending
+ ? 'gatewayConnection.connecting'
+ : 'gatewayConnection.connect',
+ )}
+ </Button>
+ </form>
+ </CardContent>
+ </Card>
+ )
+}
+
function getCapabilityIcon(result: CapabilityProbeResult | undefined) {
if (!result) {
return <CircleDashedIcon className="size-4" />