Harness 与 Agent 工程 · MCP与框架接入 · 2026-03-26

深入理解OpenClaw技术架构与实现原理(下)

揭秘OpenClaw沙箱系统的企业级安全架构,看阿里如何打造AI智能体安全防线。

核心内容:

  1. OpenClaw沙箱系统的核心安全机制与隔离策略
  2. 多层级容器管理与工具权限控制体系
  3. 实战配置示例与安全最佳实践

三、各系统模块讲解

3.8 SandBox 沙箱系统

Sandbox 是 OpenClaw 的 Docker 隔离层,用于在容器中执行 AI Agent 的工具操作,而非直接在主机上运行。

3.8.1 核心目的

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 安全限制

禁止的绑定挂载:

禁止的网络模式:

默认安全配置:

3.8.7 工具策略层级

隔离时工具过滤顺序:

  1. 全局工具策略
  2. Agent 特定策略
  3. Sandbox 工具策略(只能进一步限制)
  4. 子 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 命令

3.9 记忆管理

3.9.1 核心设计理念

OpenClaw 的记忆系统采用 "文件即真相" 的设计哲学:

3.9.2 记忆文件布局

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

分层设计:

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)

核心职责:

关键特性:

记忆搜索工具

3.9.5 混合搜索机制

搜索流程

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

为什么需要混合搜索?

向量搜索优势:

向量搜索劣势:

BM25 优势:

分数融合算法

finalScore = vectorWeight * vectorScore + textWeight * textScore

权重归一化为 1.0,默认 vectorWeight=0.7,textWeight=0.3

3.9.6 后处理机制

MMR(最大边际相关性)去重

目的:避免返回重复或高度相似的片段

算法:

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

λ 参数:

查询:"家庭网络设置"无 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 天

常青文件(不衰减):

3.9.7 Embedding 提供商

支持的提供商

  1. OpenAI - text-embedding-3-small(默认)
  2. Gemini - gemini-embedding-001
  3. Voyage - voyage-4-large
  4. Mistral - mistral-embed
  5. 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;

批量索引

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);

索引更新策略

触发条件:

  1. 会话启动时(sync.onSessionStart)
  2. 搜索前(sync.onSearch)
  3. 定时刷新(可配置间隔)
  4. 文件变化(watcher,防抖 1.5s)

会话索引:

3.9.9 自动记忆刷新

预压缩提示

触发时机:会话接近自动压缩时

机制:

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..." } } } }}

3.9.10 最佳实践

何时写入记忆

配置建议

小型语料库:

{ "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 }}
好处:

sqlite-vec 加速

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

好处:

3.9.12 CLI 命令

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

OpenClaw 的记忆管理系统是一个生产级的混合记忆解决方案,核心优势:

  1. 简洁直观:Markdown 文件,人类可读可编辑
  2. 强大灵活:语义搜索、混合检索、多种提供商
  3. 自动化:自动索引、自动刷新、预压缩保存
  4. 可扩展:插件架构、实验性后端
  5. 隐私优先:本地存储、支持完全本地运行

这个设计体现了现代 AI Agent 记忆管理的最佳实践:让文件成为真相,让索引成为加速器。

3.10 Skills 模块详解

Skills 模块位于 src/agents/skills/,是 OpenClaw Agent 能力扩展的核心模块。

3.10.1 核心概念

Skill = 一个封装了特定能力的 Markdown 文件 (SKILL.md),包含:

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 安全机制

  1. 路径安全:resolveSandboxPath() 防止路径穿越
  2. 环境变量安全:sanitizeSkillEnvOverrides() 过滤危险变量
  3. 代码扫描:安装前 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-…

— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/Openclaw/2026032691375.html