improve(mxc): document sandbox config options and flag network access as dangerous (#110256)

Add configContracts.dangerousFlags for network="default", per-field uiHints,
and configSchema/Zod field descriptions to the MXC sandbox plugin manifest.
Only network is flagged dangerous; containment "process" and "processcontainer"
currently resolve to the same Windows ProcessContainer. Align the manifest
description with the plugin entry and update the config schema test for the new
timeout description.


Copilot-Session: c299e8bd-b71c-4bb4-94a9-9c248543102a

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

extensions/mxc/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "mxc",
   "name": "MXC Sandbox Execution",
-  "description": "OS-level sandboxed tool execution via MXC for MXC-capable Windows hosts: runs commands in ProcessContainer (Windows) with configured MXC policy files.",
+  "description": "OS-level sandboxed tool execution via MXC: runs commands in a Windows ProcessContainer with configured MXC policy files.",
   "activation": {
     "onStartup": false,
     "onConfigPaths": ["plugins.entries.mxc"]
@@ -12,31 +12,70 @@
     "properties": {
       "mxcBinaryPath": {
         "type": "string",
-        "minLength": 1
+        "minLength": 1,
+        "description": "Absolute path to the MXC executor (wxc-exec.exe). When unset, the executor is discovered from the installed @microsoft/mxc-sdk."
       },
       "containment": {
         "type": "string",
-        "enum": ["process", "processcontainer"]
+        "enum": ["process", "processcontainer"],
+        "description": "Windows containment mode. 'process' and 'processcontainer' currently both resolve to the Windows ProcessContainer sandbox."
       },
       "network": {
         "type": "string",
-        "enum": ["none", "default"]
+        "enum": ["none", "default"],
+        "description": "Outbound network policy. 'none' blocks all network; 'default' allows outbound access via the internetClient capability."
       },
       "timeoutSeconds": {
         "type": "number",
         "minimum": 1,
-        "maximum": 2147000
+        "maximum": 2147000,
+        "description": "Per-command execution timeout in seconds. Capped to the sandbox policy baseline timeout when both are set."
       },
       "debug": {
-        "type": "boolean"
+        "type": "boolean",
+        "description": "Forward verbose debug output from the MXC SDK launcher."
       },
       "mxcPolicyPaths": {
         "type": "array",
         "items": {
           "type": "string",
           "minLength": 1
-        }
+        },
+        "description": "Absolute MXC policy file paths applied on top of the built-in sandbox baseline policy."
       }
     }
+  },
+  "configContracts": {
+    "dangerousFlags": [{ "path": "network", "equals": "default" }]
+  },
+  "uiHints": {
+    "mxcBinaryPath": {
+      "label": "MXC Executor Path",
+      "help": "Optional absolute path to the MXC executor (wxc-exec.exe). Leave unset to auto-discover from the installed @microsoft/mxc-sdk.",
+      "advanced": true
+    },
+    "containment": {
+      "label": "Containment Mode",
+      "help": "Windows containment mode. 'process' and 'processcontainer' currently both resolve to the Windows ProcessContainer sandbox."
+    },
+    "network": {
+      "label": "Network Policy",
+      "help": "'none' blocks all outbound network; 'default' allows outbound access via the internetClient capability, which weakens sandbox isolation."
+    },
+    "timeoutSeconds": {
+      "label": "Command Timeout (seconds)",
+      "help": "Per-command execution timeout, from 1 to 2147000 seconds. Capped to the sandbox policy baseline timeout when both are set.",
+      "advanced": true
+    },
+    "debug": {
+      "label": "Debug Logging",
+      "help": "Forward verbose debug output from the MXC SDK launcher.",
+      "advanced": true
+    },
+    "mxcPolicyPaths": {
+      "label": "MXC Policy Files",
+      "help": "Absolute MXC policy file paths applied on top of the built-in sandbox baseline policy.",
+      "advanced": true
+    }
   }
 }

extensions/mxc/src/config.ts

@@ -42,16 +42,26 @@ const nonEmptyTrimmedString = (message: string) =>
   z.string({ error: message }).trim().min(1, { error: message });
 
 const MxcPluginConfigSchema = z.strictObject({
-  mxcBinaryPath: nonEmptyTrimmedString("mxcBinaryPath must be a non-empty string").optional(),
+  mxcBinaryPath: nonEmptyTrimmedString("mxcBinaryPath must be a non-empty string")
+    .describe(
+      "Absolute path to the MXC executor (wxc-exec.exe). When unset, the executor is discovered from the installed @microsoft/mxc-sdk.",
+    )
+    .optional(),
   containment: z
     .enum(MXC_CONTAINMENTS, {
       error: `containment must be one of ${MXC_CONTAINMENTS.join(", ")}`,
     })
+    .describe(
+      "Windows containment mode. 'process' and 'processcontainer' currently both resolve to the Windows ProcessContainer sandbox.",
+    )
     .optional(),
   network: z
     .enum(MXC_NETWORK_MODES, {
       error: `network must be one of ${MXC_NETWORK_MODES.join(", ")}`,
     })
+    .describe(
+      "Outbound network policy. 'none' blocks all network; 'default' allows outbound access via the internetClient capability.",
+    )
     .optional(),
   timeoutSeconds: z
     .number({
@@ -61,12 +71,21 @@ const MxcPluginConfigSchema = z.strictObject({
     .max(MAX_TIMER_TIMEOUT_SECONDS, {
       error: `timeoutSeconds must be a number <= ${MAX_TIMER_TIMEOUT_SECONDS}`,
     })
+    .describe(
+      "Per-command execution timeout in seconds. Capped to the sandbox policy baseline timeout when both are set.",
+    )
+    .optional(),
+  debug: z
+    .boolean({ error: "debug must be a boolean" })
+    .describe("Forward verbose debug output from the MXC SDK launcher.")
     .optional(),
-  debug: z.boolean({ error: "debug must be a boolean" }).optional(),
   mxcPolicyPaths: z
     .array(nonEmptyTrimmedString("mxcPolicyPaths must be an array of non-empty strings"), {
       error: "mxcPolicyPaths must be an array of non-empty strings",
     })
+    .describe(
+      "Absolute MXC policy file paths applied on top of the built-in sandbox baseline policy.",
+    )
     .optional(),
 });
 

extensions/mxc/test/config.test.ts

@@ -109,6 +109,8 @@ describe("createMxcPluginConfigSchema", () => {
       type: "number",
       minimum: 1,
       maximum: MAX_TIMER_TIMEOUT_SECONDS,
+      description:
+        "Per-command execution timeout in seconds. Capped to the sandbox policy baseline timeout when both are set.",
     });
   });
 });