gateway-guardian

# Gateway Guardian — Skill Instructions

## Triggers

Activate this skill when the user:
- Shares `https://github.com/Dios-Man/gateway-guardian` and asks to install it
- Says "install gateway-guardian", "帮我安装", "install this skill", or similar
- Says "gateway-guardian status", "guardian status", "guardian 运行正常吗", or similar
- Says "uninstall gateway-guardian", "卸载 gateway-guardian", or similar

---

## Installation (AI-executed)

### Pre-flight checks

1. Confirm the system is Linux with `systemd --user` available:
   ```bash
   systemctl --user status 2>&1 | head -3
   ```
2. Check and install `inotify-tools` if missing:
   ```bash
   if ! which inotifywait > /dev/null 2>&1; then
       sudo apt-get install -y inotify-tools
   fi
   ```
3. Confirm OpenClaw is installed and the gateway is running.

### Determine notification fallback

Read from the current inbound message metadata:
- `channel`: messaging platform (feishu / telegram / discord / etc.)
- `chat_type`: conversation type (direct / group)
- `sender_id`

Set `FALLBACK_TARGET` (used when dynamic session detection fails):
- **Feishu**: `user:{sender_id}` — always send a DM, even if installed from a group
- **Telegram**: use `chat_id` for DMs; for groups, ask the user for their personal numeric Telegram ID
- **Discord**: ask the user for their DM channel ID

### Determine notification language (LOCALE)

Detect the language the user is communicating in during this conversation:
- User is writing in Chinese → `LOCALE=zh`
- User is writing in English → `LOCALE=en`
- Language is unclear or mixed → ask the user: "Should notifications be sent in Chinese or English?"

### Installation steps

**Step 1 — Back up current config**
```bash
TIMESTAMP_DIR="$HOME/.openclaw/config-backups"
mkdir -p "$TIMESTAMP_DIR"
cp "$HOME/.openclaw/openclaw.json" \
   "$TIMESTAMP_DIR/openclaw.json.$(date +%Y%m%d-%H%M%S).preinstall"
echo "Backup created: $(ls -t $TIMESTAMP_DIR | head -1)"
```

**Step 2 — Download skill files**
``...

# Gateway Guardian

<p align="center">中文丨<a href="https://github.com/Dios-Man/gateway-guardian/blob/main/README.en.md">English</a></p>

<p align="center">
  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
  <img src="https://img.shields.io/badge/platform-Linux-blue.svg" alt="Platform: Linux">
  <img src="https://img.shields.io/badge/OpenClaw-Skill-brightgreen.svg" alt="OpenClaw Skill">
</p>

> 一个给 OpenClaw 用户的网关防护 Skill。  
> 配置写坏了自动回滚，网关崩溃了自动重启，出事第一时间通知你。

---

## 它解决什么问题？

OpenClaw 的 AI 能力完全依赖网关（Gateway）。网关一旦挂掉，你就联系不上 AI 了。

常见的"网关挂掉"原因有两种：

**1. 配置文件被写坏**  
AI 在修改配置（比如添加 API Key、切换模型）时，可能因为格式错误或字段缺失，让 `openclaw.json` 变成无效文件。下次网关重启时直接起不来。

**2. 网关进程意外崩溃**  
内存问题、系统资源紧张、偶发性 bug，都可能让网关在运行中突然挂掉。

Gateway Guardian 会自动处理这两种情况，并在第一时间通知你。

---

## 工作方式

### 配置守护（实时）

每次 `openclaw.json` 发生变化，Guardian 会在毫秒内完成三关验证：

1. JSON 语法是否正确
2. 关键字段是否存在（`gateway.port` 必须有）
3. OpenClaw 自身的 schema 校验

验证失败时立刻回滚到最近一个合法备份。整个过程自动完成，无需你介入。

### 崩溃恢复（OnFailure）

如果网关在 60 秒内连续崩溃 3 次，Guardian 接管：
1. 检查配置是否有问题（有则先回滚）
2. 重启网关
3. 等待最多 30 秒确认端口可用
4. 成功则通知你，失败则发紧急告警

### 通知

无论是自动修复还是需要人工处理，都会推送通知到你的消息渠道（飞书 / Telegram / Discord 等）。

---

## 通知示例

**配置自动修复（无需操作）：**

```
✅ OpenClaw 网关守护

⏰ 时间：2026-03-09 22:10
📋 事件：配置文件损坏，已自动回滚并恢复
🔧 回滚至：openclaw.json.20260309-221005
📝 关键日志：
[22:10:03] ❌ Config invalid: missing gateway.port
[22:10:04] ✅ Rolled back to timestamp backup
[22:10:04] ✅ Gateway is running

💬 如果此次告警是由我的操作引起的，请将这条消息直接转发给我，
无需添加任何说明，我会自动了解情况并继续处理。
```...