failover-gateway✓ ناجح

محتوى SKILL.md

---
name: failover-gateway
version: 1.0.0
description: Set up an active-passive failover gateway for OpenClaw. Deploy a standby node that auto-promotes when your primary goes down and auto-demotes when it recovers. Includes health monitor script, systemd services, channel splitting strategy, and step-by-step deployment guide. Use when you need high availability, disaster recovery, or redundancy for your OpenClaw instance.
---

# Failover Gateway for OpenClaw

Deploy a standby OpenClaw gateway that automatically takes over when your primary goes down. Active-passive design with auto-promotion and auto-demotion.

## What You Get

- **~30 second failover** — health monitor detects primary down, promotes standby
- **Auto-recovery** — when primary comes back, standby demotes itself
- **Zero split-brain** — primary and standby use different channels (no duplicate messages)
- **Git-synced workspace** — standby pulls latest workspace on promotion
- **$12/month** — runs on a minimal VPS

## Architecture

```
PRIMARY (your main VPS)          STANDBY (failover VPS)
├─ Full stack (all channels)     ├─ Single channel only (e.g., Discord DM)
├─ All cron jobs                 ├─ No crons (recovery mode)
├─ Gateway active ✅              ├─ Gateway stopped 💤
└─ Pushes workspace to git       └─ Health monitor watches primary
                                      │
                                      ├─ Primary healthy → sleep
                                      ├─ Primary down 30s → PROMOTE
                                      └─ Primary back → DEMOTE
```

The key insight: **split your channels between primary and standby**. Don't share credentials — give each node exclusive ownership of different channels. This eliminates split-brain entirely.

### Channel Split Examples

| Setup | Primary | Standby |
|-------|---------|---------|
| RC + Discord | Rocket.Chat (full) | Discord DM only |
| Discord + Telegram | Discord (full) | Telegram DM only |
| Slack + Discord | Slack (full) | Discord DM only |

Your primary handles everything. The standby is minimal recovery — just enough to stay reachable.

## Prerequisites

- Primary OpenClaw instance running on a VPS
- A second VPS for the standby ($6-12/mo, any provider)
- [Tailscale](https://tailscale.com) mesh network (or any VPN/private network)
- Git repository for workspace sync (GitHub, GitLab, etc.)
- A second messaging channel for the standby (different from primary)

## Step-by-Step Deployment

### Phase 1: Provision the Standby VPS

Any cheap VPS works. Recommended: 2GB RAM, Ubuntu 24.04.

```bash
# Harden the box
ufw allow 22/tcp
ufw enable
apt install -y fail2ban unattended-upgrades

# Create openclaw user
adduser openclaw --disabled-password
usermod -aG sudo openclaw
# Copy your SSH key to openclaw user

# Install Tailscale
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up --hostname=your-failover-name
```

### Phase 2: Install OpenClaw

```bash
# As openclaw user
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install --lts
npm install -g openclaw

# Clone workspace
git clone <your-workspace-repo> ~/.openclaw/workspace
```

### Phase 3: Failover Config

Create a **minimal** OpenClaw config on the standby. Only enable the standby channel:

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-6",
        "fallbacks": ["anthropic/claude-sonnet-4-5"]
      },
      "workspace": "/home/openclaw/.openclaw/workspace"
    },
    "list": [{ "id": "main", "default": true }]
  },
  "channels": {
    "discord": {
      "enabled": true,
      "token": "<YOUR_DISCORD_BOT_TOKEN>",
      "dm": {
        "policy": "allowlist",
        "allowFrom": ["<YOUR_DISCORD_USER_ID>"]
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "tailnet"
  }
}
```

**Important:** Disable this channel on your primary to avoid conflicts.

Test it works: `openclaw gateway run` — verify the bot connects and responds, then stop it.

### Phase 4: Deploy Health Monitor

Copy the included `scripts/health-monitor.sh` to the standby:

```bash
sudo cp health-monitor.sh /usr/local/bin/openclaw-health-monitor.sh
sudo chmod +x /usr/local/bin/openclaw-health-monitor.sh
```

Edit the variables at the top:
- `PRIMARY_IP` — your primary's Tailscale IP
- `PRIMARY_PORT` — your primary's gateway port (default: 18789)
- `SECRETS_HOST` — (optional) host to rsync secrets from on promotion

Create the systemd services:

**`/etc/systemd/system/openclaw-health-monitor.service`**
```ini
[Unit]
Description=OpenClaw Failover Health Monitor
After=network-online.target tailscaled.service
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/openclaw-health-monitor.sh
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

**`/etc/systemd/system/openclaw.service`**
```ini
[Unit]
Description=OpenClaw Gateway (Failover)
After=network-online.target tailscaled.service
Wants=network-online.target

[Service]
Type=simple
User=openclaw
Group=openclaw
WorkingDirectory=/home/openclaw/.openclaw/workspace
ExecStart=/usr/bin/openclaw gateway run
Restart=on-failure
RestartSec=5
Environment=HOME=/home/openclaw
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
```

Enable the monitor (but NOT the gateway — the monitor starts it on promotion):

```bash
sudo systemctl daemon-reload
sudo systemctl enable openclaw-health-monitor
sudo systemctl start openclaw-health-monitor
# Do NOT enable openclaw.service — the monitor controls it
```

### Phase 5: Disable Standby Channel on Primary

This is critical. Remove or disable the standby's channel from your primary config:

```json
{
  "channels": {
    "discord": { "enabled": false }
  }
}
```

Each node owns its channels exclusively. No sharing, no conflicts.

### Phase 6: Test

```bash
# On primary — simulate failure
sudo systemctl stop openclaw-gateway  # or kill the process

# Watch the standby logs
journalctl -u openclaw-health-monitor -f

# Expected: 3 failed checks → PROMOTE → gateway starts → standby channel live

# On primary — recover
sudo systemctl start openclaw-gateway

# Expected: standby detects primary → DEMOTE → gateway stops
```

## Failover Timeline

| Time | Event |
|------|-------|
| 0s | Primary goes down |
| 10s | First health check fails |
| 20s | Second check fails |
| 30s | Third check fails → **PROMOTE** |
| 35s | Git pull, secrets sync |
| 40s | Gateway starting |
| 45s | Standby channel active |
| ~60s | **You're reachable again** |

## Edge Cases

| Scenario | Result |
|----------|--------|
| Primary dies | Standby promotes in ~30-60s |
| Primary + standby die | You're offline (add a third node?) |
| Network partition | Standby may promote while primary is still running — but since they use different channels, no conflicts |
| Standby reboots | Health monitor auto-restarts (systemd), resumes watching |
| Primary flaps | Promote/demote cycles — health monitor handles it, but consider increasing FAIL_THRESHOLD |

## Failback

Recovery is automatic. When the primary comes back:

1. Health monitor detects primary healthy
2. Stops the standby gateway
3. Primary resumes all channels
4. Standby returns to watching

No manual intervention needed.

## Cost

| Component | Cost |
|-----------|------|
| VPS (2GB RAM) | $6-12/mo |
| Tailscale | Free (personal) |
| Git repo | Free |
| **Total** | **$6-12/mo** |

## Tips

- **Test monthly.** Kill your primary, verify failover works. Trust but verify.
- **Keep the standby minimal.** No crons, no extra channels. It's recovery mode.
- **Git push frequently.** The standby's workspace is only as fresh as your last push.
- **Use Tailscale.** It makes cross-VPS networking trivial. No firewall rules, no port forwarding.
- **Different bot tokens.** If using Discord on both, you need two bot applications. Same bot token = last-connect-wins.
- **Monitor the monitor.** Check `journalctl -u openclaw-health-monitor` occasionally to make sure it's running.

الترخيص

الترخيص المُعلن: MIT

MIT License

Copyright (c) 2026 openclaw

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.

عرض الترخيص في المستودع المصدري — النسخة المنشورة هناك هي المرجع.