OpenClaw 数据存储层 (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 配置文件格式与位置

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 关键文件

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）以及会话索引元数据，支持会话续接、历史回放和上下文恢复。

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

1. 1. Session Store（src/config/sessions/store.ts）：JSON 格式的会话索引，维护 sessionKey → 文件路径的映射；
2. 2. 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:telegram:123456789"
parseAgentSessionKey("agent:my-agent:telegram:123456789")
// → { agentId: "my-agent", rest: "telegram: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:telegram: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 关键文件

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 媒体文件管理

注意: 实际权限为 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 数据库表结构

2.5.3 向量存储特性

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

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": "telegram", "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. 对外提供的接口

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

配置接口

会话接口

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

白名单接口

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 核心技术

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 设计原则

6.4 备份与恢复

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