# OpenClaw Agent 数据接入说明

## 推荐方式

推荐 `自动获取为主，ops 兜底修正`，不要让 ops 手动维护整个页面内容。

最适合当前局域网部署的一版是：

1. `OpenClaw` 或 `ops` agent 定时生成一份 JSON 文件
2. 把文件写到：
   - `storage/agents/openclaw-agents.json`
3. 网站的 `/api/agents` 自动读取这份文件
4. 如果文件不存在，再回退到演示数据

这样做的好处：

- 不需要网站直接耦合 OpenClaw 内部实现
- 数据源坏了时，网站不会直接崩
- 后续迁移到 MacBook 很简单
- ops agent 只需要负责“产出标准 JSON”

## 当前页面真正需要的字段

现在 Agent 页已经按任务监控页收成紧凑工作列表，重点展示：

- `id`
- `name`
- `role`
- `status`
- `statusLabel`
- `host`
- `owner`
- `currentTask`
- `taskId`
- `taskStage`
- `queueDepth`
- `todayCompleted`
- `uptime`
- `lastHeartbeat`
- `updatedAt`
- `lastOutput`
- `lastError`
- `tags`

## JSON 示例

```json
{
  "fetchedAt": "2026-03-27T12:30:00.000Z",
  "agents": [
    {
      "id": "main-orchestrator",
      "name": "main",
      "role": "主调度 Agent",
      "avatarKind": "male-dispatcher",
      "status": "working",
      "statusLabel": "工作中",
      "host": "macbook-ops.local",
      "owner": "OpenClaw Core",
      "currentTask": "拆分今日任务并下发给下游 agent",
      "taskId": "orch-20260327-0841",
      "taskStage": "dispatching",
      "queueDepth": 3,
      "todayCompleted": 18,
      "uptime": "12天 4小时",
      "lastHeartbeat": "2秒前",
      "updatedAt": "刚刚",
      "lastOutput": "已完成一轮任务编排，正在等待下游结果。",
      "lastError": "",
      "tags": ["调度", "编排", "主控"]
    }
  ]
}
```

## ops 运维专员应该做什么

`ops` agent 不应该手工逐条编辑页面内容，而应该：

1. 负责采集 OpenClaw agent 状态
2. 负责把状态转成标准 JSON
3. 定时刷新本地 JSON 文件
4. 在 OpenClaw 数据异常时写入 `lastError`
5. 在没有真实数据时告警，而不是伪造状态

## 后续更进一步

如果后面要做强实时版本，可以再从“本地 JSON 文件”升级到：

- 本地 HTTP 状态接口
- WebSocket / SSE 推送
- SQLite 历史状态记录

但第一版局域网部署，先用本地 JSON 文件是最稳的。