Hermes Agent e assinatura do Codex: configuração OAuth, cotas e API

A integração do Hermes Agent permite que desenvolvedores direcionem requisições aos modelos da OpenAI utilizando uma assinatura de consumidor do ChatGPT ou do Codex por meio do fluxo OAuth Device Code. Essa abordagem elimina a necessidade de chaves de API estáticas, mas introduz ambiguidades técnicas e financeiras. A conclusão bem-sucedida do handshake de autenticação comprova apenas a validade técnica das credenciais da conta — ela não define nem garante a mecânica de faturamento aplicada às requisições posteriores.

Limites e escopo: fatos confirmados, lacunas na documentação e verificação

Ao utilizar o Hermes Agent com contas do Codex, as interações do sistema dividem-se em três categorias distintas:

Categoria	Status na documentação	Implementação técnica e escopo de controle
Confirmado	Documentado oficialmente	Autorização via fluxo Device Code. Armazenamento local de tokens em ~/.hermes/auth.json. Importação de credenciais de ~/.codex/auth.json (sem exigir a instalação avulsa do Codex CLI). Quarentena automática de tokens revogados.
Não documentado	Não divulgado oficialmente	Planos de assinatura elegíveis e regras de dedução de cotas. A documentação oficial não especifica os planos suportados nem como os limites são debitados.
Requer verificação	Responsabilidade do usuário	Cruzamento das métricas no painel do provedor antes e depois de executar o agente, considerando a potencial latência de telemetria e a separação entre faturamento da assinatura e chaves de API independentes.

A documentação da Nous Research aborda exclusivamente o protocolo de rede para troca de chaves e os mecanismos de renovação de sessão. As fontes oficiais não detalham quais planos de assinatura são elegíveis nem como as cotas de uso são consumidas; desenvolvedores devem verificar de forma independente as métricas da conta no painel do provedor antes de executar tarefas em produção. Quaisquer alegações afirmando que o acesso aos modelos do Codex por meio de agentes é “gratuito”, “ilimitado” ou incluído sem restrições nos planos de consumo padrão são tecnicamente infundadas.

Procedimento de configuração e gerenciamento de sessões

A arquitetura do Hermes separa estritamente a configuração persistente do ambiente da troca de modelos em tempo de execução:

• hermes model — Executado diretamente no terminal, fora de qualquer sessão ativa do agente. Esse assistente gerencia o registro inicial de provedores, inicia a autorização OAuth no navegador e salva os parâmetros de configuração fundamentais.
• /model — Um comando executado dentro da sessão interativa de chat. Serve exclusivamente para alternar entre provedores e modelos já configurados. Não é possível cadastrar novos provedores ou iniciar fluxos OAuth diretamente no chat interativo.

A configuração inicial do provedor começa no terminal ao selecionar ChatGPT or Codex Subscription no menu de opções:

hermes model

Ao selecionar essa opção, o console exibe uma URL de verificação de uso único acompanhada por um código alfanumérico exclusivo do dispositivo. Abra o link em um navegador, faça login na sua conta da OpenAI e autorize a conexão. Após a confirmação, o Hermes armazena os tokens de acesso e de atualização retornados localmente em ~/.hermes/auth.json. Caso a máquina já contenha credenciais ativas do Codex CLI, o agente as importa automaticamente de ~/.codex/auth.json, eliminando a necessidade de instalar o pacote avulso do Codex CLI.

Tratamento de erros de autenticação e quarentena de tokens

Se o servidor de autorização retornar um erro fatal de autenticação (como uma resposta HTTP 4xx, status invalid_grant ou permissões de acesso revogadas), o Hermes interrompe as tentativas automáticas para evitar poluição de logs no terminal. O refresh token inválido é imediatamente colocado em estado de quarentena local. Em tentativas subsequentes de execução do agente, o sistema exibe um aviso tipado solicitando que o usuário realize uma nova autenticação.

Para redefinir o status de quarentena e concluir o fluxo de login novamente, execute:

hermes auth add openai-codex

Como alternativa, execute novamente o assistente de configuração hermes model e selecione mais uma vez o provedor de assinatura. Atualizar as credenciais com sucesso remove o indicador de quarentena de forma automática.

API dedicada versus acesso por assinatura

Conexões OAuth vinculadas a uma assinatura de consumidor e conexões diretas via API com chaves estáticas operam em ambientes financeiros e de infraestrutura totalmente isolados:

1. Assinatura: Vinculada diretamente a uma conta de consumidor do ChatGPT. A documentação oficial não especifica os planos de assinatura suportados nem detalha como as requisições via OAuth debitam os saldos de cotas. Você deve inspecionar o estado da conta e os contadores de faturamento antes de iniciar tarefas com o agente.
2. Chave de API: Configurada ao selecionar o provedor openai-api (via OPENAI_API_KEY em ~/.hermes/.env) ou gateways de terceiros. Os custos operacionais seguem a tabela de preços do provedor escolhido e nem sempre se limitam apenas ao volume de tokens consumidos.

Se a implantação de um agente exigir transparência granular de faturamento por requisição ou acesso a modelos alternativos de código aberto, as rotas por assinatura podem ser complementadas ou substituídas por um gateway dedicado. Como exemplo de arquitetura independente, consulte a documentação do BetterToken, que oferece endpoints compatíveis com o padrão da OpenAI, chaves de acesso pessoais e monitoramento de consumo por painel de controle. O roteamento via API de terceiros opera como um canal segregado: ele não converte uma assinatura existente do ChatGPT/Codex, não consome cotas da assinatura e não garante a disponibilidade exatamente dos mesmos modelos.

Lista de verificação e solução de problemas

Como os mecanismos exatos que regem as deduções de cotas em assinaturas de consumidor não são divulgados, recomenda-se estabelecer uma linha de base empírica antes do uso regular:

1. Parâmetros da conta: Verifique e registre seu plano de assinatura ativo e o saldo disponível no painel web do provedor (os requisitos de planos compatíveis não são divulgados).
2. Carimbo de data/hora e linha de base: Anote os contadores de uso iniciais junto ao carimbo de data/hora (timestamp) exato de início do teste.
3. Prompt mínimo: Inicie uma sessão do agente e execute uma solicitação curta, sem ferramentas externas (por exemplo: Calcule 256 * 4).
4. Reconciliação de saldo: Reexamine a interface de faturamento do provedor após um intervalo razoável, pois a latência de telemetria não é informada. Um contador de uso que não atualize de forma instantânea não significa que a chamada foi gratuita.
5. Higiene de segurança: Nunca compartilhe as credenciais de ~/.hermes/auth.json com terceiros nem publique logs brutos de sessões de terminal contendo fragmentos de tokens.

Caso o Hermes retorne um erro HTTP 403 ou indique permissões insuficientes após um login bem-sucedido, a causa exata específica para o Codex permanece não documentada. Examine a mensagem de resposta, confirme a elegibilidade da conta e o nível de permissões, verifique a rota e o identificador do modelo selecionados e consulte a documentação oficial ou o suporte do provedor. Se necessário, mudar para um provedor de API independente com chave de acesso própria oferece uma alternativa.