三、各系统模块讲解
3.8 SandBox 沙箱系统
Sandbox 是 OpenClaw 的 Docker 隔离层,用于在容器中执行 AI Agent 的工具操作,而非直接在主机上运行。
3.8.1 核心目的
- 限制工具执行(exec、read、write、edit 等)的安全边界
- 减少模型执行意外操作时的"爆炸半径"
- 提供可配置的隔离级别
3.8.2 关键文件结构
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 # 容器自动清理
3.8.3 沙箱模式
| 模式 | 行为 |
|---|---|
| "off" | 不隔离,所有工具直接在主机运行 |
| "non-main" | 仅隔离非主会话(默认) |
| "all" | 所有会话都隔离 |
3.8.4 容器作用域
| 作用域 | 容器数量 |
|---|---|
| "session" | 每个会话一个容器(默认) |
| "agent" | 每个 Agent 一个容器 |
| "shared" | 所有会话共享一个容器 |
3.8.5 工作区访问权限
| 权限 | 挂载行为 |
|---|---|
| "none" | 完全隔离的工作区 ~/.openclaw/sandboxes |
| "ro" | 只读挂载 Agent 工作区到 /agent |
| "rw" | 读写挂载到 /workspace |
3.8.6 安全限制
禁止的绑定挂载:
- 系统路径:/etc、/proc、/sys、/dev、/root、/boot、/run
- Docker socket:/var/run/docker.sock
- 根文件系统:/
禁止的网络模式:
- host(绕过网络隔离)
- container:
默认安全配置:
- 只读根文件系统 (readOnlyRoot: true)
- 无网络 (network: "none")
- 丢弃所有能力 (capDrop: ["ALL"])
3.8.7 工具策略层级
隔离时工具过滤顺序:
- 全局工具策略
- Agent 特定策略
- Sandbox 工具策略(只能进一步限制)
- 子 Agent 策略
默认允许的工具:exec、read、write、edit、apply_patch、image 等 默认禁止的工具:browser、canvas、nodes、cron、gateway 及所有消息通道
3.8.8 配置示例
{ "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 } } } }}
3.8.9 CLI 命令
- openclaw sandbox list - 列出沙箱容器
- openclaw sandbox recreate - 强制重建容器
- openclaw sandbox explain - 调试当前配置
3.9 记忆管理
3.9.1 核心设计理念
OpenClaw 的记忆系统采用 "文件即真相" 的设计哲学:
- 存储介质:纯 Markdown 文件(人类可读可编辑)
- 索引机制:SQLite + 向量嵌入(机器可搜索)
- 工作模式:文件优先,索引辅助
3.9.2 记忆文件布局
~/.openclaw/workspace/├── MEMORY.md # 长期记忆(精选、持久化)└── memory/ └── YYYY-MM-DD.md # 每日记忆日志(append-only)
分层设计:
- MEMORY.md:长期记忆,存储决策、偏好、重要事实
- memory/YYYY-MM-DD.md:短期记忆,存储日常笔记、临时上下文
3.9.3 核心类型定义
type MemorySource = "memory" | "sessions";type MemorySearchResult = { path: string; // 文件路径 startLine: number; // 起始行号 endLine: number; // 结束行号 score: number; // 相关性得分 snippet: string; // 文本片段(~700 字符) source: MemorySource; // 来源类型 citation?: string; // 引用标注};
3.9.4 核心功能模块
记忆索引管理器 (MemoryIndexManager)
核心职责:
- 管理 SQLite 索引数据库
- 协调向量化搜索和全文搜索
- 监视文件变化并自动同步
- 处理 embedding 提供商
关键特性:
- 单例模式:通过缓存避免重复实例
- 混合搜索:向量 + BM25 关键词
- 自动同步:文件监视 + 定时刷新
- 会话集成:delta 更新机制
记忆搜索工具
- memory_search - 语义搜索
- 基于向量嵌入的语义检索
- 返回相关片段(路径 + 行号 + 得分)
- 支持 MMR 去重和时间衰减
- memory_get - 定向读取
- 按路径读取特定记忆文件
- 支持行范围查询
- 安全检查(防止路径穿越)
3.9.5 混合搜索机制
搜索流程
用户查询 ↓关键词提取 (FTS)向量嵌入 ↓并行搜索 ├─ 向量搜索(语义相似) └─ BM25 搜索(关键词匹配) ↓加权融合 ↓后处理 ├─ 时间衰减 └─ MMR 去重 ↓Top-K 结果
为什么需要混合搜索?
向量搜索优势:
- 理解语义:"Mac Studio gateway host" ≈ "运行 gateway 的机器"
- 容错性强:拼写错误、同义词
向量搜索劣势:
- 对精确 token 弱:ID、代码符号、错误字符串
BM25 优势:
- 精确匹配:a828e60、memorySearch.query.hybrid
- 高信号 token
分数融合算法
finalScore = vectorWeight * vectorScore + textWeight * textScore
权重归一化为 1.0,默认 vectorWeight=0.7,textWeight=0.3
3.9.6 后处理机制
MMR(最大边际相关性)去重
目的:避免返回重复或高度相似的片段
算法:
score = λ × relevance - (1-λ) × max_similarity_to_selected
λ 参数:
- 1.0:纯相关性(不去重)
- 0.0:最大多样性(忽略相关性)
- 默认 0.7:平衡
查询:"家庭网络设置"无 MMR:1. memory/2026-02-10.md (0.92) ← 路由器 + VLAN2. 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) ← 路由器 + VLAN2. memory/network.md (0.85) ← 参考文档(多样)3. memory/2026-02-05.md (0.78) ← AdGuard DNS(多样)
时间衰减
目的:让近期记忆排名更高
公式:
decayedScore = score × e^(-λ × ageInDays)
半衰期:默认 30 天
- 今天:100%
- 7 天:84%
- 30 天:50%
- 90 天:12.5%
常青文件(不衰减):
- MEMORY.md
- 非日期命名的文件(如 memory/projects.md)
3.9.7 Embedding 提供商
支持的提供商
- OpenAI - text-embedding-3-small(默认)
- Gemini - gemini-embedding-001
- Voyage - voyage-4-large
- Mistral - mistral-embed
- Local - 本地模型
自动选择逻辑
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;
批量索引
- OpenAI Batch API:异步处理,折扣价格
- Gemini Batch:异步 embeddings 批量端点
- 并发控制:默认 2 个并发批处理任务
3.9.8 索引管理
SQLite 数据库结构
-- 文件表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);
索引更新策略
触发条件:
- 会话启动时(sync.onSessionStart)
- 搜索前(sync.onSearch)
- 定时刷新(可配置间隔)
- 文件变化(watcher,防抖 1.5s)
会话索引:
- 基于 delta 阈值:100KB 字节 或 50 条消息
- 异步更新,不阻塞搜索
3.9.9 自动记忆刷新
预压缩提示
触发时机:会话接近自动压缩时
机制:
tokenEstimate > contextWindow - reserveTokensFloor - softThresholdTokens
行为:
- 发送静默提示:"Session nearing compaction. Store durable memories now."
- 模型可能回复(但通常 NO_REPLY)
- 每个压缩周期仅触发一次
- 只在可写工作空间执行
配置示例
{ 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..." } } } }}
3.9.10 最佳实践
何时写入记忆
- 长期记忆:决策、偏好、重要事实 → MEMORY.md
- 短期记忆:日常笔记、运行上下文 → 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" }}
3.9.11 性能优化
Embedding 缓存
{ "cache": { "enabled": true, "maxEntries": 50000 }}
好处:
- 避免重复嵌入相同文本
- 加速增量更新
- 降低 API 成本
sqlite-vec 加速
{ "store": { "vector": { "enabled": true, "extensionPath": "/path/to/sqlite-vec" } }}
好处:
- 数据库内向量计算
- 避免加载所有 embedding 到 JS
- 查询速度提升显著
3.9.12 CLI 命令
## 查看状态openclaw memory status# 强制同步openclaw memory sync --force# 检查配置openclaw config get agents.defaults.memorySearch
OpenClaw 的记忆管理系统是一个生产级的混合记忆解决方案,核心优势:
- 简洁直观:Markdown 文件,人类可读可编辑
- 强大灵活:语义搜索、混合检索、多种提供商
- 自动化:自动索引、自动刷新、预压缩保存
- 可扩展:插件架构、实验性后端
- 隐私优先:本地存储、支持完全本地运行
这个设计体现了现代 AI Agent 记忆管理的最佳实践:让文件成为真相,让索引成为加速器。
3.10 Skills 模块详解
Skills 模块位于 src/agents/skills/,是 OpenClaw Agent 能力扩展的核心模块。
3.10.1 核心概念
Skill = 一个封装了特定能力的 Markdown 文件 (SKILL.md),包含:
- YAML frontmatter(元数据)
- 使用指南/命令模板
3.10.2 目录结构
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 # 技能安装器
3.10.3 Skill 加载优先级(从低到高)
// workspace.ts:369-388extra → bundled → managed → agents-skills-personal → agents-skills-project → workspace
| 来源 | 路径 | 说明 |
|---|---|---|
| extra | config.skills.load.extraDirs | 用户自定义目录 |
| bundled | skills/ (包内) | OpenClaw 内置技能 |
| managed | ~/.openclaw/skills | 全局管理技能 |
| agents-skills-personal | ~/.agents/skills | 个人 agents 目录 |
| agents-skills-project | 项目 agents 目录 | |
| workspace | 项目技能 (最高优先) |
3.10.4 核心类型
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;};
3.10.5 技能过滤逻辑
// config.ts:70-101shouldIncludeSkill() 检查:1. config.skills.entries[skillKey].enabled !== false2. bundled allowlist 检查3. 运行时资格评估: - OS 兼容性 - 二进制依赖 - 环境变量依赖 - 配置路径检查
3.10.6 SKILL.md 结构示例
---name: githubdescription: "GitHub operations via `gh` CLI..."metadata: openclaw: emoji: "🐙" requires: bins: ["gh"] install: - id: brew kind: brew formula: gh bins: ["gh"]---# GitHub Skill...使用说明...
3.10.7 关键导出 API
// skills.ts 导出loadWorkspaceSkillEntries() // 加载技能条目buildWorkspaceSkillSnapshot() // 构建快照(含 prompt)buildWorkspaceSkillsPrompt() // 生成 Agent promptfilterWorkspaceSkillEntries() // 过滤技能buildWorkspaceSkillCommandSpecs() // 生成命令规格syncSkillsToWorkspace() // 同步到沙箱applySkillEnvOverrides() // 注入环境变量
3.10.8 安装支持类型
// types.ts:3-17type SkillInstallSpec = { kind: "brew" | "node" | "go" | "uv" | "download"; formula?: string; // brew formula package?: string; // npm/go/uv 包名 module?: string; // go module url?: string; // download URL // ...};
3.10.9 文件监听机制
// refresh.tsensureSkillsWatcher() // 监听 SKILL.md 变更 → bumpSkillsSnapshotVersion() // 版本号递增 → 事件通知 listeners
3.10.10 安全机制
- 路径安全:resolveSandboxPath() 防止路径穿越
- 环境变量安全:sanitizeSkillEnvOverrides() 过滤危险变量
- 代码扫描:安装前 scanDirectoryWithSummary() 检查危险模式
3.11 Session 管理
3.11.1 整体架构设计
┌─────────────────────────────────────────────────────────────────┐│ 会话管理层级 │├─────────────────────────────────────────────────────────────────┤│ Session Key(身份标识) ││ ↓ ││ Session Entry(会话元数据) ││ ↓ ││ Session Store(持久化存储) ││ ↓ ││ Transcript File(对话历史) │└─────────────────────────────────────────────────────────────────┘
3.11.2 Session Key 设计
1. 会话键格式规范
基础格式: 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 # 子代理会话
2. 会话键解析(session-key-utils.ts:12-32)****
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(":") };}
3. 会话类型判断
| 类型 | 识别模式 | 示例 |
|---|---|---|
| direct | 包含 :direct: 或 :dm: | agent:main:telegram:direct:user123 |
| group | 包含 :group: | agent:main:discord:group:guild789 |
| channel | 包含 :channel: | agent:main:slack:channel:C123 |
| cron | rest 以 cron: 开头 | agent:main:cron:backup |
| subagent | 包含 :subagent: | agent:main:subagent:child |
| thread | 包含 :thread: 或 :topic: | agent:main:discord:group:123:thread:456 |
3.11.3 Session Entry 数据结构
核心字段(config/sessions/types.ts 相关)
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; // 内存刷新时间};
3.11.4 会话生命周期管理
1. 会话初始化流程(auto-reply/reply/session.ts:165-579)
┌─────────────────────────────────────────────────────────────────┐│ 会话初始化流程 │├─────────────────────────────────────────────────────────────────┤│ 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() │└─────────────────────────────────────────────────────────────────┘
2. 重置触发器机制(auto-reply/reply/session.ts:249-273)
// 默认重置触发器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; }}
3. 会话新鲜度策略(config/sessions/reset.ts 相关)
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 };
4. 线程派生机制 (auto-reply/reply/session.ts:123-163)
// 当父会话 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, // 链接到父会话 };}
3.11.5 会话存储机制
1. 存储结构(gateway/session-utils.ts:575-618)
~/.openclaw/├── agents/│ ├── main/sessions.json # main agent 的会话存储│ ├── ops/sessions.json # ops agent 的会话存储│ └── ...└── sessions.json # 全局存储 (旧版兼容)
2. 多 Agent 存储合并(gateway/session-utils.ts:575-…