Frequently asked questions
Short answers to the most common questions. Didn't find yours? Open an issue on GitHub.
faq Do I need Python installed? No. The installer uses uv as its engine — it downloads Python 3.11+, creates the isolated environment and installs everything. The only prerequisite is git. Does it work offline / fully local? Yes. With a local LMStudio provider and the holographic or sqlite-fts5 (BM25) memory, the agent runs with no network. The remote embedder is optional and degrades to BM25 if offline. Do I have to pay for an API? Not necessarily. The posture is subscription-only: Claude via the claude CLI and Codex/MiniMax via subscription OAuth. Local models are free. Pay-as-you-go (API key) is optional. Does it work on Windows? Yes. The installer is a PowerShell one-liner and uv avoids litellm's long-path pain. If running from source without uv, use a short venv path (e.g. C:\okv). Is it reliable with a weak or small model? Yes — that's the whole point. The intelligence lives in the harness: the weaker the model, the more it decomposes, constrains (GBNF) and verifies. The quality floor is in the verifier, not the model. How does it adhere to my design system? By contract. okami.yaml → contracts.ui declares verifiable rules (library, component_source, forbid_raw_css) that become exitCriteria and are checked by okami gate — the agent can be blocked from finishing if it violates UI, components or style. How do I switch models mid-conversation? Use /model <id> to switch the session's model and /think <level> for reasoning effort. The chained fallback also switches automatically if a provider fails. Will my secrets end up in git? No. Secrets live only in .env; a literal in versioned YAML fails the policy. Also, run_shell runs with sanitized_env() — keys and tokens are stripped from the environment. Can I use it on Telegram? Yes. Set the bot token on the agent and run okami gateway. There's voice (Whisper + TTS), slash commands and per-chat go/no-go. Can I run multiple agents? Yes, experimentally. Each agent is a folder (agents/<id>) with its own model, identity and memory. okami room tests group conversations with a moderator and turn-taking, but this is still an alpha validation area. Does the persona change on its own? Can I revert? Yes and yes. An observer evolves VOICE/PERSONA from how you talk; SOUL stays protected. Everything has an append-only changelog and /undo. How do I contribute? The project is open source on GitHub (OkamiOps/Okami-Agent). Issues and PRs are welcome.