Command Routing & Dispatch

Introduction

When a user types a slash command, OpenClaw must determine which handler should process it. The routing system follows a priority chain: built-in commands are checked first, then skill-based commands, and finally a fallback handler. Understanding this resolution order is essential for debugging command conflicts and designing reliable command interfaces.

Key Concepts

• Resolution Order: Built-in commands take priority over skills, which take priority over fallback handling
• Built-in Priority: Commands like /new, /reset, /model are always resolved first and cannot be overridden
• Skill Resolution: After built-in check, the system searches registered skills for a matching command name
• Fallback Handler: If no built-in or skill matches, the command text is passed to the agent as a regular message
• Command Dispatch Middleware: The internal pipeline that processes each step of command resolution

Real World Context

A team creates a /status skill that shows their custom deployment status dashboard. They discover it never fires because OpenClaw's built-in /status command takes priority. They rename their skill to /deploy-status to avoid the conflict. Understanding the resolution order saved them from a frustrating debugging session.

Deep Dive

The Resolution Chain

When a user types /something, OpenClaw follows this chain:

json
{
  "commandResolution": {
    "order": [
      {
        "priority": 1,
        "type": "built-in",
        "commands": ["/new", "/reset", "/stop", "/status", "/model", "/compact", "/context", "/send"]
      },
      {
        "priority": 2,
        "type": "skill",
        "source": "agent skills directory",
        "condition": "user-invocable: true in frontmatter"
      },
      {
        "priority": 3,
        "type": "fallback",
        "action": "pass command text as regular message to agent"
      }
    ]
  }
}

This resolution chain means built-in commands are immutable. You cannot create a skill that overrides /new or /model. Skills occupy the second tier, and anything unrecognized falls through to the agent as a regular message.

Dispatch Middleware Pipeline

The command dispatch middleware processes each resolution step:

json
{
  "middleware": [
    {
      "step": "parse",
      "action": "Extract command name and arguments from user input"
    },
    {
      "step": "authenticate",
      "action": "Verify the user has permission to use this command"
    },
    {
      "step": "resolve",
      "action": "Find the handler using the priority chain"
    },
    {
      "step": "execute",
      "action": "Run the resolved handler with parsed arguments"
    },
    {
      "step": "respond",
      "action": "Deliver the handler's response to the user"
    }
  ]
}

Every command passes through these five middleware steps in order. The parse step extracts the command name and arguments. The authenticate step checks permissions. The resolve step finds the handler. The execute step runs it. The respond step delivers the result.

Error Handling

When a command fails at any middleware step, the error propagates to the user:

json
{
  "error": {
    "command": "/deploy staging",
    "step": "authenticate",
    "message": "User 'junior-dev' does not have permission to execute /deploy",
    "code": "COMMAND_AUTH_DENIED"
  }
}

Errors are structured with the failed step, a human-readable message, and an error code. This makes it easy to diagnose where in the pipeline the command failed and why.

Debugging Command Resolution

To see how a command would be resolved without executing it:

bash
openclaw commands resolve /deploy staging --dry-run

This shows which handler would process the command, what arguments would be passed, and whether any middleware would reject it, all without actually executing the command.

Common Pitfalls

• Naming skills the same as built-in commands: Built-in commands always win. Your skill will never be invoked.
• Assuming the fallback handler does nothing: The fallback passes the command text to the agent as a message. This can cause unexpected agent behavior if the command text looks like an instruction.
• Not checking permissions in skill handlers: The middleware only checks basic authentication. Business logic permissions should be validated within the skill handler itself.

Best Practices

• Check the built-in command list before naming custom skills to avoid conflicts.
• Use commands resolve --dry-run to verify routing before deploying new skills.
• Add permission checks in skill handlers for commands that perform sensitive operations.

Summary

• Command resolution follows a strict priority chain: built-in > skill > fallback
• Built-in commands cannot be overridden by skills
• The dispatch middleware pipeline includes parse, authenticate, resolve, execute, and respond steps
• Errors at any middleware step are propagated to the user with structured error information
• Use --dry-run to debug command resolution without executing commands