Instalación y configuración de Claude Code para Ollama, llama.cpp y precios

Codificación agentica, ahora con backends de modelos locales.

Índice

Claude Code no es autocompletado con mejor marketing. Es una herramienta de codificación basada en agentes: lee tu base de código, edita archivos, ejecuta comandos e integra tus herramientas de desarrollo.

Esa diferencia importa porque la unidad de trabajo deja de ser “una línea de código” y pasa a ser “una tarea con un estado final”.

Anthropic enmarca la distinción con claridad: la finalización de código sugiere la siguiente línea mientras escribes, mientras que Claude Code opera a nivel de proyecto, planifica a través de múltiples archivos, ejecuta cambios, ejecuta pruebas e itera sobre los fallos. En la práctica, esto lo acerca más a un ingeniero junior nativo de terminal que puede realizar tareas rutinarias rápidamente, pero que aún necesita supervisión.

Esa tensión entre velocidad y supervisión es gran parte de lo que la gente agrupa bajo el término “vibe coding”; ¿Qué es el Vibe Coding? desglosa el término, su origen y cómo se ven la eficiencia y el riesgo en la práctica.

laptop-homeresver-claude-code-coffee-books

Un detalle fácil de pasar por alto al leer la documentación rápidamente: el CLI de Terminal (y la interfaz de VS Code) se puede configurar para usar proveedores de terceros. Ahí es donde entran Ollama y llama.cpp.

Una vez que Claude Code apunta a un endpoint HTTP local, las compensaciones de tiempo de ejecución, hardware y alojamiento quedan fuera del cliente; esta comparación de alojamiento de LLM en 2026 alinea Ollama, pilas de inferencia dedicadas y opciones en la nube en un solo lugar.

Para ver cómo encaja Claude Code junto a otros flujos de trabajo de codificación y entrega asistidos por IA, esta guía de herramientas para desarrolladores de IA recopila asistentes al estilo Copilot, automatización y patrones de editor en un solo lugar.

Para una encuesta herramienta por herramienta de asistentes de codificación en la misma categoría, Comparativa de Asistentes de Codificación por IA recorre Cursor, Copilot, Cline y el resto a un nivel superior que esta guía de instalación.

Instalación y inicio rápido de Claude Code

Opciones de instalación y lo que implican

Hay varias rutas de instalación y no son iguales:

  • Los scripts de instalación nativos son la opción “siempre actualizada” porque se actualizan automáticamente.
  • Homebrew y WinGet son la opción de “cambio controlado” porque debes actualizar explícitamente.

Comandos de instalación (inicio rápido oficial):

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

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

Luego, inicia una sesión interactiva desde dentro de una carpeta de proyecto:

cd /path/to/your/project
claude

Inicio de sesión y tipos de cuenta

Claude Code necesita una cuenta para ejecutarse en el modo de primera parte. El flujo de inicio rápido admite inicios de sesión mediante una suscripción a Claude (Pro, Max, Team, Enterprise), una cuenta de Consola (créditos de API) o proveedores en la nube compatibles. Una nota operativa útil: en el primer inicio de sesión en la Consola, se crea un espacio de trabajo “Claude Code” para el seguimiento centralizado de costos.

Configuración de Claude Code: settings.json y variables de entorno

Si Claude Code parece mágico cuando funciona, a menudo parece “misterioso” cuando no. La cura es entender su capas de configuración y las pocas variables de entorno que realmente importan.

Archivos de configuración y precedencia

La configuración de Claude Code es jerárquica, con tres archivos orientados al desarrollador:

  • Ámbito de usuario, aplica en todas partes: ~/.claude/settings.json
  • Ámbito de proyecto, compartido en un repositorio: .claude/settings.json
  • Ámbito local, sobrescrituras por máquina: .claude/settings.local.json (ignorado por git)

La precedencia es (de mayor a menor): política gestionada, banderas de CLI, local, proyecto, usuario. Ese orden explica varios momentos de “¿por qué se ignora mi configuración?”.

Puedes gestionar la configuración de forma interactiva mediante el comando /config, que abre una interfaz de configuración dentro del REPL.

Variables de entorno que controlan el enrutamiento del proveedor

Claude Code puede ser dirigido en tiempo de ejecución por variables de entorno. Dos rarezas de comportamiento vale la pena tratar como restricciones de diseño:

  1. Si ANTHROPIC_API_KEY está establecida, Claude Code usará la clave en lugar de una suscripción a Claude, incluso si has iniciado sesión. En el modo de impresión (-p), la clave siempre se usa cuando está presente.

  2. Si ANTHROPIC_BASE_URL apunta a un host que no es de primera parte (un proxy, gateway o servidor local), algunas características son intencionalmente conservadoras. Por ejemplo, la búsqueda de herramientas MCP está desactivada por defecto a menos que la reactives explícitamente.

Un patrón mínimo de “usar un gateway” se ve así:

export ANTHROPIC_BASE_URL=https://your-gateway.example
export ANTHROPIC_API_KEY=sk-your-key

Nota sobre el gateway: Claude Code espera ciertos formatos de API. Para el formato Anthropic Messages, el gateway debe exponer /v1/messages y /v1/messages/count_tokens y debe reenviar los encabezados anthropic-beta y anthropic-version. Si un gateway rechaza esos encabezados, hay un control dedicado para eliminar betas experimentales.

Selección de modelo en Claude Code cuando no usas Anthropic directamente

Claude Code tiene un concepto de alias (opus, sonnet, haiku) y también soporta fijar identificadores de modelo específicos. También hay una lista blanca que puede restringir lo que los usuarios pueden seleccionar en el selector de modelos, incluso cuando se enruta a través de proveedores de terceros.

Un patrón pragmático es establecer un modelo inicial y restringir el selector, luego fijar a qué se resuelve “default” mediante el entorno:

{
  "model": "claude-sonnet-4-5",
  "availableModels": ["claude-sonnet-4-5", "haiku"],
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5"
  }
}

Ejecución de LLM autoalojados vía Ollama

Ollama es actualmente la forma de menor fricción para hacer que Claude Code funcione con modelos que no son de Anthropic, porque expone una API compatible con Anthropic para que Claude Code se comunique con ella.

Configuración rápida con ollama launch

Si tienes Ollama instalado y en ejecución, la vía rápida es:

ollama launch claude

O especifica un modelo al iniciar:

ollama launch claude --model glm-4.7-flash

Configuración manual con variables de entorno explícitas

La documentación de integración de Ollama detalla un cableado manual simple donde Claude Code habla con Ollama a través del endpoint de API compatible con Anthropic:

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434

claude --model qwen3.5

Este patrón es opinado de una manera útil: trata el “enrutamiento de proveedor” como una preocupación de entorno, no algo en lo que haces clic en una GUI.

Verificación de realidad de la ventana de contexto

La codificación basada en agentes es voraz de contexto. Ollama lo señala de forma directa: Claude Code requiere una ventana de contexto grande y recomienda al menos 64k tokens. Si tu modelo local se detiene en 8k o 16k, Claude Code seguirá funcionando, pero la promesa de “nivel de proyecto” se vuelve frágil.

Para un comportamiento de modelo local práctico en una configuración de agente de terminal similar (Ollama y llama.cpp, tareas de codificación y notas de fallos francas), Mejores LLM para OpenCode - Probados Localmente es un contrachequeo útil cuando estás haciendo una preselección de etiquetas GGUF u Ollama para Claude Code.

Ejecución de LLM autoalojados vía llama.cpp

llama.cpp es atractivo por la razón opuesta: no intenta ser una plataforma. Es un servidor rápido y ligero que puede exponer tanto rutas compatibles con OpenAI como una ruta de API compatible con Anthropic Messages.

Para rutas de instalación, comportamiento de llama-cli y llama-server más allá de los fragmentos a continuación, Inicio rápido de llama.cpp con CLI y Servidor es la referencia de extremo a extremo.

Qué ejecutar en el lado del servidor

El servidor HTTP de llama.cpp (llama-server) soporta una API de mensajes compatible con Anthropic en POST /v1/messages, con transmisión mediante SSE. También ofrece count_tokens en /v1/messages/count_tokens.

Dos detalles importan para Claude Code:

  • El servidor no hace afirmaciones fuertes de compatibilidad total con la especificación de API de Anthropic, pero afirma que funciona lo suficientemente bien para muchas aplicaciones.
  • El uso de herramientas requiere iniciar llama-server con la bandera –jinja. Si te la pierdes, Claude Code se comportará como si de repente olvidara cómo ser un agente.

Una ejecución local mínima se ve así:

# Compilar o descargar llama-server, luego ejecutar con un modelo GGUF
./llama-server -m /models/your-model.gguf --jinja --host 127.0.0.1 --port 8080

Si quieres un límite de autenticación estricto, llama-server se puede configurar con una clave de API:

./llama-server -m /models/your-model.gguf --jinja --api-key my-local-key --host 127.0.0.1 --port 8080

Apunta Claude Code a llama-server

Con el servidor en ejecución, tu lado de Claude Code es principalmente una sobrescritura de URL base:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8080
export ANTHROPIC_API_KEY=my-local-key   # solo si habilitaste --api-key en llama-server

claude --model your-model-alias

Si no estableces una clave de API o un token de autenticación, Claude Code puede intentar volver al inicio de sesión por suscripción, que es la fuente de muchas quejas de “¿por qué abre un navegador?”.

Controles de salud y triaje de primer fallo

llama-server expone un endpoint de salud simple que devuelve “cargando modelo” hasta que el modelo esté listo, y “ok” cuando sea usable. Cuando Claude Code parece colgarse en la primera solicitud, verificar /health es una forma rápida de distinguir entre “bug de configuración del cliente” y “servidor aún cargando”.

Modelos de precios y costos

El precio de Claude Code tiene menos que ver con “comprar un CLI” y más con “qué carril de facturación respalda los tokens”.

Los planes de suscripción incluyen Claude Code

Anthropic incluye Claude Code en los niveles de suscripción de pago de Claude. A partir de abril de 2026, la lista de precios publicada incluye:

  • Pro a $17 por mes con descuento anual ($200 facturados por adelantado), o $20 facturados mensualmente, e incluye Claude Code.
  • Planes Max que comienzan en $100 por mes.
  • Planes Team con precios por asiento, con un asiento estándar a $20 por asiento por mes facturado anualmente ($25 mensual) y un asiento premium a $100 por asiento por mes facturado anualmente ($125 mensual).

Precios por token de API

Si usas Claude Code mediante facturación de API, los costos siguen las tarifas por token. Anthropic publica precios por millón de tokens (MTok) para modelos como:

  • Haiku 4.5 a $1/MTok de entrada y $5/MTok de salida.
  • Sonnet 4.5 a $3/MTok de entrada y $15/MTok de salida.
  • Opus 4.5 a $5/MTok de entrada y $25/MTok de salida.

Controles de costos en la CLI

El modo de impresión (-p) soporta límites de presupuesto directos como –max-budget-usd, que es útil cuando estás scripteando tareas y quieres un gasto predecible.

Dentro de sesiones interactivas, /cost muestra estadísticas de uso de tokens.

Los backends locales cambian la factura, no la física

Enrutar Claude Code a Ollama o llama.cpp puede eliminar las facturas de API por token, pero no hace que el trabajo sea gratuito. Estás intercambiando costos en la nube por cómputo local, memoria y “alguien es dueño del tiempo de actividad”. Para algunos equipos, ese intercambio es todo el punto.

Flujo de trabajo típico: de plan a PR

Mi sesgo es que Claude Code es más fuerte cuando lo tratas como un motor de flujo de trabajo, no como un chatbot. Las herramientas sugieren esto.

Comienza con el modelo de permisos, no con el prompt

Claude Code está diseñado con control de permisos. La documentación describe un modelo escalonado: las operaciones de solo lectura, como lectura de archivos y grep, están permitidas, mientras que los comandos bash y las modificaciones de archivos necesitan aprobación.

Los modos de permiso existen para gestionar la fricción. En la CLI puedes alternar modos con Shift+Tab (default -> acceptEdits -> plan). El modo Plan lee y propone cambios pero no edita. El modo acceptEdits permite que Claude Code cree y edite archivos en tu directorio de trabajo sin preguntar, aunque aún pide confirmación para comandos con efectos secundarios fuera de su lista segura.

El modo Auto es una opción más nueva que reduce los prompts delegando aprobaciones a un clasificador, posicionado como un camino intermedio más seguro entre prompts constantes y la desactivación total de prompts. Requiere una versión mínima de Claude Code y requisitos específicos de plan y modelo.

Usa comandos integrados para mantener las sesiones honestas

Unos pocos comandos convierten a Claude Code de “asistente” a “herramienta”:

  • /init genera una guía de proyecto CLAUDE.md, que es una forma ligera de alimentar un contexto consistente.
  • /diff ofrece una vista interactiva de los cambios, incluyendo diferencias por turno.
  • /rewind te permite retroceder la conversación y/o el código a un punto anterior, usando puntos de control.
  • /debug habilita la registro de depuración en medio de la sesión.
  • /doctor diagnostica y verifica tu instalación y configuración.

Estos no son trucos; son los rieles de seguridad en los que apoyas cuando un agente edita más de lo esperado.

Cuando ir a modo no interactivo

Para tareas de una sola vez (explicar, resumir, generar un plan de parche), el modo de impresión es una buena opción:

claude -p "Resume la arquitectura del repositorio y lista los módulos más arriesgados"

Se cierra después de la respuesta, lo que funciona bien en scripts y CI.

Lista de verificación de solución de problemas

La mayoría de los problemas de Claude Code son problemas de configuración disfrazados. Aquí hay una lista de verificación que mapea síntomas comunes al mecanismo subyacente.

Claude Code sigue pidiendo iniciar sesión mientras usas un servidor local

Esto típicamente significa que Claude Code todavía intenta usar la autenticación de suscripción de primera parte. Asegúrate de establecer un modo de autenticación explícito para el proxy:

  • Establece ANTHROPIC_API_KEY para gateways que esperan X-Api-Key.
  • O establece ANTHROPIC_AUTH_TOKEN para gateways que usan Authorization Bearer.

Recuerda que ANTHROPIC_API_KEY sobrescribe el uso de suscripción incluso si has iniciado sesión, y en modo interactivo puede que necesites aprobar esa sobrescritura una vez.

El gateway da error en los encabezados anthropic-beta

Algunos gateways rechazan encabezados desconocidos o campos beta. Hay una variable de entorno diseñada para este modo de fallo exacto:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

La documentación del gateway de LLM también señala que puede necesitar esto al usar el formato Anthropic Messages con Bedrock o Vertex.

Las llamadas a herramientas no funcionan en llama.cpp

Verifica doblemente las banderas del servidor. llama-server documenta que el uso de herramientas requiere la bandera –jinja. Sin ella, el servidor puede responder, pero el bucle del agente se degradará.

Los prompts de permisos interrumpen cada comando

Eso puede ser normal, dependiendo del modo y las reglas de permiso. Las opciones incluyen:

  • Cambiar temporalmente a acceptEdits (las ediciones de archivos fluyen más rápido).
  • Escribir reglas explícitas de permisivo para comandos bash conocidos como seguros en settings.json.
  • Usar /sandbox para aislar la herramienta bash mientras reduces los prompts.
  • Evaluar el modo auto si tu plan y versión lo soportan, como un punto medio.

Algo se siente mal y necesitas observabilidad

Usa los integrados:

  • /doctor para validar la instalación y la configuración.
  • /debug para comenzar a capturar registros desde ese punto en adelante.
  • Si estás en modo de impresión, considera un presupuesto máximo ajustado y giros máximos para mantener los experimentos acotados.