← Back to Skills Marketplace
Heartbeat Ollama Guard
by
halfmoon82
· GitHub ↗
· v1.0.0
· MIT-0
227
Downloads
0
Stars
1
Active Installs
1
Versions
Install in OpenClaw
/install heartbeat-ollama-guard
Description
Switch OpenClaw heartbeat model to local Ollama and deploy a guard to prevent unauthorized changes, avoiding paid cloud token usage.
README (SKILL.md)
heartbeat-ollama-guard
将 OpenClaw 心跳切换为本地 Ollama 模型，并部署配置守卫防止被静默修改，从而避免心跳请求消耗付费云端 token。
背景
OpenClaw 的心跳机制每 30 分钟调用一次 LLM，默认走云端模型（kimi / claude 等）。 在 token 限额有限的情况下，这会白白消耗配额，甚至耗尽每周限额。
本技能：
- 将所有 OpenClaw 实例的
agents.defaults.heartbeat.model改为local/\x3Cmodel> - 部署一个 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 \x3Cid> |
指定本地模型 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 修改。合法修改流程：
- 先更新
~/.openclaw/workspace/.lib/heartbeat-guard.conf.json中对应实例的expected值 - 再修改
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/\x3Cbackup>.json ~/.openclaw/openclaw.json
验证
- 运行
--status→ 所有项 ✅ - 手动篡改
openclaw.json的heartbeat.model→ 60 秒内自动回滚 + 系统通知 - 查看日志
~/.openclaw/workspace/.lib/heartbeat-guard.log→ 有[ALERT]+[REVERT]条目 - 授权修改：先改 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 备份 |
Usage Guidance
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.
Capability Analysis
Type: OpenClaw Skill
Name: heartbeat-ollama-guard
Version: 1.0.0
The skill bundle implements a configuration 'guard' that uses high-risk capabilities to ensure OpenClaw settings remain pointed to a local Ollama model. Specifically, 'heartbeat_ollama_guard.py' installs a persistent background daemon via macOS LaunchAgents or Linux systemd and automatically reverts modifications to 'openclaw.json' files. While these actions align with the stated purpose, the use of persistence and automated file overwriting is inherently risky. Furthermore, the daemon's notification logic is vulnerable to AppleScript injection because it passes unsanitized configuration values directly into an 'osascript' command.
Capability Assessment
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.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install heartbeat-ollama-guard - After installation, invoke the skill by name or use
/heartbeat-ollama-guard - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
- Added skill to redirect OpenClaw's heartbeat from cloud to local Ollama model, preventing excessive token use.
- Implements a 60s polling guard to monitor and revert unauthorized changes to heartbeat configuration, with system notifications.
- Provides CLI commands for setup, status monitoring, authorized modification, and uninstallation.
- Ensures all operations are local, secure, and fully reversible with built-in backup and restoration tools.
- Detailed instructions for quick start, Ollama installation, and permission management included.
Metadata
Frequently Asked Questions
What is Heartbeat Ollama Guard?
Switch OpenClaw heartbeat model to local Ollama and deploy a guard to prevent unauthorized changes, avoiding paid cloud token usage. It is an AI Agent Skill for Claude Code / OpenClaw, with 227 downloads so far.
How do I install Heartbeat Ollama Guard?
Run "/install heartbeat-ollama-guard" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is Heartbeat Ollama Guard free?
Yes, Heartbeat Ollama Guard is completely free, licensed under MIT-0. You can download, install and use it at no cost.
Which platforms does Heartbeat Ollama Guard support?
Heartbeat Ollama Guard is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created Heartbeat Ollama Guard?
It is built and maintained by halfmoon82 (@halfmoon82); the current version is v1.0.0.
More Skills