fix(doctor): polish sandbox MCP warnings

nxmxbbd · nxmxbbd · commit e0290ceac5e0 · 2026-05-21T04:44:33.000+08:00
diff --git a/docs/gateway/config-tools.md b/docs/gateway/config-tools.md
@@ -54,6 +54,8 @@ Configured MCP servers are exposed as plugin-owned tools under the `bundle-mcp`
 - `group:plugins` for all loaded plugin-owned tools
 - exact MCP server globs such as `outlook__*` when you only want one server
 
+Server globs use the provider-safe MCP server prefix, not necessarily the raw `mcp.servers` key. Non-`[A-Za-z0-9_-]` characters become `-`, names that do not start with a letter get an `mcp-` prefix, and long or duplicate prefixes may be truncated or suffixed; for example, `mcp.servers["Outlook Graph"]` uses a glob like `outlook-graph__*`.
+
 ```json5
 {
   agents: { defaults: { sandbox: { mode: "all" } } },
@@ -72,7 +74,7 @@ Configured MCP servers are exposed as plugin-owned tools under the `bundle-mcp`
 }
 ```
 
-Without that sandbox-layer entry, the MCP server can still load successfully while its tools are filtered before the provider request. Use `openclaw doctor` to catch this shape.
+Without that sandbox-layer entry, the MCP server can still load successfully while its tools are filtered before the provider request. Use `openclaw doctor` to catch this shape for OpenClaw-managed servers in `mcp.servers`. MCP servers loaded from bundled plugin manifests or Claude `.mcp.json` use the same sandbox gate, but this diagnostic does not enumerate those sources yet; use the same allowlist entries if their tools disappear in sandboxed turns.
 
 ### `tools.allow` / `tools.deny`
 
diff --git a/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md b/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md
@@ -102,7 +102,9 @@ Available groups:
 - `group:openclaw`: all built-in OpenClaw tools (excludes provider plugins)
 - `group:plugins`: all loaded plugin-owned tools, including configured MCP servers exposed through `bundle-mcp`
 
-For sandboxed MCP servers, the sandbox tool policy is a second allow gate. If `mcp.servers` is configured but sandboxed turns only show built-in tools, add `bundle-mcp`, `group:plugins`, or a server glob such as `outlook__*` to `tools.sandbox.tools.alsoAllow`, then restart/reload the gateway and recapture the tool list.
+For sandboxed MCP servers, the sandbox tool policy is a second allow gate. If `mcp.servers` is configured but sandboxed turns only show built-in tools, add `bundle-mcp`, `group:plugins`, or a server glob such as `outlook__*` to `tools.sandbox.tools.alsoAllow`, then restart/reload the gateway and recapture the tool list. Server globs use the provider-safe MCP server prefix: non-`[A-Za-z0-9_-]` characters become `-`, names that do not start with a letter get an `mcp-` prefix, and long or duplicate prefixes may be truncated or suffixed.
+
+`openclaw doctor` currently checks this shape for OpenClaw-managed servers in `mcp.servers`. MCP servers loaded from bundled plugin manifests or Claude `.mcp.json` use the same sandbox gate, but this diagnostic does not enumerate those sources yet; use the same allowlist entries if their tools disappear in sandboxed turns.
 
 ## Elevated: exec-only "run on host"
 
diff --git a/src/commands/doctor/shared/plugin-tool-allowlist-warnings.test.ts b/src/commands/doctor/shared/plugin-tool-allowlist-warnings.test.ts
@@ -115,6 +115,43 @@ describe("collectPluginToolAllowlistWarnings", () => {
     ]);
   });
 
+  it("uses a config-path source label when sandbox allowlist is unset", () => {
+    const warnings = collectPluginToolAllowlistWarnings({
+      cfg: {
+        agents: { defaults: { sandbox: { mode: "all" } } },
+        mcp: { servers: { outlook: { command: "node", args: ["outlook-server.js"] } } },
+      },
+      manifestRegistry,
+    });
+
+    expect(warnings).toEqual([
+      '- mcp.servers defines 1 MCP server ("outlook"), but tools.sandbox.tools.alsoAllow (unset) does not include "bundle-mcp", "group:plugins", or a matching "<server>__*" MCP tool pattern. Sandboxed agents will filter bundled MCP tools before provider requests. Add "bundle-mcp" to tools.sandbox.tools.alsoAllow (or use "group:plugins" / server globs) if those MCP tools should be visible; use tools.sandbox.tools.allow: [] only when you intentionally want no sandbox allow gate.',
+    ]);
+  });
+
+  it("uses plural grammar when multiple sandbox allow sources hide MCP servers", () => {
+    const warnings = collectPluginToolAllowlistWarnings({
+      cfg: {
+        agents: {
+          defaults: { sandbox: { mode: "all" } },
+          list: [
+            {
+              id: "worker",
+              tools: { sandbox: { tools: { alsoAllow: ["web_fetch"] } } },
+            },
+          ],
+        },
+        mcp: { servers: { outlook: { command: "node", args: ["outlook-server.js"] } } },
+        tools: { sandbox: { tools: { alsoAllow: ["web_search"] } } },
+      },
+      manifestRegistry,
+    });
+
+    expect(warnings).toEqual([
+      '- mcp.servers defines 1 MCP server ("outlook"), but agents.list[0].tools.sandbox.tools.alsoAllow, tools.sandbox.tools.alsoAllow do not include "bundle-mcp", "group:plugins", or a matching "<server>__*" MCP tool pattern. Sandboxed agents will filter bundled MCP tools before provider requests. Add "bundle-mcp" to tools.sandbox.tools.alsoAllow (or use "group:plugins" / server globs) if those MCP tools should be visible; use tools.sandbox.tools.allow: [] only when you intentionally want no sandbox allow gate.',
+    ]);
+  });
+
   it("does not warn for sandboxed MCP servers when bundle-mcp is explicitly allowed", () => {
     const warnings = collectPluginToolAllowlistWarnings({
       cfg: {
@@ -198,6 +235,19 @@ describe("collectPluginToolAllowlistWarnings", () => {
     expect(warnings).toStrictEqual([]);
   });
 
+  it("does not warn when a server glob matches the sanitized MCP server name", () => {
+    const warnings = collectPluginToolAllowlistWarnings({
+      cfg: {
+        agents: { defaults: { sandbox: { mode: "all" } } },
+        mcp: { servers: { "Outlook Graph": { command: "node", args: ["outlook-server.js"] } } },
+        tools: { sandbox: { tools: { alsoAllow: ["outlook-graph__*"] } } },
+      },
+      manifestRegistry,
+    });
+
+    expect(warnings).toStrictEqual([]);
+  });
+
   it("does not warn for sandboxed MCP servers when sandbox allow is explicitly allow-all", () => {
     const warnings = collectPluginToolAllowlistWarnings({
       cfg: {
diff --git a/src/commands/doctor/shared/plugin-tool-allowlist-warnings.ts b/src/commands/doctor/shared/plugin-tool-allowlist-warnings.ts
@@ -79,14 +79,29 @@ function collectToolAllowlistSources(cfg: OpenClawConfig): ToolAllowlistSource[]
   return sources;
 }
 
-function formatSourceLabels(labels: Iterable<string>): string {
-  const sorted = [...new Set(labels)].toSorted((left, right) => left.localeCompare(right));
+function collectSortedSourceLabels(labels: Iterable<string>): string[] {
+  return [...new Set(labels)].toSorted((left, right) => left.localeCompare(right));
+}
+
+function formatSortedSourceLabels(sorted: readonly string[]): string {
   if (sorted.length <= 3) {
     return sorted.join(", ");
   }
   return `${sorted.slice(0, 3).join(", ")} (+${sorted.length - 3} more)`;
 }
 
+function formatSourceLabels(labels: Iterable<string>): string {
+  return formatSortedSourceLabels(collectSortedSourceLabels(labels));
+}
+
+function formatSourceLabelSubject(labels: Iterable<string>): { text: string; verb: "does" | "do" } {
+  const sorted = collectSortedSourceLabels(labels);
+  return {
+    text: formatSortedSourceLabels(sorted),
+    verb: sorted.length === 1 ? "does" : "do",
+  };
+}
+
 function collectToolOwners(registry: PluginManifestRegistry): Map<string, string[]> {
   const owners = new Map<string, string[]>();
   for (const plugin of registry.plugins) {
@@ -202,7 +217,7 @@ function buildEffectiveSandboxToolPolicy(params: {
   const allowLabels = [allow.label, alsoAllow.label].filter((label): label is string =>
     Boolean(label),
   );
-  const labels = allowLabels.length > 0 ? allowLabels : ["default sandbox tool allowlist"];
+  const labels = allowLabels.length > 0 ? allowLabels : ["tools.sandbox.tools.alsoAllow (unset)"];
   const dedupeLabels = Array.from(new Set([...labels, deny.label].filter(Boolean)));
 
   return {
@@ -233,13 +248,16 @@ function collectActiveSandboxToolPolicies(cfg: OpenClawConfig): ActiveSandboxToo
       if (!hasRecord(agent)) {
         return;
       }
-      const explicitMode = agent.sandbox?.mode;
+      const agentSandbox = hasRecord(agent.sandbox) ? agent.sandbox : undefined;
+      const explicitMode = agentSandbox?.mode;
       const agentSandboxActive =
         explicitMode === undefined ? defaultSandboxActive : isSandboxModeActive(explicitMode);
       if (!agentSandboxActive) {
         return;
       }
-      const agentPolicy = hasRecord(agent.tools?.sandbox) ? agent.tools.sandbox.tools : undefined;
+      const agentTools = hasRecord(agent.tools) ? agent.tools : undefined;
+      const agentToolsSandbox = hasRecord(agentTools?.sandbox) ? agentTools.sandbox : undefined;
+      const agentPolicy = hasRecord(agentToolsSandbox?.tools) ? agentToolsSandbox.tools : undefined;
       addPolicy(
         buildEffectiveSandboxToolPolicy({
           agentPolicy,
@@ -327,8 +345,9 @@ function collectSandboxMcpAllowlistWarnings(cfg: OpenClawConfig): string[] {
   if (issueSources.length === 0) {
     return [];
   }
+  const sourceSubject = formatSourceLabelSubject(issueSources);
   return [
-    `- mcp.servers defines ${formatMcpServerSummary(serverNames)}, but ${formatSourceLabels(issueSources)} does not include "bundle-mcp", "group:plugins", or a matching "<server>${TOOL_NAME_SEPARATOR}*" MCP tool pattern. Sandboxed agents will filter bundled MCP tools before provider requests. Add "bundle-mcp" to tools.sandbox.tools.alsoAllow (or use "group:plugins" / server globs) if those MCP tools should be visible; use tools.sandbox.tools.allow: [] only when you intentionally want no sandbox allow gate.`,
+    `- mcp.servers defines ${formatMcpServerSummary(serverNames)}, but ${sourceSubject.text} ${sourceSubject.verb} not include "bundle-mcp", "group:plugins", or a matching "<server>${TOOL_NAME_SEPARATOR}*" MCP tool pattern. Sandboxed agents will filter bundled MCP tools before provider requests. Add "bundle-mcp" to tools.sandbox.tools.alsoAllow (or use "group:plugins" / server globs) if those MCP tools should be visible; use tools.sandbox.tools.allow: [] only when you intentionally want no sandbox allow gate.`,
   ];
 }
 

Original file line number	Diff line number	Diff line change
@@ -54,6 +54,8 @@ Configured MCP servers are exposed as plugin-owned tools under the `bundle-mcp`
`54`	`54`	- `group:plugins` for all loaded plugin-owned tools
`55`	`55`	- exact MCP server globs such as `outlook__*` when you only want one server
`56`	`56`
	`57`	+Server globs use the provider-safe MCP server prefix, not necessarily the raw `mcp.servers` key. Non-`[A-Za-z0-9_-]` characters become `-`, names that do not start with a letter get an `mcp-` prefix, and long or duplicate prefixes may be truncated or suffixed; for example, `mcp.servers["Outlook Graph"]` uses a glob like `outlook-graph__*`.
	`58`	`+`
`57`	`59`	```json5
`58`	`60`	`{`
`59`	`61`	`agents: { defaults: { sandbox: { mode: "all" } } },`
@@ -72,7 +74,7 @@ Configured MCP servers are exposed as plugin-owned tools under the `bundle-mcp`
`72`	`74`	`}`
`73`	`75`	```
`74`	`76`
`75`		-Without that sandbox-layer entry, the MCP server can still load successfully while its tools are filtered before the provider request. Use `openclaw doctor` to catch this shape.
	`77`	+Without that sandbox-layer entry, the MCP server can still load successfully while its tools are filtered before the provider request. Use `openclaw doctor` to catch this shape for OpenClaw-managed servers in `mcp.servers`. MCP servers loaded from bundled plugin manifests or Claude `.mcp.json` use the same sandbox gate, but this diagnostic does not enumerate those sources yet; use the same allowlist entries if their tools disappear in sandboxed turns.
`76`	`78`
`77`	`79`	### `tools.allow` / `tools.deny`
`78`	`80`