Como Instalar e Configurar o Claude Code: API, LLM Local, Skills e Exemplos Práticos

Claude Code · Anthropic · Ollama · LLM Local · CLI · Skills · Hooks · MCP · Sysadmin  |  ✎ Duarte Spínola  |  7 de Maio de 2026

O Claude Code é a ferramenta de coding agêntico da Anthropic que vive no terminal — lê o codebase completo, edita ficheiros em múltiplos locais, corre comandos shell, gere workflows Git e liga-se a ferramentas externas via MCP. Não é um chat com blocos de código: é um agente autónomo que opera directamente no teu ambiente de desenvolvimento. Em Abril de 2026, cerca de 4% dos commits públicos no GitHub — mais de 135.000 por dia — são da autoria do Claude Code.

Este guia cobre tudo: instalação, as duas formas de autenticação (API key e subscrição), como ligar o Claude Code a um LLM local via Ollama ou LM Studio (código nunca sai da máquina), as configurações iniciais que fazem diferença desde o primeiro dia, skills essenciais para sysadmins e developers, e exemplos concretos de utilização.

1. O que é o Claude Code — e o que o Diferencia

O Claude Code opera como agente autónomo no terminal — não como assistente de chat. A diferença prática é significativa:

Ferramenta Como opera Ideal para
GitHub Copilot Autocompletar inline dentro do editor Completar código enquanto escreves
Cursor IDE com IA integrada — edições dentro do editor Edições de ficheiros individuais ou pequenos grupos
Claude Code Agente no terminal — lê codebase, executa comandos, edita múltiplos ficheiros, gere Git Tarefas que cruzam muitos ficheiros, requerem shell commands, ou orquestram subagentes em paralelo

ℹ Claude Code não é só para developers

Para sysadmins, o Claude Code é uma ferramenta de automação de infra — analisa logs, gera scripts PowerShell/Bash, cria configurações, lê e edita ficheiros YAML/JSON de configuração, e executa comandos directamente. Qualquer coisa que faças num terminal pode ser delegada ao Claude Code.

2. Instalação — Pré-requisitos e Instalação do CLI

Pré-requisitos

Requisito Versão mínima Nota
Node.js 18+ Recomendado Node 20 LTS. Verificar: node -v
Sistema Operativo macOS 10.15+, Linux Ubuntu 20.04+ Windows requer WSL2 — Node deve ser instalado dentro do WSL2
VS Code (opcional) 1.85+ Para a extensão oficial Claude Code no marketplace do VS Code

Instalar o Claude Code CLI

# Instalar o Claude Code globalmente via npm
npm install -g @anthropic-ai/claude-code

# Verificar a instalação
claude –version

# Se tiveres erro EACCES (permissões npm), usar:
sudo npm install -g @anthropic-ai/claude-code
# OU configurar npm para instalar sem sudo:
# https://docs.npmjs.com/resolving-eacces-permissions-errors

# Instalar Node 20 se necessário (via nvm — recomendado)
# macOS / Linux:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20

# Windows (WSL2) — instalar dentro do terminal WSL Ubuntu:
sudo apt update && sudo apt install -y curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20

3. Autenticar com API Anthropic (Pay-as-you-go)

A API key dá acesso a todos os modelos Claude no modelo pay-as-you-go — sem subscrição. Novas contas recebem 5 USD de crédito gratuito. Uso diário típico (refactoring, debugging, análise de logs): 10–15 USD/mês com Sonnet.

1
 Criar conta em console.anthropic.com → API Keys → Create Key
2
 Copiar a chave — é mostrada apenas uma vez. Guardar em local seguro.
3
 Definir a API key e lançar o Claude Code. Escolher uma das três opções abaixo:

Opção A — só funciona enquanto o terminal estiver aberto
Escrever os dois comandos seguintes no terminal, um de cada vez, e premir Enter após cada um. Substituir sk-ant-api03-... pela chave copiada no passo anterior:

export ANTHROPIC_API_KEY=sk-ant-api03-…
claude

Quando o terminal for fechado, a chave desaparece e é necessário repetir o processo.

Opção B — configuração permanente (recomendado)
Escrever os três comandos seguintes no terminal, um de cada vez. Substituir sk-ant-api03-... pela chave real. A chave fica guardada e não é necessário repetir em sessões futuras:

# macOS (Zsh) — usar este bloco:
echo ‘export ANTHROPIC_API_KEY=sk-ant-api03-…‘ >> ~/.zshrc
source ~/.zshrc
claude

# Linux / WSL Ubuntu (Bash) — usar este bloco:
echo ‘export ANTHROPIC_API_KEY=sk-ant-api03-…‘ >> ~/.bashrc
source ~/.bashrc
claude

O comando echo ... >> ~/.bashrc guarda a chave no ficheiro de configuração do terminal. O comando source aplica as alterações sem ter de fechar e abrir o terminal. O claude lança o Claude Code já autenticado.

Opção C — via interface gráfica do Claude Code
Escrever claude no terminal e premir Enter. Dentro do Claude Code, escrever /config e seleccionar “Use custom API key”. A chave é pedida e guardada automaticamente no perfil do Claude Code.

# Opção A — variável de sessão (só para este terminal)
export ANTHROPIC_API_KEY=sk-ant-api03-…
claude

# Opção B — variável persistente (adicionar ao ~/.zshrc ou ~/.bashrc)
echo ‘export ANTHROPIC_API_KEY=”sk-ant-api03-…”‘ >> ~/.zshrc
source ~/.zshrc

# Opção C — definir no /config do Claude Code (interactivo)
claude
# Dentro do Claude Code: /config → “Use custom API key”

Modelo Custo por sessão típica Quando usar
claude-haiku-4-5 ~0.05–0.10 USD Refactoring, documentação, tarefas simples, subagentes de exploração
claude-sonnet-4-6 ~0.30–0.80 USD Driver do dia-a-dia — implementação de features, debugging, code review
claude-opus-4-6 ~1.50–4.00 USD Decisões de arquitectura, debugging complexo, análise de segurança, trabalho de longa duração

4. Autenticar com Subscrição Claude Pro / Max

Se já tens uma subscrição Claude Pro (20 USD/mês) ou Max (100–200 USD/mês), o Claude Code está incluído — sem custos adicionais por token. A autenticação é feita via OAuth no browser.

# Lançar o Claude Code — na primeira vez abre o browser para OAuth
claude

# Para ambientes sem browser (CI/CD, servidores remotos):
claude setup-token
# Gera um CLAUDE_CODE_OAUTH_TOKEN para usar em pipelines
export CLAUDE_CODE_OAUTH_TOKEN=o_token_gerado

ℹ Pro vs Max — o que muda para Claude Code

O Pro (20 USD/mês) inclui Claude Code mas com rate limits mais apertados — adequado para uso ocasional. O Max (100 USD/mês) tem limites 5× mais altos e é o padrão recomendado para uso intensivo diário. O Max 20× (200 USD/mês) destina-se a utilização muito pesada ou equipas. Para uso por API key (pay-as-you-go), o custo está tipicamente entre 10–30 USD/mês para uso diário moderado.

5. Ligar a um LLM Local com Ollama

O Claude Code é, no fundo, um cliente que fala com a API Anthropic. Não verifica que há um Claude real do outro lado. Qualquer servidor local que exponha um endpoint compatível com a API Anthropic pode ser usado como backend — incluindo o Ollama. O código nunca sai da máquina.

1
 Instalar o Ollama em ollama.com e descarregar um modelo de coding
2
 Confirmar que o Ollama está a correr e a responder
3
 Definir as variáveis de ambiente e lançar o Claude Code
# Passo 1 — Descarregar modelo de coding via Ollama
ollama pull qwen2.5-coder:14b # recomendado (9 GB, 16 GB RAM)
# Alternativa mais leve (8 GB RAM):
ollama pull qwen2.5-coder:7b

# Passo 2 — Confirmar que o Ollama está a responder
curl http://localhost:11434/api/tags

# Passo 3 — Configurar variáveis e lançar Claude Code
# O Ollama expõe a API Anthropic no endpoint /api/
export ANTHROPIC_BASE_URL=http://localhost:11434
export ANTHROPIC_AUTH_TOKEN=ollama # valor arbitrário — Ollama não verifica
export ANTHROPIC_API_KEY=“”

# Lançar o Claude Code apontando para o modelo local
claude –model qwen2.5-coder:14b

# Para persistir, adicionar ao ~/.zshrc ou ~/.bashrc:
echo ‘export ANTHROPIC_BASE_URL=”http://localhost:11434″‘ >> ~/.zshrc
echo ‘export ANTHROPIC_AUTH_TOKEN=”ollama”‘ >> ~/.zshrc
echo ‘export ANTHROPIC_API_KEY=””‘ >> ~/.zshrc

⚠ Contexto mínimo de 32K tokens — essencial para Claude Code

O Claude Code é muito exigente em contexto — lê ficheiros inteiros e mantém histórico de operações. Configurar o Ollama com pelo menos 32.768 tokens de contexto, idealmente 65.536. Adicionar ao ~/.ollama/models/ um ficheiro Modelfile, ou definir OLLAMA_NUM_CTX=65536 como variável de ambiente antes de lançar o Ollama.

6. Ligar a um LLM Local com LM Studio

O LM Studio serve os modelos num endpoint OpenAI-compatível por defeito em http://localhost:1234. O processo é similar ao Ollama, mas via interface gráfica.

# LM Studio — após instalar o modelo e arrancar o servidor local:
# 1. Abrir o LM Studio, carregar o modelo (ex: Gemma 4 26B A4B)
# 2. Ir a “Local Server” e clicar “Start Server”
# 3. Configurar context window para 65536 no LM Studio

# 4. Configurar as variáveis no terminal
export ANTHROPIC_BASE_URL=http://localhost:1234
export ANTHROPIC_AUTH_TOKEN=lmstudio
export ANTHROPIC_API_KEY=“”

# Lançar com o modelo exacto carregado no LM Studio
claude –model gemma-4-26b-a4b-it

7. Melhores Modelos Locais para Coding em 2026

Modelo Tamanho RAM mínima Nota
qwen2.5-coder:7b 4.7 GB 8 GB Melhor modelo de coding no tier 7B. HumanEval ~76%. Boa entrada.
qwen2.5-coder:14b 9 GB 16 GB Recomendado como driver principal. HumanEval ~85%. Sweet spot.
devstral-small-2 ~15 GB 24–32 GB Mistral coding model. SWE-bench ~68%. Para hardware mais forte.
gemma-4-26b-a4b ~16 GB 24 GB Google MoE — 4B activos por token. Rápido e capaz. Boa opção Mac M4.
qwen2.5-coder:32b 20 GB 32 GB Para hardware topo de gama. Qualidade próxima de Sonnet em tarefas de código.

8. Configurações Iniciais Recomendadas

As configurações do Claude Code vivem em dois locais: ~/.claude/settings.json (global) e .claude/settings.json na raiz do projecto (partilhado com a equipa).

settings.json — configuração de projecto recomendada

// .claude/settings.json — guardar na raiz do projecto e fazer commit
{