写给 Golang 工程师的 OpenClaw.NET 上手指南：用你熟悉的 Go 思维，跑起一个生产级 AI Agent - 张善友
内容提要
OpenClaw.NET 是一个用 .NET 编写的自托管 AI Agent 运行时，支持 NativeAOT 编译为单文件原生二进制，类似 Go 的构建产物。它提供鉴权、记忆、多渠道接入等功能，并支持工具、技能和插件扩展。文章以 Go 概念类比，介绍系统架构、消息流转、配置和开发流程，帮助 Go 工程师快速上手。
延伸解读
NativeAOT 的代价：反射受限
文章强调 NativeAOT 编译产物类似 Go 的单文件二进制，但代价是启用激进裁剪（TrimMode=link），导致运行时反射受限。所有 JSON 序列化必须通过 JsonSerializerContext 代码生成，类似 Go 中强制使用 easyjson 而非标准库反射。新增 DTO 时需挂载到对应 Context，否则可能运行时报错。
运行时车道：AOT 与 JIT 的差异
文章指出系统存在 AOT 和 JIT 两条运行时车道，当前开源版本实际只支持 MAF 编排器且需 JIT 运行。若选择 native 编排器会启动异常。理解这一点对配置和部署至关重要，避免因文档与代码不一致而踩坑。
扩展机制：工具、技能与插件
工具是显式实现 ITool 接口的类，类似 Go 中定义接口并实现；技能是 SKILL.md 文件，类似 Runbook，通过渐进式披露节省 token；插件支持原生 DLL 和 JS/TS 桥接，类似 Go 的 plugin 与 go-plugin 的取舍。扩展时需注意接口显式声明和 DI 注册。
安全与测试实践
文章强调渠道接入需实现签名校验（恒定时间比较）、白名单、体积限制和去重窗口，类似 Go 的 hmac.Equal。测试使用 xUnit 和 NSubstitute，对应 go test 和 testify。项目开启 TreatWarningsAsErrors，类似 go vet 严格检查，代码需注意可空性处理。
Q&A
OpenClaw.NET 是什么？它和 Go 有什么关系？
OpenClaw.NET 是一个用 .NET 编写的自托管 AI Agent 运行时和网关，支持 NativeAOT 编译为无依赖的单文件原生二进制，类似于 Go 的构建产物。它提供鉴权、记忆、多渠道接入等功能，并支持工具、技能和插件扩展。文章以 Go 概念类比，帮助 Go 工程师快速上手。
OpenClaw.NET 的代码仓库在哪里？解决方案和命名空间是什么？
OpenClaw.NET 的代码仓库在 https://github.com/clawdotnet/openclaw.net。解决方案文件是 OpenClaw.Net.slnx，命名空间是 OpenClaw.*。
OpenClaw.NET 如何实现类似 Go 的单文件原生二进制？
OpenClaw.NET 使用 .NET 的 NativeAOT 编译技术，可以生成无依赖的单文件原生二进制，启动即原生码、无 JIT、无运行时安装，与 Go 的 CGO_ENABLED=0 go build 产物体验一致。
OpenClaw.NET 中如何创建一个工具（Tool）？
创建一个工具需要实现 ITool 接口，包括 Name、Description、ParameterSchema 和 ExecuteAsync 方法。例如，可以创建一个字符串反转工具，然后在 CreateBuiltInTools 中注册它。
OpenClaw.NET 中的技能（Skill）是什么？如何创建？
技能不是代码，而是一份给 Agent 的操作手册，教它如何组合调用已有工具。创建技能只需一个文件夹和一个 SKILL.md 文件，包含名称、描述和步骤，零编译，重启或热加载即可生效。
OpenClaw.NET 支持哪些插件类型？它们与 Go 的插件机制有何相似？
OpenClaw.NET 支持两种插件：原生 .NET 动态插件（进程内 DLL 加载，仅 jit 车道）和 JS/TS 桥接插件（Node.js 子进程 + JSON-RPC，两条车道都行）。这与 Go 的 plugin 包和 HashiCorp go-plugin 的取舍类似。
如何快速在本地启动 OpenClaw.NET？
设置三个环境变量（MODEL_PROVIDER_KEY、OPENCLAW_WORKSPACE）并运行 dotnet run --project src/OpenClaw.Gateway -c Release 即可。默认监听 http://127.0.0.1:18789，浏览器打开 /chat 即可对话。
OpenClaw.NET 的配置体系是怎样的？
配置体系类似 Go 服务的配置文件加环境变量覆盖。环境变量用双下划线映射层级，如 OpenClaw__Runtime__Mode 对应配置树 OpenClaw:Runtime:Mode。敏感字段支持 env:VAR_NAME 引用写法。
OpenClaw.NET 中消息流转的 11 步是什么？
文章提到一条用户消息从进来到回复共 11 步，但未详细列出每一步。核心组件包括 IChannelAdapter、MessagePipeline、SemaphoreSlim、MafAgentRuntime.RunAsync、IMemoryStore 和 ChannelId。
OpenClaw.NET 的测试栈是什么？如何运行测试？
测试栈是 xUnit v3 和 NSubstitute，类似于 Go 的 go test 和 testify/mock。运行全部测试使用 dotnet test，运行单个测试类使用 dotnet test --filter "FullyQualifiedName~ProcessToolTests"。
