[Feat] Gateway: add commands.list RPC method (openclaw#62656)

Merged via squash.

Co-authored-by: samzong <samzong.lu@gmail.com>
Co-authored-by: Frank Yang <frank.ekn@gmail.com>
Reviewed-by: @frankekn

Author: samzong

CHANGELOG.md

@@ -13,6 +13,7 @@ Docs: https://docs.openclaw.ai
 - Gateway: split startup and runtime seams so gateway lifecycle sequencing, reload state, and shutdown behavior stay easier to maintain without changing observed behavior. (#63975) Thanks @gumadeiras.
 - CLI/exec policy: add a local `openclaw exec-policy` command with `show`, `preset`, and `set` subcommands for synchronizing requested `tools.exec.*` config with the local exec approvals file, plus follow-up hardening for node-host rejection, rollback safety, and sync conflict detection.
 - Models/providers: add per-provider `models.providers.*.request.allowPrivateNetwork` for trusted self-hosted OpenAI-compatible endpoints, keep the opt-in scoped to model request surfaces, and refresh cached WebSocket managers when request transport overrides change. (#63671) Thanks @qas.
+- Gateway: add a `commands.list` RPC so remote gateway clients can discover runtime-native, text, skill, and plugin commands with surface-aware naming and serialized argument metadata. (#62656) Thanks @samzong.
 
 ### Fixes
 

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -2883,6 +2883,92 @@ public struct ModelsListResult: Codable, Sendable {
     }
 }
 
+public struct CommandEntry: Codable, Sendable {
+    public let name: String
+    public let nativename: String?
+    public let textaliases: [String]?
+    public let description: String
+    public let category: AnyCodable?
+    public let source: AnyCodable
+    public let scope: AnyCodable
+    public let acceptsargs: Bool
+    public let args: [[String: AnyCodable]]?
+
+    public init(
+        name: String,
+        nativename: String?,
+        textaliases: [String]?,
+        description: String,
+        category: AnyCodable?,
+        source: AnyCodable,
+        scope: AnyCodable,
+        acceptsargs: Bool,
+        args: [[String: AnyCodable]]?)
+    {
+        self.name = name
+        self.nativename = nativename
+        self.textaliases = textaliases
+        self.description = description
+        self.category = category
+        self.source = source
+        self.scope = scope
+        self.acceptsargs = acceptsargs
+        self.args = args
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case name
+        case nativename = "nativeName"
+        case textaliases = "textAliases"
+        case description
+        case category
+        case source
+        case scope
+        case acceptsargs = "acceptsArgs"
+        case args
+    }
+}
+
+public struct CommandsListParams: Codable, Sendable {
+    public let agentid: String?
+    public let provider: String?
+    public let scope: AnyCodable?
+    public let includeargs: Bool?
+
+    public init(
+        agentid: String?,
+        provider: String?,
+        scope: AnyCodable?,
+        includeargs: Bool?)
+    {
+        self.agentid = agentid
+        self.provider = provider
+        self.scope = scope
+        self.includeargs = includeargs
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case agentid = "agentId"
+        case provider
+        case scope
+        case includeargs = "includeArgs"
+    }
+}
+
+public struct CommandsListResult: Codable, Sendable {
+    public let commands: [CommandEntry]
+
+    public init(
+        commands: [CommandEntry])
+    {
+        self.commands = commands
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case commands
+    }
+}
+
 public struct SkillsStatusParams: Codable, Sendable {
     public let agentid: String?
 

apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift

@@ -2883,6 +2883,92 @@ public struct ModelsListResult: Codable, Sendable {
     }
 }
 
+public struct CommandEntry: Codable, Sendable {
+    public let name: String
+    public let nativename: String?
+    public let textaliases: [String]?
+    public let description: String
+    public let category: AnyCodable?
+    public let source: AnyCodable
+    public let scope: AnyCodable
+    public let acceptsargs: Bool
+    public let args: [[String: AnyCodable]]?
+
+    public init(
+        name: String,
+        nativename: String?,
+        textaliases: [String]?,
+        description: String,
+        category: AnyCodable?,
+        source: AnyCodable,
+        scope: AnyCodable,
+        acceptsargs: Bool,
+        args: [[String: AnyCodable]]?)
+    {
+        self.name = name
+        self.nativename = nativename
+        self.textaliases = textaliases
+        self.description = description
+        self.category = category
+        self.source = source
+        self.scope = scope
+        self.acceptsargs = acceptsargs
+        self.args = args
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case name
+        case nativename = "nativeName"
+        case textaliases = "textAliases"
+        case description
+        case category
+        case source
+        case scope
+        case acceptsargs = "acceptsArgs"
+        case args
+    }
+}
+
+public struct CommandsListParams: Codable, Sendable {
+    public let agentid: String?
+    public let provider: String?
+    public let scope: AnyCodable?
+    public let includeargs: Bool?
+
+    public init(
+        agentid: String?,
+        provider: String?,
+        scope: AnyCodable?,
+        includeargs: Bool?)
+    {
+        self.agentid = agentid
+        self.provider = provider
+        self.scope = scope
+        self.includeargs = includeargs
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case agentid = "agentId"
+        case provider
+        case scope
+        case includeargs = "includeArgs"
+    }
+}
+
+public struct CommandsListResult: Codable, Sendable {
+    public let commands: [CommandEntry]
+
+    public init(
+        commands: [CommandEntry])
+    {
+        self.commands = commands
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case commands
+    }
+}
+
 public struct SkillsStatusParams: Codable, Sendable {
     public let agentid: String?
 

docs/gateway/protocol.md

@@ -400,7 +400,7 @@ implemented in `src/gateway/server-methods/*.ts`.
   - `wake` schedules an immediate or next-heartbeat wake text injection
   - `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`,
     `cron.run`, `cron.runs`
-- skills/tools: `skills.*`, `tools.catalog`, `tools.effective`
+- skills/tools: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`
 
 ### Common event families
 
@@ -431,6 +431,18 @@ implemented in `src/gateway/server-methods/*.ts`.
 
 ### Operator helper methods
 
+- Operators may call `commands.list` (`operator.read`) to fetch the runtime
+  command inventory for an agent.
+  - `agentId` is optional; omit it to read the default agent workspace.
+  - `scope` controls which surface the primary `name` targets:
+    - `text` returns the primary text command token without the leading `/`
+    - `native` and the default `both` path return provider-aware native names
+      when available
+  - `textAliases` carries exact slash aliases such as `/model` and `/m`.
+  - `nativeName` carries the provider-aware native command name when one exists.
+  - `provider` is optional and only affects native naming plus native plugin
+    command availability.
+  - `includeArgs=false` omits serialized argument metadata from the response.
 - Operators may call `tools.catalog` (`operator.read`) to fetch the runtime tool catalog for an
   agent. The response includes grouped tools and provenance metadata:
   - `source`: `core` or `plugin`

src/gateway/method-scopes.ts

@@ -76,6 +76,7 @@ const METHOD_SCOPE_GROUPS: Record<OperatorScope, readonly string[]> = {
     "usage.cost",
     "tts.status",
     "tts.providers",
+    "commands.list",
     "models.list",
     "tools.catalog",
     "tools.effective",

src/gateway/protocol/index.ts

@@ -56,6 +56,11 @@ import {
   ChannelsStatusParamsSchema,
   type ChannelsStatusResult,
   ChannelsStatusResultSchema,
+  type CommandEntry,
+  type CommandsListParams,
+  CommandsListParamsSchema,
+  type CommandsListResult,
+  CommandsListResultSchema,
   type ChatAbortParams,
   ChatAbortParamsSchema,
   type ChatEvent,
@@ -295,6 +300,7 @@ const ajv = new (AjvPkg as unknown as new (opts?: object) => import("ajv").defau
   removeAdditional: false,
 });
 
+export const validateCommandsListParams = ajv.compile<CommandsListParams>(CommandsListParamsSchema);
 export const validateConnectParams = ajv.compile<ConnectParams>(ConnectParamsSchema);
 export const validateRequestFrame = ajv.compile<RequestFrame>(RequestFrameSchema);
 export const validateResponseFrame = ajv.compile<ResponseFrame>(ResponseFrameSchema);
@@ -624,6 +630,8 @@ export {
   AgentsFilesSetResultSchema,
   AgentsListParamsSchema,
   AgentsListResultSchema,
+  CommandsListParamsSchema,
+  CommandsListResultSchema,
   ModelsListParamsSchema,
   SkillsStatusParamsSchema,
   ToolsCatalogParamsSchema,
@@ -726,6 +734,9 @@ export type {
   AgentsFilesSetResult,
   AgentsListParams,
   AgentsListResult,
+  CommandsListParams,
+  CommandsListResult,
+  CommandEntry,
   SkillsStatusParams,
   ToolsCatalogParams,
   ToolsCatalogResult,

src/gateway/protocol/schema.ts

@@ -1,6 +1,7 @@
 export * from "./schema/agent.js";
 export * from "./schema/agents-models-skills.js";
 export * from "./schema/channels.js";
+export * from "./schema/commands.js";
 export * from "./schema/config.js";
 export * from "./schema/cron.js";
 export * from "./schema/error-codes.js";

src/gateway/protocol/schema/commands.ts

@@ -0,0 +1,76 @@
+import { Type } from "@sinclair/typebox";
+import { NonEmptyString } from "./primitives.js";
+
+export const CommandSourceSchema = Type.Union([
+  Type.Literal("native"),
+  Type.Literal("skill"),
+  Type.Literal("plugin"),
+]);
+
+export const CommandScopeSchema = Type.Union([
+  Type.Literal("text"),
+  Type.Literal("native"),
+  Type.Literal("both"),
+]);
+
+export const CommandCategorySchema = Type.Union([
+  Type.Literal("session"),
+  Type.Literal("options"),
+  Type.Literal("status"),
+  Type.Literal("management"),
+  Type.Literal("media"),
+  Type.Literal("tools"),
+  Type.Literal("docks"),
+]);
+
+export const CommandArgChoiceSchema = Type.Object(
+  {
+    value: Type.String(),
+    label: Type.String(),
+  },
+  { additionalProperties: false },
+);
+
+export const CommandArgSchema = Type.Object(
+  {
+    name: NonEmptyString,
+    description: Type.String(),
+    type: Type.Union([Type.Literal("string"), Type.Literal("number"), Type.Literal("boolean")]),
+    required: Type.Optional(Type.Boolean()),
+    choices: Type.Optional(Type.Array(CommandArgChoiceSchema)),
+    dynamic: Type.Optional(Type.Boolean()),
+  },
+  { additionalProperties: false },
+);
+
+export const CommandEntrySchema = Type.Object(
+  {
+    name: NonEmptyString,
+    nativeName: Type.Optional(NonEmptyString),
+    textAliases: Type.Optional(Type.Array(NonEmptyString)),
+    description: Type.String(),
+    category: Type.Optional(CommandCategorySchema),
+    source: CommandSourceSchema,
+    scope: CommandScopeSchema,
+    acceptsArgs: Type.Boolean(),
+    args: Type.Optional(Type.Array(CommandArgSchema)),
+  },
+  { additionalProperties: false },
+);
+
+export const CommandsListParamsSchema = Type.Object(
+  {
+    agentId: Type.Optional(NonEmptyString),
+    provider: Type.Optional(NonEmptyString),
+    scope: Type.Optional(CommandScopeSchema),
+    includeArgs: Type.Optional(Type.Boolean()),
+  },
+  { additionalProperties: false },
+);
+
+export const CommandsListResultSchema = Type.Object(
+  {
+    commands: Type.Array(CommandEntrySchema),
+  },
+  { additionalProperties: false },
+);

src/gateway/protocol/schema/protocol-schemas.ts

@@ -60,6 +60,11 @@ import {
   WebLoginStartParamsSchema,
   WebLoginWaitParamsSchema,
 } from "./channels.js";
+import {
+  CommandEntrySchema,
+  CommandsListParamsSchema,
+  CommandsListResultSchema,
+} from "./commands.js";
 import {
   ConfigApplyParamsSchema,
   ConfigGetParamsSchema,
@@ -297,6 +302,9 @@ export const ProtocolSchemas = {
   ModelChoice: ModelChoiceSchema,
   ModelsListParams: ModelsListParamsSchema,
   ModelsListResult: ModelsListResultSchema,
+  CommandEntry: CommandEntrySchema,
+  CommandsListParams: CommandsListParamsSchema,
+  CommandsListResult: CommandsListResultSchema,
   SkillsStatusParams: SkillsStatusParamsSchema,
   ToolsCatalogParams: ToolsCatalogParamsSchema,
   ToolCatalogProfile: ToolCatalogProfileSchema,

src/gateway/protocol/schema/types.ts

@@ -105,6 +105,9 @@ export type AgentsListResult = SchemaType<"AgentsListResult">;
 export type ModelChoice = SchemaType<"ModelChoice">;
 export type ModelsListParams = SchemaType<"ModelsListParams">;
 export type ModelsListResult = SchemaType<"ModelsListResult">;
+export type CommandEntry = SchemaType<"CommandEntry">;
+export type CommandsListParams = SchemaType<"CommandsListParams">;
+export type CommandsListResult = SchemaType<"CommandsListResult">;
 export type SkillsStatusParams = SchemaType<"SkillsStatusParams">;
 export type ToolsCatalogParams = SchemaType<"ToolsCatalogParams">;
 export type ToolCatalogProfile = SchemaType<"ToolCatalogProfile">;