核心概念12 分钟阅读中级

持久化记忆

OpenClaw 如何记住你并成为独一无二的 AI 助手。你的偏好、上下文和 AI 记忆管理

你将学到

  • OpenClaw 如何持久化和存储对话历史
  • Session 的生命周期和重置策略
  • 配置记忆保留和清理规则
  • 在不同设备间共享对话上下文
  • 使用命令行工具管理和检查 Session

目录导航

核心概念

OpenClaw 将每个 agent 的直接聊天会话视为主要会话。直接聊天合并到 agent:\<agentId\>:\<mainKey\>（默认为 main），而群组/频道聊天则拥有自己的独立 key。这确保了你的 AI 助手能够在所有设备上记住你。

💡 Gateway 是单一真相源 —— 所有 Session 状态都由 Gateway 管理，UI 客户端（macOS 应用、WebChat 等）必须查询 Gateway 来获取 Session 列表和 token 计数。

单一真相源

Gateway 拥有所有 Session 状态，UI 客户端从 Gateway 获取数据而不是读取本地文件

持久化存储

Session 存储在 ~/.openclaw/agents/\<agentId\>/sessions/sessions.json 中，对话历史保存为 JSONL 文件

自动管理

Session 会根据配置的重置策略自动过期和清理，支持每日重置和空闲超时

灵活配置

可以通过配置文件控制 Session 的作用域、重置策略和身份链接

状态存储位置

在 Gateway 主机上，OpenClaw 将 Session 数据存储在以下位置：

~/.openclaw/agents/\<agentId\>/sessions/sessions.json

Session 存储：每个 agent 的会话映射表，包含 Session ID、更新时间等元数据

~/.openclaw/agents/\<agentId\>/sessions/\<SessionId\>.jsonl

对话记录：每个 Session 的完整对话历史，以 JSONL 格式存储

远程模式提示

在远程模式下，你关心的 Session 存储位于远程 Gateway 主机上，而不是你的 Mac。确保在正确的机器上查看和管理 Session。

Session 生命周期

🎯

创建阶段

当收到第一条消息时创建新的 Session，或使用 /new、/reset 命令强制创建新 Session

💬

活跃使用

Session 在每次收到消息时更新，保持对话上下文和相关记忆

⏰

重置评估

每次收到消息时评估 Session 是否过期（基于每日重置时间或空闲时间）

🔄

过期重置

过期的 Session 会被标记为 stale，下一条消息将创建新的 Session ID

配置选项

你可以通过 ~/.openclaw/openclaw.json 文件配置 Session 行为。以下是一个示例配置：

{\n  \"session\": {\n    \"scope\": \"per-sender\",\n    \"dmScope\": \"main\",\n    \"identityLinks\": {\n      \"alice\": [\"telegram:123456789\", \"discord:987654321012345678\"]\n    },\n    \"reset\": {\n      \"mode\": \"daily\",\n      \"atHour\": 4,\n      \"idleMinutes\": 120\n    },\n    \"resetByType\": {\n      \"thread\": { \"mode\": \"daily\", \"atHour\": 4 },\n      \"dm\": { \"mode\": \"idle\", \"idleMinutes\": 240 },\n      \"group\": { \"mode\": \"idle\", \"idleMinutes\": 120 }\n    },\n    \"resetTriggers\": [\"/new\", \"/reset\"],\n    \"mainKey\": \"main\"\n  }\n}

dmScope

main

控制如何分组直接消息：main（所有 DM 共享主会话）、per-peer（按发送者隔离）、per-channel-peer（按渠道和发送者隔离）

identityLinks

{}

将提供商前缀的 peer ID 映射到规范身份，使同一个人在不同渠道间共享 DM 会话

reset.mode

daily

重置模式：daily（每日定时）、idle（空闲超时）或两者结合

reset.atHour

4

每日重置时间（Gateway 主机本地时间的小时数）

reset.idleMinutes

未设置

空闲超时分钟数，Session 在此时间内无活动则过期

resetByType

{}

为不同类型的 Session（dm、group、thread）设置不同的重置策略

检查和管理 Session

查看 Session 状态

openclaw status

显示存储路径和最近的 Session 列表

导出所有 Session

openclaw sessions --json

以 JSON 格式导出所有 Session 条目，可使用 --active 过滤活跃 Session

从运行中的 Gateway 获取

openclaw gateway call sessions.list --params '{}'

从运行中的 Gateway 获取 Session（使用 --url/--token 访问远程 Gateway）

聊天命令

在聊天中发送以下命令来管理 Session 和查看状态：

/status

查看 agent 是否可达、Session 上下文使用情况、当前的 thinking/verbose 开关以及 WhatsApp 凭据刷新时间

/context list

查看系统提示中包含的内容以及注入的工作区文件

/context detail

显示详细的上下文信息，包括最大的上下文贡献者

/stop

中止当前运行，清除该 Session 的排队后续，并停止从其生成的所有子 agent 运行

/compact [可选说明]

手动压缩旧上下文以释放窗口空间，可以提供压缩说明

/new [模型]

开始新 Session，可选择指定模型别名、提供商/模型或提供商名称

/reset

重置当前 Session 并开始新的对话

后续步骤