You need to enable JavaScript to run this app.
文档中心
火山方舟

火山方舟

请输入
  • 文档首页
    • 火山方舟Agent Plan 个人版配置 HarnessAgent 记忆
复制全文
下载 pdf
我的收藏
配置 Harness
Agent 记忆
复制全文
下载 pdf
我的收藏
Agent 记忆
火山引擎 OpenViking Context 为 Agent Plan Harness 层提供 Agent 记忆服务。OpenViking Context 是基于 开源 OpenViking 内核构建的全托管云服务，是一款面向 AI Agents 的上下文数据库，以“虚拟文件系统 + 分层上下文 + 目录递归检索 + 可观测与自迭代”为核心思想，通过将 Memory、Resource、Skill 统一抽象为文件的理念，解决 AI Agent 在执行对话和长周期任务时的复杂上下文管理难题，为 AI Agent 开发者提供结构化、可追溯且低成本的上下文工程解决方案。​
能力介绍​
OpenViking Context 适用于需要长程记忆、复杂知识管理和多 Agent 协作的各类 AI 应用场景，核心价值在于提供结构化、可迭代的上下文管理能力。​
  • Agent 长期记忆升级：作为 Agent 产品的记忆插件，为 Agent 提供记忆沉淀、检索和自进化能力，解决长周期任务中常见的遗忘和高昂成本问题。​
  • 全局知识资产沉淀：支持将多个代码仓库、文档库等知识源统一导入 OpenViking Context，构建可语义检索的知识库，赋能代码助手与研发场景。​
  • 多 Agent 协作共享：多个独立 Agent 可共享同一个 OpenViking Context 实例作为记忆与知识中枢，实现高效协同。​
  • 多租户安全隔离：利用多租户共享与隔离能力，为团队或企业构建安全可控的知识与记忆中心，让智能体在可控的上下文环境中执行任务。​
使用限制​
  • 仅支持完成了实名认证的企业用户和个人用户使用。​
  • 仅支持在北京地域使用 Agent Plan 套餐的 AFP 额度抵扣火山引擎 OpenViking Context 资源的使用费用。​
  • 仅支持 Agent Plan 、OpenViking Context 个人版。​
  • 如果您是子账号，首次使用时需联系主账号授权 VikingdbFullAccess 策略。​
  • 火山引擎官网账号未欠费（账户余额 ≥ 0）。​
使用 OpenViking Context​
步骤一：订阅套餐并开通 Agent 记忆​
  1. 在 开通管理-Agent Plan 页面购买 Agent Plan 套餐。套餐说明参见套餐概览。​
  1. 在控制台单击Harness，开启 Agent 记忆的抵扣开关。​
  • ​memory1.png​​
  • ​
步骤二：创建数据库​
在Harness区域，找到 Agent 记忆卡片，单击配置使用进入 OpenViking Context 页面，根据页面提示开通服务并创建数据库。​
说明​
创建数据库的页面左下角会展示 AFP 抵扣信息。​
​memory2.png​​
步骤三：接入 Agent​
OpenViking Context 支持 MCP、CLI、API、SDK 接入您的自研 Agent 框架，同时对主流 Agent 框架进行生态适配。​
说明​
当前文档仅展示了常用 Agent 接入步骤，更多 Agent 的接入步骤可在 OpenViking Context 控制台 页面单击接入 Agent查看。​
​image-20260619-205438-901.png​​
​
认证说明​
Agent 接入 OpenViking 时，必须使用 OpenViking 的 API Key 作为唯一认证，并关联到对应的数据。​
OpenViking API Key 可在 OpenViking Context 控制台 的用户管理页面查看与复制。​
​image-20260619-205141-807.png​​
主流 Agent 集成​
​
Claude Code
OpenClaw
Hermes Agent
Codex
​
说明​
集成方式：Plugin 接入，为 Claude Code 添加跨项目、跨会话（session）的长期记忆功能。安装完成后，每轮对话均会自动召回相关记忆并捕获新内容，无需模型主动调用任何工具。​
步骤 1：安装​
​
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh)​
​
该脚本将自动检查依赖项、配置 OpenViking 连接并完成插件安装，支持重复运行（幂等操作）。​
安装完成后，需在当前终端激活 claude 的封装函数（wrapper），或者直接打开一个新的终端窗口：​
​
source ~/.openviking/openviking-repo/examples/claude-code-memory-plugin/setup-helper/wrapper.sh​
​
说明​
通过自定义命令启动 Claude Code？例如包装脚本 cc-custom，或“基础命令 + 子命令”形式的多词启动器——在安装时的“Extra launch commands”一步填入（或运行脚本时传入 OPENVIKING_CC_WRAP_EXTRA='cc-custom'），即可让它们一并注入凭据。​
使用一段时间后，即便在全新的对话中提及过往的话题，Claude Code 也能准确回忆起来。​
步骤 2：验证​
​
type claude​
​
说明​
若输出的是一个路径而非 shell function，说明 wrapper 尚未生效，请先 source 那行 wrapper（或新开一个终端）再启动；否则 claude 会静默连到本地 127.0.0.1 且不带鉴权。​
在 type claude 显示为 shell function 的终端中运行 claude 启动，随后：​
  • 输入 /plugins：在 Installed 列表中应能找到 openviking-memory（其子项 openviking MCP 应显示为已连接状态）。​
  • 输入 /mcp：OpenViking 对应的条目应显示您的服务器 URL 及有效的认证信息。​
  • 输入 /openviking-memory:ov：查看服务器状态、身份信息、召回/注入的统计数据以及功能开关状态。​
  • 若插件未正常工作，可设置环境变量 OPENVIKING_DEBUG=1，并查看日志文件 ~/.openviking/logs/cc-hooks.log 以排查问题。​
​
CLI 接入​
​
手动终端安装
通过 AI Agent 安装
​
步骤1：安装 OpenViking CLI 并进入配置流程​
​
npm i -g @openviking/cli && ov config​
​
步骤2: 配置信息​
按提示填写以下信息：​
  • Base URL：https://api.vikingdb.cn-beijing.volces.com/openviking​
  • API Key：在 OpenViking Context 控制台的用户管理页面复制 API Key，具体参见认证说明。​
步骤3：查看 CLI 用法​
​
ov --help​
​
​
MCP 接入​
步骤1：MCP 配置​
以下为 MCP 配置示例，将 <OPENVIKING_API_KEY> 替换为 OpenViking API Key，具体参见认证说明。​
​
{​
"mcpServers": {​
"ov-mcp-server": {​
"url": "https://api.vikingdb.cn-beijing.volces.com/openviking/mcp",​
"headers": {​
"Authorization": "Bearer <OPENVIKING_API_KEY>"​
}​
}​
}​
}​
​
步骤2：测试 MCP 工具连通性​
​
ov health​
​
SDK 接入​
步骤1：安装 OpenViking​
​
pip install openviking --upgrade --force-reinstall​
​
步骤2：初始化客户端​
将控制台用户管理页面中展示的 API Key 复制到你的 Agent 运行环境中，建议通过环境变量或安全配置中心进行注入，而不要直接硬编码在代码里。具体参见认证说明。​
​
export OPENVIKING_API_KEY="your-api-key"​
​
​
import os​
import openviking as ov​
​
client = ov.SyncHTTPClient(​
url="https://api.vikingdb.cn-beijing.volces.com/openviking",​
api_key=os.environ["OPENVIKING_API_KEY"],​
agent_id="your-agent-id", # 自定义 agent_id，用于隔离 Agent 侧上下文​
timeout=120.0,​
)​
client.initialize()​
​
步骤3：写入资源​
资源写入用于把外部知识导入 OpenViking Context。SDK 可以直接接收本地文件路径、目录路径或远端 URL，并自动处理上传细节。​
​
file_path = "your-file-path"​
resource_to = "your-resource-path" # e.g. viking://resources/demo/api.md​
reason = "your-reason" # e.g. External API documentation​
​
result = client.add_resource(​
path=file_path,​
to=resource_to,​
reason=reason,​
wait=True,​
)​
​
print(result)​
​
说明​
  • to 必须位于 viking://resources/... 作用域下。​
  • 如果 path 是本地文件，SDK 会自动先上传再调用服务端接口。​
  • 如果 wait=True，接口会等待资源处理完成后再返回，更适合导入后马上检索的场景。​
  • 如果不希望阻塞，也可以使用默认异步模式，然后显式调用 client.wait_processed()。​
步骤4：写入记忆​
记忆写入建议通过会话方式完成。下面示例演示如何将一条用户消息写入会话，并通过提交触发后续记忆提取。​
​
text = "your-message-text" # e.g. I am a developer​
​
session = client.create_session()​
session_id = session["result"]["session_id"] if "result" in session else session["session_id"]​
​
client.add_message(​
session_id,​
"user",​
parts=[{"type": "text", "text": text}],​
)​
​
result = client.commit_session(session_id)​
print(result)​
​
API 接入​
如果您希望通过平台网关、工作流引擎、低代码平台直接调用接口，推荐使用 HTTP API 接入。​
步骤1：写入资源​
对于 HTTP 接口，本地文件不能直接作为path传给 /api/v1/resouces，需先上传本地文件获取temp_file_id，再调用 /api/v1/resouces。​
​
import json​
from pathlib import Path​
​
import requests​
​
url = "https://api.vikingdb.cn-beijing.volces.com/openviking"​
api_key = "your-api-key" #可在用户管理页面复制​
agent_id = "your-agent-id" #自定义agent-id​
file_path = Path("your-file-path") # e.g. test.txt​
resource_to = "your-resource-path" # e.g. viking://resources/demo/test.txt​
reason = "your-reason" # e.g. External API documentation​
​
headers = {​
"Content-Type": "application/json",​
"Authorization": "Bearer " + api_key,​
"X-OpenViking-Agent": agent_id,​
}​
​
​
def post_json(path: str, payload: dict, timeout: float):​
response = requests.post(​
f"{url}{path}",​
headers=headers,​
json=payload,​
timeout=timeout,​
)​
response.raise_for_status()​
return response.json()​
​
​
with file_path.open("rb") as file:​
result = requests.post(​
f"{url}/api/v1/resources/temp_upload",​
headers={​
"Authorization": "Bearer " + api_key,​
"X-OpenViking-Agent": agent_id,​
},​
files={"file": (file_path.name, file, "application/octet-stream")},​
timeout=120.0,​
)​
​
result.raise_for_status()​
result = result.json()​
print(json.dumps(result, ensure_ascii=False, indent=2))​
​
temp_file_id = result["result"]["temp_file_id"]​
​
result = post_json(​
"/api/v1/resources",​
{​
"temp_file_id": temp_file_id,​
"source_name": file_path.name,​
"to": resource_to,​
"reason": reason,​
},​
120.0,​
)​
​
print(json.dumps(result, ensure_ascii=False, indent=2))​
​
步骤2：写入记忆​
通过 API 写入记忆时，同样遵循“创建会话 - 添加消息 - 提交会话”的流程。​
​
import json​
import requests​
​
url = "https://api.vikingdb.cn-beijing.volces.com/openviking"​
api_key = "your-api-key" #可在【用户管理页面】复制​
agent_id = "your-agent-id" #自定义agent-id​
text = "your-message-text" # e.g. I am a developer​
​
headers = {​
"Content-Type": "application/json",​
"Authorization": "Bearer " + api_key,​
"X-OpenViking-Agent": agent_id,​
}​
​
​
def post_json(path: str, payload: dict, timeout: float):​
response = requests.post(​
f"{url}{path}",​
headers=headers,​
json=payload,​
timeout=timeout,​
)​
response.raise_for_status()​
return response.json()​
​
​
session = post_json("/api/v1/sessions", {}, 360.0)​
session_id = session["result"]["session_id"]​
​
post_json(​
f"/api/v1/sessions/{session_id}/messages",​
{​
"role": "user",​
"parts": [{"type": "text", "text": text}],​
},​
360.0,​
)​
​
result = post_json(​
f"/api/v1/sessions/{session_id}/commit",​
{"telemetry": False},​
360.0,​
)​
​
print(json.dumps(result, ensure_ascii=False, indent=2))​
​
计费说明​
  • 未开启超额后付费：请求调用产生的费用使用套餐内 AFP 进行抵扣，不消耗其他资源包或账户余额。抵扣规则参见 套餐内 AFP 抵扣规则。​
  • 开启超额后付费：在套餐周期内额度未用尽时优先抵扣套餐额度；当套餐周期内额度用尽时，无需修改任何配置信息，系统将自动切换至超额后付费模式继续使用，并产生后付费账单。具体规则与操作参见 超额后付费规则 和 超额后付费管理。​
实践教程​
搭建销售团队工作台​
基于 Agent Plan + Codex + AI Native 应用开发底座 + 豆包搜索 + 专业数据集 + Agent 记忆，把散落在飞书会话、云文档里的私域销售资料和外部专业信息，搭成一个能查公司、看档案、问历史的销售团队定制工作台。​
​
‌​
​
常见问题​
  • 我想保留 OpenViking 服务，仅想从 Agent Plan 抵扣切换到官网付费，要如何操作？​
  • 我想保留 OpenViking 服务，仅想从官网付费切换到 Agent Plan 抵扣，要如何操作？​
  • 下单个人版 Agent Plan 套餐，并在 Agent Plan 页面开启抵扣即可。​
  • Agent Plan 额度不足且未开通超额后付费，导致服务无法使用，如何恢复？​
  • 开启超额后付费立即恢复，通过官网出账；或升级 Agent Plan 套餐扩充 AFP 额度，待下一个扣费周期扣减成功即可恢复，最长 1 小时；或升级后 oncall 客服人工恢复。​
服务协议​
​
最近更新时间：2026.11.03 15:23:08
这个页面对您有帮助吗？
有用
有用
无用
无用