openclaw-warden 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roy Zhu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# OpenClaw Warden
+
+OpenClaw Warden is a small guardrail CLI for production OpenClaw deployments. It keeps your gateway stable by validating configuration changes, versioning them with git, and running health/agent probes with automatic restart when needed.
+
+## Why this exists
+
+Over 72 hours of hands-on deployment:
+- Day 1: excitement + pitfalls
+- Day 2: crashes + git saved the day
+- Day 3: stable operation + feature expansion
+
+OpenClaw now runs in my production environment and handles daily automation workloads. It still has sharp edges, but overall it is stable. It is not perfect, yet it is the closest open-source agent framework I have seen to "production usable."
+
+Tools are like people: nothing is perfect. The important part is knowing the strengths and weaknesses and deciding which trade-offs you can accept. OpenClaw's strengths are strong, and its weaknesses are clear. For me, the 72 hours were worth it because it made the real-world potential of AI agents tangible.
+
+OpenClaw Warden exists to make those trade-offs safer and easier to manage.
+
+## What it does
+
+- Validates OpenClaw config using the official schema to prevent crash loops
+- Stores config in a git-managed workspace and syncs it to `~/.openclaw/openclaw.json`
+- Runs periodic health checks and agent probes with backoff
+- Restarts the gateway and notifies the last active channel after failure
+
+## Layout
+- `warden.config.json`: Warden configuration
+- `config/openclaw.json`: managed OpenClaw config (git-tracked)
+- `state/schema.json`: OpenClaw config schema (generated)
+- `src/warden.js`: CLI entry
+
+## Initialization
+`openclaw-warden init` creates `warden.config.json` in the current directory (if missing), and pulls `~/.openclaw/openclaw.json` into `./config/openclaw.json`.
+
+**Important:** `config/openclaw.json` is always created relative to the directory containing `warden.config.json`. Put the config where you want the managed OpenClaw config to live.
+
+## Quick start
+
+```bash
+# Run without cloning the repo
+npx openclaw-warden init
+# or
+bunx openclaw-warden init
+
+# Generate/update schema (auto-clone OpenClaw source)
+npx openclaw-warden schema:update
+
+# Validate config
+npx openclaw-warden config:validate
+
+# Watch config -> validate -> sync to ~/.openclaw/openclaw.json -> git commit
+npx openclaw-warden watch
+
+# Heartbeat loop (every 5 minutes with 30/40/50s backoff)
+npx openclaw-warden heartbeat
+
+# Watch + heartbeat
+npx openclaw-warden run
+```
+
+## Background (daemon)
+Run in the background (no foreground terminal needed):
+
+```bash
+npx openclaw-warden daemon:start
+npx openclaw-warden daemon:status
+npx openclaw-warden daemon:stop
+```
+
+Default pid/log paths:
+- pid: `os.tmpdir()/openclaw-warden/warden.pid`
+- log: `os.tmpdir()/openclaw-warden/warden.log`
+
+## System service (recommended)
+If you need auto-start after reboot, install a system service.
+
+### Linux (systemd --user)
+```bash
+openclaw-warden service:template > ~/.config/systemd/user/openclaw-warden.service
+systemctl --user daemon-reload
+systemctl --user enable --now openclaw-warden
+```
+
+### macOS (launchd)
+```bash
+openclaw-warden service:template > ~/Library/LaunchAgents/ai.openclaw.warden.plist
+launchctl load -w ~/Library/LaunchAgents/ai.openclaw.warden.plist
+```
+
+### Windows (Task Scheduler)
+```powershell
+openclaw-warden service:template | Out-File -Encoding unicode $env:TEMP\openclaw-warden.xml
+schtasks /Create /TN OpenClawWarden /XML $env:TEMP\openclaw-warden.xml /F
+```
+
+> Tip: service templates assume `openclaw-warden` is on PATH (use `npm i -g openclaw-warden`).
+
+## Config location strategy
+- Prefer `./warden.config.json` in the current directory
+- If missing, fall back to the global config directory:
+  - macOS: `~/Library/Application Support/openclaw-warden/warden.config.json`
+  - Linux: `~/.config/openclaw-warden/warden.config.json`
+  - Windows: `%APPDATA%\openclaw-warden\warden.config.json`
+
+`init` creates the config in the current directory by default. Use `--global` to write to the global path:
+
+```bash
+npx openclaw-warden init --global
+```
+
+## Configuration (warden.config.json)
+
+```json
+{
+  "paths": {
+    "repoConfig": "./config/openclaw.json",
+    "liveConfig": "~/.openclaw/openclaw.json",
+    "schemaFile": "./state/schema.json"
+  },
+  "schema": {
+    "source": "git",
+    "repoUrl": "https://github.com/openclaw/openclaw.git",
+    "ref": "main",
+    "checkoutDir": "./state/openclaw",
+    "useLocalDeps": true,
+    "exportCommand": "node --import tsx -e \"import { buildConfigSchema } from './src/config/schema.ts'; console.log(JSON.stringify(buildConfigSchema(), null, 2));\""
+  },
+  "git": {
+    "enabled": true,
+    "autoInit": true
+  },
+  "heartbeat": {
+    "intervalMinutes": 5,
+    "waitSeconds": [30, 40, 50],
+    "checkCommand": "node ./src/check-health.js",
+    "agentProbe": {
+      "enabled": true,
+      "fallbackAgentId": "main",
+      "command": "node ./src/check-agent-probe.js"
+    },
+    "notifyOnRestart": true,
+    "notifyCommand": "openclaw agent --agent {agentId} -m \"[warden] gateway restarted after failed health check\" --channel last --deliver",
+    "restartCommand": "openclaw gateway restart"
+  }
+}
+```
+
+### Commands
+- `config:pull` (alias: `pull`): copy live config into the repo + git commit
+- `config:push` (alias: `push`): validate and sync repo config to the live path + git commit
+- `config:validate` (alias: `validate`): validate repo config against schema
+- `schema:update`: update schema from OpenClaw source
+- `watch`: watch repo config and auto-apply on changes
+- `heartbeat`: run health/agent probes loop
+- `run`: watch + heartbeat
+
+### checkCommand / notifyCommand / restartCommand / placeholders
+- `checkCommand`: health check (**exit code 0 = healthy**)
+- `agentProbe`: optional agent probe after gateway health
+- `notifyOnRestart`: send notification after restart
+- `notifyCommand`: notification command (recommended to use `openclaw agent ... --channel last --deliver`)
+- `restartCommand`: restart command
+
+Supported placeholders:
+- `{id}`: heartbeat id
+- `{repoConfig}`: managed config path
+- `{liveConfig}`: live config path
+- `{agentId}`: default agent id from last health check
+- `{sessionId}`: latest session id from sessions.json
+- `{sessionKey}`: latest session key
+
+### Logging
+- Default: `os.tmpdir()/openclaw-warden/warden.log` (stdout preserved)
+- Optional: set `logging.file` to override
+
+### Default health check script
+- `src/check-health.js` runs `openclaw gateway call health --json`, parses the last JSON object and checks `ok: true`
+- Writes recent session info to `os.tmpdir()/openclaw-warden/health.json` for notify/agent probe use
+- Only requires `openclaw` in PATH
+
+### Default agent probe script
+- `src/check-agent-probe.js` reads `health.json` for `agentId` (fallback `main`), runs
+  `openclaw agent --agent <id> -m "healthcheck" --json --timeout 60`
+  and checks `status: "ok"`
+
+## Notes
+- `schema:update` auto-clones OpenClaw source (default: main) and generates schema locally.
+- By default, OpenClaw repo dependencies are not installed; warden reuses its own `node_modules` (`useLocalDeps: true`).
+- All git operations only affect this repo; `~/.openclaw/` is never git-managed.
+
+## Acknowledgements
+This project exists because OpenClaw makes production agent workflows practical. Thank you to the OpenClaw team and community for building it.
+
+## Release workflow
+
+### Versioning and changelog
+This project uses `standard-version` for semantic versioning and changelog generation.
+
+- Generate/refresh changelog only:
+```bash
+npm run changelog
+```
+
+- Create a release (bumps version, updates changelog, creates a git tag):
+```bash
+npm run release
+# or
+npm run release:patch
+npm run release:minor
+npm run release:major
+```
+
+Then push commits and tags:
+```bash
+git push --follow-tags
+```
+
+### npm publish via GitHub Actions
+Publishing is automated when a tag like `v1.2.3` is pushed.
+
+Required secret:
+- `NPM_TOKEN` (npm access token with publish permission)

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "openclaw-warden",
+  "version": "0.1.0",
+  "description": "OpenClaw config guard + heartbeat monitor",
+  "type": "module",
+  "bin": {
+    "openclaw-warden": "./src/warden.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/royisme/openclaw-warden.git"
+  },
+  "bugs": {
+    "url": "https://github.com/royisme/openclaw-warden/issues"
+  },
+  "homepage": "https://github.com/royisme/openclaw-warden#readme",
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "scripts": {
+    "warden": "node ./src/warden.js",
+    "start": "node ./src/warden.js run",
+    "changelog": "standard-version --skip.bump --skip.commit --skip.tag",
+    "release": "standard-version",
+    "release:patch": "standard-version --release-as patch",
+    "release:minor": "standard-version --release-as minor",
+    "release:major": "standard-version --release-as major"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "tsx": "^4.21.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "standard-version": "^9.5.0"
+  }
+}

package/src/check-agent-probe.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function extractJson(text) {
+  if (!text) return null;
+  const lines = text.split(/\r?\n/).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i].trim();
+    if (!line.startsWith("{")) continue;
+    try {
+      return JSON.parse(line);
+    } catch {
+      // keep searching
+    }
+  }
+  const lastBrace = text.lastIndexOf("{");
+  if (lastBrace >= 0) {
+    const candidate = text.slice(lastBrace).trim();
+    try {
+      return JSON.parse(candidate);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function readHealthCache() {
+  const filePath = path.join(os.tmpdir(), "openclaw-warden", "health.json");
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+const cache = readHealthCache();
+const agentId = cache?.agentId || "main";
+
+const res = spawnSync(
+  "openclaw",
+  ["agent", "--agent", agentId, "-m", "healthcheck", "--json", "--timeout", "60"],
+  {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  },
+);
+
+const stdout = res.stdout || "";
+const data = extractJson(stdout);
+if (data && data.status === "ok") {
+  process.exit(0);
+}
+
+process.exit(1);

package/src/check-health.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+function extractJson(text) {
+  if (!text) return null;
+  const lines = text.split(/\r?\n/).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i].trim();
+    if (!line.startsWith("{")) continue;
+    try {
+      return JSON.parse(line);
+    } catch {
+      // keep searching
+    }
+  }
+  const lastBrace = text.lastIndexOf("{");
+  if (lastBrace >= 0) {
+    const candidate = text.slice(lastBrace).trim();
+    try {
+      return JSON.parse(candidate);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+async function readSessionId(sessionsPath, sessionKey) {
+  if (!sessionsPath || !sessionKey) return null;
+  try {
+    const raw = await fsp.readFile(sessionsPath, "utf8");
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== "object") return null;
+    const entry = data[sessionKey];
+    if (!entry || typeof entry !== "object") return null;
+    return entry.sessionId || null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeHealthCache(payload) {
+  try {
+    const dir = path.join(os.tmpdir(), "openclaw-warden");
+    await fsp.mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, "health.json");
+    await fsp.writeFile(filePath, JSON.stringify(payload, null, 2), "utf8");
+  } catch {
+    // ignore cache errors
+  }
+}
+
+const res = spawnSync("openclaw", ["gateway", "call", "health", "--json"], {
+  encoding: "utf8",
+  stdio: ["ignore", "pipe", "pipe"],
+});
+
+const stdout = res.stdout || "";
+const data = extractJson(stdout);
+if (data && data.ok === true) {
+  let agentId = data.defaultAgentId || null;
+  const recent = data.sessions?.recent?.[0];
+  const sessionKey = recent?.key || null;
+  if (
+    !agentId &&
+    typeof sessionKey === "string" &&
+    sessionKey.startsWith("agent:")
+  ) {
+    const parts = sessionKey.split(":");
+    agentId = parts[1] || null;
+  }
+  const sessionsPath = data.sessions?.path || null;
+  const sessionId = await readSessionId(sessionsPath, sessionKey);
+  await writeHealthCache({
+    ok: true,
+    agentId,
+    sessionKey,
+    sessionId,
+    sessionsPath,
+    updatedAt: Date.now(),
+  });
+  process.exit(0);
+}
+
+process.exit(1);