The first command when something's off is okami doctor — it checks providers, keys, connectivity, toolchain, SQLite FTS5, the embedder and the sandbox. Here are the…
PATH doesn't have the binary yet → reopen the terminal
Windows long-path
running from source without uv → use a short venv, e.g. C:\okv
no Python
not needed: the installer uses uv, which downloads Python 3.11+
Provider authentication
symptom
fix
claude_cli not ready
install and log in to the official claude CLI
codex not authed
run okami login codex (device flow)
minimax not authed
run okami login minimax
mimo missing key
set MIMO_API_KEY in .env
"missing auth" in doctor
okami auth list shows kind/status/where the credential lives
Memory and embeddings
symptom
behavior · fix
SQLite FTS5 missing
memory falls back to LIKE → use a Python with FTS5
embedder offline
degrades to BM25 automatically (fine, won't break)
honcho offline
okami memory list warns about the degraded layer
Sandbox and shell
Chat, gateway and API
symptom
fix
TUI won't open
falls back to the REPL automatically; force with --no-tui
gateway "already running"
okami gateway --stop then boot again
bot answers no one
deny-by-default → set channels.telegram.allow_chats
API refuses (no token)
okami config set OKAMI_API_TOKEN <token>
off doesn't allow all
off mode is fail-closed: no prompt = deny the sensitive action
Skills
Structured diagnostics
okami doctor # human-readable diagnosis
okami doctor --fix # stale lock, .env perms, temp files
okami doctor --json # report for CI/monitoring
okami doctor --lint # security-posture lint
