618a82a5创建于 4月25日历史提交

oG-Memory + OpenClaw 联调测试文档

本文档说明如何使用工作区中的 oG-Memory 代码，通过 deploy/ 目录完成部署，并使用 locomo-eval-kit/scripts/run_eval_small.sh 进行联调测试。

适用目标：

使用 oG-Memory 作为 OpenClaw 的记忆后端
不再依赖 OpenViking 直写路径
使用 LoCoMo small 数据集完成一轮完整测试

1. 当前测试链路

当前工作区中的组件关系如下：

oG-Memory/deploy/ 负责部署 oG-Memory 服务和 OpenClaw Gateway 容器
oG-Memory/openclaw_context_engine_plugin/ 负责把 oG-Memory 以 Context Engine 的方式接到 OpenClaw
locomo-eval-kit/scripts/run_eval_small.sh 负责跑 LoCoMo small 数据集评测

在这套集成方式下，推荐测试链路是：

先部署 oG-Memory + OpenClaw
确认 OpenClaw Gateway 和 oG-Memory 健康检查通过
使用 run_eval_small.sh --import-mode claw 走 OpenClaw 会话导入
再执行 QA、Judge、统计

也就是说，对 oG-Memory 来说，推荐使用 claw 模式，不推荐使用 ov 模式。

2. 重要说明

在开始之前，先注意这几个和当前代码相关的事实：

2.1 `run_eval_small.sh` 推荐使用 `claw`

当前脚本支持：

ov
claw
both
skip

但你现在的 oG-Memory 是通过 OpenClaw 插件接入，不是通过 import_to_ov.py 直接写入，所以：

推荐：--import-mode claw
可选：--import-mode skip
不推荐：--import-mode ov
不推荐：--import-mode both

2.2 默认端口存在不一致

当前默认值有冲突：

oG-Memory/deploy/deploy.env 中 OpenClaw 默认端口是 18789
locomo-eval-kit/scripts/run_eval_small.sh 中默认 Gateway 地址是 http://127.0.0.1:19789

因此你需要二选一：

在部署时把 OpenClaw 端口改成 19789
或运行评测时显式传入 --gateway-url http://127.0.0.1:18789

为了少改部署文件，本文档默认采用第 2 种方式。

2.3 脚本里仍残留 OpenViking 文案

run_eval_small.sh 和 eval.py 里还有一些 OpenViking 相关参数和日志，例如：

--ov-url
--memory-mode openviking
OV task token 查询逻辑

这不代表当前测试必须使用 OpenViking。对于 oG-Memory + OpenClaw 联调，核心是：

导入阶段通过 OpenClaw 完成
记忆写入由 OpenClaw 插件触发到 oG-Memory
QA 阶段通过 OpenClaw Gateway 访问

但在日志里，你仍然可能看到一些与 OV 兼容逻辑有关的提示。只要导入、QA 和结果文件正常生成，这类提示通常不是主路径阻塞。

3. 前置条件

建议在 Linux / WSL / 远程 Linux 机器上执行部署与测试。

3.1 系统和工具

至少需要：

Bash
Docker
curl
Python 3
能运行 run_eval_small.sh

如果是在 Windows IDE 中操作，推荐方式是：

在 WSL 中执行
或在远程 Linux 服务器执行

3.2 目录约定

下面命令默认你的工作区根目录是：

cd /path/to/locomo-eval-kit

并且目录结构类似：

locomo-eval-kit/
├── locomo-eval-kit/
└── oG-Memory/

4. 第一步：准备 oG-Memory 部署配置

进入部署目录：

cd oG-Memory/deploy

4.1 编辑 `deploy.env`

打开：

vim deploy.env

重点确认这些字段：

LLM_PROVIDER="..."
LLM_API_KEY="..."
LLM_BASE_URL="..."
LLM_MODEL="..."

OPENCLAW_HOST_IP="127.0.0.1"
OPENGAUSS_HOST_IP="127.0.0.1"
OG_HOST_PORT="15432"

ENABLE_OPENGAUSS="true"
OPENCLAW_HOME_DIR="/your/path/openclaw-home"
AGFS_DATA_DIR="/your/path/agfs-data"

建议重点检查：

LLM_API_KEY 是否已替换为真实值
LLM_BASE_URL / LLM_MODEL 是否可用
OPENCLAW_HOME_DIR 是否设置了持久化目录
AGFS_DATA_DIR 是否设置了持久化目录

4.2 创建 `ogmemory.yaml`

如果还没有该文件：

cp ogmemory.example.yaml ogmemory.yaml

再编辑：

vim ogmemory.yaml

建议至少确认这些项目：

llm
embedding
vector_db
service.http_port
identity
auth

如果你使用 deploy.env 里的 ${ENV_VAR} 引用方式，通常不需要把 LLM 信息重复写死。

5. 第二步：部署 oG-Memory + OpenClaw

仍在 oG-Memory/deploy 目录下。

5.1 完整部署

如果启用了 openGauss：

bash deploy.sh -password "YourStrongPassword@2026"

如果 ENABLE_OPENGAUSS="false"：

bash deploy.sh

5.2 查看部署状态

bash deploy.sh --status

预期至少能看到：

oG-Memory 容器 running
OpenClaw 容器 running

5.3 查看容器日志

docker logs ogmem_auto -f

docker logs openclaw_ogmem_auto -f

如果你的容器名不同，请以 deploy.env 中的配置为准。

6. 第三步：验证服务健康状态

6.1 检查 oG-Memory 健康状态

curl http://127.0.0.1:8090/api/v1/health

如果 service.http_port 或 OGMEM_HTTP_PORT 改过，请替换成你的端口。

6.2 检查 OpenClaw 健康状态

如果部署默认端口未改：

curl http://127.0.0.1:18789/health

如果你在 deploy.env 中改了 GATEWAY_PORT，这里也要一起改。

6.3 检查插件是否生效

建议观察 OpenClaw 日志里是否能看到和 og-memory、context engine、memory-api 相关的日志。

例如：

og-memory
memory-api
after_turn
assemble
commit_messages_to_memory

如果能看到这类日志，说明 OpenClaw 已经把请求转到了 oG-Memory 插件链路。

7. 第四步：准备 locomo-eval-kit 测试环境

进入评测脚本目录：

cd ../../locomo-eval-kit/scripts

确认 Python 依赖已安装：

pip install requests openai python-dotenv

如果要跑 Judge，还需要准备 Judge 使用的 API Key，例如：

export ARK_API_KEY="your_judge_key"

或者：

export OPENAI_API_KEY="your_judge_key"

同时设置 OpenClaw Gateway Token：

export OPENCLAW_GATEWAY_TOKEN="your_gateway_token"

这个值需要和 deploy.env 中的 OPENCLAW_GATEWAY_TOKEN 保持一致。

8. 第五步：先做一次最小连通性验证

在正式跑 small 之前，推荐先手动打一条健康检查命令，再决定是否继续。

8.1 查看脚本默认行为

当前 run_eval_small.sh 默认会访问：

Gateway: http://127.0.0.1:19789

但你的 deploy/ 默认是：

Gateway: http://127.0.0.1:18789

因此运行时要显式传 --gateway-url。

8.2 推荐先跑 `case0`

如果你愿意先做小规模验证：

./run_eval_case0.sh \
  --import-mode claw \
  --gateway-url http://127.0.0.1:18789 \
  --gateway-token "$OPENCLAW_GATEWAY_TOKEN" \
  --skip-judge

如果这一步成功，再跑 small 会稳很多。

9. 第六步：正式运行 `run_eval_small.sh`

9.1 推荐命令

对 oG-Memory + OpenClaw 联调，推荐命令如下：

./run_eval_small.sh \
  --import-mode claw \
  --gateway-url http://127.0.0.1:18789 \
  --gateway-token "$OPENCLAW_GATEWAY_TOKEN"

这条命令会执行：

通过 OpenClaw 会话导入 LoCoMo small 数据
让 OpenClaw 在导入过程中通过插件把记忆写入 oG-Memory
再通过 QA 阶段向 OpenClaw Gateway 发问
使用 Judge 评分
统计结果

9.2 如果暂时不想跑 Judge

./run_eval_small.sh \
  --import-mode claw \
  --gateway-url http://127.0.0.1:18789 \
  --gateway-token "$OPENCLAW_GATEWAY_TOKEN" \
  --skip-judge

9.3 如果只想看导入 + QA

./run_eval_small.sh \
  --import-mode claw \
  --gateway-url http://127.0.0.1:18789 \
  --gateway-token "$OPENCLAW_GATEWAY_TOKEN" \
  --skip-judge \
  --skip-stat

9.4 如果已经导入过，只想重跑 QA / Judge

./run_eval_small.sh \
  --import-mode skip \
  --gateway-url http://127.0.0.1:18789 \
  --gateway-token "$OPENCLAW_GATEWAY_TOKEN"

9.5 如果需要更稳的低并发模式

./run_eval_small.sh \
  --import-mode claw \
  --gateway-url http://127.0.0.1:18789 \
  --gateway-token "$OPENCLAW_GATEWAY_TOKEN" \
  --qa-parallel 2 \
  --judge-parallel 2

10. 运行过程中建议同时观察日志

建议开 3 个终端同时观察：

终端 1：运行评测

cd locomo-eval-kit/scripts
./run_eval_small.sh \
  --import-mode claw \
  --gateway-url http://127.0.0.1:18789 \
  --gateway-token "$OPENCLAW_GATEWAY_TOKEN"

终端 2：看 OpenClaw 日志

docker logs openclaw_ogmem_auto -f

终端 3：看 oG-Memory 日志

docker logs ogmem_auto -f

重点观察这些行为是否出现：

OpenClaw 收到会话导入请求
OpenClaw 触发 context engine 生命周期
oG-Memory 收到 after_turn / assemble / commit 相关调用
QA 时能看到召回、拼装上下文或检索相关日志

11. 结果目录与产物

评测完成后，结果一般会在：

locomo-eval-kit/scripts/result/small_时间戳/

常见文件包括：

import_claw.log
qa.log
judge.log
stat.log
qa_results.csv
summary.txt

建议优先看：

11.1 `import_claw.log`

重点确认：

导入阶段是否成功
是否有大量 [ERROR]
是否出现与 Gateway、session、compact 相关的异常

11.2 `qa.log`

重点确认：

QA 请求是否都正常返回
是否有明显的网络错误或超时

11.3 `qa_results.csv`

重点确认：

response 是否有真实回答
是否大量出现 [ERROR]
result 列是否在 Judge 后被填充

11.4 `summary.txt`

重点确认：

是否生成统计
正确率是否可用

12. 推荐的验证标准

如果你要确认 “oG-Memory + OpenClaw + run_eval_small.sh” 联调成功，建议至少满足下面几点：

deploy.sh --status 显示 oG-Memory 和 OpenClaw 容器都在运行
curl /health 能打通
run_eval_small.sh --import-mode claw 能完整执行到结束
qa_results.csv 正常生成
OpenClaw 日志中能看到 context engine 相关调用
oG-Memory 日志中能看到会话写入或检索相关日志
summary.txt 能生成最终统计

13. 常见问题与排查

13.1 `run_eval_small.sh` 连不上 Gateway

常见原因：

你部署的是 18789，但脚本默认访问 19789

解决：

./run_eval_small.sh \
  --import-mode claw \
  --gateway-url http://127.0.0.1:18789 \
  --gateway-token "$OPENCLAW_GATEWAY_TOKEN"

13.2 Gateway Token 错误

现象：

报 --token or OPENCLAW_GATEWAY_TOKEN env var is required
或 HTTP 401 / 403

解决：

确认 deploy.env 中的 OPENCLAW_GATEWAY_TOKEN
确认 shell 中导出的 OPENCLAW_GATEWAY_TOKEN
确认运行命令中传的 --gateway-token 是同一个值

13.3 OpenClaw 能跑，但没走到 oG-Memory

现象：

OpenClaw 有响应
但 oG-Memory 日志里没有任何写入/检索痕迹

排查方向：

检查插件是否正确安装和加载
检查 OpenClaw 容器日志里是否有 og-memory 或 contextEngine 相关错误
检查 openclaw.json 中是否真的启用了 og-memory-context-engine
检查 OGMEM_URL 是否正确

13.4 看到 OpenViking 相关 warning

原因：

locomo-eval-kit 当前脚本仍保留了部分 OpenViking 兼容逻辑

判断原则：

如果导入成功、QA 成功、结果文件正常生成，这类 warning 可以先视为兼容层噪音
如果 warning 直接导致脚本退出，再进一步看 import_claw.log

13.5 Judge 阶段失败

原因通常是：

ARK_API_KEY 或 OPENAI_API_KEY 未设置

解决：

export ARK_API_KEY="your_judge_key"

或者先跳过：

./run_eval_small.sh \
  --import-mode claw \
  --gateway-url http://127.0.0.1:18789 \
  --gateway-token "$OPENCLAW_GATEWAY_TOKEN" \
  --skip-judge

13.6 想重跑导入

./run_eval_small.sh \
  --import-mode claw \
  --gateway-url http://127.0.0.1:18789 \
  --gateway-token "$OPENCLAW_GATEWAY_TOKEN" \
  --force-ingest

如果需要更彻底清理 OpenClaw 会话数据，可在 locomo-eval-kit 根目录执行：

python tools/clean_openclaw.py

注意：

如果你用了容器挂载的 OPENCLAW_HOME_DIR，清理前先确认路径和数据影响范围

14. 一套最短可复制流程

如果你只想按最短路径跑起来，可以按下面做。

14.1 部署

cd oG-Memory/deploy
cp ogmemory.example.yaml ogmemory.yaml
vim deploy.env
vim ogmemory.yaml
bash deploy.sh -password "YourStrongPassword@2026"

14.2 检查

bash deploy.sh --status
curl http://127.0.0.1:8090/api/v1/health
curl http://127.0.0.1:18789/health

14.3 评测

cd ../../locomo-eval-kit/scripts
export OPENCLAW_GATEWAY_TOKEN="your_gateway_token"
./run_eval_small.sh \
  --import-mode claw \
  --gateway-url http://127.0.0.1:18789 \
  --gateway-token "$OPENCLAW_GATEWAY_TOKEN" \
  --skip-judge

14.4 结果

看目录：

locomo-eval-kit/scripts/result/small_*/

优先检查：

import_claw.log
qa.log
qa_results.csv

oG-Memory + OpenClaw 联调测试文档

1. 当前测试链路

2. 重要说明

2.1 run_eval_small.sh 推荐使用 claw

2.2 默认端口存在不一致

2.3 脚本里仍残留 OpenViking 文案

3. 前置条件

3.1 系统和工具

3.2 目录约定

4. 第一步：准备 oG-Memory 部署配置

4.1 编辑 deploy.env

4.2 创建 ogmemory.yaml

5. 第二步：部署 oG-Memory + OpenClaw

5.1 完整部署

5.2 查看部署状态

5.3 查看容器日志

6. 第三步：验证服务健康状态

6.1 检查 oG-Memory 健康状态

6.2 检查 OpenClaw 健康状态

6.3 检查插件是否生效

7. 第四步：准备 locomo-eval-kit 测试环境

8. 第五步：先做一次最小连通性验证

8.1 查看脚本默认行为

8.2 推荐先跑 case0

9. 第六步：正式运行 run_eval_small.sh

9.1 推荐命令

9.2 如果暂时不想跑 Judge

9.3 如果只想看导入 + QA

9.4 如果已经导入过，只想重跑 QA / Judge

9.5 如果需要更稳的低并发模式

10. 运行过程中建议同时观察日志

终端 1：运行评测

终端 2：看 OpenClaw 日志

终端 3：看 oG-Memory 日志

11. 结果目录与产物

11.1 import_claw.log

11.2 qa.log

11.3 qa_results.csv

11.4 summary.txt

12. 推荐的验证标准

13. 常见问题与排查

13.1 run_eval_small.sh 连不上 Gateway

13.2 Gateway Token 错误

13.3 OpenClaw 能跑，但没走到 oG-Memory

13.4 看到 OpenViking 相关 warning

13.5 Judge 阶段失败

13.6 想重跑导入

14. 一套最短可复制流程

14.1 部署

14.2 检查

14.3 评测

14.4 结果

2.1 `run_eval_small.sh` 推荐使用 `claw`

4.1 编辑 `deploy.env`

4.2 创建 `ogmemory.yaml`

8.2 推荐先跑 `case0`

9. 第六步：正式运行 `run_eval_small.sh`

11.1 `import_claw.log`

11.2 `qa.log`

11.3 `qa_results.csv`

11.4 `summary.txt`

13.1 `run_eval_small.sh` 连不上 Gateway