Jan Agent

Uma linha `jan config set --base-url https://api.kunavo.com/v1` grava a Kunavo em ~/.jan/config.toml, e a CLI de prévia do Jan Agent — que não inclui mecanismo de inferência — roda com essa chave.

# Jan Agent is a preview on a nightly channel — check your build first.
jan --version

jan config set \
  --provider kunavo \
  --api-key sk-kn-... \
  --base-url https://api.kunavo.com/v1 \
  --model claude-sonnet-5 \
  --model claude-haiku-4-5 \
  --api-type openai

jan config list   # configured providers as JSON, keys redacted

Passo a passo

1. Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
2. Confira o que você está configurando: jan --version. O Jan Desktop também inclui uma CLI chamada jan, mas com um conjunto diferente de comandos; portanto, confirme que jan config set --help lista --base-url antes de digitar o restante.
3. Execute a linha jan config set acima. --provider é um ID escolhido por você, não um nome de uma lista fixa — o próprio exemplo da documentação para hardware local usa --provider local — e --model pode ser repetido; ele substitui qualquer lista existente em vez de acrescentar itens a ela.
4. Confirme que a configuração foi aplicada com jan config list (com as chaves ocultadas) ou jan config path para ver o próprio arquivo; em seguida, execute jan cli models list para conferir o que cada provedor oferece. Um ID de modelo digitado manualmente permanece mesmo quando o endpoint deixa de listá-lo; jan cli models refresh --provider kunavo considera como verdadeira a lista do endpoint.
5. Acesse um projeto e execute jan; depois, escolha o modelo com /model. Prefira jan --plan na primeira execução: ele é somente leitura, então uma incompatibilidade de protocolo aparece antes de qualquer gravação no disco.
6. Dê a ele uma tarefa que edite um arquivo. O Jan Agent é um agente, portanto o uso de ferramentas e a transmissão em fluxo são o que uma primeira execução deve exercitar — são os recursos que falhariam primeiro se a compatibilidade do endpoint fosse apenas parcial, e uma saudação não exercita nenhum dos dois.

Verificado em Página de provedores do Jan Agent em 21 de setembro de 2026. As configurações de terceiros podem mudar; se o nome de um campo aqui já não corresponder ao que você vê, aquela página é a autoridade, não esta.

Verifique antes de depurar o cliente

Uma solicitação determina se a falha está no endpoint, na chave ou no arquivo de configuração. Se isto retornar JSON, a mesma URL base e a mesma chave funcionarão em Jan Agent.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Qual ID de modelo inserir no campo

Todo modelo de texto pode ser acessado como um ID de modelo — a lista atual está em GET /v1/models, e o catálogo com preços está na página de modelos. As tarifas são em USD por 1 milhão de tokens, entrada / saída.

Há duas coisas diferentes chamadas chave de API do Jan

Elas ficam no mesmo arquivo e têm significados opostos; por isso, jan config list pode parecer incorreto para quem espera a outra.

O Jan Desktop não emite nenhum dos dois: ele não tem conta, então não há nada para gerar nele. O servidor de API local aceita uma chave que você mesmo inventa, que é um terceiro significado e pertence a outro host.

O que o Jan Desktop fornece e onde isso termina

O Jan Agent lê as configurações do provedor em quatro fontes, cada uma prevalecendo sobre as anteriores, e a segunda surpreende muita gente.

1. ~/.jan/config.toml — a base e o único arquivo que jan config set grava.
2. O settings.json do Jan Desktop — apenas herdado. Ele adiciona provedores que você não configurou no Agent, nunca substitui os que você já configurou e nunca grava alterações de volta nesse arquivo.
3. Um bloco [provider] no agent.toml de um projeto — uma escolha explícita por projeto, que prevalece sobre as duas fontes anteriores. Esse arquivo normalmente é enviado para o repositório, então mantenha api_key fora dele.
4. --provider / --api-key na linha de comando, ou JAN_API_KEY / <PROVIDER>_API_KEY — a opção mais explícita e mais efêmera.

Há duas consequências que convém conhecer antes de depurar o problema errado. jan config list pode não mostrar nenhum provedor, enquanto jan cli models list retorna vários — o segundo inclui os provedores herdados do Desktop, que não estão armazenados em ~/.jan/config.toml. Além disso, um provedor herdado nunca é atualizado, porque não há uma entrada aqui para reescrever: se você quiser manter atualizada a lista de modelos da Kunavo, ela precisa ser uma entrada jan config set própria, como a criada pelo bloco acima.

Quando dois provedores oferecem o mesmo ID de modelo

A Kunavo oferece IDs como claude-sonnet-5, assim como uma entrada de provedor apontada diretamente para o fornecedor. O Jan Agent precisa escolher um deles, e a ordem documentada é: primeiro, uma correspondência exata na lista models de um provedor; depois, um prefixo <provider>/<model> que indique um provedor configurado; e, quando vários oferecem o mesmo ID, um provedor com credenciais prevalece sobre um equivalente sem chave. Portanto, kunavo/claude-sonnet-5 é como você indica qual deles queria usar. O qualificador serve apenas para o Jan — ele é removido antes do envio da solicitação, pois os provedores upstream rejeitam IDs qualificados com o nome de um provedor.

A mesma entrada, dentro do console

Se preferir não digitar opções: /settings > providers gerencia as mesmas entradas ~/.jan/config.toml, e a abre um formulário de adição com os campos name, base url, api key e models separados por espaços. O formulário faz duas coisas que as opções de linha de comando não fazem: a URL base precisa usar https:// (ou http:// para um endpoint localhost), para que uma chave nunca seja enviada por uma conexão remota sem criptografia — a Kunavo usa https://, então isso não é um impedimento — e, ao editar, o campo da chave de API mostra (unchanged) e mantém o valor armazenado, a menos que você digite algo nele. Se você deixar esse campo em branco, a chave será apagada, em vez de permanecer como está.