// operação · runbooks

Runbooks operacionais

Procedimentos curtos para incidentes comuns. Cada runbook começa por diagnóstico, isola a causa provável e termina com evidência de recuperação.

Gateway caiu ou está preso

Checar estado
Veja se o processo registrado ainda existe.
```
okami gateway --status
okami doctor --lint
```
Parar com segurança
Se o PID ficou órfão, o stop limpa o estado antigo.
```
okami gateway --stop
```
Subir em foreground
Rode com logs ao vivo para capturar token, rota ou erro de provider.
```
okami gateway --foreground
```

okami ps -w workspaces/defaultlista processos conhecidos

okami process log <id> -n 120lê o log redigido

okami process signal <id> INTtenta encerramento cooperativo

okami process kill <id>mata grupo ou container quando necessário

okami process clean --ttl-hours 24 --dry-runconfere poda sem remover

sinal	ação
auth ausente	`okami auth list` e `okami login <provider>`
modelo lento ou fraco	`okami tune` para ver falhas por modelo
rate limit	troque `default_provider` temporariamente ou reduza paralelismo
CLI provider quebrado	rode o CLI oficial fora do Okami e depois `okami doctor`

Validar config
Confirme comando, args e env.
```
okami config show
okami mcp
```
Testar credencial
Tokens devem vir de .env, nunca hardcoded no YAML.
```
env | grep GITHUB_TOKEN
okami doctor --lint
```
Reduzir superfície
Desative servidores MCP um a um até achar o que quebra o bootstrap.
```
okami tools
```

okami memory search "termo problemático"encontra fatos relevantes

okami memory forget <id>remove entrada específica

okami persona-loglista mudanças de persona/voz

okami persona-rollback 1desfaz a última evolução

okami replay --jsonconfirma se o erro veio de memória, tool ou provider

okami config set OKAMI_API_TOKEN <token-forte>define token obrigatório

okami serve --host 127.0.0.1 --port 8765sobe local e fail-closed

curl -s http://127.0.0.1:8765/healthverifica health sem auth

curl -s http://127.0.0.1:8765/chat -H 'Authorization: Bearer <token-forte>' -H 'content-type: application/json' -d '{"message":"ping"}'

testa auth e payload