Configuração BYOK do Hermes Agent: guia passo a passo

O que BYOK significa de fato no Hermes Agent

O Hermes Agent é BYOK por design. Você aponta ele para qualquer provedor no qual já tenha credenciais e cada chamada de inferência é cobrada na sua conta do provedor, não em uma camada intermediária que remarca os tokens. Isso não é um truque para furar um paywall, é a postura padrão do agente: agnóstico ao modelo, agnóstico ao provedor e enviesado a favor do backend em que você confia com seus dados.

Duas coisas costumam confundir no começo. Primeiro, BYOK no Hermes cobre chaves de API de LLM reais (OpenAI, Anthropic, OpenRouter, Kimi, MiniMax e muitas outras) e também endpoints compatíveis com OpenAI, o que significa que um vLLM ou Ollama auto-hospedado também conta. Segundo, BYOK é por backend, não é tudo-ou-nada. Você pode usar Anthropic para raciocínio e Ollama para resumos de fundo baratos no mesmo agente, se configurar os dois.

O resto deste guia percorre a escolha de um provedor, o armazenamento da chave sem vazá-la e a troca depois sem refazer o setup.

Por que BYOK importa mais do que "créditos grátis de API"

Todo SaaS de IA acaba te pedindo para confiar na chave comum opaca dele. BYOK quebra esse modelo. Sua credencial, sua conta, sua política de retenção de dados, seu log de auditoria. Se a plataforma sumir amanhã, sua conta no provedor continua funcionando.

Os benefícios práticos, na ordem em que costumam pesar em deployments reais do Hermes:

Controle de dados. Os logs do lado do provedor, as regras de retenção e os termos de Zero Data Retention são regidos pelo seu acordo com o provedor do modelo, não pelos padrões negociados pelo fornecedor do agente.
Transparência de custo. Sem markup escondido entre você e o modelo. Se você usa OpenRouter, vê o mesmo custo por token que veria em um curl direto.
Sem lock-in de fornecedor. Trocar de provedor é uma mudança de duas linhas de config, não um projeto de migração. O comando hermes model te leva entre Claude, GPT, Gemini ou Llama sem mexer nas skills nem na memória.
Botão de desligar do seu lado. Se uma chave vazar ou a conta disparar, você rotaciona no painel do provedor. O agente para em segundos, e ninguém mais precisa aprovar a rotação.

Para o plano Starter da Hermify, BYOK é o coração da coisa. A faixa é desenhada em torno de "você traz a chave, a gente roda o contêiner". Por isso vale a pena aprender o setup abaixo mesmo que você planeje usar hosting gerenciado depois.

Passo a passo: configure seu primeiro provedor BYOK

O Hermes precisa de pelo menos um provedor configurado para rodar. O caminho de menor atrito é OpenRouter (uma chave, centenas de modelos), mas a mecânica é a mesma para OpenAI, Anthropic e qualquer outro backend suportado.

1. Consiga uma chave no provedor

Escolha um e gere uma chave no painel do provedor:

OpenRouter em openrouter.ai. A chave começa com sk-or-. É a melhor opção padrão para BYOK.
OpenAI em platform.openai.com. A chave começa com sk-.
Anthropic em console.anthropic.com. A chave começa com sk-ant-.
Kimi, MiniMax, GLM, Nous Portal e outros seguem o mesmo padrão: cadastra, gera a chave e copia uma vez.
Ollama ou vLLM rodando na sua máquina. Não precisa de chave, só da URL do endpoint compatível com OpenAI.

Adicione crédito (ou um meio de pagamento) no provedor. Se a conta estiver zerada, o Hermes vai falhar na primeira chamada com um erro claro.

2. Rode o setup interativo

Do terminal, na máquina onde o Hermes vive:

hermes setup

Escolha o provedor da lista, cole a chave e selecione um modelo. O Hermes escreve a configuração por você.

Se preferir por script, o mesmo sem prompts:

hermes config set OPENROUTER_API_KEY sk-or-sua-chave-aqui
hermes config set MODEL "anthropic/claude-sonnet-latest"

O prefixo ~ num identificador de modelo (~anthropic/claude-sonnet-latest) significa "última versão dessa família", então você não precisa ficar perseguindo snapshots novas na mão.

3. Saiba onde a chave mora

O Hermes guarda segredos e configuração em arquivos separados, de propósito:

Segredos vão para ~/.hermes/.env (permissão 600, só o usuário lê).
Nome do provedor, modelo e feature flags vão para ~/.hermes/config.yaml e são seguros de versionar.

Essa divisão importa. Você pode versionar config.yaml em um repo privado ou nos seus dotfiles e reproduzir uma instalação Hermes em outra máquina, e adicionar a chave nessa máquina a partir de uma variável de ambiente ou de um gerenciador de segredos sem nunca escrevê-la em disco em texto claro.

Se você versiona o config, adicione ~/.hermes/.env ao seu .gitignore. Se usa gerenciador de segredos (1Password CLI, doppler, sops, Bitwarden), você pode gerar o .env no boot em vez de deixar a chave em disco de forma permanente.

4. Verifique que funcionou

Mande um smoke test pelo Hermes:

hermes chat "diga oi e me diga qual modelo você é"

Se a chave estiver errada, a conta sem crédito ou o endpoint fora do ar, o erro te diz qual. Corrija e rode de novo. Não avance para skills, tarefas agendadas ou ajuste de memória até o provedor responder limpo.

Como escolher o provedor certo

Você não fica preso à primeira escolha. Mas a primeira importa, porque ela define o teto do trabalho com memória, tool calling e contexto longo que o Hermes vai tentar.

Você quer zero atrito, "só faz funcionar": OpenRouter com ~anthropic/claude-sonnet-latest. Uma chave, uma conta, troca de modelo fácil.
Você já tem conta na OpenAI ou na Anthropic: use o provedor direto. Custo por token ligeiramente menor do que rotear via OpenRouter, mas sem fallback entre provedores.
Quer ficar em infraestrutura da Nous Research: Nous Portal é o caminho abençoado oficialmente e casa naturalmente com os system prompts do Hermes.
Quer rodar local: Ollama ou vLLM como endpoint compatível com OpenAI. Não custa por token, exige uma máquina com GPU e precisa de um modelo com suporte real a tool calling para ser útil ao agente.
Quer isolamento estrito de dados: Anthropic direto (Zero Data Retention sob pedido) ou um endpoint auto-hospedado. Não passe por agregadores se essa é sua prioridade.

O Hermes precisa de um modelo com pelo menos 64K tokens de contexto, porque os arquivos de memória persistente (MEMORY.md, USER.md, skills) são injetados em cada chamada. Modelos de contexto menor descartam contexto em silêncio, e isso quebra o loop de memória que faz o Hermes não ser um chatbot sem estado.

Se você quer um mergulho mais fundo em como escolher o modelo em si, veja como configurar o Hermes Agent com OpenRouter.

Erros de configuração para evitar

Alguns padrões queimam os usuários no primeiro setup BYOK:

Commitar o arquivo .env. O erro mais comum. Nem repositório "privado" no GitHub é lugar seguro para chaves sk-. Adicione .env ao .gitignore do dia zero.
Escolher um modelo sem suporte a tool calls. Alguns modelos baratos no OpenRouter não conseguem chamar ferramentas. O Hermes precisa disso para escrever arquivos, buscar na web, rodar tarefas agendadas e MCP. Se as skills pararem em silêncio, cheque as flags de capacidade do modelo.
Sub-financiar a conta do provedor. Provedores pausam as requisições quando o crédito bate um limiar. Configure um recarregamento automático no OpenRouter ou um alerta de saldo baixo na OpenAI para que um cron longo do Hermes não morra às 3 da manhã.
Guardar a chave no histórico do shell. hermes config set OPENROUTER_API_KEY sk-or-... vai para o .bash_history por padrão. Prefira hermes setup (interativo, sem histórico) ou coloque um espaço antes do comando se o seu shell estiver configurado para pular essas linhas.
Achar que uma chave cobre tudo. Ferramentas MCP que precisam de credenciais próprias (um token do GitHub, uma chave do Notion) são slots BYOK separados. A chave do LLM não desbloqueia isso.
Não rotacionar. Coloque um lembrete no calendário a cada 90 dias para rotacionar a chave do provedor. hermes config set sobrescreve o valor antigo de forma limpa.

Se travar, troubleshooting do Hermes Agent no Telegram cobre os modos de falha comuns de ponta a ponta.

O que muda com hosting gerenciado

Tudo acima é como uma instalação auto-hospedada do Hermes se parece. Se você deploya via Hermify, o modelo BYOK é idêntico (sua chave, sua conta, seus dados), mas a mecânica vai para o painel:

Cole a chave da OpenRouter, OpenAI ou Anthropic uma vez no onboarding.
A Hermify criptografa em repouso e injeta no seu contêiner no boot. Nunca aparece nos logs, nunca é mostrada de volta após salvar e rotaciona limpo sob demanda.
Troque de modelo pelo painel sem dar SSH em lugar nenhum. A mudança vale no próximo reinício do agente, que fica a um clique.
O plano Starter é BYOK-only por design. Pro e Dedicated incluem uma chave gerenciada se você preferir pular o cadastro no provedor, mas você ainda pode trazer a sua se quiser.

O ponto é que BYOK não é uma característica só de self-hosting. É uma postura: sua credencial, seus dados, seu botão de desligar. O hosting gerenciado preserva isso, só cuida da operação ao redor.

Comece agora

Se você é self-hosting, roda hermes setup, cola a chave e pronto. Se quer o mesmo modelo BYOK sem a manutenção do contêiner, comece com a Hermify e você está no Telegram em cerca de um minuto.

De qualquer forma, mantenha a chave do seu lado da cerca. É para isso que serve o BYOK.