# odd-bot-research — agent setup instructions

You are installing the odd-bot-research deep research stack into a local OpenClaw installation.
Follow these steps in order. Every step is idempotent and safe to re-run.

## Preconditions (verify before starting)

- `openclaw --version` works and `~/.openclaw/openclaw.json` exists (OpenClaw onboarded).
- `node` 20+, `npm`, `git`, `python3`, and `pipx` are on PATH. If `pipx` is missing: `brew install pipx && pipx ensurepath` (macOS) or `python3 -m pip install --user pipx && python3 -m pipx ensurepath`.
- You know which API keys the user has. All are optional. Without any keys you still get: paper-search (arXiv/PubMed/Scholar), BCC Research, fetch, knowledge-graph-memory.

## Steps

1. Clone the repo.
   ```bash
   git clone https://github.com/oddessentials/odd-bot-research.git
   cd odd-bot-research
   ```
2. Create `.env` from the template and fill in the keys the user has. Leave unknown keys blank. Never commit `.env`.
   ```bash
   cp .env.example .env
   ```
3. Validate without changing anything. This prints the config patch with keys masked and runs OpenClaw's schema check.
   ```bash
   ./install.sh --dry-run
   ```
4. Install. This runs, in order: MCP server installs (npm/pipx/git, pinned), third-party skill installs (pinned), deploy of the `deep-research` skill and `bcc-research` proxy, a backed-up config patch, a TOOLS.md append, and a doctor check.
   ```bash
   ./install.sh
   ```
5. Restart the gateway so it picks up `mcp.servers`. Do not restart repeatedly; Discord rate-limits reconnects.
   ```bash
   openclaw gateway restart
   ```
6. Verify. Expect `deep-research` to be absent from `openclaw skills list` as a workspace skill (it is a managed skill under `~/.openclaw/skills/`, routed from TOOLS.md) and the MCP servers to appear under `mcp.servers`.
   ```bash
   ./scripts/doctor.sh
   openclaw config get mcp.servers
   ```
7. Smoke test by asking the agent: `research "What changed in MCP transports in 2026?"`. The first call to each MCP server is slow because servers lazy-load on first use.

## If doctor reports a failure

- `X registers as 'deep-research' and shadows the orchestrator`: a workspace skill (usually `agent-deep-research` from ClawHub) uses the same name. Remove it: `rm -rf ~/.openclaw/workspace/skills/agent-deep-research`, then restart the gateway.
- `paper-search-mcp not installed` or `mcp-server-fetch not installed`: run `./scripts/install-mcp-servers.sh` and check `pipx list`.
- `bcc-research-proxy not deployed` or `deep-research not deployed`: run `./scripts/deploy.sh`.
- Keys unset: edit `.env`, re-run `./scripts/configure.sh`, restart the gateway.

## What NOT to do

- Do not edit `~/.openclaw/openclaw.json` by hand for these entries; `scripts/configure.sh` writes one validated patch and keeps a backup.
- Do not use a flat `mcpServers` key. OpenClaw uses nested `mcp.servers`.
- Do not install `agent-deep-research`, `crawl4ai-rag`, or `semantic-scholar-mcp` (name collision, CVE-2026-26216, abandoned, respectively).
- Do not put keys anywhere in the repo.

## Files you may need to read

- `README.md` — overview and tool matrix
- `config/mcp-servers.template.json` — exactly what gets written under `mcp.servers`
- `config/skills.lock.json` — pinned third-party skill and server versions
- `skills/deep-research/SKILL.md` — the orchestrator the agent follows
- `docs/troubleshooting.md` — known gotchas