OpenClaw.NET 技术解读(第一篇):架构、插件、部署与 AOT

摘要：OpenClaw.NET 是一个面向 .NET 的 AI Agent 运行时与网关，强调 NativeAOT 友好与 OpenClaw 生态的实用兼容。本文从架构分层、插件体系、常用运维（后台运行、模型切换）到 AOT 语义做系统梳理，便于技术团队评估与落地。

一、项目定位与适用人群

OpenClaw.NET 提供：

• Agent 运行时
  
  ：工具调用、流式输出、取消与重试、会话与记忆等。
• 网关（Gateway）
  
  ：Web 聊天与管理后台、OpenAI 兼容 HTTP 面、MCP、WebSocket、健康检查与诊断等。
• 多形态客户端
  
  ：CLI、桌面 Companion、TUI、.NET 客户端库等。

README 已明确说明：与上游 OpenClaw 无官方隶属关系，是独立的 .NET 实现，面向希望 本地或自托管、且偏好 .NET 技术栈与可观测性 的开发者与运维人员。

技术栈要点：主体为 C# / .NET；WhatsApp 等场景通过 Node / Go 子进程 做桥接，属于集成层扩展，不改变「网关 + Agent 核心在 .NET」这一主线。

二、架构分层与数据流

可概括为一条心智模型：

用户 / 外部渠道 → 网关 → 会话与运行时 → 大模型 → 工具与集成 → 响应

可选：Semantic Kernel、Microsoft Agent Framework 等适配器以独立项目存在，默认核心路径保持精简。

源码入口提示：OpenClaw.Gateway/Program.cs 完成 Slim WebApplication 构建、Bootstrap、InitializeOpenClawRuntimeAsync、Pipeline 与 MapOpenClawEndpoints；Agent 主循环在 AgentRuntime（RunAsync / RunStreamingAsync）。

三、快速上手（两条路径）

3.1 无密钥冒烟（验证工具链）

dotnet restore OpenClaw.Net.slnxdotnet build OpenClaw.Net.slnx -c Release --no-restoredotnet run --project samples/OpenClaw.HelloAgent -c Release --no-build

预期可看到 Agent 回复与 echo 工具执行，证明 运行时 + 工具路径 正常。

3.2 本地网关 + 浏览器

设置模型密钥后：

export MODEL_PROVIDER_KEY="你的密钥"dotnet run --project src/OpenClaw.Cli -c Release -- start

启动成功后常见地址：

• 聊天：http://127.0.0.1:18789/chat
• 管理：http://127.0.0.1:18789/admin
• MCP：http://127.0.0.1:18789/mcp

更完整流程见仓库内 docs/QUICKSTART.md、docs/USER_GUIDE.md。

四、模型与网络：从 OpenAI 切到 Qwen 等

若日志出现 No route to host (api.openai.com:443)，多为 本机到 OpenAI 官方域名不可达（路由、防火墙或区域网络策略），与 API Key 是否正确无关。此时应 更换提供商或走本地推理，避免仍指向 api.openai.com。

路径 A：本机 Ollama + Qwen

• 安装 Ollama，拉取模型（如 qwen2.5）。
• 配置中设置 Provider: ollama，Endpoint 使用原生根地址（如 http://127.0.0.1:11434），勿长期使用已弃用提示的仅 /v1 兼容 URL（openclaw models doctor 会提示迁移）。

路径 B：云端 OpenAI 兼容接口（如阿里云 DashScope）

• 使用 Provider: openai-compatible，必须配置兼容模式的 Endpoint，并设置对应 ApiKey（可用 env:变量名 引用环境变量）。

具体字段以 docs/USER_GUIDE.md 与当前服务商文档为准。

五、插件模块：不止「一个插件系统」

配置集中在 PluginsConfig，常见几类并存：

发现与过滤：PluginDiscovery 按配置路径、工作区 .openclaw/extensions、用户目录 ~/.openclaw/extensions 等扫描；Filter 处理 Allow/Deny、按插件启用状态及 Kind + Slots（互斥槽位，如同类 memory 只保留一个）。

网关组装：LoadPluginCompositionAsync 在启用插件时创建 PluginHost，加载 Bridge 工具并注册渠道、命令、Provider 等；最终工具列表经 NativePluginRegistry.ResolvePreference 与内置工具、原生副本合并，同名工具由 Prefer（native/bridge）与 Overrides 决定优先级（内置工具名不被插件覆盖）。

配置校验：PluginConfigValidator 对 manifest 中的 ConfigSchema 做 JSON Schema 子集 校验，避免任意复杂 Schema 导致行为不可控。

六、后台常驻运行

官方推荐（生成 systemd / launchd 单元）：

openclaw setup service --config ~/.openclaw/config/openclaw.settings.json --platform all

会在配置文件同级目录下的 deploy/ 写出 openclaw-gateway.service、ai.openclaw.gateway.plist、Caddyfile 等；需 手动安装 到系统服务管理器（Linux systemctl、macOS launchctl）。注意：生成单元默认基于 仓库根目录的 dotnet run --project src/OpenClaw.Gateway，适合从源码部署的机器；若仅保留 已发布的 AOT 二进制，应自行改写 ExecStart 指向实际路径。

容器：docker run -d 或 Compose 中 restart: unless-stopped，见 docs/DOCKERHUB.md。

临时方案：nohup、tmux、screen 等适合开发机，不具备服务管理器的自动拉起能力。

七、AOT：编译形态与运行模式

两层含义不要混用：

1. 发布形态
   
   ：dotnet publish ... -p:PublishAot=true 得到 原生可执行文件，无 JIT；发行包中的 gateway/cli AOT 压缩包即此类。
2. 配置 OpenClaw:Runtime:Mode
   
   ：auto / aot / jit。auto 在支持动态代码的进程中倾向 jit，在纯 AOT 产物中则为 aot；若显式 jit 而二进制不支持动态代码，启动会失败。

策略要点：Bridge 插件在 AOT 下仍可通过 进程外 边界使用；进程内动态加载的 .NET 插件（Native Dynamic）依赖反射与 JIT，在 AOT 有效模式下会被策略拦截。细节见 PluginCapabilityPolicy 与 docs/COMPATIBILITY.md。

八、安全与运维提示（节选）

• 绑定 非 loopback 时，网关对危险默认会 拒绝启动，除非按 SECURITY.md 完成加固（令牌、工具根目录、签名校验等）。
• 出站请求默认受 URL 安全策略 约束，可按环境扩展阻断列表。

九、文档与延伸阅读

结语

OpenClaw.NET 将 网关、Agent 循环、工具与渠道 收束在一条清晰的 .NET 主线上，并通过 Bridge / MCP / 原生副本 分层兼容外部生态。第二篇若需要，可单拆 「从一次 HTTP 请求到 AgentRuntime 的调用链」 或 「插件 Bridge 与 JSON-RPC 边界」 做深度导读。

版权声明：本文基于开源仓库 OpenClaw.NET 公开代码与文档整理，仅供技术交流；产品行为以对应版本源码及官方文档为准。

关于转载：若发布至公众号，建议保留项目名、仓库链接与 MIT 许可说明；若对原文有删改，请注明「有删节」。