Framework Integration Patterns

A custom module that works in isolation but fails when plugged into the OpenClaw framework is a demo, not a module. Framework integration requires conforming to the framework's lifecycle hooks, event system, and configuration management. The module must initialize when the framework starts, respond to framework events, and shut down cleanly when the framework stops.

The integration points are: initialization (the framework calls the module's init function with configuration), event subscription (the module registers for framework events it cares about — new task, agent request, schedule trigger), event emission (the module publishes its own events for other modules to consume), health reporting (the module reports its status to the framework's health check system), and graceful shutdown (the module completes in-progress work and releases resources when the framework signals shutdown).

1. 1. Implement Lifecycle Hooks Every module implements: init(config), healthCheck(), and shutdown(). Init loads configuration and establishes connections. HealthCheck returns current status. Shutdown completes in-progress work and releases resources.
2. 2. Subscribe to Framework Events Register event handlers during init. Handle events asynchronously to avoid blocking the framework event loop. Unsubscribe during shutdown to prevent orphaned handlers.
3. 3. Emit Module Events Publish events for actions other modules might care about: task.completed, analysis.ready, error.detected. Use the framework's event bus — do not create a parallel communication channel.