基于WebSocket RPC的OpenClaw多智能体可视化仪表盘ZIMZ设计与部署

1. 项目概述为OpenClaw打造一个实时、清晰的多智能体仪表盘如果你和我一样在本地或者VPS上跑着OpenClaw管理着几个甚至几十个AI智能体那你肯定经历过这种场景想知道某个Agent在干什么得SSH连上去看日志想改一下Agent的“性格”或者记忆得找到对应的SOUL.md或MEMORY.md文件手动编辑想看看整体运行状态只能靠命令行里那一堆输出。这种割裂的操作体验对于追求效率的开发者来说简直是种折磨。ZIMZ就是为了解决这个问题而生的。它不是一个简单的包装壳而是一个完全通过WebSocket RPC与OpenClaw Gateway深度集成的、自托管的可视化仪表盘。简单来说它把你对OpenClaw的所有操作——查看状态、管理Agent、编辑配置文件、调度任务——都搬到了一个现代化的Web界面上并且所有数据都是实时同步的。你不再需要和命令行打交道打开浏览器一切尽在掌握。这个项目特别适合那些在VPS或家庭实验室里部署了OpenClaw希望有一个集中、清晰、可实时监控的管理界面的运维人员或AI应用开发者。无论你是管理一个用于自动化工作流的Agent集群还是运行一个复杂的多智能体协作系统ZIMZ都能提供一个比原生CLI友好得多的操作体验。2. 核心架构与设计思路拆解2.1 为什么选择WebSocket RPC而非CLI包装很多为后端服务做UI的项目其底层实现往往是包装命令行调用。例如点击“重启Agent”按钮后端实际执行的是openclaw-cli agent restart [id]。这种方式简单粗暴但问题很多输出解析复杂、错误处理困难、无法实现真正的实时性、存在安全风险需要处理shell命令和权限。ZIMZ的设计哲学从一开始就摒弃了这种“包装CLI”的思路。OpenClaw Gateway本身提供了一个完整的WebSocket RPC协议这是一个设计良好的、标准化的远程调用接口。ZIMZ选择直接与这个协议对话带来了几个根本性的优势状态实时同步通过建立一个持久的WebSocket连接Gateway可以将Agent的心跳、状态变更、聊天事件等主动推送给ZIMZ实现了毫秒级的UI更新无需任何轮询Polling。操作原子性与安全性每一个UI操作如添加Agent、更新文件都对应一个明确的RPC方法调用如agents.add,agents.files.set。调用结果成功或包含错误信息的失败会通过相同的通道返回错误处理逻辑清晰且安全。功能完整性RPC协议暴露了Gateway的所有能力包括一些CLI可能没有直接暴露的高级功能如系统状态监控、模型列表获取、复杂的定时任务调度ZIMZ可以无缝集成这些功能。前后端职责分离浏览器端前端只与ZIMZ自己的Next.js后端API通信完全不知道Gateway的存在。Next.js后端充当了一个安全的“代理”和“协议转换器”负责维护与Gateway的WebSocket连接并将前端的HTTP请求转换为RPC调用。这种架构更清晰也更容易扩展和维护。实操心得直接对接RPC协议初期工作量稍大需要仔细阅读OpenClaw的Gateway协议文档处理连接、认证、重连等细节。但一旦打通后续增加新功能如调用新的RPC方法会变得异常简单和稳定远胜于解析不断变化的CLI输出格式。2.2 技术栈选型背后的考量ZIMZ的技术栈看起来非常“现代”Next.js 16 (App Router), React 19, TypeScript 5, Tailwind CSS v4。这并非盲目追新而是基于项目实际需求做出的选择Next.js (App Router)这是整个项目的基石。App Router提供了优秀的服务端渲染SSR和服务器组件支持。对于ZIMZ初始页面app/page.tsx直接通过服务端组件调用Gateway RPC来获取Agent列表和文件内容这意味着用户打开页面时看到的就是已经填充好数据的界面无需等待客户端JavaScript加载后再去请求提升了首屏体验。同时其内置的API Routes功能完美契合了我们需要构建代理后端的需求。React 19 TypeScript 5React 19带来了诸如Actions等优化为未来更复杂的表单交互和状态管理提供了更好的基础。TypeScript则是大型前端项目尤其是涉及复杂RPC数据类型的项目的“安全带”。它能确保从Gateway接收的数据、在组件间传递的Props都符合预期格式极大减少了运行时错误。Tailwind CSS v4仪表盘UI需要快速迭代和高度的定制化特别是要营造一种“终端美学”或“赛博朋克”风格。Tailwind的实用优先Utility-First理念允许开发者直接在JSX中组合样式快速实现设计稿同时保持CSS包体积的最小化。v4版本在性能和功能上都有进一步提升。Framer Motion为了提升用户体验特别是“办公室地图”Office Map视图中Agent状态切换时的溶解过渡效果需要一个强大且易用的动画库。Framer Motion的声明式API与React配合得天衣无缝是实现复杂交互动画的理想选择。Server-Sent Events (SSE)这是一个关键设计。虽然与Gateway的通信是WebSocket但ZIMZ选择用SSE将实时事件从Next.js后端推送到浏览器前端。为什么不用WebSocket直连主要是为了架构简化。浏览器只维持一个到熟悉域ZIMZ服务器的SSE连接由Next.js后端统一管理到Gateway的WebSocket连接处理所有订阅、重连逻辑降低了前端复杂度。3. 核心功能模块深度解析3.1 智能体Agent全生命周期管理在ZIMZ中管理一个Agent就像管理一个团队成员。仪表盘提供了从“招聘”创建到“离职”删除的完整操作闭环。3.1.1 网格视图与详情气泡Agent网格视图是仪表盘的默认主页。每个Agent以一个卡片形式呈现卡片上直观展示了关键信息Agent ID、当前状态空闲、运行中、错误、绑定的AI模型、以及可能正在执行的任务摘要。点击任何一个卡片并不会跳转到新页面而是会弹出一个“详情气泡”。这个设计非常巧妙它保持了上下文不丢失用户可以快速查看、操作后再关闭流程非常顺畅。气泡内包含两个标签页信息Info这里展示Agent的实时动态。最重要的是“实时日志流”它通过SSE持续接收并显示该Agent的chat和agent事件让你能像看终端一样看到Agent的“思考过程”和输出。同时也会显示当前任务详情。设置Settings这是功能核心区。在这里你可以直接在线编辑Agent的“灵魂”文件SOUL.md和“记忆”文件MEMORY.md。编辑是实时的每当你停止输入ZIMZ会在后台通过agents.files.setRPC将更改保存回Gateway并最终写入Agent的工作区。下方还有一个“危险区域”用于删除Agent或执行其他破坏性操作。3.1.2 模型动态分配一个很实用的功能是模型分配。ZIMZ会通过models.listRPC调用从Gateway获取当前配置的所有可用AI模型如Claude-3.5-Sonnet, GPT-4o等。在Agent卡片或设置页面你可以通过一个下拉菜单随时为Agent切换模型。这个操作同样通过agents.updateRPC完成无需重启Agent即可生效取决于OpenClaw的具体实现。注意事项模型切换的即时性取决于OpenClaw Gateway和底层运行时的实现。有些系统可能需要Agent下一次执行任务时才会加载新模型而有些则支持热重载。在ZIMZ中切换后最好观察一下Agent的下一次运行日志以确认。3.2 办公室地图Office Map——状态的可视化叙事“办公室地图”视图是一个极具创意的功能。它不再以列表或网格展示Agent而是将它们放置在一个虚拟的“办公室”平面图上并根据状态分组到不同的“区域”例如“工位区”运行中、“会议室”协作中、“休息区”空闲、“维修间”错误。这个视图的价值在于提供了态势感知。你一眼就能看出整个系统的“健康度”大部分Agent在“工位区”忙碌是好事如果“维修间”挤满了Agent那就意味着系统出了大问题。Framer Motion实现的溶解过渡动画让Agent在不同状态区域间移动时非常平滑增强了监控的直观性和沉浸感。实现原理该视图的核心逻辑是根据每个Agent的status、current_task等属性通过一套规则引擎将其映射到地图上的一个坐标x, y和区域ID。前端根据这些坐标和区域进行渲染。当SSE推送来状态更新事件时触发Agent图标的动画移动。3.3 任务调度器Task Scheduler这是将自动化能力赋予普通用户的关键模块。你可以在这里创建、编辑、管理和立即运行定时任务Cron Jobs并将它们分配给特定的Agent。3.3.1 灵活的调度配置Cron表达式支持标准的Unix Cron表达式如0 */2 * * *表示每两小时满足精确的时间调度需求。间隔调度更简单的表达方式如“每30分钟”、“每天上午9点”。一次性定时器在未来的某个特定时间点运行一次任务。立即运行无需等待调度手动触发任务执行用于测试或紧急操作。3.3.2 强大的交付选项这是任务调度器的亮点。任务执行后产生的输出结果可以发送到多个目的地消息平台集成Telegram、Discord、Slack、WhatsApp等将AI生成的报告、摘要、警报直接推送到团队聊天室。Webhook发送HTTP POST请求到自定义的API端点触发下游业务流程。电子邮件发送邮件报告。 在创建任务时你可以配置交付的目标如Discord频道ID、Telegram Chat ID和格式模板。3.3.3 与Gateway的集成所有调度操作都通过cron.*系列的RPC方法cron.add,cron.update,cron.remove,cron.run与OpenClaw Gateway交互。这意味着定时任务是由Gateway服务本身持久化和执行的即使ZIMZ仪表盘重启任务也会照常运行。ZIMZ只是一个友好的管理界面。3.4 实时事件流与连接健康管理仪表盘顶部的状态栏始终显示两个关键信息与Gateway的连接状态绿色勾表示已连接红色叉表示断开和在线Agent总数。这是系统可靠性的第一道防线。3.4.1 事件流架构浏览器 → ZIMZ后端 (SSE)浏览器加载页面后会建立一条到/api/events的Server-Sent Events连接。ZIMZ后端 → OpenClaw Gateway (WebSocket)ZIMZ后端维护一个到Gateway的WebSocket连接并在连接成功后订阅全局事件如agent.*,heartbeat,chat。事件转发当Gateway推送一个事件例如agent.updated到WebSocketZIMZ后端的GatewayEventManager会捕获它并将其转发给所有活跃的SSE连接。浏览器更新UI前端通过useGatewayEventsReact Hook监听SSE流收到事件后根据事件类型如更新某个Agent的状态更新React组件的状态从而驱动UI实时刷新。3.4.2 健壮性处理WebSocket重连网络波动导致WebSocket断开时GatewayEventManager会实施指数退避策略自动重连。SSE重连浏览器端的EventSource对象在连接断开时也会自动重连。状态同步重连成功后前端会主动重新获取一次完整的Agent列表和状态以弥补断线期间可能错过的事件。4. 部署与运维实操指南4.1 本地开发环境搭建对于想贡献代码或深度定制的开发者本地搭建环境非常简单。# 1. 克隆仓库 git clone https://github.com/burnshall-ui/ZimZ cd ZimZ # 2. 安装依赖 (推荐使用pnpm以获得更快的速度) npm install # 或 pnpm install # 3. 配置环境变量 cp .env.example .env.local # 编辑 .env.local设置你的Gateway地址 # OPENCLAW_GATEWAY_URLws://127.0.0.1:18789 # 如果需要认证填写TOKEN或PASSWORD # 4. 启动开发服务器 npm run dev # 或 pnpm dev访问http://localhost:3000如果本地运行着OpenClaw Gateway默认端口18789仪表盘应该能自动连接并显示Agent。实操心得在开发时如果Gateway尚未就绪ZIMZ会使用src/data/mockData.ts中的模拟数据来渲染UI这保证了前端开发的独立性无需时刻运行着后端服务。4.2 生产环境部署Linux VPS在生产服务器上部署ZIMZ目标是使其成为一个稳定、常驻的服务。以下是基于Node.js和反向代理的经典部署方案。4.2.1 构建与进程管理首先在服务器上获取代码并构建生产版本# 在服务器上克隆代码或通过CI/CD推送 git clone https://github.com/burnshall-ui/ZimZ /opt/zimz cd /opt/zimz # 安装生产依赖跳过devDependencies npm ci --omitdev # 构建Next.js应用 npm run build # 构建完成后可以使用PM2来管理进程 npm install -g pm2 # 使用PM2启动应用并设置进程名和日志 pm2 start npm --name zimz-dashboard -- start pm2 save pm2 startup # 根据提示执行命令设置开机自启4.2.2 使用Systemd替代PM2如果你更喜欢使用系统的服务管理器可以创建一个Systemd服务文件sudo vim /etc/systemd/system/zimz.service将以下内容写入文件注意修改User,WorkingDirectory和ExecStart路径[Unit] DescriptionZIMZ Dashboard Service Afternetwork.target [Service] Typesimple Useryour_username WorkingDirectory/opt/zimz EnvironmentNODE_ENVproduction ExecStart/usr/bin/npm start Restarton-failure RestartSec10 [Install] WantedBymulti-user.target然后启用并启动服务sudo systemctl daemon-reload sudo systemctl enable zimz.service sudo systemctl start zimz.service sudo systemctl status zimz.service # 检查状态4.2.3 配置反向代理Nginx我们不直接对外暴露Node.js的3000端口而是使用Nginx或Caddy作为反向代理处理HTTPS、静态文件缓存等。安装Nginx后创建一个站点配置文件sudo vim /etc/nginx/sites-available/zimz假设你的域名是dashboard.yourdomain.comZIMZ运行在127.0.0.1:3000server { listen 80; server_name dashboard.yourdomain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name dashboard.yourdomain.com; # SSL证书路径可以使用Let‘s Encrypt免费获取 ssl_certificate /etc/letsencrypt/live/dashboard.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/dashboard.yourdomain.com/privkey.pem; # 静态资源缓存优化 location /_next/static { alias /opt/zimz/.next/static; expires 365d; add_header Cache-Control public, immutable; } location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; # 对WebSocket转发很重要 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_cache_bypass $http_upgrade; # 增加超时时间适用于长连接的SSE proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }启用配置并重启Nginxsudo ln -s /etc/nginx/sites-available/zimz /etc/nginx/sites-enabled/ sudo nginx -t # 测试配置语法 sudo systemctl reload nginx4.2.4 网络架构与安全建议最终的部署架构如下互联网用户 ──HTTPS(443)──► Nginx (反向代理) ──HTTP──► ZIMZ (:3000) ──WebSocket──► OpenClaw Gateway (:18789) (本地回环或内网)关键安全点Gateway隔离确保OpenClaw Gateway (:18789)只监听在本地回环地址(127.0.0.1或localhost)。绝对不要将其暴露在公网。所有与Gateway的通信都通过ZIMZ后端在服务器内部完成。ZIMZ认证目前ZIMZ依赖Gateway的Token/Password认证。对于多用户场景你需要在ZIMZ层面增加一层用户登录认证例如使用NextAuth.js避免任何人只要知道地址就能访问你的所有Agent。HTTPS强制使用Let‘s Encrypt等工具为你的域名配置SSL证书Nginx配置中已包含HTTP到HTTPS的重定向。防火墙配置服务器防火墙如UFW只开放80、443端口给Nginx确保3000端口不被外部直接访问。5. 高级配置与定制化开发5.1 环境变量详解ZIMZ的配置主要通过环境变量完成理解它们有助于故障排查和高级部署。变量名描述示例必填OPENCLAW_GATEWAY_URLOpenClaw Gateway的WebSocket地址。生产环境务必使用ws://127.0.0.1:18789。ws://127.0.0.1:18789是OPENCLAW_GATEWAY_TOKENGateway认证令牌如果启用。优先级高于密码。your-secret-token-here否OPENCLAW_GATEWAY_PASSWORDGateway认证密码如果启用。your-password否NEXT_PUBLIC_APP_NAME自定义PWA应用名称显示在浏览器标签和安装提示中。My Agent Dashboard否NEXT_PUBLIC_APP_DESCRIPTIONPWA应用描述。Dashboard for OpenClaw Agents否注意以NEXT_PUBLIC_开头的变量会在构建时被嵌入到客户端JavaScript中因此不能包含任何敏感信息如密钥、Token。Gateway的认证信息不属于此类是服务端专用变量。5.2 自定义主题与样式ZIMZ采用Tailwind CSS定制视觉风格非常方便。主要修改两个文件app/globals.css这里定义了全局的CSS变量和基础样式。你可以修改:root或.dark下的CSS变量来改变主题色、字体、背景等。:root { --foreground-rgb: 220, 220, 220; /* 默认文字颜色 */ --background-start-rgb: 10, 10, 20; /* 背景渐变起始色 */ --background-end-rgb: 5, 5, 15; /* 背景渐变结束色 */ --accent-color: #00e5a0; /* 主色调绿色 */ }Tailwind配置 (tailwind.config.js)你可以在这里扩展主题颜色、字体、间距等。例如想增加一个品牌色module.exports { theme: { extend: { colors: { brand: #00e5a0, }, fontFamily: { orbitron: [Orbitron, monospace], // 使用的科技感字体 }, }, }, }之后在组件中就可以使用text-brand或bg-brand类名。5.3 扩展功能添加新的交付渠道任务调度器的交付选项是可扩展的。如果你想添加一个新的消息推送渠道比如飞书、钉钉需要修改两处后端 (app/api/cron/jobs/route.ts) 在创建或更新任务的逻辑中你需要解析前端传来的新渠道配置并将其转换为OpenClaw Gateway Cron RPC所能识别的delivery字段格式。这通常意味着你需要了解OpenClaw Gateway支持哪些交付插件及其配置格式。前端 (src/components/TasksView.tsx及相关组件)在任务表单中为新的交付渠道添加一个UI选项例如一个单选按钮或复选框。为该渠道添加对应的配置输入字段如Webhook URL、密钥等。在表单提交时将新渠道的配置数据整合到发送给后端的payload中。这个过程需要对OpenClaw Gateway的Cron API和ZIMZ的前后端数据流有清晰的理解。建议先从模仿现有的Telegram或Discord渠道的实现开始。6. 故障排查与常见问题即使设计再完善在实际部署和运行中也可能遇到问题。这里记录了一些常见情况及其解决方法。6.1 连接类问题问题仪表盘显示“与Gateway断开连接”状态栏为红色。这是最常见的问题表示ZIMZ后端无法连接到OpenClaw Gateway。检查1Gateway服务是否运行# 在运行Gateway的机器上执行 systemctl status openclaw-gateway # 或你使用的进程管理命令检查2Gateway端口是否正确默认是18789。确认Gateway配置文件中host和port设置。ZIMZ的OPENCLAW_GATEWAY_URL环境变量必须与之匹配。# 检查端口是否监听 ss -tlnp | grep 18789 # 或 netstat -tlnp | grep 18789检查3防火墙/安全组规则如果ZIMZ和Gateway不在同一台机器确保Gateway所在服务器的防火墙允许从ZIMZ服务器IP访问18789端口。检查4认证信息是否正确如果Gateway启用了token或password认证请确保在ZIMZ的.env文件中正确设置了OPENCLAW_GATEWAY_TOKEN或OPENCLAW_GATEWAY_PASSWORD。注意Token和Password只需设置一个Token优先级更高。检查5ZIMZ后端日志查看ZIMZ的运行日志通常会有更详细的错误信息。# 如果使用PM2 pm2 logs zimz-dashboard # 如果使用systemd sudo journalctl -u zimz.service -f6.2 数据与显示类问题问题Agent列表为空但Gateway确认有Agent在运行。可能原因ZIMZ后端成功连接了Gateway但调用agents.listRPC时失败或返回空。排查步骤检查ZIMZ后端日志看是否有RPC调用错误。确认Gateway的RPC接口agents.list是否正常工作。可以尝试使用websocat或wscat工具手动连接Gateway WebSocket端口发送RPC请求进行测试。检查网络策略确保ZIMZ后端服务器能访问Gateway的RPC端口。问题编辑Agent的SOUL.md文件后保存失败。可能原因文件内容格式错误、权限问题或RPC调用失败。排查步骤打开浏览器开发者工具F12的“网络(Network)”标签观察PATCH请求到/api/agents/:id的响应。服务器会返回具体的错误信息。检查Gateway日志看agents.files.set调用是否被执行以及错误详情。确认你编辑的文件语法是否正确例如YAML frontmatter格式是否闭合。6.3 性能与优化问题当Agent数量很多例如50时仪表盘操作变慢或卡顿。前端优化虚拟滚动当前的Agent网格视图如果渲染大量卡片会占用大量DOM节点。可以考虑引入虚拟滚动库如tanstack/virtual只渲染可视区域内的卡片。事件防抖实时日志流如果过于频繁每秒多条直接更新React状态会导致频繁重渲染。应对SSE事件处理器使用防抖debounce或节流throttle或者将日志追加到一个固定长度的数组中而不是每次都更新整个数组。后端优化SSE连接管理确保每个浏览器会话只维持一个SSE连接并在页面卸载时正确关闭。Gateway查询优化agents.list可能会返回大量数据。如果每个Agent的workspace文件都很大可以考虑在列表页只获取基本信息在点击详情气泡时才去获取具体的文件内容即按需加载。问题定时任务没有按时执行。排查步骤首先在ZIMZ的“任务调度器”视图中确认任务状态是否为“活跃”。检查OpenClaw Gateway的日志查看其内置的Cron调度器是否有相关日志。确认服务器时间是否正确Cron表达式是基于系统时间的。如果任务配置了交付选项但未收到消息检查Gateway中对应交付插件如telegram, discord的配置是否正确以及网络连通性。6.4 PWA渐进式Web应用相关问题问题无法将ZIMZ安装到手机主屏幕。确保HTTPSPWA要求必须通过HTTPS访问本地localhost除外。检查Manifest确保public/manifest.json文件可访问且格式正确。可以通过访问https://your-domain.com/manifest.json来验证。Service WorkerNext.js的App Router默认支持PWA但需要正确的构建和部署。确保在生产构建 (npm run build) 后部署开发模式下某些PWA特性可能不完整。iOS SafariiOS上的Safari对PWA的支持有特定行为。需要在Safari的分享菜单中选择“添加到主屏幕”。部署并稳定运行ZIMZ后你会发现管理OpenClaw智能体从未如此轻松。从繁琐的命令行到直观的可视化界面不仅仅是效率的提升更带来了对整个多智能体系统运行状态的一种“全局掌控感”。无论是快速检查某个Agent的输出还是批量调整一批Agent的配置亦或是设置复杂的自动化任务流都可以在几分钟内通过点击和拖拽完成。这个项目完美地诠释了“好的工具让复杂的事情变简单”这一理念。如果你正在寻找一个提升OpenClaw运维体验的方案ZIMZ绝对值得你投入时间部署和尝试。