The openclaw docs command fails immediately with a non-zero exit code when attempting to search documentation.

CLI Execution Output

$ openclaw --profile imladri-sidequest-2026-5-7 docs gateway
Docs search failed: MCP error -32602: Tool SearchOpenClaw not found

$ openclaw --profile imladri-sidequest-2026-5-7 docs health
Docs search failed: MCP error -32602: Tool SearchOpenClaw not found

$ echo $?
1

Technical Manifestations

• Exit Code: 1 (failure)
• MCP Error Code: -32602 (invalid parameters / tool not found)
• Error Pattern: Tool SearchOpenClaw not found
• Affected Command: openclaw docs <query>
• Impact Scope: All documentation search operations via CLI; agent self-help workflows that rely on docs search path

Diagnostic Indicators

The error originates from the MCP (Model Context Protocol) layer, indicating a tool name mismatch between:

• The tool name hardcoded or configured in the CLI's docs command handler
• The actual tool name registered in the active MCP server

Architectural Context

The openclaw docs command delegates documentation search to an MCP server that exposes a tool for querying the OpenClaw documentation index. The command handler constructs an MCP request targeting a specific tool name.

Failure Sequence

1. CLI Invocation: User executes openclaw docs <query>
2. Tool Invocation Request: CLI constructs an MCP tools/call request with name: "SearchOpenClaw"
3. MCP Protocol Layer: The MCP client forwards the request to the connected server
4. Tool Resolution Failure: MCP server returns error -32602 because no tool named SearchOpenClaw is registered
5. Error Propagation: CLI wraps the MCP error and terminates with exit code 1

Probable Root Causes

Primary: Tool Name Divergence

The MCP server exposes a tool under a different identifier. Common renames in the OpenClaw codebase:

• SearchOpenClaw → search_openclaw_docs (snake_case)
• SearchOpenClaw → docs_search (abbreviated)
• SearchOpenClaw → SearchDocs (different casing)

Secondary: Tool Registration Failure

The tool exists in the server codebase but failed to register during MCP server initialization:

• Missing @openclaw/mcp-tools package dependency
• Initialization order issue where docs tool registration occurs before index is ready
• Profile-specific configuration disabling the docs tool

Tertiary: Version Mismatch

The CLI version (2026.5.7) may reference a tool name from a newer or older API contract than what the MCP server exposes.

Relevant Code Paths

The error likely originates from:

• packages/cli/src/commands/docs.ts - constructs the MCP request
• packages/mcp-server/src/tools/registry.ts - tool registration logic
• .openclaw/mcp-config.json - profile-specific MCP configuration

Option A: Update CLI Configuration (Recommended)

If the tool exists under a different name, configure the CLI to use the correct name.

Step 1: List Available MCP Tools

powershell

Windows PowerShell

openclaw mcp list-tools –profile imladri-sidequest-2026-5-7

bash

macOS/Linux

openclaw mcp list-tools –profile imladri-sidequest-2026-5-7

Step 2: Identify the Correct Documentation Tool

Look for tools with names containing:

• search
• docs
• doc

Step 3: Update or Create Profile Configuration

If using a custom tool name, create a profile override:

json // ~/.openclaw/profiles/imladri-sidequest-2026-5-7/config.json { “mcp”: { “tools”: { “docsSearch”: { “toolName”: “search_openclaw_docs” } } } }

Option B: Reinstall to Restore Tool Bindings

Step 1: Clear npm Cache and Reinstall

powershell

Windows

npm cache clean –force npm uninstall -g openclaw npm install -g openclaw@latest

Verify installation

openclaw –version

Step 2: Reset MCP Configuration

powershell

Remove profile-specific MCP config

Remove-Item -Path “$env:USERPROFILE.openclaw\profiles\imladri-sidequest-2026-5-7\mcp-config.json” -Force

Reinitialize profile

openclaw init –profile imladri-sidequest-2026-5-7

Option C: Patch via Environment Variable (Temporary)

Override the tool name at runtime:

powershell

Windows

$env:OPENCLAW_DOCS_TOOL=“search_openclaw_docs” openclaw docs gateway

bash

macOS/Linux

OPENCLAW_DOCS_TOOL=“search_openclaw_docs” openclaw docs gateway

Option D: Manual Tool Registration (Advanced)

If you have access to the MCP server source:

Step 1: Locate Tool Registry

typescript // packages/mcp-server/src/tools/registry.ts import { registerTool } from ‘@openclaw/mcp-core’;

registerTool({ name: ‘SearchOpenClaw’, // Ensure this matches CLI expectation handler: searchOpenClawHandler, schema: searchOpenClawSchema });

Step 2: Verify Tool Name Consistency

Ensure the tool name in registry.ts matches the reference in docs.ts:

typescript // packages/cli/src/commands/docs.ts const response = await mcpClient.callTool({ name: ‘SearchOpenClaw’, // Must match registry arguments: { query } });

After applying the fix, verify the docs command functions correctly.

Step 1: Execute Docs Search with Known Query

powershell openclaw –profile imladri-sidequest-2026-5-7 docs gateway

Expected Output (Success):

[
  {
    "title": "API Gateway Configuration",
    "url": "https://docs.openclaw.dev/gateway",
    "snippet": "Configure the API gateway for routing..."
  },
  ...
]

Or Empty Results (Acceptable):

[]

Step 2: Verify Exit Code

powershell openclaw –profile imladri-sidequest-2026-5-7 docs gateway if ($LASTEXITCODE -eq 0) { Write-Host “SUCCESS: Docs search completed” } else { Write-Host “FAILURE: Exit code $LASTEXITCODE” }

Expected: SUCCESS: Docs search completed

Step 3: Test Multiple Query Terms

powershell $queries = @(“health”, “authentication”, “plugins”, “configuration”) foreach ($q in $queries) { openclaw docs $q if ($LASTEXITCODE -ne 0) { Write-Host “FAILED on query: $q” exit 1 } } Write-Host “All queries succeeded”

Step 4: Verify MCP Tool Discovery (Diagnostic)

powershell openclaw mcp list-tools –profile imladri-sidequest-2026-5-7 | Select-String -Pattern “search|doc”

Expected: At least one matching tool should appear in the output.

Environment-Specific Traps

• Windows Profile Path Encoding: Ensure profile names use hyphens or underscores, not spaces. The profile imladri-sidequest-2026-5-7 is valid; imladri sidequest may cause path resolution failures.
• npm Global Install Permissions: On Windows, npm install -g may require Administrator privileges or --force. Verify the package installed to the correct location:

  npm list -g openclaw --depth=0
  # Should show: C:\Users\<user>\AppData\Roaming\npm\openclaw

• Node.js Version Mismatch: OpenClaw 2026.5.7 requires Node >=18.0.0. Verify compatibility:

  node --version
  # Must be v18.x, v20.x, v22.x, or v24.x

Configuration Pitfalls

• Stale Profile Cache: After reinstalling OpenClaw, delete the profile cache to force re-initialization:

  # Windows
  Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw\profiles\imladri-sidequest-2026-5-7"
  macOS/Linux
  rm -rf ~/.openclaw/profiles/imladri-sidequest-2026-5-7

• MCP Config Precedence: Profile-level mcp-config.json overrides global settings. Ensure no conflicting tool names:

  Get-Content "$env:USERPROFILE\.openclaw\profiles\imladri-sidequest-2026-5-7\mcp-config.json"

• Proxy/Network Configuration: If the MCP server fetches docs from remote, proxy settings may block requests. Check HTTP_PROXY and HTTPS_PROXY environment variables.

User Misconfigurations

• Outdated CLI Without Tool Sync: Running an older CLI with a newer MCP server (or vice versa) causes tool name mismatches. Always use matching versions.
• Multiple OpenClaw Installations: Having both npm global and npx installations may lead to version confusion. Verify which binary is being executed:

  Get-Command openclaw | Select-Object Source

• Ignoring MCP Server Logs: The MCP server may log the actual tool names on startup. Enable debug logging:

  $env:OPENCLAW_DEBUG="mcp"
  openclaw docs gateway

Directly Related

• -32602: Tool SearchOpenClaw not found
  The specific error reported in this issue. Indicates the MCP server has no registered tool matching the requested name.
• -32601: Method not found
  MCP protocol error indicating the requested method (e.g., tools/call) is not supported by the server.
• -32603: Internal error
  MCP internal error, potentially from tool registration failing silently during server startup.

Historically Related

• Issue #39587 - Original docs-search functionality reports (locked). This issue is a more specific manifestation of tool discovery failures affecting docs search.
• ECONNREFUSED - MCP server not reachable. May occur if the docs tool handler fails to initialize and the server crashes.
• ETIMEDOUT - Network timeout when fetching docs index. Distinct from tool-not-found errors but may be confused in error handling.

Error Code Reference