概述

Memok 为 OpenClaw 助手提供可持久化的记忆：能把对话中的要点写入本地数据库，在后续轮次中召回，并可按时间表做后台整理（上游文档中常称为 dreaming / predream）。您安装的是 OpenClaw 插件；具体流水线与存储由 memok-ai 核心库在本地完成。

本文按阅读顺序组织：先弄清术语与版本，再安装与自检，然后理解向导与配置项，最后提供使用场景与排障。算法细节以开源仓库为准。

若需了解 memok-ai npm 库本身（memok-ai/bridge、MemokPipelineConfig、SQLite 语义，或不经过 OpenClaw 的集成方式），请见本站核心库文档：/zh/docs/memok-ai。

术语与组件

Memok：产品能力名称，指「可长期保存与召回的记忆」这一套能力。
OpenClaw：网关/运行时，负责加载插件并把模型接到你的工具链。
memok-ai：核心 npm 库（流水线、SQLite、bridge 等）。一般用户只需知道插件依赖它；二次开发核心时才需深入该仓库。
Memok OpenClaw 插件：从 memok-ai-openclaw 仓库安装/克隆的扩展（国内常用 Gitee 镜像）。手动克隆时请克隆插件仓库，而非仅克隆核心库。
TOML：一种配置文件格式。向导生成的 Memok 流水线配置在扩展目录下的 config.toml，键名对应 MemokPipelineConfig（见仓库内 config.toml.example）。
Dreaming / predream：可选的定时后台整理/合并记忆的流程；向导里可配置是否启用及频率。

环境与版本要求

以下条目应在安装前全部满足；缺任一项都可能导致安装失败或运行异常。

检查项	要求	自检命令
Node.js	20 及以上（建议 LTS）。	node -v
npm	可在终端调用。	npm -v
OpenClaw 网关	与插件声明的版本兼容（网关与 plugin API 建议 2026.3.24 及以上，见插件仓库 package.json 的 openclaw.compat）。	openclaw --version（或您环境中的等价命令）
一键安装	同一终端内可用 git、node、npm、openclaw。	which git、which npm、which openclaw（Windows 用 Get-Command）

提示

磁盘：预留数 GB 空间供依赖与 SQLite 使用。网络：首次安装需下载依赖；大陆用户优先使用本文「快速开始」中的 Gitee 一键脚本。

配置会写在哪里（安装前可读）

首次安装不必手写配置。插件注册成功后运行 openclaw memok setup，向导会把 MemokPipelineConfig 写入例如 ~/.openclaw/extensions/memok-ai/config.toml。网关还可能合并 ~/.openclaw/openclaw.json 中的可选键，合并优先级以上游 README 为准。

仓库提供带注释的示例文件（勿提交真实密钥）：https://github.com/galaxy8691/memok-ai-openclaw/blob/main/config.toml.example

完整的「键—含义—是否必填」对照表在本文后段「配置项参考（config.toml）」；读完向导章节再看该表会更易理解。

快速开始（一键安装）

注意

首次安装常需数分钟：下载依赖并编译原生模块（如 better-sqlite3）。终端长时间无新输出多数仍在执行，并非死机。

提示

大陆网络建议直接使用下列 Gitee 脚本（默认国内 npm 镜像），成功率更高。

任选其一，整段粘贴到终端或 PowerShell，等待脚本结束。

Linux / macOS（国内脚本）

bash

bash <(curl -fsSL https://gitee.com/wik20/memok-ai-openclaw/raw/main/scripts/install-cn-linux-macos.sh)

Windows PowerShell（从 Gitee 拉安装脚本）

PowerShell

irm https://gitee.com/wik20/memok-ai-openclaw/raw/main/scripts/install-windows.ps1 | iex

若需从 GitHub 拉取安装脚本，可与英文文档页使用相同的一行命令。脚本内部会处理镜像与超时等细节，一般用户无需自行配置安装器环境变量。

安装结果自检

脚本结束后，建议依次确认插件已注册、扩展目录存在、配置文件已生成。

执行 openclaw plugins list，输出中应出现与 Memok 相关的插件条目。
检查扩展目录是否存在，例如：ls ~/.openclaw/extensions/memok-ai（实际目录名以安装为准）。
确认配置文件已生成：test -f ~/.openclaw/extensions/memok-ai/config.toml；Windows 可用 PowerShell：Test-Path 同上路径。
若手动改过插件或 JSON 配置，执行 openclaw gateway restart 让进程重新加载。

说明

插件在列表中的显示字符串以 openclaw.plugin.json 为准；若与示例文案不完全一致，以 list 命令与实际磁盘文件为准。

手动安装

适用于禁止 curl 一键脚本、或需要写入内部运维手册的场景。每步成功后再执行下一步。

git clone 插件仓库（勿只克隆核心库）。
在仓库根目录执行 npm install（国内可加 --registry https://registry.npmmirror.com），再执行 npm run build。
在仓库根目录执行 openclaw plugins install .
执行 openclaw memok setup，按提示完成向导。

示例（Gitee 克隆）

bash

git clone https://gitee.com/wik20/memok-ai-openclaw.git
cd memok-ai-openclaw
npm install --registry https://registry.npmmirror.com && npm run build
openclaw plugins install .
openclaw memok setup

或从 GitHub 克隆

bash

git clone https://github.com/galaxy8691/memok-ai-openclaw.git
cd memok-ai-openclaw
npm install && npm run build
openclaw plugins install .
openclaw memok setup

预期现象：npm install / build 无报错；openclaw plugins install 显示成功；向导结束且 config.toml 已写入。

配置向导（openclaw memok setup）

向导在终端中依次询问模型服务地址、API Key、模型名、是否启用梦境整理及时间表等，并把结果写入 ~/.openclaw/extensions/memok-ai/config.toml。通常无需手工编辑该文件。

若网关已启动但 Memok 无响应，先确认上述 config.toml 是否存在；修改配置后请重启网关（如 openclaw gateway restart）。

若提示 plugins.allow 未包含 memok，请在 ~/.openclaw/openclaw.json 的 plugins.allow 中加入 "memok"，保存后重新执行 openclaw memok setup。

安装完成后：如何使用记忆

启用后，Memok 参与正常对话闭环：可能在模型作答前注入候选记忆，并提供对已使用记忆进行强化的流程（具体命令名随 OpenClaw / 插件版本变化，以上游 README 为准）。

下表为示意，真实回答仍取决于模型、采样与是否成功落库。

用户追问	无 Memok 时常见表现	有 Memok 且召回命中时可能表现
我们上周二锁定的发布日是哪天？	泛泛而谈或表示没有更早上下文。	若当时对话已入库且被召回，可能复述当时约定的日期。
把上次部署脚本报错的原文贴出来。	需要您再次粘贴日志。	若错误文本曾写入记忆，可能直接带出相关片段。
服务 B 最终统一用哪个鉴权头？	容易与先前结论不一致。	若决策文本被记忆且排序靠前，回答更可能与历史一致。

建议：长讨论结束的次日，用一两句「记忆抽查」问题验证；若明显忽略旧结论，请检查 config.toml、模型能力及是否在改配置后重启网关。

说明

本站不内嵌向导截图；界面示意见插件仓库 README。

模型选择建议

Memok 通过兼容 OpenAI 的 HTTP 接口调用大模型。base URL 与模型名必须与服务商文档一致；不存在放之四海皆准的「最佳模型」。

先用性价比高的小模型验证召回与整理是否满足需求，再考虑升级。
用少量真实会话回归：召回内容是否被正确使用，是否出现捏造引用。
若延迟或费用上升，可换更小模型或降低重任务频率。

更深入说明见核心仓库：https://github.com/galaxy8691/memok-ai

容量、限制与预期

本站不给出固定 SLA；下列为运维向说明，请在自家机器与工作负载上实测。

主题	实践要点
SQLite 体积	随对话与后台任务增长；大版本或迁移前建议备份 memok.sqlite；若运维规范要求静止拷贝，可先停网关再复制文件。
延迟	记忆相关步骤通常由「大模型往返 + 本地 SQLite」主导；模型越大、库越大，耗时常上升。上游 README 偶有社区经验区间，仍应以自测为准。
Token 上限	config.toml 中各阶段 max tokens 决定单次阶段输出上限；调大可能增加费用与超时概率，调小可缓解超时。
梦境 / 定时任务	启用后会周期性调用模型；若账单上升，可放宽执行间隔或对维护任务换更小模型。

进阶用法

适合已完成向导、需要比交互式提问更细粒度控制的运维人员。

手工编辑 config.toml 前，先停或重启网关，避免与运行中进程写冲突。
为 ~/.openclaw/extensions/memok-ai/config.toml 与 dbPath 指向的 SQLite 做带日期的备份。
修改后务必重启网关，并用短对话做回归（召回 + 若启用则观察一轮定时窗口）。
梦境强度：优先在向导里调整时间表；再按需对照上游示例微调可选数值阈值。
多机高可用：默认是单机 SQLite；若无明确复制方案，请勿假设跨主机自动同步。

流水线语义与扩展点：https://github.com/galaxy8691/memok-ai；插件行为与 issue：https://github.com/galaxy8691/memok-ai-openclaw。

配置项参考（config.toml）

下表与上游 config.toml.example 对齐，便于对照；若与发行版不一致，以您克隆/安装版本中的示例文件为准。

带注释的完整示例：https://github.com/galaxy8691/memok-ai-openclaw/blob/main/config.toml.example

配置项	是否必填	说明
dbPath	必填	SQLite 路径（向导常默认在 memok-ai 扩展目录下）。
openaiApiKey	必填	API Key。
llmModel	必填	模型名，需与服务商一致（示例常用 gpt-4o-mini）。
llmMaxWorkers	一般会写	并行路数；为 1 时串行。
articleSentencesMaxOutputTokens	一般会写	文章拆句阶段输出 token 上限。
coreWordsNormalizeMaxOutputTokens	一般会写	核心词归一化输出 token 上限。
sentenceMergeMaxCompletionTokens	一般会写	句子合并补全 token 上限。
openaiBaseUrl	可选	自定义 API 根地址；不写用 SDK 默认。
skipLlmStructuredParse	可选	是否跳过部分结构化解析。
articleWordImportInitialWeight	可选	导入新句初始权重。
articleWordImportInitialDuration	可选	导入新句初始持续天数。
dreamShortTermToLongTermWeightThreshold	可选	predream 短→长期阈值（省略则用核心库默认 7）。

故障排除

现象	处理建议
permission denied	检查当前用户对家目录与 ~/.openclaw 的写权限；尽量避免无谓的 sudo npm，可先修正目录属主。
Linux 上 plugins install 已显示成功但脚本不返回	查阅插件仓库 issue/脚本说明；部分环境需调整终端交互方式。
网关运行但 Memok 无反应	确认 config.toml 是否存在；重跑 openclaw memok setup；重启网关。
向导提示 plugins.allow	在 ~/.openclaw/openclaw.json 的 plugins.allow 中加入 memok，保存后重跑向导。
模型 401 / 404	核对 openaiBaseUrl 与 llmModel；检查 Key 是否过期。
SQLite database is locked 等	确认仅有一个网关在写同一库；结束重复进程后干净重启再试。
召回始终为空	确认对话确实经插件路径落库；检查 Key/模型能否跑完流水线；按上游文档打开诊断日志。
升级 OpenClaw 后 Memok 异常	阅读插件发行说明后重跑 openclaw memok setup；若兼容矩阵变化，按需重装插件目录。

安装后仍「完全无反应」时的建议排查顺序：

openclaw plugins list — 确认 Memok 扩展在列表中。
test -f ~/.openclaw/extensions/memok-ai/config.toml — 确认向导产物存在。
openclaw gateway restart — 让 JSON/TOML 修改生效。
用上一会话刚说过的简单事实做追问；若仍空白，收集网关日志与版本号到插件仓库提 issue。

更多日志与高级诊断：见 https://github.com/galaxy8691/memok-ai-openclaw 的 README 与 Issues。

源码与镜像

OpenClaw 插件（GitHub）：https://github.com/galaxy8691/memok-ai-openclaw
OpenClaw 插件（Gitee）：https://gitee.com/wik20/memok-ai-openclaw
Memok 核心（GitHub）：https://github.com/galaxy8691/memok-ai
Memok 核心（Gitee）：https://gitee.com/wik20/memok-ai