Heartbeat Ollama Guard

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

Security Scan

The skill's code and instructions broadly match its stated purpose (switch heartbeats to a local Ollama model and install a local guard), but there are a few inconsistencies and operational risks you should review before installing.

Purpose & Capability

Name, description, SKILL.md and the included Python code align: the tool finds openclaw.json instances, sets agents.defaults.heartbeat.model to a local/<model>, deploys a user-level guard (LaunchAgent or systemd user service), and backs up/rewrites those JSON files. It calls the ollama binary as expected and does not request unrelated environment variables or credentials.

Instruction Scope

The runtime instructions and embedded guard operate on user OpenClaw config files (read/write heartbeat.model and models.providers.local) and create backups/logs under ~/.openclaw/workspace/.lib — this is in-scope for the stated purpose. However SKILL.md recommends running "curl -fsSL https://ollama.com/install.sh | sh" for Ollama on Linux (a risky pattern) and the setup will run 'ollama pull' (which downloads models). The README claims the guard makes "no network requests"; that appears to be true for the guard daemon itself, but setup/model pulls and the recommended Ollama installer do perform network activity. The guard relies on a conf.json mapping to decide what to revert; that conf file effectively authorizes changes and must be protected.

Install Mechanism

There is no platform install spec in the registry (instruction-only), which is lower risk, but SKILL.md explicitly instructs a remote install via a curl|sh command. The domain used (ollama.com) is an official project host, not an arbitrary paste or IP, but piping remote install scripts to sh is generally risky and should be reviewed. The skill will also call 'ollama pull' which downloads model artifacts (large network downloads) — expected for the feature but worth noting.

Credentials

The skill requests no environment variables or credentials and only accesses user-level files under the home directory. It does not require sudo. The requested file-system accesses (openclaw.json, .lib/*, user LaunchAgents/systemd) are proportional to the stated purpose.

Persistence & Privilege

The skill installs a persistent user-level service (LaunchAgent on macOS or systemd user service on Linux) that runs every ~60s to enforce config values. It does not request always:true and does not require elevated privileges, but it does create long-lived presence in the user's account and will autonomously revert changes unless you update the guard conf to permit them.

What to consider before installing

What to check before installing: - Review the included Python files (heartbeat_ollama_guard.py and the embedded guard code) yourself — they are provided in the package and implement the behavior described. Confirm there are no additional hidden behaviors in the truncated portion of the manifest you received. - Do not blindly run curl | sh; if you must install Ollama, prefer downloading from the official site and inspecting the installer script first. - Be aware setup will run 'ollama pull' to fetch models (network and large downloads). The guard itself appears not to contact external endpoints, but setup does. - Understand the guard's conf file (~/.openclaw/workspace/.lib/heartbeat-guard.conf.json) is the authorization mechanism: anyone who can modify that file can authorize changes. After install, tighten file permissions on that conf and on the backup/log directory. - Verify the LaunchAgent or systemd unit contents before enabling so you know exactly what will start at login. - Keep backups of your openclaw.json (the tool also writes .hog_backups) and test with --status and --check first. - If you are uncomfortable with persistent user-level services or automated modification of config files, do not install; instead manually change heartbeat.model and manage Ollama yourself.

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

---

背景

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

本技能：

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

---

快速开始

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：

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

Linux：

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）

---

安装向导步骤

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 前自动备份到：

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

如需手动恢复：

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 备份