写给 Java 工程师的 OpenClaw.NET 上手指南：用你熟悉的 Spring 思维，跑起一个生产级 AI Agent - 张善友
内容提要
OpenClaw.NET 是一个用 .NET 编写的自托管 AI Agent 运行时，可编译为单文件原生二进制，支持鉴权、记忆和多渠道接入。文章面向 Java 工程师，通过类比 Spring Boot 解释其架构、消息流转和扩展点，并指导本地运行、创建工具、技能和插件，强调 NativeAOT 裁剪下的禁反射约束。
延伸解读
Java 工程师的迁移捷径：接口 + DI 的心智模型
OpenClaw.NET 的核心架构与 Spring Boot 高度相似：通过接口定义扩展点（如 ITool、IChannelAdapter），再依赖注入（DI）注册实现，启动时组装。这种设计让 Java 工程师能快速上手，只需理解 .NET 的 DI 容器和接口约定，即可类比 Spring 的 @Service、@Autowired 等概念。
NativeAOT 裁剪：最大的隐性约束
项目编译为 NativeAOT 单文件二进制并启用激进裁剪（TrimMode=link），这意味着禁止反射。Java 工程师需注意：不能使用 Class.forName() 等动态加载，JSON 序列化需通过 JsonSerializerContext 编译期生成，而非运行时反射。新增 DTO 时务必挂载到对应的 JsonSerializerContext，否则可能被裁剪导致运行错误。
工具与技能：代码 vs 手册的清晰分工
工具（ITool）是可执行的代码，类似 Spring 的 @Service；技能（SKILL.md）则是给 Agent 的操作手册，指导如何组合工具完成任务。技能采用渐进式披露：系统提示只放索引，按需加载正文，节省 token。创建技能只需文件夹和 Markdown 文件，无需编译，适合快速调整 Agent 行为。
渠道接入的安全基线
每个渠道适配器都应实现安全措施：签名校验（恒定时间比较）、发送者白名单、消息体积上限、去重窗口。这些是生产级部署的基本要求，尤其在多渠道接入时，防止伪造请求和滥用。参考 Twilio SMS 实现可快速上手，但务必补齐安全面。
Q&A
OpenClaw.NET 是什么？它和 Java 的 Spring Boot 有什么相似之处？
OpenClaw.NET 是一个用 .NET 编写的自托管 AI Agent 运行时和网关，可以编译成 NativeAOT 单文件二进制部署，自带鉴权、记忆、可观测性和多渠道接入。它类似于 Spring Boot 应用：对外是网关（HTTP/WebSocket/IM webhook），对内运行着能调用工具、读写记忆、跨渠道对话的 AI Agent。
如何快速在本地运行 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 中如何创建一个自定义工具？
创建一个实现 ITool 接口的类，包含 Name、Description、ParameterSchema 属性和 ExecuteAsync 方法。例如，ReverseTextTool 实现字符串反转。然后将该工具添加到内置工具列表（CreateBuiltInTools）中，重启网关即可。
OpenClaw.NET 中的技能（Skill）是什么？如何创建？
技能不是代码，而是一份给 Agent 的操作手册（Runbook），教它如何组合使用已有工具。创建只需一个文件夹加一个 SKILL.md 文件，包含 YAML 头（name、description）和步骤说明。无需编译，重启或热加载即生效。
OpenClaw.NET 支持哪些插件机制？它们有什么区别？
支持两种插件：原生 .NET 动态插件（进程内 DLL 加载，仅 jit 车道）和 JS/TS 桥接插件（Node.js 子进程 + JSON-RPC，两条车道都行）。原生插件实现 INativeDynamicPlugin 接口，JS/TS 插件通过桥接方式运行。
NativeAOT 裁剪对开发 OpenClaw.NET 有什么影响？如何避免反射问题？
NativeAOT 裁剪（TrimMode=link）禁用了运行时反射，因此不能使用 Class.forName() 等反射 API。需要使用编译期生成的 JsonSerializerContext 进行 JSON 序列化，并避免动态加载类型。新增 DTO 时，要将其挂到某个 JsonSerializerContext 上。
OpenClaw.NET 的消息流转过程是怎样的？
一条用户消息从进入到回复共 11 步，涉及 IChannelAdapter、MessagePipeline、System.Threading.Channels、SemaphoreSlim、MafAgentRuntime.RunAsync、IMemoryStore 等组件。消息通过渠道适配器进入管道，经过处理，由 Agent 运行时调用 LLM 和工具，最后按 ChannelId 路由投递回复。
OpenClaw.NET 的测试栈是什么？如何运行测试？
测试栈是 xUnit v3 + NSubstitute。运行全部测试使用 `dotnet test`，运行单个测试类使用 `dotnet test --filter "FullyQualifiedName~ProcessToolTests"`。
