1. 项目概述为你的AI特工打造一个像素风实时指挥中心如果你和我一样在本地运行着好几个OpenClaw AI智能体每天看着它们在终端里默默工作是不是总觉得少了点什么它们各自为战状态不明成本消耗也像一笔糊涂账。直到我发现了这个项目——Pixel Office。这不仅仅是一个仪表盘它是一个完全可视化的、像素艺术风格的“AI特工办公室”。想象一下你手下的每个AI特工都变成了一个像素小人在办公室的工位上忙碌有的在电脑前敲代码working有的在饮水机旁摸鱼idle甚至还能聚在会议室里“开会”。所有状态、消耗的Token、产生的费用都以一种直观、生动的方式实时呈现在你面前。这正是SC32br/openclaw-skill-pixel-office这个开源项目带来的核心体验。它基于Next.js和Pixi.js构建将枯燥的后台数据变成了一个可交互的、充满游戏感的监控界面。对于任何管理多个AI智能体的开发者或团队来说这不仅是效率工具更是一种乐趣。2. 核心架构与设计思路拆解2.1 为什么是“像素办公室”在深入代码之前我们先聊聊设计哲学。市面上监控仪表盘很多Grafana、Prometheus功能强大但冰冷。Pixel Office选择像素艺术风格是一个非常高明的设计决策。第一降低认知负荷。AI智能体是抽象的、无形的。将它们具象化为一个个有表情、有动作的像素角色用户一眼就能分辨出“谁是谁”、“在干嘛”。红色小人可能在报错error绿色小人正在运行working黄色小人则在思考thinking。这种视觉映射比看文字状态快得多。第二强化归属感与叙事性。将智能体称为“特工”Agent并放置在一个有工位、会议室、饮水机的“办公室”里构建了一个完整的叙事场景。这不仅仅是监控更像是在“管理一支团队”。这种隐喻让复杂的系统管理变得亲切尤其适合向非技术背景的成员展示项目进展。第三技术实现的优雅契合。像素艺术Pixel Art在渲染上对性能要求相对较低非常适合用Pixi.js这种2D渲染引擎来实现复杂的动画和实时状态更新。一个办公室场景加上几十个动画小人在现代浏览器上也能保持60fps的流畅度这是选择Pixi.js而非Three.js3D等更重方案的关键原因。2.2 技术栈选型背后的逻辑项目的技术栈组合非常经典且务实每一层选择都有其明确目的前端框架Next.js 16 React 19为什么是Next.js项目需要服务端渲染SSR来保证首屏加载速度特别是对于需要认证的仪表盘快速呈现登录界面或基础框架至关重要。Next.js的App Router提供了清晰的数据获取模式fetchin Server Components非常适合构建/api路由和预渲染静态部分如办公室布局。React 19的优势其并发特性和改进的渲染器能更好地处理Pixi.js画布与React UI侧边栏、活动流之间的状态同步减少不必要的重渲染。渲染引擎Pixi.js v8核心选择这是项目的灵魂。Pixi.js是业界领先的2D WebGL渲染引擎性能极高。我们需要在画布上实时渲染数十个独立的、带有行走、坐下、伸展等骨骼动画的像素精灵Sprite并可能伴随粒子效果如思考时的“ZZZ”气泡。Pixi.js的显示对象容器、滤镜系统和补间动画库能完美支撑这些需求。与React的集成通常Pixi.js画布是一个独立于React的DOM节点。项目需要精巧的状态管理将React侧的智能体状态来自Zustand Store同步到Pixi.js侧的精灵状态和行为上。状态管理Zustand轻量且高效相比ReduxZustand的API更简洁学习曲线平缓。对于这个中等复杂度的应用一个集中的Store来管理智能体列表、活动流、UI状态如侧边栏折叠完全足够。它的响应式更新能高效地驱动React组件和Pixi.js画布通过订阅Store变化。后端与数据层SQLite Drizzle ORM本地优先作为一个本地部署的监控工具使用文件型数据库SQLite是最自然的选择。它无需额外服务better-sqlite3驱动性能出色。类型安全Drizzle ORM是一个新兴的、类型安全的SQL查询构建器。它与TypeScript结合得天衣无缝能保证从数据库表结构到API返回类型的一致性极大减少运行时错误。npm run db:push命令就是基于Drizzle的迁移工具来创建表结构。样式与部署Tailwind CSS v4, systemd, nginxTailwind CSS用于快速构建响应式的UI组件侧边栏、成本报表。其实用优先Utility-First的理念与组件化开发非常契合。systemd nginx体现了项目的“生产就绪”思维。提供一键部署脚本和Service文件让应用能作为后台服务稳定运行并通过nginx实现反向代理和基础的HTTP认证提升了安全性。整个架构可以概括为Next.js作为全栈框架统筹前后端Pixi.js负责核心可视化Zustand进行状态同步SQLite持久化基础数据再通过标准的Linux服务化部署方案交付给用户。3. 核心模块深度解析与实操要点3.1 数据模型智能体Agent、会话Session与成本Cost这是理解整个系统数据流的基础。很多新手容易混淆为什么启动了Bot办公室却空无一人OpenClaw 工作区 │ ├── 会话 (Sessions) - **地图上特工的唯一数据源** │ └── 通过 POST /tools/invoke → sessions_list 工具从网关获取 │ └── 每个 key 格式为 agent:main:label 的会话对应地图上一个特工 │ ├── 机器人 (Bots) - 通信渠道如Telegram, Discord │ └── 一个机器人 ≠ 一个特工。一个机器人可以为多个特工服务。 │ └── 一个特工也可以没有机器人无头运行。 │ └── 工作区文件夹 (Workspace Folders) - 你的项目文件 └── 不直接读取。只有注册到网关的活跃会话才会出现在地图上。核心规则地图上特工的数量 OpenClaw网关中活跃会话的数量而不是机器人的数量或文件夹的数量。实操要点确保网关运行且Token正确Pixel Office通过OPENCLAW_GATEWAY_URL和OPENCLAW_TOKEN访问网关API。如果网关没开或Token无效/api/openclaw/stats接口就会失败导致无法获取会话列表。启动你的特工在你的OpenClaw工作区通过openclaw start agent-name或类似命令启动特工。成功启动后特工会向网关注册一个会话。理解会话Key网关返回的会话key是识别特工的唯一标识。Pixel Office会过滤掉非agent:开头或包含:subagent:的内部会话只将agent:main:your-agent-label映射为办公室里的一个像素角色。成本数据来源成本报表/office/costs的数据独立于网关会话。它通过读取本地磁盘上OpenClaw运行时生成的会话日志文件~/.openclaw/agents/*/*.jsonl来聚合计算Token消耗和估算费用。这意味着即使网关暂时不可用你依然能查看历史成本。3.2 可视化核心Pixi.js画布与智能体渲染src/components/office/PixelOffice.tsx是这个模块的入口。其核心工作流程如下画布初始化在React组件挂载后创建一个PixiApplication实例并将其Canvas DOM节点挂载到ref上。设置合适的分辨率可能根据窗口缩放和背景色。办公室场景绘制调用drawOffice.ts中的函数。这里会创建并排列多个PIXI.Container作为图层例如backgroundLayer: 绘制地板、墙壁等静态背景。furnitureLayer: 绘制工位桌椅、饮水机、会议室桌子等家具。agentLayer:最重要的图层所有特工精灵都在这一层。overlayLayer: 用于绘制状态气泡、名字标签等UI元素。特工精灵生成与动画drawAgent.ts是灵魂所在。每个特工根据其ID和状态被绘制成一个像素精灵。精灵表Sprite Sheet通常不会为每个动作单独绘制图片而是使用一张包含所有动画帧的精灵表。通过PIXI.AnimatedSprite来播放行走、闲置、工作等动画序列。状态驱动行为订阅Zustand Store中特工状态的变化。当状态从idle变为working时可能触发播放“打字”动画变为thinking时头顶显示“...”气泡error时角色颜色变红或显示感叹号。路径寻找与移动当特工需要从一个工位移动到会议室时会使用简单的A*算法或预设路径点进行移动。Pixi.js的Ticker游戏循环会在每一帧更新精灵的位置形成平滑移动。注意事项性能是关键。尽管像素艺术资源很小但精灵数量多、动画复杂时仍需优化。务必使用PIXI.Container进行合理的图层管理将静态元素和动态元素分离。对于不再需要的精灵如已销毁的特工一定要调用destroy()方法释放纹理和内存。3.3 前后端数据流与API设计数据流清晰分离保证了应用的响应性和可维护性。浏览器 ├── 请求 /api/agents (GET) → Next.js API路由 → 查询SQLite数据库 → 返回特工基础信息名称、角色、表情符号 ├── 请求 /api/openclaw/stats (GET) → Next.js API路由 → 调用网关/tools/invoke → 处理并返回活跃会话及实时状态 ├── 请求 /api/activity/feed (GET) → 从数据库或内存中获取最近的活动日志 └── 请求 /api/openclaw/cost-report (GET) → 读取本地JSONL日志文件 → 聚合计算后返回成本数据API路由详解src/app/api/agents/route.ts: 简单的CRUD接口用于管理特工元数据。初始化时你可以通过SQL插入或Drizzle迁移来预置特工。openclaw/stats/route.ts:核心数据接口。它封装了对OpenClaw网关的调用处理认证、错误401、429、503并将会话数据格式化为前端需要的结构。这里必须做好错误隔离即使网关挂掉前端界面也不应崩溃而是显示友好的错误提示。openclaw/cost-report/route.ts: 使用Node.js的fs模块遍历指定目录默认为~/.openclaw/agents下的所有.jsonl文件。逐行解析JSON按时间范围、特工、模型提供商进行聚合统计。这里需要注意文件读取的效率和错误处理避免因为单个损坏文件导致整个报表失败。activity/feed/route.ts: 可以对接OpenClaw的日志系统或者简单地将特工的状态变化、重要操作记录到SQLite的activities表中用于在侧边栏显示实时动态。安全与代理配置要点项目文档特别强调了nginx的配置陷阱这是很多部署失败的原因。/_next/静态资源必须由Next.js服务3001端口提供但也需要HTTP Basic Auth保护否则用户可能绕过登录直接访问打包后的JS文件。配置中location ^~ /_next/块同样需要auth_basic。/api/接口绝对不能加auth_basic。因为浏览器发出的XHRFetch/Axios请求默认不会携带在访问/office/时弹出的Basic Auth凭据。这部分认证应由Next.js的中间件middleware.ts在应用层基于Session或Token来处理或者依赖nginx对/office/入口的保护已进入办公室页面的请求其同源的API请求被认为是已认证的。4. 从零到一的完整部署与配置实操假设你已经在Ubuntu 22.04服务器上运行了OpenClaw网关现在要部署Pixel Office。4.1 环境准备与手动部署# 1. 进入你的工作区目录克隆项目 cd ~/agents-workspace git clone https://github.com/SC32br/openclaw-skill-pixel-office.git cd openclaw-skill-pixel-office # 2. 确保Node.js版本 20.x (推荐22 LTS) node --version # 如果版本低使用nvm管理 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新打开终端或 source ~/.bashrc nvm install 22 nvm use 22 # 3. 安装依赖并构建 npm install npm run build # 生产环境构建 # 4. 配置环境变量 cp .env.example .env.local nano .env.local在.env.local中至少配置以下关键项NODE_ENVproduction PORT3001 DATABASE_URLfile:/home/your_user/agents-workspace/pixel-office/data/office.db OPENCLAW_GATEWAY_URLhttp://localhost:18789 # 你的网关地址 OPENCLAW_TOKENyour_super_secret_gateway_token_here # 从OpenClaw配置中获取# 5. 初始化数据库 npm run db:push # 检查表是否创建成功 sqlite3 data/office.db .tables # 应该看到 agents, activities 等表 # 6. 可选预置一些特工数据到数据库 sqlite3 data/office.db INSERT INTO agents (id, name, role, emoji, currentStatus) VALUES (chief, 首席指挥官, Manager, ‍, idle), (dev, 代码工程师, Developer, ‍, working), (writer, 内容写手, Writer, ✍️, thinking);4.2 配置Systemd服务后台运行# 将提供的service文件复制到系统目录 sudo cp deploy/pixel-office.service /etc/systemd/system/ # 编辑service文件确认路径和用户正确通常不需要改它使用了动态路径 sudo nano /etc/systemd/system/pixel-office.service # 重点关注 # Useryour_username # WorkingDirectory/home/your_username/agents-workspace/pixel-office # ExecStart/usr/bin/env node /home/your_username/agents-workspace/pixel-office/.next/standalone/server.js # 启用并启动服务 sudo systemctl daemon-reload sudo systemctl enable --now pixel-office # 检查服务状态和日志 sudo systemctl status pixel-office sudo journalctl -u pixel-office -f --no-pager4.3 配置Nginx反向代理与基础认证这是最容易出错的环节。请严格按照deploy/nginx-location.conf的示例将配置块添加到你的Nginx站点配置中通常是/etc/nginx/sites-available/your_domain。server { listen 80; server_name your-domain.com; # 或你的服务器IP # ... 其他配置 ... # 关键配置开始 # 1. 保护静态资源但必须代理到Next.js location ^~ /_next/ { auth_basic Pixel Office; auth_basic_user_file /etc/nginx/.htpasswd; proxy_pass http://127.0.0.1:3001; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } # 2. API路由 - 不要加auth_basic location ^~ /api/ { proxy_pass http://127.0.0.1:3001; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; # 重要不要在这里设置 auth_basic } # 3. 应用主入口 location ^~ /office/ { auth_basic Pixel Office; auth_basic_user_file /etc/nginx/.htpasswd; proxy_pass http://127.0.0.1:3001; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } # 关键配置结束 }生成HTTP Basic Auth密码文件# 安装apache2-utils如果未安装 sudo apt-get install apache2-utils # 创建密码文件用户名为office会提示输入密码 sudo htpasswd -c /etc/nginx/.htpasswd office # 如果文件已存在去掉 -c 参数添加新用户 # 测试密码文件 cat /etc/nginx/.htpasswd配置检查与重载# 测试Nginx配置语法 sudo nginx -t # 如果成功重载Nginx sudo systemctl reload nginx4.4 使用OpenClaw技能一键安装推荐如果你已经有一个正在运行的OpenClaw特工那么部署可以变得极其简单。这体现了OpenClaw生态的“技能”Skill理念。在你的OpenClaw特工所在的聊天窗口如Telegram直接发送命令install pixel office或者用中文установи пиксельный офис俄语命令项目作者是俄语开发者特工会自动执行SKILL.md中定义的脚本完成我们上面手动操作的所有步骤克隆仓库到~/agents-workspace/pixel-office安装Node.js依赖并构建生成随机的8位密码创建并启用systemd服务配置Nginx设置HTTP Basic Auth最后它会将访问URL和生成的密码发给你。这种方式极大地简化了部署流程是OpenClaw技能系统的典型应用。5. 高级定制与问题排查实录5.1 自定义你的像素办公室修改特工外观每个特工在drawAgent.ts中通过其id映射到一套颜色方案和精灵样式。你可以找到类似下面的函数进行修改export function getAgentColorScheme(agentId: string): AgentColors { const palette: Recordstring, AgentColors { chief: { primary: 0xFF6B6B, secondary: 0x4ECDC4 }, // 红蓝配色 dev: { primary: 0x45B7D1, secondary: 0x96E6A1 }, // 蓝绿配色 writer: { primary: 0xFECA57, secondary: 0xFF9FF3 }, // 黄粉配色 // 添加或修改你的特工ID my_custom_agent: { primary: 0x5F27CD, secondary: 0x54A0FF } }; return palette[agentId] || { primary: 0x95A5A6, secondary: 0x7F8C8D }; // 默认灰色 }调整办公室布局办公室的工位、会议室位置是在drawOffice.ts中通过一个网格或坐标数组定义的。例如const DESK_POSITIONS [ { x: 100, y: 150, id: desk_1 }, { x: 250, y: 150, id: desk_2 }, { x: 400, y: 150, id: desk_3 }, // 添加更多工位 { x: 100, y: 300, id: desk_4 }, ];在PixelOffice.tsx中会将特工列表与这些位置进行匹配例如按特工加入顺序分配工位或根据特工ID哈希分配。5.2 常见问题排查速查表以下是我在部署和使用过程中遇到的一些典型问题及解决方案问题现象可能原因排查步骤与解决方案办公室页面空白浏览器控制台报JS 404错误Nginx配置中缺少或错误的/_next/路由块导致静态资源无法加载。1. 检查浏览器开发者工具“网络”标签确认是/_next/static/...文件返回404。2. 核对Nginx配置确保有location ^~ /_next/ { ... proxy_pass ... }块并且包含了auth_basic指令。侧边栏显示“0个特工在线”1. OpenClaw网关未运行或Token错误。2. Nginx对/api/路径误加了auth_basic导致前端API请求被401拦截。1. 在服务器上测试网关连通性curl -X POST http://localhost:18789/tools/invoke -H \Authorization: Bearer $YOUR_TOKEN\ ...。2.检查Nginx配置确保location ^~ /api/块内没有auth_basic指令。/office/costs页面404使用了过时的Nginx配置其中包含rewrite ^/office/(.*)$ /$1 break;规则将请求错误地重写。移除所有对/office/路径的rewrite规则。确保配置是location ^~ /office/ { proxy_pass http://127.0.0.1:3001/office/; }。Pixel Office服务启动失败1. Node.js路径问题特别是使用nvm时。2. 端口3001被占用。3. 数据库文件权限错误。1. 查看日志sudo journalctl -u pixel-office -n 50。2. 检查which node确保systemd service文件中的ExecStart使用了正确的绝对路径或/usr/bin/env node。3. 检查data/目录权限确保运行服务的用户有读写权限。成本报表数据为空或不准1.OPENCLAW_AGENTS_DIR环境变量未设置或指向错误路径。2. JSONL日志文件格式不兼容或损坏。1. 确认.env.local中OPENCLAW_AGENTS_DIR指向了正确的OpenClaw代理日志目录通常是~/.openclaw/agents。2. 手动检查该目录下是否有*.jsonl文件并用tail命令查看其内容格式。网关返回429请求过多Pixel Office前端轮询网关的频率过高触发了网关的速率限制。检查前端代码或配置中调用/api/openclaw/stats的间隔时间建议不低于5-10秒。在src/lib/openclaw-gateway.ts中应有错误处理和退避逻辑。5.3 性能优化与扩展思路性能优化画布渲染如果特工数量非常多50需要考虑精灵的批处理渲染Sprite Batching。Pixi.js的PIXI.ParticleContainer或pixi/particles可以对大量简单精灵进行优化。状态更新避免在React的每次渲染或Pixi.js的每帧ticker中都进行深度的数据对比。使用Zustand的selector精细订阅或使用PIXI.Ticker的deltaTime进行节流更新。API轮询合理设置数据拉取间隔。实时状态如特工是否在线可以频繁一点如5秒而成本数据可以拉取间隔更长如1分钟。功能扩展自定义行为在drawAgent.ts中为特定状态添加更丰富的动画。例如error状态时可以让角色闪烁红光或播放一个“摔倒”的动画。交互功能点击特工可以弹出详细信息面板显示其最近的任务、消耗的详细Token、或直接向其发送指令如果网关API支持。多办公室/视图对于特工集群可以支持切换不同的“办公室”视图例如按项目分组、按功能分组。告警集成当特工长时间处于error状态或成本超过阈值时在办公室界面显示明显的告警如闪烁的警报灯并可以通过Webhook通知到外部系统如Slack、钉钉。部署并运行起Pixel Office后看着那些像素小人在屏幕上忙碌你对整个AI智能体集群的运行状态会有一种前所未有的、直观的掌控感。它把运维的“苦差事”变成了一种有趣的“管理游戏”。这个项目不仅是一个优秀的监控工具更是开源社区如何通过创意提升开发者体验的一个绝佳范例。