Gateway: add path-scoped config schema lookup (#37266)

Merged via squash.

Prepared head SHA: 0c4d187f6f
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Reviewed-by: @gumadeiras

src/agents/openclaw-gateway-tool.test.ts

@@ -11,6 +11,27 @@ vi.mock("./tools/gateway.js", () => ({
     if (method === "config.get") {
       return { hash: "hash-1" };
     }
+    if (method === "config.schema.lookup") {
+      return {
+        path: "gateway.auth",
+        schema: {
+          type: "object",
+        },
+        hint: { label: "Gateway Auth" },
+        hintPath: "gateway.auth",
+        children: [
+          {
+            key: "token",
+            path: "gateway.auth.token",
+            type: "string",
+            required: true,
+            hasChildren: false,
+            hint: { label: "Token", sensitive: true },
+            hintPath: "gateway.auth.token",
+          },
+        ],
+      };
+    }
     return { ok: true };
   }),
   readGatewayCallOptions: vi.fn(() => ({})),
@@ -166,4 +187,36 @@ describe("gateway tool", () => {
       expect(params).toMatchObject({ timeoutMs: 20 * 60_000 });
     }
   });
+
+  it("returns a path-scoped schema lookup result", async () => {
+    const { callGatewayTool } = await import("./tools/gateway.js");
+    const tool = requireGatewayTool();
+
+    const result = await tool.execute("call5", {
+      action: "config.schema.lookup",
+      path: "gateway.auth",
+    });
+
+    expect(callGatewayTool).toHaveBeenCalledWith("config.schema.lookup", expect.any(Object), {
+      path: "gateway.auth",
+    });
+    expect(result.details).toMatchObject({
+      ok: true,
+      result: {
+        path: "gateway.auth",
+        hintPath: "gateway.auth",
+        children: [
+          expect.objectContaining({
+            key: "token",
+            path: "gateway.auth.token",
+            required: true,
+            hintPath: "gateway.auth.token",
+          }),
+        ],
+      },
+    });
+    const schema = (result.details as { result?: { schema?: { properties?: unknown } } }).result
+      ?.schema;
+    expect(schema?.properties).toBeUndefined();
+  });
 });

src/agents/system-prompt.test.ts

@@ -443,10 +443,12 @@ describe("buildAgentSystemPrompt", () => {
     });
 
     expect(prompt).toContain("## OpenClaw Self-Update");
+    expect(prompt).toContain("config.schema.lookup");
     expect(prompt).toContain("config.apply");
     expect(prompt).toContain("config.patch");
     expect(prompt).toContain("update.run");
-    expect(prompt).not.toContain("config.schema");
+    expect(prompt).not.toContain("Use config.schema to");
+    expect(prompt).not.toContain("config.schema, config.apply");
   });
 
   it("includes skills guidance when skills prompt is present", () => {

src/agents/system-prompt.ts

@@ -482,7 +482,8 @@ export function buildAgentSystemPrompt(params: {
       ? [
           "Get Updates (self-update) is ONLY allowed when the user explicitly asks for it.",
           "Do not run config.apply or update.run unless the user explicitly requests an update or config change; if it's not explicit, ask first.",
-          "Actions: config.get, config.apply (validate + write full config, then restart), config.patch (partial update, merges with existing), update.run (update deps or git, then restart).",
+          "Use config.schema.lookup with a specific dot path to inspect only the relevant config subtree before making config changes or answering config-field questions; avoid guessing field names/types.",
+          "Actions: config.schema.lookup, config.get, config.apply (validate + write full config, then restart), config.patch (partial update, merges with existing), update.run (update deps or git, then restart).",
           "After restart, OpenClaw pings the last active session automatically.",
         ].join("\n")
       : "",

src/agents/tools/gateway-tool.ts

@@ -34,6 +34,7 @@ function resolveBaseHashFromSnapshot(snapshot: unknown): string | undefined {
 const GATEWAY_ACTIONS = [
   "restart",
   "config.get",
+  "config.schema.lookup",
   "config.apply",
   "config.patch",
   "update.run",
@@ -47,10 +48,12 @@ const GatewayToolSchema = Type.Object({
   // restart
   delayMs: Type.Optional(Type.Number()),
   reason: Type.Optional(Type.String()),
-  // config.get, config.apply, update.run
+  // config.get, config.schema.lookup, config.apply, update.run
   gatewayUrl: Type.Optional(Type.String()),
   gatewayToken: Type.Optional(Type.String()),
   timeoutMs: Type.Optional(Type.Number()),
+  // config.schema.lookup
+  path: Type.Optional(Type.String()),
   // config.apply, config.patch
   raw: Type.Optional(Type.String()),
   baseHash: Type.Optional(Type.String()),
@@ -73,7 +76,7 @@ export function createGatewayTool(opts?: {
     name: "gateway",
     ownerOnly: true,
     description:
-      "Restart, apply config, or update the gateway in-place (SIGUSR1). Use config.patch for safe partial config updates (merges with existing). Use config.apply only when replacing entire config. Both trigger restart after writing. Always pass a human-readable completion message via the `note` parameter so the system can deliver it to the user after restart.",
+      "Restart, inspect a specific config schema path, apply config, or update the gateway in-place (SIGUSR1). Use config.schema.lookup with a targeted dot path before config edits. Use config.patch for safe partial config updates (merges with existing). Use config.apply only when replacing entire config. Both trigger restart after writing. Always pass a human-readable completion message via the `note` parameter so the system can deliver it to the user after restart.",
     parameters: GatewayToolSchema,
     execute: async (_toolCallId, args) => {
       const params = args as Record<string, unknown>;
@@ -171,6 +174,14 @@ export function createGatewayTool(opts?: {
         const result = await callGatewayTool("config.get", gatewayOpts, {});
         return jsonResult({ ok: true, result });
       }
+      if (action === "config.schema.lookup") {
+        const path = readStringParam(params, "path", {
+          required: true,
+          label: "path",
+        });
+        const result = await callGatewayTool("config.schema.lookup", gatewayOpts, { path });
+        return jsonResult({ ok: true, result });
+      }
       if (action === "config.apply") {
         const { raw, baseHash, sessionKey, note, restartDelayMs } =
           await resolveConfigWriteParams();