在 Studio 中管理 OpenViking 网关
本页面向在 Studio 里使用网关页面的人，说明各标签页的用途、谁能修改什么，以及保存的修改何时生效。用你的 OpenViking API 密钥打开 Studio（本地 dev 模式的服务无需密钥），在侧边栏选择 OpenViking 网关；独立部署的网关在自己的 /studio/ 下提供 Studio。上游和上下文配置由同一 OpenViking 账号下的所有用户共享，网关密钥和请求日志则属于各个用户。
Studio 标签页
网关页面共有六个标签页，每行都链接到详细说明该标签页的文档。
| 标签页 | 用途 | 数据归属 | 详见 |
|---|---|---|---|
| 概览 | 一眼看清运行状况：请求数、缓存命中率、召回的记忆、OpenViking 状态和降级请求。第一个请求到达之前，这里显示快速开始清单。 | 自己的请求；账号管理员和 root 看到整个账号的 | 概览、快速开始清单 |
| 上游 | 添加、编辑、测试和导入网关转发请求的模型端点。 | 账号内共享 | 上游 |
| 上下文配置 | 新建和编辑上下文配置：召回、保存、长对话和 OpenViking 工具。 | 账号内共享 | 上下文配置 |
| 密钥 | 签发和吊销网关密钥；账号管理员和 root 还能删除某个用户的网关数据。 | 自己的密钥；账号管理员和 root 管理整个账号的 | 网关密钥 |
| 请求日志 | 每个模型请求的记录，包括补充的记忆、Token 用量、问题和保存状态。 | 自己的请求；账号管理员和 root 看到整个账号的 | 请求日志 |
| 接入 | 网关地址，以及各客户端可直接复制的配置。 | 所有人相同 | 接入客户端 |
谁能修改什么
能否修改上游和上下文配置，取决于一项部署设置：网关管理密钥。默认不设置，是否设置由部署网关的人决定。
| Studio 中的操作 | 没有设置管理密钥 | 设置了管理密钥 |
|---|---|---|
| 查看上游和上下文配置，并在签发密钥时选用 | 本账号所有登录用户 | 所有登录用户；只读视图看不到上游的 API Key 和请求头 |
| 添加、修改或删除上游和上下文配置 | 本账号所有登录用户 | 必须先解锁编辑，账号管理员和 root 也不例外 |
| 测试上游（连接测试或模型测试） | 本账号所有登录用户 | 必须先解锁；只读时不显示测试按钮 |
| 导入 OpenViking 模型配置（仅限嵌入式部署） | 只有 root，包括本地 dev 模式 | 必须先解锁 |
| 签发网关密钥 | 用户给自己签发；账号管理员可给本账号的用户签发；root 先在侧边栏切换账号 | 同左，管理密钥不额外授予任何权限 |
测试之所以需要写权限，是因为测试会使用已存的凭证，模型测试还会被服务商计费。签发密钥的细节见网关密钥；包括管理 API 在内的完整规则见权限矩阵。
如果还没有可用的上游或上下文配置、自己又无权修改，快速开始清单会显示正在等待网关管理员添加。这时请联系部署网关的人。
解锁编辑
设置了网关管理密钥后，“上游”和“上下文配置”标签页默认只读，需要在当前浏览器标签页里解锁。账号管理员或 root 的 API 密钥不能解锁，网关密钥（ovgw_…）也不行。
- 在“上游”或“上下文配置”标签页的只读提示中，点输入网关管理密钥。
- 粘贴管理密钥，点解锁。
openviking-server init、openviking-gateway init和 Studio 的开启网关生成的密钥都以ovgm_开头；对话框里的**在哪里找？**列出了它的存放位置。 - 页面提示“已解锁，现在可以修改上游和上下文配置”，页头显示“可修改上游和上下文配置”和锁定按钮。
解锁只对当前浏览器标签页有效，直到你点锁定或关闭这个标签页。服务端更换管理密钥后，Studio 会自动锁定，并提示“网关管理密钥已失效，上游和上下文配置恢复为只读。”如果没人知道密钥，见忘记网关管理密钥。
快速开始清单和快速模式
第一个请求到达之前，“概览”标签页上会显示快速开始清单，按顺序列出四步：添加上游、创建上下文配置、签发网关密钥、接入客户端。客户端发出第一个请求后，清单自动隐藏。
还没有任何网关密钥时，清单里还有一张快速模式卡片，点一键生成密钥即可完成前三步：
| 步骤 | 快速模式做什么 |
|---|---|
| 上游 | 沿用已有的可用上游；一个都没有时，把 OpenViking 自身的模型配置（ov.conf 里的 VLM）导入为上游。 |
| 上下文配置 | 沿用已有的上下文配置；一个都没有时，用推荐设置新建一份，名为“默认”。 |
| 密钥 | 为当前用户签发一个名为“快速模式”的密钥，绑定所有可用上游。本地 dev 模式以外，root 改为在签发对话框里选择密钥归属的用户。 |
同时满足以下条件的上游才算可用：
- 已启用；
- API Key 由网关保管（没有设为每个客户端自带 API Key），并且已经保存了密钥；
- 至少列出一个模型或别名（模型列表为空的上游不算，所以即使已经有这样的上游，快速模式也会导入模型配置）；
- 不是仍被拦截的 Coding Plan 上游。
例外情况：
- 导入后仍没有网关能直接转发的模型时，卡片会说明原因，这时请在第 1 步（添加上游）手动添加上游。
- 设置了管理密钥、而快速模式需要新建上下文配置或导入模型时，卡片会先要求你用管理密钥解锁。
- 只有部分用户能导入模型配置：未设置管理密钥时是 root（本地 dev 模式下任何人都可以），设置了管理密钥时是用它解锁的人；独立部署的网关则完全无法导入。不能导入时，只有已经存在可用上游才会显示这张卡片。
修改何时生效
上游或上下文配置保存后，会作用于所有使用它的网关密钥，不需要重新签发密钥。区别只在于已经开始的对话能不能用上修改：
| 修改内容 | 何时生效 |
|---|---|
| 除优先级外的任何上游设置，例如 API Key、模型、启用 | 立即生效，进行中的对话也一样。停用上游会对它的对话产生什么影响，见路由。 |
| 上游优先级 | 只对之后开始的对话生效。进行中的对话只要原来的上游还能服务，就一直留在那里。 |
| 任何上下文配置 | 只对之后开始的对话生效。 |
| 网关密钥 | 密钥不能编辑。要更换密钥的上下文配置、上游、允许的模型或归属用户，请签发新密钥并吊销旧密钥，见签发之后。 |
对话在第一个请求时记下当时的上下文配置并一直沿用，因为中途改变模型看到的内容会破坏服务商的提示词缓存。所以客户端多快能用上新的上下文配置，取决于它多久开始一次新对话：
- 每次聊天都新开对话的客户端，很快就能用上新设置。
- Claude Code、Codex 以及发送固定会话请求头的客户端，会把一段对话延续很多天。它们一直沿用旧设置，直到开始新对话，或者这段对话闲置满 30 天（
session_ttl_days），此时网关会删除这段对话的状态。
网关如何区分不同的对话，见网关如何识别对话。
下一步
- OpenViking 网关快速上手：从空白的网关开始，拿到可用的密钥并发出测试请求。
- 网关管理密钥：设置、更换或重置保护上游和上下文配置的密钥。
- Studio 显示设置卡片：Studio 显示设置卡片、看不到网关标签页时怎么办。