openclaw - 💡(How to fix) Fix Feature request: openclaw agents restart <id> — per-agent restart capability [1 comments, 2 participants]

Summary

Add a openclaw agents restart <agent-id> command (or equivalent under another subcommand surface) that restarts a single agent's session/provider without bouncing the entire gateway. There is currently no way to surgically recover a stuck or runaway specialist agent — the only available action is openclaw gateway restart, which terminates all agents on the host and incurs ~3 minutes of downtime + the orphaned-child-process risk documented in #75747 + the session-lock-leak risk documented in #75805.

Verified gap (against 2026.4.24)

$ openclaw gateway restart --help
Usage: openclaw gateway restart [options]
Restart the Gateway service (launchd/systemd/schtasks)
Options:
  -h, --help  Display help for command
  --json      Output JSON (default: false)

No --agent, no --name, no --id. Confirmed adjacent surfaces also lack per-agent restart:

$ openclaw agents --help
Commands:
  add, bind, bindings, delete, list, set-identity, unbind
$ openclaw channels --help
Commands:
  add, capabilities, list, login, logout, logs, remove, resolve, status

Existing channels logout + channels login cycles a transport (e.g. Discord WebSocket), but does not reset the agent's reasoning context — different failure mode, different fix.

Use case

Production multi-agent setup with a dedicated security/monitoring agent (Arya) that watches the other ten specialists for runaway sessions, stuck conversations, and token-spend anomalies. Industry pattern (AutoGen is_termination_msg, LangGraph supervisor pattern, CrewAI task cancellation) is to give the supervisor agent the ability to terminate-and-restart a specific subordinate without affecting siblings.

Today, when the supervisor detects a runaway, the available remediations are:

1. Wait for session.reset.idleMinutes — slow (15+ min), only resolves cases that were going to recover anyway.
2. /reset in the agent's Discord channel via the agent's messaging tool — works for context-level resets, doesn't help if the agent's provider is wedged.
3. Full gateway restart — bounces all 11 agents, ~3 min downtime, surfaces #75747 risks.

The first is too slow, the third is too disruptive. There's no "just this one" option.

Proposed API

openclaw agents restart <agent-id> [--soft|--hard]

• --soft (default): tear down the agent's active session, preserve channel bindings + auth profiles + workspace state, restart the agent's provider, resume on next inbound message. Equivalent to what a hypothetical /reset would do at the gateway level rather than the chat level.
• --hard: full provider reinit including channel re-handshake. Useful when transport is also wedged (Discord WebSocket close 1006 with no recovery, etc.).

Exit codes:

• 0 — restart succeeded, agent ready for new turn
• 1 — agent ID not found
• 2 — agent restart attempted but health check failed
• 3 — agent currently locked (session in flight, retry after lock release)

Cross-references

• #75747 — orphaned child processes after gateway restart on Linux. Per-agent restart should ensure single-agent process tree is fully reaped.
• #75805 — session lock files not released on shutdown. Per-agent restart should release/clean its own locks before completing.
• (Optionally) the AutoGen is_termination_msg pattern: https://microsoft.github.io/autogen/ — for prior art on supervisor-driven agent termination in production multi-agent systems.

Workaround in our deployment

Documented at the supervisor agent's prompt level: tiered protocol (watch → surgical /reset in Discord → escalate to human for full gateway restart). Works but Tier 3 is a manual step that interrupts the human, defeating the autonomy goal.

Severity

Feature gap, not a bug. Without it, supervisor-pattern multi-agent setups can't fully self-heal — every runaway becomes a human-paged incident.