OpenClaw.NET 技术解读(第四篇):OpenClaw.Core 核心库

摘要：Gateway 负责组装进程，Agent 负责对话循环；OpenClaw.Core 则是跨进程的 共享契约层：配置模型、会话与持久化抽象、消息管道、安全与校验、插件与技能元数据、可观测性原语。本篇按目录与职责梳理，并说明它为何被标为 AOT 友好。

一、定位与包身份

OpenClaw.Core 在 csproj 中的描述是：abstractions, models, validation, security, and memory primitives（抽象、模型、校验、安全、内存原语）。它被 Gateway、Agent、Channels、CLI 等引用，是 “领域模型 + 可插拔接口 + 横切能力” 的集中地，而不是某个 HTTP 宿主。

    <IsAotCompatible>true</IsAotCompatible>    <Description>Core abstractions, models, validation, security, and memory primitives for OpenClaw.NET.</Description>

为何单独成库：把 GatewayConfig、Session、InboundMessage、IMemoryStore、ITool 等稳定边界沉淀在这里，宿主与运行时只做组合；便于测试、裁剪（trim）与 NativeAOT 发布。

二、目录地图（按文件夹）

仓库内约 百余个 C# 文件，可按顶层文件夹快速导航：

三、配置：GatewayConfig 是一棵大树

几乎所有运行时行为都能追溯到 GatewayConfig（见 Models/GatewayConfig.cs）：绑定地址与端口、Runtime（Mode / Orchestrator）、Llm、Memory（Provider、Sqlite、Mempalace 子块）、Plugins、Skills、Security、Channels、Tooling、Sandbox、Delegation……

网关启动时的 ConfigValidator 对这棵树做一致性校验；Core 还提供 GatewayConfigFile、ConfigPathResolver 等，支持外部 JSON 与环境变量合并。理解 Core 的第一步往往是：你要改的行为落在哪个配置节点下。

四、会话与内存：端口与实现分离

IMemoryStore 定义会话与持久化笔记、分支等的最小契约：

public interface IMemoryStore{    ValueTask<Session?> GetSessionAsync(string sessionId, CancellationToken ct);    ValueTask SaveSessionAsync(Session session, CancellationToken ct);    ValueTask<string?> LoadNoteAsync(string key, CancellationToken ct);    ValueTask SaveNoteAsync(string key, string content, CancellationToken ct);    ValueTask DeleteNoteAsync(string key, CancellationToken ct);    ValueTask<IReadOnlyList<string>> ListNotesWithPrefixAsync(string prefix, CancellationToken ct);    // ── Conversation Branching ─────────────────────────────────────────    ValueTask SaveBranchAsync(SessionBranch branch, CancellationToken ct);    ValueTask<SessionBranch?> LoadBranchAsync(string branchId, CancellationToken ct);    ValueTask<IReadOnlyList<SessionBranch>> ListBranchesAsync(string sessionId, CancellationToken ct);    ValueTask DeleteBranchAsync(string branchId, CancellationToken ct);}

扩展接口（如 IMemoryNoteSearch、ISessionAdminStore）由具体存储实现；Gateway 在注册 DI 时根据 Memory.Provider 选择 文件 / Sqlite / 动态插件（如 MemPalace）。

SessionManager 在内存中维护 活跃会话字典、每会话信号量、准入与超时扫描，并把负载落到 IMemoryStore：

/// <summary>/// Manages active sessions with automatic expiry. Thread-safe, allocation-light./// </summary>public sealed class SessionManager : IAsyncDisposable, IDisposable{    private readonly ConcurrentDictionary<string, Session> _active = new();

会话键约定 channelId:senderId 或显式 sessionId（文档与源码注释中有说明），渠道与 Web UI 共用同一套会话语义。

五、消息管道：MessagePipeline

MessagePipeline 使用 System.Threading.Channels 实现有界入站/出站队列，用于在高负载下 背压、避免无界堆积：

/// <summary>/// High-throughput, zero-allocation message pipeline using System.Threading.Channels./// Bounded channel applies backpressure to prevent OOM under load./// </summary>public sealed class MessagePipeline : IAsyncDisposable

Gateway 侧的 Worker 从 Reader 取 InboundMessage，再交给 MiddlewarePipeline 与 Agent；出站同理。Core 定义消息信封（如 Models/Messages.cs），保证 Host 与 Channels 解耦。

六、插件与安全策略

• Plugins/
  
  ：发现、manifest、配置校验、AOT 下能力封锁策略（与 PluginCapabilityPolicy、GatewayRuntimeMode 配合），详见系列第一篇、第二篇。
• Security/
  
  ：密钥解析、URL 拉取安全、工具路径策略、配对与 Ed25519 等——与 SECURITY.md 中的运维建议一一对应。
• Validation/
  
  ：启动前配置校验、模型 doctor、provider smoke，减少 “服务起来了但运行时才炸” 的概率。

七、技能与兼容性

Skills/ 负责加载 SKILL.md、拼装注入提示词；Compatibility/ 嵌入 public-smoke.json 等兼容矩阵数据，供 CLI/Admin 展示。它们把「生态兼容」从 Gateway 里剥离成 可版本化的数据 + 纯逻辑。

八、与前几篇的衔接

延伸阅读（仓库内）

版权声明：基于开源仓库 OpenClaw.NET 整理，仅供技术交流。