OpenViking 网关配置参考
本页供修改 ov.conf、gateway.conf 或环境变量的运维人员查阅，也方便把 Studio 中的名称对应到管理 API 的字段名。每张表都列出名称、默认值和可选值；设置的作用和什么时候需要改，见各节链接的功能页面。
配置放在哪里
嵌入网关和独立网关的字段大部分相同，区别在于写在哪个文件里、用什么命令生成。只有一种部署形态使用的字段，在网关字段的“适用于”一列中标出。
| 嵌入 | 独立 | |
|---|---|---|
| 文件 | ov.conf 的 gateway 段 | gateway.conf 的根层，没有 gateway 外层 |
| 生成命令 | openviking-server init | openviking-gateway init |
| 读取哪个文件 | Server 自己的 ov.conf | --config 或 OPENVIKING_GATEWAY_CONFIG_FILE 指定的文件，且文件必须存在；两者都没设置时，读取 ~/.openviking/gateway.conf 和 /etc/openviking/gateway.conf 中第一个存在的文件 |
| host、port 和 workers | 跟随 Server | 由 host、port、workers 字段设置 |
OPENVIKING_CONFIG_FILE 只用来选择 Server 的配置，不会让独立网关读取它指向的文件。
网关字段
| 字段 | 适用于 | 默认值 | 可选值 | 含义 |
|---|---|---|---|---|
enabled | 嵌入 | false | 在 Server 中开启网关 | |
openviking_url | 独立 | —（必填） | HTTP(S) URL | OpenViking Server 的地址 |
host | 独立 | 127.0.0.1 | 监听地址 | |
port | 独立 | 1935 | 1–65,535 | 监听端口 |
workers | 独立 | 1 | 1–64 | worker 进程数 |
public_url | 两者 | 空 | HTTP(S) URL，不带 /gateway | 客户端访问的对外地址，/gateway 由网关自己加。为空时，嵌入网关沿用 Server 的对外地址；两者都没有时，接入指南使用请求来源地址，MCP 文件上传和下载也不可用（mcp_file_links 为 direct 时除外）。见对外地址 |
mcp_file_links | 两者 | proxy | proxy、direct | MCP 上传和下载工具返回的链接如何交给客户端。proxy 改写为 public_url 加 /gateway/uploads 或 /gateway/downloads，需要设置 public_url。direct 原样透传 OpenViking 的链接，需要 Server 的 OPENVIKING_PUBLIC_BASE_URL（或 server.public_base_url）是客户端能访问的地址 |
storage_path | 两者 | ~/.openviking/gateway | 本地存储目录 | |
encryption | 独立 | 不设置（明文） | 字段同 ov.conf 的 encryption 段 | 加密本地保存的数据，见加密；嵌入网关沿用 Server 的设置 |
management_key | 两者 | 空 | 至少 32 个字符 | 可选的网关管理密钥 |
min_server_version | 两者 | 0.4.16 | 版本号 | 独立网关要求的 OpenViking Server 最低版本 |
session_ttl_days | 两者 | 30 | 1 及以上 | 对话闲置多少天后过期 |
response_ttl_seconds | 两者 | 2592000（30 天） | 60 及以上 | Responses 响应与上游的对应关系保留多少秒 |
log_retention_days | 两者 | 30 | 1 及以上 | 请求日志保留天数 |
max_body_bytes | 两者 | 33554432（32 MiB） | 1,024 及以上 | 请求和上传的大小上限，单位为字节 |
upstream_timeout_seconds | 两者 | 600 | 大于 0 | 服务商请求超时 |
health_interval_seconds | 两者 | 60 | 1 及以上 | 检查 OpenViking 状态的间隔秒数 |
环境变量
每个网关字段都能用环境变量设置，变量名是 OPENVIKING_GATEWAY_ 加上大写的字段名，两种部署形态都适用：
bash
OPENVIKING_GATEWAY_PUBLIC_URL=https://ov.example.com
OPENVIKING_GATEWAY_MANAGEMENT_KEY='<management-key>'- 环境变量优先于配置文件。 非空的环境变量覆盖文件中的值，值为空等于没有设置。
- 以
tcp://或udp://开头的值会被忽略。这样，Kubernetes 为名为openviking-gateway的 Service 自动注入的变量（例如OPENVIKING_GATEWAY_PORT=tcp://…）不会覆盖文件。 - 文件中的值也可以写成
"$VAR"，从环境变量中取值。 encryption块只能写在文件里。- 容器通常不需要配置文件，用环境变量设置需要的字段即可。
校验
| 对象 | 规则 |
|---|---|
openviking_url 和 public_url | 必须是 HTTP(S)，不能含凭证、查询参数或 fragment |
上游的 base_url | 规则不同，见接口 |
management_key | 解析 $VAR 引用后至少 32 个字符；$VAR 没能解析时校验失败 |
| 未知字段 | 校验失败 |
| 已删除的字段 | 忽略，启动时打印警告：encryption_key_env，以及 ov.conf 中迁移列出的 v0.5 字段 |
上下文配置的设置
在 Studio 中：上下文配置 → 打开一份配置。下面几张表按编辑器的分区排列，先写 Studio 中的名称，再写管理 API 中的名称（管理 API 把上下文配置称为 policies）。名称（name，默认 Default）是配置的显示名称；各分区的作用见上下文配置。
召回记忆
作用见召回记忆。
| Studio 名称 | API 名称 | 默认值 | 取值范围 | 含义 |
|---|---|---|---|---|
| 召回记忆 | recall | true | 为每条新的用户消息检索记忆。 | |
| 会话开头提供用户画像 | profile | true | 新对话开始时提供画像，独立于召回。 | |
| 开头内容预算 | profile_max_tokens | 4000 | 0–32,000 | 画像和目录的独立预算；0 表示省略。目录需要提供 OpenViking 的 read 工具（openviking_read）。 |
| 显示召回摘要 | show_recall | false | 在回复开头说明 OpenViking 补充了什么，或召回失败的原因。模型看不到。 | |
| 检索范围 | context_types | memory、resource、skill | 开启召回时至少一个（仅 Studio 校验） | 检索哪些内容：记忆、资源、技能。 |
| 单条消息预算 | max_tokens | 1600 | 64–32,000 | 一条消息最多补充的 token 数。 |
| 单个上下文窗口预算 | session_max_tokens | 30000 | 0 及以上 | 一个上下文窗口内最多补充的 token 数，每次压缩后重新计算；0 表示关闭召回。 |
| 相关度阈值 | score_threshold | 0.35 | 0–1 | 接受的最低相关度分数。 |
| 超时时间 | recall_timeout | 2（秒） | 大于 0，最多 30 | 检索最多等多久，超时后消息不带记忆继续发送。 |
| 检索文本长度 | query_max_chars | 8000 | 3–32,000 | 取消息的多少个字符作为检索文本。 |
| 按分类限量 | quotas | {}（关闭） | 键：events、entities、preferences、experiences、resources、skills；设置时至少一项大于 0（仅 Studio 校验） | 每个分类最多取的条数；只检索大于 0 的分类。 |
管理 API 保存 context_types 和 quotas 时不做校验。quotas 里出现未知的键时，OpenViking 会拒绝检索请求，导致每次召回都失败。
保存对话
作用见保存对话。
| Studio 名称 | API 名称 | 默认值 | 取值范围 | 含义 |
|---|---|---|---|---|
| 保存对话 | capture | true | 把完成的轮次保存到 OpenViking。 | |
| 最新回复等待时长 | idle_seconds | 600（秒） | 1 及以上 | 停顿多久之后保存最后一轮并提交会话。 |
| 提交阈值 | commit_tokens | 20000 | 1 及以上 | 会话中待提交的 token 数达到这个值时提交。 |
| 保留最近消息 | keep_recent_messages | 10 | 0–1,000 | 提交后会话中保留的消息数。 |
长对话
作用见网关中的长对话。
| Studio 名称 | API 名称 | 默认值 | 取值范围 | 含义 |
|---|---|---|---|---|
| 压缩 | compaction | true | 接近上下文窗口时，用摘要替换对话较早的部分。 | |
| 压缩时机 | compaction_threshold | 0.9 | 0.5–0.98 | 上下文窗口用到多大比例时压缩。 |
| 摘要长度上限 | 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 工具
| Studio 名称 | API 名称 | 默认值 | 取值范围 | 含义 |
|---|---|---|---|---|
| OpenViking 工具 | gateway_tools | true | 为 Chat Completions、完整历史的 Responses 和 Anthropic Messages 提供 OpenViking 工具。 | |
| 工具（未勾选的项） | disabled_tools | 会修改数据的 8 个工具 | OpenViking 工具原名，不带 openviking_ | 新对话不提供这些工具，其余可用工具都提供，包括以后新增的。 |
| 显示工具调用 | show_tool_calls | true | 每次 OpenViking 工具调用都在回复里加一行提示。 | |
| 每次请求的工具轮数 | tool_max_rounds | null（不限） | 1 及以上 | 工具调用达到这个轮数后，拒绝继续调用 OpenViking 工具。 |
| 单次调用超时 | tool_timeout_seconds | 30（秒） | 大于 0，最多 120 | 超时的调用向模型返回错误。 |
| 结果大小上限 | tool_result_bytes | 65536（字节） | 1,024–1,048,576 | 超出部分在交给模型前截掉。 |
| 总时长 | tool_total_seconds | null（不限） | 大于 0 | 超过这个秒数模型仍在调用工具时，请求失败。 |
| Token 预算 | tool_total_tokens | null（不限） | 1,024 及以上 | 工具调用和结果在一次请求中最多增加的估算 token 数，用完后拒绝继续调用 OpenViking 工具。 |
API 请求省略 disabled_tools 时使用默认列表；列表为空且 gateway_tools 开启时，提供全部可用工具。
上游设置
在 Studio 中：上游 → 打开一个上游。下面几张表按编辑器的四个分区排列；各字段的作用见上游。
接口
| Studio 名称 | API 名称 | 默认值 | 可选值 | 含义 |
|---|---|---|---|---|
| 名称 | name | —（必填） | 显示名称。 | |
| 服务商 | vendor | generic | generic、anthropic、openai、deepseek、ark（火山方舟）、byteplus（BytePlus 方舟） | Studio 只提供服务商支持的协议，API 接受任意组合。 |
| 协议 | protocol | —（必填） | anthropic（Anthropic Messages）、chat（Chat Completions）、responses（Responses） | 这个上游使用的 API。 |
| Base URL | base_url | —（必填） | HTTP(S) URL | 服务商地址；默认地址见什么是上游，拼接规则见接口。 |
| 拼接协议接口路径 | append_endpoint_path | true | 拼接所选协议的接口路径；关闭时把 base_url 直接作为完整请求地址。 |
凭证
| Studio 名称 | API 名称 | 默认值 | 可选值 | 含义 |
|---|---|---|---|---|
| API Key 由谁提供 | auth_mode | managed | managed（由网关保管 API Key）、passthrough（每个客户端自带 API Key） | 见凭证。 |
| 密钥发送方式 | key_header | authorization | authorization（Bearer）、api-key、x-api-key | base_url 含 {api_key} 时不生效。 |
| API Key | api_key | 空 | 只写，见凭证。 | |
| 额外请求头 | headers | {} | 请求头名称 → 取值 | 只写，见凭证。 |
| 这是 Coding Plan 或订阅密钥 | coding_plan | false | 除非另外允许，否则拒绝发往这个上游的请求。 | |
| 允许通过网关使用这个套餐 | allow_coding_plan | false | 允许使用被标记为 Coding Plan 的密钥。 |
模型
| Studio 名称 | API 名称 | 默认值 | 可选值 | 含义 |
|---|---|---|---|---|
| 模型 | models | [] | 模型名 | 提供的模型名；留空表示接受任何名称。 |
| 模型别名 | aliases | {} | 客户端使用的名称 → 发给上游的模型 | |
| 上下文窗口 | context_windows | {} | 模型 → token 数，每项至少 1,024 | 各模型的上下文窗口，见设置模型的上下文窗口。 |
路由
| Studio 名称 | API 名称 | 默认值 | 可选值 | 含义 |
|---|---|---|---|---|
| 优先级 | priority | 0 | 整数 | 数值越大，新对话越优先使用。 |
| 启用 | enabled | true | 停用的上游不接收请求。 | |
| 允许 OpenViking 工具 | allow_gateway_tools | true | 能否通过这个上游提供 OpenViking 工具。 | |
| 补全推理内容回传 | replay_reasoning | null（跟随服务商） | null、true、false | 把客户端丢掉的推理内容补回之前的回复。null 时 deepseek、ark 和 byteplus 开启，其他服务商关闭；true 或 false 覆盖服务商默认值。Studio 中开关与服务商默认值一致时保存为 null。 |
| 最小可缓存长度 | cache_min_tokens | 1024 | 0 及以上 | 仅火山方舟和 BytePlus 方舟；影响缓存资格的报告。 |
下一步
- 独立部署：生成
gateway.conf，单独运行网关。 - 在 Server 中启用：在
ov.conf中开启嵌入网关。 - 上下文配置和上游：用 Studio 的说法解释上面这些设置的作用。
- 管理 API：网关密钥的字段、全部管理操作、权限规则和错误原因。