# `robot.install.md` — Install guide for AI agents

> You are reading this because you are an AI agent installing
> FrankenClaw for your user. This page assumes you know **nothing**
> about the AI host platforms FrankenClaw works with — Claude
> Desktop, Claude Code, OpenClaw, LM Studio, AnythingLLM, Agent Zero,
> Hermes Agent, Ollama, and the generic MCP hosts (Open WebUI,
> llama.cpp, LobeChat, Jan). Each gets a one-paragraph orientation
> below, then a config snippet you can drop into that host's MCP
> config.

Companion files:

- **[`robot.info`](./robot.info)** — structured JSON manifest of what
  FrankenClaw is and what tools it exposes. Read this first if you
  need to *describe* the product before installing it.
- **[`robot.install`](./robot.install)** — the JSON config manifest
  the installer reads. Edit values here, then run the script.
- **[`robot-install.sh`](./robot-install.sh)** — the non-interactive
  installer. Emits a single JSON object on stdout (including an
  `mcp_snippet` ready to paste into your host's config); exit `0`
  on success.
- **[`README.md`](./README.md)** — human-readable overview. Source
  of truth for the long-form story and the 14-tool table.

---

## 1. How FrankenClaw is different from Mnemo Cortex (and why install is simpler)

If you've installed [Mnemo Cortex](https://github.com/GuyMannDude/mnemo-cortex),
mentally remove half the steps. Mnemo runs a Python server on
`localhost:50001` and pairs it with a Node bridge per host. FrankenClaw
is **stdio-only**: the MCP host (Claude Desktop, OpenClaw, etc.)
spawns `server.py` directly. No daemon. No port. No systemd. No
Node bridge.

```
   ┌──────────────────────────┐                  ┌─────────────────┐
   │  Your user's AI host     │ ◀── stdio JSON ──│  server.py      │
   │  (e.g. Claude Desktop)   │     RPC          │  (Python, this  │
   │                          │                  │   repo)         │
   └──────────────────────────┘                  └─────────────────┘
   one config block in           14 FrankenTools registered from
   the host's MCP config         tools/*.py — each Python file
                                 contributes one or more tools
```

The trade-off: tool availability depends on which Python deps imported
cleanly at startup. NotebookLM tools need `notebooklm-py`, the browser
tool needs `agent-browser` (and Lightpanda), search needs a reachable
SearXNG instance. The installer's smoke test imports every
`tools/*.py` and reports `loaded` vs `failed` so you know what's
actually available without trial-and-error.

---

## 2. Install FrankenClaw

One step. The installer creates the venv, pip-installs requirements,
writes `~/.frankenclaw/config.json` + `~/.frankenclaw/keys.json`,
smoke-imports every tool module, and prints the MCP snippet for the
host on stdout.

```bash
./robot-install.sh
```

If the user has provider API keys to wire in, set the corresponding
env vars **before** running — the installer reads `OPENROUTER_API_KEY`,
`FIRECRAWL_API_KEY`, `SEARXNG_API_KEY` (the names listed in the
`provider_keys` block of [`robot.install`](./robot.install)) and
writes them into `~/.frankenclaw/keys.json` at `0600` permissions.
Never paste keys into the JSON manifest.

Success output:

```json
{
  "ok": true,
  "steps": {
    "deps":       {"ok": true, "python": "3.12"},
    "venv":       {"ok": true, "path": "..."},
    "pip":        {"ok": true},
    "config":     {"ok": true, "config_path": "...", "keys_path": "..."},
    "keys":       {"ok": true, "providers_written": ["openrouter"], "providers_missing": ["firecrawl"]},
    "smoke_test": {"ok": true, "loaded": [...], "failed": {}}
  },
  "mcp_snippet": {
    "command": "/path/to/.venv/bin/python",
    "args": ["/path/to/frankenclaw/server.py"]
  }
}
```

Failure: `{"ok": false, "error": "..."}`, exit code 1.

> **Heads-up for Windows users:** install FrankenClaw inside **WSL2**,
> not native Windows. `agent-browser` (the engine behind
> `browser_task`) ships native Linux/macOS binaries; the SSH-stdio
> shortcut some hosts try to use is buffered to uselessness on
> Windows. The other 13 tools work native-Windows in theory, but the
> verified path is WSL2.

---

## 3. Wire your user's AI host to spawn `server.py`

### 3a. If you don't know what host your user has

Ask. Or check these tells:

| Tell | Likely host |
|---|---|
| User typed `cc` or `claude` in a terminal | **Claude Code** |
| Desktop app, runs locally, no API key required | **Claude Desktop** (Anthropic-built) |
| User mentions "ClawdBot," "Rocky," or "Sparky" | **OpenClaw** |
| Desktop app with a model picker; user picked Qwen / Llama / Mistral | **LM Studio** (most common GUI for local models) |
| User has "workspaces"; can drag PDFs into chat | **AnythingLLM** |
| Docker container; user mentions "Bullwinkle" / "Agent Zero" | **Agent Zero** |
| User runs `hermes ...` in a terminal; mentions Nous Research | **Hermes Agent** |
| User runs `ollama run` or `ollama launch openclaw` | **Ollama** (via MCPHost or ollmcp) |
| User runs `llama-server` directly | **llama.cpp** |
| Browser-based, multi-model dashboard | **Open WebUI** |
| Chinese-friendly UI, MIT-licensed clone of ChatGPT | **LobeChat** |
| Cross-platform desktop, "AI playground" framing | **Jan** |

If none match, ask the user: *"What AI assistant or model host are
you using? I need the name so I can wire FrankenClaw in correctly."*

### 3b. Per-host config snippets

Every snippet below uses the same shape: a `mcpServers.frankenclaw`
entry that spawns `server.py` over stdio. Use the `mcp_snippet`
block from your `robot-install.sh` output to fill in absolute paths
— it already points at the venv's Python.

| Host | What it is | Config |
|---|---|---|
| **Claude Code** | Anthropic's terminal CLI agent — runs in your user's shell, reads/writes files, executes commands. | `claude mcp add frankenclaw -- /path/to/.venv/bin/python /path/to/frankenclaw/server.py` |
| **Claude Desktop** | Anthropic's desktop app. | Edit `claude_desktop_config.json` (location varies by OS — see Anthropic docs). Add an `mcpServers.frankenclaw` block with `command` + `args` from `mcp_snippet`. Restart Claude Desktop. |
| **OpenClaw** | Open-source local AI agent framework (the "ClawdBot" platform). | `openclaw mcp set frankenclaw '{"command":"/path/to/.venv/bin/python","args":["/path/to/frankenclaw/server.py"]}'` then `openclaw gateway restart` |
| **LM Studio** | Desktop GUI for running local LLMs (Qwen, Llama, etc.). Native MCP support since v0.3.17. | Edit `~/.lmstudio/mcp.json` (Linux/macOS) or `%USERPROFILE%\.lmstudio\mcp.json` (Windows). Add `mcpServers.frankenclaw`. Restart LM Studio. |
| **AnythingLLM** | Desktop GUI with workspace-scoped chat. | Edit `anythingllm_mcp_servers.json` (path varies — see [the AnythingLLM section in Mnemo's README](https://github.com/GuyMannDude/mnemo-cortex#anythingllm--desktop-gui-multi-workspace) for OS-specific locations). Then flip workspace to **Automatic** mode (Settings → Chat Settings → Automatic) so tools fire without `@agent` prefix. |
| **Agent Zero** | Autonomous Docker-based agent (the "Bullwinkle / BW" platform). | In-container MCP config. Use the `mcp_snippet` paths from *inside the container's* filesystem perspective, not the host's. |
| **Hermes Agent** | Nous Research's open-weights agent framework (v0.12.0+). | `hermes mcp add frankenclaw <command> <args...>` |
| **Ollama** (no native MCP) | Ollama Desktop's own chat does not support MCP. Use MCPHost or ollmcp as the bridge. | `~/.mcphost.yaml` → `mcpServers.frankenclaw.type: local`, `command: [".venv/bin/python", "server.py"]`. Pick a tool-capable model: `model: "ollama:qwen3:8b"`. |
| **llama.cpp** | Direct local inference. | `llama-server -m model.gguf --mcp-config /path/to/mcp.json` where `mcp.json` is shaped like LM Studio's. |
| **Open WebUI** | Browser-based multi-model dashboard. | Settings → Tools → MCP Servers → add a stdio server with the `mcp_snippet` command + args. |
| **LobeChat** | MIT-licensed chat UI. | Settings → Plugins → MCP → Add custom MCP server. Type `stdio`, command `python3 /ABSOLUTE/PATH/TO/frankenclaw/server.py`. |
| **Jan** | Cross-platform desktop AI playground. | Settings → Extensions → MCP Servers → Add with the `mcp_snippet` JSON shape. |

### 3c. Things to get right for every host

1. **Use the venv Python, not system Python.** The `mcp_snippet` from
   `robot-install.sh` points at `<install-dir>/.venv/bin/python`. If
   you swap to `python3`, the host launches FrankenClaw against the
   system Python which won't have the requirements installed — every
   tool import fails and the server registers zero tools.
2. **Absolute paths only.** Same trap as Mnemo: relative paths break
   silently because the host spawns the bridge from the wrong cwd.
3. **Use a tool-capable model.** Qwen3, Llama 3.2, Mistral, and
   Gemma 2 invoke tools correctly. Small models (under 7B) often
   *narrate* tool calls instead of making them. If you can't verify
   a tool actually ran, the model is faking it — scale up. Verified
   on AnythingLLM: `qwen3:8b` works, `llama3.1:8b` hallucinates.
4. **Coexists cleanly with Mnemo.** If your user has both, they
   register as separate `mcpServers` entries (`frankenclaw` and
   `mnemo-cortex`). They don't conflict and the agent gets both
   toolboxes simultaneously.

---

## 4. Verify which tools loaded

Run the smoke test (it's the last step of `robot-install.sh`, but
you can also run it standalone):

```bash
/path/to/.venv/bin/python server.py --smoke-test
```

You'll get a list of `loaded` modules and a `failed` map keyed by
module name with the import error. **A failed module is not a fatal
install error** — the other tools still register. Common failures:

| Module | Likely fix |
|---|---|
| `notebooklm` | `pip install notebooklm-py` in the venv, then re-run the smoke test. NotebookLM also needs Google session cookies — see `notebooklm-py` docs. |
| `browser` | Install `agent-browser` and ensure Lightpanda is at `/usr/local/bin/lightpanda` (override in `config.browser_executable`). |
| `search` | Set `config.searxng_url` in `robot.install` to a reachable SearXNG instance. Without it, every other tool still works — search is the only one disabled. |
| `gdrive` | Google OAuth credentials needed. See `tools/gdrive.py` for the auth flow. |
| `shopify` | Shop domain + admin API token needed in `keys.json`. |

After wiring the host: ask your user's AI to call any tool that
loaded cleanly (e.g. `vision_analyze` on a known image URL). If the
call round-trips, the host wiring works.

---

## 5. Provider keys → tool availability map

Tools degrade gracefully when keys are missing. Knowing what each
key unlocks lets you tell the user what's worth filling in:

| Key | Tools that need it |
|---|---|
| `OPENROUTER_API_KEY` | `vision_analyze` (Gemini via OpenRouter) |
| `FIRECRAWL_API_KEY` | `web_scrape` |
| `SEARXNG_API_KEY` *(if your SearXNG instance requires auth)* | `search_web` |
| Google OAuth tokens *(separate flow, not in `provider_keys`)* | `gdrive_search`, `gdrive_read` |
| Shopify admin token *(per-store, in `keys.json`)* | `shopify_*` (3 tools) |
| NotebookLM session cookies *(separate flow)* | `notebooklm_*` (5 tools) |

The minimum-useful install is `OPENROUTER_API_KEY` + a SearXNG URL
— that gets vision, search, and the browser/scraper tools wired with
one cloud account.

---

## 6. Related installs

- **Mnemo Cortex** — `https://github.com/GuyMannDude/mnemo-cortex`.
  Persistent memory for AI agents. The "memory" companion to
  FrankenClaw's "hands." Install order doesn't matter — they register
  as separate `mcpServers` entries and can be installed in either
  order. See Mnemo's
  [`robot.install.md`](https://github.com/GuyMannDude/mnemo-cortex/blob/master/robot.install.md)
  for the parallel guide.

- **Sparks Bus** — `https://github.com/GuyMannDude/sparks-bus`.
  Agent-to-agent messaging. Not required for FrankenClaw; install
  only if your user wants delivery-confirmed multi-agent
  communication.

---

## 7. Common pitfalls

| Symptom | Likely cause |
|---|---|
| Host shows zero FrankenTools registered | MCP config points at system `python3` instead of the venv Python. Use the exact `command` from `mcp_snippet`. |
| Some tools missing but most work | Optional deps not installed (NotebookLM, agent-browser) or keys absent. Check the smoke test's `failed` map. |
| `browser_task` fails on Windows | Native Windows isn't supported. Install inside WSL2. |
| `search_web` returns "SearXNG unreachable" | `config.searxng_url` empty or pointing at a dead instance. Set it to a reachable one, or accept that search is offline and let the other 13 tools work. |
| Agent claims it called a tool but nothing happened on the backend | Model is narrating tool calls without invoking them. Use a tool-capable model (qwen3:8b verified; llama3.1:8b fakes calls). |
| `vision_analyze` errors with `401 unauthorized` | `OPENROUTER_API_KEY` not in `~/.frankenclaw/keys.json` or rotated since install. Re-run the installer with the env var set, or hand-edit the keys file. |
| Install works on Mac, fails on Linux server | Headless server probably missing system libraries for `agent-browser` (it bundles a headless browser binary). Check the `agent-browser` install notes. |

---

## 8. When to bail and ask the user

This install is *for* your user, not *of* your user. If you hit any
of these, stop and ask:

- The user hasn't told you which AI host they run, and §3a's tells
  don't match.
- The user is on native Windows and you haven't confirmed they have
  WSL2 set up. Don't blindly install — the `browser_task` tool will
  fail at runtime.
- The user has Shopify or NotebookLM tools in scope, but you don't
  have the per-tool auth artifacts (Shopify admin token, Google
  session cookies). Don't fake or skip — ask.
- `robot-install.sh` reports `{"ok": false}` with an error you don't
  recognize. Paste the error to the user — don't guess.
- The smoke test reports `failed` modules the user explicitly needs.
  Some failures are fine (search without SearXNG); some aren't
  (NotebookLM tools when the user asked you to install for NotebookLM
  workflows). Ask before declaring the install successful.

When in doubt: install nothing destructive; surface the question.
