🆕 Criando sua conta no OpenRouter
OpenRouter é o gateway unificado que dá acesso a praticamente todos os modelos relevantes — Anthropic, OpenAI, DeepSeek, Google, Meta — sob uma única API e uma única fatura. A conta leva menos de 5 minutos e desbloqueia toda a infraestrutura do Triad.
O que é
Uma conta OpenRouter é o seu ponto de entrada único para múltiplos provedores de LLM. Em vez de gerenciar contas, faturas e chaves separadas em Anthropic, OpenAI e DeepSeek, você tem uma única conta que faz proxy para todos.
📋 Passos para criar a conta
- Acesse openrouter.ai e clique em Sign in
- Escolha autenticação por Google, GitHub ou email (OAuth é mais rápido)
- Confirme o email (caso tenha usado email/senha)
- Adicione créditos iniciais em Settings → Credits ($10 cobre semanas de uso normal)
- Pronto — você já pode gerar a primeira API key
💡 Por que OpenRouter (e não os provedores diretos)
Com uma única chave, o Triad chama Opus para o Condutor, DeepSeek para o Worker e GPT-5.5 para o Crítico — sem orquestrar três contas, três faturas e três limites de rate independentes. Custo, observabilidade e fallback ficam em um lugar só.
🔑 Conceitos-chave
Uma conta, uma chave, todos os principais provedores de LLM acessíveis
Créditos pré-pagos em USD consumidos em todos os modelos sob a mesma conta
Google ou GitHub aceleram o cadastro e evitam confirmação de email
$10 são suficientes para semanas de exercícios e validação do Triad
🔑 Gerando a API key principal
A chave do OpenRouter tem o formato sk-or-v1-... e é o que autentica todas as chamadas do Triad. Trate como senha bancária: nunca commitada, nunca em chat, nunca em screenshot.
O que é
A API key é um token longo que identifica e autoriza a sua conta. Em openrouter.ai/keys você cria múltiplas chaves nomeadas — uma por projeto, por máquina, ou por ambiente (dev/prod) — e revoga qualquer uma individualmente sem afetar as outras.
📝 Criando e armazenando a chave
# 1. Em openrouter.ai/keys clique em "Create Key"
# 2. Nomeie ("triad-laptop", "triad-prod"), opcionalmente defina limite de crédito
# 3. Copie IMEDIATAMENTE — a chave não é exibida novamente
export OPENROUTER_API_KEY="sk-or-v1-abc123...xyz"
# Persistir no shell (zsh)
echo 'export OPENROUTER_API_KEY="sk-or-v1-..."' >> ~/.zshrc
source ~/.zshrc
✗ Como NÃO tratar a chave
- ✗Commitada em .env versionado no Git
- ✗Colada em chat, Slack ou ticket
- ✗Hardcoded em arquivo config.json de exemplo
- ✗Mesma chave usada em laptop pessoal e produção
- ✗Sem limite de crédito — vazamento = fatura aberta
✓ Manejo seguro
- ✓Variável de ambiente carregada por ~/.zshrc ou keychain
- ✓Uma chave por máquina/ambiente, com nome descritivo
- ✓Limite de crédito por chave em openrouter.ai/keys
- ✓.env sempre no .gitignore
- ✓Revogação imediata se houver suspeita de exposição
💡 Dica de blast radius
Defina um credit limit por chave (ex.: $20). Se a chave vazar, o prejuízo máximo é o limite — não a sua conta inteira. Custo zero, proteção real.
🔑 Conceitos-chave
Prefixo identifica origem OpenRouter, útil para detectar vazamento em scanners
Uma chave por máquina ou ambiente reduz blast radius em caso de vazamento
Limite financeiro individual transforma vazamento em incidente contido
Variável de ambiente é o ponto único que o Hermes consulta para autenticação
🔌 Configurando OpenRouter no Hermes
O Hermes lê os provedores em ~/.hermes/config.json. O comando hermes setup model guia a configuração interativa — mas conhecer o JSON manual é o que dá controle real.
O que é
O arquivo de configuração do Hermes mapeia papéis do Triad (Condutor, Worker, Crítico) para modelos específicos via providers. OpenRouter é declarado uma vez como provider, e cada papel referencia um modelo no formato provider/model-id.
📝 Setup interativo
$ hermes setup model
? Provider: openrouter
? API key env var: OPENROUTER_API_KEY
? Conductor model: anthropic/claude-opus-4-7
? Worker model: deepseek/deepseek-chat
? Critic model: openai/gpt-5.5
✓ Saved to ~/.hermes/config.json
📄 ~/.hermes/config.json resultante
{
"providers": {
"openrouter": {
"base_url": "https://openrouter.ai/api/v1",
"api_key_env": "OPENROUTER_API_KEY"
}
},
"models": {
"conductor": "anthropic/claude-opus-4-7",
"worker": "deepseek/deepseek-chat",
"critic": "openai/gpt-5.5"
}
}
🧭 Por que api_key_env e não a chave direta
O config.json fica no disco, possivelmente no Dropbox, possivelmente sincronizado por algum agente. Guardar apenas o nome da variável de ambiente mantém o config compartilhável (e até versionável) sem nunca expor o segredo.
🔑 Conceitos-chave
O config.json é literal: conductor, worker, critic apontam para model IDs
OpenRouter usa namespace explícito: anthropic/..., deepseek/...
Config aponta para variável de ambiente — segredo nunca entra no arquivo
O comando guia o primeiro setup; editar o JSON manualmente dá controle fino depois
✅ Testando a conexão — smoke test
Antes de despachar o primeiro briefing do Condutor, valide o caminho inteiro: chave → OpenRouter → modelo → resposta. Um curl manual com DeepSeek isola problemas de auth e roteamento sem o overhead do Hermes.
O que é
Um smoke test é o teste mínimo que confirma "o sistema responde ao chamar nele". Usamos DeepSeek porque é o modelo mais barato — uma chamada custa frações de cents — e a latência típica fica abaixo de 2 segundos.
📝 Curl de validação
curl -X POST https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek/deepseek-chat",
"messages": [
{"role": "user", "content": "ping — responda apenas: pong"}
],
"max_tokens": 10
}'
📥 Resposta esperada (resumo)
{
"id": "gen-...",
"model": "deepseek/deepseek-chat",
"choices": [{ "message": { "content": "pong" } }],
"usage": { "total_tokens": 12 }
}
⚡ Smoke test via Hermes
$ hermes ping
✓ openrouter reachable 142ms
✓ conductor anthropic/claude-opus-4-7
✓ worker deepseek/deepseek-chat
✓ critic openai/gpt-5.5
🎯 Por que sempre fazer smoke test
Falhas de auth e config se manifestam como respostas estranhas dentro do loop Triad — difíceis de diagnosticar quando há três modelos conversando. Um hermes ping de 2 segundos elimina essa classe de problemas antes que ela contamine o debugging.
📊 Navegando o dashboard
O dashboard em openrouter.ai/activity é a sua observabilidade de primeira linha — custo por chamada, modelo, latência e erros, tudo em tempo quase real. Conhecer o dashboard antes da emergência é o que distingue debugging tranquilo de pânico.
O que é
O dashboard do OpenRouter é o painel web que registra cada chamada feita com a sua chave: modelo escolhido, tokens entrada/saída, custo em USD, latência, status code e erro (se houver). Tudo filtrável por chave, modelo e janela de tempo.
🗺️ Mapa das seções principais
🔍 O que olhar em /activity
- •Coluna Status: 200 = ok, qualquer outra coisa abre o pop-up de erro
- •Coluna Cost: chamadas anormalmente caras revelam loop infinito ou contexto inflado
- •Coluna Latency: p95 acima de 30s sinaliza modelo sobrecarregado — considere fallback
- •Filtro por Key: isola tráfego de uma máquina ou ambiente específico
🔑 Conceitos-chave
Toda chamada aparece — fonte da verdade para auditoria e debugging
Detecta loops, prompts inflados e modelos caros antes da fatura
p95 alto avisa que um provider está sob carga e merece fallback
Preços e capacidades atualizados — referência ao escolher trocas
🎯 Selecionando modelos padrão por papel do Triad
Os três papéis do Triad têm perfis de carga radicalmente diferentes. Condutor pensa devagar e profundo, Worker gera volume, Crítico julga rápido — e os modelos padrão refletem exatamente isso.
O que é
A seleção de modelos por papel é uma decisão de design do Triad: cada papel recebe o modelo cuja relação custo-benefício é melhor para aquela função específica, em vez de usar o modelo top-de-linha para tudo (caro e desnecessário).
Condutor → anthropic/claude-opus-4-7
Briefing demanda raciocínio profundo, restrições explícitas, ângulos diversos. Custo por chamada é alto, mas a frequência é baixa (uma vez por tarefa) e o multiplicador de qualidade no resto do loop justifica.
Executor → deepseek/deepseek-chat
Gera 3–5 ângulos por iteração, possivelmente em loop. Custo importa muito aqui. DeepSeek entrega qualidade competitiva a uma fração do preço dos modelos premium.
Crítico → openai/gpt-5.5
Julga SHIP/REVISE com base em critérios. Precisa de raciocínio sólido e perfil de calibração diferente do Executor — modelo de outra família reduz convergência cega.
📄 Configuração completa de referência
{
"providers": {
"openrouter": { "api_key_env": "OPENROUTER_API_KEY" }
},
"models": {
"conductor": "anthropic/claude-opus-4-7",
"worker": "deepseek/deepseek-chat",
"critic": "openai/gpt-5.5"
},
"defaults": {
"temperature": 0.7,
"max_tokens": 4000
}
}
💡 Heterogeneidade é feature, não bug
Usar três famílias de modelos diferentes (Anthropic + DeepSeek + OpenAI) reduz convergência cega — o risco de três instâncias do mesmo modelo concordarem por viés compartilhado em vez de por mérito do argumento.
🔑 Conceitos-chave
Baixa frequência + alto impacto = premium; alta frequência = custo otimizado
Famílias diferentes reduzem convergência cega no julgamento
Trocar de modelo é editar uma linha — não refatorar código
Temperature e max_tokens herdados por todos os papéis, sobrescritíveis por chamada
🚨 Troubleshooting — erros comuns
Quatro códigos cobrem 95% dos incidentes de conexão. Reconhecer cada um em segundos — pelo status code, antes de ler a mensagem — corta tempo de diagnóstico drasticamente.
O que é
O OpenRouter retorna status HTTP padrão; cada código mapeia para uma classe de problema com remediação específica. Conhecer o mapa elimina o "google a mensagem de erro" da sua rota de debugging.
401 — Unauthorized
Causa: chave inválida, expirada, revogada ou ausente.
Remediação: echo $OPENROUTER_API_KEY para confirmar que está carregada; em openrouter.ai/keys verifique status; gere nova chave se necessário.
404 — Not Found (modelo)
Causa: model ID errado, modelo descontinuado ou typo no formato provider/model.
Remediação: consulte openrouter.ai/models e copie o ID exato. Exemplo comum: deepseek/chat (errado) vs deepseek/deepseek-chat (certo).
429 — Too Many Requests
Causa: rate limit do provider upstream estourado (ou crédito esgotado).
Remediação: aguarde o intervalo do header Retry-After; verifique saldo em /credits; configure fallback automático em /settings.
408 / 504 — Timeout
Causa: provider lento, prompt enorme, ou rede instável.
Remediação: retry com backoff exponencial; reduza max_tokens ou contexto; considere fallback de provider via OpenRouter Settings.
🛠️ Diagnóstico rápido pelo Hermes
$ hermes doctor
✓ OPENROUTER_API_KEY set (sk-or-v1-***xyz)
✓ config.json valid JSON
✓ network openrouter.ai reachable
✗ critic model openai/gpt-5.5 → 404 Not Found
hint: check id at https://openrouter.ai/models
🎯 Regra dos 30 segundos
Antes de mergulhar em logs, rode hermes doctor e abra o dashboard. Em 30 segundos você sabe se é auth, modelo, rede ou crédito — e qual das quatro classes está em jogo.
✅ Resumo do Módulo
Próximo Módulo:
2.3 — DeepSeek BYOK: conectando sua chave direta para reduzir custo do Executor