Open main menu

OpenClaw Runtime Hooks on Agent 37: post-restart and post-image-update

Runtime hooks let your OpenClaw instance run small setup scripts automatically during startup, so packages, services, and runtime state come back on their own.

Published on

•

Table of Contents

Do not index
Runtime hooks let your OpenClaw instance on Agent 37 run small setup scripts automatically during startup.
Use them when you want to:
  • reinstall packages after a runtime update
  • restart background services
  • recreate temporary runtime state
  • restore tools or files your app depends on
Hook files live in:
/home/node/.agent37/hooks/
There are two hooks. Use post-image-update.sh for things that should run only after a runtime update, and post-restart.sh for things that should run on every start.

The post-restart hook

This hook runs on every container start, including restarts, host reboots, and updates. Use it for runtime state that should be restored every time the container starts.
Create this file:
/home/node/.agent37/hooks/post-restart.sh

When to use it

  • start background services
  • restart a local app or worker
  • recreate temporary directories
  • restore runtime-only state

Timeout

The post-restart hook has a 5 minute timeout. If the hook fails or times out, startup continues.
The default scaffold is comments only. The post-restart hook is skipped until the file contains at least one non-comment command.

Example

#!/usr/bin/env bash
set -euo pipefail

mkdir -p "$HOME/.cache/my-worker"
nohup "$HOME/.local/bin/my-worker" > "$HOME/.cache/my-worker/worker.log" 2>&1 &
A practical real-world use: if you access OpenClaw Web Chat over Tailscale, add the tailscaled daemon command here so the tailnet connection survives every restart. The full walkthrough is in How to Set Up Tailscale with OpenClaw Web Chat.

The post-image-update hook

This hook runs only when the runtime image reference changes. Use it for setup that is lost when the container image changes, such as packages installed into non-persisted system paths.
Create this file:
/home/node/.agent37/hooks/post-image-update.sh

When to use it

  • reinstall system packages
  • restore tools that are not part of your persisted home directory
  • rerun one-time setup after a runtime update

Timeout

The post-image-update hook has a 15 minute timeout. If the hook fails or times out, startup continues. The image ref is not marked as completed, so the hook retries on the next container start.

Example

#!/usr/bin/env bash
set -euo pipefail

sudo apt-get update
sudo apt-get install -y --no-install-recommends ffmpeg

Tips

  • Keep each hook focused on one job
  • Test the commands manually in Terminal first
  • Keep the script short enough to finish within its timeout
  • Put long-running processes in the background when needed