Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix boot-md hook silently fails when gateway is restarted via LaunchAgent kickstart [1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#52855•Fetched 2026-04-08 01:18:27
View on GitHub
Comments
1
Participants
2
Timeline
1
Reactions
0
Author
zuco1111zuco1111
Participants
Hollychou924Hollychou924zuco1111zuco1111
Timeline (top)
commented ×1

Error Message

[hooks:loader] Registered hook: boot-md -> gateway:startup
[gateway/hooks] loaded 4 internal hook handlers
// No boot-md execution logs follow

Root Cause

Looking at the boot-md handler code (dist/bundled/boot-md/handler.js):

const runBootChecklist = async (event) => {
  if (!isGatewayStartupEvent(event)) return;  // ← Silently returns if false
  // ...
};

The isGatewayStartupEvent() function requires both:

  1. Correct event type/action: gateway:startup
  2. A valid getHookContext(event) to return truthy

When the gateway is restarted via LaunchAgent kickstart, the gateway:startup event may be fired but getHookContext(event) returns falsy in certain restart scenarios, causing the hook to silently return without any logging.

Fix Action

Workaround

None ideal - users must implement their own restart notification logic outside of BOOT.md.

Code Example

const runBootChecklist = async (event) => {
  if (!isGatewayStartupEvent(event)) return;  // ← Silently returns if false
  // ...
};

---

[hooks:loader] Registered hook: boot-md -> gateway:startup
[gateway/hooks] loaded 4 internal hook handlers
// No boot-md execution logs follow
RAW_BUFFERClick to expand / collapse

Bug Description

The boot-md hook (which runs BOOT.md on gateway startup) is registered correctly and shows as ready in openclaw hooks list, but it silently fails when the gateway is restarted via openclaw gateway restart command (which uses LaunchAgent kickstart under the hood).

Expected Behavior

When running openclaw gateway restart, the boot-md hook should execute BOOT.md and send a notification.

Actual Behavior

  • Hook is registered: ✓ (visible in logs: `Registered hook: boot-md -> gateway:startup`)
  • Hook is enabled in config: ✓
  • But no execution logs appear - the hook silently returns without any output

Root Cause Analysis

Looking at the boot-md handler code (dist/bundled/boot-md/handler.js):

const runBootChecklist = async (event) => {
  if (!isGatewayStartupEvent(event)) return;  // ← Silently returns if false
  // ...
};

The isGatewayStartupEvent() function requires both:

  1. Correct event type/action: gateway:startup
  2. A valid getHookContext(event) to return truthy

When the gateway is restarted via LaunchAgent kickstart, the gateway:startup event may be fired but getHookContext(event) returns falsy in certain restart scenarios, causing the hook to silently return without any logging.

Steps to Reproduce

  1. Create a BOOT.md file in the workspace
  2. Run openclaw gateway restart
  3. Observe: no notification is sent, no error logged
  4. Check logs: only `Registered hook: boot-md -> gateway:startup` appears, no "boot-md skipped" or "boot-md ran" log

Logs

[hooks:loader] Registered hook: boot-md -> gateway:startup
[gateway/hooks] loaded 4 internal hook handlers
// No boot-md execution logs follow

Environment

  • Platform: macOS (LaunchAgent)
  • OpenClaw version: 2026.3.13
  • Gateway restart method: openclaw gateway restart (uses launchctl kickstart)

Suggested Fix

  1. Add logging when isGatewayStartupEvent() returns false so the failure is visible
  2. Or investigate why getHookContext(event) returns falsy on LaunchAgent kickstart restarts
  3. Alternatively, ensure the hook handler logs its skip reason explicitly

Workaround

None ideal - users must implement their own restart notification logic outside of BOOT.md.

extent analysis

Fix Plan

To address the silent failure of the boot-md hook, we will implement the suggested fixes:

  • Add logging when isGatewayStartupEvent() returns false
  • Ensure the hook handler logs its skip reason explicitly

Code Changes

We will modify the handler.js file in dist/bundled/boot-md/ to include logging for the isGatewayStartupEvent() check:

const runBootChecklist = async (event) => {
  if (!isGatewayStartupEvent(event)) {
    console.log('boot-md hook skipped: isGatewayStartupEvent() returned false');
    return;
  }
  // ...
};

Additionally, we will modify the isGatewayStartupEvent() function to log the reason for returning false:

const isGatewayStartupEvent = (event) => {
  const eventType = event.type;
  const hookContext = getHookContext(event);
  if (eventType !== 'gateway:startup') {
    console.log('boot-md hook skipped: incorrect event type');
    return false;
  }
  if (!hookContext) {
    console.log('boot-md hook skipped: getHookContext() returned falsy');
    return false;
  }
  return true;
};

Verification

To verify the fix, restart the gateway using openclaw gateway restart and check the logs for the boot-md hook execution or skip messages.

Extra Tips

  • Ensure that the logging statements are properly configured to output to the desired log file or console.
  • Consider adding additional logging or debugging statements to help diagnose any further issues with the boot-md hook.
  • Review the getHookContext() function to determine why it may be returning falsy on LaunchAgent kickstart restarts and address the root cause if possible.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#runtime error#dependency conflict#environment setup#docker error#permission error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING