1. 项目概述一个为AI Agent打造的“驾驶舱”如果你正在运行自己的AI Agent比如基于OpenClaw框架的智能体并且厌倦了在终端、浏览器、日志文件和聊天界面之间来回切换那么这个项目可能就是为你量身定做的。Clawmander Dashboard你可以把它理解为一个为AI Agent、个人工作和财务数据打造的“一体化驾驶舱”或“指挥中心”。它的核心目标很简单把所有分散的信息和操作界面聚合到一个统一的、实时的Web仪表盘中。想象一下你有一个或多个AI Agent在后台不知疲倦地工作它们可能在自动浏览网页、处理文档、执行脚本任务或者帮你监控财务状况。传统的做法是你需要SSH到服务器看日志用Playwright脚本控制浏览器在另一个聊天窗口和Agent对话再打开一个终端执行命令。Clawmander Dashboard 把这些都整合到了一个Next.js构建的现代化Web界面里。你可以在一个标签页里看到所有Agent的实时状态和任务进度在另一个标签页里通过一个虚拟浏览器直接观察或控制Agent正在浏览的网页旁边还能开一个完整的Bash终端同时还能在一个类似Discord的聊天界面里和Agent们流畅沟通甚至用语音和它们对话。这个项目最初是为了深度集成OpenClaw Agent框架而设计的但它提供的许多组件如虚拟浏览器、终端、绘图板是通用的理论上可以适配其他能通过WebSocket或API提供数据的Agent系统。它的设计哲学是“为单用户部署优化”这意味着它更侧重于为开发者或高级用户提供一个功能强大、集成度高的个人工具而不是一个面向多租户的企业级SaaS平台。2. 核心架构与设计思路拆解2.1 为什么选择这样的技术栈Clawmander的技术选型清晰地反映了一个现代、实时、全栈Web应用的需求。我们来拆解一下每个选择背后的考量后端Node.js Express选择Node.js的核心原因在于其非阻塞I/O模型非常适合处理大量并发连接这正是实时仪表盘WebSocket、SSE的典型场景。Express作为最成熟、生态最丰富的Node.js Web框架能快速搭建REST API中间件机制也便于集成认证、日志等功能。对于需要与系统进程如终端深度交互的部分Node.js的原生能力如child_process模块和丰富的NPM包如node-pty提供了完美支持。前端Next.js ReactNext.js的选择非常明智。首先它基于React拥有庞大的生态系统和开发者社区。其次Next.js内置的App Router、API Routes、服务端渲染SSR和静态生成SSG能力使得构建一个既有丰富交互如虚拟浏览器画布又需要良好SEO和快速首屏加载的仪表盘变得非常高效。其文件系统路由约定也使得项目结构清晰。Tailwind CSS的采用则保证了UI开发的快速和一致性避免了传统CSS的维护噩梦。实时通信WebSocket SSE这是仪表盘“实时”特性的生命线。项目采用了混合模式WebSocket用于双向、低延迟、高频率的数据流。例如虚拟浏览器的JPEG帧流传输、终端输入的实时回显、聊天消息的发送这些都需要全双工通信。Server-Sent Events用于服务器向客户端的单向事件推送。例如Agent状态更新、新任务通知、Feed流新条目。SSE比WebSocket更轻量在只需要服务器推送的场景下是更标准、更简单的选择。这种区分体现了架构上的清晰思考。浏览器自动化Playwright相比Selenium或PuppeteerPlaywright提供了对Chromium、Firefox和WebKit更好的跨浏览器支持、更强大的API如自动等待、网络拦截以及更可靠的执行环境。其CDPChrome DevTools Protocol的深度集成能力使得实现“隐身模式”通过传递特定CDP参数来规避一些基础的Bot检测成为可能这对于需要Agent模拟真实用户浏览的场景至关重要。认证JWT HttpOnly Cookie采用无状态的JWTJSON Web Token作为访问令牌Access Token配合存储在HttpOnly Cookie中的刷新令牌Refresh Token这是一种兼顾安全性与开发便利性的经典模式。访问令牌有效期短即使泄露影响范围也有限刷新令牌通过HttpOnly Cookie传输能有效防止XSS攻击窃取。bcrypt用于密码哈希是当前存储密码的行业标准。2.2 整体架构前后端分离与数据流项目采用了经典的前后端分离架构但通过WebSocket和SSE紧密耦合了实时数据流。后端服务(/backend) 承担了多重角色API网关提供RESTful API处理用户认证、聊天消息发送、绘图保存等业务逻辑。WebSocket服务器维护与前端虚拟浏览器、终端以及外部系统如OpenClaw Gateway的持久连接。数据收集器通过OpenClawCollector等模块以只读WebSocket方式监听Agent系统的事件将其转化为仪表盘内部的SSE事件或状态更新。进程管理器管理Playwright浏览器实例、node-pty伪终端进程的生命周期。存储层虽然使用了简单的JSON文件存储适用于单用户、配置和绘图等非高频数据但通过内存缓存来提升读取性能结构清晰。前端应用(/frontend) 则是一个功能模块化的Next.js应用页面每个核心功能/chat,/browser,/terminal,/draw,/voice对应一个路由页面。组件库功能被拆分为高内聚的React组件如BrowserPanel,TerminalView便于维护和复用。自定义Hooks这是React逻辑复用的精髓。useSSE、useBrowser、useChatState、useSpeechRecognition等Hook封装了复杂的副作用如订阅事件、管理WebSocket连接、语音识别状态使页面组件保持简洁。状态管理从描述看项目似乎没有引入Redux或Zustand等重型状态库而是倾向于结合React Context、组件自身状态和通过Hook从服务端获取的实时数据流。这对于一个功能明确、数据流相对线性的仪表盘来说是合理且轻量的选择。关键数据流示例 以聊天功能为例其数据流完美体现了这种混合架构用户在React前端的聊天框输入消息并点击发送。前端调用POST /api/chat/sendREST API。后端Express路由收到请求验证JWT后通过一个读写WebSocket连接将消息以RPC远程过程调用形式例如chat.send命令转发给远端的OpenClaw Gateway。OpenClaw Gateway将消息交给AI模型处理并开始流式返回响应。响应通过同一个WebSocket连接以事件形式如chat.deltachat.final回传给Clawmander后端。后端接收到这些事件后将其转换为SSE事件推送给所有订阅了该聊天会话的前端客户端。前端通过useSSEHook监听这些事件实时更新聊天界面实现打字机效果。这个过程将REST API的请求/响应简洁性、WebSocket的双向实时性以及SSE的服务器推送能力结合了起来。3. 核心功能模块深度解析与实操要点3.1 虚拟浏览器不只是远程桌面虚拟浏览器模块是技术含量最高的部分之一。它并非简单的VNC或远程桌面而是针对Web自动化场景做了深度定制。实现原理实例化当用户通过API创建一个浏览器实例时后端通过Playwright启动一个Chromium进程。关键参数是--headlessnew这是较新的无头模式能提供更完整的浏览器环境。屏幕流传输Playwright通过CDP启动页面的“截屏”功能以设定的帧率例如每秒10帧捕获视口区域的JPEG图像。流式传输每一帧JPEG被后端通过WebSocket以二进制数据形式直接推送到前端。前端渲染前端接收到二进制数据后将其转换为Blob再生成Object URL设置为一个img标签的src。通过连续快速地更新src就形成了流畅的视频流。这种方式比传输RGB像素数据或使用WebRTC更轻量更适合控制带宽。输入转发前端的canvas或img元素上捕获用户的鼠标点击、滚动、键盘事件通过同一个WebSocket发送到后端后端再通过Playwright的API如page.mouse.click(x, y),page.keyboard.type(text)在真实的浏览器页面上执行相应操作。高级特性与实操要点多标签页与弹窗支持这是超越简单远程控制的亮点。实现原理是后端需要监听页面的popup事件。当目标页面打开新窗口window.open或点击target_blank链接时Playwright会创建一个新的Page对象。Clawmander的后端会为这个新页面创建一个逻辑上的“标签页”并将其纳入同一个浏览器实例的管理。前端则更新标签栏UI。这要求前后端共同维护一套标签页的状态同步逻辑。隐身模式通过向Playwright启动的浏览器上下文传递额外的CDP参数可以修改navigator.webdriver属性、屏蔽某些自动化特征指纹等以绕过一些基础的反爬虫检测。但这并非万能面对高级风控系统仍需更复杂的策略。用户/Agent控制模式这是一个精妙的设计。前端有一个“控制权”状态。当处于“用户控制”模式时所有前端输入事件都会转发给浏览器。当切换到“Agent控制”模式时前端会禁用输入并可能显示一个“Agent正在操作”的横幅此时浏览器由后端接收来自AI Agent的指令通过另一个接口来驱动。这实现了人机协同观察与操作。性能考量JPEG的压缩质量和帧率是权衡流畅度与带宽的关键。在局域网内可以提高帧率和质量在公网访问时则需要降低。此外前端可以采用requestAnimationFrame来协调图像更新避免不必要的渲染。实操心得在部署虚拟浏览器时最大的挑战是资源管理和稳定性。每个浏览器实例都会消耗可观的内存和CPU。务必在代码中实现完善的实例清理逻辑超时销毁、异常退出重启。另外Playwright需要下载特定版本的浏览器二进制文件在Docker或CI环境中需要妥善处理。3.2 集成终端在浏览器中运行真正的Shell这个功能让用户可以直接在Web页面里执行ls,cd,vim等命令体验接近本地终端。实现原理伪终端后端使用node-pty库创建一个伪终端pseudo-terminal。PTY在Unix-like系统中模拟了硬件终端的行为可以运行交互式Shell如bash, zsh。进程绑定这个PTY与一个实际的Shell进程如/bin/bash绑定。用户在Web终端里输入字符实际上是通过WebSocket发送到后端再写入这个PTY的输入流。输出捕获Shell进程的输出包括命令回显、程序输出、控制字符等会从PTY的输出流中被读取然后通过WebSocket发送回前端。前端渲染前端使用xterm.js这个强大的终端模拟器库。它负责将后端传回的字符流包括ANSI转义序列用于颜色、光标位置等正确地渲染成终端文本界面。同时它也将用户的键盘输入捕获并发送给后端。关键细节会话持久化WebSocket连接对应一个持久的PTY进程。即使前端页面刷新只要后端没有重启理想情况下应该尝试重连并恢复之前的终端会话。这需要前后端共同维护会话ID和重连逻辑。窗口大小同步当用户调整浏览器中终端组件的大小时前端需要将新的列数和行数通过WebSocket通知后端后端再调用pty.resize(cols, rows)来调整PTY的大小这样运行在其中的top、vim等全屏程序才能正确显示。安全性这是重中之重。在Web中暴露一个真实的Shell是极其危险的。Clawmander通过JWT认证来保护/ws/terminalWebSocket端点确保只有授权用户能访问。但更进一步应该考虑在PTY中启动一个受限制的Shell如rbash或者通过环境变量和配置限制用户的家目录和可执行命令范围。注意事项node-pty的安装在不同操作系统上可能遇到原生模块编译问题。在Linux服务器上部署通常最顺利。在Windows上需要安装Visual Studio Build Tools和Python。在Docker中构建时需要确保镜像包含必要的编译工具链。3.3 聊天界面与AI Agent的协作中心聊天界面是与AI Agent交互的核心其设计借鉴了Discord/Matrix等现代聊天工具。核心交互解析流式响应与Markdown渲染当AI模型生成回复时Clawmander接收的是token流。前端需要逐步追加这些token到一个缓冲区并实时将其作为Markdown解析渲染。这涉及到复杂的字符串拼接、防抖debounce渲染以平衡性能与实时性以及安全地渲染用户提供的Markdown防止XSS。通常使用像marked或remark这类库并配合语法高亮插件来处理代码块。Slash命令像/model,/reset这样的命令前端需要在输入时进行识别和提示自动完成。当发送出去后后端并不是简单地将/model gpt-4这样的文本传给AI而是将其解析为一个特殊的指令可能直接通过WebSocket调用OpenClaw Gateway的特定RPC方法来切换模型然后返回一个系统消息到聊天界面。审批流程当AI Agent尝试执行某些需要用户确认的操作如发送邮件、支付订单时它会发送一个“审批请求”。后端会将其转换为一个特殊的消息事件前端则渲染出带有“批准”/“拒绝”按钮的横幅。用户操作后前端调用审批决议API后端再将结果通知给Agent。这实现了人机交互中的关键安全拦截点。图片附件支持拖拽或点击上传图片。前端将图片转换为Base64或FormData通过/api/chat/upload接口上传。后端存储文件或仅保存路径并将图片的引用如URL或文件ID随消息内容一起发送给AI模型。模型如GPT-4V可以“看到”这张图片并基于其内容进行回复。状态管理挑战聊天界面需要管理多个并发的会话Session、每个会话的消息历史、正在进行的流式响应、上传状态、审批状态等。使用React Hooks如useReducer,useContext或一个轻量级状态库来管理这些复杂状态会使得代码更清晰。3.4 语音集成让交互更自然语音功能分为语音输入和语音输出极大地提升了交互的自然度。语音输入基于浏览器的Web Speech APIwindow.SpeechRecognition。前端提供一个麦克风按钮点击后启动语音识别。识别到的文本实时填入聊天输入框。这里的关键是优雅降级在不支持该API的浏览器中麦克风按钮应该被隐藏。同时需要处理识别过程中的中间结果interim results以提供实时反馈以及处理识别错误和超时。语音输出项目提到了一个“Chatterbox TTS服务器”。这通常是一个独立的、提供OpenAI兼容TTS API的服务。流程是当用户开启TTS开关AI回复的文本内容会被前端或后端发送到POST /api/voice/tts。后端作为代理将请求转发给配置好的TTS服务Chatterbox。TTS服务返回音频流如MP3数据。后端将音频流返回给前端前端使用HTMLAudioElement进行播放。专用语音页面(/voice)这是一个为“免提”对话设计的全屏界面。它可能包含一个大的语音状态显示、一个悬浮动作按钮用于开关麦克风并实现一个“自动聆听”循环播放完AI的语音回复后自动开启麦克风等待用户下一句指令形成一个连续的对话流。这需要精细地管理音频播放状态和语音识别状态的切换避免两者冲突比如在播放音频时误触发识别。3.5 绘图板与Agent可访问性集成Excalidraw是一个提升创造力和协作性的妙招。Excalidraw是一个开源的虚拟白板非常适合绘制草图、图表、架构图。集成方式通常是将Excalidraw作为一个React组件引入。Clawmander需要管理多个绘图文件因此有一个绘图列表侧边栏。每个绘图的状态图形、文字、箭头等以Excalidraw的序列化格式一个大的JSON对象保存。自动保存与同步利用Excalidraw的onChange事件前端在用户每次操作后使用防抖如1秒将当前的绘图数据通过PATCH /api/drawings/:idAPI保存到后端。同时后端可以通过SSE广播drawing.updated事件如果同一个绘图在多个浏览器标签页打开可以实现近乎实时的同步。Agent-API这是最有趣的部分。后端暴露了POST /api/drawings和PATCH /api/drawings/:id等REST API。这意味着你的AI Agent可以通过代码调用这些API来创建或修改绘图例如你可以给Agent一个指令“画一个描述微服务架构的图表”。Agent可以编写代码调用这些API生成或调整Excalidraw的数据从而在仪表盘上自动生成一幅图。这为AI的“具身”表达和可视化思考提供了强大的工具。4. 部署与运维实操指南4.1 环境准备与启动假设你已经在本地或一台云服务器如Ubuntu 22.04上准备好了Node.js环境v18和Git。# 1. 克隆代码 git clone https://github.com/scottgl9/clawmander.git cd clawmander # 2. 安装后端依赖 cd backend npm install # 或使用 pnpm/yarn # 3. 安装前端依赖 cd ../frontend npm install # 4. 配置环境变量 cd ../backend cp .env.example .env # 使用你喜欢的编辑器编辑 .env 文件 # 至少需要设置AUTH_SECRET一个强随机字符串用于JWT签名 # 如果连接OpenClaw需要设置 OPENCLAW_WS_URL 等 nano .env关键的.env配置项解析PORT3001: 后端服务端口。AUTH_SECRET: 用于签署JWT令牌的密钥务必使用强密码生成器生成。AUTH_REQUIRE_AUTHtrue: 是否开启认证。在测试初期可以设为false跳过登录。TEST_MODEtrue: 测试模式会加载示例Agent和数据方便首次体验。OPENCLAW_WS_URLws://127.0.0.1:18789: 指向你的OpenClaw Gateway的WebSocket地址。CHATTERBOX_TTS_URLhttp://your-tts-server:port/v1/audio/speech: 你的TTS服务地址。启动方式开发模式前后端分离启动# 终端1启动后端 cd backend npm run dev # 或 node server.js取决于package.json脚本 # 终端2启动前端开发服务器 cd frontend npm run dev访问http://localhost:3000。前端开发服务器会代理API请求到后端3001端口。生产模式使用构建版本# 构建前端静态文件 cd frontend npm run build # 启动后端后端服务静态文件如果配置了的话或者用Nginx托管前端 cd ../backend npm start生产环境更推荐使用PM2或systemd来管理进程保证服务在后台稳定运行。4.2 使用Systemd进行服务管理Linux项目提供的service.sh脚本极大地简化了在Linux服务器上以服务形式运行的流程。# 进入项目根目录 cd /path/to/clawmander # 1. 安装服务创建systemd用户单元文件 ./service.sh install # 这个操作会在 ~/.config/systemd/user/ 下创建两个服务文件 # clawmander-backend.service # clawmander-frontend.service # 2. 启动服务 ./service.sh start # 3. 查看服务状态 ./service.sh status # 4. 查看日志 ./service.sh logs # 或使用 journalctl --user -u clawmander-* # 5. 设置开机自启针对当前用户 ./service.sh enable-boot服务文件解析 以clawmander-backend.service为例其核心是定义了工作目录、启动命令和环境变量[Unit] DescriptionClawmander Backend Service Afternetwork.target [Service] Typesimple WorkingDirectory/home/yourname/clawmander/backend ExecStart/usr/bin/node server.js EnvironmentNODE_ENVproduction EnvironmentFile/home/yourname/clawmander/backend/.env Restarton-failure RestartSec10 [Install] WantedBydefault.targetEnvironmentFile指令确保了服务能读取到你在.env文件中的配置。实操心得使用systemd --user管理服务非常方便但要注意用户会话的持久化。如果通过SSH登录后启动服务登出后服务可能会被终止。解决方案是使用loginctl enable-linger $USER启用用户linger或者使用系统级的systemd服务需要sudo权限。4.3 与OpenClaw Agent的集成配置Clawmander的核心价值之一是作为OpenClaw Agent的“仪表盘”。要让数据动起来你需要一个正在运行的OpenClaw实例。确保OpenClaw Gateway运行OpenClaw项目通常会有一个Gateway服务监听WebSocket端口默认可能是18789。确保它正在运行。配置Clawmander连接在Clawmander后端的.env文件中设置OPENCLAW_WS_URL指向正确的地址例如ws://localhost:18789。理解连接模式Clawmander后端会以“收集器”身份连接OpenClaw Gateway。这个连接通常是只读的用于接收Agent的心跳、任务状态更新、聊天事件等。而像发送聊天消息、控制Agent行动等“写入”操作则是通过Clawmander后端自身的API再由其通过另一个连接或同一连接的不同通道转发给OpenClaw。验证连接启动Clawmander后查看后端日志。你应该能看到成功连接到OpenClaw Gateway的消息。在前端如果TEST_MODEfalse且连接正常Agent状态看板Kanban应该会开始显示来自你真实Agent的数据。5. 常见问题排查与性能调优5.1 安装与启动问题问题现象可能原因解决方案npm install失败特别是node-pty或playwright报错。缺少系统级编译工具或依赖库。Linux (Ubuntu/Debian):sudo apt-get install -y python3 make g build-essential。macOS: 安装Xcode Command Line Tools:xcode-select --install。Windows: 安装Visual Studio Build Tools并勾选“C桌面开发”工作负载。对于Playwright运行npx playwright install来下载浏览器。前端访问localhost:3000报错“连接失败”或空白页。后端服务未启动或端口被占用或CORS问题。1. 确认后端服务已在3001端口运行 (curl http://localhost:3001/api/agents/status)。2. 检查前端.env.local或开发服务器代理配置是否正确指向后端地址。3. 开发模式下前端服务器通常配置了代理检查frontend/next.config.js。登录成功但无法获取数据接口返回401。JWT令牌失效或未正确传递。1. 检查浏览器开发者工具的“网络”选项卡确认请求头中是否包含Authorization: Bearer token。2. 令牌可能已过期尝试重新登录。3. 检查后端.env中的AUTH_SECRET是否在前后端重启后保持一致。虚拟浏览器无法启动日志显示Playwright错误。Playwright的Chromium未安装或版本不匹配。1. 在backend目录下运行npx playwright install chromium。2. 检查服务器是否有图形界面或虚拟帧缓冲区。对于无头服务器可能需要安装xvfb并以前缀xvfb-run启动Node.js服务或者使用Playwright的headless: ‘new’模式项目已采用。5.2 功能相关问题问题现象可能原因解决方案虚拟浏览器黑屏或卡住。WebSocket连接中断或Playwright浏览器实例崩溃。1. 查看浏览器开发者工具“网络”中的WebSocket连接状态。2. 查看后端日志确认浏览器实例是否报错退出。3. 服务器内存不足可能导致浏览器崩溃考虑增加内存或限制同时运行的浏览器实例数。终端输入无响应或显示乱码。PTY进程僵死或WebSocket传输编码问题。1. 尝试在仪表盘中关闭并重新打开终端标签页。2. 检查后端node-pty进程是否正常。可能需要实现心跳和自动重启机制。3. 确保前后端传输的数据是UTF-8编码。聊天消息发送后无回复。与OpenClaw Gateway的连接断开或Agent未响应。1. 检查后端日志中关于OpenClaw WebSocket连接的状态。2. 确认OpenClaw Gateway服务正常运行且Agent配置正确。3. 在测试模式下检查示例Agent是否正常工作。语音TTS没有声音。TTS服务未配置或不可达。1. 检查后端.env中CHATTERBOX_TTS_URL配置是否正确。2. 尝试直接curl该TTS API看是否能返回音频文件。3. 检查前端浏览器控制台是否有音频播放相关的错误如CORS。可能需要配置TTS服务端允许跨域。5.3 性能与安全调优建议资源限制浏览器实例在BrowserManager服务中设置一个最大实例数的限制例如每个用户最多3个防止资源耗尽。终端会话同样限制每个用户的终端会话数并设置空闲超时自动销毁。内存缓存对于频繁读取的配置、绘图数据使用内存缓存如Node.js的Map或LRU-Cache并设置合理的TTL和最大条目数。安全加固HTTPS在生产环境务必使用Nginx或Caddy等反向代理配置HTTPS保护登录凭证和传输数据。环境变量切勿将.env文件提交到Git。使用AUTH_SECRET等强密码。输入验证与消毒对所有API输入进行严格的验证和消毒特别是聊天消息、上传文件、绘图数据等用户可控输入防止注入攻击。终端沙箱强烈建议为Web终端创建一个受限的执行环境。例如使用chroot、容器Docker或至少是一个具有严格权限的专用系统用户来运行PTY进程。可扩展性思考当前架构为单用户设计状态如浏览器实例、终端会话多保存在后端进程内存中。若要支持多用户需要引入分布式状态存储如Redis来管理这些会话状态。JSON文件存储适合轻量级数据。如果数据量增长可以考虑迁移到SQLite仍保持单文件简单性或PostgreSQL。这个项目是一个功能密集型的典范它将多个复杂的子系统浏览器自动化、终端模拟、实时通信、AI集成优雅地整合到了一个连贯的产品中。部署和使用它就像为自己搭建了一个高度定制化的数字工作间。无论是用于监控自动化Agent还是单纯作为一个集成的个人仪表盘它都提供了极高的自由度和可玩性。在实际使用中从简单的状态监控开始逐步探索虚拟浏览器和绘图板与AI的联动你会逐渐发现这种深度集成带来的效率提升和新的可能性。