Plugin Keystone ensina o Claude Code a instalar um gateway de LLM: 8 skills, chaves fora do chat

Se você pedir a um agente «instale um gateway de LLM para a gente», ele vai inventar, com toda a confiança, variáveis de ambiente que não existem, e você vai passar uma hora tentando descobrir por que a configuração não funciona. Um gateway de LLM é um ponto único pelo qual todos os seus serviços acessam OpenAI, Anthropic, Gemini e outros provedores: ele guarda as chaves, escolhe o modelo e troca de provedor quando algo falha. Os autores do gateway self-hosted Keystone (KTMS, escrito em Go) não resolveram o problema com pedidos no prompt, mas com engenharia: lançaram um plugin para o Claude Code com 8 skills — instruções prontas que conhecem os comandos, as flags e os campos de configuração reais — e um servidor MCP pelo qual o agente enxerga o que exatamente está rodando.

As chaves, nesse processo, não vão para o chat.

O que as 8 skills fazem

A instalação leva dois comandos: adicionar o marketplace ai-process/ktms e instalar o plugin ktms@ai-process. Além disso, é preciso ter a CLI ktms no PATH (a partir do arquivo da release ou via go install). A versão do plugin coincide com a versão do Keystone.

As skills cobrem todo o caminho: assess (avaliação do sistema e veredito sobre a necessidade de um gateway), deploy (Compose ou Helm, segredos, ordem da primeira execução), integrate (migração das chamadas de LLM de um serviço para o gateway), configure (roteamento, chaves e limites no ktms.yaml, com plano de mudanças), migrate (mudança de outro gateway ou de chamadas diretas via SDK), node (nó local com GPU e fallback para a nuvem), usage-reports (gastos, relatórios, alertas) e production-review (verificação antes e depois do lançamento). Não é preciso decorar os nomes: o agente escolhe sozinho a skill adequada, e um slash command a executa de forma explícita.

Para que as skills não fiquem desatualizadas, o CI do Keystone lê cada SKILL.md e falha se houver ali um comando, uma flag, uma ferramenta MCP ou uma seção do README que não existe naquela versão. Isso evita um problema típico: a instrução cita uma flag removida duas releases atrás, e o agente começa a improvisar.

Como fica no projeto de demonstração

O exemplo tem três serviços: um bot de suporte com o SDK da OpenAI, uma busca com o SDK da Anthropic e embeddings da OpenAI, e um worker noturno que chama o Gemini cerca de 40 000 vezes por noite. A skill assess não altera nada: ela encontra todas as cinco chamadas de LLM, com arquivo e linha, e aponta o que ninguém perguntou. Todos os serviços carregam um env_file comum, então cada um recebe as três chaves dos provedores. O gateway vai ignorar o parâmetro temperature=0.3 em uma das chamadas, por isso é preciso verificar a qualidade das respostas depois da troca. A skill também notou que o rerank.ts não reordena nada, apenas explica os resultados.

O veredito é franco: o gateway se justifica, mas, se o sistema tivesse apenas o bot de suporte com gpt-4o, ele não seria necessário. O plano começa pelo worker noturno: ali estão o dinheiro e o risco principais, os usuários não veem a chamada, e uma noite com falha pode simplesmente ser reiniciada.

A skill integrate reúne endereço, chave, timeouts, retries e atribuição de gastos em um pequeno módulo de cliente. O modelo fixado no código é substituído por um nível de complexidade com justificativa em uma linha: low para classificação e respostas curtas, medium para geração comum, high para raciocínio e documentos longos. Ela desativa os retries do SDK e implementa uma única vez o contrato de erros: aguardar o Retry-After em caso de 429, recuar em caso de 503 e não repetir erros de configuração.

A verificação final usa o roteamento real: o comando ktms route explain (saída do Keystone 1.3.6) mostra a cadeia de modelos.

Se ela termina com o status kept, está tudo certo; já no_vendor_key significa que falta uma chave, e isso aparece antes mesmo de o serviço ir para produção.

Onde fica o limite da confiança

O comando ktms init o agente deixa de propósito para o humano: no seu terminal, sem eco, ele pede a chave de administrador e as chaves dos provedores, grava o ktms.yaml com modelos e regras padrão, mostra o plano e o aplica.

Daí em diante, o configure funciona como o Terraform: edição, ktms config plan, apresentação do plano a uma pessoa e aplicação somente após a aprovação. As restrições estão embutidas nas ferramentas, e não no prompt:

• o servidor MCP, por padrão, só lê; as ferramentas de escrita aparecem com a flag --allow-write;
• config_plan devolve um plan_id, e config_apply aplica exatamente esse plano uma única vez e recusa a operação se a configuração tiver mudado nesse meio-tempo;
• a chave do provedor é lida apenas das variáveis KTMS_VENDOR_KEY_*, por isso o agente não consegue colocar na configuração a chave de administrador ou outro segredo;
• nomes e valores vindos do Keystone são marcados como dados, e não como instruções.

Limitações e o que levar para a prática

É um plugin feito pelos próprios autores do gateway, e funciona apenas com o Keystone. A API do gateway, compatível com a da OpenAI, ignora temperature, top_p, stop e seed, e os embeddings exigem o id exato do modelo, então parte das chamadas não migra de forma idêntica. Os exemplos vêm de um projeto de demonstração, e não do ambiente de produção de terceiros.

A lição vai além do gateway. Se você quer que um agente configure infraestrutura, dê a ele skills verificadas no CI contra a versão do produto, um MCP em modo somente leitura por padrão e um plano com confirmação em vez de escrita direta. Deixe os segredos com o humano. As skills são Agent Skills comuns, ou seja, pastas com um SKILL.md, então dá para copiá-las para o Codex, o Cursor ou outro agente que as leia e conectar os dois servidores MCP. Para assistentes sem suporte a skills e MCP, as mesmas instruções estão disponíveis em forma de prompts.