跳到正文
字节跳动技术团队· 字节跳动技术团队·· 1 天前精选AI 评分66

OpenViking 网关：让任意客户端用上 Agentic 记忆

AI 导读

OpenViking 网关位于客户端与模型服务之间，为兼容客户端自动召回、按需检索和保存 OpenViking 中的记忆，客户端无需自行实现记忆逻辑或安装插件。

推荐理由

原文给出了网关的能力边界、两种部署路径和 Claude Code 接入步骤，可直接用于评估是否为现有客户端补充记忆能力。

正文

一个项目聊到第三天，你希望 AI 接着上次的结论往下做，而不是重新问一遍背景。要做到这一点，它需要在回答时找到之前的信息，也需要把新的进展保存下来。但接入记忆并不总是方便。有的客户端能装插件，有的只能聊天；有的脚本可以调用模型，却没有检索、读取和保存记忆的逻辑。

OpenViking 网关把这些工作接了过来。它位于客户端和模型服务之间，帮助模型查找和使用 OpenViking 中的记忆，让兼容客户端不必各自实现一套记忆功能。

一、它能帮你做什么

网关提供三项能力，分别对应对话里的三个问题。

之前说过什么？自动找。你发出新消息后，网关会查找相关记忆，连同问题一起发给模型。这样，模型回答时就能参考之前的背景。

信息不够怎么办？继续查。你问“上次定的发布日期是哪天”，模型可以先搜索，再打开对应原文确认。检索和读取由网关执行，客户端不需要自己支持这些工具。

这次聊出的内容怎么办？保存下来。开启对话保存后，OpenViking 会从中整理出有用信息，供以后使用。对话太长时，网关还可以让模型生成摘要，缩短后续请求中携带的历史内容。

AI 不只是被动收到一段背景，还能在需要时自己查找和使用记忆。如果开放了保存工具，它也能按你的要求记住内容。

二、接入主要改两项配置

在已经部署好网关的前提下，兼容客户端主要调整两项设置：

  • Base URL：模型接口地址，改为网关地址，即网关所在服务的地址加 /gateway。

  • API Key：访问凭证，换成在 Studio 中签发的网关密钥。

不需要再为这些客户端安装 OpenViking 插件，也不用单独编写记忆处理代码。Claude Code 还需增加一项环境配置，用来区分它的后台请求，具体步骤见文末接入指南。

Studio 是网关的管理页面，可以设置连接哪个模型、是否保存对话，以及允许模型使用哪些工具。

模型服务和运行情况也能在这里查看，不必在每个客户端里分别维护。

网关可以随 OpenViking Server 一起运行，也可以独立部署、连接已有的 OpenViking 服务，包括火山引擎托管服务。更多原理可查看官网：https://openviking.ai/gateway

三、哪些客户端可以用

网关主要面向能自定义模型接口地址、并满足接口要求的聊天应用、自己写的调用脚本和低代码平台。对已有的编程 Agent，它也可以补充记忆能力。

在已完成的测试中，Claude Code、Codex CLI 和 OpenAI Python SDK 已验证能查找和保存记忆；Cherry Studio 的纯聊天模式也能使用记忆工具。其他客户端仍需按实际环境验证。

下图是 Cherry Studio、pi 和 Codex 的接入示例，均未安装 OpenViking 插件，只更换了模型来源。

能改地址不代表所有调用方式都支持。客户端还需要把完整聊天记录带给模型；只用订阅账号登录，或由厂商服务器发起模型调用的方式，不适用这条接入路径。具体支持情况以接入指南为准。

四、一张图看懂架构

  • 运行在哪：网关可以嵌入 OpenViking Server，和 Server 共用端口；也可以用 openviking-gateway 独立运行，连接已有的 OpenViking 服务（例如火山引擎托管的 OpenViking）。两种形态下，客户端地址都是服务地址加 /gateway（见“部署方式”）。

  • 和 OpenViking 的关系：网关只调用 OpenViking 的公开接口，向量化和记忆提取都在 OpenViking 里做。

  • 数据在哪：会话和记忆的正本在 OpenViking；网关本机只有两个 SQLite 文件，一个存上游、密钥和配置，一个存对话状态（见图），对话闲置 30 天过期。加密、删除与隔离见“安全与数据边界”。

  • 出故障时：OpenViking 不可用时对话照常，只是不带记忆，写回自动重试。网关停止服务时（嵌入形态下即 OpenViking Server 停止时），经过它的模型调用全部失败。

  • 谁来管：用户在 Studio 给自己签发网关密钥，账号管理员也能替本账号用户签发。每把密钥绑定一位 OpenViking 用户、一份上下文配置（召回预算、是否写回、开放哪些工具）和一组上游（转发到的模型服务地址和 Key）。

五、接入后，对话会发生什么

网关自动认出同一段对话，只有用户的新消息触发召回，工具步骤和辅助请求不召回。压缩切点之前的原文不再发给模型，模型可以用 OpenViking 工具回会话里查原文。

六、让任意客户端拥有 Agentic 记忆

自动召回是网关替模型猜它需要什么；有了 OpenViking 工具，模型自己决定查什么、读什么、记什么。工具由网关执行，客户端不用声明或实现任何工具，请求里一个工具都没有也能用。

  • 一条回复里的多步操作：网关拦下模型发出的 OpenViking 工具调用，用该用户的 OpenViking 密钥执行，把结果接回再问模型，直到模型不再调用。客户端只收到一条连贯的回复。

  • 客户端自己的工具照常用：同一条回复里可以同时调用 OpenViking 工具和客户端工具（例如 Bash），客户端的调用原样交给客户端执行，照常经过它的权限确认。

  • 下一轮还记得：工具往返（模型发出的工具调用和网关拿回的结果）不在客户端历史里，网关把它们存下来，下一轮原样放回，模型记得查到过什么，提示缓存也不断。

6.1 模型能用哪些工具

工具直接来自所连 OpenViking 服务的工具清单，随服务端版本增减，名字前加 openviking_。写入、导入、删除和改权限这几类会改数据的工具默认不勾选，其余默认勾选（包括 OpenViking 以后新增的工具，开放前可以先看一眼清单）。

七、部署方式

网关有两种运行形态，客户端用法相同：地址都是服务地址加 /gateway，只改 Base URL 和 API Key。详细步骤见官方文档 OpenViking 网关部署与运维（https://docs.openviking.ai/zh/guides/22-gateway-operations）

7.1 开始前准备

  • 已有可用的 OpenViking。运行网关的本机安装 OpenViking 0.5.1 及以上；本地 OV 已配置好 embedding 和 VLM。

  • 准备火山方舟 API Key；路径 B 还需准备自己的 OV 用户 API 密钥。本机已安装 Claude Code，可运行 claude，并有 curl。

  • 以下命令适用于 macOS / Linux 终端，默认仅供本机访问。需要升级时，在原安装环境执行：

python -m pip install --upgrade openviking

7.2 路径 A：本地 OV

网关与已有 OV 共用端口，地址为 http://127.0.0.1:1933/gateway。以下以本地 dev 模式为例。

A1 开启网关

终端执行：

openviking-server init

  1. 用方向键选 Update gateway (now: disabled)，按回车。不要直接确认默认的 Start over，它会重新配置整套服务。

  2. 在 Enable OpenViking Gateway on the same port? 输入 y。

  3. 在 Save configuration? 按回车保存；原配置自动备份为 ov.conf.bak。

  4. 在 Validate the setup now? 输入 n，网关稍后单独验证。

  5. 如果 OV 已在运行，Start the server now? 选 N，按 A2 重启；如果未运行，可选 y 直接启动。

图 1｜用方向键选中 Update gateway，再按回车

默认配置文件为 ~/.openviking/ov.conf。若使用其他路径，执行 OPENVIKING_CONFIG_FILE=/实际路径/ov.conf openviking-server init，启动时也指定同一文件。自建 api_key 服务若禁止用户自行配置上游，需保存向导生成的 ovgm_… 管理密钥。

A2 重启并检查

  1. 若服务在原终端前台运行，按 Ctrl-C 停止，然后执行下方启动命令；若由进程管理器托管，用原方式重启，不要重复启动。

openviking-server --config ~/.openviking/ov.conf

  1. 保持服务运行，另开终端执行：

curl -s http://127.0.0.1:1933/health; echo
curl -s http://127.0.0.1:1933/gateway/v1/models; echo

成功标准：第一条返回"status":"ok"；第二条返回 401 / Invalid gateway key，表示网关已挂载，只是还没带密钥。若为 404，检查是否启用并重启。

图 2｜未携带密钥时返回 401，是本步骤的预期结果

A3 进入 Studio

  1. 浏览器打开 http://127.0.0.1:1933/studio/。

  2. 首次连接选择 开源服务 → 添加新服务地址，手动输入 http://127.0.0.1:1933，点 下一步；灰色占位地址不算已填写。

  3. 本地 dev 模式的用户 API 密钥留空，点 验证连接 → 进入 Studio。自建 api_key 服务在此填用户 API 密钥。

  4. 左侧选择 OpenViking 网关，然后跳到“通用配置与接入”。

成功标准：连接验证成功，能打开网关页面。

图 3｜本地 dev 模式无需 API 密钥，验证成功后进入 Studio

7.3 路径 B：火山托管 OV

本机运行独立网关，连接已有托管服务；记忆仍保存在托管 OV。网关地址为 http://127.0.0.1:1935/gateway。

B1 初始化独立网关

终端执行：

openviking-gateway init

按提示依次填写：

  1. OpenViking server URL：输入 https://api.vikingdb.cn-beijing.volces.com/openviking。

  2. Listen host：回车，保持 127.0.0.1。

  3. Listen port：回车，保持 1935。

  4. Require a management key to change upstreams and profiles?：输入 y。

  5. 立即保存生成的ovgm_…管理密钥，只显示一次。 配置写入 ~/.openviking/gateway.conf。

成功标准：向导保存配置，并生成管理密钥。商业版显示 Version: unknown 不代表连接失败。

图 4｜填写 OV 地址并启用管理密钥；端口保持正文的 1935

B2 启动并检查

  1. 启动网关，保持该终端运行：

openviking-gateway

  1. 另开终端检查：

curl -s http://127.0.0.1:1935/health

成功标准：返回 "service":"openviking-gateway"，openviking_url 为托管地址，且 openviking 中的 status 为 ok、auth_mode 为 api_key。

图 5｜检查网关连接的 OV 地址及健康状态

B3 登录并解锁编辑

  1. 浏览器打开 http://127.0.0.1:1935/studio/。

  2. 粘贴自己的 OV API 密钥，点 登录。

图 6｜登录用 OV API 密钥，不是管理密钥

 3. 点 输入网关管理密钥，粘贴 B1 保存的 ovgm_…，点 解锁。

成功标准：页头显示“可修改上游和上下文配置”。关闭标签页后会重新锁定。

图 7｜管理密钥只用于解锁上游和上下文配置的编辑权限

7.4 通用配置与接入

两条路径都在 OpenViking 网关页面完成以下操作。为减少配置，本简版只创建 Claude Code 必需的 Anthropic Messages 上游，不额外创建 Chat 上游。

添加模型上游

  1. 点 上游 → 添加上游。

  2. 名称填“火山方舟 Anthropic”，服务商选 火山方舟，协议选 Anthropic Messages。

  3. 确认 Base URL 为 https://ark.cn-beijing.volces.com/api/compatible，拼接协议接口路径保持开启。

图 8｜Claude Code 必须选择 Anthropic Messages，网关不做协议转换

  1. API Key 由谁提供选“由网关保管 API Key”，填入 方舟 API Key。

  2. 模型填 deepseek-v4-1-flash-261017，按回车形成标签，再点 添加上游。

成功标准：上游列表出现“火山方舟 Anthropic”，且包含所填模型。模型沿用原文示例；若账号不可用，请换成已开通且支持此协议的模型，并同步修改后面的环境变量。

图 9｜填入模型服务商的 API Key，模型名称输入后需要按回车

配置自动记忆

  1. 点 上下文配置。路径 A 点 新建配置，名称填“快速体验（30 秒）”；路径 B 点 使用推荐设置创建，再编辑生成的“默认”配置。

  2. 确认 召回记忆 和 保存对话均开启。

  3. 把 保存对话 → 最新回复等待时长改为 30 秒，方便快速验证。日常使用可恢复默认 600 秒。

  4. 召回记忆 → 超时时间：路径 A 保持 2 秒；路径 B 按原教程建议设为 8 秒。

  5. 点 创建配置或保存。

成功标准：配置已保存。修改只对新对话生效。

图 10｜红框改为 30 秒；图中召回超时为本地用的 2 秒，托管路径请填 8 秒

签发客户端密钥

  1. 点 密钥 → 签发密钥，名称填“Claude Code 演示”。

  2. 路径 A 的 dev 模式自动使用 default 身份；路径 B 再粘贴自己的 OV 用户 API 密钥，不接受 root 密钥。

  3. 上下文配置选刚保存的配置，上游勾选 火山方舟 Anthropic，“允许的模型”留空。

  4. 点 签发密钥，立即复制并保存 ovgw_…。完整密钥只显示一次，下一步给 Claude Code 使用。

成功标准：拿到 ovgw_…，且密钥绑定了正确用户、配置与 Anthropic 上游。一人一把密钥，不要共用。

图 11A｜本地 dev 模式自动绑定 default

图 11B｜托管路径需要再填 OV 用户 API 密钥

截图差异：原图包含 Chat / curl 示例；本简版的名称填“Claude Code 演示”，上游只勾选 火山方舟 Anthropic，不要照右图只选 Chat。

接入 Claude Code

在运行 Claude Code 的终端配置；占位密钥必须换成第 3 步复制的值。以下仅影响当前终端，原有全局配置无需修改。

  1. 使用未安装 OpenViking 插件的独立配置目录，并临时关闭 Claude Code 自带记忆，避免干扰验证：

export CLAUDE_CONFIG_DIR=~/.claude-gateway-demo
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
unset ANTHROPIC_API_KEY

  1. 设置网关地址、密钥和模型。路径 B 把 1933 改为 1935；地址不要加/v1。

export ANTHROPIC_BASE_URL=http://127.0.0.1:1933/gateway
export ANTHROPIC_AUTH_TOKEN='ovgw_替换为你的完整网关密钥'
export CLAUDE_CODE_GATEWAY_HINT_HEADERS=1
export ANTHROPIC_MODEL=deepseek-v4-1-flash-261017
export ANTHROPIC_DEFAULT_HAIKU_MODEL=$ANTHROPIC_MODEL
export ANTHROPIC_DEFAULT_SONNET_MODEL=$ANTHROPIC_MODEL
export ANTHROPIC_DEFAULT_OPUS_MODEL=$ANTHROPIC_MODEL

  1. 发一条真实请求检查连接：

claude -p "用一句话回答：1+1 等于几？"

成功标准：正常输出回答。无需 Claude 订阅登录，也不要使用订阅令牌。若提示模型名未识别、按 200k 上下文处理，但仍正常回答，可继续验证。

图 12｜图片只设了部分模型变量，请完整复制正文，补齐 Sonnet / Opus

7.5 验证自动记忆

使用同一项目目录、同一把网关密钥，先保存一条约定，再用全新会话验证。

写入项目约定

在示例项目目录运行 claude，首次进入时仅信任你确认安全的目录，然后输入：

记住：这个项目统一用 pnpm，不要用 npm；提交信息用英文。不要把这些约定写入项目文件，只回复确认。

收到回复后输入 /exit，等待约 1 分钟。30 秒是保存等待时间，记忆提取还需时间，不保证恰好 1 分钟完成。

图 13｜原教程会话 1 示例；本简版只记录约定，省去修改 package.json

新会话验证

重新运行 claude，不要使用--resume，输入：

帮我给这个项目加一个 lodash 依赖，告诉我该用什么命令，先别执行。

预期结果：给出 pnpm add lodash，而不是 npm 命令。

图 14｜新会话自动使用 pnpm 约定

确认网关确实召回

  1. 在 Claude Code 输入 /status，复制 Session ID。

  2. 回 Studio，点 OpenViking 网关页面顶部的请求日志，不是左侧“活动”下的请求日志。

  3. 搜索 Session ID，查看新会话的第一条“新消息”。

完成标准：请求成功、保存正常，且记忆列出现+N；展开详情能看到 Anthropic 上游及已补充记忆。不要只凭模型说“我记住了”判断成功。

图 15｜实际条数和耗时会不同，重点是有召回记录

可以先从一个常用客户端、一条真实的项目约定开始，按上面的步骤验证保存与召回。 让下一次对话，少一次背景重述，多一步实际推进。

立即体验 OpenViking，让 Agent 协作真正拥有记忆！

开通 OpenViking 服务，领取 50 文档免费额度。

点击阅读原文，立即开通 OpenViking 服务

三分钟测出你是哪种 Agent 饲养员选择属于你的 OpenViking：https://blog.openviking.ai/post/should-you-use-openviking/

接入过程中遇到问题？想交流多 Agent 协作的实践经验？欢迎加入社群，一起探索 OpenViking 的更多玩法！

来源：字节跳动技术团队 · mp.weixin.qq.com

字节跳动 / 火山引擎Agent 智能体工程模型推理与部署工程知识库、RAG 与搜索平台与工具发布#产品更新#Agent#RAG#部署/工程#字节跳动