<p>The <a href="/bot-wiki.html">bot-wiki post</a> introduced a structured wiki
designed for machine consumption. The whole point was to build
something a RAG pipeline could actually use. This is that pipeline.</p>
<h2 id="the-stack">The stack</h2>
<p>The wiki has 21 markdown pages with structured frontmatter:
title, summary, keywords, scope. The RAG pipeline is a single
Python script that:</p>
<ol>
<li>Embeds all 21 pages into vectors using OpenRouter's API</li>
<li>Stores them in a FAISS flat index (129 KB, committed to git)</li>
<li>At query time, embeds the question, finds the nearest pages,
and feeds them to an LLM for a grounded answer</li>
</ol>
<p>Dependencies: <code>faiss-cpu</code>, <code>openai</code> (for the OpenAI-compatible
API), and <code>pyyaml</code>. That's it.</p>
<h2 id="why-faiss">Why FAISS</h2>
<p><a href="https://github.com/facebookresearch/faiss">FAISS</a> is Meta's
library for similarity search over dense vectors. It runs
in-process, no server needed. You give it vectors, it gives
you nearest neighbors. The index is a flat file you can
commit to git.</p>
<p>I picked it because this is 21 vectors. There's no need for
a database, a server, or a managed service. <code>pip install faiss-cpu</code>, build an index, save it, done. The index is
129 KB. It loads in milliseconds.</p>
<p>If you're working at larger scale or want more features,
the main alternatives are:</p>
<ul>
<li><a href="https://github.com/chroma-core/chroma">Chroma</a>: embedded
vector database with a nice Python API. Good if you want
metadata filtering or persistence without managing files
yourself. Still runs locally.</li>
<li><a href="https://github.com/qdrant/qdrant">Qdrant</a>: vector search
engine written in Rust. Runs as a server, supports
filtering and payloads. Better fit when you have millions
of vectors or need a proper API.</li>
<li><a href="https://www.pinecone.io/">Pinecone</a>: fully managed cloud
vector database. Zero ops, but you're paying per query and
your data lives on someone else's servers.</li>
</ul>
<p>If you're already running PostgreSQL,
<a href="https://github.com/pgvector/pgvector">pgvector</a> is worth
a look. It adds vector columns and similarity search to
your existing database. No new service to run, and your
vectors live next to your relational data.</p>
<p>For 21 pages committed to a git repo, FAISS is the obvious
choice. No dependencies beyond the pip package, no running
services, no accounts.</p>
<h2 id="why-whole-page-chunks">Why whole-page chunks</h2>
<p>The wiki pages are short, 18 to 65 lines each. Splitting them
by section would lose context without gaining anything. The
frontmatter was designed to enrich embeddings, so each chunk
looks like this:</p>
<pre><code>Title: Claude Code
Summary: Anthropic's CLI-based AI coding assistant. Runs
  in terminal, edits files directly, supports MCP tool
  integrations and custom hooks.
Keywords: claude-code, anthropic, cli, ai-coding-assistant,
  mcp, hooks
Scope: Covers Claude Code setup, configuration, MCP
  integration, hooks, and usage patterns.

Claude Code is Anthropic's CLI tool for AI-assisted software
engineering. It operates directly in the terminal...
</code></pre>
<p>Prepending the summary, keywords, and scope to the body gives
the embedding model more signal about what the page covers.
21 chunks, 5,434 tokens total.</p>
<h3 id="chunking-in-general">Chunking in general</h3>
<p>Most RAG guides recommend chunks of 256 to 512 tokens. That's
a reasonable default for long documents where you want to
retrieve a specific paragraph, not the whole thing. Smaller
chunks give more precise retrieval. Larger chunks give the
LLM more context per result.</p>
<p>The tradeoffs:</p>
<ul>
<li><strong>Too small</strong> (under 100 tokens): chunks lose meaning on
their own. "See above" or "as mentioned" with no referent.
Retrieval finds fragments, not answers.</li>
<li><strong>Too large</strong> (over 1000 tokens): embeddings become diluted.
A chunk about five topics matches all five weakly instead
of one strongly. You also burn more of the LLM's context
window per retrieved result.</li>
<li><strong>Overlap</strong> helps when chunks split mid-thought. A common
pattern is 512-token chunks with 50-100 tokens of overlap.
This adds redundancy but reduces the chance of cutting a
relevant passage in half.</li>
</ul>
<p>The wiki pages average about 260 tokens each, which lands
right in the sweet spot. They're also self-contained by
design, each page covers one topic with clear boundaries.
No reason to split them further.</p>
<p>If I were indexing longer documents (blog posts, docs, book
chapters), I'd split by section headers first, then by token
count within sections. Semantic boundaries beat arbitrary
ones.</p>
<h2 id="building-the-index">Building the index</h2>
<pre><code class="language-bash">python3 -m venv .venv
.venv/bin/pip install -r bin/requirements-rag.txt
.venv/bin/python bin/wiki-rag.py build
</code></pre>
<pre><code>Embedding 21 wiki pages...
Indexed 21 pages, 1536 dimensions, 5434 tokens
Index: 129,069 bytes, metadata: 29,663 bytes
Saved to blog/markdown/wiki/.index
</code></pre>
<p>The embedding model is <code>text-embedding-3-small</code> via OpenRouter.
1536 dimensions per vector. The FAISS index uses <code>IndexFlatIP</code>
(inner product on normalized vectors = cosine similarity). No
approximate search needed at this scale.</p>
<p>The index and a <code>metadata.json</code> file (slug, title, summary,
full chunk text for each page) get saved to
<code>blog/markdown/wiki/.index/</code>. Both files are committed to git.
Any tool that wants to query the wiki can just read the index
directly without needing the embedding API.</p>
<p>The build is a manual step, not part of <code>npm run build</code>. Wiki
content doesn't change often, and there's no reason to pay for
embeddings on every deploy.</p>
<h2 id="querying">Querying</h2>
<p>A query hits two models. First, the question gets embedded
into a vector using the same embedding model that indexed
the wiki pages. FAISS compares that vector against the 21
stored vectors and returns the closest matches. Those
matches are wiki pages that are semantically similar to the
question, not keyword matches, but meaning matches.</p>
<p>Then the retrieved pages get passed to an LLM (Claude
Sonnet) as context, along with the original question. The
LLM reads the pages and writes an answer grounded in what
they actually say. Without the retrieval step, the LLM
would just guess from its training data. With it, the LLM
answers from your specific documents.</p>
<p>That's the "retrieval-augmented" part of RAG: find relevant
documents first, then generate an answer from them.</p>
<pre class="mermaid">
graph LR
    Q[Question] --> E[Embed question]
    E --> F[FAISS search]
    F --> R[Top 3 wiki pages]
    R --> P[Build prompt]
    P --> LLM[Claude Sonnet]
    LLM --> A[Answer + sources]
</pre>
<pre><code class="language-bash">.venv/bin/python bin/wiki-rag.py query \
  "What MCP servers does this project use?"
</code></pre>
<pre><code>Question: What MCP servers does this project use?

Top 3 matches:
  1. [0.644] MCP Integrations (wiki/mcp)
  2. [0.563] Linear MCP (wiki/mcp/linear)
  3. [0.524] GA4 MCP (wiki/mcp/ga4)

Answer:
Based on the provided context, this project uses three MCP
servers:

1. Playwright, for browser automation
2. Linear, for project management
3. GA4, for accessing website traffic data and reports

All MCP servers run as subprocesses communicating via JSON-RPC
over stdio, and are configured in ~/.claude.json or a
project-level .claude.json file.
</code></pre>
<p>The retrieval nailed the right pages. Here's a different query:</p>
<pre><code class="language-bash">.venv/bin/python bin/wiki-rag.py query "How do I run security scans?"
</code></pre>
<pre><code>Question: How do I run security scans?

Top 3 matches:
  1. [0.484] Security Toolkit (wiki/devops/security-toolkit)
  2. [0.439] DevOps &#x26; Security (wiki/devops)
  3. [0.343] OpenClaw Kubernetes Security (wiki/openclaw/kubernetes)
</code></pre>
<p>The answer included the actual docker commands from the security
toolkit wiki page, copy-paste ready. The third result
(Kubernetes security) is a reasonable stretch, the word
"security" overlaps, but the top two are exactly right.</p>
<h2 id="the-script">The script</h2>
<p>The interesting parts are small. Embedding is a single API call
since all 21 pages fit in one batch:</p>
<pre><code class="language-python">client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)
response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=texts,
)
</code></pre>
<p>OpenRouter's embedding endpoint is OpenAI-compatible, so the
<code>openai</code> Python package works with just a base URL swap.</p>
<p>FAISS search returns similarity scores and indices:</p>
<pre><code class="language-python">scores, indices = index.search(query_vec, k)
for score, idx in zip(scores[0], indices[0]):
    page = metadata[idx]
    # score is cosine similarity (0 to 1)
</code></pre>
<p>The retrieved pages get stuffed into a prompt with instructions
to only use the provided context and cite sources. The LLM
(Claude Sonnet via OpenRouter) generates the answer.</p>
<h2 id="cost">Cost</h2>
<p>Indexing 21 pages used 5,434 tokens at
<code>text-embedding-3-small</code> rates ($0.02/1M tokens). That's
$0.0001. Each query embeds a short question (maybe 20 tokens)
plus one chat completion. A query costs roughly $0.002 to
$0.01 depending on the response length.</p>
<p>Building the index and running test queries cost $0.03
total on OpenRouter. That covers the embedding API calls
and the chat completions for query-mode answers. The
development itself (writing the script, iterating on the
blog post) ran through Claude Code on an Anthropic Max
subscription, so that cost isn't on the OpenRouter bill.</p>


<h2 id="table-of-contents">Table of contents</h2>
<ul>
<li><a href="#why-one-router">Why one router</a>
<ul>
<li><a href="#claudes-token-efficiencies">Claude's token efficiencies</a></li>
</ul>
</li>
<li><a href="#getting-an-openrouter-key">Getting an OpenRouter key</a></li>
<li><a href="#claude-code">Claude Code</a></li>
<li><a href="#opencode">OpenCode</a>
<ul>
<li><a href="#what-didnt-work">What didn't work</a></li>
<li><a href="#what-worked">What worked</a></li>
</ul>
</li>
<li><a href="#openclaw">OpenClaw</a></li>
<li><a href="#custom-openrouter-usage-mcp">Custom OpenRouter Usage MCP</a>
<ul>
<li><a href="#registering-it">Registering it</a></li>
<li><a href="#usage-output">Usage output</a></li>
<li><a href="#model-pricing-snapshot">Model pricing snapshot</a></li>
</ul>
</li>
</ul>
<h1 id="why-one-router">Why one router</h1>
<p>I run three AI tools regularly: Claude Code, OpenCode,
and OpenClaw. Each has its own API key, its own billing
dashboard, and its own model config. Anthropic bills
Claude Code. Google bills OpenClaw's Gemini usage.
OpenCode can talk to either.</p>
<p>That's three places to check spend, three sets of rate
limits, and no single view of what I'm burning through.
OpenRouter fixes this. It's a proxy that sits between
your tools and the model providers. You get one API key,
one billing dashboard, and the ability to swap models
without changing provider credentials.</p>
<p>The tradeoff is a small markup on token costs and an
extra network hop. For a personal setup where I want
visibility and flexibility, that's fine.</p>
<h2 id="claudes-token-efficiencies">Claude's token efficiencies</h2>
<p>Anthropic's Pro and Max plans include Claude Code
usage at a steep discount compared to raw API pricing.
Pro is $20/month with generous token allowances. Max
plans scale up from there. If you only use Claude Code,
the Pro plan is the cheapest way to run it.</p>
<p>The problem is that those plan tokens only work with
Claude Code through Anthropic's direct API. OpenCode
and OpenClaw are third-party tools. They can call
Claude models, but not through your Pro subscription.
They hit the standard API and bill at full rate.</p>
<p>So the choice is: keep Claude Code on the Pro plan
(cheapest for that one tool) and manage the other two
separately, or route everything through OpenRouter and
get unified billing at API rates. I went with
OpenRouter because the visibility across all three
tools matters more to me than the per-token savings
on Claude Code alone.</p>
<h1 id="getting-an-openrouter-key">Getting an OpenRouter key</h1>
<ol>
<li>Sign up at <a href="https://openrouter.ai">openrouter.ai</a></li>
<li>Go to Settings > Keys and create a new API key</li>
<li>Add credits (pay-as-you-go, no minimum)</li>
</ol>
<p>OpenRouter gave me $100 in free credits as a signup
promo. That's a lot of tokens to experiment with before
committing any money.</p>
<p>Set the key in your shell:</p>
<pre><code class="language-bash">export OPENROUTER_API_KEY="sk-or-v1-..."
</code></pre>
<p>Add it to your <code>~/.zshrc</code> or <code>~/.bashrc</code> so it persists.
The same key works for every tool below.</p>
<p>OpenRouter's <a href="https://openrouter.ai/models">models page</a>
shows per-token pricing for every model. Useful for
comparing costs before swapping models around.</p>
<h1 id="claude-code">Claude Code</h1>
<p>Claude Code normally talks directly to Anthropic's API.
To route it through OpenRouter, you override the base
URL and auth token via environment variables:</p>
<pre><code class="language-bash">ANTHROPIC_BASE_URL="https://openrouter.ai/api" \
ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY" \
ANTHROPIC_API_KEY="" \
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
claude
</code></pre>
<p>Four variables. <code>ANTHROPIC_BASE_URL</code> points Claude Code
at OpenRouter instead of Anthropic. <code>ANTHROPIC_AUTH_TOKEN</code>
passes your OpenRouter key. <code>ANTHROPIC_API_KEY</code> must be
set to an empty string, otherwise Claude Code tries to
use it and the auth conflicts.
<code>CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC</code> stops
telemetry calls that would fail against OpenRouter.</p>
<p>That's verbose to type every time. I wrapped it in a
shell function:</p>
<pre><code class="language-bash"># ~/.zshrc
orclaude() {
  ANTHROPIC_BASE_URL="https://openrouter.ai/api" \
  ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY" \
  ANTHROPIC_API_KEY="" \
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
  claude "$@"
}
</code></pre>
<p>Now <code>orclaude</code> launches Claude Code through OpenRouter.
Regular <code>claude</code> still uses the Anthropic API directly.</p>
<p>You can also swap models. Claude Code has three model
slots (Opus, Sonnet, Haiku) that you can override:</p>
<pre><code class="language-bash">export ANTHROPIC_DEFAULT_SONNET_MODEL=\
  "google/gemini-2.5-pro"
export ANTHROPIC_DEFAULT_HAIKU_MODEL=\
  "google/gemini-2.5-flash"
</code></pre>
<p>Any model on OpenRouter that supports tool use works.
Models without tool use will break Claude Code since
it relies on tools for file reading, editing, and
command execution.</p>
<h1 id="opencode">OpenCode</h1>
<p>OpenCode has native OpenRouter support.</p>
<h2 id="what-didnt-work">What didn't work</h2>
<p>I tried putting the API key in <code>opencode.json</code>. It passed config validation but
OpenCode still tried to bill through its own payment system. "No payment method" error
pointing at OpenCode's billing page, not OpenRouter's.</p>
<h2 id="what-worked">What worked</h2>
<p>OpenCode picks up <code>OPENROUTER_API_KEY</code> from the environment automatically. The config
file only needs the model names. <code>opencode.json</code> goes in the project root where you
launch it, or the global <code>~/.config/opencode/opencode.json</code>.</p>
<pre><code class="language-json">{
  "model": "openrouter/anthropic/claude-sonnet-4-6",
  "small_model": "openrouter/anthropic/claude-haiku-4-5"
}
</code></pre>
<p>The key has to be registered through OpenCode's auth system. Inside the TUI:</p>
<ol>
<li>Run <code>/connect</code></li>
<li>Search for "OpenRouter"</li>
<li>Paste your API key</li>
</ol>
<p>After that, OpenCode routes through OpenRouter. The
<code>openrouter/</code> prefix on model names tells it which
provider to use.</p>
<p>Note: OpenCode shows a warning when you select
OpenRouter saying requests "will often be routed to
subpar providers." That feels like they're trying to just sell their own model hosting.</p>
<h1 id="openclaw">OpenClaw</h1>
<p>OpenClaw has native OpenRouter support. The model
reference format is <code>openrouter/&#x3C;provider>/&#x3C;model></code>,
same as OpenCode.</p>
<p>In OpenClaw's home directory, <code>openclaw.json</code>, for the K8s setup
<code>/home/node/.openclaw/openclaw.json</code> (the PVC mount). For a local install it'd be
<code>~/.openclaw/openclaw.json.</code>:</p>
<pre><code class="language-json5">{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      model: {
        primary: "openrouter/anthropic/claude-sonnet-4-6"
      },
    },
  },
}
</code></pre>
<p>Or use the CLI:</p>
<pre><code class="language-bash">openclaw onboard \
  --auth-choice apiKey \
  --token-provider openrouter \
  --token "$OPENROUTER_API_KEY"
</code></pre>
<p>Since my OpenClaw runs in K8s with secrets injected via
Vault, I added <code>OPENROUTER_API_KEY</code> to the Vault secret
and updated the Vault Agent template to export it. Same
pattern as the
<a href="/openclaw-linear-skill.html">Linear API key</a> from the
previous post.</p>
<p>After redeploying, I cleared my OpenClaw agent's sessions (OpenClaw
caches the model config per session) and asked what
model it was running:</p>
<pre><code class="language-text">Claude: What model are you running on?
Pai: I'm running on Claude Sonnet 4.6 via OpenRouter
  (openrouter/anthropic/claude-sonnet-4-6).
</code></pre>
<p>Previously Pai ran Gemini 2.5 Flash through Google's
API directly. Now it's Claude Sonnet 4.6 through
OpenRouter. Same Vault-injected credentials pattern,
different model, one billing dashboard.</p>
<p>The Linear skill still works through the new model.
Pai listed my teams and issues the same as before.
The skill's curl commands don't care which model is
driving the agent.</p>
<h1 id="custom-openrouter-usage-mcp">Custom OpenRouter Usage MCP</h1>
<p>With everything routed through OpenRouter, I wanted
to check my spend without leaving the terminal. OpenRouter
has a billing API, so I built a small
<a href="https://github.com/kylep/multi/tree/main/apps/mcp-servers/openrouter">MCP server</a>
that queries it.</p>
<p>The server has two tools. <code>get_usage</code> calls the
<code>/api/v1/key</code> endpoint and returns daily, weekly, monthly,
and total spend plus remaining credits. <code>get_model_pricing</code>
calls <code>/api/v1/models</code> and shows per-million-token costs,
with an optional filter to search by model name.</p>
<p>The whole thing is one TypeScript file using the MCP SDK
with stdio transport. It reads <code>OPENROUTER_API_KEY</code> from
the environment, same key the other tools already use.</p>
<h2 id="registering-it">Registering it</h2>
<p>In <code>~/.claude.json</code>, under the project's <code>mcpServers</code>:</p>
<pre><code class="language-json">"openrouter": {
  "type": "stdio",
  "command": "node",
  "args": [
    "/path/to/openrouter-mcp/build/index.js"
  ]
}
</code></pre>
<p>No <code>env</code> block needed. Claude Code spawns it as a child
process, which inherits the shell environment.</p>
<h2 id="usage-output">Usage output</h2>
<p>After restarting Claude Code, I asked it to check my
OpenRouter usage:</p>
<pre><code class="language-text">Key: sk-or-v1-3fd...374
Free tier: no

Usage:
  Today:  $0.5467
  Week:   $0.5467
  Month:  $0.5467
  Total:  $0.5467

Credit limit:
  Limit:     $200.0000
  Remaining: $199.4533
</code></pre>
<p>That $0.55 is from a few hours of Claude Code and
OpenCode use. The $200 limit is what I set on the key
in OpenRouter's dashboard.</p>
<p>The pricing tool is useful for comparing models before
switching. Searching "claude-sonnet-4" shows all the
Sonnet variants and their per-million-token rates side
by side.</p>
<h2 id="model-pricing-snapshot">Model pricing snapshot</h2>
<p>Pulled from <code>get_model_pricing</code> on 2026-03-10:</p>
<table>
<thead>
<tr>
<th>Model</th>
<th>Prompt</th>
<th>Completion</th>
<th>Context</th>
</tr>
</thead>
<tbody>
<tr>
<td>openai/gpt-5.4-pro</td>
<td>$30.00/M</td>
<td>$180.00/M</td>
<td>1050k</td>
</tr>
<tr>
<td>openai/gpt-5.4</td>
<td>$2.50/M</td>
<td>$15.00/M</td>
<td>1050k</td>
</tr>
<tr>
<td>openai/gpt-5.3-codex</td>
<td>$1.75/M</td>
<td>$14.00/M</td>
<td>400k</td>
</tr>
<tr>
<td>openai/gpt-5.2-pro</td>
<td>$21.00/M</td>
<td>$168.00/M</td>
<td>400k</td>
</tr>
<tr>
<td>openai/gpt-5.1</td>
<td>$1.25/M</td>
<td>$10.00/M</td>
<td>400k</td>
</tr>
<tr>
<td>anthropic/claude-opus-4.6</td>
<td>$5.00/M</td>
<td>$25.00/M</td>
<td>1000k</td>
</tr>
<tr>
<td>anthropic/claude-sonnet-4.6</td>
<td>$3.00/M</td>
<td>$15.00/M</td>
<td>1000k</td>
</tr>
<tr>
<td>anthropic/claude-haiku-4.5</td>
<td>$1.00/M</td>
<td>$5.00/M</td>
<td>200k</td>
</tr>
<tr>
<td>anthropic/claude-opus-4</td>
<td>$15.00/M</td>
<td>$75.00/M</td>
<td>200k</td>
</tr>
<tr>
<td>anthropic/claude-sonnet-4</td>
<td>$3.00/M</td>
<td>$15.00/M</td>
<td>200k</td>
</tr>
<tr>
<td>google/gemini-3.1-pro-preview</td>
<td>$2.00/M</td>
<td>$12.00/M</td>
<td>1049k</td>
</tr>
<tr>
<td>google/gemini-2.5-pro</td>
<td>$1.25/M</td>
<td>$10.00/M</td>
<td>1049k</td>
</tr>
<tr>
<td>google/gemini-2.5-flash</td>
<td>$0.30/M</td>
<td>$2.50/M</td>
<td>1049k</td>
</tr>
<tr>
<td>google/gemini-2.5-flash-lite</td>
<td>$0.10/M</td>
<td>$0.40/M</td>
<td>1049k</td>
</tr>
<tr>
<td>deepseek/deepseek-v3.2</td>
<td>$0.25/M</td>
<td>$0.40/M</td>
<td>164k</td>
</tr>
<tr>
<td>deepseek/deepseek-r1-0528</td>
<td>$0.45/M</td>
<td>$2.15/M</td>
<td>164k</td>
</tr>
<tr>
<td>meta-llama/llama-4-maverick</td>
<td>$0.15/M</td>
<td>$0.60/M</td>
<td>1049k</td>
</tr>
<tr>
<td>mistralai/mistral-large-2512</td>
<td>$0.50/M</td>
<td>$1.50/M</td>
<td>262k</td>
</tr>
<tr>
<td>qwen/qwen3.5-397b-a17b</td>
<td>$0.39/M</td>
<td>$2.34/M</td>
<td>262k</td>
</tr>
<tr>
<td>qwen/qwen3-coder-plus</td>
<td>$0.65/M</td>
<td>$3.25/M</td>
<td>1000k</td>
</tr>
</tbody>
</table>
<p>Prices are per million tokens. These change often.
Check OpenRouter's models page for current rates.</p>


Kyle Pericak

"It works in my environment"

Categories

Tags