Command Registry

Contents

Overview

flowchart TD
  CLI["CLI Entry (openclaw ...)"]
  CORE["Core CLI Registry"]
  LAZY["Lazy Import Module"]
  COMMANDER["Commander.js Program"]
  PLUGIN_REG["Plugin Registration"]
  VALIDATE["validatePluginCommandDefinition()"]
  PLUGIN_MAP["pluginCommands Map"]
  USER["User Message /command"]
  MATCH["matchPluginCommand()"]
  DISPATCH["Command Dispatch"]

  CLI --> CORE
  CORE -->|"registerCoreCliByName()"| LAZY
  LAZY -->|"await import()"| COMMANDER
  COMMANDER --> DISPATCH

  PLUGIN_REG -->|"registerPluginCommand()"| VALIDATE
  VALIDATE -->|"OK"| PLUGIN_MAP
  USER --> MATCH
  MATCH -->|"Lookup"| PLUGIN_MAP
  MATCH -->|"Found"| DISPATCH

Two distinct paths converge at dispatch. CLI commands flow through Commander.js after lazy loading; plugin commands are matched from the global pluginCommands Map. The registry enforces that no two commands can claim the same invocation key.

Core Types

// src/cli/program/command-registry.ts — Core CLI types
export type CommandRegistration = {
  id: string;
  register: (params: CommandRegisterParams) => void;
};

type CoreCliEntry = {
  commands: CoreCliCommandDescriptor[];
  register: (params: CommandRegisterParams) => Promise<void> | void;
};

type CommandRegisterParams = {
  program: Command;
  ctx: ProgramContext;
  argv: string[];
};

// src/plugins/command-registry-state.ts — Plugin registry state
export type RegisteredPluginCommand = OpenClawPluginCommandDefinition & {
  pluginId: string;
  pluginName?: string;
  pluginRoot?: string;
};

type PluginCommandState = {
  pluginCommands: Map<string, RegisteredPluginCommand>;
  registryLocked: boolean;
};

Decision Points

How It Works

Phase 1 — CLI Core Registration

The coreEntries array defines 18 built-in commands. Each entry contains a descriptor (name + description) and an async register function that dynamically imports the command module and attaches it to the Commander.js program tree.

// src/cli/program/command-registry.ts — lazy registration pattern
const coreEntries: CoreCliEntry[] = [
  {
    commands: [{ name: "doctor", description: "Health checks + quick fixes",
                 hasSubcommands: false }],
    register: async ({ program }) => {
      const mod = await import("./register.doctor.js");
      mod.registerDoctorCommand(program);
    },
  },
  {
    commands: [{ name: "models", description: "Model selection, configuration, auth",
                 hasSubcommands: true }],
    register: async ({ program }) => {
      const mod = await import("./register.models.js");
      mod.registerModelsCommand(program);
    },
  },
  // ... 16 more entries: setup, onboard, configure, config, backup,
  //     dashboard, reset, uninstall, message, mcp, agent, agents,
  //     status, health, sessions, tasks
];

Phase 2 — On-Demand Lookup

// src/cli/program/command-registry.ts — name-based lazy load
export async function registerCoreCliByName(
  program: Command,
  ctx: ProgramContext,
  name: string,
  argv: string[] = process.argv,
): Promise<boolean> {
  const entry = coreEntries.find((candidate) =>
    candidate.commands.some((cmd) => cmd.name === name),
  );
  if (!entry) {
    return false;
  }
  removeEntryCommands(program, entry);
  await entry.register({ program, ctx, argv });
  return true;
}

Phase 3 — Plugin Command Registration

sequenceDiagram
    participant Plugin as Plugin Loader
    participant Validate as validatePluginCommandDefinition()
    participant NameCheck as validateCommandName()
    participant Reserved as reservedCommands Set
    participant Map as pluginCommands Map
    participant Lock as Registry Lock

    Plugin->>Lock: isPluginCommandRegistryLocked()?
    Lock-->>Plugin: false
    Plugin->>Validate: validatePluginCommandDefinition(def)
    Validate->>NameCheck: validateCommandName("tts")
    NameCheck->>Reserved: reservedCommands.has("tts")?
    Reserved-->>NameCheck: false
    NameCheck-->>Validate: null (valid)
    Validate-->>Plugin: null (valid)
    Plugin->>Map: Check for duplicate keys
    Map-->>Plugin: No conflicts
    Plugin->>Map: pluginCommands.set("/tts", registered)
    Map-->>Plugin: { ok: true }

// src/plugins/command-registration.ts — registration with validation
export function registerPluginCommand(
  pluginId: string,
  command: OpenClawPluginCommandDefinition,
  opts?: { pluginName?: string; pluginRoot?: string },
): CommandRegistrationResult {
  if (isPluginCommandRegistryLocked()) {
    return { ok: false, error: "Cannot register commands while processing is in progress" };
  }

  const definitionError = validatePluginCommandDefinition(command);
  if (definitionError) {
    return { ok: false, error: definitionError };
  }

  const invocationKeys = listPluginInvocationKeys(command);
  const key = `/${command.name.trim().toLowerCase()}`;

  for (const invocationKey of invocationKeys) {
    const existing = pluginCommands.get(invocationKey) ??
      Array.from(pluginCommands.values()).find((candidate) =>
        listPluginInvocationKeys(candidate).includes(invocationKey),
      );
    if (existing) {
      return { ok: false,
        error: `Command "${invocationKey.slice(1)}" already registered by plugin "${existing.pluginId}"` };
    }
  }

  pluginCommands.set(key, { ...command, pluginId, pluginName: opts?.pluginName, pluginRoot: opts?.pluginRoot });
  return { ok: true };
}

Code Walkthrough

// src/plugins/command-registry-state.ts — singleton state
const PLUGIN_COMMAND_STATE_KEY = Symbol.for("openclaw.pluginCommandsState");

const getState = () =>
  resolveGlobalSingleton<PluginCommandState>(PLUGIN_COMMAND_STATE_KEY, () => ({
    pluginCommands: new Map<string, RegisteredPluginCommand>(),
    registryLocked: false,
  }));

// src/plugins/command-registry-state.ts — proxy delegation
export const pluginCommands = new Proxy(
  new Map<string, RegisteredPluginCommand>(),
  {
    get(_target, property) {
      const value = Reflect.get(
        getPluginCommandMap(), property, getPluginCommandMap()
      );
      return typeof value === "function"
        ? value.bind(getPluginCommandMap())
        : value;
    },
  },
);

// src/plugins/command-registration.ts — name validation
export function validateCommandName(name: string): string | null {
  const trimmed = name.trim().toLowerCase();
  if (!trimmed) return "Command name cannot be empty";
  if (!/^[a-z][a-z0-9_-]*$/.test(trimmed)) {
    return "Command name must start with a letter and contain " +
           "only letters, numbers, hyphens, and underscores";
  }
  reservedCommands ??= new Set([
    "help", "commands", "status", "whoami", "context", "btw",
    "stop", "restart", "reset", "new", "compact", "config",
    "debug", "allowlist", "activation", "skill", "subagents",
    "kill", "steer", "tell", "model", "models", "queue",
    "send", "bash", "exec", "think", "verbose", "reasoning",
    "elevated", "usage",
  ]);
  if (reservedCommands.has(trimmed)) {
    return `Command name "${trimmed}" is reserved by a built-in command`;
  }
  return null;
}

Reserved Command Names

The following 30 names are permanently reserved by the built-in command system. Plugins that attempt to register any of these names receive a validation error.

Plugin Lifecycle & Teardown

When a plugin is unloaded — either during a hot-reload or because the user disabled it — all commands registered by that plugin must be removed. The registry provides two teardown functions:

// src/plugins/command-registry-state.ts — teardown
export function clearPluginCommands(): void {
  pluginCommands.clear();
}

export function clearPluginCommandsForPlugin(pluginId: string): void {
  for (const [key, cmd] of pluginCommands.entries()) {
    if (cmd.pluginId === pluginId) {
      pluginCommands.delete(key);
    }
  }
}

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,
  }));
}

Registered Core Commands

Edge Cases

Related Topics

Source Files

src/
├── cli/program/
│   ├── command-registry.ts           ← Core CLI lazy-load registry (18 commands)
│   ├── core-command-descriptors.ts   ← Command name/description metadata
│   ├── command-tree.ts               ← Commander.js tree management
│   └── register-lazy-command.ts      ← Lazy command loading helper
├── plugins/
│   ├── command-registration.ts       ← registerPluginCommand(), validation
│   ├── command-registry-state.ts     ← pluginCommands Map, locking
│   ├── commands.ts                   ← matchPluginCommand() runtime lookup
│   └── bundle-commands.ts            ← Bundle command utilities
└── commands/                         ← 260+ command implementation files