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:
- Olhe os nomes das chaves.
openai,anthropic,openrouter,deepseek,gemini,xai,lmstudio, em qualquer capitalização, contam como colisão. - Rode
hermes doctore procure o avisoruns on your providers.<key> endpoint. - Se você realmente quer um nome embutido apontando para o seu próprio relay, as duas rotas funcionam: escrever
model.providercomocustom:<key>, ou simplesmente renomear a chave para algo comomy-relay— a chave emproviders:é 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 updateas 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.