Documentação

Crush

O Crush é o agente de programação para terminal da Charm — não o shell Rust de mesmo nome. Sua configuração é em Bash, então apontá-lo para outro endpoint exige apenas adicionar um provedor com tipo, URL base e chave.

A configuração do Crush é Bash — um único `provider add kunavo --type openai-compat --base-url "https://api.kunavo.com/v1"` em um crushrc coloca o agente de terminal do Charm em Claude e GPT.

~/.config/crush/crushrc

# A crushrc is Bash, not a settings file. Everything here is executed.
provider add kunavo \
  --type openai-compat \
  --base-url "https://api.kunavo.com/v1" \
  --api-key "${KUNAVO_API_KEY:?set KUNAVO_API_KEY}"

model add kunavo/claude-sonnet-5 \
  --name "Claude Sonnet 5" \
  --context-window 1000000 \
  --default-max-tokens 32000 \
  --price-input 1.4 \
  --price-output 7

model add kunavo/claude-haiku-4-5 \
  --name "Claude Haiku 4.5" \
  --context-window 200000 \
  --default-max-tokens 16000 \
  --price-input 0.7 \
  --price-output 3.5

model large kunavo/claude-sonnet-5
model small kunavo/claude-haiku-4-5

A URL base mantém o sufixo /v1. O exemplo compatível com OpenAI documentado pelo próprio Crush é --base-url "https://api.deepseek.com/v1", e o exemplo compatível com Anthropic termina da mesma forma — portanto, o sufixo é uma convenção do cliente, não uma suposição. Se você omiti-lo, receberá um erro 404 em vez de um erro de autenticação.

Use --type openai-compat, não openai. O README traça essa distinção: openai serve para encaminhar ou rotear solicitações pela OpenAI; openai-compat, para provedores que não sejam a OpenAI e tenham APIs compatíveis com OpenAI. O Kunavo é o segundo caso.

Um crushrc é um script Bash com comandos integrados do Crush, e o próprio Crush alerta que ele é código confiável — executado em um shell completo. Essa também é a vantagem: --api-key "$(op read ...)" mantém a chave fora do arquivo. O crush.json mais antigo ainda é carregado, mas o README o considera obsoleto; por isso, use o crushrc.

O Kunavo não testou o Crush em tempo de execução — nem este cliente nem qualquer outro destas páginas. O que foi verificado aqui é a configuração documentada pelo próprio Crush em relação ao endpoint publicado pelo Kunavo; uma página de configuração não é um resultado de teste. Execute uma tarefa limitada antes de adotá-lo para o uso diário.

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

Passo a passo

Crie uma chave em /app/keys e copie-a — ela será exibida uma única vez. Exporte-a como KUNAVO_API_KEY ou leia-a de um gerenciador de senhas diretamente na configuração.
Coloque o bloco acima em ~/.config/crush/crushrc. O Crush lê ./.crushrc, depois ./crushrc e, por fim, a configuração global. Assim, um projeto pode substituir a configuração da máquina — e um repositório clonado pode incluir uma configuração própria.
Inicie crush e pressione ctrl+l para abrir o seletor de modelos. As linhas model large e model small acima já definem os dois espaços, então o seletor serve para trocar de modelo, não para configurá-lo.
Se preferir não cadastrar IDs manualmente: a descoberta automática é executada quando a lista de modelos de um provedor openai-compat está vazia ou quando você passa --discover-models true. O Kunavo responde a GET /v1/models, então a lista é preenchida automaticamente, e seus próprios campos model add prevalecem em caso de conflito.
Execute uma tarefa limitada e depois confira a cobrança registrada na sua conta em /app/billing. O valor exibido no terminal é calculado a partir dos números de --price-* que você digitou; o extrato mostra a cobrança.

Verificado em A seção Provedores personalizados do Crush 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.

Esta é a versão resumida. O guia completo — escolha do modelo, custo de uma sessão real e modos de falha — está em Crush vs OpenCode.

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

# 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 Crush
`claude-sonnet-5`	$1.40 / $7.00	o espaço do modelo grande — o modelo para programação e edição do dia a dia
`claude-haiku-4-5`	$0.70 / $3.50	o espaço do modelo pequeno, usado constantemente pelo Crush para títulos e resumos
`claude-opus-5`	$3.50 / $17.50	troque para o modelo grande em uma refatoração em que um plano errado sairia caro
`gpt-5-6-terra`	$0.70 / $4.20	uma segunda família usando a mesma chave, a apenas mais um model add

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.

Perguntas frequentes

Como adiciono um provedor de API personalizado ao Crush CLI?

Grave isso em um crushrc, que usa Bash com os comandos integrados do Crush. Uma linha registra o endpoint — provider add kunavo --type openai-compat --base-url "https://api.kunavo.com/v1" --api-key "$KUNAVO_API_KEY" — e um comando model add para cada ID registra o que você quer chamar, com o nome de exibição, a janela de contexto e os preços por milhão que o Crush usa para a estimativa exibida na tela. O Crush lê ./.crushrc, depois ./crushrc e, em seguida, ~/.config/crush/crushrc; assim, o mesmo bloco funciona por projeto ou por máquina.

A URL base do Crush precisa terminar com /v1?

Sim. Os exemplos de provedores personalizados do próprio Crush incluem o sufixo para os dois tipos: https://api.deepseek.com/v1 para o caso compatível com OpenAI e https://api.anthropic.com/v1 para o caso compatível com Anthropic. Para uma chave Kunavo, o valor é https://api.kunavo.com/v1. Isso é o oposto do Claude Code, em que ANTHROPIC_BASE_URL recebe a origem sem caminho porque esse cliente acrescenta o caminho por conta própria — mesmo gateway, duas formas de escrever, e a falta de /v1 resulta em 404, não em 401.

Devo usar --type openai ou --type openai-compat?

openai-compat, para qualquer gateway de terceiros. O README do Crush reserva openai para encaminhar ou rotear solicitações pelo próprio OpenAI e orienta usar openai-compat para provedores que não sejam da OpenAI e tenham APIs compatíveis com OpenAI. O tipo também determina o comportamento além do formato na transmissão: a descoberta automática de modelos é executada para um provedor openai-compat cuja lista de modelos esteja vazia. O Crush também oferece suporte a --type anthropic para endpoints compatíveis com Anthropic, que recebe --extra-header anthropic-version 2023-06-01.

crush.json ainda é o lugar certo para essa configuração?

Não. crush.json é o formato original, e a documentação do próprio Crush agora o descreve como obsoleto e sem novos recursos; o formato atual é crushrc. Observe que ambos são executados, em vez de analisados — um crushrc é executado em um shell completo, e qualquer $(...) dentro de crush.json é expandido no carregamento —, por isso a documentação alerta para não iniciar o Crush em um diretório cuja configuração você não tenha lido. É também por isso que é possível buscar uma chave em um gerenciador de senhas dentro da configuração.

Por que o custo exibido pelo Crush é diferente do valor cobrado?

Porque são dois valores diferentes, provenientes de fontes distintas. A estimativa exibida na tela para um provedor cadastrado manualmente é calculada com base nos valores --price-input e --price-output que você informou em model add; para provedores integrados, ela vem do Catwalk, o catálogo externo de provedores do Crush. Nenhum dos dois consulta sua conta. Um erro de digitação em uma flag --price-* gera um valor exibido incorreto, não uma cobrança incorreta. Confira o extrato em /app/billing.

O Crush pode usar modelos Claude ou GPT por meio de um provedor personalizado?

Sim, e nada no Crush restringe esse uso. Charm Hyper é o provedor oficial para o qual o fluxo de integração direciona você, mas um provedor personalizado é uma opção documentada e de primeira classe, sem restrição de plano, e o ID do modelo é resolvido no endpoint, não no cliente. Portanto, um ID Claude em um provedor openai-compat é a combinação prevista: o tipo indica o protocolo de transmissão, não o fornecedor.