feat(mcp): add bounded tools/list timeout override

Dockerfile

@@ -152,6 +152,7 @@
 COPY scripts/patch-openclaw-chat-send.mts /usr/local/lib/nemoclaw/patch-openclaw-chat-send.mts
 COPY scripts/patch-openclaw-mcp-npx.mts /usr/local/lib/nemoclaw/patch-openclaw-mcp-npx.mts
 COPY scripts/patch-openclaw-mcp-reliability.mts /usr/local/lib/nemoclaw/patch-openclaw-mcp-reliability.mts
+COPY scripts/patch-openclaw-mcp-tools-list-timeout.mts /usr/local/lib/nemoclaw/patch-openclaw-mcp-tools-list-timeout.mts
 COPY scripts/patch-openclaw-issue-4434-diagnostics.mts /usr/local/lib/nemoclaw/patch-openclaw-issue-4434-diagnostics.mts
 COPY scripts/patch-openclaw-managed-transport-diagnostics.mts /usr/local/lib/nemoclaw/patch-openclaw-managed-transport-diagnostics.mts
 COPY scripts/patch-openclaw-device-self-approval.mts /usr/local/lib/nemoclaw/patch-openclaw-device-self-approval.mts
@@ -401,6 +402,7 @@
         /usr/local/lib/nemoclaw/patch-openclaw-chat-send.mts \
         /usr/local/lib/nemoclaw/patch-openclaw-mcp-npx.mts \
         /usr/local/lib/nemoclaw/patch-openclaw-mcp-reliability.mts \
+        /usr/local/lib/nemoclaw/patch-openclaw-mcp-tools-list-timeout.mts \
         /usr/local/lib/nemoclaw/patch-openclaw-issue-4434-diagnostics.mts \
         /usr/local/lib/nemoclaw/patch-openclaw-managed-transport-diagnostics.mts \
         /usr/local/lib/nemoclaw/patch-openclaw-device-self-approval.mts \
@@ -1032,6 +1034,17 @@
 RUN node --experimental-strip-types /usr/local/lib/nemoclaw/patch-openclaw-mcp-reliability.mts \
     /usr/local/lib/node_modules/openclaw/dist
 
+# Keep OpenClaw's 1,500 ms tools/list catalog timeout by default. A validated
+# OpenClaw sandbox runtime setting can override only this discovery budget from
+# 1,500 ms through 10,000 ms. Invalid direct runtime values stop OpenClaw before
+# it connects to an MCP server.
+#
+# Removal criterion: drop when upstream OpenClaw exposes an equivalent bounded
+# tools/list-only runtime setting.
+# hadolint ignore=DL3059
+RUN node --experimental-strip-types /usr/local/lib/nemoclaw/patch-openclaw-mcp-tools-list-timeout.mts \
+    /usr/local/lib/node_modules/openclaw/dist
+
 # Emit a redacted managed-transport diagnostic when a remote Streamable HTTP MCP
 # request fails. OpenClaw 2026.7.1 surfaces only the transport error text, which
 # does not say whether policy, CONNECT, TLS, the upstream connection, the
@@ -1202,10 +1215,10 @@
 # CHAT_UI_URL is a non-loopback address (Brev Launchable, remote deployments)
 # since terminal-based pairing is impossible in those contexts.
 # Default: "0" (device auth enabled for local deployments — secure by default).
 ARG NEMOCLAW_DISABLE_DEVICE_AUTH=0
 # Internal audit provenance for the opt-out above. Standard onboarding rewrites
 # this to managed-onboard; direct image builders retain operator provenance.
 ARG NEMOCLAW_DEVICE_AUTH_OPT_OUT_SOURCE=operator
 # Compatibility build arg for older custom Dockerfiles and rebuild tooling.
 # NemoClaw-managed images intentionally do not consume it; gateway auth tokens
 # are generated at container startup and are never baked into image layers.
@@ -1239,7 +1252,7 @@
 # NEMOCLAW_MESSAGING_PLAN_B64 intentionally remains ARG-only: Docker exposes it
 # to build RUN processes without retaining the full plan in the final image env.
 # Direct ARG interpolation into inline source is a code injection vector (C-2).
 ENV NEMOCLAW_MODEL=${NEMOCLAW_MODEL} \
     NEMOCLAW_INFERENCE_PROVIDER_ID=${NEMOCLAW_INFERENCE_PROVIDER_ID} \
     NEMOCLAW_UPSTREAM_PROVIDER=${NEMOCLAW_UPSTREAM_PROVIDER} \
     NEMOCLAW_PRIMARY_MODEL_REF=${NEMOCLAW_PRIMARY_MODEL_REF} \

ci/source-architecture-budget.json

@@ -60,6 +60,6 @@
     "src/lib/actions/sandbox": 184,
     "src/lib/state": 37,
     "src/lib/inference": 63,
-    "scripts": 46
+    "scripts": 47
   }
 }

docs/reference/commands.mdx

@@ -4390,6 +4390,25 @@ Then open `http://localhost:16686` and select the `openclaw-gateway` service.
 The built-in `openclaw-diagnostics-otel-local` preset allows only `POST /v1/traces` (and subpaths) to `host.openshell.internal:4318` from `openclaw` and `node`.
 For a remote collector, create a custom preset for the collector host and port instead of using the local host-gateway preset.
 
+### OpenClaw MCP Tool Discovery Timeout
+
+Set `NEMOCLAW_MCP_TOOLS_LIST_TIMEOUT_MS` before onboarding or rebuilding an OpenClaw sandbox to override its `tools/list` timeout.
+The setting accepts an integer from `1500` through `10000` milliseconds.
+When unset or blank, NemoClaw adds no override; OpenClaw uses a server-specific request timeout when configured and otherwise uses its 1,500 ms fallback.
+The override applies to catalog `tools/list` requests for every MCP server in that sandbox and takes precedence over a server-specific request timeout.
+It does not change connection timeouts or the separate MCP tool-call request timeout, which defaults to 60,000 ms.
+NemoClaw rejects an invalid value before the sandbox create step, including the replacement create step during rebuild.
+
+For an existing sandbox, apply a 3,000 ms timeout:
+
+```bash
+export NEMOCLAW_MCP_TOOLS_LIST_TIMEOUT_MS=3000
+$$nemoclaw <sandbox> rebuild
+```
+
+OpenClaw writes `mcp_tools_list_timeout_override_ms=3000` when the MCP runtime loads.
+Refer to [Troubleshoot MCP Servers](troubleshoot-mcp-servers#adjust-the-tool-discovery-timeout) for the incremental test and rollback procedure.
+
 </AgentOnly>
 
 ### Probe Timeouts

docs/reference/troubleshoot-mcp-servers.mdx

@@ -157,6 +157,64 @@ If NemoClaw cannot enable OpenShell audit logs, it prints a warning and the poli
 `diagnostic_id` is a local identifier created for one line group.
 It is not a distributed trace identifier and does not appear in OpenShell audit events.
 Correlate with OpenShell by endpoint and time until OpenShell records a shared identifier.
+
+### Adjust the Tool Discovery Timeout
+
+OpenClaw uses a 1,500 ms timeout for `tools/list` when no server-specific request timeout exists.
+This discovery request retrieves tool names and schemas; it does not execute an MCP tool.
+
+Set `NEMOCLAW_MCP_TOOLS_LIST_TIMEOUT_MS` before you create or rebuild an OpenClaw sandbox to override only this discovery timeout.
+The value must be an integer from `1500` through `10000`.
+When the value is unset or blank, NemoClaw adds no override.
+OpenClaw then uses a server-specific request timeout when configured and otherwise uses its 1,500 ms fallback.
+The override applies to catalog `tools/list` requests for every MCP server in the sandbox and takes precedence over a server-specific request timeout.
+NemoClaw rejects an invalid value before the sandbox create step, including the replacement create step during rebuild.
+
+<Warning>
+Rebuilding interrupts the agent while NemoClaw replaces the sandbox and restores its managed state.
+A longer timeout does not correct an HTTP 503 response, an authentication failure, a policy denial, or a connection failure.
+</Warning>
+
+For an existing sandbox, start with 3,000 ms:
+
+```bash
+export NEMOCLAW_MCP_TOOLS_LIST_TIMEOUT_MS=3000
+$$nemoclaw <sandbox> rebuild
+```
+
+OpenClaw writes the selected override once when its MCP runtime loads:
+
+```text
+[nemoclaw] mcp_tools_list_timeout_override_ms=3000
+```
+
+Verify the selected value in recent startup output:
+
+```bash
+$$nemoclaw <sandbox> logs --tail 100
+```
+
+Choose a repeat count before testing, such as 10 runs.
+After each rebuild, run the identical tool-discovery workflow that many times.
+Current OpenClaw timeout errors do not identify the JSON-RPC operation, so reproduce through catalog loading rather than a tool call.
+Advance from `3000` to `5000`, and then to `10000`, only when catalog loading fails and the recent logs contain:
+
+```text
+McpError: MCP error -32001: Request timed out
+```
+
+Stop at the lowest value that completes every planned catalog-loading run without that error.
+Do not increase this setting for `MCP server ... connection timed out after 30000ms`; that message reports the separate connection timeout.
+Do not increase the value after an explicit HTTP 503 response or a non-timeout transport failure.
+
+Unset the override and rebuild to restore OpenClaw's normal server-specific or 1,500 ms fallback selection:
+
+```bash
+unset NEMOCLAW_MCP_TOOLS_LIST_TIMEOUT_MS
+$$nemoclaw <sandbox> rebuild
+```
+
+Inspect the recent startup output again and verify that the new OpenClaw start did not add an `mcp_tools_list_timeout_override_ms` line.
 </AgentOnly>
 
 ## Policy or Provider Ownership Drifted

docs/security/openclaw-2026.7.1-dependency-review.md

@@ -499,6 +499,40 @@ A reusable source schema is deferred until a production consumer requires one.
 
 Removal criterion: drop this patch when the reviewed OpenClaw release emits redacted diagnostics classified by transport phase for remote MCP fetch failures.
 
+## Bounded MCP Tool Discovery Timeout
+
+`scripts/patch-openclaw-mcp-tools-list-timeout.mts` is a version-scoped, fail-closed compatibility patch.
+The transport symptoms investigated in issue #7957 motivated this bounded follow-up; the patch does not change that issue's diagnostics acceptance criteria.
+OpenClaw `2026.7.1` gives `tools/list` 1,500 ms unless an MCP server configuration supplies a request timeout.
+The managed mcporter registration does not expose a tool-discovery-only timeout.
+
+The patch identifies the compiled target by the `"openclaw-bundle-mcp"` client identity.
+It requires the 1,500 ms constant and the complete catalog-timeout resolver to appear exactly once.
+An unrecognized compiled shape fails the image build.
+`--audit` re-verifies the applied state.
+
+Reviewed behavior:
+
+- An unset or blank `NEMOCLAW_MCP_TOOLS_LIST_TIMEOUT_MS` value adds no override.
+  OpenClaw then uses a server-specific request timeout when configured and otherwise uses its 1,500 ms fallback.
+- NemoClaw forwards the setting only to an OpenClaw sandbox.
+  Host-side validation trims surrounding whitespace, accepts the remaining canonical integer from 1,500 through 10,000 ms, forwards normalized digits, and rejects an invalid value before the sandbox create step, including the replacement create step during rebuild.
+- The injected runtime parser repeats the range and integer checks.
+  It ignores the host-side setting unless `OPENSHELL_SANDBOX=1` and stops module initialization for an invalid direct runtime value.
+- A valid override takes precedence over the server request timeout only for catalog `tools/list` requests.
+  It does not change the 30,000 ms connection timeout or the 60,000 ms default used by tool calls and other MCP requests.
+- OpenClaw writes one `mcp_tools_list_timeout_override_ms` line when the MCP runtime loads with an override.
+  The default path emits no additional log line.
+- The existing OpenClaw test-only timeout setter keeps first precedence so upstream runtime tests retain their isolation control.
+- The build patch runs only for OpenClaw `2026.7.1`.
+  It skips the reviewed `2026.3.11` and `2026.4.24` stale-upgrade E2E fixture versions before bundle discovery and rejects every other version.
+
+`test/openclaw-mcp-tools-list-timeout-patch.test.ts` executes the injected parser and pins the compiled preimage.
+It covers patch idempotence, fail-closed drift rejection, host and sandbox gates, bounds, invalid values, and composition with managed transport diagnostics.
+`src/lib/onboard/sandbox-create-launch.test.ts` covers canonical forwarding, range rejection, and exclusion from Hermes and Deep Agents Code sandboxes.
+
+Removal criterion: drop this patch when the reviewed OpenClaw release provides an equivalent bounded `tools/list`-only runtime setting.
+
 ## Gateway Startup Migration Compatibility
 
 OpenClaw `2026.7.1` requires its migration checkpoint to complete without