// guias · 04
Solução de problemas
O primeiro comando quando algo não vai bem é okami doctor — ele checa providers, chaves, conectividade, toolchain, SQLite FTS5, embedder e sandbox. Aqui estão os si…
Instalação e PATH
sintoma causa · correção okami não encontradoPATH ainda sem o binário → reabra o terminal long-path no Windows rodando do código sem uv → use um venv curto, ex. C:\okv sem Python não precisa: o instalador usa o uv, que baixa o Python 3.11+
Autenticação de provider
sintoma correção claude_cli não prontoinstale e logue o CLI oficial claude codex sem auth rode okami login codex (device flow) minimax sem auth rode okami login minimax mimo falta chave defina MIMO_API_KEY no .env "falta auth" no doctor okami auth list mostra tipo/status/onde mora a credencial
Memória e embeddings
sintoma comportamento · correção SQLite FTS5 ausente memória cai para LIKE → use um Python com FTS5 embedder offline degrada para BM25 automaticamente (ok, não quebra) honcho offline okami memory list avisa a camada degradada
Sandbox e shell
Atenção backend=docker exigido, mas Docker não está disponível — run_shell DESABILITADO: é proposital. Backend docker explícito sem Docker NÃO cai no local inseguro. Instale o Docker, ou use backend: auto (cai no local) / backend: local.
Chat, gateway e API
sintoma correção TUI não abre cai no REPL automaticamente; force com --no-tui gateway "já está no ar" okami gateway --stop e suba de novobot não responde ninguém deny-by-default → defina channels.telegram.allow_chats API recusa (sem token) okami config set OKAMI_API_TOKEN <token>off não libera tudomodo off é fail-closed: sem prompt = nega o sensível
Skills
Nota okami learn clawhub:<slug> recusa por padrão: o ClawHub roda npx (código) ANTES do scan validar. Use --allow-exec só se confiar na origem; prefira git/caminho local (estáticos).
Diagnóstico estruturado
okami doctor # diagnóstico legível
okami doctor --fix # lock órfão, perms do .env, temporários
okami doctor --json # relatório p/ CI/monitoramento
okami doctor --lint # lint de postura de segurança
