OpenClaw Agent 运行时架构：沙箱、记忆、技能、会话与配置管理

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                         # 容器自动清理

/etc
/proc
/sys
/dev
/root
/boot
/run
/var/run/docker.sock
/

{
  "readOnlyRoot": true,
  "network": "none",
  "capDrop": ["ALL"]
}

exec
read
write
edit
apply_patch
image

browser
canvas
nodes
cron
gateway
消息通道类工具

{
  "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 sandbox list       # 列出沙箱容器
openclaw sandbox recreate   # 强制重建容器
openclaw sandbox explain    # 查看当前沙箱配置如何生效

~/.openclaw/workspace/
├── MEMORY.md
└── memory/
    └── YYYY-MM-DD.md

type MemorySource = "memory" | "sessions";

type MemorySearchResult = {
  path: string;           // 文件路径
  startLine: number;      // 起始行号
  endLine: number;        // 结束行号
  score: number;          // 相关性得分
  snippet: string;        // 文本片段
  source: MemorySource;   // memory 或 sessions
  citation?: string;      // 引用标注
};

finalScore = vectorWeight × vectorScore + textWeight × textScore

vectorWeight = 0.7
textWeight   = 0.3

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

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

if (local.modelPath exists) return "local";
if (OPENAI_API_KEY exists) return "openai";
if (GEMINI_API_KEY exists) return "gemini";
if (VOYAGE_API_KEY exists) return "voyage";
if (MISTRAL_API_KEY exists) 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(...);

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

openclaw memory status
openclaw memory sync --force
openclaw config get agents.defaults.memorySearch

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

Use `gh` CLI for repository, issue, pull request and workflow operations.

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     # 技能安装器

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: string;
    primaryEnv?: string;
    requiredEnv?: string[];
  }>;
  skillFilter?: string[];
  resolvedSkills?: Skill[];
  version?: number;
};

type SkillInstallSpec = {
  kind: "brew" | "node" | "go" | "uv" | "download";
  formula?: string;
  package?: string;
  module?: string;
  url?: string;
};

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

agent:<agentId>:<rest>

agent:main:main
agent:ops:work
agent:main:telegram:direct:user123
agent:main:discord:group:guild789
agent:main:cron:daily-backup:run:uuid
agent:main:subagent:child-session

function parseAgentSessionKey(sessionKey: string | undefined | null) {
  const raw = (sessionKey ?? "").trim().toLowerCase();
  const parts = raw.split(":").filter(Boolean);

  if (parts.length < 3 || parts[0] !== "agent") {
    return null;
  }

  return {
    agentId: parts[1],
    rest: parts.slice(2).join(":")
  };
}

const DEFAULT_RESET_TRIGGERS = ["/new", "/reset"];

/new 请帮我重新规划这个任务

type ResetPolicy = {
  direct: number;
  group: number;
  thread: number;
};

const DEFAULT_RESET_HOURS = {
  direct: 24,
  group: 4,
  thread: 24
};

const DEFAULT_PARENT_FORK_MAX_TOKENS = 100_000;

const header = {
  type: "session",
  version: CURRENT_SESSION_VERSION,
  id: sessionId,
  parentSession: parentSessionFile
};

~/.openclaw/
├── agents/
│   ├── main/
│   │   └── sessions.json
│   ├── ops/
│   │   └── sessions.json
│   └── ...
└── sessions.json

function pruneLegacyStoreKeys(params: {
  store: Record<string, unknown>;
  canonicalKey: string;
  candidates: Iterable<string>;
}) {
  const keysToDelete = new Set<string>();

  for (const candidate of params.candidates) {
    if (candidate !== params.canonicalKey) {
      keysToDelete.add(candidate);
    }

    for (const legacyKey of findStoreKeysIgnoreCase(params.store, candidate)) {
      if (legacyKey !== params.canonicalKey) {
        keysToDelete.add(legacyKey);
      }
    }
  }

  for (const key of keysToDelete) {
    delete params.store[key];
  }
}

const DEFAULT_RETENTION_MS = 24 * 3_600_000;
const MIN_SWEEP_INTERVAL_MS = 5 * 60_000;

deliveryContext: {
  channel: update.channel,
  to: update.to,
  accountId: update.accountId,
  threadId: update.threadId
}

~/.openclaw/workspace

一个用户 / 一台主机 / 一个 Gateway / 多个 Agent

openclaw gateway run --bind loopback

gateway.bind = "loopback"

tools.exec.applyPatch.workspaceOnly = true

tools.fs.workspaceOnly = true

src/config/
├── io.ts                  # 配置 I/O 主流程
├── paths.ts               # 配置路径解析
├── validation.ts          # 多层验证
├── zod-schema.ts          # Zod Schema
├── defaults.ts            # 运行时默认值
├── includes.ts            # $include 模块化配置
├── env-substitution.ts    # 环境变量替换
└── types.ts               # TypeScript 类型聚合

{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}" // 运行时替换
      }
    }
  }
}

function loadConfig(): OpenClawConfig {
  const raw = fs.readFileSync(configPath, "utf-8");
  const parsed = json5.parse(raw);

  const resolvedIncludes =
    resolveConfigIncludesForRead(parsed, configPath, deps);

  const { resolvedConfigRaw } =
    resolveConfigForRead(resolvedIncludes, deps.env);

  const validated =
    validateConfigObjectWithPlugins(resolvedConfigRaw);

  const cfg = applyModelDefaults(
    applyAgentDefaults(validated.config)
  );

  normalizeConfigPaths(cfg);

  return cfg;
}

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

if (!isPathInside(this.rootDir, normalized)) {
  throw new ConfigIncludeError(
    `Include path escapes config directory: ${includePath}`,
    includePath
  );
}

const real = fs.realpathSync(normalized);

if (!isPathInside(this.rootRealDir, real)) {
  throw new ConfigIncludeError(
    "Include path resolves outside config directory (symlink)",
    includePath
  );
}

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)
  → findLegacyConfigIssues(raw)
  → findDuplicateAgentDirs(config)
  → validateIdentityAvatar(config)
  → validatePluginSchemas(config)

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}"`
      });
    }
  }
}

function resolveConfigForRead(resolvedIncludes, env) {
  applyConfigEnvVars(resolvedIncludes, env);

  return {
    resolvedConfigRaw: resolveConfigEnvVars(resolvedIncludes, env),
    envSnapshotForRestore: { ...env }
  };
}

cfgToWrite = restoreEnvVarRefs(
  cfgToWrite,
  parsedRes.parsed,
  envForRestore
);

const DEFAULT_CONFIG_CACHE_MS = 200;

OPENCLAW_DISABLE_CONFIG_CACHE=1

size-drop
missing-meta-before-write
gateway-mode-removed

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

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

[REDACTED]

await fs.promises.mkdir(dir, {
  recursive: true,
  mode: 0o700
});

await fs.promises.writeFile(tmp, json, {
  encoding: "utf-8",
  mode: 0o600
});