1. 项目概述为你的AI Agent打造一个专属的“驾驶舱”如果你正在使用OpenClaw这类AI Agent框架那么你很可能已经体验过它的强大能力一个能够自主思考、执行任务、学习进化的数字助手。但随之而来的问题是你如何清晰地了解它的“状态”它在想什么它用了多少API额度花了多少钱系统资源还够用吗过去你可能需要频繁地SSH登录服务器在终端里敲打各种命令查看分散的日志和文件这个过程既繁琐又不够直观。OpenClaw Dashboard就是为了解决这个问题而生的。它是一个开源的、自托管的实时监控仪表盘专门为OpenClaw Agent设计。你可以把它想象成给你的AI Agent装上一个功能齐全的“驾驶舱”或“控制中心”。在这里所有关键信息——从会话活动、API使用率、成本分析到系统健康状态、记忆文件、乃至安全审计——都被整合在一个现代化的Web界面中并以近乎实时的方式更新。这个项目最吸引我的地方在于它的“一体化”和“零依赖”理念。它本身就是一个纯Node.js应用无需数据库开箱即用。通过深度集成OpenClaw的工作流它能自动发现会话、解析记忆、监控系统让你从一个统一的视角掌控全局。无论是想快速查看Agent今天完成了哪些任务还是想精细分析本月在Claude API上的花费抑或是排查某个服务为何异常这个仪表盘都能提供直接的答案。2. 核心架构与设计思路拆解2.1 为什么选择纯Node.js Server-Sent Events (SSE)在技术选型上OpenClaw Dashboard做了一个非常务实且高效的选择后端使用纯Node.js前端通过Server-Sent Events (SSE)实现实时数据推送。这背后有几个关键的考量。首先零外部依赖。项目明确声明“no database or npm packages required”。这意味着部署极其简单你只需要一个Node.js环境。所有数据如用户凭证、健康历史都存储在本地JSON文件中。这种设计极大地降低了运维复杂度也避免了因数据库连接、版本兼容等问题带来的故障。对于个人或小团队使用的监控工具来说这种轻量级架构是完全够用且优雅的。其次实时性的权衡。监控仪表盘的核心需求之一是数据的实时性。常见的方案有WebSocket和SSE。WebSocket是双向通信功能更强大但实现相对复杂。SSE是单向的服务器向客户端推送但实现简单并且天然支持自动重连。对于监控场景数据流主要是从服务器推送到客户端如新的日志条目、会话状态更新SSE完全满足需求且代码更简洁、资源开销更小。在server.js中你可以看到它维护了一个客户端连接数组当有新的Agent消息或系统事件时就遍历这个数组进行广播模式非常清晰。最后与现有生态的无缝集成。Node.js能够轻松地执行系统命令通过child_process模块读取文件系统这正好契合了监控各种外部进程如OpenClaw服务、Docker、系统日志的需求。仪表盘通过调用ps、df、docker ps等命令或者直接读取OpenClaw工作区内的特定文件如MEMORY.md,sessions/目录来获取所有需要的数据无需Agent本身提供复杂的API。2.2 安全模型从零构建一个可信的Web管理界面将一个管理界面暴露出来即使是内网安全也是头等大事。OpenClaw Dashboard的安全设计考虑得非常周全形成了一套多层防御体系。1. 认证与会话管理这是第一道防线。它没有采用简单的Cookie而是实现了基于Token的服务器端会话。用户登录后服务器生成一个随机会话Token存储在内存中并返回给客户端。客户端后续的每个API请求都必须在Authorization头中携带这个Token。服务器在内存中进行校验。这种方式避免了Cookie可能面临的CSRF攻击并且服务重启后所有会话失效增加了安全性。2. 密码存储与MFA密码绝不明文存储。它使用PBKDF2算法配合一个随机生成的Salt进行10万次SHA-512哈希迭代后才存储。这即使面对彩虹表攻击也有很强的抵抗力。更进阶的是它支持基于时间的一次性密码TOTP多因素认证MFA。启用后用户除了密码还需要输入Google Authenticator等应用生成的6位动态码才能登录。这为账号安全加上了双保险。其实现原理是服务器生成一个Base32格式的密钥前端将其转化为二维码供用户扫描。登录时服务器用同样的密钥和当前时间计算TOTP与用户输入的进行比对允许±30秒的时钟容差。3. 网络访问控制仪表盘默认对访问来源非常“挑剔”。它只允许来自localhost127.0.0.1和Tailscale内网网段100.64.0.0/10的HTTP连接。对于其他任何IP的HTTP请求它会强制返回“HTTPS required”错误。这是一个非常聪明的默认设置鼓励用户通过本地端口转发或Tailscale这样的加密VPN进行访问从而在传输层就获得安全保障。如果你确实需要在普通局域网用HTTP访问必须显式设置环境变量DASHBOARD_ALLOW_HTTPtrue。4. 操作审计与输入硬化所有关键操作如登录、登出、密码修改、MFA启用/禁用、配置文件修改等都会被记录到audit.log文件中。这为事后追溯提供了依据。同时在处理用户输入时比如读取文件路径代码会进行规范化并检查路径遍历攻击如../../../etc/passwd。对于执行系统命令它采用了严格的服务白名单机制防止任意命令注入。2.3 数据流与集成点解析理解仪表盘的数据流有助于你定制化或排查问题。其核心数据源可以分为以下几类1. OpenClaw Agent原生数据会话列表通过扫描~/.openclaw/agents/agent_id/sessions/目录。每个子目录代表一个会话其中的session.json文件包含了模型、状态、消息历史等元数据。记忆文件直接读取工作区根目录的MEMORY.md长期记忆、HEARTBEAT.md心跳任务列表以及memory/目录下的每日笔记。配置文件与技能读取工作区内skills/、config/等目录的文件并提供在线编辑功能编辑前会自动创建备份文件。2. 系统与外部API数据系统健康通过执行top、df、vcgencmd树莓派等命令获取CPU、内存、磁盘、温度信息并定期采样存入health-history.json用于绘制趋势图。服务状态通过systemctl命令检查OpenClaw相关服务如clawd的运行状态。API用量与成本这是两个需要额外脚本支持的“增强功能”。Claude用量依赖于scripts/scrape-claude-usage.sh和scripts/parse-claude-usage.py。其原理是模拟或调用Claude Code CLI来获取真实的用量数据。仪表盘提供了手动触发抓取的按钮。Gemini用量类似依赖于scripts/scrape-gemini-usage.sh和scripts/parse-gemini-usage.py从Google AI Studio或相关API获取数据。Docker如果宿主机安装了Docker且仪表盘进程有权限访问/var/run/docker.sock则可以列出容器、镜像并执行启停等操作。3. 实时事件流这是通过SSE实现的/api/live端点。任何地方如会话更新、日志产生、手动触发都可以调用broadcastMessage函数向所有连接的客户端推送一个JSON格式的事件。前端JavaScript监听这个事件流并动态更新UI。例如当Agent发送一条新消息时这条消息会同时被追加到会话详情和“实时动态”页面。3. 从零开始的部署与配置实战3.1 环境准备与基础部署假设你已经在服务器可以是云服务器、本地NAS或树莓派上运行了OpenClaw。部署Dashboard的第一步是获取代码。# 1. 克隆仓库 git clone https://github.com/tugcantopaloglu/openclaw-dashboard.git cd openclaw-dashboard # 2. 检查Node.js版本确保是v18或以上 node --version # 3. 设置环境变量关键步骤 # 告诉Dashboard你的OpenClaw工作区在哪里。如果未设置它会尝试自动检测。 export WORKSPACE_DIR/home/yourusername/.openclaw/workspace # 如果你想监控非默认的Agent可以指定 export OPENCLAW_AGENTmy_agent # 自定义访问端口 export DASHBOARD_PORT7070 # 4. 启动 node server.js启动后控制台会输出访问地址和一个恢复令牌Recovery Token。务必保存好这个令牌它是你忘记密码时的唯一救命稻草。注意第一次启动时因为data/credentials.json文件不存在仪表盘会处于“等待注册”状态。此时用浏览器访问http://你的服务器IP:7070看到的将是注册页面而不是登录页。注册第一个账号后该文件被创建后续访问才会显示登录页。3.2 进阶部署以Systemd服务形式运行对于生产环境我们肯定不希望一个SSH窗口关掉Dashboard就停了。将其配置为Systemd服务是最佳实践。项目贴心地提供了install.sh脚本。# 1. 使用安装脚本需要sudo权限 sudo ./install.sh这个脚本会做以下几件事在/etc/systemd/system/下创建agent-dashboard.service单元文件。创建一个覆盖配置目录/etc/systemd/system/agent-dashboard.service.d/并在其中生成override.conf将你的WORKSPACE_DIR和自动生成的DASHBOARD_TOKEN写入环境变量。重载Systemd配置并启用开机自启、启动该服务。你可以查看服务状态和日志sudo systemctl status agent-dashboard sudo journalctl -u agent-dashboard -f # 实时跟踪日志手动配置Systemd服务供参考如果你想更精细地控制可以手动创建服务文件/etc/systemd/system/agent-dashboard.service[Unit] DescriptionOpenClaw Agent Dashboard Afternetwork.target [Service] Typesimple Useryourusername WorkingDirectory/path/to/openclaw-dashboard EnvironmentWORKSPACE_DIR/home/yourusername/.openclaw/workspace EnvironmentDASHBOARD_PORT7000 ExecStart/usr/bin/node /path/to/openclaw-dashboard/server.js Restarton-failure RestartSec10 [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable --now agent-dashboard3.3 网络访问与HTTPS配置详解如前所述默认的安全策略会阻止非本机的HTTP访问。你有以下几种安全的访问方式方案A本地端口转发最安全简单如果你在本地电脑上操作通过SSH隧道将服务器的7000端口映射到本地。ssh -L 7000:localhost:7000 yourusernameyour-server-ip然后直接在本地浏览器访问http://localhost:7000。所有流量都通过加密的SSH通道传输无需担心HTTP明文问题。方案B通过Tailscale等VPN访问如果你和服务器都加入了同一个Tailscale网络你可以直接用服务器的Tailscale IP通常是100.x.x.x访问。因为Tailscale IP段100.64.0.0/10被仪表盘默认信任允许HTTP访问同时Tailscale在节点间自动建立了加密通道。方案C通过反向代理提供HTTPS用于公网或复杂内网如果你需要在非Tailscale的内网或者有特殊需求要从公网强烈不推荐访问你应该在前面加一个反向代理如Nginx, Caddy来提供HTTPS。一个简单的Caddyfile配置示例dashboard.yourdomain.com { reverse_proxy localhost:7000 header { # 确保仪表盘能识别到来自HTTPS X-Forwarded-Proto https } }Caddy会自动申请并管理SSL证书。Nginx配置类似但需要手动配置SSL证书。这样外部通过HTTPS访问你的域名代理服务器解密后以HTTP协议转发给本地的Dashboard进程并且附带了X-Forwarded-Proto: https头使Dashboard认为连接是安全的。重要提醒即使通过HTTPS暴露也强烈建议在反向代理层或服务器防火墙设置IP白名单仅允许可信IP段访问进一步减少攻击面。3.4 功能依赖项与可选组件安装仪表盘核心功能无需额外依赖但部分增强功能需要安装特定工具Docker管理页面需要安装jq一个轻量级命令行JSON处理器用于解析docker命令的输出。# Ubuntu/Debian sudo apt install jq # CentOS/RHEL sudo yum install jqClaude用量抓取需要tmux和python3。这是因为抓取脚本可能需要在一个独立的tmux会话中运行Claude CLI命令并用Python解析结果。确保这些工具已安装。sudo apt install tmux python3系统健康监控树莓派温度树莓派上需要vcgencmd工具它通常包含在libraspberrypi-bin包中默认已安装。如果这些工具缺失对应的Dashboard功能如Docker页面、Claude用量图表可能会显示错误或为空但核心功能不受影响。4. 核心功能模块深度使用指南4.1 会话管理与实时动态洞察Agent的“思维过程”“会话”页面是Dashboard的核心。它列出了所有Agent运行过的任务会话。每个会话卡片显示了模型、创建时间、状态运行中、已完成、失败、消息数量以及一个成本估算。实操要点实时更新当Agent在某个会话中发送或接收消息时该会话的“最后活动”时间和消息数会实时更新。你无需刷新页面。深入查看点击任意会话可以展开查看完整的消息历史。这对于调试Agent的行为、理解它为什么做出某个决策至关重要。消息通常按角色用户、助理区分并高亮显示代码块。状态过滤页面顶部的筛选器可以让你快速聚焦于“运行中”、“已完成”或“失败”的会话。时间线视图这是一个非常直观的功能它以横向时间线的形式展示了不同会话的起止时间和重叠情况帮助你一目了然地了解Agent的工作负载分布。注意事项会话数据来源于OpenClaw生成的session.json文件。如果OpenClaw异常退出导致文件未正确保存或者你手动删除了会话目录那么Dashboard中将看不到这些记录。这是一种“最终一致性”的视图。4.2 成本与用量监控守住你的API预算对于频繁使用Claude、Gemini等付费API的用户来说成本控制是刚需。Dashboard的“成本”和“用量限制”页面提供了多维度的分析。成本分析页面按日视图以柱状图展示每日总花费点击柱子可以下钻查看该日不同模型如Claude-3-Opus, Claude-3-Sonnet的消费占比。按模型视图饼图展示总花费中各个模型的贡献度。按会话视图列表展示花费最高的会话帮你定位“烧钱”的任务。数据来源成本数据依赖于OpenClaw在会话中记录的理论token消耗和预设的模型单价进行计算。请注意这只是估算最终费用以官方账单为准。但对于监控异常消费趋势已经足够。用量限制页面滚动窗口这里展示的是过去5小时可配置的用量特别是针对有每分钟/每小时速率限制的API。双提供商支持可以切换查看Claude和Gemini的用量。进度条直观显示了当前用量距离限制还有多少余量。手动抓取页面提供了“抓取Claude用量”和“抓取Gemini用量”的按钮。点击后会触发执行对应的scrape-*.sh脚本从官方渠道拉取真实用量并更新图表。建议结合系统的Cron任务定期如每小时执行抓取以保持数据新鲜。经验分享我将抓取脚本配置为Cron任务每小时运行一次。然后在Dashboard的“Cron管理”页面可以方便地看到这个任务的状态、上次运行时间并且可以手动触发或禁用它。这种集成度大大简化了运维。4.3 记忆与文件管理直接与Agent的“大脑”对话“记忆”和“文件”页面让你能直接浏览和编辑Agent工作区内的内容。记忆查看器集中展示MEMORY.md长期核心记忆、HEARTBEAT.md待办任务列表以及memory/目录下的所有每日笔记。点击任一文件内容会以渲染后的Markdown形式在右侧面板显示。这对于快速回顾Agent的学习成果和当前任务焦点非常有用。文件管理器列出工作区内的所有文件特别是skills/技能、config/配置等关键目录。安全编辑这是一个强大但危险的功能。你可以直接在线编辑文件如修改某个技能的提示词。保存时Dashboard会做两件事1) 在相同目录下创建一份带时间戳的.bak备份文件2) 向OpenClaw网关发送重启信号使配置生效。请谨慎操作尤其是修改核心配置文件时。4.4 系统健康与运维控制台这个模块将服务器运维的常用命令Web化。系统健康实时显示CPU使用率、内存占用、磁盘空间和如果支持温度。下方有“健康历史”图表展示过去24小时各项指标的趋势帮助你发现潜在问题如内存泄漏、磁盘空间持续减少。服务控制列出与OpenClaw相关的系统服务如clawd。提供一键“重启”、“停止”、“启动”按钮。这些操作通过调用systemctl命令实现但受服务白名单限制只能操作预设的几个安全服务。日志查看器可以实时查看systemd日志通过journalctl或特定服务的日志文件。支持自动刷新是排查服务启动失败、运行时错误的神器。Docker管理如果安装了Docker展示所有容器状态、镜像列表。可以对容器执行启动、停止、重启、删除操作。提供“清理”按钮一键删除未使用的镜像、容器、网络和构建缓存释放磁盘空间。4.5 安全与配置中心这是Dashboard的管理后台功能敏感因此需要二次认证点击进入时会要求你再次输入密码。安全仪表盘UFW防火墙规则显示当前防火墙状态和规则列表。开放端口列出系统上所有处于监听状态的网络端口帮助发现不必要的服务暴露。Fail2ban状态显示Fail2ban服务的状态和被封禁的IP用于防御SSH暴力破解。SSH登录日志展示最近的SSH登录尝试成功/失败。审计日志展示Dashboard自身的所有安全相关事件记录。配置编辑器直接编辑OpenClaw的主配置文件通常是~/.openclaw/config.json。保存时自动创建备份并重启OpenClaw网关使新配置立即生效。编辑器带有简单的JSON语法高亮和验证。5. 常见问题排查与运维技巧5.1 登录与认证问题问题1忘记了密码也没有保存恢复令牌。这是最棘手的情况。解决方案是“核重置”——删除凭证文件。SSH登录到服务器。找到Dashboard的数据目录通常在工作区的data/子目录下或/root/clawd/data/删除credentials.json文件。重启Dashboard服务sudo systemctl restart agent-dashboard。重新访问页面你会再次看到注册界面可以设置新的用户名和密码。代价之前的密码和MFA设置全部丢失。问题2启用MFA后手机丢失或验证器App数据没了。按照上文“MFA重置”部分的操作通过SSH执行命令删除credentials.json文件中的mfaSecret字段。重启服务后即可用密码登录然后重新设置MFA。教训启用MFA时务必将恢复代码如果验证器App提供或二维码密钥文本妥善备份。问题3登录时提示“Too many failed attempts”。这是触发了登录速率限制5次失败尝试后软锁定15分钟20次后硬锁定。解决等待15分钟或者重启Dashboard服务sudo systemctl restart agent-dashboard来清空内存中的计数器。5.2 数据不显示或显示异常问题1“会话”页面为空但OpenClaw明明在运行。检查路径确认WORKSPACE_DIR和OPENCLAW_AGENT环境变量设置正确。Dashboard会在$OPENCLAW_DIR/agents/$OPENCLAW_AGENT/sessions/下寻找会话。检查权限确保运行Dashboard进程的用户如yourusername或root有权限读取OpenClaw的目录和文件。查看日志检查Dashboard的日志journalctl -u agent-dashboard是否有权限错误。问题2Claude/Gemini用量数据一直为0或无法抓取。检查脚本确认工作区的scripts/目录下存在scrape-claude-usage.sh和对应的Python解析脚本。检查依赖确保服务器安装了tmux和python3。手动测试SSH到服务器切换到工作区目录手动执行./scripts/scrape-claude-usage.sh看是否有错误输出。可能是Claude CLI未登录或者API密钥失效。查看抓取结果抓取成功后数据会保存在data/claude-usage.json。可以手动查看这个文件是否有内容。问题3系统健康数据如温度不显示。树莓派温度确保vcgencmd命令可用。在非树莓派系统上此功能不可用。CPU/内存Dashboard使用top和free命令。在容器化部署时需要确保容器有权限访问宿主机的/proc文件系统或者传递相应的Volume。5.3 性能与网络问题问题Dashboard界面加载慢或实时更新有延迟。检查服务器负载首先通过Dashboard自身的“系统健康”页面或SSH使用htop命令确认服务器CPU和内存是否过载。检查客户端网络如果通过Tailscale或公网访问网络延迟可能影响实时性。SSE连接在弱网环境下可能断开重连。调整轮询间隔前端默认每5秒轮询一次数据如会话列表、系统健康。对于会话数量非常多数百个的情况可以适当调慢这个频率但需要修改前端代码。问题通过反向代理访问部分功能如SSE实时推送不正常。代理超时设置SSE连接是长连接。确保你的Nginx或Caddy配置为这些连接设置了较长的超时时间例如proxy_read_timeout 3600s;。缓冲设置有时需要禁用代理缓冲以确保数据实时推送proxy_buffering off;。连接头确保代理正确传递了X-Forwarded-For和X-Forwarded-Proto头。5.4 备份与恢复策略Dashboard本身不存储你的核心数据会话、记忆这些都在OpenClaw工作区。但它存储了关键的配置数据data/credentials.json用户凭证和MFA密钥。务必定期备份此文件尤其是在启用MFA后。丢失它意味着你需要重置整个认证体系。data/audit.log安全审计日志。可根据安全合规要求定期归档。data/health-history.json等历史数据丢失影响不大。简易备份方案 创建一个简单的Cron任务定期将整个Dashboard目录或至少data/子目录打包备份到其他位置或云存储。# 例如每天凌晨2点备份 0 2 * * * tar -czf /backup/openclaw-dashboard-$(date \%Y\%m\%d).tar.gz -C /path/to/openclaw-dashboard .恢复时只需将备份文件解压回原路径并确保文件权限正确然后重启服务即可。6. 扩展与定制化思路OpenClaw Dashboard的架构非常清晰基于纯Node.js使得定制化开发门槛较低。以下是一些可能的扩展方向1. 添加新的数据源假设你想监控另一个自定义服务的日志。可以在server.js中新增一个API端点例如GET /api/my-service-logs在这个端点里使用child_process.exec去执行tail或cat命令读取你的日志文件然后以JSON格式返回。前端再新增一个页面或面板来展示这些数据。2. 集成其他监控工具你可以修改系统健康检查的逻辑集成node_exporterPrometheus的数据或者从/proc/net/dev读取网络流量信息丰富监控面板。3. 自定义告警目前Dashboard有浏览器通知当API用量接近限制时但这是前端行为。你可以扩展后端在检测到特定条件如磁盘使用率超过90%、某个服务停止时通过调用Webhook如发送到Slack、Telegram或钉钉的方式实现服务器端告警。4. 修改UI主题或布局前端是单HTML文件CSS和JavaScript都是内联或通过少量script标签引入的。你可以直接修改index.html文件调整样式或者增加新的图表组件例如使用Chart.js的更多图表类型。5. 支持多用户与权限控制目前是单用户系统。如果你需要团队使用可以修改认证模块将credentials.json扩展为一个用户列表并增加基于角色的权限控制例如只允许管理员访问“安全”和“配置”页面。进行任何定制前建议先Fork原仓库在自己的分支上进行开发。由于项目代码风格追求极简无注释在修改时可能需要花些时间理解现有代码的数据流和函数作用。但正因为其简洁核心逻辑通常都集中在server.js的几百行代码内阅读和修改起来并不困难。