Documentação

goose

O goose separa o endpoint em duas partes: um URL do host e um caminho de solicitação que ele mesmo acrescenta. Informe apenas a origem e deixe o caminho como está; assim, o provedor OpenAI integrado se comunica com Claude e GPT usando uma única chave.

Settings → Models → Configure providers → OpenAI: Host URL recebe a origem sem caminho, porque o goose acrescenta o caminho da solicitação (v1/chat/completions) por conta própria.

Configure providers → OpenAI, ou por variáveis de ambiente

# goose Desktop → Settings → Models → Configure providers → OpenAI
API Key           sk-kn-...
Host URL          https://api.kunavo.com
Organization ID   (leave blank)
Project           (leave blank)

# …or as environment variables, which goose CLI reads too:
OPENAI_API_KEY=sk-kn-...
OPENAI_HOST=https://api.kunavo.com

# OPENAI_BASE_PATH is left unset on purpose. Its default is
# v1/chat/completions, which is the path Kunavo serves — that default is
# exactly why Host URL above carries no /v1.

O URL do host não deve incluir /v1. O goose documenta OPENAI_BASE_PATH como o “caminho de solicitação acrescentado ao host (o padrão é v1/chat/completions)” e orienta os usuários de proxy a definir OPENAI_HOST como “a raiz do seu proxy (sem caminho no final)”. Essa combinação esclarece o formato: a origem vai no campo, e o /v1 vem com o caminho padrão. Informar https://api.kunavo.com/v1 solicita /v1/v1/chat/completions — e a mesma página indica que um 404 significa que o caminho está errado, não a chave.

Esta configuração foi consultada na documentação do próprio goose na data abaixo. A Kunavo não executou o goose contra o endpoint — nem uma sessão, nem um turno transmitido em fluxo, nem uma interação completa com ferramentas. Uma página de configuração publicada não é um teste, e nada aqui deve ser entendido como tal; o curl abaixo é a parte que você pode verificar em dez segundos, e o comportamento do cliente depende de você e do goose.

A Kunavo não oferece modelos de embeddings, conversão de texto em fala ou conversão de fala em texto, portanto este endpoint responde a solicitações de conclusão de conversa e nada mais. Tudo o que houver na configuração do goose para transcrever áudio ou criar um índice vetorial continua usando a chave do provedor que já utiliza — apontar o provedor OpenAI para cá não redireciona essas chamadas.

Ainda não tem uma chave? Crie uma conta na Kunavo, gere uma chave (ela começa com sk-kn-) e adicione crédito a partir de $10 — as chamadas são pagas com esse saldo, e chamadas malsucedidas não são cobradas. O painel então abre na configuração de goose.

Passo a passo

Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
No goose Desktop: barra lateral → Configurações → Modelos → Configurar provedores → OpenAI. Na CLI: goose configure → Configurar provedores → OpenAI.
Preencha Chave da API e URL do host. Deixe ID da organização e Projeto vazios — o goose os documenta para monitoramento de uso e gerenciamento de recursos nas próprias contas da OpenAI, e a Kunavo não tem equivalentes para preencher esses campos. Clique em Enviar.
Escolha o modelo. A observação do goose é explícita: goose configure “não permite inserir nomes personalizados de modelos” — portanto, se o ID desejado não estiver na lista retornada, digite-o no goose Desktop ou defina GOOSE_MODEL em config.yaml, que substitui o valor do arquivo nesse processo.
Inicie uma sessão e dê a ela uma tarefa que envolva um arquivo. O goose depende do uso de ferramentas para quase tudo o que faz — a página de provedores avisa que um modelo sem suporte ao uso de ferramentas “só consegue concluir conversas” e que, nesse caso, as extensões precisam ser desativadas —, então a primeira execução, lendo e editando algo, informa mais do que uma saudação.

Verificado em Página Configurar provedor de LLM do goose em 29 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 goose.

# 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.

ID do modelo	Entrada / saída da Kunavo	Onde se encaixa em goose
`claude-sonnet-5`	$1.40 / $7.00	o modelo de trabalho padrão para sessões que editam arquivos
`claude-opus-5`	$3.50 / $17.50	planejamento de uma mudança em que errar sairia caro
`claude-haiku-4-5`	$0.70 / $3.50	interações baratas — triagem, resumos e o ciclo que roda o dia inteiro
`gpt-5-6-sol`	$2.00 / $12.00	uma segunda opinião de outra família, com a mesma chave e o mesmo URL do host

A cobrança é por token, usando um saldo pré-pago e sem tarifa mensal — consulte billing. Em contextos repetidos — que representam a maior parte do que um editor ou cliente de chat envia — o cache de prompt altera a conta mais do que a escolha do modelo.

A outra opção: o arquivo de provedor da Kunavo

O goose também carrega definições de provedores a partir de arquivos JSON no diretório custom_providers, e um provedor adicionado dessa forma recebe sua própria entrada no seletor, sua própria chave e uma lista de modelos armazenada, em vez de sobrecarregar o espaço chamado OpenAI. A Kunavo publica um arquivo em kunavo.com/goose/kunavo.json. Ele é gerado a partir do catálogo ativo, então a lista de modelos corresponde aos que a Kunavo oferece hoje, e o arquivo contém o nome da variável da chave, nunca uma chave:

terminal

# macOS / Linux — goose reads every JSON file in this directory
mkdir -p ~/.config/goose/custom_providers
curl -fsSL https://kunavo.com/goose/kunavo.json \
  -o ~/.config/goose/custom_providers/kunavo.json

# The file names the variable; the key itself never goes in the file
export KUNAVO_API_KEY=sk-kn-...
goose session start --provider kunavo

No Windows, o diretório é %APPDATA%\Block\goose\config\custom_providers\. No goose Desktop, o provedor aparece em Configurar provedores como Kunavo; nesse caso, a chave pode ser armazenada no chaveiro, em vez de no ambiente.

Endpoint. O arquivo define base_url como https://api.kunavo.com/v1. A documentação do goose não esclarece se esse campo deve receber a base /v1 ou o /v1/chat/completions completo apresentado no exemplo; o código-fonte esclarece: derive_base_path converte ambos no mesmo caminho v1/chat/completions.
Os IDs GPT usam a API Responses. O goose envia IDs de modelo que começam com gpt-5 ou gpt-6 para /v1/responses, e todos os demais para /v1/chat/completions. A Kunavo oferece ambos, portanto os IDs Claude e GPT no arquivo funcionam com uma única chave.
A lista inclui apenas modelos com suporte ao uso de ferramentas. O goose depende de ferramentas em quase todos os turnos, então os modelos de imagem, vídeo e áudio são omitidos do arquivo, embora possam ser chamados usando a mesma chave.

A mesma ressalva do restante desta página se aplica: estas informações foram consultadas na documentação e no código-fonte do goose, mas não foram testadas em execução. Prefere criar o arquivo do provedor manualmente? Acesse Configurar provedores → Adicionar provedor personalizado, que solicita os mesmos dados — tipo OpenAI Compatible, URL da API https://api.kunavo.com/v1, sua chave sk-kn- e uma lista de modelos separados por vírgulas.

Perguntas frequentes

Como direciono o goose para uma API personalizada compatível com OpenAI?

Use o provedor OpenAI integrado e informe um host. No goose Desktop, acesse Configurações → Modelos → Configurar provedores → OpenAI, onde os campos são Chave da API, URL do host, ID da organização e Projeto; na CLI, execute `goose configure` → Configurar provedores → OpenAI, que solicita os mesmos valores. Como variáveis de ambiente, o par é OPENAI_API_KEY e OPENAI_HOST. Se precisar usar vários endpoints ao mesmo tempo, o fluxo Adicionar provedor personalizado do goose atribui a cada um uma entrada própria na lista de provedores.

O URL do host do goose precisa terminar em /v1?

Não, e incluí-lo quebra a solicitação. O goose documenta OPENAI_BASE_PATH como o caminho da solicitação acrescentado ao host, com padrão v1/chat/completions, e orienta os usuários de proxy a definir OPENAI_HOST como a raiz do proxy, sem caminho no final. Portanto, o campo recebe apenas a origem — https://api.kunavo.com —, e o /v1 vem do caminho padrão. Um host terminado em /v1 solicita /v1/v1/chat/completions, o que resulta em 404, não em um erro de autenticação.

Por que o goose retorna 404 depois que defino um host personalizado?

Segundo a própria documentação do goose, um 404 geralmente significa que o caminho base está incorreto para aquele endpoint: a maioria dos proxies oferece v1/chat/completions, alguns oferecem chat/completions sem v1, e o valor configurado precisa corresponder. A Kunavo oferece v1/chat/completions, que é o padrão do goose; portanto, um 404 contra a Kunavo geralmente significa que /v1 também foi incluído no host e agora está duplicado. Um 401 informando que nenhuma chave de API foi enviada é outro problema — o goose documenta que uma chave colocada em config.yaml é ignorada.

O goose pode usar modelos Claude por meio de um endpoint compatível com OpenAI?

Sim. O tipo de provedor identifica um protocolo de comunicação, não um fornecedor: o goose envia uma conclusão de conversa no formato OpenAI ao host configurado e encaminha diretamente o ID do modelo; assim, um ID Claude é resolvido nesse endpoint, não dentro do goose. Vale lembrar que o goose usa muito o recurso de chamada de ferramentas, e a página de provedores diz que um modelo sem suporte a esse recurso só consegue concluir conversas, com as extensões desativadas — portanto, escolha IDs compatíveis com ferramentas.

A Kunavo testou essa configuração?

Não. O que foi consultado foi a documentação do próprio goose (21 e 29 de setembro de 2026) — os nomes dos campos, a ordem e a regra de host mais caminho são citados diretamente dela — e, para o arquivo do provedor, o código-fonte dos provedores do goose (29 de setembro). A Kunavo não executou uma sessão do goose contra seu endpoint e não faz afirmações sobre transmissão em fluxo, interações com ferramentas ou comportamento das extensões neste cliente. A única coisa que você pode verificar isoladamente é se o endpoint e a chave funcionam, usando o curl desta página.

Existe um arquivo de provedor da Kunavo pronto para usar com o goose?

Sim: https://kunavo.com/goose/kunavo.json. Salve-o no diretório custom_providers do goose (~/.config/goose/custom_providers/ no macOS e Linux, %APPDATA%\Block\goose\config\custom_providers\ no Windows), defina KUNAVO_API_KEY, e a Kunavo aparecerá na lista de provedores com os IDs dos modelos já preenchidos. O arquivo é gerado a partir do catálogo ativo, por isso lista apenas os modelos que a Kunavo oferece atualmente e não contém nenhuma chave.