Feature Request: hooks.sessionRetention Brings Automatic Cleanup to Webhook-Triggered Sessions

If you've integrated OpenClaw with CI/CD webhooks or PR automation, you've likely noticed something annoying: hook-triggered sessions pile up indefinitely. Unlike cron jobs, which have had sessionRetention for a while, webhook sessions have been orphaned children—spawned but never cleaned up.

The Problem

Every time a webhook fires (a PR opened, a CI run completed, a deployment triggered), OpenClaw spins up a new session. For high-churn workflows—think active monorepos with dozens of PRs per day—this creates serious operational debt:

• Session bloat: Your session list becomes an archaeological dig through completed, one-shot hook runs
• Memory creep: Each session holds state, and hundreds of completed hook sessions consume resources
• Debugging noise: When something goes wrong, you're sifting through a graveyard of finished sessions to find the active ones

The workaround has been manual: periodically enumerate agent:main:hook:* sessions via the API and delete the completed ones. Functional, but tedious.

The Solution: hooks.sessionRetention

A new feature request (#30093) proposes adding hooks.sessionRetention to mirror the existing cron behavior. The config would look like:

{
  "hooks": {
    "enabled": true,
    "path": "/hooks",
    "token": "...",
    "sessionRetention": "30m"
  }
}

Set it to a duration string (30m, 1h, 24h) and completed hook sessions get pruned automatically via the existing session reaper. Set it to false to disable cleanup entirely (the current default behavior).

Implementation Already Submitted

The good news: PR #30104 has already been opened with a working implementation. According to the author, it includes:

• Full hooks.sessionRetention config support (duration or false)
• Integration with the existing session reaper infrastructure
• Documentation and tests

The PR defaults to disabled for backward compatibility, so existing setups won't see any behavior change until you explicitly enable retention.

Why This Matters

For anyone running OpenClaw as part of their development workflow—especially with GitHub Actions, GitLab CI, or custom PR bots—this is a significant quality-of-life improvement. The pattern of "fire webhook → agent does work → session sits there forever" has been a friction point since hooks landed.

With sessionRetention, you can finally treat hook sessions as the ephemeral, disposable operations they are: spawn, execute, expire. No manual cleanup scripts. No session list archaeology.

If you're using webhooks in production, consider adding a 👍 to the issue or reviewing the PR. The faster this lands, the sooner we can all stop writing session-pruning cron jobs.