写给 C++ 工程师的 OpenClaw.NET 上手指南：用你熟悉的 C++ 思维，跑起一个生产级 AI Agent - 张善友
内容提要
OpenClaw.NET 是开源的 .NET AI Agent 运行时与网关，内置鉴权、记忆和多渠道接入，支持 NativeAOT 编译为无依赖单文件原生二进制。文章面向 C++ 开发者，通过类比 C# 概念讲解系统组成与消息流转，并演示如何编写工具、技能、插件和渠道适配器。
延伸解读
从 C++ 到 C#：概念映射与心智转换
文章用大量 C++ 类比帮助理解 C# 概念，如 async/await 对应协程、CancellationToken 对应 std::stop_token、string? 对应 std::optional。但需注意关键差异：C# 是 GC 语言，内存回收不确定，RAII 的确定性析构不适用于内存，但非内存资源通过 using 实现确定性释放。这种心智转换是 C++ 工程师上手时最需要重建的习惯。
NativeAOT 与裁剪：编译期优化的双刃剑
OpenClaw.NET 支持 NativeAOT 编译为无依赖单文件原生二进制，并开启激进裁剪（TrimMode=link）。这要求 JSON 序列化使用源生成器，为类型声明 JsonSerializerContext，否则裁剪器可能删除看似未引用的代码。这体现了编译期生成与运行期内省的权衡，C++ 工程师对此应感熟悉，但需注意新增 DTO 时必须挂到 JsonSerializerContext 上。
扩展机制：工具、技能、插件与渠道的取舍
系统通过接口实现和 DI 注册进行扩展。工具（ITool）是代码，技能（SKILL.md）是操作手册，插件分原生 .NET 动态插件（仅 jit 车道）和 JS/TS 桥接插件（两条车道都行）。原生插件类似 dlopen 加载 .so，零调用开销但 ABI 和崩溃隔离是坑；桥接插件类似子进程 IPC，有成本但隔离性好。生产环境（aot 车道）建议使用 TS 桥接插件。
生产部署与安全考量
文章强调生产环境推荐使用环境变量覆盖配置，敏感字段支持 env:VAR_NAME 引用。渠道适配器需实现签名校验（恒定时间比较防时序侧信道）、发送者白名单、体积上限和去重窗口。此外，项目开启 TreatWarningsAsErrors，警告即错误，类似 -Werror，这要求代码质量严格。测试使用 xUnit v3 + NSubstitute，类似 Google Test + gmock。
Q&A
OpenClaw.NET 是什么？它和 Python/Node 的 Agent 框架有什么不同？
OpenClaw.NET 是一个用 .NET 写的自托管 AI Agent 运行时 + 网关，内置鉴权、策略、记忆、可观测性和多渠道接入。与 Python/Node 框架不同，它可以用 NativeAOT 编译成无依赖单文件原生二进制，启动即原生码，没有 JIT 预热，也不需要安装运行时。
C++ 工程师如何快速在本地把 OpenClaw.NET 跑起来？
需要 .NET 10 SDK（必须），可选 Node.js 20+（仅跑 TS/JS 插件时需要），以及一个 LLM API Key。最快启动方式：设置环境变量 MODEL_PROVIDER_KEY 和 OPENCLAW_WORKSPACE，然后运行 dotnet run --project src/OpenClaw.Gateway -c Release。默认监听 http://127.0.0.1:18789，浏览器打开 /chat 即可对话。
OpenClaw.NET 中如何编写一个自定义工具（Tool）？
实现 ITool 接口，提供 Name、Description、ParameterSchema 属性和 ExecuteAsync 方法。例如字符串反转工具：定义类实现 ITool，在 ExecuteAsync 中用 JsonDocument 解析入参（AOT 安全），返回 ValueTask<string>。然后将其加入 CreateBuiltInTools(...) 列表，重启网关即可使用。
OpenClaw.NET 的技能（Skill）是什么？如何创建？
技能不是代码，而是一份给 Agent 的操作手册，教 Agent 如何组合调用已有工具。机制是渐进式披露：系统提示只放技能索引，Agent 判断相关时拉取完整正文。创建只需一个文件夹加一个 SKILL.md 文件，零编译，重启或热加载即生效。
OpenClaw.NET 支持哪些插件类型？各自有什么优缺点？
支持两种插件：原生 .NET 动态插件（进程内 DLL 加载，仅 jit 车道）和 JS/TS 桥接插件（Node.js 子进程 + JSON-RPC，两条车道都行）。原生插件零调用开销但 ABI/生命周期/崩溃隔离有坑且仅限 jit；桥接插件有 IPC 成本但进程隔离、语言自由、崩溃不影响宿主。生产环境（aot 车道）推荐 TS 桥接插件。
C++ 工程师从 C++ 转向 OpenClaw.NET 需要适应哪些主要差异？
主要适应两点：内存管理从 RAII 换成 GC（确定性析构变为 using 显式管理非内存资源），以及模板换成带约束的泛型（编译期元编程能力减弱但编译速度更快）。同时失去部分内存控制，但换来没有 UB、没有头文件、async 不用手写状态机。
