src/agents/sandbox/
├── types.ts          # 核心类型定义
├── config.ts         # 配置合并逻辑
├── context.ts        # 入口点 - 解析沙箱上下文
├── docker.ts         # Docker 容器管理
├── browser.ts        # 隔离浏览器容器
├── tool-policy.ts    # 工具允许/拒绝策略
├── validate-sandbox-security.ts  # 安全验证
├── fs-bridge.ts      # 文件系统操作桥接
└── prune.ts          # 容器自动清理

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session",
        "workspaceAccess": "none",
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "network": "none",
          "memory": "512m",
          "cpus": 1
        },
        "prune": {
          "idleHours": 24,
          "maxAgeDays": 7
        }
      }
    }
  }
}

~/.openclaw/workspace/
├── MEMORY.md           # 长期记忆（精选、持久化）
└── memory/
    └── YYYY-MM-DD.md   # 每日记忆日志（append-only）          # 长期记忆（精选、持久化）└── memory/    └── YYYY-MM-DD.md   # 每日记忆日志（append-only）

type MemorySource = "memory" | "sessions";
type MemorySearchResult = {
  path: string;           // 文件路径
  startLine: number;      // 起始行号
  endLine: number;        // 结束行号
  score: number;          // 相关性得分
  snippet: string;        // 文本片段（~700 字符）
  source: MemorySource;   // 来源类型
  citation?: string;      // 引用标注
};

用户查询
  ↓
关键词提取 (FTS)
向量嵌入
  ↓
并行搜索
  ├─ 向量搜索（语义相似）
  └─ BM25 搜索（关键词匹配）
  ↓
加权融合
  ↓
后处理
  ├─ 时间衰减
  └─ MMR 去重
  ↓
Top-K 结果

finalScore = vectorWeight * vectorScore + textWeight * textScore

score = λ × relevance - (1-λ) × max_similarity_to_selected

查询："家庭网络设置"

无 MMR：
1. memory/2026-02-10.md (0.92) ← 路由器 + VLAN
2. memory/2026-02-08.md (0.89) ← 路由器 + VLAN（重复！）
3. memory/network.md (0.85)

有 MMR (λ=0.7)：
1. memory/2026-02-10.md (0.92) ← 路由器 + VLAN
2. memory/network.md (0.85) ← 参考文档（多样）
3. memory/2026-02-05.md (0.78) ← AdGuard DNS（多样）

decayedScore = score × e^(-λ × ageInDays)

if (local.modelPath 存在) return "local";
if (OpenAI key 可用) return "openai";
if (Gemini key 可用) return "gemini";
if (Voyage key 可用) return "voyage";
if (Mistral key 可用) return "mistral";
return disabled;

-- 文件表
CREATE TABLE files (
  path TEXT PRIMARY KEY,
  source TEXT,
  mtime INTEGER,
  hash TEXT
);
-- 分块表
CREATE TABLE chunks (
  id TEXT PRIMARY KEY,
  path TEXT,
  startLine INTEGER,
  endLine INTEGER,
  text TEXT,
  embedding BLOB,
  source TEXT
);
-- 向量表
CREATE VIRTUAL TABLE chunks_vec USING vec0(...);
-- 全文索引
CREATE VIRTUAL TABLE chunks_fts USING fts5(...);
-- Embedding 缓存
CREATE TABLE embedding_cache (
  hash TEXT PRIMARY KEY,
  embedding BLOB
);

tokenEstimate > contextWindow - reserveTokensFloor - softThresholdTokens

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          systemPrompt: "Session nearing compaction...",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md..."
        }
      }
    }
  }
}

{
  "provider": "openai",
  "query": { "hybrid": { "enabled": false } }
}

{
  "provider": "openai",
  "remote": { "batch": { "enabled": true } },
  "query": {
    "hybrid": {
      "enabled": true,
      "mmr": { "enabled": true, "lambda": 0.7 },
      "temporalDecay": { "enabled": true, "halfLifeDays": 30 }
    }
  }
}

{
  "provider": "local",
  "fallback": "none",
  "local": { "modelPath": "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF" }
}

{
  "cache": {
    "enabled": true,
    "maxEntries": 50000
  }
}

{
  "store": {
    "vector": {
      "enabled": true,
      "extensionPath": "/path/to/sqlite-vec"
    }
  }
}

# 查看状态
openclaw memory status
# 强制同步
openclaw memory sync --force
# 检查配置
openclaw config get agents.defaults.memorySearch

src/agents/skills/
├── types.ts           # 类型定义
├── config.ts          # 配置解析与过滤
├── workspace.ts       # 核心加载逻辑
├── frontmatter.ts     # SKILL.md 解析
├── filter.ts          # 技能过滤器
├── bundled-dir.ts     # 内置技能目录解析
├── bundled-context.ts # 内置技能缓存
├── plugin-skills.ts   # 插件技能集成
├── refresh.ts         # 文件监听与版本刷新
├── env-overrides.ts   # 环境变量注入
├── serialize.ts       # 并发控制锁
├── tools-dir.ts       # 工具目录路径
└── skills-install.ts  # 技能安装器

// workspace.ts:369-388
extra → bundled → managed → agents-skills-personal → agents-skills-project → workspace

type SkillEntry = {
  skill: Skill;
  frontmatter: ParsedSkillFrontmatter;
  metadata?: OpenClawSkillMetadata;
  invocation?: SkillInvocationPolicy;
};
type OpenClawSkillMetadata = {
  always?: boolean;
  skillKey?: string;
  primaryEnv?: string;
  emoji?: string;
  os?: string[];
  requires?: {
    bins?: string[];
    env?: string[];
    config?: string[];
  };
  install?: SkillInstallSpec[];
};
type SkillSnapshot = {
  prompt: string;
  skills: Array<{ name, primaryEnv, requiredEnv }>;
  skillFilter?: string[];
  resolvedSkills?: Skill[];
  version?: number;
};

// config.ts:70-101
shouldIncludeSkill() 检查:
1. config.skills.entries[skillKey].enabled !== false
2. bundled allowlist 检查
3. 运行时资格评估:
   - OS 兼容性
   - 二进制依赖
   - 环境变量依赖
   - 配置路径检查

---
name: github
description: "GitHub operations via `gh` CLI..."
metadata:
  openclaw:
    emoji: "🐙"
    requires:
      bins: ["gh"]
    install:
      - id: brew
        kind: brew
        formula: gh
        bins: ["gh"]
---
# GitHub Skill
...使用说明...

// skills.ts 导出
loadWorkspaceSkillEntries()     // 加载技能条目
buildWorkspaceSkillSnapshot()   // 构建快照（含 prompt）
buildWorkspaceSkillsPrompt()    // 生成 Agent prompt
filterWorkspaceSkillEntries()   // 过滤技能
buildWorkspaceSkillCommandSpecs() // 生成命令规格
syncSkillsToWorkspace()         // 同步到沙箱
applySkillEnvOverrides()        // 注入环境变量

// types.ts:3-17
type SkillInstallSpec = {
  kind: "brew" | "node" | "go" | "uv" | "download";
  formula?: string;   // brew formula
  package?: string;   // npm/go/uv 包名
  module?: string;    // go module
  url?: string;       // download URL
  // ...
};

// refresh.ts
ensureSkillsWatcher() // 监听 SKILL.md 变更
  → bumpSkillsSnapshotVersion() // 版本号递增
  → 事件通知 listeners

┌─────────────────────────────────────────────────────────────────┐
│                        会话管理层级                              │
├─────────────────────────────────────────────────────────────────┤
│  Session Key(身份标识)                                          │
│       ↓                                                         │
│  Session Entry(会话元数据)                                      │
│       ↓                                                         │
│  Session Store(持久化存储)                                      │
│       ↓                                                         │
│  Transcript File(对话历史)                                      │
└─────────────────────────────────────────────────────────────────┘

基础格式: agent:<agentId>:<rest>

示例:
- agent:main:main                    # 默认 agent 的主会话
- agent:ops:work                     # ops agent 的主会话
- agent:main:telegram:direct:user123 # Telegram DM 会话
- agent:main:discord:group:guild789  # Discord 群组会话
- agent:main:cron:daily-backup:run:uuid  # Cron 任务运行会话
- agent:main:subagent:child-session  # 子代理会话

function parseAgentSessionKey(sessionKey: string | undefined | null): ParsedAgentSessionKey | null {
  // 1. 规范化：小写、去空格
  const raw = (sessionKey ?? "").trim().toLowerCase();
  // 2. 验证最小结构 (agent:id:rest)
  const parts = raw.split(":").filter(Boolean);
  if (parts.length < 3 || parts[0] !== "agent") return null;
  // 3. 提取 agentId 和 rest
  return { agentId: parts[1], rest: parts.slice(2).join(":") };
}

type SessionEntry = {
  // === 身份标识 ===
  sessionId: string;        // UUID，关联对话历史文件
  sessionFile?: string;     // 自定义会话文件路径
  
  // === 模型配置 ===
  model?: string;           // 当前运行时模型
  modelProvider?: string;   // 当前运行时提供商
  modelOverride?: string;   // 用户指定的模型覆盖
  providerOverride?: string;// 用户指定的提供商覆盖
  contextTokens?: number;   // 上下文窗口大小
  
  // === Token 统计 ===
  totalTokens?: number;     // 总 token 数
  inputTokens?: number;     // 输入 token
  outputTokens?: number;    // 输出 token
  totalTokensFresh?: boolean; // token 数据是否新鲜
  
  // === 投递路由 ===
  lastChannel?: string;     // 最后使用的通道
  lastTo?: string;          // 最后发送目标
  lastAccountId?: string;   // 最后账号 ID
  lastThreadId?: string;    // 最后线程 ID
  deliveryContext?: DeliveryContext; // 投递上下文
  
  // === 会话状态 ===
  updatedAt?: number;       // 最后更新时间戳
  systemSent?: boolean;     // 系统消息是否已发送
  abortedLastRun?: boolean; // 上次运行是否中断
  
  // === 行为配置 ===
  thinkingLevel?: string;   // 思考级别
  verboseLevel?: string;    // 详细级别
  reasoningLevel?: string;  // 推理级别
  sendPolicy?: string;      // 发送策略
  
  // === 群组/频道元数据 ===
  chatType?: "direct" | "group" | "channel";
  channel?: string;         // 来源通道
  subject?: string;         // 主题/名称
  groupId?: string;         // 群组 ID
  groupChannel?: string;    // 频道名称
  space?: string;           // 空间/工作区
  
  // === 显示 ===
  displayName?: string;     // 显示名称
  label?: string;           // 用户标签
  
  // === 线程/派生 ===
  forkedFromParent?: boolean; // 是否从父会话派生
  spawnedBy?: string;       // 创建来源
  
  // === 压缩状态 ===
  compactionCount?: number; // 压缩次数
  memoryFlushAt?: number;   // 内存刷新时间
};

┌─────────────────────────────────────────────────────────────────┐
│                     会话初始化流程                               │
├─────────────────────────────────────────────────────────────────┤
│  1. 解析 Agent ID                                               │
│     resolveSessionAgentId({ sessionKey, config })               │
│                                                                 │
│  2. 加载会话存储                                                 │
│     loadSessionStore(storePath, { skipCache: true })            │
│                                                                 │
│  3. 检查重置触发器                                               │
│     匹配 /new, /reset 等命令                                    │
│                                                                 │
│  4. 评估会话新鲜度                                               │
│     evaluateSessionFreshness({ updatedAt, now, policy })        │
│                                                                 │
│  5. 处理线程派生 (可选)                                          │
│     forkSessionFromParent()                                     │
│                                                                 │
│  6. 持久化会话文件                                               │
│     resolveAndPersistSessionFile()                              │
│                                                                 │
│  7. 归档旧会话 (重置时)                                          │
│     archiveSessionTranscripts()                                 │
│                                                                 │
│  8. 触发插件钩子                                                 │
│     hookRunner.runSessionStart() / runSessionEnd()              │
└─────────────────────────────────────────────────────────────────┘

// 默认重置触发器
const DEFAULT_RESET_TRIGGERS = ["/new", "/reset"];

// 匹配逻辑
for (const trigger of resetTriggers) {
  if (trimmedBodyLower === triggerLower) {
    isNewSession = true;
    bodyStripped = "";  // 清空消息体
    resetTriggered = true;
  }
  // 支持带参数的重置: "/new 你好"
  if (strippedForResetLower.startsWith(triggerPrefixLower)) {
    isNewSession = true;
    bodyStripped = strippedForReset.slice(trigger.length).trimStart();
    resetTriggered = true;
  }
}

type ResetPolicy = {
  direct: number;   // DM 会话过期时间 (小时)
  group: number;    // 群组会话过期时间
  thread: number;   // 线程会话过期时间
};

// 默认策略
const DEFAULT_RESET_HOURS = { direct: 24, group: 4, thread: 24 };

// 评估函数
function evaluateSessionFreshness(params: {
  updatedAt: number;
  now: number;
  policy: ResetPolicy;
}): { fresh: boolean; reason?: string };

// 当父会话 token 过多时跳过派生，避免上下文溢出
const DEFAULT_PARENT_FORK_MAX_TOKENS = 100_000;

function forkSessionFromParent(params: {
  parentEntry: SessionEntry;
  agentId: string;
  sessionsDir: string;
}): { sessionId: string; sessionFile: string } | null {
  // 1. 打开父会话管理器
  const manager = SessionManager.open(parentSessionFile);
  
  // 2. 创建分支会话
  const sessionFile = manager.createBranchedSession(leafId);
  
  // 3. 或创建新的派生会话文件
  const header = {
    type: "session",
    version: CURRENT_SESSION_VERSION,
    id: sessionId,
    parentSession: parentSessionFile,  // 链接到父会话
  };
}

~/.openclaw/
├── agents/
│   ├── main/sessions.json      # main agent 的会话存储
│   ├── ops/sessions.json       # ops agent 的会话存储
│   └── ...
└── sessions.json               # 全局存储 (旧版兼容)

function loadCombinedSessionStoreForGateway(cfg: OpenClawConfig): {
  storePath: string;
  store: Record<string, SessionEntry>;
} {
  // 模板路径: 支持每个 agent 独立存储
  if (isStorePathTemplate(storeConfig)) {
    for (const agentId of agentIds) {
      const storePath = resolveStorePath(storeConfig, { agentId });
      const store = loadSessionStore(storePath);
      // 合并到 combined，以 canonicalKey 为键
    }
  }
  // 单一文件: 所有 agent 共享存储
  else {
    // 直接加载，规范化键名
  }
}

// 清理大小写不一致的遗留键
function pruneLegacyStoreKeys(params: {
  store: Record<string, unknown>;
  canonicalKey: string;
  candidates: Iterable<string>;
}) {
  // 1. 收集所有需要删除的键
  for (const candidate of candidates) {
    if (candidate !== canonicalKey) {
      keysToDelete.add(candidate);
    }
    // 2. 查找大小写变体
    for (const legacyKey of findStoreKeysIgnoreCase(store, candidate)) {
      if (legacyKey !== canonicalKey) {
        keysToDelete.add(legacyKey);
      }
    }
  }
  // 3. 批量删除
  for (const key of keysToDelete) {
    delete store[key];
  }
}eKeys(params: {  store: Record<string, unknown>;  canonicalKey: string;  candidates: Iterable<string>;}) {  // 1. 收集所有需要删除的键  for (const candidate of candidates) {    if (candidate !== canonicalKey) {      keysToDelete.add(candidate);    }    // 2. 查找大小写变体    for (const legacyKey of findStoreKeysIgnoreCase(store, candidate)) {      if (legacyKey !== canonicalKey) {        keysToDelete.add(legacyKey);      }    }  }  // 3. 批量删除  for (const key of keysToDelete) {    delete store[key];  }}

// 清理策略
const DEFAULT_RETENTION_MS = 24 * 3_600_000; // 24 小时
const MIN_SWEEP_INTERVAL_MS = 5 * 60_000;    // 最小清理间隔 5 分钟

async function sweepCronRunSessions(params: {
  cronConfig?: CronConfig;
  sessionStorePath: string;
}): Promise<ReaperResult> {
  // 1. 节流检查
  if (now - lastSweepAtMs < MIN_SWEEP_INTERVAL_MS) {
    return { swept: false, pruned: 0 };
  }
  
  // 2. 遍历存储，删除过期 cron 运行会话
  for (const key of Object.keys(store)) {
    if (isCronRunSessionKey(key) && entry.updatedAt < cutoff) {
      delete store[key];
      pruned++;
    }
  }
  
  // 3. 归档关联的对话文件
  archiveSessionTranscripts({ sessionId, reason: "deleted" });
}

async function recordInboundSession(params: {
  storePath: string;
  sessionKey: string;
  ctx: MsgContext;
  updateLastRoute?: InboundLastRouteUpdate;
}): Promise<void> {
  // 1. 记录入站消息元数据
  await recordSessionMetaFromInbound({
    storePath,
    sessionKey: canonicalSessionKey,
    ctx,
    groupResolution,
  });
  
  // 2. 更新投递路由
  await updateLastRoute({
    storePath,
    sessionKey: targetSessionKey,
    deliveryContext: {
      channel: update.channel,
      to: update.to,
      accountId: update.accountId,
      threadId: update.threadId,
    },
  });
}

function resolveLastChannelRaw(params: {
  originatingChannelRaw?: string;
  persistedLastChannel?: string;
  sessionKey?: string;
}): string | undefined {
  // 内部 webchat/系统消息不应覆盖已知的外部投递路由
  if (originatingChannel === INTERNAL_MESSAGE_CHANNEL) {
    // 优先使用已持久化的外部通道
    if (persistedChannel && isDeliverableMessageChannel(persistedChannel)) {
      return persistedChannel;
    }
    // 回退到 sessionKey 中编码的通道提示
    if (sessionKeyChannelHint && isDeliverableMessageChannel(sessionKeyChannelHint)) {
      return sessionKeyChannelHint;
    }
  }
}

用户指令/反馈 → Agent 修改文件 → 下次会话加载新内容 → 行为改变 → 持续迭代

const tiers = [
  { matchedBy: "binding.peer", ... },           // 1. 精确对等匹配
  { matchedBy: "binding.peer.parent", ... },    // 2. 父对等匹配（线程）
  { matchedBy: "binding.guild+roles", ... },    // 3. 公会+角色匹配
  { matchedBy: "binding.guild", ... },          // 4. 公会匹配
  { matchedBy: "binding.team", ... },           // 5. 团队匹配
  { matchedBy: "binding.account", ... },        // 6. 账户匹配
  { matchedBy: "binding.channel", ... },        // 7. 频道匹配
  { matchedBy: "default", ... }                 // 8. 默认代理
];

const bindings = [
  // 精确对等绑定
  {
    agentId: "support",
    match: {
      channel: "whatsapp",
      accountId: "biz",
      peer: { kind: "direct", id: "+1234567890" }
    }
  },
  // 公会绑定
  {
    agentId: "community",
    match: {
      channel: "discord",
      guildId: "123456789"
    }
  },
  // 角色绑定
  {
    agentId: "admin",
    match: {
      channel: "discord",
      guildId: "123456789",
      roles: ["admin", "moderator"]
    }
  }
];

type DmScope = 
  | "main"                      // 所有 DM 共享一个会话
  | "per-peer"                  // 每个对等有独立会话
  | "per-channel-peer"          // 每个频道+对等组合独立
  | "per-account-channel-peer"; // 每个账户+频道+对等组合独立

agent:{agentId}:{mainKey}                           // 主会话
agent:{agentId}:direct:{peerId}                     // per-peer DM
agent:{agentId}:{channel}:direct:{peerId}           // per-channel-peer DM
agent:{agentId}:{channel}:{accountId}:direct:{peerId}  // per-account-channel-peer
agent:{agentId}:{channel}:{peerKind}:{peerId}       // 群组/频道
agent:{agentId}:{channel}:{peerKind}:{peerId}:thread:{threadId}  // 线程

identityLinks: {
  alice: ["telegram:111111111", "discord:222222222222222222"]
}

binding 1: WhatsApp Business "company-a" -> agent "support-a"
binding 2: WhatsApp Business "company-b" -> agent "support-b"

binding 1: Guild "123" + Role "admin" -> agent "admin-bot"
binding 2: Guild "123" (no role) -> agent "community-bot"
binding 3: Channel "welcome" -> agent "greeter"

binding 1: Team "T-sales" -> agent "sales-assistant"
binding 2: Team "T-engineering" -> agent "tech-support"

Parent Channel "general" -> agent "general-bot"
Thread in "general" inherits parent binding

Node                              Gateway
  |-- node.pair.request -------------->|  (发起请求)
  |                                    |  (加入 pending 列表)
  |                                    |
  |<-------- 广播 node.pair.requested --|  (通知管理员)
  |                                    |
  |          [管理员审批]              |
  |                                    |
  |<------- node.pair.approve ---------|  (生成 token)
  |                                    |
  |-- node.pair.verify --------------->|  (验证 token)
  |                                    |
  |<----------- 连接建立 --------------|  (认证成功)

┌─────────────────────────────────────────────────┐
│                   Node Host                      │
├─────────────────────────────────────────────────┤
│  runner.ts                                      │
│    - 启动 WebSocket 客户端                       │
│    - 连接 Gateway                               │
│    - 声明 caps/commands                         │
├─────────────────────────────────────────────────┤
│  invoke.ts                                      │
│    - 处理 system.run/which/browser.proxy        │
│    - 执行本地命令                                │
│    - 管理执行审批                   │
├─────────────────────────────────────────────────┤
│  config.ts                                      │
│    - 存储 nodeId/token/gateway 配置             │
│    - ~/.openclaw/node.json                      │
└─────────────────────────────────────────────────┘

1. maybeWakeNodeWithApns()
   ├── 检查 APNS 注册
   ├── 发送后台唤醒通知
   └── 等待重连 (3s)

2. 如果仍离线，重试一次
   └── 发送后台唤醒 + 等待 (12s)

3. 如果仍离线
   └── maybeSendNodeWakeNudge()
       └── 发送可见提醒："OpenClaw needs a quick reopen"

客户端 → Gateway.node.invoke({nodeId, command, params})
          │
          ├── 检查节点是否连接
          │     └── 未连接 → APNS 唤醒
          │
          ├── 命令策略检查
          │     └── node-command-policy.ts
          │
          ├── NodeRegistry.invoke()
          │     └── WebSocket 发送 node.invoke.request
          │
          └── Node Host 处理
                ├── invoke.ts 路由到具体 handler
                ├── 执行命令 (spawn + 安全检查)
                └── 返回 node.invoke.result

单用户信任模型：
┌─────────────────────────────────────┐
│  一个可信操作者                      │
│  ├── 一个 Gateway                   │
│  │   └── 多个 Agent                 │
│  └── 多个会话（sessionKey 是路由控制，不是授权边界）
└─────────────────────────────────────┘

插件 = 可信代码
├── 可以读取环境变量/文件
├── 可以执行主机命令
└── 与 Gateway 进程权限相同

agents.defaults.sandbox.mode: off  # 默认关闭沙箱
tools.exec.host: sandbox          # 路由偏好，但沙箱未激活时在主机执行

信任边界：
├── 主机 OS/管理员边界 = 信任边界
├── 能修改 ~/.openclaw 的人 = 可信操作者
└── 推荐模式：一用户一主机/VPS一Gateway

# 推荐：仅绑定回环地址
gateway.bind="loopback"  # 默认值
openclaw gateway run --bind loopback

# 远程访问方案：
# 1. SSH 隧道
# 2. Tailscale serve/funnel
# 3. 不要直接暴露到公网

# 推荐
tools.exec.applyPatch.workspaceOnly: true  # 限制写入到工作区

# 可选
tools.fs.workspaceOnly: true  # 限制所有文件操作到工作区

src/config/
├── io.ts              # 配置I/O核心引擎
├── paths.ts           # 路径解析策略
├── validation.ts      # 多层验证框架
├── zod-schema.ts      # Zod模式定义
├── defaults.ts        # 运行时默认值应用
├── includes.ts        # $include模块化支持
├── env-substitution.ts # 环境变量替换
└── types.ts           # TypeScript类型聚合

// 支持环境变量
{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"  // 运行时替换
      }
    }
  }
}

加载 → 解析 → 合并 → 验证 → 应用默认值 → 缓存

function loadConfig(): OpenClawConfig {
  // 1. 读取原始JSON5文件
  const raw = deps.fs.readFileSync(configPath, "utf-8");
  const parsed = deps.json5.parse(raw);
  
  // 2. 解析$include指令
  const resolved = resolveConfigIncludesForRead(parsed, configPath, deps);
  
  // 3. 环境变量替换
  const { resolvedConfigRaw } = resolveConfigForRead(resolved, deps.env);
  
  // 4. 验证与默认值
  const validated = validateConfigObjectWithPlugins(resolvedConfigRaw);
  const cfg = applyModelDefaults(applyAgentDefaults(validated.config));
  
  // 5. 路径规范化
  normalizeConfigPaths(cfg);
  
  return cfg;
}

// openclaw.json
{
  "$include": [
    "./models/anthropic.json5",
    "./channels/telegram.json5"
  ],
  "gateway": {
    "mode": "remote"
  }
}

// 拒绝访问配置目录外的文件
if (!isPathInside(this.rootDir, normalized)) {
  thrownew ConfigIncludeError(
    `Include path escapes config directory: ${includePath}`,
    includePath
  );
}

// 解析符号链接并重新验证
const real = fs.realpathSync(normalized);
if (!isPathInside(this.rootRealDir, real)) {
  thrownew ConfigIncludeError(
    `Include path resolves outside config directory (symlink)`,
    includePath
  );
}nside(this.rootDir, normalized)) {  thrownew ConfigIncludeError(    `Include path escapes config directory: ${includePath}`,    includePath  );}// 解析符号链接并重新验证const real = fs.realpathSync(normalized);if (!isPathInside(this.rootRealDir, real)) {  thrownew ConfigIncludeError(    `Include path resolves outside config directory (symlink)`,    includePath  );}

export function deepMerge(target: unknown, source: unknown): unknown {
  if (Array.isArray(target) && Array.isArray(source)) {
    return [...target, ...source]; // 数组连接
  }
  if (isPlainObject(target) && isPlainObject(source)) {
    const result = { ...target };
    for (const key of Object.keys(source)) {
      result[key] = key in result 
        ? deepMerge(result[key], source[key]) // 递归合并
        : source[key];
    }
    return result;
  }
  return source; // 原始类型: 后值覆盖前值
}

// 验证流水线
validateConfigObjectWithPlugins(raw)
  → validateConfigObjectRaw(raw)        // 1. 基础Zod验证
  → findLegacyConfigIssues(raw)         // 2. 历史配置检查
  → findDuplicateAgentDirs(config)      // 3. Agent目录冲突检测
  → validateIdentityAvatar(config)      // 4. Avatar路径安全验证
  → validatePluginSchemas(config)       // 5. 插件配置验证

exportconst OpenClawSchema = z.object({
  // 元数据自动时间戳处理
  meta: z.object({
    lastTouchedAt: z.union([
      z.string(),
      z.number().transform((n, ctx) => {
        const d = new Date(n);
        if (Number.isNaN(d.getTime())) {
          ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Invalid timestamp" });
          return z.NEVER;
        }
        return d.toISOString();
      })
    ]).optional()
  }).strict().optional(),
  
  // Gateway配置
  gateway: z.object({
    mode: z.union([z.literal("local"), z.literal("remote")]).optional(),
    auth: z.object({
      mode: z.union([
        z.literal("none"),
        z.literal("token"),
        z.literal("password"),
        z.literal("trusted-proxy")
      ]).optional(),
      token: z.string().optional().register(sensitive) // 敏感值标记
    }).strict().optional()
  }).strict().optional(),
  
  // 跨字段验证
}).superRefine((cfg, ctx) => {
  // 验证broadcast中的agentId是否存在于agents.list
  const agentIds = new Set(cfg.agents?.list?.map(a => a.id) ?? []);
  for (const [peerId, ids] of Object.entries(cfg.broadcast ?? {})) {
    for (const agentId of ids) {
      if (!agentIds.has(agentId)) {
        ctx.addIssue({
          code: z.ZodIssueCode.custom,
          path: ["broadcast", peerId],
          message: `Unknown agent id "${agentId}"`
        });
      }
    }
  }
});

for (const record of registry.plugins) {
  const pluginId = record.id;
  const entry = normalizedPlugins.entries[pluginId];
  
  if (record.configSchema) {
    const res = validateJsonSchemaValue({
      schema: record.configSchema,
      cacheKey: record.schemaCacheKey ?? pluginId,
      value: entry?.config ?? {}
    });
    
    if (!res.ok) {
      issues.push({
        path: `plugins.entries.${pluginId}.config`,
        message: `invalid config: ${res.errors.join(", ")}`
      });
    }
  }
}

function resolveConfigForRead(resolvedIncludes, env){
  // 1. 应用config.env到process.env
  applyConfigEnvVars(resolvedIncludes, env);
  
  // 2. 替换${VAR}引用
  return {
    resolvedConfigRaw: resolveConfigEnvVars(resolvedIncludes, env),
    envSnapshotForRestore: { ...env } // 保存快照用于回写
  };
}

// 写入前恢复原始的${VAR}引用
cfgToWrite = restoreEnvVarRefs(
  cfgToWrite,
  parsedRes.parsed,     // 原始文件内容
  envForRestore          // 读取时的环境变量快照
);

// 加载时应用默认值
const cfg = applyModelDefaults(
  applyAgentDefaults(
    applySessionDefaults(validated.config)
  )
);

// 写入时不包含运行时默认值
const stampedOutputConfig = stampConfigVersion(outputConfig);
// 不调用 applyModelDefaults

const DEFAULT_CONFIG_CACHE_MS = 200; // 200ms TTL

export function loadConfig(): OpenClawConfig {
  // 检查运行时快照
  if (runtimeConfigSnapshot) {
    return runtimeConfigSnapshot;
  }
  
  // 检查缓存
  const cached = configCache;
  if (cached && cached.configPath === configPath && cached.expiresAt > now) {
    return cached.config;
  }
  
  // 加载并更新缓存
  const config = io.loadConfig();
  configCache = {
    configPath,
    expiresAt: now + cacheMs,
    config
  };
  
  return config;
}

const auditRecord = {
  ts: new Date().toISOString(),
  event: "config.write",
  result: "rename" | "copy-fallback" | "failed",
  configPath,
  previousHash,
  nextHash,
  previousBytes,
  nextBytes,
  changedPathCount,
  suspicious: [
    "size-drop",           // 大小骤降50%+
    "missing-meta-before-write",
    "gateway-mode-removed"
  ],
  pid, ppid, cwd, argv
};

await appendConfigWriteAuditRecord(deps, auditRecord);

function formatConfigValidationFailure(pathLabel, issueMessage){
  const match = issueMessage.match(OPEN_DM_POLICY_ALLOW_FROM_RE);
  if (!match) return `Config validation failed: ${pathLabel}: ${issueMessage}`;
  
  return [
    `Configuration mismatch: ${policyPath} is "open", but ${allowPath} does not include "*".`,
    "",
    "Fix with:",
    `  openclaw config set ${allowPath} '["*"]'`,
    "",
    "Or switch policy:",
    `  openclaw config set ${policyPath} "pairing"`
  ].join("\n");
}

export function findLegacyConfigIssues(raw: unknown): LegacyConfigIssue[] {
  const issues: LegacyConfigIssue[] = [];
  
  // 检测已移除的配置项
  if (raw.routing?.allowFrom) {
    issues.push({
      path: "routing.allowFrom",
      message: "routing.allowFrom is removed. Use routing.channels.*.dm.policy instead."
    });
  }
  
  // 检测废弃的命名
  if (raw.gateway?.token) {
    issues.push({
      path: "gateway.token",
      message: 'Use "gateway.auth.token" instead.'
    });
  }
  
  return issues;
}

exportconst BLOCKED_OBJECT_KEYS = new Set([
  "__proto__",
  "constructor",
  "prototype"
]);

export function isBlockedObjectKey(key: string): boolean {
  return BLOCKED_OBJECT_KEYS.has(key);
}

exportconst sensitive = Symbol("sensitive");

export function redactSensitiveValues(config: unknown): unknown {
  // 递归遍历配置对象
  // 替换标记为sensitive的值为"[REDACTED]"
}

// 目录权限: 0o700 (仅所有者可访问)
await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });

// 文件权限: 0o600 (仅所有者可读写)
await fs.promises.writeFile(tmp, json, { encoding: "utf-8", mode: 0o600 });

export interface PluginConfigSchema {
  id: string;
  kind: "channel" | "memory" | "tool" | "skill";
  configSchema?: JSONSchema;
  channels?: string[];
}

export function applyConfigOverrides(config: OpenClawConfig): OpenClawConfig {
  // 允许通过环境变量覆盖特定配置项
  // 例如: OPENCLAW_OVERRIDE_gateway_mode=local
  return config;
}