// guias · 01

Receitas (cookbook)

Tarefas reais, do começo ao fim. Cada receita é copiável e usa só o que o código entrega — sem passos mágicos. Comece pela que parece com o seu problema.

Abrir na documentação completa GitHub

Rodar uma tarefa verificável em CI

O okami task só declara sucesso quando os exitCriteria batem de fato — e sai com código ≠ 0 se o estado final não for COMPLETE. É isso que o torna seguro em pipeline.

okami task "crie um endpoint /health em FastAPI" \
  -e file_exists:app/health.py \
  -e "file_contains:app/health.py:/health" \
  -e "shell_ok:pytest -q"
echo $?     # 0 = COMPLETE · 2 = BLOCKED/NEEDS_INPUT/FAILED

Construir UI que respeita o design system

Declare o contrato uma vez no okami.yaml; depois rode o gate como exitCriteria. Código que viola o contrato (hex inline, <style> cru, import fora da lib) reprova e volta pro modelo.

okami task "tela de login com shadcn" -e ui_gate
okami gate -c ui ./src        # ou rode o gate sozinho num diretório

Rodar 100% local / offline

Um provider lmstudio (ou outro OpenAI-compat local) + memória holographic (ou sqlite-fts5) roda sem rede. O embedder remoto é opcional e degrada para BM25 se estiver offline.

okami setup --memory holographic   # backend local, sem servidor de embedding
okami provider default lmstudio
okami chat                          # conversa sem tocar a rede

Pôr um agente no Telegram

Crie o bot
Fale com o @BotFather no Telegram e copie o token.
Ligue o token no agente
O token mora no agente, não no YAML global.
```
okami setup channel    # cola o token (vai pro agent.yaml)
```
Libere o seu chat
Deny-by-default: sem allowlist o bot não responde ninguém. Pegue seu id com /whoami no chat e libere.
```
okami config set channels.telegram.allow_chats '[<seu_id>]'
```
Suba o gateway
Roda em background e devolve o terminal; 1 bot por agente.
```
okami gateway              # --status / --stop p/ controlar
```

Brainstorm multi-agente

cd examples/company          # cto / ui / backend, cada um no seu modelo
okami agent list
okami room "CTO, e o frontend?"   # o moderador decide quem fala (ou ninguém)

Agendar uma tarefa recorrente

O cron do Okami é persistido; um cron de sistema (ou systemd timer) chama okami cron tick para rodar o que venceu.

okami cron add "0 9 * * 1" "resuma os commits da semana"  # toda segunda 9h
okami cron list
# crontab do sistema:
*/5 * * * * cd /caminho/do/projeto && okami cron tick

Usar como API HTTP (headless)

okami config set OKAMI_API_TOKEN <um-token-secreto>
okami serve                                  # bind 127.0.0.1:8765 (fail-closed)
curl -s localhost:8765/chat \
  -H 'Authorization: Bearer <um-token-secreto>' \
  -H 'content-type: application/json' \
  -d '{"agent":"okami","message":"diga oi"}'

Instalar uma skill com segurança

okami learn owner/repo       # baixa p/ quarentena, escaneia, só promove se passar
okami scan ./skills/x        # re-valida sob demanda
okami skills                 # lista as ativas

Reverter uma mudança ruim

Toda escrita de arquivo entra num journal com checkpoint. Reverter as últimas N é um comando.

okami rollback 3      # desfaz as 3 escritas mais recentes

CLI · básicorun, task, chat e os critérios -e.Self-hostingLevar isto a produção com segurança.

Abrir esta página nos docs interativos