Dynamic Model Switching with before_agent_start Hooks in OpenClaw 2026.2.17

OpenClaw 2026.2.17 introduces a powerful new plugin hook that lets you dynamically change which AI model your agent uses—before the agent even starts processing. If you've ever wanted to route different conversations to different models based on context, this feature is for you.

What's New

The before_agent_start hook fires before model/provider resolution, giving your plugins a chance to override which model handles a request. This opens up sophisticated routing scenarios that were previously impossible or required awkward workarounds.

Why This Matters

Before this feature, model selection was largely static—you'd configure your primary model and fallbacks in config.yaml, and that was it. Now you can make runtime decisions based on:

• User identity: Route VIP users to more capable (expensive) models
• Message content: Use vision models when images are attached
• Channel context: Different models for Discord vs Telegram vs API
• Time of day: Use faster/cheaper models during off-peak hours
• Cost optimization: Route simple queries to lighter models
• A/B testing: Gradually roll out new models to a percentage of users

Basic Usage

Create a plugin that exports a before_agent_start hook:

// plugins/smart-router/index.ts
import type { Plugin } from "openclaw";

export default {
  name: "smart-router",
  hooks: {
    before_agent_start: async ({ context, override }) => {
      // Route image messages to a vision-capable model
      if (context.hasImages) {
        override.model = "anthropic/claude-sonnet-4-6";
        return;
      }
      
      // Use a cheaper model for simple queries
      if (context.messageLength < 50) {
        override.model = "groq/llama-3.3-70b";
        return;
      }
    }
  }
} satisfies Plugin;

Real-World Example: Cost-Aware Routing

Here's a more complete example that routes based on estimated complexity:

export default {
  name: "cost-router",
  hooks: {
    before_agent_start: async ({ context, override }) => {
      const { channel, sender, message } = context;
      
      // Premium channels get premium models
      if (channel === "api" && sender.tier === "enterprise") {
        override.model = "anthropic/claude-opus-4-5";
        override.params = { ...override.params, context1m: true };
        return;
      }
      
      // Group chats get balanced models
      if (context.isGroup) {
        override.model = "anthropic/claude-sonnet-4-5";
        return;
      }
      
      // Default to fast model for DMs
      override.model = "anthropic/claude-haiku-3-5";
    }
  }
};

Key Points

• The hook runs before model resolution, so your overrides take precedence
• You can override both model and provider independently
• Fallback chains still work—your override becomes the new primary
• Multiple plugins can have before_agent_start hooks; they run in plugin order
• Access full context including channel, sender, message content, and attachments

Getting Started

1. Update to OpenClaw 2026.2.17 or later
2. Create a plugin in your plugins/ directory
3. Export the before_agent_start hook
4. Register the plugin in your config

plugins:
  - ./plugins/smart-router

This feature was contributed by @natefikru in PR #18568.

Dynamic model routing is a game-changer for anyone running OpenClaw at scale or optimizing costs. Combined with the rate limit recovery and fallback improvements in this release, you now have fine-grained control over how your agent chooses and fails over between models.