command-registry-integration

command-registry-integration

Integrate a new chat command into OpenClaw’s formal command registry and command handling chain so it appears in /commands, supports native slash registration where applicable, and avoids brittle text-intercept hacks.

Use this when

• You need a real built-in chat command such as /foo
• The command must appear in /commands
• The command should ride the formal command detection / registry / handler path
• You want the smallest-source-change path for adding a command

Do NOT use this when

• A plugin command is enough and you do not need a built-in source command
• A skill command (/skill name) already solves the problem
• You are trying to intercept plain text with ad-hoc regexes outside the command pipeline

Source map: where to look first

1. src/auto-reply/commands-registry.data.ts
   • Source of truth for built-in command registry entries
   • Controls /commands visibility and native command metadata
2. src/auto-reply/commands-registry.ts
   • Detection, normalization, arg parsing, native spec export
3. src/auto-reply/reply/commands-core.ts
   • Main built-in handler chain
4. src/auto-reply/reply/commands-*.ts
   • Concrete handlers; add the new command here
5. src/auto-reply/status.ts
   • /commands and /help rendering tests depend on registry descriptions
6. Tests:
   • src/auto-reply/commands-registry.test.ts
   • src/auto-reply/reply/commands.test.ts
   • src/auto-reply/status.test.ts

Minimal integration path

1) Add registry entry

In commands-registry.data.ts, add a defineChatCommand({...}) entry with:

• key
• nativeName
• description
• textAlias or textAliases
• category
• args / argsParsing / acceptsArgs only if needed

This is what makes the command:

• detectable from text
• eligible for native slash export
• visible in /commands

2) Implement a focused handler

Create src/auto-reply/reply/commands-<name>.ts.

Typical shape:

• early return if text commands disabled
• early return if normalized command doesn’t match /name
• auth gate via rejectUnauthorizedCommand(...) if needed
• parse args minimally
• return { shouldContinue: false, reply: { text } }