功能描述

OpenClaw Gateway 黄金包活机制，确保 7x24 小时稳定运行

使用说明 (SKILL.md)

Gateway Keepalive Skill (黄金包活机制)

Name: Gateway Keepalive
Author: jooey

用途: 确保 OpenClaw Gateway 7x24 小时稳定运行

触发: 系统自动运行，无需手动触发

架构

┌─────────────────────────────────────────────────────────┐
│                    黄金包活机制                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Layer 1: LaunchAgent KeepAlive (秒级)                  │
│  ├─ KeepAlive: true                                     │
│  ├─ ThrottleInterval: 1 秒                              │
│  └─ 进程崩溃 → 1 秒内自动重启                            │
│                                                         │
│  Layer 2: Health Check (每分钟)                         │
│  ├─ 检测进程 + 端口 18789                               │
│  ├─ 连续失败 3 次 → 触发恢复                             │
│  ├─ 恢复黄金备份配置                                     │
│  └─ 发送通知 (系统 + Telegram)                          │
│                                                         │
│  Layer 3: 日志轮转                                      │
│  ├─ 超过 5MB 自动压缩                                   │
│  └─ 保留 30 天内的日志                                   │
│                                                         │
└─────────────────────────────────────────────────────────┘

安装

# 一键安装
bash ~/.openclaw/skills/gateway-keepalive/scripts/install.sh

使用

查看状态

# 检查服务状态
bash ~/.openclaw/skills/gateway-keepalive/scripts/status.sh

# 或直接使用 openclaw
openclaw gateway status
launchctl list | grep openclaw

查看日志

# 健康检测日志（会轮转）
tail -f ~/.openclaw/logs/health-recovery.log

# 恢复历史（永久保留）
cat ~/.openclaw/logs/recovery-history.log

# Gateway 日志
tail -f ~/.openclaw/logs/gateway.log

恢复历史

重要：恢复历史永久保留，不受日志轮转影响。

# 查看所有恢复记录
cat ~/.openclaw/logs/recovery-history.log

# 统计成功恢复次数
grep -c "自动恢复成功" ~/.openclaw/logs/recovery-history.log

# 统计失败次数
grep -c "自动恢复失败" ~/.openclaw/logs/recovery-history.log

日志轮转规则：

health-recovery.log：超过 5MB 压缩，保留 30 天
recovery-history.log：永久保留（只记录恢复事件）

更新黄金备份

重要: 每次重大配置变更后，更新黄金备份！

cp ~/.openclaw/openclaw.json ~/.openclaw/backups/golden-config/openclaw.json

手动恢复

# 触发手动恢复
bash ~/.openclaw/scripts/health-check-recovery.sh

统计

查看黄金包活机制的历史效果：

# 自动恢复次数
grep -c "自动恢复成功" ~/.openclaw/logs/health-recovery.log*

# 失败次数
grep -c "自动恢复失败" ~/.openclaw/logs/health-recovery.log*

# 总检测次数
grep -c "健康检测通过" ~/.openclaw/logs/health-recovery.log*

配置参数

核心参数:

参数	默认值	说明
`ThrottleInterval`	1 秒	Gateway 重启间隔
`StartInterval`	60 秒	健康检查间隔
`MAX_FAILURES`	3 次	触发恢复的连续失败次数
`GATEWAY_PORT`	18789	Gateway 端口
`LOG_MAX_SIZE_MB`	5	日志轮转阈值
`LOG_KEEP_DAYS`	30	日志保留天数

通知配置（可选）:

参数	说明
`TELEGRAM_BOT_TOKEN`	Telegram Bot Token（可选）
`TELEGRAM_CHAT_ID`	Telegram Chat ID（可选）

配置文件位置：~/.openclaw/config/keepalive.conf

# 编辑配置
nano ~/.openclaw/config/keepalive.conf

# 配置示例
TELEGRAM_BOT_TOKEN="123456789:ABCdef..."
TELEGRAM_CHAT_ID="123456789"

注意：

Telegram 通知是可选的，不配置也正常运行
系统通知（macOS Notification Center）始终启用
敏感信息不会包含在发布的技能包中

测试指南

测试 Layer 1 (KeepAlive)

目的：验证进程崩溃后能否秒级重启

# 1. 记录当前 PID
PID=$(pgrep -f "openclaw gateway")
echo "当前 PID: $PID"

# 2. 手动杀死进程
kill -9 $PID

# 3. 等待 1-2 秒，检查是否自动重启
sleep 2
pgrep -f "openclaw gateway"

# 预期结果：进程自动重启，PID 变化

测试 Layer 2 (Health Check)

目的：验证健康检测和自动恢复机制

# 方法 1: 停止 Gateway LaunchAgent
launchctl stop ai.openclaw.gateway

# 等待 3-5 分钟（需要连续失败 3 次）
# 观察日志：
tail -f ~/.openclaw/logs/health-recovery.log

# 预期结果：
# - 检测到失败（❌ Gateway 进程不存在）
# - 失败计数累加（1/3, 2/3, 3/3）
# - 触发自动恢复
# - 恢复成功（✅ 自动恢复成功）

# 方法 2: 手动运行检测脚本
bash ~/.openclaw/scripts/health-check-recovery.sh

验证机制起作用

1. 查看恢复历史（永久保留）：

cat ~/.openclaw/logs/recovery-history.log

# 输出示例：
# [2026-03-06 23:11:52] 🚨 触发自动恢复 - 原因: Gateway 进程不存在
# [2026-03-06 23:12:09] ✅ 自动恢复成功

2. 统计恢复次数：

# 成功次数
grep -c "自动恢复成功" ~/.openclaw/logs/recovery-history.log

# 失败次数
grep -c "自动恢复失败" ~/.openclaw/logs/recovery-history.log

# 总触发次数
grep -c "触发自动恢复" ~/.openclaw/logs/recovery-history.log

3. 检查 LaunchAgent 状态：

# 查看服务是否运行
launchctl list | grep openclaw

# 预期输出：
# 66266  -15  ai.openclaw.gateway
# -      0    com.openclaw.health-check

# 第一列是 PID（- 表示服务在运行但无进程）
# 第二列是退出码（0 = 正常，-15 = 被信号终止）

4. 查看实时日志：

# 健康检测日志
tail -f ~/.openclaw/logs/health-recovery.log

# 每分钟应该看到：
# [2026-03-08 10:30:00] 🔍 开始健康检测
# [2026-03-08 10:30:00] ✅ 健康检测通过
# [2026-03-08 10:30:00] ✅ 黄金备份已更新（健康检测通过）

快速状态检查

# 一键检查
~/.openclaw/skills/gateway-keepalive/scripts/status.sh

# 或手动检查
openclaw gateway status          # Gateway 状态
launchctl list | grep openclaw   # LaunchAgent 状态
cat ~/.openclaw/state/recovery-count  # 失败计数

故障排查

Gateway 无法启动

tail -50 ~/.openclaw/logs/gateway.err.log
openclaw gateway config
openclaw gateway start

健康检查失败

bash ~/.openclaw/scripts/health-check-recovery.sh
cat ~/.openclaw/state/recovery-count

自动恢复失败

ls -la ~/.openclaw/backups/golden-config/
cp ~/.openclaw/backups/golden-config/openclaw.json ~/.openclaw/openclaw.json
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

卸载

# 一键卸载
bash ~/.openclaw/skills/gateway-keepalive/scripts/uninstall.sh

文件清单

~/.openclaw/skills/gateway-keepalive/
├── SKILL.md                          # 本文件
├── scripts/
│   ├── install.sh                    # 安装脚本
│   ├── uninstall.sh                  # 卸载脚本
│   └── status.sh                     # 状态检查
└── docs/
    └── gateway-keepalive-setup-guide.md  # 详细安装指南

~/.openclaw/scripts/
└── health-check-recovery.sh          # 健康检测脚本

~/Library/LaunchAgents/
├── ai.openclaw.gateway.plist         # Gateway LaunchAgent
└── com.openclaw.health-check.plist   # 健康检测 LaunchAgent

~/.openclaw/backups/golden-config/
└── openclaw.json                     # 黄金备份配置

依赖

系统: macOS (LaunchAgent)
OpenClaw: 2026.3.2+
端口: 18789 (可配置)

维护者

康妃 (config) - 配置管理与系统稳定性

更新记录

日期	版本	变更
2026-03-08	1.1.0	添加日志轮转机制，打包为 skill
2026-03-07	1.0.0	初始版本

安全使用建议

This skill appears to do what it says: install user LaunchAgents, run a periodic health-check, and restore a golden OpenClaw config when needed. Before installing: 1) Inspect ~/.openclaw/backups/golden-config/openclaw.json to ensure it doesn't contain secrets you don't want duplicated or permanently retained. 2) Be aware the installer will create ~/Library/LaunchAgents/*.plist and run launchctl bootstrap/bootout commands (user-level, not system-wide). 3) If you enable Telegram notifications, the Bot Token and Chat ID are stored in plaintext under ~/.openclaw/config/keepalive.conf — treat those like credentials. 4) The skill preserves a recovery-history log permanently by design; if that is a concern, modify the scripts or adjust retention. 5) As with any script that manipulates configs and restarts services, review the included scripts (install.sh, health-check-recovery.sh, status.sh, uninstall.sh) and back up your current ~/.openclaw/openclaw.json before running the installer. If you want a tighter security posture, remove or redact sensitive fields from the golden backup and avoid enabling Telegram integration.

功能分析

Type: OpenClaw Skill Name: gateway-keepalive Version: 1.1.1 The skill bundle provides a legitimate high-availability and monitoring solution for the OpenClaw Gateway on macOS. It implements a two-layer 'keepalive' mechanism using macOS LaunchAgents for process persistence and a bash script (health-check-recovery.sh) for application-level health monitoring and automated configuration recovery. While it utilizes potentially risky capabilities such as system persistence, configuration modification, and network access for Telegram notifications, these actions are transparently documented, user-configured, and strictly aligned with the stated purpose of ensuring 24/7 operation. No evidence of malicious intent, data exfiltration, or unauthorized remote control was found.

能力评估

✓ Purpose & Capability

Name/description match what the package installs and instructs: macOS LaunchAgents for process keepalive, a periodic health-check script, log rotation, and golden-config restore. The required files and the actions (copying configs, using launchctl, checking port 18789) are consistent with providing an auto-recovery/keepalive mechanism.

ℹ Instruction Scope

The runtime instructions and scripts operate on user home paths (~/.openclaw) and create user LaunchAgents under ~/Library/LaunchAgents. They read and write the OpenClaw config (copying current config to backups and restoring a golden config) and permanently append to a recovery-history log. This behavior is expected for an auto-recovery feature, but it does mean the skill will read/write potentially sensitive configuration files and preserve recovery history permanently unless removed.

✓ Install Mechanism

There is no external binary download; installation is script-driven (install.sh) that copies bundled scripts and writes launchd plist files. That is a low-to-moderate risk install pattern but coherent for this functionality—no remote URLs or extracted archives were used.

ℹ Credentials

The skill requests no global environment variables, but the installer optionally prompts for Telegram bot token and chat id which it stores in ~/.openclaw/config/keepalive.conf in plaintext. Given the functionality, storing/using those tokens is expected, but users should be aware tokens are stored locally and the scripts may send notifications to Telegram if configured.

ℹ Persistence & Privilege

The installer creates and loads user-level LaunchAgents and bootstraps them via launchctl so the health-check and gateway services run persistently. always:false is correctly set; the skill does not demand platform-wide 'always' privileges, but it will create persistent user-level services which will auto-run at user login/intervals.

版本历史

v1.1.1

测试版本

v1.1.0

gateway-keepalive 1.1.0 - 新增日志轮转机制，健康检测日志超过 5MB 自动压缩，保留 30 天，恢复历史永久保留 - 技能结构文档化，详细描述三层包活架构（LaunchAgent、健康检测、日志轮转） - 支持 Telegram 通知（可选），系统通知始终启用 - 一键安装、卸载与状态检查脚本完善 - 文档新增详细测试与故障排查指南

元数据

Slug gateway-keepalive

版本 1.1.1

许可证 —

累计安装 2

当前安装数 2

历史版本数 2

常见问题

Gateway Keepalive 是什么？

OpenClaw Gateway 黄金包活机制，确保 7x24 小时稳定运行. 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 281 次。

如何安装 Gateway Keepalive？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install gateway-keepalive」即可一键安装，无需额外配置。

Gateway Keepalive 是免费的吗？

是的，Gateway Keepalive 完全免费（开源免费），可自由下载、安装和使用。

Gateway Keepalive 支持哪些平台？

Gateway Keepalive 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 Gateway Keepalive？

由 jooey（@jooey）开发并维护，当前版本 v1.1.1。

Gateway Keepalive