lan-reader-chat/docs/openclaw-ops-runbook.md

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. 重启网站

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

2. 重跑 agent feed 同步

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

3. 检查日志

建议查看：

/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：

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

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

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

storage/agents/openclaw-agents.json

字段格式参考：

• openclaw-agent-feed.md
• openclaw-agent-feed.example.json

八、更新回归清单

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

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