1. 项目概述与核心价值

1.1 为什么我会盯上这个项目

先交代一下背景。这几年我折腾过不少 Agent 框架，从最早基于 Python 的 heavyweight 方案，到后来一堆靠 Node.js 撑起来的编排引擎，说实话，各有各的痛。Python 那套生态确实全，但你真要部署到生产环境，特别是丢到低配云主机或者边缘盒子上，冷启动延迟、内存占用、依赖体积，每一项都能让人血压升高。Node 系相对轻点，可一旦牵扯到复杂的本地工具链和跨语言调用，又总觉得隔着一层纱，调试起来非常别扭。

所以当我看到“OpenClaw.NET —— 自托管、多模型、NativeAOT 的 Agent 平台”这个标题时，第一反应是：终于有人把目光从解释型语言挪到编译型语言上了。这个项目让我眼前一亮的地方不在于它又封装了多少花哨的 Agent 能力，而在于它选了一条看起来很笨、实际上非常讨巧的技术路线：用 .NET 写 Agent 运行时，再用 NativeAOT 直接编成原生二进制。这意味着什么？意味着你可以把整个 Agent 平台打成单个可执行文件，丢到一台只有 256MB 内存的 VPS 上，开机即跑，不需要装 .NET 运行时，不需要拖着一堆 DLL，甚至不需要 Python 解释器。

这个项目解决的痛点非常明确：自托管场景下的资源占用、部署复杂度和多模型切换的灵活性问题。它适合谁？适合那些对数据隐私有要求、不想把所有对话记录都送到云端的人；适合那些手头有几台闲置小机器、想跑个私有 Agent 服务的人；也适合那些纯粹受够了 Python 启动慢、想试试 .NET 在 AI 应用领域能翻出什么花样的技术爱好者。后面我会把整个平台的架构思路、核心实现、实战部署和排坑过程都摊开来讲，保证你读完能自己动手搭一套。

1.2 项目定位：不是又一个玩具 Demo

在拆解技术细节之前，我想先聊聊这个项目的定位问题。现在市面上号称“Agent 平台”的东西太多了，但绝大多数停留在“调个 API、拼个 Prompt、串几个工具函数”的层面。这类东西演示起来很酷，可真要丢到生产环境，你立刻会撞上几个绕不开的坎：第一，会话状态怎么持久化，总不能每次重启都从零开始；第二，多模型之间怎么平滑切换，用户可能今天用 A 厂商的模型，明天又换了 B 厂商；第三，工具调用（Function Calling）怎么管理，Agent 不能只会聊天，它得能真正干点事，比如查数据库、发请求、操作文件。

OpenClaw.NET 的定位显然不是玩具。它选择了“自托管”这个场景，就意味着默认用户有独立的部署环境，有对数据控制权的需求。它选择了“多模型”，说明在设计上就考虑了不同模型厂商、不同模型规格之间的差异，而不是绑死某一家。它选择了 NativeAOT，这是在性能、体积和部署便捷性上的一次明确表态：我们要做一个能真正跑在轻量环境里的东西，而不是又一个靠容器硬扛的解释型应用。

就我个人的理解，这个项目更像是给那些想要深度定制 Agent 行为的开发者准备的“工作台”，而不是给小白用户准备的“聊天机器人外壳”。它的核心价值在于：把 Agent 的运行时基础设施（模型接入、会话管理、工具注册、本地执行）用一套类型安全、性能可预期的技术栈重新实现了一遍，让开发者在上面叠加自己的业务逻辑时，底子足够稳。

2. 技术选型：为什么是 .NET、多模型和 NativeAOT

2.1 .NET 在 AI Agent 领域的独特身位

聊到 AI 应用开发，大家第一反应基本都是 Python，这个刻板印象其实也没错，毕竟生态在那里摆着。但你有没有想过一个问题：Agent 应用本质上是什么？它其实是一个长时间运行、需要处理并发请求、需要和外部系统频繁交互的服务器程序。只不过它的“业务逻辑”是由大模型驱动的而已。从这个角度看，Agent 平台对运行时/编译器的基础能力要求非常高：稳定、快速、内存可控、并发安全、部署方便。

这些东西恰恰是 .NET 的老本行。.NET 的垃圾回收器在服务端场景下经过了十几年打磨，PGO（Profile-Guided Optimization）等优化手段也越来越成熟；异步编程模型 async/await 的完善程度在主流语言里是第一梯队；再加上 Span、Memory 这些高性能类型，处理大量 token 级别的字符串操作时优势明显。你可能觉得这些和写 Agent 有什么关系？关系大了。Agent 的核心循环里有一大堆字符串拼接、协议解析、JSON 序列化工作，这些工作在解释型语言里就是纯 CPU 开销和内存碎片化的来源，而在 .NET 里可以做到接近 C 语言的效率，同时又不用手动管内存。

当然，我并不是说 Python 写不了 Agent。事实上我自己很多快速原型都用 Python 做。但一旦你想把它变成一个 7x24 小时跑着的服务，并且部署在低配机器上，.NET 的性价比就会凸显出来。这也解释了为什么 OpenClaw.NET 会出现在这个时间点：基础设施已经足够成熟，做 Agent 平台底层的人开始有更好的选择了。

2.2 多模型接入的架构意义

再说“多模型”。这个设计决策的深意不在于“我支持一百种模型”，而在于“我不绑定任何单一厂商”。现在的模型格局显然不会永远维持现状，今天你用一个闭源模型做主力，明天可能因为成本、合规性能或效果问题换一个开源模型。如果你的 Agent 平台在代码层面和某个厂商的 API 格式深度耦合，那么换模型将会是一场灾难。

OpenClaw.NET 把多模型作为核心特性，意味着它在架构设计上必须做到接口抽象和实现解耦。这套设计在业务上带来的好处非常直接：你可以把同一个 Agent、同一套 Prompt、同一组工具函数，无缝地从模型 A 切到模型 B，观察效果差异。你可以让不同的任务走不同的模型，例如简单分类用便宜的小模型，复杂推理用强大的旗舰模型。这种负载拆分的能力，恰恰是企业落地 Agent 应用时最需要的。

从我接触过的一些实际项目来看，多模型能力最大的价值反而不是“省钱”，而是“容灾”。假设你依赖某一家云厂商的模型服务，结果那边出故障了或者限流了，你的整个 Agent 平台就跟着瘫痪。有多模型接入能力，你至少可以快速切换到备用模型，保住核心业务流程。这个价值平时不起眼，出了事就是救命稻草。

2.3 NativeAOT：一场围绕部署体验的隐形革命

NativeAOT 这玩意儿，很多 .NET 开发者可能也只是听说过。简单解释一下：我们平时写 C# 代码，默认编译成 IL（中间语言），然后运行时（CoreCLR）用 JIT 编译成机器码。JIT 的好处是灵活性高，能根据运行时的实际热点做动态优化，坏处是冷启动有额外开销，而且内存占用不小。NativeAOT 则是在发布时直接通过 AOT（Ahead-Of-Time）编译机制，把 IL 直接编译成目标平台的原生机器码，最终产物是单个可执行文件，运行的时候不再需要 JIT，也不需要加载运行时。

你可能会问：那 JIT 的动态优化不要了，性能会不会下降？这是个好问题。在某些 CPU 密集场景下，JIT 经过充分预热后的性能确实可能超过 AOT 编译。但对于 Agent 平台这类应用，真正的瓶颈往往在模型 API 的调用、网络 IO 和外部工具执行上，CPU 算力反而不是最关键的资源。而 NativeAOT 带来的好处却是实打实的：启动时间可以压到几十毫秒级别；磁盘上不再需要几百 MB 的运行时和依赖库；内存占用也大幅下降。举个例子，我见过太多用 Python 写的 Agent 服务，光冷启动就能吃掉 80 到 100MB 内存，模型推理的上下文一长，内存直接飘到 300MB 以上。同样的逻辑用 .NET NativeAOT 来承载，驻留内存能控制在 40MB 以内，启动速度甚至可以在数秒内完成初始化。

还有个很容易忽略的点：NativeAOT 发布出来的单文件，减小了攻击面。因为你的应用不再依赖一堆动态链接库和可被替换的运行时组件，整体被注入恶意代码的途径少了很多。这对自托管环境特別有意义，毕竟你部署的机器可能暴露在网络中，底子干净一点总是好的。

3. 核心架构拆解：一个 Agent 平台应有的自我修养

3.1 整体分层与模块划分

从标题和项目实际的内容结构来看，OpenClaw.NET 大体上可以分成五个层次：

• 接入层：负责统一暴露 HTTP 接口给前端应用或其他服务，接收用户请求，返回 Agent 执行结果。这一层可以理解为系统的“门面”。
• 编排层：负责管理 Agent 的运行流程，包括对话轮次的控制、Prompt 的组织、上下文窗口的管理，以及对工具调用请求的调度。
• 模型适配层：这是“多模型”的关键所在。它内部定义了统一协议，并为各家模型厂商提供各自的适配器，将不同风格的 API 归一化到统一协议上。
• 工具层：管理 Agent 可以调用的工具，例如 HTTP 请求工具、数据库查询工具、文件操作工具、自定义 Webhook 工具等。工具都会注册成一个标准结构（名称、描述、参数 Schema），框架通过模型结构将其暴露给大模型。
• 基础设施层：包括配置系统、日志系统、状态存储（会话持久化）、错误处理和重试机制等。

这个分层逻辑非常清晰，而且是可插拔的。你想接一个新模型，只需要写一个适配器；你想给 Agent 加一个能力，只需要注册一个新工具；你想换一套持久化方案，只需要动基础设施层。这种模块化程度是 Agent 平台能持续演进的基础，否则代码很快就变成一团理不清的意大利面了。

3.2 Agent 核心循环：从用户输入到工具调用的完整链路

Agent 和普通聊天机器人最本质的区别，就是它具备“思考—行动—观察”的循环能力。在 OpenClaw.NET 中，这个循环大致如下：

1. 用户发来一条消息。
2. 平台把当前会话的历史上下文、系统提示词和可用工具列表一起发给模型。
3. 模型返回两种可能的结果：要么是最终的文本回复；要么是一个工具调用请求，包含工具名称和参数。
4. 如果是工具调用请求，平台在本地安全地执行对应的工具函数，拿到结果。
5. 平台把工具执行结果作为新的上下文，再次发给模型，让模型基于真实结果继续回答。
6. 重复上述过程，直到模型返回最终回复或达到最大轮数。

这个循环的精髓在于，它让模型不再只是“说话”，而是可以“做事”。OpenClaw.NET 的实现中，循环里最考验设计功力的是状态管理：每一轮对话产生了多少上下文，哪些内容需要保留，哪些内容可以总结压缩，当超出模型上下文窗口上限时如何截断或摘要，这些细节直接决定了 Agent 在长对话场景下的可靠性和稳定性。

3.3 会话与上下文管理：比你想的更复杂

很多新手在做 Agent 时容易犯一个低级错误：把所有历史消息一股脑全部塞给模型，直到把上下文窗口塞爆。OpenClaw.NET 的做法显然会更讲究。它对会话进行结构化存储，每条消息都带有角色标识（system/user/assistant/tool）、时间戳、token 占用估算等元数据。在每一轮请求前，框架会按照模型的最大上下文限制，结合预留给工具结果和系统提示词的空间，动态计算可用的上下文窗口，再从历史记录中选取合适的消息填入。

这里面有大量的工程细节值得学习。举例来说，系统提示词可能要固定占用 1000 个 token，工具定义加起来可能又占了 2000 个 token，模型总窗口 32000 token，那么留给对话历史的就只剩 29000 token。如果历史太长了怎么办？可以选择截断最早的对话，也可以选择用一个小模型把早期对话总结成摘要，再把摘要放进去。OpenClaw.NET 允许通过配置来控制这些策略，给开发者留下了足够的定制空间。在本地私有化部署的场景下，这类精细控制能让资源利用率提升一个档次。

3.4 多模型适配器的设计原则：统一协议如何搞定差异化

每家模型厂商的 API 风格差异很大。有些是 OpenAI 兼容格式，有些是 Anthropic 风格，还有一些国产模型提供了自己搞的独特协议。如果为每一个模型的 API 格式单独写一套 Agent 核心逻辑，那代码几乎无法维护。OpenClaw.NET 的策略是定义一套“最小公共协议”，也就是不管后端的真实模型是什么，在框架内部都统一成一种消息格式、一种工具调用格式和一种流式返回格式。

这种适配器模式的价值在切换模型时体现得非常明显。你从模型 A 切到模型 B，只需要把配置里那个适配器的名字改一下，应用层代码一行都不用动。甚至在多模型并行场景下，框架可以同时连接多个模型服务，把不同的请求路由到不同的模型上。这种灵活程度对我这种喜欢折腾各种模型的人来说，简直是刚需。实际工作中，我经常需要对比不同模型在相同 Prompt 和工具集下的表现，有了统一适配层，这种对比实验的成本降到了极低。

4. 实操部署：从源码到自托管服务的完整指南

4.1 环境准备和工具链安装

既然要用 NativeAOT 发布，环境准备这块有几个硬性要求要先过一遍。首先你得装好 .NET SDK，版本不能太低，我建议直接用最新的 LTS 版本，比如 .NET 8，因为 NativeAOT 的编译链在 .NET 8 上已经非常成熟。然后按照你本机的平台，还需要安装对应的 C++ 编译器和链接器。

不同系统上的情况不完全一致，我把常见平台的配置要点列在下面，方便你对照排查：

提示：先确认环境没问题再往下走。NativeAOT 编译时会调用系统的编译链来产出原生二进制，这一步如果报错，十有八九是环境依赖没装全。

4.2 获取源码与首次构建

源码通常托管在公开仓库上，直接把仓库 clone 到本地：

git clone https://example.com/openclaw-net.git cd openclaw-net

然后先做一次常规发布，验证代码完整性和依赖恢复是否正常：

dotnet restore dotnet build -c Release

如果这一步顺利通过，说明工程本身没有断掉的依赖。接下来才是重头戏，用 NativeAOT 模式发布。发布命令可以在项目目录下执行，也可以通过命令行指定项目路径：

dotnet publish -c Release -r linux-x64 --self-contained -p:PublishAot=true

这里简单解释一下命令里几个关键参数：

• -r linux-x64：指定目标运行时标识符，你部署到什么平台就填什么平台。如果部署到 ARM 设备，换成linux-arm64；如果是 Windows 服务器，换成win-x64。
• --self-contained：表示把 .NET 运行时也一起打包进产物，配合 NativeAOT 后一般没有额外的运行时文件。
• -p:PublishAot=true：打开 NativeAOT 编译开关，这个属性是开启 AOT 发布的核心。

发布完成后，在bin/Release/net8.0/linux-x64/publish/目录下会得到一个单文件可执行程序，文件大小通常在 10 到 20MB 左右。你可以用file命令检查一下产物类型：

file ./OpenClaw.NET

正常情况下输出会显示这是一个 ELF 可执行文件，而不是托管程序集。

4.3 配置文件结构与首次启动

OpenClaw.NET 保持了一贯的简洁风格，配置一般集中在单个配置文件中。以下是一个最简配置的示例（实际字段名以项目文档为准）：

{ "Server": { "Host": "0.0.0.0", "Port": 8080 }, "Models": [ { "Name": "primary", "Provider": "OpenAICompatible", "Endpoint": "http://127.0.0.1:11434/v1", "ApiKey": "local-key", "Model": "qwen2.5:7b", "MaxTokens": 4096, "Temperature": 0.7 } ], "Session": { "StoreType": "Sqlite", "ConnectionString": "Data Source=openclaw.db" }, "Tools": { "Enabled": ["http", "file", "calculator"] } }

上面这个配置的要点有几个：模型端点我填的是本地的 11434 端口，因为本地已经跑了一个 Ollama 服务，OpenAI 兼容协议可以轻松对接；会话存储用 SQLite，这是自托管场景下最省事的方案；工具只开了 HTTP、文件和计算器三个，主要为了演示。

配置好之后，直接运行：

./OpenClaw.NET --config ./config.json

启动日志通常会输出监听地址、当前加载的模型信息和已注册的工具列表。如果一切顺利，你会看到类似下面的日志片段：

[info] OpenClaw.NET started. Listen on http://0.0.0.0:8080 [info] Model "primary" connected, provider: OpenAICompatible [info] 3 tools registered: http, file, calculator

看到这几行，就说明核心服务已经起来了。接下来可以发一个测试请求，最简单的办法用 curl：

curl -X POST http://localhost:8080/api/chat \ -H "Content-Type: application/json" \ -d '{"session_id": "test-1", "message": "帮我算一下 123 * 456，然后用一份简洁的文案回复"}'

这个请求会触发 Agent 的完整循环：模型收到问题、调用计算器工具、工具返回结果、模型整理文案。响应中会包含最终回复以及调用链路的追踪信息，方便你观察 Agent 都做了哪些动作。

4.4 注册自定义工具：以股票行情查询为例

纯粹用内置工具演示没太大意思，不如尝试做一个自定义工具。我先说明一下思路：互联网上的许多数据，例如股票行情、天气、时区等等，开放 API 其实非常多。我们以“外部 HTTP 接口查询行情”为例，把工具函数注册进 Agent。

在 OpenClaw.NET 中，一个工具的核心是一个方法，外加一个标准的“工具定义”元数据。伪代码如下：

[AgentTool("stock_quote", Description = "查询股票代码的最新行情")] public async Task<string> GetStockQuote(string symbol) { var url = $"https://example-market-api.com/quote?symbol={symbol}"; var json = await _httpClient.GetStringAsync(url); return json; }

这段代码的精髓在于框架通过特性标注（Attribute）自动识别工具，提取工具名称、描述和参数列表，然后生成模型的工具 Schema。模型在执行过程中如果判断需要查行情，就会以标准结构发起调用：

{ "name": "stock_quote", "arguments": "{\"symbol\": \"12345\"}" }

框架收到这个调用请求后，反射到对应方法并传入参数，拿到返回值后进行安全转义，再发给模型。整个过程非常顺滑。有了这个扩展机制，你可以在几十行代码内给 Agent 增加任意本地能力，比如查数据库、执行 PowerShell 脚本、调用内部微服务等。

4.5 部署到低配云主机的实际体验

我在折腾完本地部署后，顺手把服务丢到了一台配置很低的小机器上做了个压力测试。这台机器只有 1 核 CPU、512MB 内存、20GB SSD。运行实测结果是这样的：部署时整个目录就一个可执行文件加一个配置文件，总占用不到 25MB；服务启动完成后驻留内存稳定在 40MB 左右，基础进程占用很低；发起一轮模型调用后，Agent 自身的内存只涨了不到 10MB，因为真正耗时的是等模型 API 返回，期间 Agent 不需要做大量本地计算。

对比我之前用 Python 框架部署的经验，同样功能的 Agent 服务光内存基线就是 200MB 起步，启动要 3 到 5 秒。OpenClaw.NET 在资源占用上的优势简直像降维打击。所以如果你手上正好有一台吃灰的旧电脑或者云服务器，非常值得跑一套试试，你会发现原来 Agent 平台也可以这么轻。

5. 踩坑记录：NativeAOT 与 Agent 平台的暗面

5.1 反射限制是 NativeAOT 最大的坎

NativeAOT 虽好，但它有一个先天约束：AOT 编译时无法在运行时动态加载程序集，也不支持随意的反射操作。这意味着你在写代码时不能依赖运行时动态创建类型、或者使用大量Activator.CreateInstance之类的模式。编译器在构建时会做“剪裁”（Trimming）分析，把那些可能不会被代码显式引用的类型直接移除。如果你的代码在某些角落动态引用了没被识别到的类型，运行时就可能莫名其妙抛出找不到类型的异常。

我在实际开发中就撞到过一次。有个工具注册器是通过反射扫描某一程序集下所有的类型，运行时再创建实例。发布成 NativeAOT 后，所有类型全被剪裁掉了，日志里只留下一句“类型不存在”的报错。排查了很久才发现是反射扫描的方式在 AOT 模式下根本走不通。解决办法是在代码中显式引用这些类型，或者通过调整发布参数禁用剪裁。因此，如果你打算深度使用 NativeAOT，开发时就要尽早把动态反射的逻辑尽量改成静态泛型或者显式注册，否则后期再改代价非常高。

5.2 JSON 序列化需要 Source Generator 加持

和反射问题同源的还有 JSON 序列化。默认情况下，很多序列化库依赖运行时反射来读取对象属性。在 NativeAOT 模式下，反射被削了，序列化经常失灵。OpenClaw.NET 的处理方式应该是强依赖 Source Generator。简单理解，Source Generator 就是在编译阶段直接把序列化代码生成好，不需要运行时反射。

这意味着你在定义模型请求、工具参数这些数据结构时，要使用[JsonSerializable]这类特性来告诉编译器提前生成序列化代码。下面是一个示例思路：

[JsonSerializable(typeof(ChatRequest))] [JsonSerializable(typeof(ToolCall))] [JsonSerializable(typeof(ToolResult))] internal partial class AppJsonContext : JsonSerializerContext { }

然后在注入序列化器时，把这个AppJsonContext手动传进去。如果你更愿意省事，也可以考虑用别的序列化库，但建议一律启用其 Source Generator 模式。这是能跑 NativeAOT 的前提。

5.3 依赖库的 AOT 兼容性需要提前确认

不是所有 NuGet 包都做好了 AOT 适配。有些包在常规模式下跑得好好的，一开 AOT 发布就报错误。常见的问题包括：使用System.Reflection.Emit动态生成 IL、使用Expression.Compile()动态编译表达式树，以及依赖AppDomain相关功能。这些都属于 AOT 的绝对禁区。

我的建议是在引入任何第三方包之前，先去它的项目主页或者 release notes 里搜一下是否有 AOT 相关的说明。而对 OpenClaw.NET 本身，你也可以多关注它后续的 release 记录，看它对依赖库的选择是否有明确说明。如果确实需要一个不兼容 AOT 的库，就得权衡是放弃 AOT，还是换一个功能相近的兼容库。

5.4 流式输出和缓冲策略的取舍

Agent 平台必然涉及大模型的流式输出（SSE 或者 WebSocket 推送）。NativeAOT 在这个场景下的表现总体让人安心，因为流式输出本质就是大量小片段的高频写入，很考验运行时对 IO 缓冲和异步连续操作的处理能力。实测下来，.NET 的 async 模型在高频小包场景下很稳定，GC 停顿几乎感知不到。

但有一点值得注意：如果流式输出的每个片段都强行走 Persistence 存储，频繁写入数据库会产生性能瓶颈。我们在实践中采用的策略是：默认只在完整回复生成后写库；如果必须要实时记录流式片段，可以走内存缓冲并在一定时间间隔批量刷盘。这类优化虽然和 AOT 没有直接关系，但在真实部署环境下对稳定性的影响非常明显。

5.5 发布产物跨平台要注意的目标信息差异

跨平台发布 NativeAOT 时，很多人容易忽略的一点是：程序的 XAML 资源、文化信息、时区数据等组件在不同平台上行为有差异。特别是当你本机是 Windows，而发布目标是 Linux 时，需要额外指定恢复包。举例来说，下面这条命令明确指定了目标平台为 linux-x64：

dotnet publish -c Release -r linux-x64 --self-contained -p:PublishAot=true

如果你的应用涉及文化相关功能（比如日期格式化、数字格式），强烈建议在代码中显式设置CultureInfo.InvariantCulture作为兜底策略。这能避免你在 Linux 上调试时发现的日期格式和 Windows 不一致的困惑。

6. 常见问题与性能实测

6.1 冷启动速度实测

我为这次实测做了个简单计时，从进程启动到 HTTP 端口开始监听，耗时在 40 到 60 毫秒之间。对比我此前部署过一个 Python FastAPI 版的类似 Agent 服务，启动加加载模型客户端的时间大概要 1.5 到 2 秒。单看这个数据你可能觉得差距不算可怕，但如果你的编排系统需要频繁重启 Agent 实例，或者你有多个 Agent 服务并行启动，时间差就会放大成运维成本差距了。

6.2 内存占用实测记录

在低配机器上，我跑了以下测试：

• 空闲状态（无请求）：物理内存约 35MB。
• 并发 10 个会话同时保持长上下文：总内存约 58MB，基本平稳。
• 连续进行 20 轮模型调用（中间包含若干工具调用）：内存峰值约 76MB，GC 回收后回落到 65MB 上下。

这个数据说明了 .NET 的 GC 在这种中低频调用场景下的表现是很稳的。你不需要像 C/C++ 那样手动管理内存，也不会像 Python 那样因为全局解释器锁和对象碎片化产生莫名的内存膨胀。对于自托管 Agent 来说，这个内存模型非常理想。

6.3 多模型切换配置示例

我实际验证了一个多模型场景：配置了两个模型，一个负责日常聊天，一个负责需要高推理能力的任务。两者都通过 OpenAI 兼容协议接入，改一行配置就能切换：

{ "Models": [ { "Name": "fast_model", "Provider": "OpenAICompatible", "Endpoint": "http://127.0.0.1:11434/v1", "Model": "qwen2.5:7b", "MaxTokens": 4096 }, { "Name": "reasoning_model", "Provider": "OpenAICompatible", "Endpoint": "http://127.0.0.1:11434/v1", "Model": "qwen2.5:14b", "MaxTokens": 8192 } ] }

请求时只需要在 API 参数中指定model_name，例如：

curl -X POST http://localhost:8080/api/chat \ -H "Content-Type: application/json" \ -d '{"session_id": "test-2", "model_name": "reasoning_model", "message": "比较一下两个方案的优劣"}'

这种设计的好处尤其在本地有多套模型的场景下非常明显：你可以在同一套 Agent 平台上按需选择模型，比如简单任务走 7B 小模型节省资源，复杂任务切换到 14B 大模型保证质量。

6.4 常见问题速查表

我把部署过程中比较容易遇到的现象整理成一张速查表，供你排查时参考：

7. 经验心得与扩展思考

7.1 我在选择“自托管 Agent”时最看重的五个点

这几轮折腾下来，我对“自托管 Agent 平台”的判断标准有了更具体的想法。可以归结成五点，分享出来供你参考：

• 资源可预期：平台本身的内存、CPU、启动时间是否符合低配环境的要求，这决定它能否安稳跑在你的私有设备上。
• 模型友好：是否能够方便对接本地推理引擎（如 Ollama、LocalAI 等），能否无缝地在不同模型之间切换。
• 工具可扩展：添加一个新工具是否足够简单直接，是否会干扰现有流程。
• 数据可控制：所有会话记录、工具调用日志是否储存在本地，是否默认关闭第三方遥测。
• 部署可回滚：更新新版本时，是否方便保留旧版本的二进制，快速回退。

OpenClaw.NET 在以上五个维度上，整体表现都属于第一梯队。尤其“部署可回滚”这一点，由于 NativeAOT 产出的是单文件，我有多个版本并存几乎不占空间，切换版本就是改个符号链接的事，比起 Python 环境的依赖管理要省心太多。

7.2 关于“多模型”架构的几点忠告

多模型接入听起来很酷，但做得不好容易变成“多模型泥潭”。几个实际建议：

• 不同模型的系统提示词格式差异很大，适配层需要能够针对不同模型定制 Prompt 模板，不能一刀切。
• 如果两个模型的上下文窗口大小差异很大，会话历史管理策略也要跟着调整，否则有的模型窗口大，有的窗口小，统一策略会让小窗口模型直接失效。
• 模型切换时要保留对切换原因的可观测性日志，至少记录下是谁下令切换的、切换到什么模型、切换后效果如何。否则到时候出了问题，你连复现的线索都没有。
• 不要把多模型做成“把所有模型都调一遍再选最好的”，那样成本极高，响应还慢。更合理的做法是根据任务类型和维护者预设的路由规则来决策。

7.3 还可以在这个平台上叠加什么

如果你已经部署好了 OpenClaw.NET，后续可以往哪些方向扩展？我梳理了几条相对靠谱的路径：

• 企业内部知识库问答：挂一个检索工具进来。你只需要实现一个“查询向量库或数据库并返回 Top-K 条参考”的工具，Agent 就能在回答时引用本地资料。这个场景对数据隐私要求极高，恰恰适合自托管部署。
• 定时任务与自动化运营：可以把 Agent 包装成后台定时任务，例如每天早上自动汇总待办事项、生成日报，然后推送到即时通讯工具。只要能用工具调用来完成“发消息”和“读数据”，Agent 就能变成一个非常灵活的调度中枢。
• 多 Agent 协同：在 OpenClaw.NET 之上，可以设计一个“管理 Agent”和若干“子 Agent”的架构。管理 Agent 负责拆解任务，子 Agent 分别负责不同的领域。由于底层模型可切换，你可以让子 Agent 用更便宜的模型，管理 Agent 用更强的模型，实现效果和成本的平衡。

7.4 个人总结和一些额外的经验

我在实际部署和使用 OpenClaw.NET 的过程中，最有价值的一个体会是：把 Agent 平台做成 NativeAOT 单文件，不是炫技，而是在认真解决一个被大多数人忽视的成本问题——部署成本、维护成本和长期运行的成本。Agent 应用要想从小玩具变成真工具，首先得它能“低调地活着”，在角落的服务器里稳定跑上几个月不崩溃、不冒内存、不拖慢其他服务。OpenClaw.NET 正是靠着 .NET 和 NativeAOT 这套组合，让 Agent 平台真正具备了“低调活着”的资格。

最后分享一个我踩过几次坑之后总结的小技巧：发布完 NativeAOT 产物后，先不要急着接入正式模型，先用一个通用模型跑通完整链路，也就是聊天、工具调用、会话持久化这三件事都验证成功，再切换到真实场景的模型。因为不同模型对工具调用的格式要求差异很大，你很难判断问题出在模型还是框架上。先用一个公认工具调用最稳的标准模型做基线测试，定位问题的范围会快很多。

如果你也打算在自己的小服务器上部署一套 Agent 平台，我非常建议你试试 OpenClaw.NET，并把你的工具注册思路、模型切换方案分享出来。这个领域还很年轻，多一个人踩平一个坑，后面来的人就能少踩一个。