Pools de credencial no Hermes com duas assinaturas Codex

Ter duas assinaturas ChatGPT Plus significa que você pode registrar as duas no Hermes e deixar o agente rodar entre elas automaticamente quando uma bater limite.

Credential pools no Hermes permitem registrar múltiplas chaves de API ou tokens OAuth para o mesmo provedor. Quando uma credencial atinge rate limit ou estoura o saldo, o Hermes troca automaticamente para a próxima — sem interromper a sessão. Este guia mostra como configurar isso com duas contas Codex (baseadas em assinatura ChatGPT Plus) e, se quiser, um fallback para a OpenAI API paga por token.

A diferença entre pool e fallback

O Hermes tem dois mecanismos de resiliência que parecem parecidos, mas atuam em camadas diferentes:

O pool é tentado primeiro. Se todas as credenciais do pool falharem, aí o fallback é ativado. Os dois podem coexistir.

Cenário alvo: duas assinaturas Codex

Você tem duas contas ChatGPT Plus — a sua atual e uma segunda. Cada uma dá acesso ao Codex como provedor OAuth no Hermes. O que queremos é:

1. Registrar as duas no pool de openai-codex.
2. Quando uma bater o limite de tokens por minuto (500.000 TPM, como vimos nos logs da OpenAI API), o Hermes gira para a outra.
3. Opcional: se as duas estourarem, cair na OpenAI API paga por token como fallback.

Estado atual desta instalação

Hoje seu Hermes tem:

Para formar o pool, precisamos adicionar a segunda assinatura Codex ao provider openai-codex.

Passo a passo da implementação

Passo 1: adicionar a segunda conta Codex

O comando que abre o fluxo OAuth no navegador:

hermes auth add openai-codex --type oauth

O Hermes exibe um código de dispositivo e uma URL. Você abre a URL em qualquer navegador, insere o código e faz login com a segunda conta ChatGPT.

O resultado esperado:

$ hermes auth list openai-codex
openai-codex (2 credentials):
  #1  device_code          oauth   device_code ←
  #2  device_code_2        oauth   device_code

Passo 2: verificar se o pool está ativo

hermes auth list openai-codex

Mostra as credenciais, o status de cada uma (ok, cooling_down, exhausted) e qual está ativa no momento (marcada com ←).

Passo 3: escolher a estratégia de rotação

Você pode configurar como o Hermes escolhe entre as credenciais do pool. Por padrão, usa fill_first — consome a #1 até ela falhar, depois vai para a #2. As alternativas são:

Para definir a estratégia:

# Via CLI
hermes config set credential_pool_strategies.openai-codex round_robin

# Ou direto no config.yaml
credential_pool_strategies:
  openai-codex: round_robin

Passo 4: (opcional) configurar fallback para OpenAI API

Se as duas contas Codex estiverem exauridas, o Hermes pode cair automaticamente na OpenAI API paga por token. Para isso, você precisa de um bloco de fallback:

hermes config set fallback_providers '[{"provider": "openai-api", "model": "gpt-5.4"}]'

Ou no config.yaml:

fallback_providers:
  - provider: openai-api
    model: gpt-5.4

A ordem de resolução completa fica:

1. Pool openai-codex — tenta #1
2. Se #1 falhar com 429/402, tenta #2
3. Se ambas falharem, ativa fallback_providers → openai-api

Comportamento em caso de erro

O sistema de recuperação do pool é um dos pontos mais interessantes do recurso. Cada tipo de erro tem uma reação específica:

O flag has_retried_429 é resetado a cada chamada bem-sucedida. Isso significa que um 429 isolado não inicia uma cascata de rotação — apenas o segundo 429 consecutivo dispara a troca.

Subagentes e o pool

Se você usa delegate_task para criar subagentes, eles herdam automaticamente o pool do provider pai. Nenhuma configuração extra é necessária.

• Subagente no mesmo provider → recebe o pool completo do pai
• Subagente em outro provider → carrega o pool daquele provider
• Sem pool configurado → cai para a chave única herdada

Além disso, o leasing por tarefa garante que subagentes concorrentes não conflitem entre si ao girar credenciais simultaneamente.

Auto-descoberta: o que o Hermes já faz sozinho

O Hermes descobre credenciais automaticamente de várias fontes e as semeia no pool na inicialização:

Um detalhe importante: credenciais de ambiente (.env) são referenciadas, não armazenadas em auth.json. Se você remover a variável de ambiente, a entrada no pool é removida automaticamente. Já entradas manuais nunca são removidas automaticamente.

Resumo de comandos

# Adicionar segunda conta Codex (abre navegador)
hermes auth add openai-codex --type oauth

# Ver o pool
hermes auth list openai-codex

# Definir estratégia de rotação
hermes config set credential_pool_strategies.openai-codex round_robin

# (Opcional) Configurar fallback para OpenAI API
hermes config set fallback_providers '[{"provider": "openai-api", "model": "gpt-5.4"}]'

# Resetar cooldown de uma credencial exaurida
hermes auth reset openai-codex

# Remover uma credencial específica do pool
hermes auth remove openai-codex 2

Onde os dados ficam

O estado do pool fica em ~/.hermes/auth.json, na chave credential_pool. Cada entrada armazena: id, label, tipo de autenticação, prioridade, origem, status, contagem de requisições e fingerprint do segredo.

As estratégias de rotação ficam no config.yaml, não no auth.json:

credential_pool_strategies:
  openai-codex: round_robin

O pool é thread-safe — usa locks para todas as mutações de estado (select(), mark_exhausted_and_rotate(), try_refresh_current(), mark_used()). Isso garante segurança mesmo quando o gateway gerencia múltiplas sessões simultâneas.

Checklist rápido

1. Duas assinaturas ChatGPT Plus ativas
2. hermes auth add openai-codex --type oauth para a segunda conta
3. hermes auth list openai-codex para confirmar 2 credenciais
4. Definir estratégia (opcional, mas recomendado: round_robin para contas iguais)
5. Configurar fallback para OpenAI API (opcional)
6. Abrir nova sessão do Hermes para usar o pool

Fontes e base desta página

• Documentação oficial do Hermes — Credential Pools
• Configuração real em ~/.hermes/config.yaml e ~/.hermes/auth.json
• Logs reais de 429 rate limit na OpenAI API desta instância
• Saída de hermes auth list openai-codex e hermes auth list openai-api reais