NemoClaw 沙箱中一键部署 Hindsight 持久记忆hindsight-nemoclaw 集成指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读本文围绕仓库中的 hindsight-integrations/nemoclaw 集成讲解如何在 NemoClaw基于 OpenShell 沙箱运行 OpenClaw 的 Agent 平台上为 Agent 接入 Hindsight 持久记忆。文章覆盖从一键命令行npx vectorize-io/hindsight-nemoclaw setup的完整参数与执行流程到手工分步配置创建记忆库、安装/配置hindsight-openclaw插件、编写 OpenShell 网络 egress 策略、重启网关、验证记忆写入与召回并结合 hindsight-integrations/openclaw 插件源码和 nemoclaw 的 CLI 实现 说明底层原理与排障方法。读完你将能在 NemoClaw 沙箱中独立完成 Hindsight 记忆的接入与验证。背景为什么 NemoClaw 沙箱里需要专门的记忆接入方案NemoClaw 在 OpenShell 沙箱中运行 OpenClaw并带有严格的网络 egress 策略默认阻止所有出站流量。这意味着hindsight-openclaw插件对api.hindsight.vectorize.io的出站调用必须被显式加入沙箱的网络策略否则记忆写入会因 HTTP 403 失败OpenClaw 的 LaunchAgent 运行在受限的 macOS 安全上下文中插件若以符号链接方式安装会因无法访问用户目录而报EPERM: operation not permitted, scandir沙箱内通常没有uvx/uv运行本地 daemon因此插件需切换为外部 API 模式external API mode直接调用 Hindsight 云端 API。hindsight-nemoclaw这个包把这些步骤全部自动化安装插件、写入外部 API 模式配置、把 Hindsight egress 规则合并进沙箱策略、重启网关。快速开始一条命令完成接入如果你还没有 Hindsight API Key官方推荐先使用 Hindsight Cloudui.hindsight.vectorize.io 注册即得 Key无需自建基础设施。拿到 Key 后在 NemoClaw 沙箱所在机器上执行npx vectorize-io/hindsight-nemoclaw setup \ --sandbox my-assistant \ --api-token your-api-key \ --bank-prefix my-sandbox该命令会自动完成以下 5 个步骤对应仓库 setup.ts 中runSetup的实现Preflight— 校验openshell与openclaw是否在 PATH 上Install plugin— 执行openclaw plugins install vectorize-io/hindsight-openclawConfigure plugin— 把外部 API 模式配置写入~/.openclaw/openclaw.jsonApply policy— 读取当前沙箱策略合并 Hindsight egress 规则通过openshell policy set重新应用Restart gateway— 执行openclaw gateway restart。注意步骤 4 中openshell policy set是整体替换策略而非补丁式合并因此 CLI 会先读取完整策略再合并见 policy-reader.ts 与 policy-writer.ts避免把已有策略覆盖掉。CLI 参数参考参数必填默认值说明--sandbox name是—NemoClaw 沙箱名称如my-assistant--api-token token是—Hindsight API Key来自 ui.hindsight.vectorize.io--bank-prefix prefix是—记忆库 ID 前缀实际库 ID 为prefix-openclaw--api-url url否https://api.hindsight.vectorize.ioHindsight API 地址--skip-policy否—跳过沙箱网络策略更新会打印手工添加的 policy 块--skip-plugin-install否—跳过插件安装--dry-run否—只预览将发生的变更不实际执行--help/-h否—显示帮助参数解析与缺失校验实现在 cli.ts 的parseArgs中--sandbox、--api-token、--bank-prefix三者缺失时会报错退出源码第 55-65 行。--dry-run模式下除 Preflight 的which校验外所有外部命令安装插件、写配置、policy set、重启网关都不会真正执行只打印将要执行的内容——这一行为被 setup.test.ts 中的does not execute any shell commands in dry-run mode用例明确验证。手动接入六步详解不想用自动化 CLI或想完全理解每一步在做什么可以按 NEMOCLAW.mdhindsight-integrations/nemoclaw/NEMOCLAW.md中的分步指南手工配置。前置条件NemoClaw 已安装并创建好沙箱nemoclaw onboardOpenClaw 已安装brew install openclaw或等价方式一份 Hindsight API Key本地构建好的插件源码若从源码安装需要先npm run build。第一步创建 Hindsight 记忆库Memory Bank插件会把记忆写入一个名为{bankIdPrefix}-openclaw的 bank。当dynamicBankId为false时库 ID 遵循该模式。用curl创建curl -X PUT https://api.hindsight.vectorize.io/v1/default/banks/my-sandbox-openclaw \ -H Authorization: Bearer your-hindsight-api-key \ -H Content-Type: application/json \ -d {mission: Memory bank for my NemoClaw sandbox.}第二步安装插件从源码安装必须以复制方式而非符号链接否则 LaunchAgent 无法访问# 先构建 npm run build # 安装复制不用 --link —— 这是 LaunchAgent 访问的硬性要求 openclaw plugins install /path/to/hindsight-integrations/openclaw或者直接从 npm 安装openclaw plugins install vectorize-io/hindsight-openclaw第三步配置插件外部 API 模式把插件配置写入~/.openclaw/openclaw.json的plugins.entries.hindsight-openclaw{ plugins: { entries: { hindsight-openclaw: { enabled: true, config: { hindsightApiUrl: https://api.hindsight.vectorize.io, hindsightApiToken: your-hindsight-api-key, llmProvider: claude-code, dynamicBankId: false, bankIdPrefix: my-sandbox } } } } }各配置项含义字段值为什么这样设hindsightApiUrlhindsightApiToken外部 API 地址 Key跳过本地 daemon沙箱内无需uvx/uvllmProvider: claude-codeclaude-code无需额外 API Key 即可满足 LLM 检测——Claude Code 已通过沙箱的claude_code策略可用dynamicBankId: falsefalse所有会话写入同一个 bank测试期更易验证bankIdPrefix如my-sandbox最终库 ID 为my-sandbox-openclaw关于一条容易误导的日志网关日志会输出Dynamic bank IDs disabled - using static bank: openclaw这行日志本身有误导性——运行时实际应用的库 ID 会正确带上前缀如my-sandbox-openclaw。可以在完整初始化后的日志中看到[Hindsight] Default bank: my-sandbox-openclaw来确认。源码印证hindsight-openclaw插件的库 ID 推导逻辑在 index.ts 的deriveBankId第 1386-1439 行当dynamicBankId false时走getStaticBankId即bankIdPrefix ? \${bankIdPrefix}-${baseBankId} : baseBankIdDEFAULT_BANK_NAME为openclaw第 576 行。所以bankIdPrefixmy-sandbox时静态库 ID 就是my-sandbox-openclaw与文档描述一致。相关行为在 [index.test.ts](https://link.gitcode.com/i/b2285179fcf39457f98b5d3fb157fc60) 的uses static bankId when dynamicBankId is false 用例中也有覆盖。第四步把 Hindsight 加入沙箱网络策略沙箱默认阻止全部出站流量。先取回当前完整策略保存为 YAMLopenshell sandbox get name在network_policies下加入hindsight块network_policies: # ... 你已有的策略 ... hindsight: name: hindsight endpoints: - host: api.hindsight.vectorize.io port: 443 protocol: rest tls: terminate enforcement: enforce rules: - allow: method: GET path: /** - allow: method: POST path: /** - allow: method: PUT path: /** binaries: - path: /usr/local/bin/openclaw然后应用openshell policy set sandbox-name --policy /path/to/full-policy.yaml --wait重要openshell policy set替换的是整个策略而非补丁。你的 YAML 必须包含所有既有网络策略否则它们会被移除。验证策略已加载openshell policy get sandbox-name # 应显示Status: Loaded且版本号递增源码印证CLI 的自动模式并不会手工编辑 YAML而是走 policy-reader.ts解析openshell sandbox get输出中的Policy:段并去缩进成 YAML→ policy-writer.tsmergeHindsightPolicy幂等合并 serializePolicy序列化→ 写到临时文件后执行openshell policy set。hasHindsightPolicy会检查策略里是否已存在指向api.hindsight.vectorize.io的 hindsight 块存在则跳过见 setup.ts 第 87-88 行。策略的类型定义SandboxPolicy、NetworkPolicy、PolicyEndpoint等在 types.ts其中HINDSIGHT_HOST与OPENCLAW_BINARY常量即上面的 host 与 binaries 路径。第五步重启 OpenClaw 网关openclaw gateway restart然后查看日志确认插件加载与 API 连通grep Hindsight ~/.openclaw/logs/gateway.log | tail -20 # 应看到 # [Hindsight] Plugin loaded successfully # [Hindsight] ✓ Using external API: https://api.hindsight.vectorize.io # [Hindsight] External API health: {status:healthy,database:connected} # [Hindsight] Default bank: my-sandbox-openclaw # [Hindsight] ✓ Ready (external API mode)第六步验证记忆写入与召回向 Agent 发送一条消息openclaw agent --agent main --session-id test-1 \ -m My name is Ben and I work on Hindsight. I prefer detailed commit messages.检查记忆是否被保留看日志grep Retained\|agent_end ~/.openclaw/logs/gateway.log | tail -5 # 应看到[Hindsight] Retained N messages to bank my-sandbox-openclaw for session ...换一个新会话测试召回openclaw agent --agent main --session-id test-2 \ -m What do you remember about me? # 应能回忆起上一个会话中的名字和偏好也可以直接调用 Hindsight API 验证curl -s -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-sandbox-openclaw/memories/recall \ -H Authorization: Bearer your-hindsight-api-key \ -H Content-Type: application/json \ -d {query: what do you know about the user, max_tokens: 512}排障指南插件加载失败EPERM: operation not permitted, scandir原因安装时用了--link。OpenClaw 的 LaunchAgent 运行在受限的 macOS 安全上下文无法通过符号链接访问~/Documents等用户目录。解决卸载后重新安装不带--linkopenclaw plugins uninstall hindsight-openclaw openclaw plugins install /path/to/hindsight-integrations/openclaw # 不带 --link[Hindsight] Failed to retain memory (HTTP 403)沙箱网络策略阻止了出站调用。检查三点策略 YAML 中存在hindsight网络策略块策略已应用且状态为Status: Loaded用openshell policy get name确认binaries列表包含/usr/local/bin/openclaw。网关重启超时但随后恢复首次安装插件后的重启超时属正常现象——LaunchAgent 需要一点时间重新加载。若openclaw gateway status显示RPC probe: ok即说明网关健康。openclaw agent报Pass --to, --session-id, or --agent需要显式指定会话。用--agent main使用默认 agent或用--session-id 任意字符串创建命名会话。自动化 vs 手动如何选择首选自动化CLI 做了策略合并的幂等处理已存在则跳过与原子写入openclaw-config.ts中先写临时文件再rename比手工编辑更不易出错且--dry-run可先预览需要细粒度控制例如要自定义 egress 规则的 method/path 集合、要复用已存在的策略文件、或沙箱输出格式与 CLI 解析不兼容时可按 NEMOCLAW.md 手工配置。CLI 在策略解析失败时也会提示回退到手工方式见 policy-reader.ts 第 66-73 行的错误信息。包结构速览hindsight-integrations/nemoclaw/README.md — 包说明与 CLI 参考hindsight-integrations/nemoclaw/NEMOCLAW.md — 手工分步配置指南本篇文章的核心依据hindsight-integrations/nemoclaw/src/cli.ts — 参数解析与帮助输出hindsight-integrations/nemoclaw/src/setup.ts — 五步安装编排hindsight-integrations/nemoclaw/src/openclaw-config.ts —~/.openclaw/openclaw.json的读改写原子写入hindsight-integrations/nemoclaw/src/policy-reader.ts / policy-writer.ts — 沙箱策略解析、合并、序列化hindsight-integrations/nemoclaw/src/types.ts — 策略与 CLI 参数类型、HINDSIGHT_HOST/OPENCLAW_BINARY常量hindsight-integrations/nemoclaw/src/setup.test.ts — 对执行顺序、skip 标志、dry-run、失败快速退出的测试验证hindsight-integrations/openclaw/src/index.ts — 插件本体deriveBankId第 1386 行起决定静态/动态库 ID 推导。Licensehindsight-nemoclaw以 MIT 协议开源。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考