Tutorial do Claude Code — uso diário com uma chave cobrada por uso: trocar modelos, calcular custos e gerenciar o contexto

O uso do Claude Code pode ser resumido em quatro etapas: execute claude na pasta do projeto, rode /init uma vez para gerar CLAUDE.md, descreva a tarefa em português incluindo o caminho do arquivo e revise as alterações propostas antes de decidir se deseja aceitá-las. Ele é um assistente de programação que vive no terminal: lê arquivos, edita arquivos e executa testes, pedindo sua autorização antes de agir. Pode ser usado com uma assinatura Pro/Max ou com uma chave de API cobrada por uso; com a chave, cada etapa é cobrada por tokens, então o essencial no uso diário é escolher o modelo conforme a tarefa, saber o custo de uma sessão e manter o contexto enxuto.

Quase todos os tutoriais online do Claude Code pressupõem login por assinatura. Esta página é para outro tipo de usuário: quem não tem assinatura ou não quer ficar limitado pela janela de uso de 5 horas e prefere uma chave cobrada por uso. Se ainda não instalou, consulte primeiro o tutorial de instalação do Claude Code; depois de instalar e conectar, volte aqui.

Primeiros passos: quatro ações

# 1. 一定要在專案資料夾裡啟動——它能看、能改的範圍就是這個資料夾
cd ~/work/my-app
claude

# 2. 第一個指令：讀過整個 repo，產生 CLAUDE.md
> /init

# 3. 之後直接用中文交代任務，附上檔案路徑最準
> 把 src/api/user.ts 的輸入驗證改用 zod，測試也一起修好

# 4. 牽涉很多檔案的任務，先按 Shift+Tab 切到計畫模式，確認做法再動手

Ele sempre perguntará antes de editar um arquivo ou executar um comando. Se a direção estiver errada, pressione Esc para interromper e use /rewind para voltar ao ponto de verificação anterior; o código e a conversa serão revertidos juntos. O /init gera um CLAUDE.md que é apenas um rascunho; abaixo há uma seção específica sobre como encurtá-lo.

Como uma sessão é cobrada ao usar uma chave de API

A cada solicitação, o Claude Code reenvia o prompt do sistema, CLAUDE.md, toda a conversa e o conteúdo dos arquivos lidos, acrescentando o conteúdo novo ao final. A parte inalterada usa cache: leituras do cache custam 10% do preço de entrada e gravações custam 1,25 vez o preço de entrada. Por isso, a maior parte da conta de uma sessão costuma ser a releitura da conversa antiga.

A tabela abaixo usa uma sessão de exemplo da documentação oficial de custos da Anthropic — 1.200 tokens de entrada, 5.300 de saída, 940.000 lidos do cache e 50.000 gravados — e calcula uma vez para cada um dos quatro modelos usando as tarifas da Kunavo:

Em Claude Sonnet 5, aproximadamente 85% da conta desta sessão corresponde à leitura e gravação do cache. Em outras palavras, o custo é determinado pelo tamanho da conversa, não pela quantidade de caracteres digitados — esse é o motivo da seção posterior sobre “higiene de contexto”.

Para ver seus próprios números, execute /usage no Claude Code (/cost é o alias); ele exibirá essas quatro quantidades de tokens. O valor ao lado é uma estimativa local do Claude Code baseada nos preços da Anthropic; ao usar a Kunavo, consulte a página de uso do painel para ver a cobrança real, incluindo tokens lidos e gravados no cache.

Trocar o modelo conforme a tarefa

Primeiro, no bloco env de ~/.claude/settings.json, associe cada alias ao modelo real. Escreva isso nesse arquivo para que as extensões do editor e os processos em segundo plano também possam ler; não escreva em .claude/settings.json, que será incluído em commits do projeto. Os aliases precisam corresponder: o modelo padrão do Claude Code e o alias opus apontam para o Opus mais recente; se a Kunavo ainda não o oferecer, uma configuração sem correspondência receberá 404 na primeira solicitação. O alias sonnet aponta para Sonnet 5.5, que a Kunavo não oferece; sem ANTHROPIC_DEFAULT_SONNET_MODEL, as etapas de execução de /model sonnet e opusplan e os subagentes definidos como model: sonnet também receberão 404. A configuração abaixo associa o alias opus a Claude Opus 5.5 (claude-opus-5-5), exige Claude Code v2.1.280 ou superior; em versões anteriores, execute primeiro claude update.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5"
  }
}

Depois de configurar, trocar exige apenas uma linha:

# 工作階段裡切換（別名會對應到上面設定的模型）
> /model haiku
> /model sonnet
> /model opus

# 也可以直接打完整名稱
> /model claude-fable-5

# 或在啟動時指定
claude --model claude-opus-5-5

/model salva a escolha como padrão para as próximas sessões; para mudar apenas desta vez, execute /model sem argumentos e pressione s no menu. ANTHROPIC_DEFAULT_HAIKU_MODEL é obrigatório na Kunavo: sem essa configuração, o alias haiku solicita um nome de modelo que a Kunavo não oferece (Haiku 5.5 a partir da v2.1.293), e /model haiku e os subagentes configurados com haiku retornam 404. Essa configuração também determina qual modelo o próprio Claude Code usa em segundo plano para gerar resumos e títulos; usar o modelo mais barato permite economizar ainda mais.

Na Kunavo, Claude Opus 5.5 custa $2,80 / $14,00, e Claude Sonnet 5 custa $1,40 / $7,00; a tarifa unitária de Claude Haiku 4.5 é cerca de 1/2 da de Claude Sonnet 5, enquanto a de Claude Fable 5 é 5 vezes essa tarifa de referência. Em comparação com os preços oficiais: Claude Sonnet 5 Cerca de 30% mais barato que a Anthropic oficial, Claude Opus 5.5 Cerca de 30% mais barato que a Anthropic oficial, Claude Haiku 4.5 Cerca de 30% mais barato que a Anthropic oficial, Claude Fable 5 Cerca de 30% mais barato que a Anthropic oficial.

Troque de modelo entre tarefas, não no meio de uma tarefa. O cache de cada modelo é separado: se você /model no meio da tarefa, a próxima solicitação terá de reler toda a conversa ao preço sem cache. Enquanto o cache ainda estiver válido, o Claude Code pedirá confirmação. Faça /clear antes de trocar; assim, só a nova conversa curta será relida. Tokens de raciocínio são cobrados à tarifa de saída; para tarefas simples, use /effort para reduzir o nível de raciocínio. Defina isso no início da tarefa, pois alterar o esforço no meio também invalida o cache na maioria dos modelos.

CLAUDE.md: escreva apenas o que você repetiria continuamente

# CLAUDE.md — 放在專案根目錄，commit 進 git

## 指令
- 測試：npm test（只跑一個檔：npm test -- path/to/file）
- 型別檢查：npx tsc --noEmit
- Lint：npm run lint

## 規則
- 日期一律用 date-fns，不用 moment。
- API handler 只放在 app/api/**/route.ts。
- commit 訊息用繁體中文，前綴 feat / fix / docs。

## 不要動的地方
- db/migrations/ —— 產生出來的檔案，不要手改。

CLAUDE.md é carregado no início de cada sessão e enviado em todas as solicitações seguintes, geralmente ao preço de leitura do cache. A Anthropic recomenda manter cada arquivo com no máximo 200 linhas; quanto maior, mais contexto consome e pior fica a adesão. Não escreva o que pode ser visto no código, como estrutura de diretórios e descrições de funções; observações destinadas apenas a pessoas podem ser colocadas em <!-- -->, sendo removidas antes de entrar no contexto.

Há ainda um mal-entendido comum: alterar CLAUDE.md no meio da sessão não produz efeito imediatamente; é preciso aguardar /clear, /compact ou reiniciar para que a nova versão seja carregada.

Higiene de contexto: torne cada etapa barata

• Use /clear entre tarefas não relacionadas. Isso inicia uma conversa nova e não custa nada; depois, a conversa antiga pode ser recuperada com /resume.
• Quando a mesma tarefa ficar longa demais, use /compact. Você pode indicar os pontos a preservar, como /compact 保留測試輸出和改過的檔案. Isso envia uma solicitação de resumo; faça-o enquanto o cache ainda estiver válido para obter o menor custo. Se fizer compactação depois de muito tempo, a solicitação de resumo precisará reler todo o histórico sem cache.
• Se você tomou a direção errada, use /rewind. O que será revertido já está no cache, portanto é mais barato que compactar.
• No modo de chave, o cache fica ativo por padrão durante apenas 5 minutos. Se você voltar depois de mais de 5 minutos, a primeira etapa gravará novamente todo o contexto anterior no cache, a 1,25 vez o preço de entrada. Antes de ir a uma reunião ou comer, finalize com /compact ou /clear.
• Use /context para ver o que está ocupando o contexto. Ao usar a Kunavo, esse número é uma estimativa local; atualmente a Kunavo não oferece /v1/messages/count_tokens, e a compactação automática e a própria sessão não são afetadas.
• Desative no /mcp os servidores MCP que você não usa. A documentação da Anthropic informa que, ao definir um ANTHROPIC_BASE_URL personalizado, a busca de ferramentas (tool search) fica indisponível; as definições das ferramentas MCP não são carregadas sob demanda e ocupam diretamente todas as solicitações.
• Inclua caminhos de arquivos ao descrever uma tarefa. “Altere a validação” fará o sistema pesquisar em muitos lugares e ler vários arquivos; “altere a validação de src/api/user.ts para usar zod” limita a leitura ao necessário.

Para reduzir as perguntas “posso executar?”, recomendamos liberar apenas comandos de leitura e validação. A opção que ignora todas as confirmações só deve ser usada em ambientes que podem ser completamente descartados; veja --dangerously-skip-permissions (em inglês). Para saber como o cache é cobrado, consulte a documentação do cache.

Limites de gastos e pagamento

Na página de gerenciamento de chaves, crie uma chave exclusiva para o Claude Code e defina um limite mensal; ao atingir o limite, as solicitações dessa chave retornarão 402 e não haverá novas cobranças. A mesma página também permite definir uma lista de IPs permitidos.

A conta é pré-paga: recarga mínima de $10, saldo que não expira e solicitações malsucedidas não são cobradas. Em Taiwan, é possível recarregar com cartões de crédito internacionais (Visa, Mastercard, Amex, JCB, UnionPay) ou Apple Pay e Google Pay; atualmente não há canais locais como JkoPay e LINE Pay. Consulte os detalhes em Custos do Claude Code.

Quando uma assinatura compensa mais

Para quem interage por longos períodos todos os dias e executa muitas etapas por mês, a mensalidade fixa geralmente é mais barata que a cobrança por uso. Basta uma divisão: mensalidade ÷ custo por etapa = número de etapas de equilíbrio. Usando Claude Sonnet 5 a aproximadamente $0,043 por etapa, sem considerar o cache, se você executar menos etapas do que esse número no mês, a cobrança por uso será mais econômica; meses sem trabalho custam $0. A mensalidade atual de cada plano e o cálculo completo estão na página custos do Claude Code; não os repetimos aqui.

Também é importante deixar clara a concessão: ao usar a Kunavo, você utiliza capacidade compartilhada, sem cota dedicada nem SLA contratual. Equipes que precisam de cota ou SLA garantidos devem contratar diretamente com a Anthropic. As instruções completas de conexão estão na documentação de integração do Claude Code (em inglês).

Perguntas frequentes