写给 Python 工程师的 OpenClaw.NET 上手指南：用你熟悉的 Python 思维，跑起一个生产级 AI Agent - 张善友
内容提要
OpenClaw.NET 是一个用 .NET 编写的开源 AI Agent 运行时，内置鉴权、记忆、多渠道接入等功能，可编译为无依赖的单文件二进制。文章面向 Python 工程师，用 Python 概念类比解释其架构、异步模型、工具/技能/插件开发及部署方式，强调其生产级特性，并指出当前版本仅支持 MAF 运行时。
延伸解读
Python 工程师的思维迁移要点
文章用大量 Python 类比帮助 .NET 新手快速上手，但需注意：C# 的 async/await 虽与 asyncio 相似，却采用显式 CancellationToken 传递取消信号，而非 Python 的 task.cancel()。此外，C# 的接口是显式声明，不同于 Python 的鸭子类型，扩展系统时必须实现对应接口。理解这些差异，能避免将 Python 习惯直接套用到 .NET 代码中。
NativeAOT 裁剪带来的约束
项目启用 NativeAOT 和激进裁剪（TrimMode=link），意味着运行时无法使用反射和动态加载，类似 Python 中禁止 importlib 和 getattr。这直接影响 JSON 序列化，必须使用源生成器（JsonSerializerContext）而非反射。新增 DTO 时需挂载到对应上下文，否则可能被裁剪掉。这种约束换来了无依赖单文件二进制和毫秒级冷启动，但开发时需时刻留意。
当前版本仅支持 MAF 运行时
文章明确指出，README 虽提到默认 native 编排器可选，但当前开源版本实际只支持 MAF（Microsoft Agent Framework）运行时，native 已不在仓库中。若配置选错 orchestrator，启动会直接抛异常。因此，阅读文档或示例时，应以 MAF + jit 为唯一运行时理解，避免因文档与代码不一致而产生困惑。
工具、技能与插件的区别
文章清晰区分了三者：工具是实现 ITool 接口的代码，技能是包含 SKILL.md 的文件夹，提供操作手册，插件则是动态扩展包。技能通过渐进式披露节省 token，插件支持 .NET 动态加载或 Node.js 子进程。理解这些层次，有助于按需选择扩展方式：简单功能写工具，复杂流程用技能，跨语言或隔离需求则用插件。
Q&A
OpenClaw.NET 是什么？它和 Python 的 Agent 框架有什么不同？
OpenClaw.NET 是一个用 .NET 编写的开源 AI Agent 运行时，内置鉴权、记忆、多渠道接入等功能，可编译为无依赖的单文件二进制。与 Python 框架相比，它更强调生产级特性，如内置鉴权、策略、记忆、可观测性，且部署时无需解释器和依赖，启动即原生码。
OpenClaw.NET 的异步模型和 Python 的 asyncio 有什么对应关系？
OpenClaw.NET 的异步模型与 Python 的 asyncio 非常相似：async/await 对应 C# 的 async/await，asyncio.Queue 对应 System.Threading.Channels，asyncio.Task.cancel() 对应 CancellationToken。但 C# 中取消令牌需要显式传递，而 Python 中是从外部取消任务。
如何用 OpenClaw.NET 创建一个自定义工具？
创建一个实现 ITool 接口的类，实现 Name、Description、ParameterSchema 和 ExecuteAsync 方法。例如，一个反转字符串的工具：定义 Name 为 "reverse_text"，Description 描述功能，ParameterSchema 为 JSON Schema，ExecuteAsync 中解析参数并返回结果。然后将该工具添加到内置工具列表（如 CreateBuiltInTools）中，重启网关即可。
OpenClaw.NET 中的技能（Skill）是什么？如何创建？
技能不是代码，而是一份给 Agent 的操作手册，类似于精心设计的 system prompt 和 Runbook。创建技能只需一个文件夹和一个 SKILL.md 文件，零编译。SKILL.md 包含 frontmatter（name、description）和步骤说明。重启或开启热加载后即可生效。
OpenClaw.NET 支持哪些插件开发方式？
支持两种：原生 .NET 动态插件（进程内 DLL 加载，仅 jit 车道）和 JS/TS 桥接插件（Node.js 子进程 + JSON-RPC，两条车道都行）。原生插件通过实现 INativeDynamicPlugin 接口注册工具、渠道等；JS/TS 插件则通过子进程通信，隔离性更好。
如何将 OpenClaw.NET 接入一个新的消息渠道（如 IM）？
需要实现 IChannelAdapter 接口（收+发），并创建 webhook handler 处理入站消息。步骤包括：配置类、适配器、webhook handler、DI 注册、挂适配器、映射端点。handler 中需进行签名校验、白名单校验等安全措施，然后入队消息。可参考 Twilio SMS 的实现。
OpenClaw.NET 的配置体系是怎样的？如何设置环境变量？
配置体系类似 Python 的 pydantic-settings，支持配置文件加环境变量覆盖。环境变量使用双下划线映射层级，例如 OpenClaw__Runtime__Mode 对应配置树 OpenClaw:Runtime:Mode。敏感字段支持 env:VAR_NAME 引用写法，生产环境推荐。
OpenClaw.NET 的测试栈是什么？如何运行测试？
测试栈是 xUnit v3 + NSubstitute（类似 pytest + unittest.mock）。运行全部测试使用 dotnet test，运行单个测试类使用 dotnet test --filter "FullyQualifiedName~ProcessToolTests"。
