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

Programación con agentes, ahora con backends de modelos locales.

Índice

Claude Code no es autocompletado con mejor marketing. Es una herramienta de codificación agéntica: lee tu base de código, edita archivos, ejecuta comandos y se integra con 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 claramente: 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 hace más parecido a un ingeniero junior nativo de terminal que puede realizar tareas rutinarias rápidamente, pero que aún necesita revisión.

Esta tensión entre velocidad y supervisión es gran parte de lo que la gente agrupa bajo el término “vibe coding” (codificación por ambiente/vibración); ¿Qué es el Vibe Coding? desglosa el término, de dónde proviene y cómo se ven la eficiencia y el riesgo en la práctica.

laptop-homeresver-claude-code-coffee-books

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

Una vez que Claude Code está dirigido a un punto final HTTP local, las compensaciones entre el runtime, el hardware y el alojamiento quedan fuera del cliente; esta comparación del 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 sobre herramientas de desarrollo con IA reúne asistentes 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, Comparación de Asistentes de Codificación IA recorre Cursor, Copilot, Cline y el resto a un nivel más alto que esta guía de instalación.

Instalación y inicio rápido de Claude Code

Opciones de instalación y lo que implican

Existen varias vías de instalación, y no son iguales:

  • Los scripts de instalación nativa son la opción “siempre actualizada” porque se actualizan automáticamente.
  • Homebrew y WinGet son la opción de “cambio controlado” porque tú actualizas 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 (first-party). El flujo de inicio rápido soporta inicios de sesión mediante una suscripción a Claude (Pro, Max, Team, Enterprise), una cuenta de Console (créditos de API) o proveedores de nube soportados. Una nota operativa útil: en el primer inicio de sesión en Console, 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 visibles para el desarrollador:

  • Ámbito de usuario, se 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 interactivamente 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 peculiaridades de comportamiento merecen ser tratadas como limitaciones de diseño:

  1. Si ANTHROPIC_API_KEY está establecida, Claude Code usará la clave en lugar de una suscripción a Claude incluso cuando hayas 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, pasarela o servidor local), algunas características son intencionalmente conservadoras. Por ejemplo, la búsqueda de herramientas MCP está deshabilitada por defecto a menos que la reactives explícitamente.

Para el límite específico de suscripción ahora impuesto en pilas de agentes de terceros, esta actualización de política de Anthropic para flujos de trabajo de OpenClaw explica por qué se requiere el uso respaldado por API.

Un patrón mínimo de “usar una pasarela” se ve así:

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

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

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

Claude Code tiene un concepto de alias (opus, sonnet, haiku) y también soporta fijar IDs de modelos específicos. También hay una lista de permitidos que puede restringir qué pueden seleccionar los usuarios 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 lo que “default” resuelve vía env:

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

Ejecutar LLMs autoalojados vía Ollama

Ollama es actualmente la forma de menor fricción para hacer que Claude Code se ejecute en modelos no 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, el camino rápido 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 integración de Ollama documenta un cableado manual simple donde Claude Code se comunica con Ollama a través del punto final 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 del proveedor” como una preocupación de entorno, no algo que hagas clic en una GUI.

Verificación de la realidad de la ventana de contexto

La codificación agéntica es hambrienta de contexto. Ollama lo señala de manera directa: Claude Code requiere una ventana de contexto grande y recomienda al menos 64k tokens. Si tu modelo local se limita a 8k o 16k, Claude Code aún se ejecutará, pero la promesa de “nivel de proyecto” se vuelve frágil.

Para un comportamiento práctico de modelos locales en una configuración similar de agente terminal (Ollama y llama.cpp, tareas de codificación y notas de fallo francas), Mejores LLMs para OpenCode - Probados Localmente es un punto de comprobación útil cuando estás haciendo una lista corta de etiquetas GGUF o Ollama para Claude Code.

Ejecutar LLMs autoalojados vía llama.cpp

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

Para las vías de instalación, llama-cli, y el comportamiento de llama-server más allá de los fragmentos a continuación, Inicio rápido de llama.cpp con CLI y Servidor es la referencia completa.

Qué ejecutar en el lado del servidor

El servidor HTTP de llama.cpp (llama-server) soporta una API Anthropic-compatible Messages en POST /v1/messages, con streaming vía SSE. También ofrece count_tokens en /v1/messages/count_tokens.

Dos detalles importan para Claude Code:

  • El servidor explícitamente no hace afirmaciones fuertes de compatibilidad completa con la especificación de la 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 saltas esto, Claude Code se comportará como si de repente hubiera olvidado cómo ser un agente.

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

# Construye o descarga llama-server, luego ejecuta con un modelo GGUF
./llama-server -m /models/your-model.gguf --jinja --host 127.0.0.1 --port 8080

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

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

Dirige Claude Code a llama-server

Con el servidor en ejecución, tu lado de Claude Code es principalmente una sobrescritura de la 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 API o token de autenticación, Claude Code puede intentar volver a la suscripción de inicio de sesión, que es la fuente de muchas quejas de “por qué se abre un navegador”.

Comprobaciones de salud y triaje de primeros fallos

llama-server expone un punto final de salud simple que devuelve “loading model” (cargando modelo) hasta que el modelo esté listo, y “ok” (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”.

Precios y modelo de costos

El precio de Claude Code se trata menos de “comprar una CLI” y más de “qué vía de facturación respalda los tokens”.

Los planes de suscripción incluyen Claude Code

Anthropic incluye Claude Code en los niveles de suscripción pagados de Claude. A partir de abril de 2026, los precios publicados listan:

  • Pro a $17 por mes con un descuento anual ($200 facturado por adelantado), o $20 facturado mensualmente, e incluye Claude Code.
  • Planes Max comenzando en $100 por mes.
  • Planes Team con precio 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 de tokens de API

Si usas Claude Code mediante facturación por 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 directos de presupuesto como –max-budget-usd, lo cual es útil cuando estás escribiendo scripts de tareas y quieres un gasto predecible.

Dentro de las 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 gratis. Estás intercambiando costos en la nube por computación local, memoria y “alguien se encarga de la disponibilidad”. Para algunos equipos, esa compensación es todo el punto.

Flujo de trabajo típico: del plan al 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 puertas de permisos. La documentación describe un modelo escalonado: las operaciones de solo lectura, como lecturas de archivos y grep, están permitidas, mientras que los comandos bash y las modificaciones de archivos necesitan aprobación.

Los modos de permisos 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 pedir confirmación, mientras 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 las aprobaciones a un clasificador, posicionado como un camino medio más seguro entre prompts constantes y deshabilitar los prompts por completo. 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 transforman Claude Code de “asistente” a “herramienta”:

  • /init genera una guía de proyecto CLAUDE.md, que es una forma ligera de alimentar contexto consistente. Para libros de jugabilidad reutilizables y flujos de trabajo repetibles que se sitúan por encima de CLAUDE.md, Habilidades de Claude para desarrolladores cubre el diseño de SKILL.md, compatibilidad con IDE, ajuste de disparadores y pruebas.
  • /diff da una vista interactiva de los cambios, incluyendo diffs por turno.
  • /rewind te permite rebobinar la conversación y/o el código a un punto anterior, usando puntos de control.
  • /debug habilita el 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 te apoyas cuando un agente edita más de lo que esperabas.

Cuándo ir no interactivo

Para tareas de un solo disparo (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 riesgosos"

Sale después de la respuesta, lo cual 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 usa un servidor local

Esto generalmente significa que Claude Code aún está intentando 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 pasarelas que esperan X-Api-Key.
  • O establece ANTHROPIC_AUTH_TOKEN para pasarelas que usan Authorization Bearer.

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

La pasarela da error en los encabezados anthropic-beta

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

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

La documentación de la pasarela LLM también nota que puede necesitar esto cuando usas el formato Anthropic Messages con Bedrock o Vertex.

La llamada de herramientas no funciona en llama.cpp

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

Los prompts de permisos están interrumpiendo cada comando

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

  • Cambiar a acceptEdits temporalmente (las ediciones de archivos fluyen más rápido).
  • Escribir reglas de permiso explícitas 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 término medio.

Algo se siente mal y necesitas observabilidad

Usa las funciones integradas:

  • /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.

La posición de Claude Code como herramienta protegida de primera parte de Anthropic se volvió estratégicamente significativa en abril de 2026, cuando Anthropic bloqueó el acceso a suscripciones de Claude para marcos de trabajo de agentes de terceros mientras mantenía Claude Code en la facturación de suscripción. La línea de tiempo del auge y caída de OpenClaw cubre ese evento y lo que revela sobre el enfoque de Anthropic hacia las herramientas de primera parte versus de terceros.

Suscribirse

Recibe nuevas publicaciones sobre sistemas, infraestructura e ingeniería de IA.