Heartbeat Ollama Guard

Switch OpenClaw heartbeat model to local Ollama and deploy a guard to prevent unauthorized changes, avoiding paid cloud token usage.

将 OpenClaw 心跳切换为本地 Ollama 模型，并部署配置守卫防止被静默修改，从而避免心跳请求消耗付费云端 token。

---

背景

OpenClaw 的心跳机制每 30 分钟调用一次 LLM，默认走云端模型（kimi / claude 等）。 在 token 限额有限的情况下，这会白白消耗配额，甚至耗尽每周限额。

本技能：

1. 将所有 OpenClaw 实例的 agents.defaults.heartbeat.model 改为 local/<model>
2. 部署一个 60s 轮询守卫，检测到未授权修改立即回滚并发出系统通知

---

快速开始

bash

cd ~/.openclaw/workspace/skills/heartbeat-ollama-guard

# 一键安装（需要先安装 Ollama）
python3 heartbeat_ollama_guard.py --setup

# 指定其他模型
python3 heartbeat_ollama_guard.py --setup --model llama3:8b

# 查看状态
python3 heartbeat_ollama_guard.py --status

---

安装 Ollama

macOS：

bash

brew install ollama
# 或访问 https://ollama.com 下载 App

Linux：

bash

curl -fsSL https://ollama.com/install.sh | sh

---

CLI 命令

命令	说明
--setup	完整安装向导（自动检测、拉取模型、配置、部署守卫）
--status	显示 Ollama、模型、守卫进程、所有实例的当前状态
--check	执行一次守卫检查（不循环）
--uninstall	卸载守卫（LaunchAgent/systemd + 守卫脚本 + conf）
--model <id>	指定本地模型 ID（默认 qwen3.5:4b-q4_K_M）

---

安装向导步骤

text

Step 1  检测 Ollama 是否已安装（未安装则打印安装指引并退出）
Step 2  检测目标模型，未拉取则自动 ollama pull
Step 3  发现所有 openclaw.json 实例，确认需要配置哪些
Step 4  写入 heartbeat.model（自动备份原文件）
Step 5  生成守卫脚本、conf.json，部署 LaunchAgent（macOS）或 systemd（Linux）
Step 6  验证守卫进程 + 单次检查
Step 7  提示重启 gateway

---

授权修改 heartbeat.model

守卫会阻止任何未经授权的 heartbeat.model 修改。合法修改流程：

1. 先更新 ~/.openclaw/workspace/.lib/heartbeat-guard.conf.json 中对应实例的 expected 值
2. 再修改 openclaw.json

守卫检测到 conf 与 openclaw.json 一致时自动放行，无需关闭守卫。

---

安全声明

操作	范围
读取 openclaw.json	仅检测 heartbeat.model 现状
写入 openclaw.json	仅 heartbeat.model + models.providers.local 字段
守卫守护进程	纯本地，60s 轮询，无网络请求
macOS 系统通知	仅守卫检测到未授权改动时触发
不需要 sudo	✅
不读取对话内容	✅
不访问外部 API	✅

---

备份与恢复

安装向导在修改 openclaw.json 前自动备份到：

text

~/.openclaw/workspace/.lib/.hog_backups/

如需手动恢复：

bash

cp ~/.openclaw/workspace/.lib/.hog_backups/<backup>.json ~/.openclaw/openclaw.json

---

验证

1. 运行 --status → 所有项 ✅
2. 手动篡改 openclaw.json 的 heartbeat.model → 60 秒内自动回滚 + 系统通知
3. 查看日志 ~/.openclaw/workspace/.lib/heartbeat-guard.log → 有 [ALERT] + [REVERT] 条目
4. 授权修改：先改 conf.json expected 值 → 再改 openclaw.json → 守卫放行

---

文件位置

文件	说明
~/.openclaw/workspace/.lib/heartbeat-guard.py	守卫守护进程脚本
~/.openclaw/workspace/.lib/heartbeat-guard.conf.json	守卫授权配置
~/.openclaw/workspace/.lib/heartbeat-guard.log	守卫运行日志
~/Library/LaunchAgents/com.openclaw.heartbeat-guard.plist	macOS LaunchAgent
~/.config/systemd/user/openclaw-heartbeat-guard.service	Linux systemd
~/.openclaw/workspace/.lib/.hog_backups/	openclaw.json 备份