Clawmander Dashboard：AI Agent一体化Web仪表盘架构与部署指南

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 + React）：Next.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或Puppeteer，Playwright提供了对Chromium、Firefox和WebKit更好的跨浏览器支持、更强大的API（如自动等待、网络拦截）以及更可靠的执行环境。其CDP（Chrome DevTools Protocol）的深度集成能力，使得实现“隐身模式”（通过传递特定CDP参数来规避一些基础的Bot检测）成为可能，这对于需要Agent模拟真实用户浏览的场景至关重要。

认证（JWT + HttpOnly Cookie）：采用无状态的JWT（JSON Web Token）作为访问令牌（Access Token），配合存储在HttpOnly Cookie中的刷新令牌（Refresh Token），这是一种兼顾安全性与开发便利性的经典模式。访问令牌有效期短，即使泄露影响范围也有限；刷新令牌通过HttpOnly Cookie传输，能有效防止XSS攻击窃取。bcrypt用于密码哈希，是当前存储密码的行业标准。

2.2 整体架构：前后端分离与数据流

项目采用了经典的前后端分离架构，但通过WebSocket和SSE紧密耦合了实时数据流。

后端服务(/backend) 承担了多重角色：

1. API网关：提供RESTful API，处理用户认证、聊天消息发送、绘图保存等业务逻辑。
2. WebSocket服务器：维护与前端（虚拟浏览器、终端）以及外部系统（如OpenClaw Gateway）的持久连接。
3. 数据收集器：通过OpenClawCollector等模块，以只读WebSocket方式监听Agent系统的事件，将其转化为仪表盘内部的SSE事件或状态更新。
4. 进程管理器：管理Playwright浏览器实例、node-pty伪终端进程的生命周期。
5. 存储层：虽然使用了简单的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从服务端获取的实时数据流。这对于一个功能明确、数据流相对线性的仪表盘来说是合理且轻量的选择。

关键数据流示例： 以聊天功能为例，其数据流完美体现了这种混合架构：

1. 用户在React前端的聊天框输入消息并点击发送。
2. 前端调用POST /api/chat/sendREST API。
3. 后端Express路由收到请求，验证JWT后，通过一个读写WebSocket连接将消息以RPC（远程过程调用）形式（例如chat.send命令）转发给远端的OpenClaw Gateway。
4. OpenClaw Gateway将消息交给AI模型处理，并开始流式返回响应。
5. 响应通过同一个WebSocket连接以事件形式（如chat.delta，chat.final）回传给Clawmander后端。
6. 后端接收到这些事件后，将其转换为SSE事件，推送给所有订阅了该聊天会话的前端客户端。
7. 前端通过useSSEHook监听这些事件，实时更新聊天界面，实现打字机效果。

这个过程将REST API的请求/响应简洁性、WebSocket的双向实时性以及SSE的服务器推送能力结合了起来。

3. 核心功能模块深度解析与实操要点

3.1 虚拟浏览器：不只是远程桌面

虚拟浏览器模块是技术含量最高的部分之一。它并非简单的VNC或远程桌面，而是针对Web自动化场景做了深度定制。

实现原理：

1. 实例化：当用户通过API创建一个浏览器实例时，后端通过Playwright启动一个Chromium进程。关键参数是--headless=new，这是较新的无头模式，能提供更完整的浏览器环境。
2. 屏幕流传输：Playwright通过CDP启动页面的“截屏”功能，以设定的帧率（例如每秒10帧）捕获视口区域的JPEG图像。
3. 流式传输：每一帧JPEG被后端通过WebSocket以二进制数据形式直接推送到前端。
4. 前端渲染：前端接收到二进制数据后，将其转换为Blob，再生成Object URL，设置为一个<img>标签的src。通过连续快速地更新src，就形成了流畅的视频流。这种方式比传输RGB像素数据或使用WebRTC更轻量，更适合控制带宽。
5. 输入转发：前端的<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等命令，体验接近本地终端。

实现原理：

1. 伪终端：后端使用node-pty库创建一个伪终端（pseudo-terminal）。PTY在Unix-like系统中模拟了硬件终端的行为，可以运行交互式Shell（如bash, zsh）。
2. 进程绑定：这个PTY与一个实际的Shell进程（如/bin/bash）绑定。用户在Web终端里输入字符，实际上是通过WebSocket发送到后端，再写入这个PTY的输入流。
3. 输出捕获：Shell进程的输出（包括命令回显、程序输出、控制字符等）会从PTY的输出流中被读取，然后通过WebSocket发送回前端。
4. 前端渲染：前端使用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 API（window.SpeechRecognition）。前端提供一个麦克风按钮，点击后启动语音识别。识别到的文本实时填入聊天输入框。这里的关键是优雅降级：在不支持该API的浏览器中，麦克风按钮应该被隐藏。同时，需要处理识别过程中的中间结果（interim results）以提供实时反馈，以及处理识别错误和超时。
• 语音输出：项目提到了一个“Chatterbox TTS服务器”。这通常是一个独立的、提供OpenAI兼容TTS API的服务。流程是：
  1. 当用户开启TTS开关，AI回复的文本内容会被前端或后端发送到POST /api/voice/tts。
  2. 后端作为代理，将请求转发给配置好的TTS服务（Chatterbox）。
  3. TTS服务返回音频流（如MP3数据）。
  4. 后端将音频流返回给前端，前端使用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配置项解析：

• PORT=3001: 后端服务端口。
• AUTH_SECRET: 用于签署JWT令牌的密钥，务必使用强密码生成器生成。
• AUTH_REQUIRE_AUTH=true: 是否开启认证。在测试初期可以设为false跳过登录。
• TEST_MODE=true: 测试模式，会加载示例Agent和数据，方便首次体验。
• OPENCLAW_WS_URL=ws://127.0.0.1:18789: 指向你的OpenClaw Gateway的WebSocket地址。
• CHATTERBOX_TTS_URL=http://your-tts-server:port/v1/audio/speech: 你的TTS服务地址。

启动方式：

1. 开发模式（前后端分离启动）：

   # 终端1：启动后端 cd backend npm run dev # 或 node server.js，取决于package.json脚本 # 终端2：启动前端开发服务器 cd frontend npm run dev

   访问http://localhost:3000。前端开发服务器会代理API请求到后端3001端口。

2. 生产模式（使用构建版本）：

   # 构建前端静态文件 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] Description=Clawmander Backend Service After=network.target [Service] Type=simple WorkingDirectory=/home/yourname/clawmander/backend ExecStart=/usr/bin/node server.js Environment=NODE_ENV=production EnvironmentFile=/home/yourname/clawmander/backend/.env Restart=on-failure RestartSec=10 [Install] WantedBy=default.target

EnvironmentFile指令确保了服务能读取到你在.env文件中的配置。

实操心得：使用systemd --user管理服务非常方便，但要注意用户会话的持久化。如果通过SSH登录后启动服务，登出后服务可能会被终止。解决方案是使用loginctl enable-linger $USER启用用户linger，或者使用系统级的systemd服务（需要sudo权限）。

4.3 与OpenClaw Agent的集成配置

Clawmander的核心价值之一是作为OpenClaw Agent的“仪表盘”。要让数据动起来，你需要一个正在运行的OpenClaw实例。

1. 确保OpenClaw Gateway运行：OpenClaw项目通常会有一个Gateway服务，监听WebSocket端口（默认可能是18789）。确保它正在运行。
2. 配置Clawmander连接：在Clawmander后端的.env文件中，设置OPENCLAW_WS_URL指向正确的地址，例如ws://localhost:18789。
3. 理解连接模式：Clawmander后端会以“收集器”身份连接OpenClaw Gateway。这个连接通常是只读的，用于接收Agent的心跳、任务状态更新、聊天事件等。而像发送聊天消息、控制Agent行动等“写入”操作，则是通过Clawmander后端自身的API，再由其通过另一个连接（或同一连接的不同通道）转发给OpenClaw。
4. 验证连接：启动Clawmander后，查看后端日志。你应该能看到成功连接到OpenClaw Gateway的消息。在前端，如果TEST_MODE=false且连接正常，Agent状态看板（Kanban）应该会开始显示来自你真实Agent的数据。

5. 常见问题排查与性能调优

5.1 安装与启动问题

5.2 功能相关问题

5.3 性能与安全调优建议

1. 资源限制：

   • 浏览器实例：在BrowserManager服务中，设置一个最大实例数的限制（例如，每个用户最多3个），防止资源耗尽。
   • 终端会话：同样限制每个用户的终端会话数，并设置空闲超时自动销毁。
   • 内存缓存：对于频繁读取的配置、绘图数据，使用内存缓存（如Node.js的Map或LRU-Cache）并设置合理的TTL和最大条目数。

2. 安全加固：

   • HTTPS：在生产环境，务必使用Nginx或Caddy等反向代理配置HTTPS，保护登录凭证和传输数据。
   • 环境变量：切勿将.env文件提交到Git。使用AUTH_SECRET等强密码。
   • 输入验证与消毒：对所有API输入进行严格的验证和消毒，特别是聊天消息、上传文件、绘图数据等用户可控输入，防止注入攻击。
   • 终端沙箱：强烈建议为Web终端创建一个受限的执行环境。例如，使用chroot、容器（Docker）或至少是一个具有严格权限的专用系统用户来运行PTY进程。

3. 可扩展性思考：

   • 当前架构为单用户设计，状态（如浏览器实例、终端会话）多保存在后端进程内存中。若要支持多用户，需要引入分布式状态存储，如Redis，来管理这些会话状态。
   • JSON文件存储适合轻量级数据。如果数据量增长，可以考虑迁移到SQLite（仍保持单文件简单性）或PostgreSQL。

这个项目是一个功能密集型的典范，它将多个复杂的子系统（浏览器自动化、终端模拟、实时通信、AI集成）优雅地整合到了一个连贯的产品中。部署和使用它，就像为自己搭建了一个高度定制化的数字工作间。无论是用于监控自动化Agent，还是单纯作为一个集成的个人仪表盘，它都提供了极高的自由度和可玩性。在实际使用中，从简单的状态监控开始，逐步探索虚拟浏览器和绘图板与AI的联动，你会逐渐发现这种深度集成带来的效率提升和新的可能性。