AI Agent运维仪表盘AgentHQ：轻量部署与OpenClaw智能体监控实践

1. 项目概述：一个为AI Agent团队打造的轻量级运维仪表盘

如果你正在使用OpenClaw框架来管理和运行你的AI智能体团队，那么你很可能和我一样，经历过这样的困扰：手头同时运行着好几个Agent，有的在处理数据分析，有的在生成报告，还有的在等待指令。你很难一眼看清谁在线、谁在忙、谁的任务卡住了，更别提回溯某个Agent今天到底干了些什么。传统的日志文件虽然详细，但缺乏直观的聚合视图；而自己动手写一个监控界面，又得耗费不少精力在前后端联调上。

AgentHQ就是为了解决这个痛点而生的。它是一个极其轻量、开箱即用的运维仪表盘，专门为OpenClaw智能体团队设计。它的核心目标非常明确：让你能在一个简洁的网页界面上，实时掌握所有Agent的状态、工作内容和历史活动。整个项目只有3个页面和4个API路由，没有任何冗余功能，追求的就是快速部署和直观易用。你可以把它想象成是给AI团队配备的一个“任务指挥中心”，或者一个“数字化的团队看板”。

这个工具特别适合两类人：一是AI应用开发者，你需要直观地监控和调试你部署的Agent集群；二是团队管理者或研究者，你需要一个清晰的视图来跟踪多个AI协作者的工作进度和协作流程。无论你是想快速查看当前运行状态，还是需要审计过去一段时间内所有Agent的操作记录，AgentHQ都能提供一个集中化的解决方案。

2. 核心设计思路与架构解析

2.1 为什么选择“轻量”作为首要原则？

在决定开发AgentHQ之初，我反复思考的第一个问题就是：一个AI Agent的运维面板，最核心的价值是什么？答案是：信息的实时性与可读性，以及部署的便捷性。我们不需要一个功能大而全、依赖复杂的“重型”系统。一个复杂的系统往往意味着更长的启动时间、更多的维护成本和更高的学习门槛，这与OpenClaw本身追求高效、灵活的理念是相悖的。

因此，AgentHQ的设计哲学是“做减法”。它只聚焦于三个最关键的视图：

1. 仪表盘：提供全局概览，包括Agent状态卡片、关键统计数据（如在线数、任务总数）和最近的活动流。
2. 时间线：提供一个完整的、可过滤的审计追踪记录。所有Agent的关键事件（如任务创建、状态变更、结果产出）都按时间顺序排列，并支持按Agent筛选和按日期分组，方便进行问题回溯和过程复盘。
3. 任务看板：采用经典的Kanban（看板）模式，将任务分为“待办”、“进行中”、“审核中”、“已完成”四个状态列。这为任务管理和流程推进提供了直观的可视化工具，并且还包含一个已归档任务的网格视图。

这种极简的设计确保了用户能在几秒钟内找到所需信息，而不会迷失在复杂的菜单和配置项中。

2.2 技术栈选型背后的考量

AgentHQ的技术栈选择也完全服务于“轻量”和“高效”的目标：

• 前端：Next.js 16 + React 19 + Tailwind CSS：Next.js提供了开箱即用的服务端渲染和API路由功能，让我们能用同一个技术栈同时搞定前端页面和后端接口，极大地简化了项目结构。React 19带来了更好的性能和开发体验。Tailwind CSS则让我们能以实用优先（Utility-First）的方式快速构建出美观、响应式的UI，无需维护复杂的CSS文件。
• 状态与数据同步：React Query：对于仪表盘这类需要实时或准实时更新数据的应用，手动管理请求状态和轮询逻辑非常繁琐且容易出错。React Query完美地解决了这个问题，它内置了缓存、后台刷新、错误重试等机制。我们只需简单地配置查询间隔，前端就能自动、优雅地保持数据新鲜度，用户看到的一直是最新的团队状态。
• 数据存储：SQLite（默认）与Supabase（可选）：这是架构中一个非常巧妙的设计。SQLite模式实现了“零外部依赖”部署。整个应用的数据（Agent配置、任务、时间线事件）都存储在一个本地SQLite文件中，无需安装和配置任何数据库服务（如PostgreSQL、MySQL）。这对于个人用户或单机部署场景来说，简单到了极致。Supabase模式则提供了云原生和团队协作的能力。它将数据存储在云端PostgreSQL中，支持多设备访问和数据持久化，并且为高级功能（如自动任务分发器）提供了基础。
• 后端逻辑：Python观察器与分发器：虽然前端是Next.js，但一些需要深度集成OpenClaw运行时的功能（如读取会话文件、调用网关API）用Python来实现更为合适。因此，项目包含了observer.py和dispatcher.py两个Python脚本。它们作为独立的“守护进程”，与前端应用松耦合，通过读写共享的数据库（SQLite文件或Supabase）来进行通信。

这种混合架构（Node.js前端 + Python后端脚本）既利用了JavaScript生态在Web UI上的优势，也发挥了Python在系统集成和数据处理上的长处，通过数据库作为中介，实现了清晰的责任分离。

2.3 数据流与组件交互全景图

要理解AgentHQ如何工作，我们需要梳理清楚数据是如何在各个组件间流动的：

[OpenClaw 运行时] (产生原始数据) | v [observer.py] (Python守护进程) |-- 定期扫描 ~/.openclaw/ 下的会话文件 |-- 解析Agent状态（活跃/在线/空闲/离线） |-- 捕获子任务生成与完成事件 |-- 将结构化数据写入 --> [数据库: SQLite 或 Supabase] | v [数据库] (作为唯一数据源) | |---------------------------------------------- | | v v [AgentHQ Next.js 前端] [dispatcher.py] (Python守护进程，仅Supabase模式) |-- 通过API路由查询数据 |-- 轮询数据库中的“待办”任务 | (`/api/agents`, `/api/tasks`等) |-- 通过OpenClaw网关API，将任务分配给合适的在线Agent |-- 使用React Query管理查询与自动刷新 |-- 将分配结果写回数据库 |-- 渲染Dashboard, Timeline, Task Board视图 | v [用户浏览器] (实时查看与交互)

这个架构的核心是数据库作为中心枢纽。观察器负责“感知”现实世界（OpenClaw运行状态）并写入数据库，前端和分发器则从数据库“读取”状态并做出反应（展示或执行）。这种设计使得各个组件可以独立开发、部署和扩展。

3. 环境准备与两种部署模式详解

3.1 基础环境要求与常见避坑指南

AgentHQ对运行环境的要求非常明确，但根据不同的操作系统，可能会遇到一些小坑。以下是详细的准备步骤和注意事项。

核心要求：

• Node.js 22+：这是运行Next.js前端所必需的。请注意，许多Linux发行版的默认仓库可能只提供较旧的Node.js版本（如Ubuntu 22.04/24.04默认是Node 18）。
• Python 3.8+：用于运行observer.py和dispatcher.py脚本。现代Linux和macOS系统通常已预装，但需确认版本。
• OpenClaw环境：显然，你需要一个正在运行或计划运行OpenClaw Agent的工作环境。AgentHQ会读取OpenClaw生成的数据。

注意：关于--break-system-packages参数在Ubuntu 24.04及以上版本中，如果你使用系统自带的Python（通过apt安装的），pip install默认会进入一个严格模式，禁止向系统目录安装包。项目文档中使用的--break-system-packages参数就是为了绕过这个限制。但请谨慎使用，因为这可能会影响系统Python环境的稳定性。更推荐的做法是使用Python虚拟环境：

# 在项目目录下创建虚拟环境 python3 -m venv venv # 激活虚拟环境 source venv/bin/activate # 然后安装依赖，无需--break-system-packages pip install -r requirements.txt

这样可以将依赖隔离在项目内，避免与系统包冲突。

在Ubuntu 24.04上安装Node.js 22：如果你的系统是Ubuntu 24.04，默认的Node.js是18版本。你需要手动安装Node.js 22。

# 1. 添加NodeSource官方仓库（提供了更新的Node.js版本） curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - # 这个过程会添加APT源并导入GPG密钥。 # 2. 安装Node.js 22和npm sudo apt-get install -y nodejs # 3. 验证安装 node --version # 应显示 v22.x.x npm --version

避坑点：有时系统里残留的老版本Node.js可能会造成冲突。如果安装后版本不对，可以尝试先卸载旧版：sudo apt remove --purge nodejs npm，然后再执行上述步骤。

3.2 极速部署：一键安装脚本解析

对于大多数用户，尤其是想快速体验和评估的用户，AgentHQ提供了最便捷的一行命令安装方式：

bash <(curl -fsSL https://raw.githubusercontent.com/98kiran/agenthq/master/install.sh)

这个命令做了以下几件事：

1. 下载安装脚本：通过curl从GitHub仓库获取install.sh脚本的内容。
2. 执行脚本：bash <(...)这个语法意味着直接将下载的内容作为脚本执行。
3. 脚本内部逻辑（推测）：脚本很可能会自动检测环境，安装缺失的依赖（如Node.js 22），克隆AgentHQ仓库，安装Python和Node.js依赖，运行初始化设置（setup.sh），并最终启动应用。

实操心得：

• 这种安装方式非常适合在干净的测试环境或容器中快速拉起服务。
• 在生产环境或已有复杂环境的主机上使用前，强烈建议先查看一下install.sh脚本的内容，了解它具体会执行哪些操作，以避免意外的系统修改。你可以通过curl -fsSL https://raw.githubusercontent.com/98kiran/agenthq/master/install.sh来直接查看脚本源码。
• 执行后，脚本通常会在终端输出访问URL（如http://localhost:3000）和一个随机生成的初始密码，务必记下这个密码。

3.3 手动部署：更可控的安装流程

如果你希望对安装过程有完全的控制权，或者需要自定义某些路径，那么手动部署是更好的选择。步骤虽然稍多，但每一步都清晰可见。

# 1. 克隆代码仓库 git clone https://github.com/98kiran/agenthq.git cd agenthq # 2. 安装Python依赖（建议在虚拟环境中进行） pip3 install -r requirements.txt # 如果在Ubuntu 24.04+的系统Python下遇到权限错误，才考虑使用： # pip3 install -r requirements.txt --break-system-packages # 3. 初始化数据库（这里以SQLite模式为例） bash setup.sh sqlite # 执行这个脚本，它会： # a. 检查环境依赖。 # b. 在项目目录下创建或初始化SQLite数据库文件（例如 `agenthq.db`）。 # c. 创建必要的数据库表（agent_config, tasks, timeline_events等）。 # d. 很可能生成一个默认的管理员账户和密码，并打印在屏幕上。 # 4. 启动前端应用 # 使用PM2进行进程管理，保证应用在后台稳定运行，即使退出终端也不会停止。 npx pm2 start npm --name agenthq -- start # 这条命令的意思是：用PM2启动一个名为“agenthq”的进程，这个进程执行 `npm start`。 # 首次运行会安装PM2。`npm start` 会启动Next.js开发服务器（默认端口3000）。 # 5. （可选）设置PM2开机自启 npx pm2 save npx pm2 startup # 按照`pm2 startup`输出的提示执行命令，即可将当前PM2管理的应用列表加入到系统启动项中。

执行完setup.sh sqlite后，控制台会输出登录信息，类似：

AgentHQ initialized with SQLite. Login URL: http://your-server-ip:3000 Default password: xxxxxxxx

请用浏览器访问该URL，并使用生成的密码登录。

3.4 高级模式：使用Supabase实现云端协同

SQLite模式简单，但数据存储在本地，无法多设备访问，也不利于团队共享。如果你需要从不同电脑查看同一个Agent团队的仪表盘，或者希望数据有更可靠的云端备份，那么Supabase模式是必选。

Supabase部署步骤：

1. 创建Supabase项目：前往 supabase.com 注册并创建一个新项目。获取你的项目URL和Service Role Key（服务角色密钥）。Service Role Key拥有绕过行级安全策略（RLS）的权限，适合后端脚本使用，请妥善保管。
2. 执行Supabase初始化命令：

   # 格式：bash setup.sh supabase <你的Supabase项目URL> <你的Service Role Key> bash setup.sh supabase https://xxxxxx.supabase.co eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

   这个命令会将数据库连接配置写入项目环境，后续应用将连接至Supabase的PostgreSQL数据库。
3. 在Supabase中创建表：setup.sh脚本可能不会自动在云端创建表结构。你需要手动执行项目根目录下的schema.sql文件。
   • 进入Supabase控制台，选择左侧的SQL Editor。
   • 点击New query，将schema.sql文件的内容复制粘贴进去。
   • 点击Run或按Cmd/Ctrl + Enter执行。这将在你的Supabase数据库中创建AgentHQ所需的所有表。
4. 启动应用：启动命令与SQLite模式相同，因为数据库连接信息已通过环境变量或配置文件注入。

   npx pm2 start npm --name agenthq -- start

模式对比与选择建议：

个人建议：即使是个人使用，如果你有多台开发机（比如办公室和家里的电脑），并且希望统一查看所有机器上Agent的状态，Supabase模式带来的便利性远远超过其微小的配置成本。它让AgentHQ从一个本地工具变成了一个真正的云端服务。

4. 核心功能模块深度实操

4.1 观察器：如何实现无侵入的Agent状态监控

observer.py是AgentHQ的“眼睛”。它的设计非常巧妙，采用了一种无侵入、基于日志文件分析的方式来监控OpenClaw Agent，这意味着你不需要修改任何OpenClaw的代码，也不需要在你自己的Agent逻辑中插入特定的上报API。

工作原理深度解析：OpenClaw在运行Agent时，会在其工作目录（通常是~/.openclaw/）下生成和维护一系列会话文件。这些文件以结构化格式（如JSON或YAML）记录了Agent的运行时信息，包括：

• Agent的唯一标识符（ID）和名称。
• 当前状态（例如：thinking,executing,waiting,finished）。
• 接收到的任务（Task）及其子任务（Subtask）。
• 任务执行的结果和产出。

observer.py脚本的核心工作就是定期（例如每30秒）扫描这些会话文件目录，解析文件内容，并将变化同步到AgentHQ的数据库中。具体流程如下：

1. 扫描与发现：脚本遍历~/.openclaw/workspace/或类似目录，寻找活动的会话文件。
2. 状态推断：通过分析会话文件中的时间戳、当前活动字段等，推断出Agent的展示状态。通常映射为：
   • 活跃：正在执行任务或思考。
   • 在线：会话文件存在且最近被更新，但当前无活动。
   • 空闲：长时间无活动。
   • 离线：会话文件不存在或已过期。
3. 事件捕获：对比上一次扫描的结果，识别出新创建的任务、完成的任务、状态变更等，将这些作为“时间线事件”记录到timeline_events表。
4. 数据写入：将最新的Agent配置（名称、技能等）、任务列表和事件批量更新到数据库（SQLite或Supabase）。

部署与运行实践：官方推荐使用cron定时任务来运行观察器，这是最经典和稳定的方式。

# 编辑当前用户的cron任务 crontab -e

在打开的编辑器中，添加以下两行：

* * * * * cd /path/to/your/agenthq && /usr/bin/python3 observer.py >> /path/to/your/agenthq/observer.log 2>&1 * * * * * sleep 30 && cd /path/to/your/agenthq && /usr/bin/python3 observer.py >> /path/to/your/agenthq/observer.log 2>&1

关键点解释：

• * * * * *：表示每分钟执行一次。
• sleep 30：第二行命令先等待30秒再执行。这样两行合起来，就实现了每30秒执行一次扫描，而不是每分钟的0秒和30秒各一次更精确。
• cd /path/to/your/agenthq：确保脚本在正确的项目目录下运行，这样才能找到数据库和导入正确的模块。
• >> .../observer.log 2>&1：将脚本的标准输出和标准错误都重定向追加到observer.log文件中，便于后续排查问题。2>&1的意思是“将标准错误（文件描述符2）重定向到标准输出（文件描述符1）所在的位置”。

避坑技巧：

• 路径问题：务必使用/usr/bin/python3这样的绝对路径来指定Python解释器，避免因环境变量问题导致cron找不到命令。同样，项目路径也要用绝对路径。
• 文件权限：确保运行cron的用户（通常是你自己）对OpenClaw的会话文件目录有读取权限，对AgentHQ项目目录有读写权限。
• 日志管理：定期检查observer.log文件大小，可以配置日志轮转（logrotate）防止其无限增长。
• 测试脚本：在加入cron之前，先在终端手动执行一次命令，确保没有报错，并能看到预期的输出（如“Observed X agents”）。

4.2 仪表盘与时间线：数据可视化与审计追踪

登录AgentHQ后，首先看到的就是仪表盘。这里的信息布局经过精心设计，旨在让你用最短的时间获取最大信息量。

仪表盘核心组件解读：

• Agent状态卡片：每个卡片代表一个独立的OpenClaw Agent。卡片上通常会显示Agent的名称、头像（如果配置了）、当前状态（用不同颜色的圆点表示，如绿色活跃、黄色在线、灰色空闲）、以及可能正在执行的任务概要。点击卡片通常可以跳转到该Agent的详细视图或时间线过滤视图。
• 统计概览：一组关键指标，例如：
  • Total Agents：发现的Agent总数。
  • Online：当前在线的Agent数。
  • Active Tasks：处于“进行中”状态的任务数。
  • Tasks Today：今天创建的任务总数。 这些数字让你对团队整体负荷有一个快速感知。
• 最近活动流：一个按时间倒序排列的微型时间线，显示最近发生的几个重要事件，例如“Agent ‘Coder’ 开始处理任务 ‘Fix bug #123’”、“Agent ‘Writer’ 完成了子任务 ‘Draft introduction’”。这是整个系统动态的实时缩影。

时间线页面的强大之处：如果说仪表盘是“现在”，那么时间线就是“过去”。它记录了所有Agent的所有事件，形成了一个完整的审计追踪。

• 过滤与搜索：页面顶部通常有一排“药丸”形状的过滤器，点击某个Agent的名字，时间线就只显示与该Agent相关的事件。这对于排查单个Agent的问题或复盘其工作流程极其有用。
• 日期分组：事件会自动按日期（如“今天”、“昨天”、“更早”）进行分组，让时间脉络更加清晰。
• 可展开的详情：每条事件记录可能只是一个摘要。点击旁边的展开箭头，可以看到该事件的完整详情，例如任务的具体输入参数、执行后的完整输出结果、产生的文件列表等。这相当于一个集成的日志查看器。
• 实操价值：当某个Agent产出的结果不符合预期时，你可以通过时间线追溯到它接收到的具体指令、执行的每一步操作，甚至中间产生的临时思考过程，从而精准定位问题是出在指令理解、工具调用还是其他环节。

4.3 任务看板：用Kanban管理AI工作流

任务看板是AgentHQ中一个偏重“管理”的功能模块。它将软件开发和项目管理中流行的Kanban方法引入了AI Agent的协作流程。

看板列的定义与流转：

• 待办：所有新创建或尚未开始处理的任务都会出现在这里。这可以是你手动通过某个接口添加的任务，也可以是外部系统推送过来的。
• 进行中：已被某个Agent认领并正在执行的任务。
• 审核中：任务已执行完毕，产出了结果，等待人工或另一个“审核Agent”进行验收检查。
• 已完成：通过审核，最终完成的任务。
• 已归档：对于已完成的任务，一段时间后可以将其归档，使其从主看板移除，但在专门的归档网格视图中仍可查询，保持主看板的整洁。

如何与OpenClaw任务关联？这里的“任务”与OpenClaw中的“Task”概念是映射的。observer.py会从OpenClaw的会话文件中提取任务信息，并将其同步到AgentHQ的tasks表中。任务的状态（如created,assigned,completed）会决定它在看板中位于哪一列。

高级用法：手动管理任务除了自动同步，你很可能需要通过API或未来可能提供的UI表单来手动创建任务。例如，你可以创建一个描述为“分析上周的销售数据并生成总结报告”的任务，并将其放入“待办”列。结合下一节要讲的分发器，这个任务就可以被自动分配给合适的Agent去执行。

使用心得：这个看板对于管理复杂的、多步骤的AI工作流特别有效。例如，你可以设计一个“写作Agent”流水线：任务“撰写一篇关于量子计算的科普文章”进入“待办”；被“调研Agent”认领后进入“进行中”；调研完成产出大纲后，任务状态更新，可能触发自动创建子任务“撰写引言部分”并再次进入“待办”，等待“写作Agent”处理；所有部分写完后，任务进入“审核中”，由“校对Agent”或人工审核；最后进入“已完成”。整个流程在看板上一目了然。

5. 高级功能与集成配置

5.1 分发器：实现任务的智能自动分配

dispatcher.py是AgentHQ的“大脑”，它实现了任务的自动路由功能。这个功能仅在Supabase模式下可用，因为它依赖于数据库的实时查询和OpenClaw网关的远程调用能力。

分发器的工作机制：

1. 轮询查询：分发器作为一个后台守护进程，定期（例如每10秒）查询Supabase数据库的tasks表，寻找状态为todo（待办）且未被分配的任务。
2. 决策逻辑：这是分发器的核心。最简单的策略是“随机分配”或“轮询分配”。但更智能的策略可以基于：
   • Agent技能：任务可能有标签（如coding,writing），分发器会寻找技能匹配的在线Agent。
   • Agent负载：优先分配给当前任务队列最短的Agent。
   • 历史表现：针对某类任务成功率高的Agent优先。 （注：当前开源版本的策略可能比较简单，但架构为自定义策略留出了空间）。
3. 调用网关：一旦确定了目标Agent，分发器就会通过HTTP请求调用OpenClaw的网关API。网关是OpenClaw与外部系统交互的入口。

   # 一个简化的调用示例（实际在dispatcher.py中封装） curl -X POST http://127.0.0.1:18789/api/v1/task \ -H "Authorization: Bearer <GATEWAY_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "selected_agent_id", "task": { "id": "task_id_from_db", "instruction": "任务描述..." } }'

4. 更新状态：任务成功分配给Agent后，分发器会更新数据库中该任务的状态为assigned，并可能在timeline_events表中添加一条“任务已分配给Agent X”的记录。

部署分发器的详细步骤：

1. 确保环境：你已经按照前文完成了Supabase模式的配置，并且应用正在运行。
2. 获取网关凭证：分发器需要与OpenClaw网关通信。网关的URL和认证令牌通常在OpenClaw的配置文件~/.openclaw/openclaw.json中。

   cat ~/.openclaw/openclaw.json | grep -A2 -B2 gateway # 查找类似以下的配置 # "gateway": { # "auth": {"token": "your_super_secret_gateway_token_here"}, # "port": 18789 # }

   记下token和port（通常网关运行在http://127.0.0.1:18789）。
3. 启动分发器进程：在AgentHQ项目目录下，使用PM2启动分发器。这里通过环境变量传递所有必要配置。

   cd ~/.openclaw/workspace/agenthq SUPABASE_URL=<你的Supabase项目URL> \ SUPABASE_KEY=<你的Supabase Service Role Key> \ GATEWAY_URL=http://127.0.0.1:18789 \ GATEWAY_TOKEN=<你的网关Token> \ npx pm2 start python3 --name agenthq-dispatcher -- dispatcher.py

   参数解释：
   • SUPABASE_URL和SUPABASE_KEY：让分发器连接你的云端数据库。
   • GATEWAY_URL：你的OpenClaw网关地址。
   • GATEWAY_TOKEN：用于认证网关API。
   • python3 dispatcher.py：启动Python脚本。
4. 保存PM2配置：为了让分发器在服务器重启后也能自动运行，执行：

   npx pm2 save # 如果之前没设置过开机启动，还需要运行 `pm2 startup` 并按照提示操作。

调试技巧：

• 查看分发器日志：npx pm2 logs agenthq-dispatcher
• 如果任务没有被分配，首先检查日志是否有错误。常见问题包括：网关地址/令牌错误、Supabase连接失败、或者没有在线的Agent可以接收任务。

5.2 实时状态推送：配置WebSocket连接

默认情况下，AgentHQ的前端是通过React Query定期轮询API（例如每5-10秒）来更新数据的。这对于大多数场景已经足够。但如果你追求极致的实时性，希望Agent状态一变化（比如从“思考”变为“在线”），前端的状态点就能立即更新，那么就需要启用WebSocket支持。

WebSocket如何工作？OpenClaw网关可能提供了WebSocket接口，用于向客户端推送实时事件（如Agent状态变更、任务进度更新）。AgentHQ前端可以连接这个WebSocket端点，订阅这些事件。当收到事件时，前端可以立即更新本地缓存和UI，无需等待下一次轮询。

配置方法：在AgentHQ项目根目录下，创建或编辑文件.env.local（Next.js会优先加载此文件的环境变量）。

# .env.local GATEWAY_WS_URL=ws://127.0.0.1:18789/ws # WebSocket端点，端口需与网关一致 GATEWAY_TOKEN=<你的网关Token> # 用于建立WebSocket连接时的认证 GATEWAY_ORIGIN=http://localhost:3000 # 你的AgentHQ前端访问地址，用于CORS

配置后：重启AgentHQ前端应用（npx pm2 restart agenthq）。如果前端代码中已集成了WebSocket客户端逻辑，它将会尝试连接指定的GATEWAY_WS_URL。此时，仪表盘上的Agent状态点、活动流等将会实现真正的“实时”更新。

注意事项：

• 这需要你的OpenClaw网关确实启用了WebSocket支持并暴露了相应的端点。
• 生产环境中，如果前端与网关不在同一个域名下，还需要正确配置网关的CORS以允许前端域名（GATEWAY_ORIGIN）的连接。

5.3 利用OpenClaw Agent技能进行自动化安装

这是一个非常酷的特性，体现了AI生态的自我管理能力。如果你的OpenClaw主Agent已经具备了agenthq这个技能（可能通过技能库安装），那么你甚至不需要手动执行任何命令。

你只需要对你的主Agent说：“安装AgentHQ给我用。”

拥有该技能的Agent会理解这个指令，并自动在后台执行我们前面提到的“一键安装脚本”或相应的安装流程。它会处理环境检查、依赖安装、配置初始化等一系列操作，并在完成后可能告诉你访问地址和密码。

这带来的启示：未来，AI Agent的管理和运维本身，完全可以由更高级别的“元Agent”或“运维Agent”来自动完成。我们只需要提出需求，它们就能自主执行复杂的部署和配置任务。AgentHQ支持这种安装方式，正是为这样的未来工作流铺平了道路。

6. 故障排查与性能优化实战记录

6.1 安装与启动常见问题

在部署AgentHQ的过程中，你可能会遇到以下典型问题。这里提供我的排查思路和解决方法。

问题1：执行一键安装脚本或setup.sh时失败，提示Node.js或Python版本不对。

• 排查：首先分别检查Node.js和Python的版本。

  node --version python3 --version

• 解决：
  • Node.js过旧：参照前文“环境准备”部分，通过NodeSource仓库安装Node.js 22。
  • Python路径问题：确保系统中有python3命令。某些环境可能只有python命令。你可以尝试创建软链接：sudo ln -s /usr/bin/python3 /usr/local/bin/python，或者修改脚本中的解释器路径。

问题2：前端应用启动失败，PM2报错或端口被占用。

• 排查：

  # 查看PM2日志 npx pm2 logs agenthq # 检查3000端口是否被占用 sudo lsof -i :3000

• 解决：
  • 端口占用：如果3000端口被其他程序（如另一个Next.js应用）占用，可以修改AgentHQ的启动端口。在package.json中修改scripts里的start命令，或在启动时指定端口：npx pm2 start npm --name agenthq -- start -- -p 3001。
  • 依赖安装不全：进入项目目录，删除node_modules和package-lock.json，然后重新安装：npm ci（推荐，它严格依赖package-lock.json）或npm install。

问题3：能打开登录页面，但输入密码后无法登录，或登录后看不到任何Agent数据。

• 排查：
  1. 检查后端API：打开浏览器开发者工具（F12），切换到“网络”标签页，尝试登录。查看登录请求（通常是/api/auth）和后续的数据请求（如/api/agents）是否返回错误（状态码非200）。
  2. 检查数据库：
     • SQLite模式：确认setup.sh sqlite成功执行，并且项目目录下存在数据库文件（如agenthq.db）。可以尝试用sqlite3 agenthq.db命令连接，查看agent_config等表是否有数据。
     • Supabase模式：登录Supabase控制台，进入Table Editor，查看对应的表是否已创建且有数据。
  3. 检查观察器：确认observer.py是否在正常运行。查看observer.log日志文件，看是否有错误信息，或者是否成功扫描到了OpenClaw会话文件。

     tail -f /path/to/agenthq/observer.log

• 解决：
  • API错误：根据网络请求返回的错误信息进行修复。常见的是数据库连接失败。
  • 观察器未运行：手动执行一次python3 observer.py，看输出是否正常。修复cron任务或直接以后台进程方式启动观察器：nohup python3 observer.py > observer.log 2>&1 &。
  • OpenClaw路径问题：观察器默认可能在~/.openclaw/寻找会话文件。如果你的OpenClaw工作目录不同，可能需要修改observer.py中的路径配置，或通过环境变量指定。

6.2 观察器与分发器运行异常

问题4：observer.log中显示“Permission denied”或“File not found”错误。

• 原因：运行cron任务的用户（如www-data或你的用户名）没有权限读取OpenClaw的会话文件目录，或者目录路径不正确。
• 解决：
  1. 确认OpenClaw会话文件的实际路径。ls -la ~/.openclaw/workspace/。
  2. 在observer.py中或通过环境变量设置正确的OPENCLAW_WORKSPACE_DIR。
  3. 调整目录权限：chmod -R 755 ~/.openclaw/workspace/（注意：这可能会降低安全性，请根据你的环境评估）。更安全的方式是将运行观察器的用户加入到拥有该目录读取权限的组中。

问题5：分发器日志显示“Failed to assign task”或网关连接错误。

• 排查：
  1. 检查分发器启动命令中的环境变量（GATEWAY_URL,GATEWAY_TOKEN）是否正确。
  2. 验证网关服务是否正在运行：curl http://127.0.0.1:18789/api/health（如果网关有健康检查端点）。
  3. 检查Supabase连接是否正常。可以在分发器脚本中临时添加打印语句，输出连接状态。
• 解决：
  • 网关令牌错误：从openclaw.json中重新获取正确的令牌。
  • 网关未运行：启动你的OpenClaw网关服务。
  • 网络/防火墙：确保分发器运行的主机能访问网关的IP和端口。

6.3 性能优化与安全建议

对于个人或小团队使用（SQLite模式）：

• 定期清理旧数据：时间线事件表可能会快速增长。可以编写一个简单的清理脚本，定期删除比如30天前的事件记录，以控制数据库文件大小。

  # 示例：使用sqlite3命令清理旧事件 sqlite3 /path/to/agenthq.db "DELETE FROM timeline_events WHERE created_at < datetime('now', '-30 days');"

• 优化观察器扫描间隔：如果Agent数量多、任务变化频繁，每分钟扫描两次（每30秒）是合理的。如果Agent很少且稳定，可以适当延长间隔（如每2分钟一次），减少系统I/O。

对于生产环境团队使用（Supabase模式）：

• 数据库索引优化：在Supabase中为tasks(status),timeline_events(created_at, agent_id)等经常查询的字段创建索引，可以大幅提升仪表盘和时间线页面的查询速度。
• 启用行级安全：Supabase默认使用行级安全策略。对于agent_config,tasks等表，你需要仔细设计RLS策略，以确保用户只能看到他们有权访问的Agent和任务数据。目前项目可能默认使用Service Role Key绕过RLS，这在多用户场景下需要调整。
• 保护环境变量：SUPABASE_KEY（Service Role）和GATEWAY_TOKEN是高级别的密钥，切勿提交到代码仓库。务必通过.env.local文件或服务器环境变量管理，并确保文件权限为600。
• 使用反向代理：不要直接将Next.js开发服务器（端口3000）暴露到公网。使用Nginx或Caddy作为反向代理，配置SSL/TLS（HTTPS），并设置适当的HTTP头安全策略。

一个实用的监控技巧：将AgentHQ自身的运行状态也纳入监控。你可以为PM2进程设置监控告警，或者简单地将observer.py和dispatcher.py的日志接入你的集中日志系统（如ELK、Loki）。这样，当这个“指挥中心”自己出现问题时，你能第一时间知晓。