写给 TypeScript 工程师的 OpenClaw.NET 上手指南：用你熟悉的 TS 思维，跑起一个生产级 AI Agent - 张善友
内容提要
OpenClaw.NET是一个开源的.NET AI Agent运行时，内核用C#编写，支持NativeAOT编译为单文件二进制，扩展层内置Node.js插件桥，允许TypeScript开发者用TS写插件。系统包含工具、技能、插件和渠道适配器，提供HTTP/WebSocket接口，配置简单，适合生产部署。
延伸解读
TS 工程师的迁移门槛：具名类型与 AOT 约束
文章指出，TS 与 C# 语法相似，但类型系统有本质差异：TS 是结构化类型，C# 是具名类型，需要显式声明接口实现。此外，NativeAOT 裁剪要求序列化必须使用编译期生成的 JsonSerializerContext，禁止运行时反射。理解这两点，能避免在编写插件或扩展时踩坑。
插件桥：生产环境下的 TS 扩展路径
OpenClaw.NET 提供 Node.js 插件桥，允许 TS 插件在独立进程中运行，类似 VS Code 的扩展宿主模型。文章强调，在 AOT 生产模式下，TS 桥接插件是运行自定义逻辑的唯一推荐路径，而原生 .NET 插件仅支持 JIT 模式。这为 TS 工程师提供了在不深入 C# 的情况下扩展系统的可行方案。
技能与工具：从代码到提示词的扩展层次
文章区分了工具和技能：工具是代码实现的 ITool 接口，技能则是基于 SKILL.md 的提示词手册，通过渐进式披露节省 token。这种设计让非代码扩展（如调整 Agent 行为）无需编译，只需修改 Markdown 文件，降低了定制门槛，适合快速迭代。
Q&A
OpenClaw.NET 是什么？它和 TypeScript 工程师有什么关系？
OpenClaw.NET 是一个开源的 .NET AI Agent 运行时，内核用 C# 编写，支持 NativeAOT 编译为单文件二进制。它内置 Node.js 插件桥，允许 TypeScript 开发者用 TS 编写插件，复用上游 OpenClaw 的 TS/JS 插件生态。
OpenClaw.NET 如何实现 TypeScript 插件支持？
OpenClaw.NET 通过内置的 Node.js 插件桥（基于 JSON-RPC over stdio/socket）实现 TS 插件支持。插件运行在独立的 Node.js 子进程中，与 .NET 内核进程隔离，类似 VS Code 的扩展宿主模型。TS 插件可以调用工具、读写记忆等，且在生产环境（AOT 车道）也能运行。
如何快速在本地启动 OpenClaw.NET？
需要 .NET 10 SDK、Node.js 20+ 和 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 的操作手册，通常是一个包含 SKILL.md 的文件夹。SKILL.md 包含 frontmatter（name、description）和步骤说明。系统采用渐进式披露：先只显示技能索引，Agent 判断相关时再拉取完整内容。创建后重启或开启热加载即可生效。
OpenClaw.NET 支持哪些渠道接入？如何添加新渠道？
OpenClaw.NET 支持 HTTP、WebSocket 以及各种 IM 的 webhook。添加新渠道需要实现 IChannelAdapter 接口，并按照 6 步流程：配置类、适配器、webhook handler、DI 注册、挂适配器、映射端点。可以参考 Twilio SMS 的实现。
NativeAOT 编译对 OpenClaw.NET 开发有什么影响？
NativeAOT 编译为单文件二进制，无运行时依赖，冷启动快。但启用了激进裁剪（TrimMode=link），禁止运行时反射，因此 JSON 序列化必须使用 JsonSerializerContext 等编译期生成的方式，新增 DTO 时需要挂到 JsonSerializerContext 上。
OpenClaw.NET 的配置体系是怎样的？
配置体系类似 Node 服务的配置文件加环境变量覆盖。环境变量用双下划线映射层级，如 OpenClaw__Runtime__Mode 对应配置树 OpenClaw:Runtime:Mode。敏感字段支持 env:VAR_NAME 引用写法，适合生产环境。
