OpenClaw 数据存储层 (Data Layer)数据存储层 (Data Layer) 1. 层概述职责: 管理系

数据存储层 (Data Layer)

文档版本：2026.3.31　　最后更新：2026-03-31

openclaw版本：v2026.3.3

1. 层概述

职责: 管理系统所有持久化状态的读写，包括配置文件、会话记录、凭证/白名单、媒体缓存和向量索引

定位: 系统最底层，为上层提供统一的数据持久化服务；无运行时依赖，仅依赖文件系统和 SQLite

核心特性:

无数据库服务依赖（纯文件系统 + SQLite）
JSON5 配置（支持注释、可组合的 includes）
JSON Lines 会话 transcript（追加写入，高效流式）
SQLite-vec 向量存储（本地向量相似度搜索）
文件锁保护并发写入
配置版本迁移系统

数据存储层六大组件全景

2. 主要组件

2.1 配置管理系统 (Config)

路径: src/config/

职责: 加载、验证、合并多层配置文件，提供全局类型化配置对象。

2.1.1 配置文件格式与位置

配置类型	默认路径	格式
主配置	`~/.openclaw/config.json5`	JSON5
运行时快照	`~/.openclaw/runtime.json`	JSON
模型配置	`~/.openclaw/models.json5`	JSON5
密钥配置	`~/.openclaw/secrets.json5`	JSON5
Session 配置	`src/config/sessions/`	JSON

2.1.2 核心配置结构（顶层字段）

配置类型定义分散于 src/config/types.*.ts 系列文件中，通过 src/config/types.ts 统一 re-export。

// src/config/types.openclaw.ts
export type OpenClawConfig = {
  meta?: { lastTouchedVersion?: string; lastTouchedAt?: string }
  auth?: AuthConfig
  acp?: AcpConfig
  env?: { shellEnv?: { enabled?: boolean; timeoutMs?: number }; vars?: Record<string, string>; [key: string]: ... }
  wizard?: { lastRunAt?: string; lastRunVersion?: string; ... }
  diagnostics?: DiagnosticsConfig
  logging?: LoggingConfig
  cli?: CliConfig
  update?: { channel?: 'stable' | 'beta' | 'dev'; checkOnStart?: boolean; auto?: { ... } }
  browser?: BrowserConfig
  ui?: { seamColor?: string; assistant?: { name?: string; avatar?: string } }
  secrets?: SecretsConfig
  skills?: SkillsConfig
  plugins?: PluginsConfig          // 注意：非数组，是整体配置对象
  models?: ModelsConfig
  nodeHost?: NodeHostConfig
  agents?: AgentsConfig            // 注意：非数组，是整体配置对象（含 agents.entries）
  tools?: ToolsConfig
  bindings?: AgentBinding[]
  broadcast?: BroadcastConfig
  audio?: AudioConfig
  media?: { preserveFilenames?: boolean; ttlHours?: number }
  messages?: MessagesConfig
  commands?: CommandsConfig
  approvals?: ApprovalsConfig
  session?: SessionConfig
  web?: WebConfig
  channels?: ChannelsConfig
  cron?: CronConfig
  hooks?: HooksConfig
  discovery?: DiscoveryConfig
  canvasHost?: CanvasHostConfig
  talk?: TalkConfig
  gateway?: GatewayConfig
  memory?: MemoryConfig
  mcp?: McpConfig
}

2.1.3 关键文件

文件	说明
`config.ts`	配置公共接口桶（barrel export），re-export io/paths/types/validation 等
`types.openclaw.ts`	`OpenClawConfig` 顶层类型定义
`types.*.ts`	各子系统类型（agents/channels/gateway/cron/memory/hooks/secrets/skills/mcp…）
`zod-schema.ts`	Zod 运行时验证 Schema（`OpenClawSchema`，聚合各子 schema）
`zod-schema.*.ts`	各子系统 Zod schema（session/hooks/agents/approvals/providers 等）
`schema.ts`	动态配置 Schema 查找系统（Config UI 用，基于 JSON Schema；非 TypeBox 配置定义）
`io.ts`	配置文件读写核心，含 `loadConfig` / `writeConfigFile` / `getRuntimeConfig` 等
`paths.ts`	配置文件路径解析（`resolveConfigPath` / `resolveStateDir`）
`includes.ts`	多文件 include 合并（`$include` 指令）
`merge-config.ts`	配置合并策略
`merge-patch.ts`	RFC 7396 JSON Merge Patch 实现（`applyMergePatch`）
`mutate.ts`	配置文件原子变更（`mutateConfigFile` / `replaceConfigFile`）
`validation.ts`	配置对象验证（`validateConfigObject` / `validateConfigObjectWithPlugins`）
`legacy-migrate.ts`	旧版配置自动迁移（`migrateLegacyConfig`）
`env-substitution.ts`	环境变量替换（`$ENV_VAR` 语法）
`runtime-overrides.ts`	运行时临时覆盖（不写入文件）
`redact-snapshot.ts`	敏感字段脱敏（日志输出时用）
`backup-rotation.ts`	配置文件备份轮替（`maintainConfigBackups`）

2.1.4 配置加载流程

readConfig(configPath)
      ↓
JSON5 解析
      ↓
处理 $include 子文件合并
      ↓
环境变量 $ENV_VAR 替换
      ↓
legacy-migrate — 旧版配置结构迁移
      ↓
Zod Schema 验证
      ↓
runtime-overrides 叠加
      ↓
返回强类型 OpenClawConfig 对象

配置加载管线

2.1.5 多文件 Include 示例

// ~/.openclaw/config.json5
{
  $include: ["./agents.json5", "./channels.json5"],
  gateway: { mode: "local" }
}

2.2 会话存储 (Sessions)

路径: src/config/sessions/, src/agents/session-dirs.ts, src/agents/session-slug.ts

职责: 持久化每次 AI 对话的完整消息记录（transcript）以及会话索引元数据，支持会话续接、历史回放和上下文恢复。

会话存储由两个独立子系统构成：

Session Store（src/config/sessions/store.ts）：JSON 格式的会话索引，维护 sessionKey → 文件路径的映射；
Session Transcript：JSONL 格式的逐条消息记录，追加写入。

会话存储双子系统

2.2.1 存储路径

~/.openclaw/
├─ sessions.json                    # Session Store 索引文件（全局）
└─ agents/
   └─ <agentId>/
      └─ sessions/
         ├─ <word1>-<word2>.jsonl          # 当前会话 transcript（随机可读短语命名）
         ├─ <word1>-<word2>-<word3>.jsonl  # 三词 slug（防冲突）
         └─ *.jsonl.gz                     # 压缩归档旧会话

2.2.2 Session Key 格式

// src/sessions/session-key-utils.ts
// Session Key 固定以 "agent:" 开头
// 格式: "agent:<agentId>:<channelId>:<accountId>"
// 示例: "agent:my-agent:tg:123456789"
parseAgentSessionKey("agent:my-agent:tg:123456789")
// → { agentId: "my-agent", rest: "tg:123456789" }

2.2.3 Session Slug（文件名）生成

// src/agents/session-slug.ts
// Slug 为随机形容词-名词组合，与 sessionKey 无关，不含年月后缀
createSessionSlug()  // → "happy-mountain" | "swift-river-lake"

优先 2 词组合（<adjective>-<noun>），冲突时用 3 词，再冲突加随机后缀
SLUG_ADJECTIVES / SLUG_NOUNS 词库内选取，碰撞则自动增词

2.2.4 Session Store 格式（会话索引，JSON）

{
  "agent:my-agent:tg:123456789": {
    "sessionId": "happy-mountain",
    "sessionFile": "/home/user/.openclaw/agents/my-agent/sessions/happy-mountain.jsonl",
    "updatedAt": 1740000000000
  }
}

2.2.5 Transcript 格式（JSON Lines）

每行一条消息事件，无行间分隔符，追加写入：

{"role":"user","content":"你好","ts":1740000000000}
{"role":"assistant","content":"你好！","ts":1740000001000}
{"role":"tool_use","id":"toolu_01","name":"bash","input":{"command":"ls"},"ts":1740000002000}
{"role":"tool_result","tool_use_id":"toolu_01","content":"file1.txt\nfile2.ts","ts":1740000003000}

2.2.6 关键文件

文件	说明
`src/config/sessions/store.ts`	Session Store 主入口（`loadSessionStore` / `saveSessionStore`）
`src/config/sessions/store-cache.ts`	Store 读缓存（mtime + size 校验）
`src/config/sessions/store-maintenance.ts`	Store 维护（过期会话清理）
`src/config/sessions/store-migrations.ts`	Store 格式迁移
`src/config/sessions/store-read.ts`	Store 只读辅助
`src/config/sessions/transcript.ts`	Transcript 文件路径解析与追加写入
`src/config/sessions/disk-budget.ts`	磁盘配额管理（`enforceSessionDiskBudget`）
`src/config/sessions/types.ts`	会话类型定义（`SessionEntry`/`SessionScope` 等）
`src/config/sessions/session-key.ts`	Session Key 创建与解析
`src/agents/session-dirs.ts`	会话目录路径解析（`resolveAgentSessionDirs`）
`src/agents/session-slug.ts`	Session Slug 随机生成（`createSessionSlug`）
`src/agents/session-write-lock.ts`	Transcript 写锁（防并发写入损坏）
`src/agents/session-file-repair.ts`	损坏 JSONL 文件修复
`src/agents/session-transcript-repair.ts`	Transcript 内容修复（格式兼容）
`src/agents/session-tool-result-guard.ts`	工具结果写入守卫
`src/sessions/transcript-events.ts`	Transcript 更新事件（观察者机制）
`src/sessions/session-key-utils.ts`	Session Key 解析工具（`parseAgentSessionKey`）
`src/sessions/session-lifecycle-events.ts`	会话生命周期事件
`src/sessions/send-policy.ts`	消息发送策略（防重发）
`src/sessions/model-overrides.ts`	会话级模型覆盖
`src/sessions/level-overrides.ts`	会话级日志级别覆盖
`src/sessions/input-provenance.ts`	入站消息来源标注

2.2.7 会话维护（磁盘配额与 Pruning）

磁盘配额: disk-budget.ts 的 enforceSessionDiskBudget 按 maxDiskBytes/highWaterBytes 删除最旧会话文件
文件压缩: 超大旧会话自动 gzip 压缩
旧 Session 清理: src/cron/session-reaper.ts 定期清理过期会话

2.3 凭证与白名单存储 (Credentials)

路径: src/pairing/pairing-store.ts, src/config/paths.ts

职责: 持久化渠道访问控制列表（AllowFrom）和配对请求状态。

2.3.1 存储路径

~/.openclaw/credentials/          # 所有文件平铺在同一目录，无子目录
├─ <channelId>-allowFrom.json              # 渠道全局白名单
├─ <channelId>-<accountId>-allowFrom.json  # 账号级白名单（多账号渠道）
└─ <channelId>-pairing.json                # 配对请求（待审批状态）

注意: 凭证文件以平铺的命名约定（<channelId>-allowFrom.json）存储，而非此前文档中描述的 <channelId>/ 子目录结构。

2.3.2 AllowFrom 文件格式

{
  "allowFrom": [
    {
      "id": "user123",
      "label": "Alice",
      "addedAt": 1740000000000,
      "lastSeenAt": 1740000090000
    }
  ],
  "updatedAt": 1740000090000
}

2.3.3 并发保护

使用 proper-lockfile 在读写前加文件锁（PAIRING_STORE_LOCK_OPTIONS），防止多进程同时修改导致数据损坏。读取侧有内存缓存（allowFromReadCache），以 mtime 校验为失效依据。

2.4 媒体缓存 (Media Cache)

路径: src/media/store.ts, src/media/temp-files.ts

职责: 为媒体管道提供临时文件存储，所有媒体均有 TTL 过期自动清理。

2.4.1 存储路径

~/.openclaw/media/
├─ <hash>_<filename>.jpg    # 下载的图像
├─ <hash>_<filename>.mp3    # 音频文件
├─ <hash>_<filename>.mp4    # 视频文件
└─ <hash>_<filename>.pdf    # PDF 文件

2.4.2 媒体文件管理

机制	说明
TTL 清理	`DEFAULT_TTL_MS` 默认过期（由 `cleanOldMedia()` 执行）
大小限制	`MEDIA_MAX_BYTES` 防止单文件过大
文件权限	`MEDIA_FILE_MODE = 0o644`（所有者读写，组/其他只读）
文件名	原始文件名 hash 前缀，保留扩展名（`sanitizeFilename` 清理）

注意: 实际权限为 0o644，非 0o600。

2.4.3 临时文件

src/media/temp-files.ts — 处理短暂存在的中间文件（如 FFmpeg 转码输出），操作完毕后立即删除。

2.5 向量索引存储 (Vector Index)

路径: extensions/memory-core/src/memory/（独立插件扩展，非 src/memory/）

职责: 以 SQLite + sqlite-vec 扩展实现本地向量相似度检索，无需外部向量数据库服务。

架构说明: 向量记忆系统是一个独立的插件扩展（位于 extensions/memory-core/），而非 core src 的组成部分。它通过 Plugin SDK 注册为记忆提供者。

2.5.1 存储路径

~/.openclaw/agents/<agentId>/memory/
└─ index.sqlite    # SQLite 数据库（含向量索引）

2.5.2 数据库表结构

表名	类型	说明
`VECTOR_TABLE`	virtual（sqlite-vec 扩展）	向量相似度索引表
`FTS_TABLE`	virtual（FTS5）	全文搜索索引表
`EMBEDDING_CACHE_TABLE`	普通表	嵌入向量缓存（避免重复生成）
`INDEX_CACHE`	内存常量	活跃索引的内存缓存键名

2.5.3 向量存储特性

特性	说明
SQLite 驱动	Node.js 22 内置 `node:sqlite`（`DatabaseSync`），不使用 better-sqlite3
嵌入维度	按提供者自动适配（768 / 1024 / 1536 / 3072）
混合检索	BM25 全文（`hybrid.ts`）+ 向量余弦相似度组合排分
MMR 去重	结果多样性优化（最大边际相关性，`mmr.ts`）
时间衰减	老记忆权重随时间递减（`temporal-decay.ts`）
原子重建	`atomic-reindex` — 安全的全量重建索引
只读恢复	SQLite 损坏时自动切换只读模式（`manager.readonly-recovery.test.ts` 覆盖）

向量记忆混合检索架构

2.5.4 关键文件（extensions/memory-core/src/memory/）

文件	说明
`manager.ts`	`MemoryIndexManager` 主类（含 `VECTOR_TABLE`/`FTS_TABLE`/`EMBEDDING_CACHE_TABLE` 常量）
`manager-sync-ops.ts`	`MemoryManagerSyncOps`：SQLite 初始化、sqlite-vec 加载、文件变更监听
`manager-search.ts`	向量 + 全文检索操作
`manager-embedding-ops.ts`	嵌入向量生成和批处理
`manager-runtime.ts`	运行时初始化与生命周期
`search-manager.ts`	`MemorySearchManager`（对外检索入口）、`FallbackMemoryManager`、`BorrowedMemoryManager`
`qmd-manager.ts`	QMD 管理器（Query/Manage/Delete 三合一接口）
`hybrid.ts`	BM25 + 向量混合检索算法（`mergeHybridResults`）
`mmr.ts`	最大边际相关性去重
`temporal-decay.ts`	时间衰减权重计算
`embeddings.ts`	嵌入向量接口
`provider-adapters.ts`	嵌入提供者适配器
`index.ts`	包公共导出

2.6 Cron 任务存储

路径: src/cron/store.ts, src/cron/run-log.ts

职责: 持久化 Cron 任务定义和执行历史，实现重启后任务恢复。

2.6.1 存储路径

~/.openclaw/cron/
├─ jobs.json          # Cron 任务定义列表（全局，非 per-agent 子目录）
└─ runs/
   └─ <jobId>.jsonl   # 每个任务独立的执行历史（JSONL 格式）

注意: Cron 存储路径为全局 ~/.openclaw/cron/，而非 per-agent 的 agents/<agentId>/cron/。执行日志也是每 job 一个独立 JSONL 文件，而非统一的 run-log.json。

2.6.2 任务定义格式

{
  "id": "daily-news",
  "schedule": "0 9 * * *",
  "prompt": "每天早上9点推送科技新闻摘要",
  "agentId": "my-agent",
  "enabled": true,
  "createdAt": 1740000000000,
  "lastRunAt": 1740000090000,
  "deliverTo": { "channel": "tg", "account": "user123" }
}

store.ts 提供 loadCronStore / saveCronStore（原子写，含备份跳过优化）；run-log.ts 提供 appendCronRunLog / readCronRunLogEntries，支持按状态/时间过滤和分页读取。

2.7 认证 Profile 存储

路径: src/agents/auth-profiles.ts

职责: 持久化多 API Key 认证配置文件及其冷却状态。

2.7.1 存储路径

~/.openclaw/agents/<agentId>/
└─ auth-profiles.json    # 认证配置文件列表（含冷却计时）

3. 对外提供的接口

数据存储层为上层提供以下编程接口：

配置接口

接口	说明
`loadConfig(path)`	加载完整配置对象（`io.ts`）
`getRuntimeConfig()`	获取当前运行时配置快照（`io.ts`）
`writeConfigFile(path, config)`	持久化配置变更（`io.ts`）
`mutateConfigFile(path, fn)`	原子局部变更配置（`mutate.ts`）
`applyMergePatch(target, patch)`	JSON Merge Patch 合并（`merge-patch.ts`）
`resolveStateDir(env)`	解析状态目录（`paths.ts`）
`validateConfigObject(obj)`	验证配置合法性（`validation.ts`）

会话接口

接口	说明
`loadSessionStore(storePath)`	加载会话索引（带缓存，`src/config/sessions/store.ts`）
`saveSessionStore(storePath, store)`	持久化会话索引（带写锁）
`resolveSessionTranscriptFile(params)`	解析 transcript 文件路径（`transcript.ts`）
`resolveAgentSessionDirs(stateDir)`	获取所有 Agent 会话目录（`session-dirs.ts`）
`createSessionSlug()`	生成随机可读短语 Slug（`session-slug.ts`）
`repairSessionFile(slug)`	修复损坏的 JSONL 文件（`session-file-repair.ts`）

记忆接口（memory-core 插件提供）

接口	说明
`MemorySearchManager.search(query)`	向量 + 全文混合检索（`search-manager.ts`）
`MemoryIndexManager.add(items)`	添加记忆条目
`MemoryIndexManager.reindex()`	atomic-reindex 原子重建向量索引
`QMD Manager`	Query/Manage/Delete 统一操作接口（`qmd-manager.ts`）

白名单接口

接口	说明
`readChannelAllowFromStore(channelId)`	读取渠道白名单
`updateChannelAllowFromStore(channelId, fn)`	原子更新白名单（文件锁）

4. 与其他层的交互

                  ┌──────────────────────────────┐
                  │   上层（Agent / Routing 层）  │
                  └──────────────┬───────────────┘
                                 │ 读写请求
              ┌──────────────────┼──────────────────┐
              ▼                  ▼                  ▼
    ┌──────────────┐  ┌──────────────────┐  ┌─────────────────┐
    │  Config I/O  │  │  Session Files   │  │  Memory SQLite  │
    │ (JSON5 文件) │  │ (JSONL 追加写)   │  │  (sqlite-vec)   │
    └──────────────┘  └──────────────────┘  └─────────────────┘
              │                  │                  │
              ▼                  ▼                  ▼
    ┌───────────────────────────────────────────────────────┐
    │              本地文件系统 ~/.openclaw/                 │
    └───────────────────────────────────────────────────────┘

所有数据存储均在本地文件系统，无需网络。

5. 关键代码路径

src/config/
├─ config.ts              # 公共接口桶（barrel export）
├─ types.openclaw.ts      # OpenClawConfig 类型定义
├─ types.*.ts             # 各子系统类型（agents/gateway/cron/memory/hooks/…）
├─ zod-schema.ts          # Zod 运行时验证（OpenClawSchema）
├─ zod-schema.*.ts        # 各子模块 Zod schema
├─ schema.ts              # 配置 Schema 动态查找（Config UI 用）
├─ io.ts                  # 文件读写核心（loadConfig/writeConfigFile/getRuntimeConfig）
├─ paths.ts               # 路径解析（resolveStateDir/resolveConfigPath）
├─ includes.ts            # 多文件合并（$include 指令）
├─ merge-config.ts        # config 合并策略
├─ merge-patch.ts         # RFC 7396 Merge Patch（applyMergePatch）
├─ mutate.ts              # 原子配置变更（mutateConfigFile/replaceConfigFile）
├─ validation.ts          # 配置验证（validateConfigObject*）
├─ env-substitution.ts    # 环境变量替换
├─ legacy-migrate.ts      # 历史版本迁移（migrateLegacyConfig）
├─ runtime-overrides.ts   # 运行时覆盖
├─ backup-rotation.ts     # 备份轮替（maintainConfigBackups）
├─ redact-snapshot.ts     # 敏感字段脱敏
└─ sessions/              # 会话存储子系统
   ├─ store.ts            # Session Store（JSON 索引，loadSessionStore/saveSessionStore）
   ├─ store-cache.ts      # Store 读缓存
   ├─ store-maintenance.ts # Store 维护
   ├─ store-migrations.ts # Store 迁移
   ├─ store-read.ts       # Store 只读辅助
   ├─ transcript.ts       # Transcript 文件路径解析与写入
   ├─ disk-budget.ts      # 磁盘配额（enforceSessionDiskBudget）
   ├─ types.ts            # 会话类型（SessionEntry/SessionScope…）
   └─ session-key.ts      # Session Key 创建/解析

src/agents/
├─ session-dirs.ts        # 会话目录路径（resolveAgentSessionDirs）
├─ session-slug.ts        # 随机 Slug 生成（createSessionSlug，词库 adjective-noun）
├─ session-write-lock.ts  # Transcript 写锁
├─ session-file-repair.ts # JSONL 文件修复
├─ session-transcript-repair.ts  # Transcript 内容修复
├─ session-tool-result-guard.ts  # 工具结果写入守卫
├─ auth-profiles.ts       # 认证 Profile 桶（re-export ./auth-profiles/）
└─ auth-profiles/         # 认证 Profile 子系统
   ├─ store.ts            # Profile Store（loadAuthProfileStore/saveAuthProfileStore）
   ├─ paths.ts            # 路径（auth-profiles.json）
   ├─ profiles.ts         # Profile 增删改（upsertAuthProfile…）
   ├─ cooldown.ts         # 冷却状态管理
   ├─ types.ts            # 类型（AuthProfileStore/OAuthCredential…）
   └─ constants.ts        # AUTH_PROFILE_FILENAME = "auth-profiles.json"

src/sessions/
├─ transcript-events.ts   # Transcript 更新事件
├─ session-key-utils.ts   # Session Key 解析（parseAgentSessionKey）
├─ session-lifecycle-events.ts  # 会话生命周期事件
├─ send-policy.ts         # 发送策略
├─ model-overrides.ts     # 会话级模型覆盖
├─ level-overrides.ts     # 会话级日志级别覆盖
└─ input-provenance.ts    # 入站消息来源标注

src/pairing/
└─ pairing-store.ts       # 白名单 + 配对请求存储
                          # 文件名: <channelId>-allowFrom.json / <channelId>-pairing.json

src/media/
├─ store.ts               # 媒体临时存储（MEDIA_FILE_MODE=0o644）
└─ temp-files.ts          # 临时文件管理

src/cron/
├─ store.ts               # Cron 任务持久化（~/.openclaw/cron/jobs.json）
├─ store-migration.ts     # Cron Store 迁移
└─ run-log.ts             # 执行历史（~/.openclaw/cron/runs/<jobId>.jsonl，JSONL 格式）

extensions/memory-core/src/memory/
├─ manager.ts             # MemoryIndexManager 主类
├─ manager-sync-ops.ts    # MemoryManagerSyncOps（SQLite 初始化、sqlite-vec 加载、文件监听）
├─ manager-search.ts      # 向量 + 全文检索操作
├─ manager-embedding-ops.ts  # 嵌入向量批处理
├─ manager-runtime.ts     # 运行时初始化
├─ search-manager.ts      # MemorySearchManager（对外入口）/FallbackMemoryManager
├─ qmd-manager.ts         # QMD 管理器（Query/Manage/Delete）
├─ hybrid.ts              # BM25 + 向量混合检索（mergeHybridResults）
├─ mmr.ts                 # 最大边际相关性去重
├─ temporal-decay.ts      # 时间衰减权重
├─ embeddings.ts          # 嵌入向量接口
├─ provider-adapters.ts   # 嵌入提供者适配器
└─ index.ts               # 包公共导出

6. 技术实现

6.1 核心技术

技术	用途
JSON5	配置文件格式（支持注释、尾随逗号）
JSON Lines / `.jsonl`	会话 transcript 格式（流式追加写）；Cron 执行日志
SQLite + sqlite-vec 扩展	本地向量相似度检索（无服务依赖）
`node:sqlite`（Node.js 22 内置）	同步 SQLite 驱动（`DatabaseSync`），非 better-sqlite3
Zod	运行时配置验证（`OpenClawSchema`，各子模块 schema 聚合）
TypeScript type-only schema	配置类型定义分散于 `types.*.ts` 系列文件
`proper-lockfile`	白名单文件级并发写入保护
原子 rename	配置/Cron Store 先写临时文件再 `rename()` 原子替换

6.2 数据目录结构

~/.openclaw/
├─ config.json5              # 主配置文件
├─ models.json5              # 模型提供者配置（可选）
├─ secrets.json5             # 密钥配置（独立文件权限）
├─ runtime.json              # 运行时状态快照
├─ sessions.json             # Session Store 索引（全局，记录 sessionKey→文件映射）
├─ media/                    # 媒体临时缓存（TTL 自动清理，0o644）
├─ credentials/              # 渠道白名单和配对状态（平铺文件，无子目录）
│  ├─ <channelId>-allowFrom.json
│  ├─ <channelId>-<accountId>-allowFrom.json
│  └─ <channelId>-pairing.json
├─ cron/                     # Cron 任务（全局，非 per-agent）
│  ├─ jobs.json              # 任务定义列表
│  └─ runs/
│     └─ <jobId>.jsonl       # 每任务独立执行历史（JSONL）
└─ agents/
   └─ <agentId>/
      ├─ sessions/           # 会话 transcript（JSONL，随机短语命名）
      │  ├─ <word1>-<word2>.jsonl
      │  └─ *.jsonl.gz
      ├─ memory/             # 向量记忆索引（memory-core 插件维护）
      │  └─ index.sqlite
      ├─ auth-profiles.json  # 认证配置文件（含冷却状态）
      └─ skills/             # 已安装技能（skills 子系统）

数据目录全景树

6.3 设计原则

原则	实现
无服务依赖	全部使用本地文件系统，开箱即用
原子写入	先写临时文件，再 `rename()` 原子替换（配置、Cron Store）
并发安全	`proper-lockfile` 文件锁（白名单）；Session Store 写锁队列（`withSessionStoreLock`）
数据安全	配置备份轮替（`backup-rotation.ts`），防止意外覆盖
隐私保护	`secrets.json5` 独立文件；媒体文件 `0o644` 权限
向后兼容	`legacy-migrate.ts`（配置迁移）；Session Store 迁移（`store-migrations.ts`）；Cron Store 迁移（`store-migration.ts`）
Windows 兼容	Session Store 有重试逻辑（`Atomics.wait` 退避），应对原子 rename 窗口期空文件

6.4 备份与恢复

配置备份: backup-rotation.ts（maintainConfigBackups）在每次写入前创建备份，保留最近 N 份
记忆重建: MemoryIndexManager 的 atomic-reindex 支持从源数据安全全量重建向量索引
会话修复: session-file-repair.ts 截断损坏 JSONL（保留有效的前几条记录）
只读恢复: 记忆系统（MemoryManagerSyncOps）检测到 SQLite 损坏时自动切换为只读模式，避免进一步损坏

OpenClaw 数据存储层 (Data Layer)