name: bot-status-api
description: "部署一个轻量级状态 API，用于展示 OpenClaw 机器人的运行健康状况、服务连通性、定时任务、技能、系统指标等信息。适用于为 OpenClaw 智能体搭建监控仪表盘、健康检查端点或状态页面。支持通过配置对接任意服务（HTTP 检查、CLI 命令、文件检查）。零依赖——仅需 Node.js 环境。"

机器人状态 API

一个可配置的 HTTP 服务，以 JSON 格式展示 OpenClaw 机器人的运行状态。专为仪表盘集成、监控和状态透明化而设计。

功能概览

• 机器人核心状态：在线状态、模型、上下文使用率、运行时长、心跳时间
• 服务健康检查：支持 HTTP 端点、CLI 工具或文件路径的检查
• 邮件状态：支持从任意邮件提供商（himalaya、gog 等）获取未读邮件数
• 定时任务：直接读取 OpenClaw 的 cron/jobs.json 文件
• Docker 状态：通过 Portainer API 获取容器健康状况
• 开发服务器：通过进程 grep 自动检测正在运行的开发服务器
• 技能列表：列出已安装和可用的 OpenClaw 技能
• 系统指标：从 /proc 读取 CPU、内存、磁盘使用情况

安装配置

1. 复制服务文件

将 server.js、collectors/ 目录和 package.json 复制到目标位置。

2. 创建配置文件

复制 config.example.json 为 config.json 并自定义配置：

{
  "port": 3200,
  "name": "MyBot",
  "workspace": "/path/to/.openclaw/workspace",
  "openclawHome": "/path/to/.openclaw",
  "cache": { "ttlMs": 10000 },
  "model": "claude-sonnet-4-20250514",
  "skillDirs": ["/path/to/openclaw/skills"],
  "services": [
    { "name": "myservice", "type": "http", "url": "http://...", "healthPath": "/health" }
  ]
}

服务检查类型

3. 启动服务

node server.js

4. 持久化运行（systemd 用户服务）

# ~/.config/systemd/user/bot-status.service
[Unit]
Description=Bot Status API
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/bot-status
ExecStart=/usr/bin/node server.js
Restart=always
RestartSec=5
Environment=PORT=3200
Environment=HOME=/home/youruser
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now bot-status
loginctl enable-linger $USER  # 保持服务在用户登出后继续运行

5. 从 OpenClaw 获取上下文/核心指标

机器人应定期将核心指标写入工作空间的 heartbeat-state.json 文件：

{
  "vitals": {
    "contextPercent": 62,
    "contextUsed": 124000,
    "contextMax": 200000,
    "model": "claude-opus-4-5",
    "updatedAt": 1770304500000
  }
}

将此功能添加到 HEARTBEAT.md 中，以便机器人在每次心跳周期更新该文件。

API 端点

架构特点

• 零依赖 — 仅使用 Node.js 内置模块（http、fs、child_process）
• 非阻塞 — 所有 shell 命令使用异步 exec，避免 execSync 阻塞
• 后台刷新 — 缓存按间隔刷新，请求始终从缓存即时响应（约 10ms）
• 配置驱动 — 所有配置均在 config.json 中，无硬编码值