# OpenClaw ops 运维专员运行手册

## 一、角色定位

`ops 运维专员` 的职责不是手工维护页面内容，而是保障这套局域网网站在 MacBook 上稳定运行。

它主要负责：

1. 网站服务启动、停止、重启
2. 局域网访问连通性检查
3. 聊天数据库、上传目录、agent 状态文件的健康检查
4. OpenClaw agent 状态采集链路的检查
5. 更新前备份、更新后回归验证
6. 异常发现、记录和告警

## 二、ops 的日常检查项

建议每天至少巡检一次：

1. 网站首页是否可访问
2. 聊天接口是否返回正常
3. `/agents` 是否显示真实数据还是回退到 demo 数据
4. `storage/chat.sqlite` 是否存在且大小正常
5. `storage/chat-uploads/` 是否持续增长异常
6. `storage/agents/openclaw-agents.json` 最近更新时间是否正常
7. 磁盘空间是否低于安全阈值

## 三、推荐告警条件

建议当以下情况出现时主动告警：

1. 网站主页返回非 `200`
2. `/api/chat` 返回非 `200`
3. `/api/agents` 已经回退到 demo 数据
4. `openclaw-agents.json` 超过 5 分钟未刷新
5. `chat.sqlite` 无法访问
6. 上传目录写入失败
7. 服务进程不存在
8. 磁盘使用率超过 85%

## 四、ops 对 OpenClaw agent 状态的要求

ops 不应伪造 agent 状态。

如果采集失败：

1. 保留最后一次成功写入的数据
2. 在新状态里写明 `lastError`
3. 必要时把对应 agent 状态标记为 `warning` 或 `offline`

## 五、ops 应执行的维护动作

### 1. 重启网站

```bash
launchctl kickstart -k gui/$(id -u)/com.lan-reader-chat.web
```

### 2. 重跑 agent feed 同步

```bash
launchctl kickstart -k gui/$(id -u)/com.lan-reader-chat.agentfeed
```

### 3. 检查日志

建议查看：

```text
/Users/ops/lan-reader-chat/logs/web.out.log
/Users/ops/lan-reader-chat/logs/web.err.log
/Users/ops/lan-reader-chat/logs/agentfeed.out.log
/Users/ops/lan-reader-chat/logs/agentfeed.err.log
```

## 六、推荐给 OpenClaw 的 ops prompt

你可以把下面这段直接发给 OpenClaw：

```text
你是这个局域网网站的 ops 运维专员。你的职责是保障网站在 MacBook 上稳定运行，负责服务启停、日志巡检、局域网访问排障、数据备份恢复、版本更新和基础环境维护。你不负责产品设计决策，但需要在发现部署风险、数据丢失风险、磁盘/端口/进程问题、agent 状态采集异常时主动告警，并给出可执行处理建议。你应优先通过标准数据文件和服务日志判断问题，不要伪造 agent 状态，也不要手工修改页面内容来掩盖运行异常。
```

## 七、ops 交付给网站的标准数据

ops 或 OpenClaw 只需要负责把标准 JSON 放到：

```text
storage/agents/openclaw-agents.json
```

字段格式参考：

- [openclaw-agent-feed.md](C:\Users\LA\Documents\New%20project\docs\openclaw-agent-feed.md)
- [openclaw-agent-feed.example.json](C:\Users\LA\Documents\New%20project\docs\openclaw-agent-feed.example.json)

## 八、更新回归清单

每次更新后，ops 至少确认：

1. `/` 打开正常
2. `/chat` 能发送文字
3. 文件上传可用
4. 服务重启后聊天记录仍保留
5. `/agents` 显示真实数据源
6. `/library` 和阅读页正常