Command Aliases

Contents

Overview

Core Types

The alias system is built on the nativeNames property of OpenClawPluginCommandDefinition. This is an optional partial record keyed by provider name, with a special default key for a cross-platform alias.

// src/plugins/types.ts — OpenClawPluginCommandDefinition
export type OpenClawPluginCommandDefinition = {
  name: string;
  nativeNames?: Partial<Record<string, string>> & { default?: string };
  description: string;
  acceptsArgs?: boolean;
  requireAuth?: boolean;
  handler: PluginCommandHandler;
};

Decision Points

How It Works

Alias resolution operates in three distinct phases spread across registration time and runtime lookup. At registration, aliases are validated and stored. At lookup time, the matcher iterates all registered commands and checks both primary keys and alias keys.

Phase 1 — Registration & Validation

When a plugin is loaded, validatePluginCommandDefinition iterates over nativeNames entries and applies the same validateCommandName rules used for the primary name. This prevents invalid aliases from entering the registry.

// src/plugins/command-registration.ts — alias validation loop
for (const [label, alias] of Object.entries(command.nativeNames ?? {})) {
  if (typeof alias !== "string") continue;
  const aliasError = validateCommandName(alias.trim());
  if (aliasError) {
    return `Native command alias "${label}" invalid: ${aliasError}`;
  }
}

Phase 2 — Invocation Key Collection

The listPluginInvocationKeys function collects all valid invocation keys for a command. It uses a Set to automatically deduplicate keys that resolve to the same normalized string.

// src/plugins/command-registration.ts — listPluginInvocationKeys
export function listPluginInvocationKeys(
  command: OpenClawPluginCommandDefinition,
): string[] {
  const keys = new Set<string>();
  const push = (value: string | undefined) => {
    const normalized = value?.trim().toLowerCase();
    if (!normalized) return;
    keys.add(`/${normalized}`);
  };
  push(command.name);
  push(command.nativeNames?.default);
  push(command.nativeNames?.telegram);
  push(command.nativeNames?.discord);
  return [...keys];
}

Phase 3 — Runtime Alias Resolution

At runtime, when getPluginCommandSpecs is called (e.g. for generating help text or autocomplete lists), it uses resolvePluginNativeName to pick the best name for the current provider context.

// src/plugins/command-registry-state.ts — getPluginCommandSpecs
export function getPluginCommandSpecs(
  provider?: string,
): Array<{ name: string; description: string; acceptsArgs: boolean }> {
  const providerName = provider?.trim().toLowerCase();
  if (providerName && providerName !== "telegram" && providerName !== "discord")
    return [];
  return Array.from(pluginCommands.values()).map((cmd) => ({
    name: resolvePluginNativeName(cmd, provider),
    description: cmd.description,
    acceptsArgs: cmd.acceptsArgs ?? false,
  }));
}

Alias Resolution Flow

The following flowchart shows how the system resolves an incoming slash command against the registered aliases. The matcher first checks the primary key in the pluginCommands Map, then falls back to scanning all registered commands via listPluginInvocationKeys.

flowchart TD
  INPUT["Incoming command: /tldr some text"]
  EXTRACT["Extract command key: /tldr"]
  DIRECT{"pluginCommands.get(/tldr)?"}
  SCAN["Scan all commands via listPluginInvocationKeys"]
  FOUND{"Alias match found?"}
  ACCEPT_ARGS{"command.acceptsArgs?"}
  DISPATCH["Dispatch to command.handler"]
  FALLTHROUGH["Fall through to built-in / agent"]
  REJECT["Reject: args not accepted"]

  INPUT --> EXTRACT
  EXTRACT --> DIRECT
  DIRECT -->|"Hit"| ACCEPT_ARGS
  DIRECT -->|"Miss"| SCAN
  SCAN --> FOUND
  FOUND -->|"Yes"| ACCEPT_ARGS
  FOUND -->|"No"| FALLTHROUGH
  ACCEPT_ARGS -->|"Yes or no args"| DISPATCH
  ACCEPT_ARGS -->|"No but args present"| REJECT
  REJECT --> FALLTHROUGH

The direct Map lookup is O(1) for commands registered under their primary name. The fallback scan iterates all registered commands and checks each one's invocation keys — this is O(n) where n is the number of registered plugin commands. In practice, n is small (typically < 50), so the linear scan has negligible cost.

Plugin Registration with Native Names

The following sequence diagram shows the lifecycle of a plugin command with nativeNames, from definition through registration to runtime invocation via an alias.

sequenceDiagram
    participant Plugin as Plugin Module
    participant Validator as validatePluginCommandDefinition
    participant Registry as pluginCommands Map
    participant KeyBuilder as listPluginInvocationKeys
    participant Matcher as matchPluginCommand
    participant User as End User

    Plugin->>Validator: Register command with nativeNames
    Validator->>Validator: Validate primary name
    Validator->>Validator: Validate each alias in nativeNames
    alt Validation passes
        Validator->>Registry: Store command under /primaryName
        Registry-->>Plugin: Registration success
    else Validation fails
        Validator-->>Plugin: Error: alias invalid
    end

    Note over User,Matcher: Later at runtime...

    User->>Matcher: /tldr summarize this
    Matcher->>Registry: pluginCommands.get("/tldr")
    Registry-->>Matcher: null (not primary key)
    Matcher->>KeyBuilder: Scan all commands
    KeyBuilder-->>Matcher: ["/summarize", "/tldr", "/recap"]
    Matcher->>Matcher: "/tldr" found in keys
    Matcher-->>User: Dispatch to summarize handler

Note that the command is stored in the Map under its primary name (/summarize), not under each alias. Aliases are resolved at match time by calling listPluginInvocationKeys on each candidate command. This design keeps the Map simple and avoids stale entries when aliases are updated.

Edge Cases

Configuration

Model Aliases (Distinct System)

OpenClaw also has a separate alias system for LLM model identifiers, managed in src/commands/models/aliases.ts. These are user-defined shortcuts, not developer-defined command names. The two systems are entirely independent.

// src/commands/models/aliases.ts — model alias management functions
export async function modelsAliasesListCommand(...)
export async function modelsAliasesAddCommand(...)
export async function modelsAliasesRemoveCommand(
  aliasRaw: string,
  runtime: RuntimeEnv,
)

Related Topics

Source Files

src/
├── plugins/
│   ├── types.ts                      ← OpenClawPluginCommandDefinition & nativeNames type
│   ├── command-registration.ts       ← listPluginInvocationKeys(), validatePluginCommandDefinition()
│   ├── command-registry-state.ts     ← getPluginCommandSpecs(), resolvePluginNativeName()
│   └── commands.ts                   ← matchPluginCommand() alias lookup fallback
├── commands/
│   └── models/
│       └── aliases.ts                ← Model alias CRUD (separate system)
└── auto-reply/
    └── reply/
        └── commands-slash-parse.ts   ← Upstream parser (feeds into alias resolution)