# Troubleshooting and known gotchas

**`deep-research` shows as "disabled" or "Visible to model: no" in `openclaw skills list`.**
A workspace skill is registering under the same name and shadowing the orchestrator. The usual culprit is the ClawHub skill `agent-deep-research` (its SKILL.md frontmatter says `name: deep-research`). Run `scripts/doctor.sh` to confirm, then `rm -rf ~/.openclaw/workspace/skills/agent-deep-research` and restart the gateway. The orchestrator in this repo is deployed to `~/.openclaw/skills/deep-research/` and is routed from TOOLS.md, so it keeps working through that path even while shadowed, but the registry entry will be wrong.

**MCP config key.** OpenClaw reads `mcp.servers` (nested). A flat `mcpServers` block is silently ignored.

**Only stdio transport is supported.** Remote MCP endpoints (Exa) are bridged with `npx -y mcp-remote <url>`. The Exa key rides in the URL query string, so it is visible in `openclaw config get mcp.servers.exa`.

**MCP servers lazy-load.** They start on first agent use, not at gateway boot. The first research call after a restart is slower, and a broken server only shows up in the gateway log at that point: `openclaw gateway logs` or `~/.openclaw/logs/`.

**`npx -y` servers need network on first use.** `knowledge-graph-memory` and `mcp-remote` are fetched on demand. Warm them once with `npx -y @modelcontextprotocol/server-memory --help` if the gateway host has restricted egress.

**BCC Research proxy.** BCC's public endpoint speaks JSON-RPC `tools/list` and `tools/call` but not the MCP `initialize` handshake, so `mcp-servers/bcc-research-proxy/index.mjs` answers the handshake locally and forwards tool calls. If BCC changes their endpoint, update `BCC_ENDPOINT` there and re-run `scripts/deploy.sh`.

**IEEE Xplore key approval is manual** (business hours, US Eastern). Until approved, the server is configured but every call returns an auth error. Leave `IEEE_API_KEY` blank in `.env` and the server is skipped.

**ClawHub rate-limits bursts.** `scripts/install-skills.sh` installs ClawHub skills sequentially with a short sleep. If one fails, re-run the script or install it by hand: `openclaw skills install <slug>`.

**GitHub-cloned skills need `_meta.json`** or `openclaw skills list` will not show them. The installer writes one for each pinned clone.

**`pubmed-edirect` shows "disabled".** It needs NCBI's EDirect binaries. Review its install script before running it, then enable with `openclaw config set skills.entries.pubmed-edirect.enabled true`.

**last30days keys.** It reads `~/.config/last30days/.env` if present, otherwise the process environment. OpenClaw exports the `env` block from openclaw.json to skill processes, so keys set via `scripts/configure.sh` reach it without a separate file.

**paper-search-mcp coverage.** Version 0.1.3 implements arXiv, PubMed, Google Scholar, bioRxiv, and medRxiv. The project's "20+ databases" claim is aspirational for that version.

**Restarting the gateway.** Avoid rapid repeated restarts. Discord rate-limits IDENTIFY and voice can break for 10 to 15 minutes.

**Removing the stack.** Delete the `mcp.servers.*` entries and `env.*` keys with `openclaw config patch` (`null` deletes a path), remove `~/.openclaw/skills/deep-research`, `~/.openclaw/mcp-servers/{bcc-research-proxy,ieee-mcp}`, the workspace skill directories listed in `config/skills.lock.json`, and the block between the `odd-bot-research:start/end` markers in TOOLS.md.