Gateway Upgrade Stability Doctor — Release Notes v1.0

Skill: gateway-upgrade-stability-doctor

Version: 1.0.0

Release Date: 2026-05-04

Category: orchestration

Price: $4.99

What It Does

Gateway Upgrade Stability Doctor is the read-only smoke checker that tells you whether your OpenClaw gateway and workspace survived an upgrade before you resume any cron jobs, agent pipelines, or production automations. One command checks gateway availability, cron indicators, key memory files, and optional log output — returning a clear PASS, WARN, or FAIL verdict with specific findings and human-executable fixes.

It's the first thing to run after any OpenClaw upgrade, gateway restart, or rollback concern.

Key Features

Gateway Status Check

Probes the OpenClaw gateway via openclaw gateway status with a 12-second timeout:

Confirms the gateway binary is on PATH
Verifies exit code 0 (running)
Detects failure/down keywords in status output (error, failed, down, stopped)
Records gateway PID and port evidence for audit trail

Workspace Integrity Check

Scans the OpenClaw workspace for critical files that confirm agent context survived the upgrade:

MEMORY.md — agent long-term memory (existence check only; content never read)
memory/release-pipeline.md — pipeline state file
Cron indicator files (glob *cron* up to 30 hits) — flags if scheduler has no footprint

Log File Scanning (Optional)

Pass --log to scan a gateway or application log file for upgrade-risk keywords:

Flags timeout, regression, failed, error as WARNING indicators
Reports all keyword hits found; does not parse or store log content beyond the scan

Structured JSON Report

Use --format json to get machine-readable output suitable for handoff to downstream pipeline steps or archiving as evidence.

Usage


# Standard health check (markdown output)
python3 scripts/gateway_upgrade_check.py \
  --workspace /root/.openclaw/workspace \
  --format markdown

# JSON output for pipeline handoff or archiving
python3 scripts/gateway_upgrade_check.py \
  --workspace /root/.openclaw/workspace \
  --format json

# With optional log file scan
python3 scripts/gateway_upgrade_check.py \
  --workspace /root/.openclaw/workspace \
  --format markdown \
  --log /var/log/openclaw/gateway.log

Example Output (PASS)


# Gateway Upgrade Stability Check: PASS

## Findings
- No findings.

## Evidence

{

"openclaw_path": "/usr/bin/openclaw",

"gateway_status": {

"cmd": "openclaw gateway status",

"code": 0,

"stdout": "Gateway running (pid 1437198) — 127.0.0.1:18789",

"stderr": ""

"cron_indicators": [

"memory/cron-heartbeat.md",

"skills/cron-manager-pro/SKILL.md"

]

}



---

## Example Output (WARN)

Gateway Upgrade Stability Check: WARN

Findings

WARNING MEMORY.md not found. Fix: Confirm workspace mount and agent context survived upgrade.
WARNING No cron indicator files found in workspace. Fix: If crons are expected, verify scheduler state externally.

Evidence

{ ... }



---

## Parameters

| Parameter | Description |
|-----------|-------------|
| `--workspace` | Path to OpenClaw workspace directory (default: current directory) |
| `--format` | Output format: `markdown` (default) or `json` |
| `--log` | Optional path to gateway/application log file for keyword scan |

---

## Guardrails

- **Read-only** — no file writes, no config changes, no service restarts
- Gateway is probed via a fixed CLI command: `openclaw gateway status` — no shell=True, no user-injectable arguments, timeout=12 enforced
- MEMORY.md access is an `.exists()` check only — content is never read or ingested
- `openclaw gateway status` probes loopback 127.0.0.1:18789 only — no external network reachability
- Always follow the AGENTS.md safety protocol: create a restore point before acting on any FAIL finding

---

## Requirements

- **OpenClaw:** v2026.3.23+
- **Runtime:** Python 3.8+
- **Dependencies:** None — Python standard library only (`argparse`, `json`, `shutil`, `subprocess`, `sys`, `pathlib`)
- **API keys:** None
- **Network:** Loopback only (127.0.0.1:18789 via `openclaw gateway status`)

---

## Security & Quality Clearances

| Stage | Verdict | Date |
|-------|---------|------|
| Viper QA | APPROVED_FOR_RELEASE | 2026-05-04 |
| Warlock Security Audit | SECURITY_CLEARED | 2026-05-04 |

**Security audit summary (2026-05-04):**
- Subprocess boundary: FIXED command list `[oc, 'gateway', 'status']`; `shell=False` (default); `timeout=12` set; no user-controlled input passed to subprocess; no command injection possible
- `shell=True`: ABSENT (confirmed)
- `eval`/`exec`: ABSENT (confirmed)
- Network access: INTENTIONAL — loopback 127.0.0.1:18789 only; by design for gateway probe; no external reachability
- File system: READ-ONLY — `pathlib` used for `.exists()`, `.rglob()`, `.read_text()` only; no writes
- Credential access: NONE — MEMORY.md reference is `.exists()` check only; content never read; no secrets ingested
- Obfuscation: NONE
- Dependency risk: LOW (stdlib only)
- Live smoke test: PASS (`--workspace /root/.openclaw/workspace --format json`; gateway pid 1437198, exit code 0)
- Warlock verdict: SECURITY_CLEARED — subprocess boundary is fixed command with timeout and no user shell/mutation; Viper approval covers intentional gateway probe scope

---

## Compatibility

- OpenClaw: v2026.3.23+
- Python: 3.8+
- OS: Linux, macOS, Windows (stdlib only)
- Dependencies: None

---

*Release notes prepared by Hollywood — 2026-05-04*

Gateway Upgrade Stability Doctor