[RFC]明确vikingbot作为agent使用场景，配置方案和调用链路

[yeshion23333]

RFC：VikingBot Gateway 与 OpenViking 的入口、配置解析和鉴权边界

本版按新的产品规则重新整理：保留 openviking-server --with-bot 旧链路，新增 ov CLI -> VikingBot Gateway 直连入口；启动期确定 gateway 是否使用 OpenViking，请求期实时校验 OpenViking 当前鉴权模式。bot.ov_server.source、ovcli.conf.target 不作为显式配置字段暴露。

1. 目标

这次改造希望同时支持三类使用方式：

场景	入口	OpenViking 来源	目标行为
本地一体启动	openviking-server --with-bot	当前启动的 OpenViking server	保留旧链路：ov chat -> OpenViking /bot/v1 -> VikingBot gateway
本地调试 bot	vikingbot chat	ov.conf.bot.ov_server 或本地配置	进程内调试 agent，不要求承载所有 OpenViking CLI API
Gateway 统一入口	vikingbot gateway，ovcli.conf.url 指向 gateway	显式 bot.ov_server 或继承同一份 ov.conf.server	ov chat 直接对话；ov list/search/session/... 经 gateway proxy 到 OpenViking

目标不是替换旧链路，而是新增 gateway 入口：

2. 术语

名称	含义
Gateway token	bot.gateway.token / X-Gateway-Token，保护 VikingBot gateway 入口
Caller OpenViking API Key	调用方从 ovcli.conf.api_key 或请求头传入的 OpenViking API Key，用于代表当前用户访问 OpenViking
Bot OpenViking API Key	bot.ov_server.api_key，用于 bot 自身连接 OpenViking memory/file tools 的默认身份；不能直接等同于调用方身份
Explicit OV	显式配置了 bot.ov_server.server_url
Inherited OV	未配置 bot.ov_server.server_url，gateway 从同一份 ov.conf.server 推导 OpenViking server
Standalone	gateway 没有可用 OpenViking upstream，只提供纯 bot chat，不提供 OpenViking memory/file tools 和 /api/v1/* proxy

3. openviking-server --with-bot 规则

openviking-server --with-bot 表示本机启动 OpenViking server 和 bot 服务，继续使用之前的链路：

ov chat -> OpenViking server /bot/v1 router -> VikingBot gateway -> Agent

规则：

1. Bot 使用当前启动 OpenViking server 对应的 ov.conf.server 配置。
2. 该模式不使用 bot.ov_server 连接另一个 OpenViking server。
3. 如果配置了 bot.ov_server.server_url，建议启动日志提示：该字段在 --with-bot 模式下被忽略。
4. OpenViking server 侧 /bot/v1 router 继续负责向 bot 注入 request-scoped openviking_connection。

4. vikingbot gateway 启动期规则

4.1 Gateway 入口安全

Gateway 监听地址	启动要求	请求要求
localhost / 127.0.0.1 / ::1	可不配置 bot.gateway.token	可不传 X-Gateway-Token
非 localhost	必须配置 bot.gateway.token，否则拒绝启动	每个 gateway 请求都必须传有效 X-Gateway-Token

说明：非 localhost gateway 下，Gateway token 是网关入口保护；OpenViking API Key 是上游身份。两者不能互相替代。

4.2 OpenViking upstream 解析

具体规则：

条件	行为
配置了 bot.ov_server.server_url，但访问不通	启动失败，不能静默 fallback 到 standalone
未配置 bot.ov_server.server_url，继承同配置 OpenViking，但默认 server 或访问不通	启动为 standalone，ov = 无
有可访问的 OpenViking，auth_mode = dev	gateway 只能监听 localhost；OpenViking server 自身已有 dev 模式非 localhost 启动校验，RFC 不重复定义
有可访问的 OpenViking，auth_mode = api_key	bot.ov_server.api_key 必须配置，且必须是有效 User API Key；否则启动失败
显式 bot.ov_server.server_url，auth_mode = trusted	bot.ov_server.api_key 必须配置，且必须是有效 root key；否则启动失败
未显式配置 bot.ov_server.server_url，继承到 auth_mode = trusted	自动读取同级 server.root_api_key，并校验有效；缺失或无效则启动失败

bot.ov_server.api_key 的定位是 bot 自身访问 OpenViking tools 的默认身份，不是公网请求的调用方身份。

5. 请求期规则

Gateway 请求先做入口鉴权，再做 OpenViking upstream 规则：

5.1 Standalone 模式

请求	行为
/bot/v1/chat	可用，只提供本地 bot chat，不具备 OpenViking memory/file tools
/api/v1/*	返回 503，因为没有 OpenViking upstream
非 localhost gateway	即使 standalone，也必须每个请求校验 X-Gateway-Token

5.2 使用 OpenViking 的模式

所有使用 OpenViking 的请求都要实时校验当前 OpenViking auth_mode，不能只信 gateway 启动时的探测结果。

当前 OpenViking auth_mode	请求规则
dev	gateway 必须是 localhost；非 localhost 直接拒绝
api_key - chat	调用方必须传有效 User API Key；缺失或无效返回 401；不能 fallback 到 standalone chat，也不能用 bot 默认 key 代替调用方身份
api_key - proxy	gateway 转发调用方 OpenViking auth headers，由 OpenViking 按接口自身权限判断 user/admin/root；gateway 不把 X-Gateway-Token 转发给 OpenViking
trusted	localhost 可本地使用；非 localhost 必须先校验 gateway token；gateway 使用 root key 和可信身份头访问 OpenViking

如果运行时发现 OpenViking 当前 auth_mode 与 gateway 启动时解析的模式不一致，gateway 应 fail-closed：

• 切到 dev 且 gateway 非 localhost：返回 403。
• 其他模式变化：返回 503，提示重启 gateway 或更新 ov.conf。

5.3 身份边界

1. openviking_connection 只能由可信 server-proxy 或本地可信链路注入，不能接受公网请求 body 随意传入。
2. X-OpenViking-Account / X-OpenViking-User 属于 trusted 身份断言；非 localhost gateway 必须先校验 gateway token 后才可信。
3. Request-scoped 身份优先于进程级默认配置，避免多个调用方共用同一个 bot 用户身份。

6. 配置约定

6.1 ov.conf

{
  "server": {
    "url": "http://127.0.0.1:1935",
    "auth_mode": "api_key",
    "root_api_key": "<root-key>"
  },
  "bot": {
    "gateway": {
      "host": "127.0.0.1",
      "port": 18791,
      "token": "<required-when-gateway-host-is-non-localhost>"
    },
    "ov_server": {
      "server_url": "https://openviking.example.com",
      "api_key": "<bot-user-key-or-trusted-root-key>"
    }
  }
}

约束：

• 不新增 bot.ov_server.source 显式字段；explicit / inherited / standalone 是内部派生状态。
• bot.ov_server.server_url 配置后表示显式 upstream，启动失败不能静默 fallback。
• bot.ov_server.api_key 在 api_key 模式下必须是 User API Key；在显式 trusted 模式下必须是 root key。

6.2 ovcli.conf

ovcli.conf.url 可以指向 OpenViking server，也可以指向 VikingBot gateway。不新增 target 字段。

{
  "url": "http://127.0.0.1:18791",
  "api_key": "<caller-openviking-api-key>",
  "root_api_key": "<optional-root-key-for-admin-commands>",
  "gateway_token": "<only-needed-when-gateway-requires-token>",
  "account": "default",
  "user": "alice",
  "actor_peer_id": "cli"
}

CLI 行为：

ovcli.conf.url 指向	ov chat	其他 ov 命令
OpenViking server	走 server /bot/v1 router；要求 server 已 --with-bot	直接访问 OpenViking /api/v1/*
VikingBot gateway	走 gateway /bot/v1/chat	访问 gateway /api/v1/*，由 gateway proxy 到 OpenViking

gateway_token 只用于生成 X-Gateway-Token，不能转发给 OpenViking。

7. 落地改动清单

1. 保留 openviking-server --with-bot 旧链路，server 侧 /bot/v1 router 继续可用。
2. vikingbot gateway 增加 /api/v1/* proxy，承载 ov list/search/session/... 等 CLI 请求。
3. vikingbot gateway 启动时区分 explicit OV、inherited OV、standalone，并按上述规则 fail-fast 或降级。
4. 非 localhost gateway 必须配置 token，并且每个请求都校验 X-Gateway-Token。
5. api_key 模式下，启动校验 bot 默认 User API Key；请求期 chat 使用调用方 User API Key；proxy 转发调用方 OpenViking auth headers。
6. trusted 模式下，公网入口必须有 gateway token，不能裸信身份头。
7. 请求期实时探测 OpenViking 当前 auth_mode，防止 server 重启后模式变化绕过安全边界。
8. 配置 schema 不暴露 bot.ov_server.source 和 ovcli.conf.target。
9. 补齐测试：--with-bot 旧链路、gateway chat、gateway proxy、standalone、安全拒绝、auth_mode 运行时变化、unknown config 字段拒绝。

8. 待确认

1. api_key 模式下，chat 是否只接受 User API Key，还是允许 Admin API Key 作为用户身份使用。当前 RFC 倾向只接受 User API Key。
2. gateway_token 字段名是否沿用现有 ovcli.conf.gateway_token，还是只通过 extra_headers.X-Gateway-Token 兼容。
3. inherited OV 的 api_key 模式是否强制要求 bot.ov_server.api_key。当前 RFC 按“有可访问 OV 就必须有 bot User Key”处理，避免 bot tools 在运行时才失败。