AI Agent运维实战：轻量级仪表板AgentHQ部署与核心功能解析

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用户最迫切的几个需求点：

1. 状态可视性：我的Agent是活着、忙碌还是挂了？
2. 任务追溯性：这个任务是谁发起的？流转到了哪个环节？最终结果是什么？
3. 事件审计性：团队里刚刚发生了什么？有没有异常或错误？

围绕这三点，它砍掉了所有非核心功能。整个前端基于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 核心组件交互关系

整个系统的数据流非常清晰，我们可以把它看作一个由“观察者”、“调度器”和“展示层”构成的三角关系：

1. Observer（观察者）：这是一个独立的Python脚本（observer.py）。它的职责是定期（例如每30秒）扫描你的OpenClaw工作区目录下的会话文件（session files）。通过解析这些文件，它能自动发现有哪些Agent、它们当前是活跃（正在执行）、在线（已注册但空闲）、空闲还是离线状态，并自动将Agent信息、任务创建/完成事件、以及各种系统事件写入数据库（无论是SQLite还是Supabase）。这是实现“自动发现”和“无侵入监控”的关键。你不需要修改你的Agent代码，Observer就能帮你把运行状态收集上来。

2. Dispatcher（调度器）：这是一个可选的高级功能，仅在Supabase模式下可用。它扮演了“任务分配中心”的角色。dispatcher.py会持续轮询数据库中的“待办（Todo）”任务，然后通过OpenClaw的网关（Gateway）API，自动将这些任务分配给合适的在线Agent去执行。这实现了简单的自动化工作流，比如你可以手动在仪表板上创建一个“分析日志”的任务，Dispatcher会自动把它派发给某个可用的数据分析Agent。

3. 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 --version

Python环境与依赖安装：项目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：使用系统Python（Ubuntu 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模式。

1. 创建Supabase项目：前往Supabase官网，免费创建一个新项目。在项目设置中，找到“Project URL”和“Project API keys”。你需要的是Service Role Key（具有最高权限，用于后端直接操作数据库），而不是公开的anon key。

2. 执行设置脚本：

bash setup.sh supabase <your-project-url> <your-service-role-key>

这个脚本会将数据库连接配置写入环境变量或配置文件，并提示你在Supabase的SQL编辑器中执行schema.sql。

3. 在Supabase中创建表：登录你的Supabase控制台，进入“SQL Editor”，将项目根目录下的schema.sql内容复制进去并执行。这会创建所需的所有表。

4. 启动服务：启动命令和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 2>&1 # 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.sh

Observer工作原理深度解析：理解Observer如何工作，有助于你调试数据不显示的问题。它主要做以下几件事：

• 扫描路径：默认会扫描OpenClaw的默认工作区目录（~/.openclaw/workspace/）。请确保你的Agent确实在这个目录下运行或保存了会话文件。
• 解析会话文件：OpenClaw的会话文件（通常是JSON格式）包含了Agent的详细运行状态、任务历史等。Observer解析这些文件，提取出Agent名称、状态、当前任务ID等信息。
• 状态判断逻辑：Observer通过检查会话文件的修改时间、内部状态字段等来判断Agent是active（近期有活动）、online（文件存在且有效）、idle（长时间无活动）还是offline（文件不存在或异常）。
• 写入数据库：将识别到的信息更新到agent_config表，并将任务开始/结束等事件写入timeline_events表。

常见问题排查：如果仪表板上看不到你的Agent，请按以下步骤检查：

1. 确认Observer的cron任务正在运行：pgrep -f observer.py。
2. 检查Observer日志：tail -f /path/to/observer.log，看是否有权限错误或导入错误。
3. 确认OpenClaw工作区路径是否正确，并且你有该目录的读取权限。
4. 手动运行一次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。

启动Dispatcher：

cd ~/.openclaw/workspace/agenthq SUPABASE_URL=<your-url> SUPABASE_KEY=<your-key> GATEWAY_URL=http://127.0.0.1:18789 GATEWAY_TOKEN=<your-token> npx pm2 start python3 --name agenthq-dispatcher -- dispatcher.py npx pm2 save

这条命令设置了必要的环境变量，并用PM2启动Dispatcher进程。GATEWAY_URL通常是OpenClaw网关服务的本地地址。

Dispatcher的工作流程：

1. 轮询：Dispatcher每隔几秒（可在代码中配置）查询Supabase的tasks表，寻找状态为todo的任务。
2. 选择Agent：它根据一定的策略（目前看代码可能是简单的轮询或选择空闲Agent）选择一个合适的、状态为online或idle的Agent。
3. 调用网关：通过OpenClaw Gateway的API，向选中的Agent发送指令，执行该任务。
4. 更新状态：任务被领取后，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_URL=ws://127.0.0.1:18789 GATEWAY_TOKEN=<your-gateway-token> GATEWAY_ORIGIN=http://localhost:3000

4.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明明在运行任务，但仪表板上显示为“空闲”或“离线”；或者状态更新有几分钟的延迟。

排查步骤：

1. 检查Observer日志：这是第一步。查看observer.log，确认Observer是否在正常运行，是否有权限错误（如无法读取OpenClaw会话文件）。
2. 确认扫描路径：默认Observer扫描的是OpenClaw的默认工作区。如果你的Agent运行在其他目录，需要修改observer.py中的WORKSPACE_ROOT变量，或者通过符号链接将你的Agent目录链接到默认工作区内。
3. 调整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

4. 检查OpenClaw会话文件格式：Observer依赖于特定格式的会话文件。确保你的OpenClaw版本与AgentHQ兼容。有时OpenClaw版本更新可能导致会话文件结构变化，需要同步更新Observer的解析逻辑。

5.2 仪表板页面加载缓慢或卡顿

症状：打开AgentHQ网页时，加载时间很长，或者操作不流畅。

排查与优化：

1. 数据库性能（SQLite模式）：如果运行了很长时间，积累了海量的时间线事件数据，SQLite查询可能会变慢。可以考虑为timeline_events表的时间戳字段创建索引。

   -- 连接到你的 agenthq.db 数据库 sqlite3 agenthq.db -- 创建索引 CREATE INDEX IF NOT EXISTS idx_timeline_created_at ON timeline_events(created_at);

   更激进的做法是定期归档旧数据，比如只保留最近30天的事件。
2. 前端资源：AgentHQ前端基于Next.js，在开发模式下（npm run dev）热重载可能会导致初始加载稍慢。对于生产环境，可以考虑构建优化版本。

   # 在项目目录下构建生产版本 npm run build # 使用PM2启动生产服务器（如果package.json配置了start脚本） npx pm2 start npm --name agenthq-prod -- start

   生产构建会对代码进行压缩、打包和优化，加载速度会显著提升。
3. 网络与反向代理：如果你通过公网访问，可能是网络延迟。考虑在服务器前部署一个Nginx反向代理，并开启gzip压缩。
4. 浏览器开发者工具：按F12打开开发者工具，切换到“网络（Network）”标签页，刷新页面，查看是哪个请求耗时最长。如果是/api/timeline加载慢，那就是数据量大的问题，参考第1点优化。

5.3 Dispatcher不分配任务

症状：在Supabase模式下，创建了“待办”任务，但长时间没有Agent领取。

排查步骤：

1. 检查Dispatcher进程状态：npx pm2 status agenthq-dispatcher，确保进程是“online”状态。
2. 查看Dispatcher日志：npx pm2 logs agenthq-dispatcher --lines 100，查看是否有明显的错误信息，如连接Supabase失败、网关认证失败等。
3. 确认环境变量：确保启动Dispatcher时传入的SUPABASE_URL、SUPABASE_KEY、GATEWAY_URL、GATEWAY_TOKEN全部正确无误。特别是GATEWAY_TOKEN，如果OpenClaw重启，令牌可能会变更。
4. 检查Agent状态：Dispatcher只会将任务分配给状态为online或idle的Agent。确保至少有一个Agent在线。
5. 检查任务表结构：确认Supabase中的tasks表结构完全按照schema.sql创建，并且status字段的值是todo（小写）。
6. 手动测试网关连接：用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模式以实现协同。

安全迁移步骤：

1. 备份SQLite数据：首先，完整备份你的agenthq.db文件。
2. 在Supabase中创建空表：按照前文所述，在Supabase SQL编辑器中执行schema.sql。
3. 使用数据导出导入工具：这是最关键的步骤。由于表结构一致，你可以使用sqlite3命令行工具和psql（PostgreSQL客户端）或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。
4. 切换AgentHQ配置：运行bash setup.sh supabase ...命令，将AgentHQ切换到Supabase模式。
5. 验证数据：重启AgentHQ服务，登录仪表板，检查所有Agent、任务和历史事件是否完整显示。

重要警告：迁移过程中，务必停止Observer和Dispatcher，避免在迁移期间产生新数据，导致数据不一致。最好在业务低峰期进行完整迁移。

AgentHQ作为一个专注解决特定痛点的工具，其简洁的设计和清晰的架构让我在管理AI Agent团队时效率倍增。它可能没有大而全的监控系统那些复杂告警和图表，但它提供的“状态-任务-事件”三维视角，对于理解和调试一个动态的Agent系统来说，已经构成了最坚实的信息基础。我最欣赏的一点是它的可扩展性，从最简单的单机SQLite部署，到支持团队协作的Supabase云端模式，路径非常平滑。如果你也在为多个AI Agent的协同工作而头疼，花半小时部署一个AgentHQ，很可能就是你一直在找的那块拼图。