企业官网建设流程全解析

深度解析nexu架构：controller-first设计如何实现双击即用的本地运行时

【免费下载链接】nexuThe simplest desktop client for OpenClaw 🦞 — bridge your Agent to WeChat, Feishu, Slack & Discord in one click. Works with Claude Code, Codex & any LLM. BYOK, Oauth, local-first, chat from your phone 24/7.项目地址: https://gitcode.com/gh_mirrors/ne/nexu

nexu 是一个开源的 OpenClaw 桌面客户端，采用 controller-first（控制器优先）的本地运行时架构：双击启动后，由单一的 controller 进程统一管理配置、编译 OpenClaw 运行时状态，并一键桥接微信、飞书、Slack 与 Discord 等 IM 渠道。这篇文章带你读懂这套"双击即用"背后的本地运行时设计，以及它如何做到数据本地优先（local-first）、配置热更新与零命令行操作。

什么是 controller-first 架构？

传统方案要跑通一个 AI Agent 渠道集成，往往需要在多台服务之间来回同步配置。nexu 的做法更直接：让一个 controller 进程成为本地控制平面（control plane）的唯一入口，由它独占以下职责：

• 持有 Nexu 本地配置（~/.nexu/config.json）
• 把 Nexu 状态编译成 OpenClaw 运行所需的openclaw.json
• 物化 Skills（技能）与工作区模板文件
• 编排 OpenClaw 运行时进程的生命周期

整体数据链路非常简洁，来自 ARCHITECTURE.md：

Desktop Shell / Browser ↓ Web (React + Ant Design + Vite) ↓ Controller (Hono + Zod OpenAPI + lowdb-backed local store) ↓ OpenClaw Runtime → Slack / Discord / Feishu API

也就是说，前端界面只和 controller 对话，controller 只和 OpenClaw 对话，每一层都清晰单一。

配置编译：从 Nexu 状态到 OpenClaw 运行时的单向管道

controller-first 的核心是单向配置流。用户在界面上的每个操作（连接飞书、切换模型、安装技能）都只写进 controller 的本地存储，由编译器统一转换成 OpenClaw 能直接消费的配置。这个"编译器"位于 apps/controller/src/lib/openclaw-config-compiler.ts，它负责：

• 把渠道凭据编译成channels.{slack|feishu}.accounts结构
• 生成bindings路由规则，把某个渠道账号的消息绑定到对应 Agent
• 解析模型供应商（BYOK Key 或 OAuth 授权）并写入模型配置
• 校验编译结果满足 OpenClaw 的硬性约束（如bindings[].agentId必须匹配agents.list[].id）

这种"单一事实来源 + 编译"模式带来一个直接好处：OpenClaw 的状态目录里的文件永远是 Nexu 的投影，而不是需要手工维护的第二份配置。你永远不会遇到"两边配置不一致"的经典困境。

类型安全同样贯穿全链路：Zod schema 定义一次，自动派生出 API 校验、OpenAPI 规范（apps/controller/openapi.json）和前端生成的 SDK 类型，完整链条记录在 specs/design-docs/core-beliefs.md：

Zod Schema (define once) → API route validation (@hono/zod-openapi) → OpenAPI spec (auto-generated) → Frontend SDK types (@hey-api/openapi-ts) → local store/runtime types

共享 schema 定义在 packages/shared/src/schemas/ 中，覆盖渠道、网关、模型、技能等所有领域模型。

双击启动：本地运行时的完整冷启动序列

"双击即用"听起来简单，但背后是一条精心编排的启动流水线，完整记录在 specs/guides/desktop-startup-flow.md。它分为六个阶段：

阶段一：端口分配与引导。Electron 主进程探测端口，若被占用则自动偏移，controller（50800）、web（50810）、OpenClaw 网关（18789）三个端口各自独立分配，并持久化到runtime-ports.json供下次恢复。

阶段二：统一引导（attach 或冷启动）。桌面壳通过 apps/desktop/main/services/launchd-bootstrap.ts 对每个服务做三态决策：

这意味着如果你上次选择"在后台运行"，再次打开窗口时几乎瞬间完成附着，而非重新冷启动。

阶段三：controller 就绪。核心逻辑在 apps/controller/src/app/bootstrap.ts 的bootstrapController()中。它先并行执行三个独立准备工作——进程清理、运行时模型插件落盘、云端模型拉取——然后按序完成：

ensureValidDefaultModel() # 校验默认模型可用 syncAllImmediate() # 写入 openclaw.json + 技能 wsClient.connect() # 连接 OpenClaw 网关 WebSocket startBackgroundLoops() # 启动健康检查 + 同步循环 bootPhase: "booting" → "ready"

值得注意的是区分托管模式与外部模式：托管模式下 controller 先播种配置再启动 OpenClaw（syncAllImmediate()→openclawProcess.start()）；外部模式则先附着已有网关再对账（wsClient.connect()→syncAllImmediate()校准配置）。两种路径最终都收敛到bootPhase = "ready"。

阶段四：UI 渲染。桌面壳轮询desktop/ready接口，controller 就绪后才把 webview 指向本地 web 服务，用户看到的就是一个已经完全可用的界面。

热更新：配置修改如何零重启生效

用户在界面上修改任何配置后，数据流是：

前端调用 controller 路由 → controller 校验并写入本地存储 → 重新编译 OpenClaw 配置 → runtime writers 物化更新后的状态 → OpenClaw 的 Config Watcher 感知文件变更 → 运行时热加载，无需重启

后台还有一个持续的兜底机制：apps/controller/src/runtime/loops.ts 中的健康循环周期性探测 OpenClaw 网关并在 WebSocket 断线时触发重连；同步循环则保证 Nexu 期望状态与 OpenClaw 实际状态最终一致。OpenClaw 侧的 Agent 隔离与热加载机制细节，可以在 specs/designs/openclaw-architecture-internals.md 中阅读完整分析。

技能系统：文件即技能，扫描即安装

nexu 的技能（Skills）同样是文件化的：公共技能仓库位于 nexu-skills/skills/，每个技能是一个带SKILL.mdfrontmatter 的目录，nexu-skills/skills.json 作为构建出的目录索引。controller 负责扫描目录、提供安装/卸载流程，并把受管技能目录物化到 OpenClaw 运行时，运行时监视器在技能文件变化时自动热加载——整个安装链路不需要任何手工拷贝文件。

为什么这套架构对新手友好

回顾 controller-first 设计，它把复杂性的收敛点做得非常干净：

1. 一个进程管一切—— controller 独占配置所有权，消除了多服务间状态漂移
2. 单向数据流—— 界面状态 → 编译 → 运行时文件，方向唯一，可预测
3. 附着优先的启动策略—— 二次打开 200ms 级恢复，首次冷启动也有明确的阶段化超时控制（初始 30s、稳定窗口 4s）
4. schema 即契约—— Zod 单源真相让校验、文档、SDK 类型永不脱节

对普通用户来说，这些架构决策最终只呈现为一件事：下载安装，双击打开，扫码连接微信或飞书，你的 AI Agent 就 7×24 小时在线了。而这份体验正是上述每一层设计共同兑现的承诺。

想深入了解设计细节，推荐按以下顺序阅读：ARCHITECTURE.md 看全局 → specs/guides/desktop-startup-flow.md 看启动时序 → specs/references/openclaw-config-schema.md 看配置约束 → specs/designs/openclaw-multi-tenant.md 看多租户演进方向。

【免费下载链接】nexuThe simplest desktop client for OpenClaw 🦞 — bridge your Agent to WeChat, Feishu, Slack & Discord in one click. Works with Claude Code, Codex & any LLM. BYOK, Oauth, local-first, chat from your phone 24/7.项目地址: https://gitcode.com/gh_mirrors/ne/nexu