Real-Time Task Notifications

Overview

A system for immediately notifying Felix when tasks are assigned, rather than waiting for heartbeat intervals.

The Problem

Originally, Felix only checked for new tasks during heartbeat polls (every 1 hour). Zak wanted instant notification when creating tasks in Mission Control.

The Solution

Discovery

The OpenClaw Gateway exposes a /tools/invoke HTTP endpoint that can call any tool directly:

POST http://127.0.0.1:18789/tools/invoke
Authorization: Bearer <gateway_token>
Content-Type: application/json

{
  "tool": "cron",
  "args": {
    "action": "wake",
    "text": "Your message here",
    "mode": "now"
  }
}

Implementation

Mission Control's backend (server.js) calls this endpoint when:

1. A task is created and assigned to Felix
2. Someone clicks "Ping Felix"

Scheduled Notifications

For tasks with a startTime in the future, instead of waking immediately, we create a cron job:

{
  "tool": "cron",
  "args": {
    "action": "add",
    "job": {
      "name": "task-{id}",
      "schedule": { "kind": "at", "atMs": startTimeMs },
      "payload": { "kind": "systemEvent", "text": "..." },
      "sessionTarget": "main"
    }
  }
}

Key Insight

The /tools/invoke endpoint is powerful for external automation. Any system can wake Felix or call tools by making HTTP requests to the Gateway.

Related

• [[mission-control]]
• [[cron-jobs]]
• [[gateway-api]]

Created: 2026-02-01