写给 PHP 工程师的 OpenClaw.NET 上手指南：用你熟悉的 PHP 思维，跑起一个生产级 AI Agent - 张善友
内容提要
OpenClaw.NET 是一个用 .NET 编写的自托管 AI Agent 运行时，支持长驻内存模型，集成鉴权、记忆、多渠道接入等功能，可编译为无依赖的单文件二进制。文章面向 PHP 工程师，类比 Laravel 概念，介绍其架构、工具/技能/插件开发及部署方式，强调从请求级到常驻 daemon 的思维转变。
延伸解读
从请求级到常驻 daemon 的思维转变
PHP-FPM 的 shared-nothing 模型下，请求结束即销毁，状态依赖外置存储。而 OpenClaw.NET 是长驻内存的 daemon，进程启动后持续运行，内存状态需要谨慎管理。如果你用过 Swoole、RoadRunner 或 Laravel Octane，对这种模型已有体会。编译型语言避免了 PHP 长驻时的扩展内存坑，但你需要适应状态持久化和资源释放的新要求。
AOT 裁剪对开发方式的约束
为了编译成无依赖的单文件原生二进制，OpenClaw.NET 启用了激进裁剪（TrimMode=link），禁止运行时反射。这意味着 PHP 中常见的动态实例化（如 new $className()）和 call_user_func 不可用。JSON 序列化需依赖源生成器，为每个 DTO 声明 JsonSerializerContext。新增 DTO 时务必挂载到对应的 Context，否则可能被裁剪掉。
工具、技能与插件的扩展方式
扩展 OpenClaw.NET 有三种主要方式：工具（ITool）是代码实现，类似 PHP 中 implements 接口；技能是 SKILL.md 文件，零编译，通过渐进式披露节省 token；插件支持原生 DLL 和 JS/TS 桥接，生产环境（AOT）下推荐使用 TS 插件。理解这些抽象接口（ITool、IChannelAdapter 等）是掌握系统扩展点的关键。
部署与配置的简化
OpenClaw.NET 内建 Kestrel 服务器，无需 nginx 和 php-fpm，部署简化为拷贝单文件并运行。配置采用分层文件加环境变量覆盖，敏感字段支持 env: 引用。本地启动只需设置三个环境变量并执行 dotnet run。相比传统 PHP 部署，省去了 composer install、opcache 预热等步骤，但需注意 AOT 编译的约束。
Q&A
OpenClaw.NET 是什么？它和 PHP 的 Laravel 有什么类比？
OpenClaw.NET 是一个用 .NET 编写的自托管 AI Agent 运行时和网关，集成了鉴权、策略、记忆、可观测性、多渠道接入等功能，并支持编译为无依赖的单文件原生二进制。用 PHP 的话说，它像一个“Laravel 应用 + 常驻队列 worker 的合体”，对外提供 HTTP/WebSocket/IM webhook，对内运行能调工具、读写记忆、跨渠道对话的 AI Agent，但它是长驻内存的 daemon，而不是请求级的。
PHP 工程师在理解 OpenClaw.NET 时，最大的思维转变是什么？
最大的思维转变是从“请求级、shared-nothing、改完即生效”到“长驻 daemon、内存状态、编译部署”。PHP-FPM 每个请求结束一切销毁，而 OpenClaw.NET 是长驻进程，运行几个月，需要管理内存状态。另外，类型纪律更严格：警告即错误，可空性编译期强制，但换来的是编译通过基本能跑和单文件二进制部署。
如何快速在本地启动 OpenClaw.NET？
需要 .NET 10 SDK、可选的 Node.js 20+（仅 TS/JS 插件）和一个 LLM API Key。先运行 `dotnet run --project src/OpenClaw.Gateway -c Release -- --doctor` 校验配置，然后设置环境变量 `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 方法。例如，一个反转字符串的工具类 ReverseTextTool，实现 ITool，在 ExecuteAsync 中解析 JSON 参数并返回结果。然后将该工具添加到内置工具列表（如 CreateBuiltInTools 方法）中，重启网关即可生效。
OpenClaw.NET 中的技能（Skill）是什么？如何创建？
技能不是代码，而是一份给 Agent 的操作手册，教它如何组合调用已有工具。创建只需一个文件夹加一个 SKILL.md 文件，零编译、零部署。SKILL.md 包含 front matter（name、description）和步骤说明。机制是渐进式披露：系统提示只放技能索引，Agent 判断相关时拉取完整正文。重启或开启热加载即生效。
OpenClaw.NET 支持哪些插件开发方式？生产环境推荐哪种？
支持两种：原生 .NET 动态插件（进程内 DLL 加载，仅 jit 车道）和 JS/TS 桥接插件（Node.js 子进程 + JSON-RPC，两条车道都行）。生产环境（aot 车道）要跑自定义逻辑，推荐使用 TS 桥接插件，因为它隔离且语言自由。
OpenClaw.NET 的配置体系是怎样的？如何用环境变量覆盖配置？
配置体系是“配置文件 + 环境变量覆盖”的分层套路，类似 Laravel 的 config/*.php + .env。环境变量用双下划线映射层级，例如 `OpenClaw__Runtime__Mode` 对应配置树 `OpenClaw:Runtime:Mode`。敏感字段支持 `env:VAR_NAME` 引用写法，生产环境推荐。
OpenClaw.NET 如何处理多渠道接入？以 Twilio SMS 为例，步骤是什么？
多渠道接入通过实现 IChannelAdapter 接口（收+发），入站走 webhook → handler 校验解析 → 管道入队，出站按 ChannelId 路由投递。以 Twilio SMS 为例，步骤为：配置类 → 适配器 → webhook handler → DI 注册 → 挂适配器 → 映射端点。webhook handler 需处理签名校验、白名单等安全面。
