1. 项目概述OpenClaw Dashboard一个为AI智能体集群打造的实时指挥中心如果你正在运行一个OpenClaw智能体集群或者对构建多智能体系统感兴趣那么你很可能面临一个共同的痛点如何清晰地掌控全局当几十甚至上百个智能体在后台同时执行任务、处理请求时你看到的可能只是一堆日志文件或者需要通过命令行不断查询状态。这种“黑盒”操作体验不仅效率低下更让问题排查和系统优化变得异常困难。这正是OpenClaw Dashboard要解决的核心问题——为你的智能体集群提供一个集中、实时、可视化的“任务控制中心”。简单来说OpenClaw Dashboard是一个开源的Web应用它通过WebSocket与你的OpenClaw网关建立连接将分散的智能体状态、任务队列、执行日志、聊天交互以及系统指标聚合在一个直观的仪表盘界面中。你可以把它想象成是给一群AI“员工”配备的数字化办公室大屏管理者可以一眼看清谁在忙碌、谁在空闲、当前有哪些任务在进行、系统整体负载如何并且能直接与任意智能体对话、创建或调整任务。它最初可能只是一个简单的状态查看器但经过v2.0的迭代已经演变成一个具备完整平台层数据库持久化、用户认证、实时推送的生产力工具。这个项目特别适合几类人首先是OpenClaw的深度用户尤其是那些运行着复杂工作流或智能体数量较多的开发者其次是对AI智能体运维和可观测性感兴趣的技术爱好者它的架构设计本身就是一个很好的学习案例最后任何希望为自己的自动化系统构建一个美观、实用管理界面的全栈开发者也能从中获得大量灵感。接下来我将为你深入拆解这个项目的设计思路、核心实现以及我在部署和二次开发中积累的实战经验。2. 架构深度解析双模数据流与模块化设计OpenClaw Dashboard的架构设计非常巧妙它没有采用单一的、僵化的数据获取方式而是设计了一套“双模数据流”架构同时支持网关直连和数据库持久化两种模式。这种设计既保证了与现有OpenClaw集群的无缝集成又为需要数据持久化、复杂任务管理的场景提供了企业级能力。理解这个架构是后续一切部署和定制开发的基础。2.1 核心架构网关模式 vs. 数据库模式项目的核心数据流分为两条清晰的路径它们共同服务于前端React应用但后端的数据源和处理逻辑完全不同。网关模式实时监控流这是Dashboard最原始、也是最核心的功能。在此模式下Next.js服务端作为一个WebSocket客户端主动连接到你本机或内网运行的OpenClaw网关默认端口18789。这个连接是经过认证的使用GATEWAY_TOKEN建立后服务端便可以通过RPC远程过程调用实时获取集群的全量状态。所有数据——智能体列表、会话状态、定时任务Routines——都直接从网关内存中拉取经过一层映射转换gateway-mappers.ts后通过HTTP API暴露给前端。这种模式的优点是延迟极低、数据绝对实时完美契合“监控”场景。但缺点也明显所有状态都存在于网关进程内存中一旦网关重启或Dashboard服务断开历史任务数据、聊天记录等就会丢失它更像一个“实时仪表盘”而非“任务管理系统”。数据库模式持久化管理流v2.0版本引入的数据库模式彻底补足了网关模式的短板。当你在环境变量中配置了DATABASE_URL指向一个PostgreSQL实例后Dashboard会激活一整套基于数据库的CRUD API。任务、通知、聊天消息、定时任务等核心实体都会被持久化到PostgreSQL中。更关键的是它引入了服务端的WebSocket Hubws-server.ts和浏览器端的WebSocket Clientws-client.ts。当你在前端创建、更新一个任务时这个变更会通过HTTP API写入数据库同时服务端的WebSocket Hub会立刻将这个变更事件广播给所有在线的浏览器客户端从而实现真正的实时同步。这种模式将Dashboard从一个“查看器”升级为了一个完整的“协作平台”支持多用户同时操作、历史记录追溯、复杂任务属性如检查清单、评论管理等。数据源选择器智能适配的桥梁为了让两种模式能够平滑共存甚至无缝切换项目在lib/data-source.ts中实现了一个智能的数据源选择器。它的逻辑非常清晰系统会优先检查数据库连接是否可用。如果可用则所有数据操作都走db-data.ts模块如果不可用比如未配置DATABASE_URL则自动回退到基于文件的data.ts模块一个更简单的本地JSON文件存储方案主要作为开发兜底。这种设计极大地提升了部署的灵活性你可以先从简单的网关模式用起待业务需要时再接入数据库无需修改业务代码。注意模式选择不是非此即彼。在实际运行中网关模式和数据库模式可以同时启用。例如实时智能体状态和活动日志Activity Feed可能仍然通过网关获取以保证毫秒级延迟而任务管理和通知系统则完全基于数据库。你需要仔细阅读useClusterState.ts和各个API路由的实现来理解哪些功能用了哪种数据源。2.2 项目结构清晰的关注点分离浏览src/目录你能立刻感受到这是一个典型的、结构良好的Next.js 14App Router项目。它的模块划分体现了清晰的责任边界app/api/这是后端逻辑的核心。注意它进一步按功能分为了gateway/网关适配器和tasks/、notifications/等v2.0 CRUD接口。这种划分与双模架构一一对应非常利于维护。components/所有React UI组件都存放在这里。从命名就能看出其功能如AgentStrip智能体状态条、MissionQueue任务看板、CommandPalette命令面板。特别值得一提的是skeletons/目录里面存放了用于加载状态占位的骨架屏组件这对提升用户体验至关重要。lib/这是项目的“引擎舱”包含了所有关键的业务逻辑和工具函数。除了前面提到的数据源、WebSocket、数据库客户端这里还有routine-scheduler.ts定时任务调度引擎和notification-bus.ts通知事件总线这样的核心服务。types/集中管理所有TypeScript接口定义。在一个数据模型复杂的全栈应用中保持类型定义的单一定义和复用能极大减少前后端联调的摩擦。scripts/存放数据库迁移脚本和离线工具如将文件任务迁移到数据库的脚本。这体现了对项目生命周期管理的重视。这种结构不仅让新开发者易于上手更重要的是当你想扩展功能时——比如想增加一个“智能体资源监控”面板——你很容易就知道该在哪里添加新的API路由app/api/metrics/、新的数据类型types/index.ts、新的业务逻辑lib/agent-monitor.ts以及新的UI组件components/AgentMonitorPanel.tsx。3. 核心功能模块拆解与实操要点了解了宏观架构我们深入到各个核心功能模块看看它们是如何实现的以及在部署和使用时需要注意哪些关键细节。3.1 实时智能体状态条AgentStrip这是Dashboard的“门面”通常位于页面顶部。它通过轮询或WebSocket从网关获取所有已注册智能体的实时快照并以紧凑的条形布局展示。每个智能体卡片通常会显示头像/标识、名称、状态空闲、忙碌、错误、当前任务如果有、所使用的AI模型以及简单的负载指标。实操要点与避坑指南状态更新的频率检查useClusterState钩子或相关API的轮询间隔。过于频繁如每秒一次会给网关带来不必要的压力过于稀疏如30秒一次则会导致状态显示滞后。通常5-10秒的间隔是一个平衡点。如果启用了数据库模式并配合浏览器WebSocket对于任务状态变更这类事件可以实现真正的实时推送无需轮询。网关连接稳定性服务端的WebSocket客户端gateway-client.ts必须具备重连机制。网络波动或网关重启会导致连接中断。一个健壮的实现应该包含指数退避的重连逻辑并在前端通过UI提示连接状态。智能体数量过多时的UI处理如果集群有上百个智能体横向滚动条体验会很差。可以考虑在AgentStrip组件中实现一个“折叠/展开”的开关或者只显示一个概要计数点击后再弹窗查看详情列表。3.2 任务看板MissionQueue / Kanban Board这是v2.0数据库模式下的核心功能一个完整的拖拽式任务看板。它通常将任务分为“待处理”、“进行中”、“已完成”等列。每个任务以卡片TaskCard形式呈现支持拖拽改变状态点击可查看/编辑详情TaskEditModal详情内可以管理检查清单ChecklistPanel和评论。实现细节与经验拖拽库的选择项目使用了dnd-kit库。这是一个现代、轻量且功能强大的React拖拽库。在实现时你需要处理好拖拽时的视觉反馈如拖动中的克隆体、放置目标的预览以及拖拽结束后的数据同步。数据同步必须通过调用/api/tasks/[id]的PATCH接口来更新任务的status字段并确保通过WebSocket广播此更新使其他用户的看板同步刷新。任务卡片的性能优化看板可能承载大量任务卡片。如果每个卡片都订阅复杂的实时更新可能引发性能问题。一个优化策略是使用虚拟滚动如react-virtuoso只渲染可视区域内的卡片。另外任务详情的模态框Modal应在打开时才去获取完整的检查清单和评论数据而不是在卡片渲染时预加载。检查清单与评论的实时同步这是体现WebSocket价值的地方。当用户A在任务详情中添加了一个检查项或评论这个事件除了保存到数据库还应立即通过WebSocket Hub广播。用户B如果正开着同一个任务的详情模态框他的界面应该能自动刷新看到用户A刚添加的内容从而实现协同办公般的体验。3.3 定时任务管理Routine ManagerRoutine是OpenClaw中预设的、可定时或手动触发的自动化流程。Dashboard的RoutineManager组件提供了图形化界面来管理这些流程创建、编辑、启用/禁用、立即触发。核心机制解析调度引擎lib/routine-scheduler.ts是大脑。在数据库模式下它会在服务启动时从数据库加载所有已启用的Routine并使用node-cron或类似的库在内存中注册定时任务。当定时时刻到达调度引擎会通过网关RPC触发对应的Routine执行。这里的关键是保证调度器的单例性和错误处理避免重复注册或任务丢失。双模存储在网关模式下Routine信息存储在网关内存中通过/api/gateway/routines接口进行管理。在数据库模式下Routine定义存储在PostgreSQL的routines表中。># 1. 检查Node.js版本推荐18或20 LTS版本 node --version # 2. 克隆项目代码 git clone https://github.com/bokiko/openClaw-dashboard.git cd openClaw-dashboard # 3. 安装依赖 npm install # 如果网络不佳可以考虑使用淘宝镜像或设置npm代理依赖安装常见问题Python或C构建工具缺失某些Native模块如bcrypt如果后续添加可能需要本地编译环境。在Windows上你需要安装windows-build-tools在macOS上需要Xcode Command Line Tools在Linux上需要build-essential等。Sharp镜像问题Next.js项目常用的图片处理库sharp可能需要从特定镜像下载。如果安装失败可以尝试设置环境变量npm_config_sharp_binary_hosthttps://npmmirror.com/mirrors/sharp。4.2 配置文件与环境变量详解接下来是配置环节这是决定Dashboard以何种模式运行的关键。在项目根目录创建.env.local文件。基础必填配置认证# 用于签发和验证JWT令牌的密钥必须设置且应足够复杂。 # 在Linux/macOS下生成openssl rand -hex 32 # 在Windows下可以用PowerShell: [System.BitConverter]::ToString((1..32|%{[byte](Get-Random -Max 256)})) -replace -, DASHBOARD_SECRET你的32位以上十六进制密钥没有这个密钥Dashboard将无法进行用户认证登录。如果为了快速测试想跳过登录可以暂时不设置此变量Dashboard会进入“开放访问模式”但强烈不建议在生产环境或公网环境下这么做。数据库配置启用v2.0完整功能# PostgreSQL连接字符串。这是启用任务看板、通知、聊天记录持久化的关键。 DATABASE_URLpostgresql://username:passwordlocalhost:5432/openclaw_dashboard你需要先确保有一个运行中的PostgreSQL实例并创建好对应的数据库如openclaw_dashboard。如果没有配置此项Dashboard将回退到文件存储模式很多高级功能将不可用。网关连接配置实现实时监控# 你的OpenClaw网关WebSocket地址默认端口18789 GATEWAY_WS_URLws://127.0.0.1:18789 # 网关的认证令牌在网关配置文件中可以找到 GATEWAY_TOKENyour_actual_gateway_token_here # 网关的HTTP健康检查端点用于Dashboard检查连接状态 GATEWAY_HEALTH_URLhttp://127.0.0.1:18792这是Dashboard能够显示智能体状态和活动日志的前提。请确保你的OpenClaw网关正在运行并且令牌正确。文件存储回退配置# 当没有配置DATABASE_URL时任务数据将存储在此目录的JSON文件中 OPENCLAW_TASKS_DIR./tasks这是一个简单的备用方案适合轻量级测试。4.3 数据库初始化与数据迁移如果你决定使用数据库模式配置好DATABASE_URL后需要初始化数据库结构。执行迁移脚本 项目在scripts/migrations/目录下提供了按顺序编号的SQL迁移文件。必须按数字顺序执行因为后面的脚本可能依赖前面创建的表。# 假设你的DATABASE_URL环境变量已设置 # 方法一使用psql命令行工具依次执行 psql $DATABASE_URL -f scripts/migrations/002_dashboard_tasks.sql psql $DATABASE_URL -f scripts/migrations/003_agents.sql # ... 依次执行直到 008_task_extras.sql # 方法二在项目根目录可以使用一个简单的Shell循环Linux/macOS for f in scripts/migrations/*.sql; do echo Running $f psql $DATABASE_URL -f $f done重要提示迁移脚本001_initial.sql可能不存在或已被整合。请务必检查migrations目录下的实际文件列表从编号最小的开始执行。执行前最好先备份数据库。迁移现有文件任务 如果你之前已经在使用文件模式存储了一些任务并希望导入到新数据库中可以使用提供的工具脚本npx tsx scripts/migrate-files-to-db.ts这个脚本会读取OPENCLAW_TASKS_DIR目录下的JSON文件并将其转换为数据库记录。运行前请确保数据库表已创建并做好数据备份。4.4 启动与验证完成以上步骤后就可以启动开发服务器了npm run dev正常情况下终端会输出“Ready on http://localhost:3000”。打开浏览器访问该地址。首次访问与登录如果设置了DASHBOARD_SECRET你会被重定向到登录页面。在密码框中输入你设置的DASHBOARD_SECRET值即可登录。这个设计意味着初始只有一个“超级管理员”账户密码就是密钥本身。对于多用户需求你需要在此基础上扩展用户体系。如果未设置DASHBOARD_SECRET则会直接进入Dashboard主界面。功能验证清单 登录后请按顺序检查以下核心功能是否正常以确认各模块配置正确智能体状态条检查是否显示了你的OpenClaw集群中的智能体。如果没有请检查GATEWAY_WS_URL和GATEWAY_TOKEN是否正确以及网关服务是否正常运行。任务看板尝试创建一个新任务拖拽改变其状态。如果功能不可用或报错很可能是数据库连接DATABASE_URL有问题或迁移未成功。活动日志观察是否有实时事件在滚动。这验证了网关连接和活动日志系统正常工作。通知面板点击右上角的铃铛图标查看通知面板是否能正常打开。命令面板按CmdK看是否能弹出搜索框并执行一些快捷命令。5. 开发、定制与故障排查指南将Dashboard运行起来只是第一步。你可能需要根据自身业务定制UI、添加新的监控指标或者集成到现有系统中。同时运行过程中也难免会遇到问题。5.1 二次开发与功能扩展添加一个新的监控指标面板 假设你想监控每个智能体的平均任务处理时间。后端API在app/api/metrics/目录下创建新的路由文件例如average-task-time/route.ts。在此路由中你可以通过网关RPC获取历史任务数据或从数据库的tasks表中计算相关指标。设计并返回一个结构化的JSON数据如{ agentId: string, avgDuration: number }[]。前端组件在components/目录下创建新的组件如AgentPerformanceChart.tsx。在组件内使用useEffect和fetch或更好的使用swr/tanstack-query这类库调用你新创建的API端点。使用Recharts或类似图表库将数据可视化。将这个新组件集成到主布局或MetricsPanel中。修改主题或样式 项目使用Tailwind CSS定制样式非常方便。检查tailwind.config.js或tailwind.config.ts文件这里定义了项目的设计令牌颜色、字体、间距等。要修改主色调可以更新配置中的primary颜色值。要调整某个特定组件如任务卡片的样式直接找到对应的组件文件TaskCard.tsx修改其className即可。Tailwind的实用性优先原则使得样式与结构紧密结合。5.2 常见问题与排查技巧以下是我在部署和使用过程中遇到的一些典型问题及解决方法问题一启动后访问页面空白控制台报错“Failed to fetch”或“WebSocket connection failed”。排查步骤检查环境变量确认.env.local文件已创建且位于项目根目录变量名拼写正确。Next.js默认只加载.env.local、.env.development、.env.production。检查网关服务在终端使用curl http://127.0.0.1:18792/health对应GATEWAY_HEALTH_URL检查网关HTTP服务是否存活。使用websocat或浏览器WebSocket工具测试GATEWAY_WS_URL是否能连通。检查后端日志查看运行npm run dev的终端输出是否有关于数据库连接失败或网关认证失败的报错信息。可能的原因网关未启动或端口被占用。GATEWAY_TOKEN错误导致WebSocket连接认证失败。DATABASE_URL格式错误或数据库服务未运行。问题二任务看板可以显示但创建或拖拽任务后页面不更新或报数据库错误。排查步骤检查数据库连接在项目根目录可以临时创建一个脚本测试数据库连接或使用psql命令行直接连接DATABASE_URL指定的数据库执行一个简单查询如SELECT 1;。检查数据库表结构确认所有迁移脚本002-008都已成功执行。可以连接到数据库查看是否存在tasks、notifications等表。检查浏览器开发者工具打开Network标签页查看创建任务POST/api/tasks或更新任务PATCH/api/tasks/[id]的API请求是否返回错误状态码如500。查看响应体中的错误信息。可能的原因数据库用户权限不足无法对表进行INSERT/UPDATE操作。迁移脚本执行顺序错误导致表依赖关系出错。Next.js服务端代码中存在未处理的数据库查询异常。问题三活动日志或通知没有实时更新。排查步骤确认WebSocket连接在浏览器开发者工具的Network标签页中过滤ws://或wss://连接查看与本地服务器的WebSocket连接是否已建立状态码应为101。检查服务端WebSocket Hub确认lib/ws-server.ts模块已正确导入并在服务启动时初始化。检查其日志输出如果有。验证事件广播在创建任务或发送通知时检查后端代码是否调用了notification-bus.ts或相应的事件发射器来广播消息。可能的原因浏览器环境不支持WebSocket极罕见。服务端WebSocket服务器初始化失败可能由于端口冲突或其他运行时错误。前端WebSocket客户端lib/ws-client.ts在连接断开后没有成功重连。问题四登录后会话很快失效需要频繁重新登录。排查步骤检查JWT过期时间查看lib/auth.ts中签发JWT时设置的expiresIn选项。默认可能是24小时‘24h’。检查Cookie设置在浏览器开发者工具的Application - Cookies中查看会话Cookie的Expires/Max-Age属性。确保httpOnly和secure在生产环境HTTPS下标志设置正确。检查服务器时钟如果服务器时钟与浏览器时钟偏差过大可能导致令牌过早被判定为过期。解决方案适当增加JWT的过期时间但需权衡安全性。实现令牌刷新机制在令牌即将过期时通过一个安全的刷新接口获取新令牌。5.3 生产环境部署建议将Dashboard用于团队内部或小规模生产环境时需要考虑更多使用Docker容器化为项目编写Dockerfile和docker-compose.yml将Dashboard、PostgreSQL数据库打包在一起便于部署和版本管理。确保在Docker中正确传递环境变量。配置反向代理与HTTPS使用Nginx或Caddy作为反向代理处理SSL/TLS终止、静态文件服务和负载均衡。将Dashboard运行在非3000端口如内部端口3001通过代理对外暴露。环境配置管理生产环境的.env.production文件必须妥善保管敏感信息如DASHBOARD_SECRET、DATABASE_URL密码应使用环境变量或密钥管理服务如AWS Secrets Manager、HashiCorp Vault注入而不是硬编码在文件中。数据库备份与维护为PostgreSQL设置定期备份策略。对于activity_log和chat_messages这类可能快速增长的表考虑制定数据归档或清理策略。监控与日志为Next.js服务添加应用性能监控APM和集中式日志收集如ELK栈或Sentry以便及时发现和诊断运行时错误。安全加固确保DASHBOARD_SECRET足够复杂且定期更换。在生产环境强制启用HTTPS。考虑在反向代理层设置IP白名单或基础认证增加一层防护。定期审计依赖库的安全漏洞使用npm audit或yarn audit。OpenClaw Dashboard作为一个开源项目其价值不仅在于它提供了一个开箱即用的管理界面更在于它展示了一套构建现代、实时、全栈Web应用的优秀实践。从双模数据架构、实时WebSocket同步、到清晰的模块划分和TypeScript的全面应用每一个设计决策都值得细细品味。无论你是直接使用它来管理你的AI集群还是借鉴其代码来构建自己的系统我相信这个项目都能给你带来实实在在的启发和帮助。在实际使用中最深刻的体会是将复杂的后台进程状态可视化所带来的运维效率提升和心智负担降低是巨大的它让“掌控感”从抽象的命令行变成了具象的交互界面。如果你在部署或开发中遇到了README之外的问题不妨去项目的GitHub仓库的Issues页面看看或者按照贡献指南提交你的Pull Request社区的协作往往能碰撞出更棒的火花。