Clarify and improve Gateway reload/restart behavior inside HA add-on

[marciogranzotto]

Pre-flight checks

• I checked existing issues first
• I checked the add-on startup scripts and OpenClaw reload behavior

What happened?

In the Home Assistant add-on, OpenClaw Gateway config changes and restarts are confusing because the add-on runs the gateway under its own run.sh supervision instead of the normal OpenClaw service manager.

From inside the add-on terminal, commands such as:

openclaw gateway restart
openclaw gateway status

report systemd/service-manager problems even though the gateway is actually running under the add-on supervisor script:

Gateway service disabled.
systemd user services are unavailable; install/enable systemd or run the gateway under your supervisor.
If you're in a container, run the gateway in the foreground instead of `openclaw gateway`.

This makes it look like the gateway is broken or needs a full Home Assistant add-on/container restart, when in many cases OpenClaw has either:

• already hot-reloaded the config, or
• self-restarted via SIGUSR1 and the add-on supervisor loop rediscovered the new process.

This is related to, but not exactly the same as, #130. That issue reports gateway startup/status confusion. This issue is specifically about the add-on restart/reload UX and the mismatch between OpenClaw CLI service commands and the HA add-on's container supervisor model.

What did you expect to happen?

Inside the HA add-on, there should be a clear, add-on-native way to reload/restart the Gateway without restarting the entire Home Assistant add-on/container, or the CLI/status output should make it clear that service-manager commands are not applicable in this packaging.

Ideally one of these would be true:

1. openclaw gateway restart works inside the add-on by delegating to the add-on supervisor / foreground gateway process, or
2. the add-on provides a documented helper such as oc-gateway-restart / oc-gateway-reload, or
3. the add-on status page/docs explain that OpenClaw is supervised by run.sh, not systemd, and distinguish:
   • hot-reloadable config changes
   • Gateway-process restarts
   • full add-on restarts required for add-on options / nginx / TLS / startup env changes

Investigation notes

Looking at openclaw_assistant/run.sh in this repo:

• config.yaml uses init: false
• the add-on starts openclaw gateway run from run.sh
• nginx/ingress and ttyd are started separately
• run.sh has its own watchdog/supervision loop
• the script explicitly handles OpenClaw self-restarts:

openclaw gateway run is a thin wrapper that spawns openclaw-gateway as a long-running daemon and then exits.
When the gateway self-restarts (SIGUSR1 / openclaw gateway restart), the old daemon exits and a NEW daemon is forked — the new PID is NOT a child of this shell so wait cannot block on it.

So the add-on already recognizes that normal service-manager semantics do not fit the HA/container environment.

OpenClaw itself supports config hot reload. The docs say gateway.reload.mode="hybrid" is the default:

• agents/channels/MCP/tools/session/routing: generally hot reload
• gateway.*, discovery, canvasHost, plugin load/install: Gateway restart required

Local logs from an add-on instance showed hot reload working:

[reload] config change detected; evaluating reload (...)
[reload] config hot reload applied (...)

But users still naturally reach for openclaw gateway restart, which reports systemd/service disabled in the add-on.

Why this is confusing

The add-on has three different "restart" layers:

1. OpenClaw config hot reload
2. OpenClaw Gateway process restart / SIGUSR1 self-restart
3. Full Home Assistant add-on/container restart

The current UX makes users think layer 3 is required more often than it really is.

Possible improvements

Some possible fixes / mitigations:

• Add an add-on helper command that restarts only the OpenClaw Gateway process in the way run.sh expects.
• Adjust PATH/env so the terminal openclaw binary always matches the running Gateway's installed OpenClaw version.
• Document which changes require:
  • no restart / hot reload
  • Gateway-only restart
  • full HA add-on restart
• If feasible, make openclaw gateway restart inside the add-on trigger OpenClaw's SIGUSR1/self-restart path instead of trying systemd.
• Add a clear warning in the add-on docs/status page that systemd service commands are not valid inside this container.

Add-on version

Observed while inspecting current repository version around openclaw_assistant 0.5.72.

OpenClaw version

Observed environment had a version mismatch that may make this more confusing:

/usr/bin/openclaw              -> OpenClaw 2026.5.2
/config/.node_global/bin/openclaw -> OpenClaw 2026.5.7
running Gateway package         -> OpenClaw 2026.5.7

This may be separate, but it reinforces the need for the add-on terminal PATH to prefer the same OpenClaw binary used by the running gateway.

Additional context

This came up while configuring multiple agents and MCP in the HA add-on. Most agent/channel/MCP changes appeared to be hot-reloadable, but gateway CLI restart/status output made it unclear whether the add-on needed a full restart.

[marciogranzotto]

Additional data point: this may also explain confusion around Whisper / voice-call setup in the add-on terminal.

On one add-on instance, Whisper itself appears to be installed and available via the persistent Homebrew path:

/config/.linuxbrew/bin/whisper
/config/.linuxbrew/bin/whisper-cli
/config/.linuxbrew/opt/openai-whisper
/config/.linuxbrew/opt/whisper-cpp

OpenClaw also has whisper-related skills present:

/config/.openclaw/skills/openai-whisper
/config/.openclaw/skills/openai-whisper-api

But the Gateway / plugin registry still reports:

plugins.entries.voice-call: plugin not installed: voice-call — install the official external plugin with: openclaw plugins install @openclaw/voice-call

And checking the global npm installation shows the plugin is not installed:

npm ls -g @openclaw/voice-call
# empty

So there are a few separate layers that are easy to conflate in the add-on terminal:

1. Whisper binary installed via Homebrew
2. OpenClaw skills copied into /config/.openclaw/skills
3. OpenClaw external plugin package @openclaw/voice-call
4. The specific openclaw CLI binary on PATH vs the one used by the running Gateway

In the observed environment, PATH resolves openclaw to an older binary first:

/usr/bin/openclaw                    -> OpenClaw 2026.5.2
/config/.node_global/bin/openclaw    -> OpenClaw 2026.5.7
running Gateway package              -> OpenClaw 2026.5.7

That makes it very easy for a user to install or inspect something from the terminal and reasonably expect the running Gateway to see it, while the Gateway/plugin loader is actually operating from a different runtime/package context.

This reinforces the suggestion above: the add-on terminal should probably prefer the same OpenClaw binary / npm root as the running Gateway, and docs should distinguish Homebrew-installed tools, OpenClaw skills, and OpenClaw plugins.