1. 项目概述一个为AI Agent团队打造的轻量级运维仪表板如果你正在使用OpenClaw框架管理一个AI Agent团队那么你很可能和我一样经历过这样的混乱时刻打开好几个终端窗口翻看一堆日志文件才能勉强搞清楚哪个Agent在线、谁在处理什么任务、刚才那个错误到底是谁抛出来的。这种状态下的团队协作效率低得让人抓狂。AgentHQ就是为了终结这种混乱而生的。它是一个极其轻量的运维仪表板核心目标就三个让你一眼看清所有Agent的实时状态、追踪每个任务的完整生命周期、以及审计团队发生的所有关键事件。整个项目只有3个页面、4个API路由没有任何花里胡哨的冗余功能追求的就是快速部署和零心智负担的使用体验。简单来说AgentHQ扮演的是你AI Agent团队的“空中交通管制塔台”。它不直接参与Agent的具体推理或任务执行而是专注于提供全局的“态势感知”。无论是个人开发者管理几个本地Agent还是小团队协作都能通过这个简洁的界面把分散的、黑盒的Agent运行状态变成结构清晰、一目了然的可视化信息。接下来我会结合自己从零部署到深度使用的全过程拆解它的设计思路、核心功能并分享那些官方文档里不会写的实操细节和避坑指南。2. 核心设计思路与架构解析2.1 为什么是“Slim”和“Zero Bloat”在AI Agent工具生态中我们见过太多功能庞大、依赖复杂的监控系统。它们往往需要引入一整套技术栈如Elasticsearch, Grafana, Prometheus配置繁琐资源占用高对于中小型Agent项目来说完全是杀鸡用牛刀。AgentHQ的设计哲学反其道而行之它精准地锚定了OpenClaw用户最迫切的几个需求点状态可视性我的Agent是活着、忙碌还是挂了任务追溯性这个任务是谁发起的流转到了哪个环节最终结果是什么事件审计性团队里刚刚发生了什么有没有异常或错误围绕这三点它砍掉了所有非核心功能。整个前端基于Next.js React Tailwind CSS构建这是目前全栈开发中效率和性能结合得最好的组合之一能保证仪表板本身响应迅速。后端逻辑极其简单大部分数据读写直接通过API路由操作数据库。这种“瘦”体现在两个方面一是功能瘦只做看板、时间线和任务板二是架构瘦默认使用SQLite无需启动任何额外的数据库服务真正做到了开箱即用。2.2 双模式存储从单机到协同的平滑路径AgentHQ在存储设计上提供了一个优雅的渐进式方案这是我认为它最实用的设计之一。SQLite模式默认这是为单用户、单机部署设计的。所有数据Agent配置、任务记录、时间线事件都存储在一个本地的SQLite文件中。它的优势是零依赖、零配置。你不需要知道数据库连接字符串不需要管理用户权限安装完立刻就能跑。所有操作都是本地文件IO速度极快隐私性也最好。适合个人开发者或项目初期的原型验证阶段。Supabase模式可选当你需要从多台设备访问同一个仪表板或者有小团队协作的需求时SQLite的局限性就出来了。Supabase模式解决了这个问题。Supabase提供了一个托管的PostgreSQL数据库和一套易用的RESTful API。切换到Supabase模式后AgentHQ的所有数据都会存储到云端。这意味着你可以在办公室的电脑上创建任务回家后用笔记本打开仪表板看到的是完全同步的状态。这种设计避免了“重写整个后端”的麻烦通过更换数据存储层就实现了从工具到协作平台的升级。注意选择哪种模式取决于你的使用场景。如果只是自己一个人在本机调试Agent强烈建议先用SQLite简单省心。如果涉及到团队内共享状态或者你希望数据能持久化保存在云端再考虑迁移到Supabase。初期用SQLite快速上手后期可以无缝迁移。2.3 核心组件交互关系整个系统的数据流非常清晰我们可以把它看作一个由“观察者”、“调度器”和“展示层”构成的三角关系Observer观察者这是一个独立的Python脚本observer.py。它的职责是定期例如每30秒扫描你的OpenClaw工作区目录下的会话文件session files。通过解析这些文件它能自动发现有哪些Agent、它们当前是活跃正在执行、在线已注册但空闲、空闲还是离线状态并自动将Agent信息、任务创建/完成事件、以及各种系统事件写入数据库无论是SQLite还是Supabase。这是实现“自动发现”和“无侵入监控”的关键。你不需要修改你的Agent代码Observer就能帮你把运行状态收集上来。Dispatcher调度器这是一个可选的高级功能仅在Supabase模式下可用。它扮演了“任务分配中心”的角色。dispatcher.py会持续轮询数据库中的“待办Todo”任务然后通过OpenClaw的网关GatewayAPI自动将这些任务分配给合适的在线Agent去执行。这实现了简单的自动化工作流比如你可以手动在仪表板上创建一个“分析日志”的任务Dispatcher会自动把它派发给某个可用的数据分析Agent。AgentHQ Web界面展示层这是用户直接交互的部分一个Next.js构建的Web应用。它通过那4个简单的API路由/api/agents,/api/tasks,/api/timeline,/api/health从数据库读取数据并以卡片、看板和时间线的形式实时展示出来。前端使用了React Query库可以轻松实现定时轮询或WebSocket连接从而获得近乎实时的数据更新体验。这种架构解耦做得很好Observer负责数据采集Dispatcher负责任务调度可选Web界面负责数据呈现。每一部分都可以独立运行或升级。3. 详细部署与配置实操指南官方提供的一键安装脚本虽然方便但理解每一步背后的原理能让你在出问题时快速定位。下面我将分步拆解手动安装的完整过程并穿插我踩过的坑和总结的技巧。3.1 基础环境准备与依赖安装首先确保你的系统满足最低要求。项目明确需要Node.js 22和Python 3.8。这里有个常见的坑Ubuntu 24.04 LTS默认的Node.js版本是18不符合要求。安装Node.js 22的正确姿势不要直接从Ubuntu默认仓库安装也不建议用snap可能遇到路径权限问题。使用NodeSource维护的仓库是最稳定可靠的方法。# 1. 清理可能存在的旧版本Node.js非必须但建议 sudo apt remove -y nodejs npm sudo apt autoremove -y # 2. 添加NodeSource仓库并安装Node.js 22 curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs # 3. 验证安装 node --version # 应输出 v22.x.x npm --versionPython环境与依赖安装项目Python依赖通过requirements.txt管理。注意安装命令中的--break-system-packages参数。这个参数在Ubuntu 24.04及更高版本上使用系统Python/usr/bin/python3时可能是必需的因为它允许pip将包安装到用户目录避免污染系统包管理。如果你使用的是虚拟环境如venv或conda则不应该使用这个参数。# 克隆项目代码 git clone https://github.com/98kiran/agenthq.git cd agenthq # 安装Python依赖 # 情况A使用系统PythonUbuntu 24.04 pip3 install -r requirements.txt --break-system-packages # 情况B使用Python虚拟环境推荐环境隔离更干净 python3 -m venv venv source venv/bin/activate pip install -r requirements.txt # 注意这里没有 --break-system-packages实操心得我强烈推荐使用Python虚拟环境。即使官方脚本用了--break-system-packages在虚拟环境中操作能完全避免与其他项目或系统工具的依赖冲突。特别是当你机器上还有其他AI项目时虚拟环境是保持清洁的必备实践。3.2 数据库初始化与项目启动安装好依赖后需要初始化数据库。这里提供了SQLite和Supabase两种选择。SQLite模式快速启动这是最简单的模式一条命令完成数据库创建和表结构初始化。bash setup.sh sqlite执行这个脚本后它会在项目根目录创建一个SQLite数据库文件通常是agenthq.db并运行schema.sql中的语句来创建agent_config、tasks、timeline_events等核心表。脚本执行成功后会在终端打印出登录URL和一个随机生成的密码务必记下这个密码。启动服务AgentHQ使用PM2作为进程管理器来保证Web服务在后台稳定运行。PM2是一个Node.js应用管理工具可以守护进程、记录日志、监控资源。# 使用PM2启动Next.js开发服务器 npx pm2 start npm --name agenthq -- start # 常用PM2命令 npx pm2 status agenthq # 查看状态 npx pm2 logs agenthq # 查看实时日志 npx pm2 stop agenthq # 停止服务 npx pm2 restart agenthq # 重启服务 npx pm2 save # 保存当前进程列表开机自启需要额外配置启动后打开终端输出的登录URL通常是http://localhost:3000使用生成的密码即可进入仪表板。Supabase模式团队协作如果你需要多设备访问或数据持久化切换到Supabase模式。创建Supabase项目前往Supabase官网免费创建一个新项目。在项目设置中找到“Project URL”和“Project API keys”。你需要的是Service Role Key具有最高权限用于后端直接操作数据库而不是公开的anon key。执行设置脚本bash setup.sh supabase your-project-url your-service-role-key这个脚本会将数据库连接配置写入环境变量或配置文件并提示你在Supabase的SQL编辑器中执行schema.sql。在Supabase中创建表登录你的Supabase控制台进入“SQL Editor”将项目根目录下的schema.sql内容复制进去并执行。这会创建所需的所有表。启动服务启动命令和SQLite模式一样。现在你的数据将存储在Supabase的PostgreSQL数据库中。避坑指南Supabase的Service Role Key权限很高务必妥善保管不要泄露到前端代码或公开仓库。建议将其设置在服务器的环境变量中而不是硬编码在配置文件里。另外首次连接时请检查Supabase项目的网络设置确保允许从你的服务器IP进行连接。3.3 Observer观察者的配置与优化Observer是AgentHQ的“眼睛”它的稳定运行决定了仪表板数据的准确性。官方推荐使用cron每30秒运行一次。但直接使用cron可能会遇到环境变量和路径问题。更可靠的Cron配置在crontab -e中不要直接写命令而是调用一个Shell脚本这样可以更好地控制执行环境。# 1. 创建一个启动脚本例如 ~/run_observer.sh #!/bin/bash cd /path/to/your/agenthq source venv/bin/activate # 如果你用了虚拟环境这行是关键 python3 observer.py /path/to/your/agenthq/observer.log 21 # 2. 给脚本执行权限 chmod x ~/run_observer.sh # 3. 配置Cron每分钟的第0秒和第30秒各执行一次 * * * * * /bin/bash /home/yourusername/run_observer.sh * * * * * sleep 30 /bin/bash /home/yourusername/run_observer.shObserver工作原理深度解析理解Observer如何工作有助于你调试数据不显示的问题。它主要做以下几件事扫描路径默认会扫描OpenClaw的默认工作区目录~/.openclaw/workspace/。请确保你的Agent确实在这个目录下运行或保存了会话文件。解析会话文件OpenClaw的会话文件通常是JSON格式包含了Agent的详细运行状态、任务历史等。Observer解析这些文件提取出Agent名称、状态、当前任务ID等信息。状态判断逻辑Observer通过检查会话文件的修改时间、内部状态字段等来判断Agent是active近期有活动、online文件存在且有效、idle长时间无活动还是offline文件不存在或异常。写入数据库将识别到的信息更新到agent_config表并将任务开始/结束等事件写入timeline_events表。常见问题排查如果仪表板上看不到你的Agent请按以下步骤检查确认Observer的cron任务正在运行pgrep -f observer.py。检查Observer日志tail -f /path/to/observer.log看是否有权限错误或导入错误。确认OpenClaw工作区路径是否正确并且你有该目录的读取权限。手动运行一次Observer脚本查看输出cd /path/to/agenthq python3 observer.py。3.4 Dispatcher调度器与网关集成Dispatcher是一个高级特性它能实现任务的自动分配。要让它工作必须满足两个条件1) 使用Supabase模式2) 能够访问OpenClaw网关。配置网关连接首先你需要从OpenClaw的配置文件中获取网关令牌Gateway Token。cat ~/.openclaw/openclaw.json | grep -A2 -B2 gateway在输出的配置中找到类似gateway: { auth: { token: your-secret-token-here } }的部分记下这个token。启动Dispatchercd ~/.openclaw/workspace/agenthq SUPABASE_URLyour-url SUPABASE_KEYyour-key GATEWAY_URLhttp://127.0.0.1:18789 GATEWAY_TOKENyour-token npx pm2 start python3 --name agenthq-dispatcher -- dispatcher.py npx pm2 save这条命令设置了必要的环境变量并用PM2启动Dispatcher进程。GATEWAY_URL通常是OpenClaw网关服务的本地地址。Dispatcher的工作流程轮询Dispatcher每隔几秒可在代码中配置查询Supabase的tasks表寻找状态为todo的任务。选择Agent它根据一定的策略目前看代码可能是简单的轮询或选择空闲Agent选择一个合适的、状态为online或idle的Agent。调用网关通过OpenClaw Gateway的API向选中的Agent发送指令执行该任务。更新状态任务被领取后Dispatcher将任务状态更新为in-progress并在时间线中记录分配事件。重要提示Dispatcher目前还是一个相对简单的原型。在生产环境中使用前你需要仔细审查dispatcher.py的代码特别是它的错误处理、任务重试机制和Agent选择策略可能需要根据你的具体业务逻辑进行增强。4. 仪表板核心功能深度使用手册成功部署并启动所有组件后打开AgentHQ仪表板你会看到三个核心页面。下面我们深入每一个页面了解其最佳使用实践。4.1 Dashboard仪表板—— 全局状态一览仪表板首页是信息密度最高的地方旨在让你快速掌握团队全景。Agent状态卡片每个Agent以一个卡片形式呈现。卡片上会显示Agent名称、当前状态通过彩色圆点标识绿色活跃、蓝色在线、黄色空闲、灰色离线、当前/最近执行的任务概要。我的使用技巧给Agent起一个清晰、具有功能指向性的名字如Data-Analyzer、Code-Reviewer比通用的Agent-1、Agent-2更能提升浏览效率。统计概览顶部通常有一些关键指标如在线Agent总数、今日完成任务数、进行中任务数等。这些数据帮你快速量化团队产出。近期活动流一个按时间倒序排列的微型时间线显示了最近发生的任务状态变更、错误信息、Agent上下线等事件。这是发现异常的第一道关口。实时性提升为了获得更好的实时体验可以配置WebSocket连接可选。在AgentHQ项目根目录创建或编辑.env.local文件添加网关的WebSocket地址和令牌。这样Agent的状态圆点就能近乎实时地更新而不需要等待前端定时轮询通常是几秒到十几秒的间隔。GATEWAY_WS_URLws://127.0.0.1:18789 GATEWAY_TOKENyour-gateway-token GATEWAY_ORIGINhttp://localhost:30004.2 Timeline时间线—— 完整审计追踪时间线页面是进行问题诊断和过程回顾的利器。它记录了所有Agent的所有事件形成一个不可篡改的审计日志。时间分组事件默认按日期如“今天”、“昨天”分组清晰明了。过滤器页面顶部的“过滤器药丸”让你可以快速筛选特定Agent的事件。当你想查看某个“问题”Agent的所有行为时这个功能非常有用。可展开详情每条事件记录都可以点击展开查看事件的完整元数据。例如一个任务失败事件展开后可能包含详细的错误堆栈信息、输入参数等这对于调试复杂任务至关重要。实操心得在团队协作中我要求所有成员在创建复杂任务时在任务描述或元数据中附带一个简单的上下文或目标。这样当在时间线中回顾时不仅能知道“发生了什么”还能知道“为什么这么做”极大提升了日志的可读性和价值。4.3 Task Board任务看板—— 可视化工作流任务看板采用了经典的Kanban看板视图将任务分为四列待办Todo、进行中In-Progress、审核Review、完成Done。这种可视化方式非常适合管理一个由多个Agent协作的、有明确阶段的工作流。拖拽管理你可以手动将任务卡片在不同列之间拖拽来改变其状态。例如将一个已完成初步分析的任务从“进行中”拖到“审核”等待另一个审核Agent处理。任务详情点击任务卡片可以查看和编辑任务的详细信息如标题、描述、负责人分配的Agent、创建时间、截止时间等。归档任务网格对于已经完成且无需再关注的任务可以将其归档。归档的任务会从主看板移除但可以在一个独立的网格视图中查看保持主看板的整洁。与Dispatcher的联动当你在“待办”列创建新任务时如果Dispatcher正在运行它会自动检测到这个新任务并尝试将其分配给一个可用的Agent。分配成功后任务会自动移动到“进行中”列并在时间线生成一条分配记录。这形成了一个简单的自动化流水线。5. 常见问题排查与性能调优实录在实际使用中你可能会遇到一些问题。以下是我遇到并解决过的一些典型情况。5.1 Agent状态显示不正确或延迟症状Agent明明在运行任务但仪表板上显示为“空闲”或“离线”或者状态更新有几分钟的延迟。排查步骤检查Observer日志这是第一步。查看observer.log确认Observer是否在正常运行是否有权限错误如无法读取OpenClaw会话文件。确认扫描路径默认Observer扫描的是OpenClaw的默认工作区。如果你的Agent运行在其他目录需要修改observer.py中的WORKSPACE_ROOT变量或者通过符号链接将你的Agent目录链接到默认工作区内。调整Observer执行频率默认的30秒间隔对于大多数场景足够。但如果你的任务非常短暂几秒内完成可能会错过状态捕捉。可以尝试将cron间隔缩短到15秒或10秒注意过于频繁可能会增加系统负载。# 每10秒运行一次Observer需要两个cron条目 * * * * * /bin/bash /path/to/run_observer.sh * * * * * sleep 10 /bin/bash /path/to/run_observer.sh * * * * * sleep 20 /bin/bash /path/to/run_observer.sh * * * * * sleep 30 /bin/bash /path/to/run_observer.sh * * * * * sleep 40 /bin/bash /path/to/run_observer.sh * * * * * sleep 50 /bin/bash /path/to/run_observer.sh检查OpenClaw会话文件格式Observer依赖于特定格式的会话文件。确保你的OpenClaw版本与AgentHQ兼容。有时OpenClaw版本更新可能导致会话文件结构变化需要同步更新Observer的解析逻辑。5.2 仪表板页面加载缓慢或卡顿症状打开AgentHQ网页时加载时间很长或者操作不流畅。排查与优化数据库性能SQLite模式如果运行了很长时间积累了海量的时间线事件数据SQLite查询可能会变慢。可以考虑为timeline_events表的时间戳字段创建索引。-- 连接到你的 agenthq.db 数据库 sqlite3 agenthq.db -- 创建索引 CREATE INDEX IF NOT EXISTS idx_timeline_created_at ON timeline_events(created_at);更激进的做法是定期归档旧数据比如只保留最近30天的事件。前端资源AgentHQ前端基于Next.js在开发模式下npm run dev热重载可能会导致初始加载稍慢。对于生产环境可以考虑构建优化版本。# 在项目目录下构建生产版本 npm run build # 使用PM2启动生产服务器如果package.json配置了start脚本 npx pm2 start npm --name agenthq-prod -- start生产构建会对代码进行压缩、打包和优化加载速度会显著提升。网络与反向代理如果你通过公网访问可能是网络延迟。考虑在服务器前部署一个Nginx反向代理并开启gzip压缩。浏览器开发者工具按F12打开开发者工具切换到“网络Network”标签页刷新页面查看是哪个请求耗时最长。如果是/api/timeline加载慢那就是数据量大的问题参考第1点优化。5.3 Dispatcher不分配任务症状在Supabase模式下创建了“待办”任务但长时间没有Agent领取。排查步骤检查Dispatcher进程状态npx pm2 status agenthq-dispatcher确保进程是“online”状态。查看Dispatcher日志npx pm2 logs agenthq-dispatcher --lines 100查看是否有明显的错误信息如连接Supabase失败、网关认证失败等。确认环境变量确保启动Dispatcher时传入的SUPABASE_URL、SUPABASE_KEY、GATEWAY_URL、GATEWAY_TOKEN全部正确无误。特别是GATEWAY_TOKEN如果OpenClaw重启令牌可能会变更。检查Agent状态Dispatcher只会将任务分配给状态为online或idle的Agent。确保至少有一个Agent在线。检查任务表结构确认Supabase中的tasks表结构完全按照schema.sql创建并且status字段的值是todo小写。手动测试网关连接用curl命令测试网关API是否可用令牌是否有效。curl -H Authorization: Bearer YOUR_GATEWAY_TOKEN http://127.0.0.1:18789/api/v1/agents如果返回Agent列表说明网关连接正常。5.4 数据迁移从SQLite到Supabase随着项目发展你可能需要从单机SQLite模式迁移到云端的Supabase模式以实现协同。安全迁移步骤备份SQLite数据首先完整备份你的agenthq.db文件。在Supabase中创建空表按照前文所述在Supabase SQL编辑器中执行schema.sql。使用数据导出导入工具这是最关键的步骤。由于表结构一致你可以使用sqlite3命令行工具和psqlPostgreSQL客户端或Supabase的导入功能。从SQLite导出CSV:sqlite3 agenthq.db .mode csv .headers on .output agents.csv SELECT * FROM agent_config; .output tasks.csv SELECT * FROM tasks; .output timeline_events.csv SELECT * FROM timeline_events; .quit向Supabase导入CSV在Supabase控制台进入“Table Editor”分别选择对应的表使用“Import data from CSV”功能上传文件。注意需要暂时禁用表的外键约束并注意id字段可能自增冲突导入时可以不导入id列让Supabase自动生成新的ID。切换AgentHQ配置运行bash setup.sh supabase ...命令将AgentHQ切换到Supabase模式。验证数据重启AgentHQ服务登录仪表板检查所有Agent、任务和历史事件是否完整显示。重要警告迁移过程中务必停止Observer和Dispatcher避免在迁移期间产生新数据导致数据不一致。最好在业务低峰期进行完整迁移。AgentHQ作为一个专注解决特定痛点的工具其简洁的设计和清晰的架构让我在管理AI Agent团队时效率倍增。它可能没有大而全的监控系统那些复杂告警和图表但它提供的“状态-任务-事件”三维视角对于理解和调试一个动态的Agent系统来说已经构成了最坚实的信息基础。我最欣赏的一点是它的可扩展性从最简单的单机SQLite部署到支持团队协作的Supabase云端模式路径非常平滑。如果你也在为多个AI Agent的协同工作而头疼花半小时部署一个AgentHQ很可能就是你一直在找的那块拼图。