# OpenClaw

通过 ClawHub 上的原生记忆插件连接 OpenClaw，并提供可选的配套 Skill 指导以实现主动召回。

- Canonical: https://docs.xmemo.dev/zh/docs/connect/openclaw
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: c1ce97e0231b187bac1701fceb894f880bb49f8d6d6dc391398e5decdaf4ff3f
- Edition-Digest: 71996af212738d21cca515c4113d1e5acd2fa455d8e88e409ca0aeecaca1c9c0
- Source-Revision: sha256:8f465eb1d6ca0b120934289273aff9d3c032c43de12f628d3bf82b19ef4657b5

## 适用对象与具体接口

本指南将 OpenClaw 智能体连接到 XMemo 持久记忆。OpenClaw 通过两层架构运行：ClawHub 上的原生 OpenClaw 记忆插件提供运行时工具绑定，而配套 Skill 则提供主动召回指导和会话检查点。

## 前置条件

在连接之前，请确保以下运行时依赖项和工具可用：

- OpenClaw 智能体运行时已安装且运行正常。
- 已启用 ClawHub 软件包访问权限。
- 在 https://xmemo.dev 拥有有效的 XMemo 账户。
- 安装配套 Skill 时，Node.js 运行时版本需为 22.22.0 或更高版本。

## 推荐路径：原生插件配合配套 Skill

推荐路径直接通过 OpenClaw 包管理器安装来自 ClawHub 的原生 OpenClaw 记忆插件和配套 Skill：

```bash
openclaw plugins install clawhub:@xmemo/openclaw-memory
openclaw skills install @xmemo/xmemo
```

## 授权与凭据选项

通过环境变量或交互式设备登录配置凭据。在选择凭据存储路径之前，切勿直接使用未配置的登录：

- 环境凭据（推荐）：在启动 OpenClaw 的 shell 或服务环境中设置 XMEMO_KEY。
- 交互式登录：如果使用配套 Skill，仅在 secret-store XMEMO_KEY 不可用时使用 --allow-plaintext 运行 login（请注意，--allow-plaintext 会在此计算机上未加密存储凭据）。
- 验证凭据：运行 openclaw plugins list 以确认插件激活，并使用配套 Skill 验证认证状态。

## 替代路径：无头服务运行器

对于无头 OpenClaw 运行器或自动化 CI 流水线，通过环境变量直接将 XMEMO_KEY 传递给插件，无需交互式提示。

```bash
export XMEMO_KEY='<your-xmemo-token>'
openclaw run --plugin @xmemo/openclaw-memory
```

## 连接检查（只读）

在写入数据之前，务必通过只读请求验证连接性。此检查不会修改记忆状态。

- 检查：启动测试 OpenClaw 会话并针对现有项目上下文发出主动召回查询。
- 成功标志：OpenClaw 从授权工作区返回包含有效 Reference 和 Location 字段的结构化记忆结果。

## 首个有用任务：合成记忆生命周期

验证记忆持久性、无状态会话转换、归属源的召回和修正：

- 1. 保存合成事实：将项目规范 ("Demo project timestamps use UTC.") 存储到 "projects/demo-onboarding/conventions"。
- 2. 无状态转换：结束当前 OpenClaw 对话并启动新会话。
- 3. 附带源归属的召回：查询 "demo project timestamp format"。确认返回的 Reference 和 Location。
- 4. 修正记忆：使用 ISO 8601 格式更新已记住的规范。
- 5. 可选清理：在入门验证完成后，软删除演示规范。

## 功能与记忆工作流

OpenClaw 工作流按智能体会话的结果对操作进行分组：

- 前瞻性主动召回：在规划前自动将相关持久记忆注入活动上下文中。
- 会话连续性：跨交接保存和恢复重启快照、跟踪决策并维护 TODO。
- 弹性层：短期召回缓存和临时写入发件箱可应对短暂的网络中断。

## 限制与边界

OpenClaw 集成的操作约束：

- 工作区隔离：所有操作都严格限定在经过身份验证的用户的工作区内。
- ClawHub 可用性：未经测试的第三方注册表或插件的非官方分支将被标记为未测试。
- 账本范围：账本月度摘要和财务审计工具需要专用的商业范围。

## 恢复、更新与移除

OpenClaw 的故障排除与维护流程：

- 恢复（插件未加载）：运行 openclaw plugins list 并检查 OpenClaw 日志以查找初始化错误。
- 恢复（认证已过期）：重新导出有效的 XMEMO_KEY 或通过配套 Skill 重新进行身份验证。
- 更新：如需更新已安装的插件和技能，请参阅 OpenClaw 的插件管理文档。
- 移除：如需移除或禁用已安装的插件和技能，请参阅 OpenClaw 的插件管理文档。

## OpenClaw

Direct client: configure in ~/.openclaw/openclaw.json with XMEMO_KEY in the environment. Run npx @xmemo/client mcp add openclaw to install automatically.

```
{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "openclaw",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```