OpenViking 与 OpenClaw 端到端记忆测试框架实战：从环境搭建到记忆 CRUD 自动化验证

OpenViking 与 OpenClaw 端到端记忆测试框架实战从环境搭建到记忆 CRUD 自动化验证【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenClaw-OpenVikingoc2ov端到端自动化测试框架用于验证 AI Agent 记忆的读写、增删改查等核心场景覆盖从写入用户信息→记忆同步→跨轮次召回→更新覆盖→删除失效的完整生命周期。本文基于 tests/oc2ov_test/README.md 并结合作业仓库内的真实源码实现完整讲解前置条件、环境搭建、CLI/HTTP 两种驱动方式、配置项、断言体系与用例扩展方法帮助你直接落地一套可复用的 Agent 记忆回归测试方案。测试框架要解决什么问题OpenClaw 与 OpenViking 的协同链路中记忆是核心资产用户在会话中暴露的个人信息、偏好、上下文需要被 OpenViking 提取、持久化并在后续会话中被准确召回。这套测试框架把这一链路拆成可自动验证的端到端场景记忆写入验证用户提供的信息能否被结构化写入记忆记忆同步验证写入后记忆是否能在指定时间内完成同步、可被检索记忆读取/更新/删除验证 CRUD 全流程包括更新后旧值是否被覆盖删除后是否不再可查复杂场景多用户切换、增量信息补充、特殊字符与边界情况。框架提供两种驱动 OpenClaw 的方式**CLI 方式推荐**与HTTP API 方式。CLI 方式通过openclaw agent --session-id ... --message ... --json直接发起请求天然支持--session-id保持会话连续性比 HTTP 方式更稳定因此 README 明确建议优先使用 CLI 方式。前置条件跑通测试前需要准备什么1. 安装 OpenClaw先在本地安装并验证 OpenClawopenclaw --version2. 安装 OpenViking 插件确保 OpenViking 插件已安装且配置正确openclaw plugins list3.可选配置 OpenClaw HTTP 通信仅当需要使用 HTTP API 方式时才需要。在 OpenClaw 配置文件~/.openclaw/openclaw.json中添加/修改{ gateway: { http: { endpoints: { responses: { enabled: true } } } } }配置后重启 Gatewayopenclaw gateway restart4. 启动 OpenClaw 服务# 检查服务状态 openclaw gateway status # 如果未运行启动服务 openclaw gateway从源码看CLI 客户端会把 session 锁文件定位到~/.openclaw/agents/*/sessions/{session_id}.jsonl.lock见 utils/openclaw_cli_client.py因此 OpenClaw 的数据目录必须是默认的~/.openclaw否则锁等待逻辑无法生效。快速开始一键搭建测试环境并运行方法一使用快速脚本推荐# 1. 设置环境自动创建虚拟环境并安装依赖 ./setup.sh # 2. 运行测试带报告生成使用 CLI 方式 ./run.sh -rsetup.sh 的逻辑是若venv/不存在则创建虚拟环境 → 激活 → 升级 pip → 安装requirements.txt依赖 → 安装pytest-html报告插件。run.sh 则会在非虚拟环境时自动source venv/bin/activate并支持-h/-a/-p/-c/-x/-v/-r参数组合。方法二手动设置# 1. 创建虚拟环境 python -m venv venv # 2. 激活虚拟环境 source venv/bin/activate # Linux/Mac # 或 venv\Scripts\activate # Windows # 3. 安装依赖 pip install -r requirements.txt pip install pytest-html # 4. 运行测试使用 CLI 方式推荐 pytest tests/p0/test_memory_crud.py -v --htmlreports/test_report.html --self-contained-html说明README 中提到的test_cli_pytest.py、test_pytest.py、test_cli_single.py属于早期版本入口当前仓库中统一由 run_tests.py 作为 Python 入口它支持--type all|p0|v2与--test指定单个用例# 运行全部测试 python run_tests.py --type all # 仅运行 P0 核心 python run_tests.py --type p0 # 运行指定用例例如记忆更新验证 python run_tests.py --test tests.p0.test_memory_crud.TestMemoryUpdate项目结构与各模块职责当前仓库中oc2ov_test的实际结构如下与 README 早期描述略有演进以仓库为准tests/oc2ov_test/ ├── config/ │ ├── __init__.py │ └── settings.example.py # 配置示例复制为 settings.py 使用 ├── tests/ │ ├── __init__.py │ ├── base_test.py # 测试基类HTTP 方式 │ ├── base_cli_test.py # 测试基类CLI 方式推荐增强版 │ ├── test_cli_diagnostics.py # CLI 故障诊断测试 │ ├── p0/ # P0 核心质量保障测试 │ │ ├── test_memory_crud.py # 记忆增删改查 │ │ ├── test_context_engine.py # Context Engine 核心链路 │ │ └── test_memory_v2_full_suite.py │ ├── advanced/ # 进阶/增强功能测试 │ ├── long_term/ # 长对话记忆测试 │ ├── session/ # 会话持久化测试 │ └── skill/ # 技能记忆测试 ├── utils/ │ ├── __init__.py │ ├── openclaw_client.py # OpenClaw HTTP 客户端封装 │ ├── openclaw_cli_client.py # OpenClaw CLI 客户端封装推荐 │ ├── cli_diagnostics.py # CLI 失败信息格式化诊断 │ ├── assertions.py # 断言工具关键词/相似度 │ ├── logger.py # 日志工具 │ └── test_utils.py # Session ID 管理/重试/智能等待/测试数据 ├── conftest.py # Pytest 配置报告美化 ├── run_tests.py # 测试运行入口--type/--test ├── run.sh / setup.sh # 快速运行/环境设置脚本 ├── requirements.txt ├── pyproject.toml └── ASSERTIONS_GUIDE.md # 断言使用详细指南其中 tests/base_cli_test.py 是 CLI 方式的核心基类源码注释明确列出了四大增强能力Session ID 自动管理、智能等待策略替代固定等待、失败自动重试机制、测试数据驱动下文会逐一展开。配置说明settings.py 中的核心参数将 config/settings.example.py 复制为config/settings.py并填入真实配置。三组核心配置如下import os BASE_DIR os.path.dirname(os.path.dirname(os.path.abspath(__file__))) # OpenClaw 服务配置 OPENCLAW_CONFIG { url: http://127.0.0.1:18789/v1/responses, # HTTP 方式的服务端点 auth_token: Bearer YOUR_AUTH_TOKEN_HERE, # 请替换为您自己的认证token agent_id: main, # 目标 Agent model: YOUR_MODEL_NAME_HERE, # 请替换为您自己的模型名称 timeout: 120, # HTTP 请求超时秒 } # 测试配置 TEST_CONFIG { wait_time: 30, # 等待记忆同步的时间秒示例中为 30 log_dir: os.path.join(BASE_DIR, logs), # 日志目录 report_dir: os.path.join(BASE_DIR, reports) # HTML 报告目录 } # 日志配置console 文件双输出 LOGGING_CONFIG { version: 1, disable_existing_loggers: False, formatters: { standard: {format: %(asctime)s - %(name)s - %(levelname)s - %(message)s}, detailed: { format: %(asctime)s - %(name)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s }, }, handlers: { console: {class: logging.StreamHandler, formatter: standard, level: INFO}, file: { class: logging.FileHandler, filename: os.path.join(TEST_CONFIG[log_dir], test_run.log), formatter: detailed, level: DEBUG, encoding: utf-8, }, }, root: {handlers: [console, file], level: DEBUG}, }参数含义与影响wait_time记忆同步等待时长直接决定测试对写入→可召回延迟的容忍度。基类中wait_for_sync()会取max(传入值或 wait_time, 5)作为最小等待MIN_SYNC_WAIT_SECONDS 5并对锁释放做轮询等待见 tests/base_cli_test.pytimeoutHTTP 请求超时CLI 客户端默认超时为 180 秒send_message()可单独传入覆盖见 utils/openclaw_cli_client.pyLOGGING_CONFIG控制台输出 INFO 级、文件输出 DEBUG 级便于排查 Agent 响应细节。运行测试的三种方式推荐CLI 方式更稳定# 运行全部 CLI 测试带报告 pytest tests/p0/ -v --htmlreports/test_report_cli.html --self-contained-html # 运行单个 CLI 测试 pytest tests/p0/test_memory_crud.py::TestMemoryUpdate::test_memory_update_verify -v # 使用统一入口 python run_tests.py --test tests.p0.test_memory_crud.TestMemoryUpdate使用 HTTP 方式pytest tests/base_test.py -v --htmlreports/test_report.html --self-contained-html使用快速脚本 run.sh./run.sh -h # 查看帮助 ./run.sh -r # 运行全部测试带报告 ./run.sh -p # 仅运行 P0 级测试 ./run.sh -c # 仅运行 CRUD 操作测试 ./run.sh -x # 仅运行复杂场景测试 ./run.sh -v # 详细输出模式 ./run.sh -v -r # 组合使用详细输出 生成报告注意run.sh内部通过pytest tests/p0/、tests/crud/、tests/complex/目录筛选测试其中 CRUD 与复杂场景目录在当前仓库中已演进至tests/p0/test_memory_crud.py与tests/advanced/等实际目录使用时以仓库当前目录为准-r参数对应--htmlreports/test_report.html --self-contained-html自包含 HTML方便分享。查看测试报告测试报告生成在reports/目录可直接在浏览器打开# macOS open reports/test_report_cli.html # Linux xdg-open reports/test_report_cli.html # Windows start reports/test_report_cli.html报告包含环境信息OpenClaw 版本、OpenViking 状态、详细的中文测试描述、测试执行结果与日志、通过/失败用例统计。断言体系如何验证 Agent 的回复符合预期1. 关键词断言assertKeywordsInResponse验证响应中包含全部或任意关键词# 验证响应中包含所有关键词 self.assertKeywordsInResponse( response, [小明, 30岁, 测试开发], require_allTrue ) # 验证响应中包含任意一个关键词 self.assertKeywordsInResponse( response, [30, 三十], require_allFalse )2. 任意关键词组断言assertAnyKeywordInResponse按组组织候选表述每组中命中任意一个即通过适合 LLM 回复措辞不确定的场景# 验证响应中包含姓名、年龄或职业中的任意一个 self.assertAnyKeywordInResponse( response, [ [小明, 小红], # 第一组姓名 [30, 25, 28], # 第二组年龄 [测试开发, 产品经理] # 第三组职业 ] )3. 文本相似度断言assertSimilarity基于difflib.SequenceMatcher计算序列相似度实现见 utils/assertions.py验证回复与期望文本的相似度不低于阈值# 验证响应文本与期望文本相似度 70% self.assertSimilarity( response, 你叫小明今年30岁住在华东区职业是测试开发, min_similarity0.7 )min_similarity取值范围 0.0-1.0默认 0.6。当多个期望表述差异较大时建议用关键词组断言而非相似度断言。响应格式的兼容处理AssertionHelper.extract_response_text()支持多种响应结构utils/assertions.py纯字符串{output: ...}/{message: ...}/{content: ...}/{text: ...}OpenAI 格式{choices: [{message: {content: ...}}]}{result: {payloads: [...]}}等嵌套格式其他格式自动转字符串。此外它还会剥离 LLM 响应中残留的工具调用结果前缀如[{name:none}] 您的临时密码...→您的临时密码...避免工具调用 JSON 干扰关键词匹配见 utils/assertions.py。针对 LLM 不稳定响应的容错设计基类中的断言方法会先调用_is_llm_unstable_response()检测响应是否为 LLM 不稳定输出包含idle timeout、couldnt generate a response、please try again、NO_REPLY、命令执行超时等标志或仅为工具调用残留若是则跳过断言并记 warning而不是误报失败见 tests/base_cli_test.py。这意味着用例天然容忍偶发性的模型超时抖动避免测试挂了但其实是模型没回复的误判。更多断言技巧组合使用、容错性设计、渐进式验证、直接使用AssertionHelper详见 ASSERTIONS_GUIDE.md。测试用例体系覆盖哪些记忆场景P0 质量保障类测试记忆写入验证用户基本信息的结构化写入如我叫小李今年28岁住在西南区职业是数据分析师记忆读取验证写入的信息可被查询召回记忆更新先写入初始信息再更新年龄/职业/地址验证更新生效且旧值被覆盖见 tests/p0/test_memory_crud.py 中TestMemoryUpdate、TestMemoryUpdateOverwrite记忆删除写入密码信息 → 验证存在 → 请求删除并 commit → 验证不知道/不存在/已删除等否定性回复TestMemoryDelete的断言关键词组涵盖中英文多种否定表述见 tests/p0/test_memory_crud.py。Context Engine 核心交互链路测试tests/p0/test_context_engine.py 覆盖更深层的链路assemble()——历史组装回放compact()——对话超阈值后压缩归档跨 session recall——不同 session 间的记忆检索注入memory_recall显式搜索——模型主动调用 memory_recall 工具ov_archive_expand展开——模型主动展开 archive 查看原始对话session 隔离——不同 session 的记忆互不污染。该文件中的OVSessionVerifier直接通过 OpenViking HTTP API默认http://127.0.0.1:1933可用环境变量SERVER_URL覆盖做API 级验证列举 session、查找新增 session、触发/api/v1/sessions/{id}/commit提交、轮询任务状态直到完成从而把对话级断言模型回复含关键词与API 级断言session 状态正确、archive 存在结合起来。前置条件要求在 ECS 上调低commitTokenThreshold如 500以缩短生成 archive 所需的对话轮次。CRUD 与复杂场景TestMemoryRead/TestMemoryUpdate/TestMemoryDelete——记忆读、改、删TestComplexScenarioMultiUsers——多用户切换场景TestComplexScenarioIncrementalInfo——增量信息添加TestComplexScenarioSpecialCharacters——特殊字符与边界情况另有tests/advanced/增强功能、tests/long_term/长对话、tests/session/会话持久化、tests/skill/技能记忆等扩展用例目录。源码级解析测试基类与客户端如何保证稳定性Session ID 自动管理基类在setUpClass中为每个测试类生成唯一的session_id基于类名的确定性 UUID并在类结束tearDownClass时清理注册。SessionIdManagerutils/test_utils.py支持单例注册表且在 CI 环境检测CI、GITHUB_ACTIONS、GITLAB_CI等环境变量下改用基于名称的确定性 UUID避免 session 数量爆满。其 UUID 格式的选择有明确原因OpenClaw 会将非 UUID 格式的 session ID 做 SHA256 转换使用 UUID 格式可确保直接使用、不做转换。Session 锁等待与 CLI 调用OpenClawCLIClient.send_message()utils/openclaw_cli_client.py执行的真实命令为openclaw agent --session-id session_id --message message --json如需指定 Agent则在openclaw后插入--agent agent_id。发送前会调用_wait_for_session_lock_release()轮询等待*.jsonl.lock文件释放15 秒超时、0.5 秒轮询间隔发送完成后再次等待锁释放从根因上规避session file locked错误。返回码非 0 或空输出时会通过cli_diagnostics.format_openclaw_cli_failure()输出格式化诊断信息。智能等待与重试机制SmartWaiter默认超时为wait_time * 3、轮询间隔 2 秒smart_wait_for_sync()支持传入检查消息与期望关键词通过轮询发送检查消息 → 断言关键词是否命中来判断记忆是否已同步轮询间隔最小 3 秒RetryManager最大重试 3 次、基础延迟 1 秒send_and_retry_on_timeout()专门处理 LLM 超时/空响应/纯工具调用三类不稳定输出最多重试 3 次、间隔 8 秒对subprocess命令执行超时可能意味着 auto-recall 上下文过大则不再重试直接返回以便人工排查。这些机制使整套测试在真实 LLM 服务波动下仍能产出可信结果。如何扩展新的测试用例在tests/相应目录下创建新的测试文件如tests/advanced/继承BaseOpenClawCLITest基类推荐 CLI 方式使用self.send_and_log()发送消息自动记录请求/响应日志使用self.wait_for_sync()/self.smart_wait_for_sync()等待记忆同步使用断言方法验证响应在 run_tests.py 的get_test_suite()中注册测试套件。最小示例from tests.base_cli_test import BaseOpenClawCLITest class TestMyNewFeature(BaseOpenClawCLITest): 测试目标我的新功能验证 测试场景描述测试场景 def test_something(self): 测试场景具体场景描述 self.logger.info(开始测试) self.send_and_log(我叫测试用户) self.wait_for_sync() # 验证响应 response self.send_and_log(我是谁) self.assertKeywordsInResponse(response, [测试用户])如需数据驱动可使用基类提供的get_test_data()/run_with_test_data()配合TestDataManager管理批量测试数据。日志与虚拟环境测试运行日志保存在logs/test_run.logDEBUG 级控制台同步输出 INFO 级日志日志格式包含文件名与行号%(filename)s:%(lineno)d便于快速定位失败用例的代码位置项目使用 Python 虚拟环境隔离依赖venv/目录已加入 .gitignore、setup.sh一键设置、run.sh一键运行。建议始终在虚拟环境中运行测试避免依赖冲突。注意事项与故障排查注意事项会话管理CLI 方式下每个测试类使用独立session-id避免会话冲突等待时间根据实际环境调整config/settings.py中的wait_time确保记忆同步完成示例配置为 30 秒超时设置CLI 客户端默认超时 180 秒可按需调整基类send_and_log(timeout...)可单独覆盖服务状态确保 OpenClaw Gateway 正常运行测试前用openclaw gateway status检查会话锁定若遇到 session file locked 错误检查是否有其他进程使用相同 session-id。常见问题与解决方案问题解决方案每次发送消息后需要重启服务改用 CLI 方式其--session-id参数可保持会话连续性测试超时增加OPENCLAW_CONFIG[timeout]与TEST_CONFIG[wait_time]检查 OpenClaw 服务是否正常会话文件锁定检查是否有其他测试进程在运行换用不同 session-id重启 OpenClaw GatewayLLM 偶发超时/空回复导致断言失败使用send_and_retry_on_timeout()发送或依赖基类的 LLM 不稳定响应跳过机制这套框架的核心价值在于把Agent 记忆是否真正写入、同步、可召回、可更新、可删除这类原本依赖人工抽查的质量问题变成可重复执行的自动化回归测试并且通过 session 隔离、锁等待、智能等待、重试与容错断言让测试结果在真实 LLM 服务的波动下依然稳定可信。如果你正在为 Agent 产品搭建记忆质量保障体系可以直接复用 tests/oc2ov_test 下的整套结构与代码作为起点。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考