Claude Code: guía completa de instalación y uso en local (2026)

¿Qué es Claude Code?

Claude Code es la herramienta de programación agéntica oficial de Anthropic. Vive en tu terminal, lee tu repositorio, ejecuta comandos por ti y edita archivos con un nivel de contexto que ningún autocomplete puede igualar. No es un plugin de IDE ni un chatbot — es un agente autónomo que trabaja dentro de tu codebase real.

La diferencia clave con otras herramientas: Claude Code no solo sugiere código, sino que ejecuta un loop agéntico. Elige herramientas, acumula contexto, corre comandos, lee resultados, y decide los siguientes pasos. Todo dentro de tu terminal, con permisos que tú controlas.

Requisitos del sistema

Requisito	Detalle
macOS	macOS 13.0+ (Apple Silicon o Intel)
Windows	Windows 10 1809+ o Windows Server 2019+ (x64 o ARM64)
Linux	Ubuntu 20.04+, Debian 10+, Alpine 3.19+, Fedora, RHEL
RAM	4 GB mínimo
CPU	x64 o ARM64
Shell	Bash, Zsh, PowerShell o CMD
Red	Conexión a internet (salvo configuración con modelos locales)
Cuenta	Claude Pro, Max, Team, Enterprise o API key de Anthropic Console

Paso 1 — Instalar Claude Code

macOS y Linux (recomendado: instalador nativo)

Abre tu terminal y ejecuta:

curl -fsSL https://claude.ai/install.sh | bash

El instalador descarga el binario, lo coloca en ~/.local/bin y lo añade a tu PATH. Las instalaciones nativas se auto-actualizan.

macOS con Homebrew

# Canal estable (recomendado)
brew install --cask claude-code

# Canal latest (últimas versiones inmediatamente)
brew install --cask claude-code@latest

Las instalaciones de Homebrew no se auto-actualizan. Ejecuta brew upgrade claude-code periódicamente.

Windows — PowerShell (nativo)

irm https://claude.ai/install.ps1 | iex

Se recomienda instalar Git for Windows para que Claude Code pueda usar la herramienta Bash. Sin Git, usa PowerShell como shell tool.

Windows — CMD

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows — WinGet

winget install Anthropic.ClaudeCode

Windows — WSL (recomendado para desarrollo)

Si usas WSL2, abre tu distribución de WSL y ejecuta el instalador de Linux:

curl -fsSL https://claude.ai/install.sh | bash

Instalas y lanzas claude dentro del terminal de WSL, no desde PowerShell.

Linux con gestores de paquetes

# Debian/Ubuntu
sudo apt install claude-code

# Fedora/RHEL
sudo dnf install claude-code

# Alpine
sudo apk add claude-code

Verificar la instalación

claude --version

Paso 2 — Autenticarse

Después de instalar, ejecuta claude en tu terminal. En el primer uso, se te pedirá iniciar sesión:

claude

Se abrirá una ventana del navegador para que inicies sesión con tu cuenta de Anthropic (Claude Pro, Max, Team o Enterprise). Una vez autenticado, el CLI recibe un token de sesión y no necesitas volver a loguearte en usos posteriores.

Para cambiar de cuenta o re-autenticarse más tarde, dentro de una sesión escribe:

/login

Autenticación con API key

Si prefieres usar una API key de Anthropic Console en lugar de una suscripción:

export ANTHROPIC_API_KEY="sk-ant-tu-api-key-aqui"

Añade esta línea a tu ~/.zshrc o ~/.bashrc para que persista entre sesiones.

Paso 3 — Tu primera sesión

Abre un terminal en el directorio de tu proyecto y lanza Claude Code:

cd /path/to/tu/proyecto
claude

Verás el prompt de Claude Code con la versión, modelo actual y directorio de trabajo. La primera vez que abras un proyecto, Claude pedirá permiso para leer y editar archivos en ese directorio. Aprueba el permiso y estarás listo.

Comandos esenciales

Comando	Qué hace
/help	Lista todos los comandos disponibles
/init	Crea un archivo CLAUDE.md con convenciones del proyecto
/model	Cambia el modelo activo (Opus, Sonnet, Haiku)
/effort	Cambia el nivel de razonamiento (low, medium, high, xhigh, max)
/context	Muestra el uso de contexto actual
/compact	Condensa la sesión para preservar contexto utilizable
/review	Revisión general del código
/security-review	Revisión de seguridad del código
/mcp	Gestiona servidores MCP conectados
/agents	Gestiona subagentes
/login	Re-autenticarse o cambiar de cuenta
/resume	Continuar una conversación anterior

Paso 4 — CLAUDE.md: la memoria del proyecto

El archivo CLAUDE.md es la constitución del agente para tu repositorio. Claude lo lee en cada sesión para anclar convenciones, comandos y reglas del proyecto. Crea uno con:

/init

O manualmente, crea un archivo CLAUDE.md en la raíz de tu proyecto:

# Proyecto: mi-app

## Build
npm run build

## Test
npm test

## Convenciones
- TypeScript strict mode
- No default exports
- Commit format: feat/fix/chore(scope): descripción
- Usar pnpm, nunca npm ni yarn

Paso 5 — Configuración avanzada

Archivo settings.json

Claude Code lee su configuración desde ~/.claude/settings.json (global) o .claude/settings.local.json (por proyecto). En Windows: C:\Users\tu-usuario\.claude\settings.json.

Estructura de settings.json

{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000"
  },
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Bash(npm run build)",
      "Bash(npm test)",
      "Bash(git status)",
      "Bash(git diff*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push*)"
    ]
  }
}

Modos de permiso

Modo	Comportamiento
Default	Pregunta antes de cada escritura de archivo y comando de shell
Plan Mode	Explora y propone sin ejecutar. Ideal para scoping antes de editar
Auto Mode	Un clasificador Sonnet revisa cada acción. Las seguras proceden; las riesgosas se bloquean

Paso 6 — Usar Claude Code con modelos personalizados

Una de las características más potentes de Claude Code es que no estás limitado a los modelos de Anthropic. Puedes apuntarlo a cualquier endpoint compatible con la API de Anthropic, incluyendo OpenRouter, GLM Coding Plan de Z.ai, o modelos locales.

Opción A: OpenRouter (acceso a 100+ modelos)

OpenRouter te permite usar cualquier modelo (GLM-5.2, DeepSeek, Qwen, Llama, etc.) dentro de Claude Code sin proxy local:

# Añadir a ~/.zshrc o ~/.bashrc
export OPENROUTER_API_KEY="sk-or-tu-key"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""
export ANTHROPIC_DEFAULT_SONNET_MODEL="z-ai/glm-5.2"
export ANTHROPIC_DEFAULT_OPUS_MODEL="z-ai/glm-5.2"

O en .claude/settings.local.json para configuración por proyecto:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-tu-key",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "z-ai/glm-5.2"
  }
}

Opción B: GLM Coding Plan de Z.ai

Si tienes una suscripción al GLM Coding Plan, puedes usar GLM-5.2 dentro de Claude Code con el endpoint compatible con Anthropic de Z.ai:

{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]"
  }
}

El endpoint de Z.ai se configura automáticamente cuando usas el Coding Tool Helper de Z.ai. Esto te da 1 millón de tokens de contexto y el modelo open source más cercano a Claude Opus, a una fracción del coste.

Opción C: Modelos locales con LM Studio

Si tienes LM Studio corriendo localmente con su servidor API en localhost:1234:

export ANTHROPIC_BASE_URL="http://localhost:1234"
export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen2.5-coder-14b-instruct"
export ANTHROPIC_DEFAULT_OPUS_MODEL="qwen2.5-coder-14b-instruct"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="llama-3.3-8b-instruct"

Esto convierte a Claude Code en un agente 100% local y offline. La calidad dependerá del modelo que cargues — modelos como Qwen2.5-Coder-14B son competentes para tareas rutinarias, pero no igualan a Claude Opus en refactors complejos.

Opción D: Modelos locales con Ollama

Si prefieres Ollama como servidor de modelos locales, necesitas un proxy que traduzca la API de Anthropic a la API de Ollama (Ollama expone una API OpenAI-compatible, no Anthropic-compatible). Herramientas como claude-code-proxy o llama-proxy hacen este puente:

# Instalar el proxy
npm install -g claude-code-proxy

# Configurar
export ANTHROPIC_BASE_URL="http://localhost:8082"
export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen2.5-coder:14b"

Variables de entorno para modelos

Variable	Controla
ANTHROPIC_BASE_URL	Endpoint al que se envían las requests
ANTHROPIC_AUTH_TOKEN	Token de autenticación (OpenRouter, Z.ai, etc.)
ANTHROPIC_API_KEY	API key de Anthropic (dejar vacío con terceros)
ANTHROPIC_DEFAULT_OPUS_MODEL	Modelo para tareas tipo Opus (razonamiento complejo)
ANTHROPIC_DEFAULT_SONNET_MODEL	Modelo para tareas tipo Sonnet (programación general)
ANTHROPIC_DEFAULT_HAIKU_MODEL	Modelo para tareas tipo Haiku (completados rápidos)
CLAUDE_CODE_SUBAGENT_MODEL	Modelo para todos los subagentes

Paso 7 — Subagentes y MCP

Subagentes

Los subagentes son instancias especializadas con su propia ventana de contexto. El trabajo verbose se mantiene aislado, así tu conversación principal se mantiene enfocada. Se definen en .claude/agents/:

---
name: explorer
description: Exploración read-only del codebase
tools: Read, Grep, Glob
---
Mapea la estructura del repositorio y resume los entry points.

Invócalos con @explorer durante una sesión.

MCP (Model Context Protocol)

MCP conecta Claude Code a herramientas externas: GitHub, bases de datos, filesystem, browsers, APIs. El servidor maneja la integración; Claude razona sobre qué hacer.

# Añadir un servidor MCP de filesystem
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

# Listar servidores MCP
claude mcp list

# Query headless usando MCP
claude -p "Lista los archivos más grandes bajo src y explica por qué" --output-format json

Paso 8 — Hooks y automatización

Los hooks son scripts determinísticos que se ejecutan en puntos específicos del ciclo de vida. PreToolUse es el checkpoint de seguridad principal antes de que cualquier herramienta se ejecute:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "scripts/guard.sh"
          }
        ]
      }
    ]
  }
}

El script guard.sh recibe el comando que Claude quiere ejecutar y puede bloquearlo si coincide con un patrón peligroso.

Paso 9 — Modo headless y CI

Claude Code puede correr como proceso one-shot sin TTY, ideal para CI/CD:

# Query one-shot
claude -p "Revisa los cambios staged y sugiere mejoras"

# Con input pipeado
cat logs.txt | claude -p "Analiza estos logs de error"

# Output en JSON
claude -p "Lista las funciones exportadas del archivo src/index.ts" --output-format json

GitHub Action

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Con OpenRouter en CI:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.OPENROUTER_API_KEY }}
  env:
    ANTHROPIC_BASE_URL: https://openrouter.ai/api

Paso 10 — Checkpoints y seguridad

Claude Code hace snapshots automáticos del estado antes de hacer cambios. Si algo se rompe, presiona Escape dos veces para rebobinar al último checkpoint.

Sandboxing

La herramienta Bash sandboxed aplica aislamiento a nivel OS de filesystem y red. Los comandos corren sin prompts dentro de los límites que definas:

{
  "sandbox": {
    "bash": {
      "allowWrite": ["./src", "./tests"],
      "allowNetwork": false
    }
  }
}

App de escritorio y extensión VS Code

Además del CLI, Claude Code está disponible como:

• App de escritorio: Descarga desde claude.ai para macOS (Intel y Apple Silicon), Windows (x64 y ARM64) y Linux. Permite usar Claude Code sin terminal
• Extensión VS Code: Busca "Claude Code" en el Extensions view (Cmd+Shift+X / Ctrl+Shift+X). Abre con Command Palette → "Claude Code" → Open in New Tab

Flujo de trabajo recomendado

1. Onboarding: cd proyecto && claude → /init para crear CLAUDE.md
2. Exploración: Pide a Claude que mapee el repo. Usa un subagent @explorer read-only
3. Planificación: Activa Plan Mode para scoping antes de editar
4. Ejecución: Cambia a modo default o Auto Mode. Claude edita archivos y corre comandos con tu aprobación
5. Review: /review para feedback general, /security-review para vulnerabilidades
6. Compactación: /compact cuando el contexto se llene en sesiones largas
7. Checkpoint: Escape×2 si algo sale mal para rebobinar

Integración con el ecosistema de IA local

Claude Code no vive aislado. Se integra con las herramientas que ya cubrimos en Blogia:

Con LM Studio

LM Studio sirve como backend local para Claude Code. Inicia el servidor API en LM Studio (localhost:1234), configura ANTHROPIC_BASE_URL y tendrás un agente de programación 100% offline con cualquier modelo GGUF o MLX.

Con Ollama

Ollama es la alternativa más ligera para servir modelos locales. Con un proxy que traduzca la API de Anthropic a OpenAI-compatible, puedes usar Ollama como backend de Claude Code sin tocar la nube.

Con GLM-5.2

GLM-5.2 es el modelo open source más cercano a Claude Opus. Con el GLM Coding Plan de Z.ai, puedes usar GLM-5.2 dentro de Claude Code con 1M tokens de contexto, a un coste 5.7× menor que Opus. La configuración es nativa vía el endpoint compatible con Anthropic de Z.ai.

Con Hermes Agent y OpenClaw

Tanto Hermes Agent como OpenClaw pueden configurarse para usar Claude Code como herramienta de programación dentro de sus flujos agénticos. Claude Code expone su loop vía el Agent SDK (query()), permitiendo orquestación programática.

Con Supabase self-hosted

Si tienes Supabase self-hosted en tu VPS, puedes combinarlo con Claude Code para desarrollo full-stack: Claude Code puede conectarse a tu base de datos Supabase vía MCP server, leer esquemas, generar migrations y escribir código contra tu backend privado.

Solución de problemas

"claude" no es reconocido (Windows)

El directorio de instalación no está en tu PATH. Abre una nueva ventana de PowerShell e intenta de nuevo. Si persiste, añade %USERPROFILE%\.local\bin a tu PATH manualmente.

Error de autenticación con OpenRouter

Verifica que ANTHROPIC_API_KEY sea un string vacío (""), no unset. Si tienes una sesión OAuth de Anthropic cacheada, ejecuta /login y selecciona la opción de API key.

Modelo no aparece en /model

Si usas un modelo personalizado que no aparece en el picker, usa ANTHROPIC_CUSTOM_MODEL_OPTION para añadirlo:

export ANTHROPIC_CUSTOM_MODEL_OPTION="glm-5.2[1m]"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="GLM-5.2 1M"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="GLM-5.2 con 1M contexto"

Contexto lleno

Usa /compact para condensar la sesión. Verifica el uso con /context. Para sesiones muy largas, considera dividir el trabajo en subagentes con contextos aislados.

Alpine Linux: error de librería

En Alpine y distros musl-based, instala dependencias: apk add libgcc libstdc++ ripgrep y setea USE_BUILTIN_RIPGREP=0.

Conclusión

Claude Code es, a mediados de 2026, la herramienta de programación agéntica más capaz disponible. Su mayor fortaleza no es solo la calidad del modelo subyacente, sino el ecosistema completo que lo rodea: CLAUDE.md, subagentes, hooks, MCP, plugins, checkpoints, sandboxing, y la capacidad de usar cualquier modelo como backend.

Y gracias a la compatibilidad con endpoints de terceros, no estás encerrado en Anthropic. Puedes usar GLM-5.2 para ahorrar coste, modelos locales vía LM Studio o Ollama para privacidad total, o el modelo frontier de Anthropic cuando necesites la máxima capacidad. Claude Code es el agente; tú eliges el cerebro.

Para un stack completo de desarrollo con IA, combina Claude Code con Hermes Agent para orquestación, OpenClaw para tu asistente IA, y Supabase self-hosted para el backend. Todo open source, todo bajo tu control.