clawbox-gateway.service restart limiter does not stop permanent startup failures

[jamesachurchill]

What happened?

clawbox-gateway.service can restart indefinitely after a permanent OpenClaw startup/config failure.

The current unit uses:

Restart=always
RestartSec=5

On the affected ClawBox, the effective systemd defaults were 5 starts in a 10-second interval. A failed OpenClaw startup plus the 5-second restart delay took longer than that interval, so the limiter never accumulated enough starts to trip. The journal reached at least restart counter 84 for the same deterministic error.

Steps to reproduce

Failure trigger

OpenClaw cold start rejected an exec SecretRef command because the configured executable path was a symlink. The application correctly failed closed, but the supervisor treated every identical permanent failure as restartable.

Both Telegram providers remained unavailable throughout the loop.

Expected behaviour

ClawBox should bound repeated gateway startup failures over a window longer than a normal failed startup cycle. After the breaker trips:

• the unit remains failed and diagnosable instead of looping;
• the last error and breaker state are visible in the setup/control surface;
• one actionable alert is emitted without duplicates;
• an operator can repair config and explicitly restart/reset-failed;
• normal one-off maintenance restarts remain reliable.

Suggested unit-level direction

Use explicit, tested rate-limit values in the canonical unit source, for example a burst of a few failures over several minutes rather than inherited 5-in-10-second defaults. The exact values should be based on worst-case legitimate pre-start duration.

Also consider whether Restart=on-failure better expresses intent, although it does not replace a real rate limiter.

Acceptance criteria

• A fixture that exits with the same permanent startup error trips the breaker after the configured burst.
• The breaker survives install/update unit regeneration.
• A single approved restart succeeds normally.
• A transient first failure followed by success recovers.
• The control surface reports breaker activation and the final startup error.
• Tests use a failure duration longer than the old 10-second limit window so the historical false protection is covered.

Related work

PRs #263, #265, and #271 improve update recovery and make optional pre-start work non-fatal. This report concerns a separate permanent OpenClaw runtime/config failure after pre-start completes.

ClawBox version

ClawBox main at commit 8cb6a43

OpenClaw version

OpenClaw 2026.7.1

Jetson model / JetPack

Ubuntu 22.04 LTS, AArch64

Logs and screenshots

[github-actions]

🦀 ClawReview

Scuttled over to help sort this one 🦀

Gateway service can restart indefinitely after permanent startup failures due to ineffective rate limiting.

At a glance

• Category: bug · Area: gateway
• Priority: 🔴 high

Suggested next step: Update clawbox-gateway.service with explicit longer rate limits (e.g., 5 starts in 5 minutes) and add breaker state reporting to the setup UI.

_{— ClawReview 🦀. Labels auto-applied on open — advisory, a maintainer will follow up. Conventions: docs.}

[KrasimirKralev]

Fixed by #308 (StartLimit in [Unit] bounds permanent startup failures; verified live on the box) — merged to beta, ships in the next release. Verified on the Jetson. Thanks for the report.