openclaw-watcher 0.0.1

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pnpm tsc:*)"
+    ]
+  }
+}

package/.dockerignore

@@ -0,0 +1,21 @@
+node_modules
+dist
+logs
+*.log
+.env
+.env.local
+.git
+.gitignore
+README.md
+CHANGELOG.md
+USAGE_GUIDE.md
+*.md
+.vscode
+.idea
+coverage
+.nyc_output
+tmp
+temp
+*.tmp
+config-backups
+.DS_Store

package/.env.example

@@ -0,0 +1,31 @@
+# OpenClaw Configuration
+OPENCLAW_GATEWAY_URL=http://localhost:10002
+OPENCLAW_HEALTH_ENDPOINT=/health
+OPENCLAW_CONFIG_PATH=~/.openclaw
+
+# Health Check Configuration
+HEALTH_CHECK_INTERVAL=30000
+HEALTH_CHECK_TIMEOUT=10000
+MAX_RETRY_ATTEMPTS=3
+FAILURE_THRESHOLD=3
+
+# AI Configuration
+# Choose 'claude' or 'kimi' - both use CLI tools (claude code / kimi code)
+AI_PROVIDER=claude
+# No API keys needed - uses CLI tools directly
+
+# Recovery Protection
+MAX_RECOVERY_RETRIES=3
+RECOVERY_COOLDOWN_MS=300000
+
+# Change Tracking
+USE_GIT_TRACKING=true
+GIT_COMMIT_MESSAGE_PREFIX=[AutoFix]
+BACKUP_CONFIG_BEFORE_CHANGE=true
+
+# Watcher Home Directory (config + logs)
+# WATCHER_HOME=~/.openclaw-watcher
+
+# Logging
+LOG_LEVEL=info
+# LOG_FILE_PATH defaults to $WATCHER_HOME/logs/healthcheck.log

package/.eslintrc.json

@@ -0,0 +1,26 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "plugins": ["@typescript-eslint"],
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module",
+    "project": "./tsconfig.json"
+  },
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      { "argsIgnorePattern": "^_" }
+    ],
+    "no-console": "warn"
+  }
+}

package/.prettierrc.json

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "endOfLine": "lf"
+}

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-02-01
+
+### 🚀 Major Architecture Upgrade
+
+**核心改变**：AI 直接修复问题，而不是返回诊断建议
+
+### Breaking Changes
+
+- ❌ 移除 API 调用方式（Claude API、Kimi API）
+- ✅ 改用 CLI 工具（Claude Code CLI、Kimi Code CLI）
+- ❌ 移除配置项：`CLAUDE_API_KEY`、`KIMI_API_KEY`
+- ✅ 新增配置项：`AI_TIMEOUT`（默认 5 分钟）
+
+### Added
+
+#### AI 直接修复能力
+- 🤖 AI 使用完整工具集（Read、Edit、Write、Bash）直接修复问题
+- ⚡ 迭代式修复：AI 会持续尝试直到问题解决
+- ✅ AI 自主验证：修复后自动验证是否成功
+- 📊 标准化摘要：AI 输出规范化的修复报告
+
+#### 统一 System Prompt
+- 📝 Claude Code 和 Kimi Code 共用同一个 System Prompt
+- 🎯 保证两个 AI 的行为一致性
+- 🔧 可自定义修复策略和指导方针
+
+#### 增强的变更追踪
+- 📝 AI 修复后自动提交到 Git
+- 📊 JSON 日志记录完整的修复过程
+- 🔍 包含：问题、原因、修复措施、修改文件、执行命令
+
+### Changed
+
+#### 工作流程优化
+```
+旧: 健康检查 → AI 返回诊断 → 程序解析 → 程序执行 → 可能失败
+新: 健康检查 → AI 直接修复 → AI 验证 → AI 总结 → 程序记录 → 完成
+```
+
+#### 架构调整
+- `ai/claude-client.ts` → `ai/cli-client.ts`（统一 CLI 客户端）
+- `ai/kimi-client.ts` → 删除（合并到 cli-client.ts）
+- `recovery/auto-fixer.ts` → 简化为只记录 AI 已完成的修复
+- `recovery/config-manager.ts` → 已弃用（AI 直接修改配置）
+
+### Improved
+
+- 🎯 修复成功率提升：AI 可以迭代尝试多次
+- ⚡ 修复速度提升：不需要往返通信
+- 🔒 安全性提升：Git 完整记录所有变更
+- 📊 可观察性提升：标准化的修复摘要
+
+### Documentation
+
+- ✨ 更新 README.md：强调 AI 直接修复能力
+- 📖 更新 QUICKSTART.md：简化配置步骤
+- 🎓 新增 `prompts/fix-openclaw.md`：AI System Prompt
+- 🔧 更新所有示例和文档
+
+---
+
+## [1.0.0] - 2026-02-01
+
+### Added（已废弃，见 v2.0.0）
+
+- 🎉 Initial release（原始版本）
+- ✨ 基于诊断 + 程序执行的修复方案（已废弃）
+- 🤖 Claude CLI / Kimi API 集成（API 方式已废弃）
+
+### Configuration
+
+- Environment-based configuration
+- Support for custom OpenClaw paths
+- Configurable AI provider selection
+- Adjustable health check parameters
+- Git tracking toggle
+- Backup system toggle
+
+### Documentation
+
+- Comprehensive README with examples
+- Architecture diagrams
+- Configuration guide
+- Security considerations
+- Troubleshooting guide
+- Development setup instructions

package/Dockerfile

@@ -0,0 +1,47 @@
+FROM node:22-alpine AS builder
+
+# Install pnpm
+RUN npm install -g pnpm
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json pnpm-lock.yaml* ./
+
+# Install dependencies
+RUN pnpm install --frozen-lockfile
+
+# Copy source code
+COPY . .
+
+# Build
+RUN pnpm run build
+
+# Production image
+FROM node:22-alpine
+
+# Install pnpm
+RUN npm install -g pnpm
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json pnpm-lock.yaml* ./
+
+# Install production dependencies only
+RUN pnpm install --prod --frozen-lockfile
+
+# Copy built files
+COPY --from=builder /app/dist ./dist
+
+# Create logs directory
+RUN mkdir -p /app/logs
+
+# Set environment
+ENV NODE_ENV=production
+
+# Expose port (if needed for metrics)
+# EXPOSE 9090
+
+# Run the service
+CMD ["node", "dist/index.js"]

package/README.md

@@ -0,0 +1,408 @@
+# OpenClaw Watcher 🛡️
+
+AI-powered automated health monitoring and self-healing CLI tool for OpenClaw Gateway.
+
+[![npm version](https://img.shields.io/npm/v/openclaw-watcher.svg)](https://www.npmjs.com/package/openclaw-watcher)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🌟 What is OpenClaw Watcher?
+
+OpenClaw Watcher is a CLI tool that automatically monitors your OpenClaw Gateway and uses AI (Claude Code or Kimi Code) to **directly diagnose and fix** issues when they occur. No more manual interventions or 3am wake-up calls!
+
+### Key Features
+
+- 🔍 **Automated Health Monitoring**: Continuous health checks of your OpenClaw Gateway
+- 🤖 **AI-Powered Repair**: AI directly fixes issues using complete tool capabilities
+- ⚡ **Iterative Fixing**: AI keeps trying until the problem is resolved
+- 🔒 **Secure Config Management**: Automatic Git tracking with sensitive data protection
+- 📊 **Complete Audit Trail**: Full history of all AI repairs in files
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js >= 22
+- OpenClaw Gateway installed
+- **Claude Code CLI** or **Kimi Code CLI** (at least one)
+
+```bash
+# Install Claude Code CLI (recommended)
+# https://github.com/anthropics/claude-code
+
+# OR install Kimi Code CLI
+# https://platform.moonshot.cn/docs/code
+```
+
+### Installation & Setup
+
+```bash
+# Initialize (interactive setup)
+npx openclaw-watcher init
+```
+
+The interactive setup will guide you through:
+
+1. OpenClaw configuration directory
+2. Gateway URL and port
+3. Health check settings
+4. AI provider selection
+5. Git repository initialization
+
+### Start Monitoring
+
+```bash
+# Start monitoring
+npx openclaw-watcher start
+```
+
+### Check Status
+
+```bash
+# View current status
+npx openclaw-watcher status
+```
+
+## 📖 Full Documentation
+
+- **[CLI Guide](./CLI_GUIDE.md)** - Complete CLI command reference
+- **[Architecture](./ARCHITECTURE.md)** - System design and architecture
+- **[Quick Start (Chinese)](./QUICKSTART.md)** - 中文快速开始指南
+
+## 🎯 How It Works
+
+```
+┌─────────────────┐
+│  Health Check   │  Every 30s (configurable)
+└────────┬────────┘
+         │ Fails 3x (configurable)
+         ▼
+┌─────────────────┐
+│  AI Triggered   │  Claude/Kimi Code CLI
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  AI Diagnosis   │  Read configs, logs, status
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   AI Repairs    │  Edit files, run commands
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  AI Verifies    │  Restart, check status
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Git Commit     │  Auto-commit changes
+└────────┬────────┘
+         │ (if GitHub sync enabled)
+         ▼
+┌─────────────────┐
+│  GitHub Push    │  Best-effort, never blocks
+└─────────────────┘
+```
+
+## 🔒 Security Features
+
+### Safe Configuration Management
+
+OpenClaw Watcher creates two configuration files:
+
+- `openclaw.json` - Real config with secrets (**NOT tracked in Git**)
+- `openclaw.safe.json` - Template with redacted secrets (**tracked in Git**)
+
+Example:
+
+```json
+// openclaw.json (real, gitignored)
+{
+  "apiKey": "sk-ant-api03-xxx-real-key-xxx",
+  "token": "actual-secret-token"
+}
+
+// openclaw.safe.json (tracked in Git)
+{
+  "apiKey": "<YOUR_API_KEY_HERE>",
+  "token": "<YOUR_TOKEN_HERE>"
+}
+```
+
+### Pre-commit Hook
+
+Automatically prevents:
+
+- ❌ Committing `openclaw.json`
+- ❌ Committing actual API keys/tokens in `openclaw.safe.json`
+- ❌ Accidental sensitive data leaks
+
+### Automatic Git Workflow
+
+Every AI repair:
+
+1. ✅ Updates `openclaw.safe.json` from `openclaw.json`
+2. ✅ Redacts all sensitive data
+3. ✅ Runs security checks
+4. ✅ Commits to Git with detailed message
+
+## 📋 CLI Commands
+
+### `init` - Initialize
+
+```bash
+npx openclaw-watcher init [options]
+```
+
+Options:
+
+- `--no-git` - Skip Git repository initialization
+
+### `start` - Start Monitoring
+
+```bash
+npx openclaw-watcher start [options]
+```
+
+Options:
+
+- `-d, --daemon` - Run as daemon process
+
+### `status` - Show Status
+
+```bash
+npx openclaw-watcher status
+```
+
+Shows:
+
+- Current configuration
+- Repair history
+- Last repair details
+
+### `config` - Manage Config
+
+```bash
+npx openclaw-watcher config [options]
+```
+
+Options:
+
+- `-s, --show` - Display current configuration
+- `-e, --edit` - Edit configuration file
+
+## 🛠️ Configuration
+
+After initialization, config and logs are stored in `~/.openclaw-watcher/` (customizable via `WATCHER_HOME` env var):
+
+```json
+{
+  "monitor": {
+    "gatewayUrl": "http://localhost:10002",
+    "healthEndpoint": "/health",
+    "checkInterval": 30000,
+    "failureThreshold": 3
+  },
+  "ai": {
+    "provider": "claude",
+    "timeout": 300000
+  },
+  "recovery": {
+    "useGitTracking": true,
+    "useGitHubCli": false,
+    "openclawConfigPath": "~/.openclaw",
+    "maxRecoveryRetries": 3,
+    "recoveryCooldownMs": 300000
+  }
+}
+```
+
+## 📊 Example Scenario
+
+### Problem: Gateway Crashes
+
+```
+1. Health check fails 3 times consecutively
+2. AI is triggered
+3. AI reads error logs: "Port 10002 already in use"
+4. AI diagnoses: Port conflict
+5. AI fixes: Changes port to 10003 in openclaw.json
+6. AI restarts: openclaw gateway restart
+7. AI verifies: Gateway is now healthy
+8. System commits: Updates openclaw.safe.json, commits to Git
+```
+
+### Git Commit Message
+
+```
+[AutoFix] Gateway failed to start - Port conflict
+
+Root Cause: Port 10002 was already in use by another process
+Fix Applied: Changed gateway port from 10002 to 10003 in openclaw.json
+
+
+Files Modified:
+- openclaw.json: Updated port configuration
+
+Commands Executed:
+- openclaw gateway restart
+
+Applied by: AI Auto-Fix System
+```
+
+## 🌐 Git Repository
+
+Watcher manages the entire `~/.openclaw` directory as a Git repository — not just repair history, but also agent configurations and any tracked files. Sensitive data (API keys, sessions, cache) is automatically excluded via `.gitignore`.
+
+```
+~/.openclaw/
+├── .git/
+│   └── hooks/
+│       └── pre-commit              # Security hook
+├── .gitignore                      # Git ignore rules
+├── README.md                       # Auto-generated docs
+├── openclaw.json                   # Real config (NOT tracked)
+├── openclaw.safe.json              # Safe template (tracked)
+├── agents/*/agent/auth-profiles.json  # API keys (NOT tracked)
+├── agents/*/sessions/              # Session history (NOT tracked)
+├── memory/*.sqlite                 # Vector index (NOT tracked)
+└── cache/                          # Cache (NOT tracked)
+```
+
+### .gitignore Coverage
+
+The auto-generated `.gitignore` excludes sensitive and temporary files:
+
+| Pattern | Reason |
+|---------|--------|
+| `openclaw.json` | Contains API keys and tokens |
+| `agents/*/agent/auth-profiles.json` | Agent authentication credentials |
+| `agents/*/sessions/` | Session history (large + privacy) |
+| `memory/*.sqlite` | Vector index databases (large) |
+| `cache/` | Temporary cache files |
+| `*.log` | Log files |
+
+### GitHub Sync (Optional)
+
+You can optionally push the repository to a private GitHub repo using the [GitHub CLI](https://cli.github.com):
+
+```bash
+# During init, answer "Yes" to "Sync repair history to GitHub?"
+npx openclaw-watcher init
+```
+
+**Requirements**: `gh` CLI installed and authenticated (`gh auth login`).
+
+**How it works**:
+
+- During `init`: creates a private GitHub repo and pushes the initial commit
+- During monitoring: auto-pushes to GitHub after each repair commit (best-effort — push failures never block recovery)
+- Repo name is auto-generated: `openclaw-config-<hostname>`
+
+If `gh` is not installed or not authenticated during init, the setup warns and continues — you can always configure GitHub sync later.
+
+### View Repair History
+
+```bash
+cd ~/.openclaw
+git log --oneline --grep="\[AutoFix\]"
+```
+
+### Rollback a Bad Fix
+
+```bash
+cd ~/.openclaw
+git log --oneline -5
+git revert <commit-hash>
+openclaw gateway restart
+```
+
+## 🎓 Advanced Usage
+
+### Run as System Service (systemd)
+
+```bash
+# Create service file
+sudo vim /etc/systemd/system/openclaw-watcher.service
+```
+
+```ini
+[Unit]
+Description=OpenClaw Watcher
+After=network.target
+
+[Service]
+Type=simple
+User=openclaw
+WorkingDirectory=/path/to/project
+ExecStart=/usr/bin/npx openclaw-watcher start
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable openclaw-watcher
+sudo systemctl start openclaw-watcher
+```
+
+### Multiple Instances
+
+```bash
+# Instance 1
+cd ~/project-1
+npx openclaw-watcher init  # Configure for instance 1
+npx openclaw-watcher start
+
+# Instance 2
+cd ~/project-2
+npx openclaw-watcher init  # Configure for instance 2
+npx openclaw-watcher start
+```
+
+## ❓ FAQ
+
+### Q: What if AI can't fix the issue?
+
+A: The system has built-in retry protection:
+
+- **Max retries**: After 3 consecutive failed recovery attempts (configurable via `maxRecoveryRetries`), the system stops retrying and logs a warning requesting manual intervention.
+- **Cooldown**: After each recovery attempt (success or failure), a 5-minute cooldown period (configurable via `recoveryCooldownMs`) prevents rapid-fire retries.
+- **Fallback**: If the primary AI provider (e.g. Claude) fails, the system automatically tries the fallback provider (e.g. Kimi) before counting it as a failure.
+
+All attempts are logged in detail for manual investigation.
+
+### Q: Is it safe to let AI modify configs?
+
+A: Yes! All changes are:
+
+- ✅ Committed to Git (easy rollback)
+- ✅ Verified after fixing
+- ✅ Logged in detail
+- ✅ Protected by pre-commit hooks
+
+### Q: Can I review changes before they're applied?
+
+A: Currently no - AI applies fixes immediately. However, all changes are in Git, so you can review and rollback if needed.
+
+### Q: Does it work with other services besides OpenClaw?
+
+A: Currently designed specifically for OpenClaw. Contributions welcome for other services!
+
+## 🤝 Contributing
+
+Issues and Pull Requests are welcome!
+
+## 📄 License
+
+MIT License
+
+## 🔗 Links
+
+- [OpenClaw Documentation](https://openclaw.io)
+- [Claude Code CLI](https://github.com/anthropics/claude-code)
+- [Kimi Code CLI](https://platform.moonshot.cn/docs/code)

package/build.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+set -e
+
+echo "🔨 Building OpenClaw Watcher..."
+
+# Clean previous build
+echo "Cleaning previous build..."
+rm -rf dist
+
+# Install dependencies
+echo "Installing dependencies..."
+pnpm install
+
+# Type check
+echo "Running type check..."
+pnpm run type-check
+
+# Build
+echo "Building..."
+pnpm run build
+
+# Make CLI executable
+echo "Setting executable permissions..."
+chmod +x dist/cli.js
+
+echo "✅ Build completed successfully!"
+echo ""
+echo "Usage:"
+echo "  npx . init          # Initialize configuration"
+echo "  npx . start         # Start monitoring"
+echo "  npx . status        # Check status"
+echo "  npx . config        # Manage configuration"

package/dist/ai/ai-orchestrator.d.ts

@@ -0,0 +1,11 @@
+import { AIClientConfig, DiagnosisResult, RecoveryConfig } from '../types';
+export declare class AIOrchestrator {
+    private primaryClient;
+    private fallbackClient?;
+    private configPath;
+    constructor(aiConfig: AIClientConfig, recoveryConfig: RecoveryConfig);
+    initialize(): Promise<void>;
+    diagnoseAndFix(error: string): Promise<DiagnosisResult>;
+    private fallbackDiagnosis;
+}
+//# sourceMappingURL=ai-orchestrator.d.ts.map

package/dist/ai/ai-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-orchestrator.d.ts","sourceRoot":"","sources":["../../src/ai/ai-orchestrator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE1E,qBAAa,cAAc;IACzB,OAAO,CAAC,aAAa,CAAY;IACjC,OAAO,CAAC,cAAc,CAAC,CAAY;IACnC,OAAO,CAAC,UAAU,CAAS;gBAEf,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc;IAW9D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B3B,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;YAoB/C,iBAAiB;CA2BhC"}