Você batizou seu relay de `Anthropic` — e a chave oficial foi enviada para ele


Você adicionou um endpoint de relay no config.yaml para cortar custos e deu a ele o nome óbvio: OpenRouter, porque é a API que ele repassa. Duas semanas depois a fatura não se moveu, e o operador do relay te manda uma mensagem: por que a sua chave oficial apareceu no meu servidor? Você confere o config. O base_url aponta claramente para o domínio deles.

Você não errou nenhum caractere. O problema era de quem o nome era. Quando uma chave de providers: colide com o nome de um provider embutido, o caminho de troca de modelo e o caminho que de fato envia a requisição chegavam a conclusões diferentes: um validava o seu endpoint, o outro enviava para o host embutido com a credencial embutida. Dois caminhos de código, duas respostas, e algo caiu pela fresta entre eles.

Uma colisão de nome, dois caminhos que divergem

providers: é onde você declara o seu próprio endpoint no config:

providers:
  OpenRouter:
    base_url: https://relay.example.com/v1
    key_env: RELAY_API_KEY
    default_model: some-model

No caso normal, a troca via /model, um save do dashboard e a requisição real do turno seguinte deveriam todos apontar para o mesmo endpoint com a mesma chave. Um nome em colisão desmanchava essa coerência.

Desde a #151042, resolve_user_provider casava chaves de providers: sem diferenciar maiúsculas de minúsculas, então Anthropic: e OpenRouter: passaram a acertar a entrada do usuário. O caminho de troca então fazia o seguinte: /model validava o seu endpoint e salvava model.provider: Anthropic. No turno seguinte, o runtime canonizava o nome embutido puro para o provider embutido (_select_named_custom_provider → _shadowed_by_builtin), e a requisição ia para api.anthropic.com — levando a sua chave embutida.

Com OpenRouter era pior de outro jeito: a requisição ia sim para a sua URL, mas carregava a OPENROUTER_API_KEY. Essa é a chave que o operador do relay viu.

O fix: um predicado, lido em três pontos de chamada

A decisão do mantenedor foi “a entrada do usuário vence”, e ela está enunciada com precisão:

Um nome de provider puro, em qualquer capitalização (openrouter, OpenRouter, anthropic, Anthropic, deepseek, …), cuja entrada em providers: sob esse nome declara o próprio base_url, significa a entrada do usuário. Um bloco com o mesmo nome e sem endpoint — só ajuste fino — mantém o provider embutido.

Essa regra vive em uma única função, builtin_name_user_entry() em hermes_cli/runtime_provider_custom.py:

def builtin_name_user_entry(name: str, providers: Any) -> Optional[str]:
    """Config key of the enabled ``providers:`` entry a bare built-in ``name`` routes to, else None.
    The one predicate the switch, the dashboard save and doctor read, so validation and the next
    turn agree: the entry wins when it declares its own base_url (#151775)."""

A expressão que importa é “o único predicado”: troca de modelo, save do dashboard e doctor leem a mesma decisão, então o endpoint que é validado é sempre o endpoint em que o turno seguinte roda. A identidade persistida segue a mesma lógica:

def persisted_provider_id(provider: str, providers: Any) -> str:
    owner = builtin_name_user_entry(provider, providers)
    return provider if owner is None else custom_provider_slug(owner, owner)

Assim, /model na chave Anthropic persiste custom:Anthropic, e o runtime resolve essa identidade de volta para o seu base_url e a sua credencial. Os dois lados concordam.

O mesmo commit fechou um buraco mais silencioso: uma chave embutida de env/pool nunca é enviada para um model.base_url que pertence a uma entrada de providers: com credencial própria. Isso cobre o caminho de api-key do registry, o caminho de entrada do pool e o caminho de env da Anthropic. Há uma exceção deliberada — uma entrada sem credencial mantém o antigo comportamento de espelho da #10622, ou seja, “usar a chave embutida contra o seu próprio espelho”.

Um aviso do doctor agora diz isso em voz alta

Depois do fix, um config como este deixa de resolver em silêncio a favor do usuário, sem avisar:

model:
  provider: openrouter
  base_url: https://relay.example.com/v1

providers:
  openrouter:
    base_url: https://relay.example.com/v1
    key_env: RELAY_API_KEY

O hermes doctor imprime (a partir de _warn_builtin_name_owned_by_entry):

⚠ model.provider 'openrouter' runs on your providers.openrouter endpoint, not the built-in
  (https://relay.example.com/v1)

e oferece duas saídas: declarar a identidade explicitamente com hermes config set model.provider custom:openrouter, ou remover providers.openrouter.base_url para voltar a usar o provider embutido. O aviso é útil porque nomeia os dois fatos de que você precisa — o endereço que está sendo acessado de fato e a identidade que você deveria estar usando — em vez de deixar você inferir.

O que conferir na sua própria máquina

Se o seu config.yaml tem uma seção providers:, gaste dois minutos em três coisas:

  1. Olhe os nomes das chaves. openai, anthropic, openrouter, deepseek, gemini, xai, lmstudio, em qualquer capitalização, contam como colisão.
  2. Rode hermes doctor e procure o aviso runs on your providers.<key> endpoint.
  3. Se você realmente quer um nome embutido apontando para o seu próprio relay, as duas rotas funcionam: escrever model.provider como custom:<key>, ou simplesmente renomear a chave para algo como my-relay — a chave em providers: é só o seu rótulo.

Por outro lado, se tudo o que você queria era um timeout maior ou um header extra para um provider embutido, não coloque base_url nesse bloco. Um bloco com o mesmo nome e sem endpoint mantém a semântica do provider embutido, e essa escapatória é explicitamente preservada pela decisão.

A lição de verdade

Num sistema de config, um “nome” costuma carregar três funções ao mesmo tempo: rótulo para humanos, chave de roteamento para o programa e escopo de credencial. No instante em que nomes escolhidos pelo usuário podem se sobrepor a nomes embutidos, essas três funções brigam — e o modo de falha raramente é um erro. É enviar em silêncio para o lugar errado, o que é especialmente ruim quando o que está sendo enviado é uma credencial.

E isso nunca aparece no primeiro uso, porque no caminho feliz os dois caminhos de código concordam. A divergência só surge nos momentos em que a identidade é recalculada: trocar de modelo, recarregar uma sessão, editar o config pelo dashboard.

Status: na main, fora da v0.23.1

O PR #152465 entrou em 2026-11-10 às 21:26 UTC; a tag v0.23.1 para num commit de 10-11 00:24 UTC. Por enquanto o fix existe só na main — instalações a partir do código que acompanham a main já têm, v0.23.1 e anteriores não.

Atualização (17/11/2026): essas mudanças saíram na v0.23.2 (16 de novembro): um hermes update as traz. O « não está na v0.23.1 » acima é um retrato da data de publicação.

Até lá, o movimento seguro é simplesmente não batizar uma entrada de providers: com o nome de um provider embutido. Renomear não custa nada em termos de funcionalidade; custa só o conforto de ler o seu próprio config.

Se quiser ir mais fundo: overrides de modelo cobre as chaves de comportamento por modelo, criptografia de secrets explica onde as credenciais realmente ficam e como são desembrulhadas, e o walkthrough dos três novos providers tem blocos providers: reais para comparar. Do lado dos comandos, a referência de config e a referência do doctor são as duas páginas que essa mudança toca diretamente.