Configuration & Keys

The KB splits its configuration into two parts:

Credentials — the embedding and OCR/vision API keys — live in the [knowledge] section of config.toml, encrypted at rest like api_key. This section landed in v0.7.0; before that, KB keys were environment-variable-only.
Tuning knobs — everything else (embedding model, retrieval toggles, extraction routing, sidecar URLs) — is environment-driven. There is no [kb] TOML section today; the runtime reads KB_* env vars directly (KbConfig::from_env in src/kb/config.rs).

The `[knowledge]` config section

Defined as KnowledgeConfig in src/config/schema.rs:


[knowledge]
embedding_api_key = "sk-..."
vision_api_key = "sk-..."   # optional; omit to reuse the embedding key for OCR

Key	Default	Purpose
`embedding_api_key`	unset	Bearer for KB document embedding (search + ingest).
`vision_api_key`	unset	Bearer for OCR/vision extraction of PDFs and images; falls back to `embedding_api_key` when unset.

Both keys are stored encrypted (as enc2:<hex>) when secrets.encrypt = true, exactly like the top-level api_key. The section is not feature-gated — KnowledgeConfig is always present so the config shape stays stable across feature sets. Adding it was an additive schema change: the config CURRENT_VERSION went 9 → 10 (verified in src/config/migrations.rs), and the v9 → v10 migration injects nothing — serde defaults the section, so an existing config migrates cleanly with no [knowledge] table written.

Three ways to set the keys

1. The `setup knowledge` wizard section


rantaiclaw setup knowledge

The section (src/onboard/section/knowledge.rs) confirms enablement, then resolves an embedding key — if your main provider is OpenRouter it can reuse the main provider key, otherwise you enter a key or skip — and optionally an OCR/vision key (reuse the embedding key, enter a different one, or skip OCR). Skipping the embedding key leaves the KB disabled. The section never persists on its own; the wizard’s final config.save() encrypts and writes once at the end.

2. The first-run wizard’s Integrations step

Bare rantaiclaw setup (and rantaiclaw onboard) offer the same Knowledge Base section as part of the interactive first-run flow, so you can configure the KB without knowing the standalone subcommand exists.

3. The gateway config API

For the management console (key values are never returned):


GET /api/v1/config/knowledge
PUT /api/v1/config/knowledge      # body: { embedding_api_key?, vision_api_key? }

Both routes are only mounted when the kb feature is built (src/gateway/config_api.rs). The responses are presence-only — the raw key is never serialized back:

GET returns { embedding_configured, vision_configured, source }, where source is "env", "config", or "none" depending on where the key resolves from.
PUT sets the keys (persisted encrypted); an omitted field leaves the existing value untouched, and an empty string clears it. Applying a change flushes the cached KB context and reloads the managed daemon so the new credentials take effect.

GET /api/v1/config also redacts both [knowledge] keys from its response, alongside the provider key and channel tokens.

Key precedence

The KB keys follow the same precedence model as the top-level api_key: environment overrides config at load, env wins. During config load, KB_EMBEDDING_API_KEY folds onto config.knowledge.embedding_api_key and KB_EXTRACT_VISION_API_KEY folds onto config.knowledge.vision_api_key (env wins). Downstream code reads only the resolved config.knowledge values, which the gateway then hands to KbConfig::from_env_with_keys. Finally, any per-endpoint key that is still empty falls back to OPENROUTER_API_KEY (KbConfig::resolve_key in src/kb/config.rs).

So the resolution order for each key is:


KB_* env var  >  [knowledge] config value  >  OPENROUTER_API_KEY

The `kb_not_configured` error

Without a usable embedding key, the KB fails with an actionable message rather than a raw provider auth failure downstream. When KbConfig::resolve_key yields an empty embedding key, the context build returns (verified in src/kb/axi/api.rs):


kb_not_configured: no embedding API key. Add one via `rantaiclaw setup knowledge` or set KB_EMBEDDING_API_KEY.

Over HTTP this surfaces as a 503 Service Unavailable with error: "kb_not_configured"; the cached failure persists until you fix the key and the gateway rebuilds its context (a PUT /api/v1/config/knowledge flushes the cache, or restart the daemon).

Storage path

The kb.db SQLite file path resolves in this order (resolve_kb_db_path in src/kb/axi/cli.rs):

Order	Location
1	`KB_DB_PATH` env var, when non-empty.
2	Platform data dir via `directories::ProjectDirs` — `~/.local/share/rantaiclaw/kb.db` on Linux, `~/Library/Application Support/rantaiclaw/kb.db` on macOS.
3	`./kb.db` in the current working directory — final fallback when HOME is unavailable (containers, embedded systems).

KB_* runtime env vars

The non-credential tuning knobs, all read by KbConfig::from_env (src/kb/config.rs). These are env-only, so changing them never affects the config schema fingerprint.

Storage & embedding

Env var	Default	Purpose
`KB_DB_PATH`	platform data dir	SQLite database path (see above).
`KB_EMBEDDING_MODEL`	`qwen/qwen3-embedding-8b`	Embedding model ID.
`KB_EMBEDDING_DIM`	`4096`	Vector dimension; must match the chosen model.
`KB_EMBEDDING_BASE_URL`	`https://openrouter.ai/api/v1/embeddings`	Embedding endpoint; point at a TEI sidecar for on-prem use.
`KB_EMBEDDING_API_KEY`	unset	Bearer for the embedding endpoint; falls back to `OPENROUTER_API_KEY`.
`KB_EMBED_BATCH_SIZE`	`128`	Batch size for embedding requests.
`KB_EMBED_CONCURRENCY`	`4`	Concurrent embedding requests in flight.
`KB_QUERY_EMBED_CACHE_SIZE`	`256`	LRU size for cached query embeddings.
`KB_QUERY_EMBED_CACHE_TTL_MS`	`300000`	TTL for cached query embeddings (5 minutes).

Retrieval

Env var	Default	Purpose
`KB_DEFAULT_MAX_CHUNKS`	`8`	Default `top_k` when a caller doesn’t specify.
`KB_HYBRID_BM25_ENABLED`	`true`	Fuse vector + BM25 via RRF. Disabled only when the value is exactly `"false"`.
`KB_QUERY_EXPANSION_ENABLED`	`false`	LLM-generated paraphrases of the query before retrieval.
`KB_QUERY_EXPANSION_MODEL`	`openai/gpt-4.1-nano`	Model used for paraphrase generation.
`KB_QUERY_EXPANSION_PARAPHRASES`	`3`	Number of paraphrases per query.
`KB_STANDALONE_QUERY_ENABLED`	`false`	Rewrite multi-turn queries to be self-contained before retrieval.
`KB_CONTEXTUAL_RETRIEVAL_ENABLED`	`false`	Anthropic-style contextual prefix prepended to each chunk during ingest.
`KB_CONTEXTUAL_RETRIEVAL_MODEL`	`openai/gpt-4.1-nano`	Model used for contextual prefix generation.

Reranker

Opt-in second-stage ranker over the top-KB_RERANK_INITIAL_K candidates.

Env var	Default	Purpose
`KB_RERANK_ENABLED`	`false`	Enable the reranker stage. Enabled only on the exact string `"true"`.
`KB_RERANK_PROVIDER`	unset	Reranker backend: `openrouter` (LLM), `cohere`, or `vllm`.
`KB_RERANK_MODEL`	`openai/gpt-4.1-nano`	Reranker model ID.
`KB_RERANK_INITIAL_K`	`20`	Candidates pulled from first-stage retrieval.
`KB_RERANK_FINAL_K`	`5`	Top-k returned after reranking.

Extraction (primary + sidecars)

Env var	Default	Purpose
`KB_EXTRACT_PRIMARY`	`smart`	PDF strategy: `smart` (text-layer first, vision fallback), `unpdf`, `vision`, `mineru`.
`KB_EXTRACT_FALLBACK`	`unpdf`	Fallback strategy when the primary fails.
`KB_EXTRACT_SMART_FALLBACK`	`openai/gpt-4.1-nano`	Vision model used when the smart router decides a PDF needs OCR.
`KB_EXTRACT_VISION_BASE_URL`	`https://openrouter.ai/api/v1/chat/completions`	Vision LLM endpoint (TEI/vLLM-style sidecar override).
`KB_EXTRACT_VISION_API_KEY`	unset	Bearer for the vision endpoint; folds onto `[knowledge].vision_api_key`, then falls back to `OPENROUTER_API_KEY`.
`KB_EXTRACT_MINERU_BASE_URL`	unset	MinerU sidecar base URL (required when `KB_EXTRACT_PRIMARY=mineru`).

Shared endpoint

Env var	Default	Purpose
`KB_OPENROUTER_CHAT_URL`	`https://openrouter.ai/api/v1/chat/completions`	Chat-completions endpoint shared by query expansion, contextual retrieval, standalone-query rewriting, and Document Intelligence extraction.
`OPENROUTER_API_KEY`	unset	Final fallback bearer for any KB endpoint whose per-endpoint key is empty.

For the Document Intelligence knobs (KB_INTELLIGENCE_*, KB_GRAPH_MAX_NODES, KB_GRAPHRAG_*), see Document Intelligence & GraphRAG.

Parsing notes. KB_RERANK_ENABLED parses exactly "true" as enabled — any other value (including "1", "yes", "on") is off. KB_HYBRID_BM25_ENABLED is the inverse: off only when the value is exactly "false". Numeric vars that fail to parse surface a KbError::Config at startup with the offending value — fail-fast, no silent fallback to a default.