Configuration

v1 status: placeholder list of sections, hand-written from pub struct Config in src/config/schema.rs. The page should eventually be generated from cargo run -- config schema --json (the schema is produced by schemars derive on the config struct). The canonical reference in the upstream repo is docs/config-reference.md.

File locations

Per-profile (under ~/.rantaiclaw/profiles/<active>/):

Path	Role
`config.toml`	Static config (hand-edited or written by `setup`)
`config.runtime.toml`	Planned live overrides — loader exists but is not yet wired into `Config::load_or_init`
`policy/autonomy.toml`	Autonomy preset writes
`policy/command_allowlist.toml`	Shell command glob patterns
`policy/forbidden_paths.toml`	Path blocklist
`secrets/api_keys.toml`	OAuth tokens for MCP integrations

Master AEAD key (shared across profiles):


~/.rantaiclaw/.secret_key   (mode 0600 on Unix)

Path resolution waterfall:

RANTAICLAW_CONFIG_DIR env var
RANTAICLAW_WORKSPACE env var
active_workspace.toml marker file
Profile-aware default — ~/.rantaiclaw/profiles/<active>/
Flat fallback — ~/.rantaiclaw/

Same shape on Linux, macOS, and Windows.

Top-level scalars

These live at the root of config.toml:

Key	Type	Default
`schema_version`	int	current `10` (v0.7.0-alpha); written by migrations, do not edit by hand
`default_provider`	string	`"openrouter"`
`default_model`	string	`"anthropic/claude-sonnet-4.6"`
`default_temperature`	float	`0.7`
`api_key`	string (encrypted as `enc2:<hex>`)	—
`provider_api_keys`	table `provider → key` (each value encrypted as `enc2:<hex>`)	`{}`
`api_url`	string	(provider default)

workspace_dir and config_path exist on the in-memory Config struct but are #[serde(skip)] — they are populated by the loader and cannot be set in config.toml.

provider_api_keys (added in schema v6 / v0.6.81, defined in src/config/schema.rs) is a per-provider encrypted key store so switching the active provider never reuses another provider’s credential. Resolution is provider-aware (Config::resolve_key_for_provider): the per-provider entry keyed by canonical provider name is consulted first, then the top-level api_key only when the requested provider is the active default_provider, then the provider-specific env var — so a stale top-level key is never sent to the wrong provider.

Top-level sections

The Config struct in src/config/schema.rs has 34 sections ([knowledge] was added in schema v10 / v0.7.0-alpha):

Section	Purpose
`[observability]`	Tracing, Prometheus, OTLP export
`[autonomy]`	Runtime level, auto_approve, always_ask, forbidden_paths, workspace_only, rate caps
`[runtime]`	Process model, runtime adapter
`[reliability]`	Provider retries, fallback chain, API key rotation, channel reconnect backoff
`[scheduler]`	Cron / scheduled task settings
`[agent]`	Agent-loop knobs (`parallel_tools`, etc.)
`[skills]`	Discovery sources, prompt-injection mode, open-skills auto-sync, SkillForge
`[[model_routes]]`	Per-model name-prefix routing to provider/credentials
`[[embedding_routes]]`	Per-embedding-model routing
`[query_classification]`	LLM-driven message classification
`[heartbeat]`	Periodic vitality signals
`[cron]`	Cron job storage
`[tasks]`	Task subsystem (HTTP-exposed CRUD)
`[channels_config]`	Cross-channel behavior
`[memory]`	Backend, retention, embedding, hybrid weights, snapshot
`[storage]`	Storage provider override
`[tunnel]`	cloudflared / ngrok
`[gateway]`	HTTP control plane (host, port, allow_public_bind, paired_tokens, rate limits)
`[composio]`	Composio integration
`[knowledge]`	Knowledge Base credentials — `embedding_api_key`, `vision_api_key` (encrypted at rest)
`[secrets]`	Encryption toggle
`[browser]`	Browser tool settings
`[http_request]`	HTTP request tool settings
`[multimodal]`	Multimodal payload settings
`[web_search]`	Web search tool settings
`[services]`	Service detection
`[proxy]`	HTTP proxy config
`[identity]`	Agent identity / project context
`[cost]`	Cost tracking and per-day caps
`[peripherals]`	Hardware peripherals
`[[agents]]`	Multi-agent configurations
`[gateway_agents]`	Per-gateway agent routing
`[hardware]`	Hardware discovery
`[mcp_servers]`	MCP server specs (table of named entries)
`[security.sandbox]`	Sandbox enabled, backend selection — not currently wired (`SecurityConfig` is defined but not a field on `Config`; the section parses but has no effect)
`[security.resources]`	Subprocess resource limits — not currently wired (same reason as above)

Local-capability tool defaults (easy mode)

Since v0.6.89 (schema v9), the local-capability surfaces ship enabled by default so a fresh install is useful without hand-editing config first. The exposure boundary (gateway bind, pairing, public-bind) stays deny-by-default. Each default below is defined in src/config/schema.rs:

Section / key	Default	Notes
`[web_search].enabled`	`true`	`web_search` tool on by default (`WebSearchConfig::default`)
`[browser].enabled`	`true`	`browser_open` tool on by default (`BrowserConfig::default`)
`[http_request].enabled`	`true`	`http_request` tool on by default
`[http_request].allowed_domains`	`["*"]`	allow-all wildcard; if enabled with an empty list, all requests are rejected
`[http_request].max_response_size`	`5242880` (5 MiB)	raised from 1 MB
`[http_request].timeout_secs`	`20`	—
`[autonomy].block_high_risk_commands`	`false`	shell high-risk guard off by default
`[autonomy].max_actions_per_hour`	`200`	raised from 20
`[agent].max_tool_iterations`	`50`	raised from 25 so long multi-tool turns finish
`[channels_config].message_timeout_secs`	`600`	raised from 300
`[reliability].provider_retries`	`3`	raised from 2

Autonomy level still defaults to Supervised — the tool defaults above make the agent useful without changing the approval UX.

`[knowledge]` — Knowledge Base credentials

KnowledgeConfig (defined in src/config/schema.rs) holds the two Knowledge Base API keys. Both are optional and encrypted at rest like the top-level api_key:


[knowledge]
embedding_api_key = "enc2:..."   # embeddings (KB search/ingest)
vision_api_key    = "enc2:..."   # OCR / vision extraction of images & scanned PDFs

Key	Type	Encrypted	Purpose
`embedding_api_key`	string	yes (`enc2:<hex>`)	embedding provider key for KB indexing + retrieval
`vision_api_key`	string	yes (`enc2:<hex>`)	vision/OCR key for extracting text from images and scanned PDFs

Credential resolution. At load, env vars fold onto config.knowledge (env wins, matching api_key precedence — see apply_env_overrides in src/config/schema.rs):

KB_EMBEDDING_API_KEY / KB_EXTRACT_VISION_API_KEY env — overrides the config value at load.
[knowledge].embedding_api_key / vision_api_key config value — used when the env var is unset.
OPENROUTER_API_KEY env — the final fallback applied downstream (KbConfig::resolve_key).

Note the env var for the vision key is KB_EXTRACT_VISION_API_KEY, while the config key is vision_api_key.

If no key resolves through any of those, KB endpoints return the actionable kb_not_configured error (src/kb/axi/api.rs):


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

KB runtime tuning env vars. Everything except the two credentials is read from KB_* env vars at runtime (KbConfig::from_env in src/kb/config.rs), not from config.toml. Common ones:

Env var	Default	Effect
`KB_DB_PATH`	XDG data dir → `./kb.db`	KB SQLite database path
`KB_EMBEDDING_MODEL`	`qwen/qwen3-embedding-8b`	embedding model id
`KB_HYBRID_BM25_ENABLED`	`true`	BM25 + vector hybrid retrieval (set `false` to disable)
`KB_RERANK_ENABLED`	`false`	LLM reranking of results
`KB_INTELLIGENCE_ENABLED`	`false`	document-intelligence graph extraction
`KB_GRAPHRAG_ENABLED`	`false`	GraphRAG entity-graph retrieval augmentation

See Knowledge Base → Configuration for the full KB_* list, and Knowledge Base for ingesting, search & retrieval, and document intelligence.

Channel config blocks

Each enabled channel gets its own [channels.<slug>] block. See Reference → Channels for per-channel allowlist key names.

Env var prefix

All env vars use the RANTAICLAW_* prefix. Common ones:

Env var	Effect
`RANTAICLAW_CONFIG_DIR`	Override config directory
`RANTAICLAW_WORKSPACE`	Override workspace
`RANTAICLAW_PROFILE`	Active profile
`RANTAICLAW_PROVIDER`	Default provider
`RANTAICLAW_API_KEY`	Provider API key
`RANTAICLAW_MODEL`	Default model
`RANTAICLAW_ALLOW_PUBLIC_BIND`	Permit non-loopback gateway bind
`RANTAICLAW_GOOGLE_CLIENT_ID` / `_SECRET`	OAuth flows for Google MCP servers
`RANTAICLAW_OPEN_SKILLS_DIR`	Override open-skills path

Some legacy bare names (API_KEY, MODEL, PROVIDER, HOST, PORT, HTTP_PROXY) are honored as fallbacks. The Knowledge Base KB_* vars are unprefixed and documented under the [knowledge] section above.

Merge order


config.toml
  → config.runtime.toml         (planned — loader exists but not yet called)
    → RANTAICLAW_* env vars     (highest precedence, except where legacy bare names override)

Exporting the schema

The Config struct uses schemars derive to produce JSON Schema:


rantaiclaw config schema --json > rantaiclaw.schema.json

That’s the source of truth for any future doc-generation pipeline.