Guía de Claude Code CLI: instalación, configuración, comandos y variables de entorno

TL;DR: Claude Code es un CLI agéntico que lee tu base de código, ejecuta comandos y modifica archivos mediante un sistema por capas de permisos, hooks, integraciones de MCP y subagents. Domina cinco sistemas fundamentales (configuración, permisos, hooks, MCP y subagents) y multiplicarás tu productividad. Elige el nivel de modelo que mejor se adapte a cada tarea: Opus para razonamientos complejos, Sonnet para trabajo general y Haiku para exploración rápida; o estandariza en Opus si la calidad es tu única variable. Usa hooks (no prompts) para todo lo que deba ejecutarse siempre. El modo automático es el modo de permisos predeterminado para las sesiones nuevas de Pro, Max y Team desde el 14 de agosto de 2026 (se anunció el 7 de agosto y se verificó en producción el día del cambio; autonomía revisada por un clasificador: un defaultMode que hayas establecido se conserva a menos que aceptes la solicitud de cambio que aparece una sola vez, Shift+Tab cambia el modo de cualquier sesión y disableAutoMode lo desactiva en toda la organización).²⁰³ El modelo predeterminado depende de tu plan: Max, Team Premium, Enterprise (basado en puestos desde v2.1.251) y el Anthropic API usan Claude Opus 5 de forma predeterminada, mientras que Pro y Team Standard usan Sonnet 5 – contexto nativo de 1M, $2/$10 por MTok como precio de lista estándar (la tarifa introductoria del lanzamiento, ahora permanente: el aumento previsto para el 1 de septiembre no se producirá)²²⁹²⁰⁷ – el valor predeterminado Sonnet-5-en-todas-partes de v2.1.197 (30 de junio de 2026) ya es historia, y el alias opus apunta a Claude Opus 5 (v2.1.219+); v2.1.198 (1 de julio) hace que los subagents se ejecuten en segundo plano de forma predeterminada, lleva Claude en Chrome a disponibilidad general, permite que los agentes en segundo plano confirmen cambios, hagan push y abran un PR en borrador cuando terminan el código de un worktree, y activa el hook Notification (agent_needs_input/agent_completed) para las sesiones en segundo plano; v2.1.199 (2 de julio) carga hasta 5 invocaciones apiladas de slash-skills y reintenta automáticamente los errores 429 transitorios para suscriptores; v2.1.200 (3 de julio) cambia el nombre del modo de permisos default a “Manual” en todo el CLI, --help, VS Code y JetBrains (el valor de configuración no cambia y manual se acepta como alias), y evita que los diálogos AskUserQuestion continúen automáticamente de forma predeterminada; v2.1.202 (6 de julio) añade un control de «Tamaño dinámico del flujo de trabajo» en /config y separa /review <pr> (una sola pasada rápida) de /code-review <level> <pr#> — una separación que v2.1.223 revirtió: /review vuelve a ser un alias de /code-review, y /code-review sin argumentos reutiliza tu último nivel de esfuerzo; v2.1.203–205 (7–9 de julio) refuerzan el modo automático — se bloquea la manipulación de los archivos de transcripción, rm -rf sobre una variable que no puede resolverse solicita confirmación primero, y las notificaciones de tareas en segundo plano indican que no hubo intervención humana (por lo que no se puede actuar a partir de aprobaciones falsas incluidas en la transcripción) — y convierten /doctor en una revisión completa de diagnóstico y corrección (alias /checkup).^181182183 v2.1.217 (21 de julio) cambió de rumbo respecto de los subagents anidados — los subagents dejaron de generar sus propios subagents de forma predeterminada (una decisión que v2.1.219 revirtió otra vez tres días después, con una profundidad de 3; consulta más adelante), se ejecutan como máximo 20 subagents simultáneamente de forma predeterminada (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), y --max-budget-usd ahora sí detiene los subagents en segundo plano cuando se alcanza el límite.¹⁹⁴ v2.1.218 (22 de julio) traslada /code-review a un subagent en segundo plano — el trabajo de revisión ya no ocupa tu conversación —, ejecuta las skills con context: fork en segundo plano de forma predeterminada (puedes desactivarlo en cada skill con background: false), hace que /deep-research se inicie únicamente mediante una invocación explícita, delega al clasificador del modo automático las comprobaciones de rm peligroso, & en segundo plano y rutas sospechosas de Windows en lugar de usar diálogos de permisos, e impide que los hooks del frontmatter de los agentes se ejecuten desde carpetas que no sean de confianza.¹⁹⁵ v2.1.219 (24 de julio) convierte a Claude Opus 5 (claude-opus-5) en el modelo Opus predeterminado — contexto de 1M, salida máxima de 128K, $5/$25 por MTok (idéntico a Opus 4.8), razonamiento activado de forma predeterminada, effort establecido en high de forma predeterminada y corte de conocimiento en mayo de 2026 — y corrige dos cambios introducidos en versiones anteriores: el modo rápido ahora se aplica a Opus 5 y Opus 4.8 por $10/$50 por MTok (2× el precio base, y Opus 4.7 se elimina por completo del modo rápido), y los subagents anidados vuelven a estar activados de forma predeterminada, con una profundidad de 3 (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 desactiva el anidamiento). La misma versión añade el evento de hook DirectoryAdded, la configuración sandbox.network.strictAllowlist, una clave de configuración workflowSizeGuideline, con los flujos de trabajo dinámicos usando ahora de forma predeterminada una pauta de tamaño mediano (procura usar menos de 15 agentes), y el reenvío de subagents anidados en stream-json. v2.1.220 (25 de julio) solo contiene correcciones de errores y mejoras de confiabilidad. v2.1.221–226 (4–7 de agosto) añaden mensajería entre sesiones (SendMessage/ListAgents entre tus sesiones, en macOS/Linux), ejecutores autohospedados para sesiones en la nube (Team/Enterprise), la fuente de plugins archive con fijación mediante SHA-256, ocultamiento de credenciales compatible con JWT/SigV4 en el sandbox, la vista Focus de VSCode y copias de /fork con su propio worktree; además, eliminan el límite de 200 subagents por sesión y ultraplan.^{199200201202196197198} v2.1.227–229 (10–12 de agosto) se centran en correcciones e incorporan varias mejoras prácticas: los marketplaces de plugins obtienen fuentes command (un programa local imprime el directorio del plugin, que se vuelve a resolver en cada sesión; mode: "link" lo usa directamente), claude remote-control --continue reanuda tu sesión más reciente de Remote Control, ListAgents etiqueta como offline a los pares de Remote Control desconectados y como cloud a tus sesiones en la nube, /commit-push-pr deja de aprobar automáticamente flags peligrosos de git (--force, --amend, --no-verify), y la herramienta Write adopta las mismas reglas que Edit en los modelos más recientes: sobrescribir un archivo no leído ya no requiere haberlo leído previamente durante la sesión.^236234235 v2.1.232 (13 de agosto) establece la bifurcación de subagents como comportamiento predeterminado (subagent_type: "fork" hereda toda la conversación y la caché del prompt; las generaciones que no sean de compañeros de equipo se ejecutan en segundo plano en las sesiones interactivas), permite mencionar con @ a otra sesión activa por su nombre en el prompt (Claude lo dirige mediante SendMessage, y un nombre sin prefijo que coincida exactamente con una sesión activa ahora se entrega sin solicitar confirmación de la referencia), mantiene nombres únicos por computadora para las sesiones interactivas (variantes name-word-word), expone los controles de entrada entre sesiones como filas de /config e incorpora paridad con GitLab — nueve familias de tokens de GitLab ocultas en el sandbox, protección de credenciales del CLI glab y clonación de URL simples de marketplaces de gitlab.com (incluidos subgrupos anidados), igual que las de GitHub.²³³ v2.1.233 (14 de agosto) extiende la paridad con GitLab a --worktree (URL de MR, mostradas como !N en claude agents), añade límites de memoria en Linux para comandos Bash (CLAUDE_CODE_TOOL_MEMORY_LIMIT) y un control del TTL de caché de WebFetch, y desactiva de forma predeterminada las herramientas de tareas y seguimiento de pendientes en Opus 4.8, Sonnet 5, Fable 5 y versiones posteriores (CLAUDE_CODE_ENABLE_TODO_TOOLS=1 las restaura); también revierte parte de los cambios de permisos de Bash para Windows introducidos en v2.1.232 debido a una regresión del modo automático.²³² v2.1.234 (17 de agosto) hace que Claude Code continúe tu sesión automáticamente cuando se restablezca un límite de uso de claude.ai (puedes desactivarlo en /config: «Continuar automáticamente al alcanzar el límite de uso»), permite abrir /permissions y /add-dir durante un turno, añade CLAUDE_CODE_PROJECT_DIR_NAME y una comprobación de tareas en segundo plano /goal (CLAUDE_CODE_GOAL_CHECKIN_MINUTES), muestra una insignia de MR de GitLab (!N) en el pie de página para repositorios con un CLI glab autenticado, y reduce el costo de contexto de la skill integrada claude-api de unos 200k a unos 25k tokens al cargar la documentación de referencia bajo demanda.²³¹ v2.1.235–238 (18–20 de agosto) añaden un estilo de salida integrado “Concise” (resultados primero, sin preámbulo ni narración; selecciónalo en Output style dentro de /config), la variable de entorno ANTHROPIC_DEFAULT_MODEL (establece el modelo con el que comienzan las sesiones nuevas; una selección en /model sigue prevaleciendo y se conserva, a diferencia de ANTHROPIC_MODEL), una configuración opcional spellcheck (subraya las palabras mal escritas del prompt mediante la instalación disponible de aspell, hunspell o ispell), una configuración keybindingFlavor ("readline" hace que Ctrl+W borre hasta el espacio en blanco anterior, como en Bash; esta configuración se retiró en v2.1.261: readline es ahora el único comportamiento), headersHelper en marketplaces de plugins y en el .mcp.json del proyecto (un comando genera encabezados HTTP de corta duración; los auxiliares de entradas del catálogo solo se ejecutan al instalar o actualizar, después de mostrar su comando, mientras que los auxiliares de ámbito de proyecto/plugin/agente se ejecutan sin variables de entorno de credenciales heredadas tras el diálogo de confianza de la carpeta), notify_when_idle en SendMessage entre sesiones (una notificación única cuando otra sesión local vuelva a quedar inactiva) y dos cambios en el comportamiento de los permisos: el modo automático ahora deja de lado las reglas de autorización de Monitor (los comandos Monitor reciben la misma revisión del clasificador que Bash), y las reglas de denegación de lectura con comodines del sandbox de macOS (**/.env) tienen prioridad dentro de las regiones de lectura permitidas y no pueden eludirse cambiando el nombre del archivo denegado; además, el clasificador del modo automático ahora usa los valores predeterminados de Claude API en Bedrock, Vertex AI y Foundry, y cuando la telemetría está desactivada²²⁴ (desde v2.1.273, esas puertas de enlace usan el clasificador local de forma predeterminada «por ahora»; CLAUDE_CODE_AUTO_MODE_SERVER=1 habilita el clasificador del servidor de la plataforma²¹⁷). v2.1.239 (21 de agosto) añade /claude-api upgrade (migra proyectos de Python de anthropic 0.x a 1.x), incorpora en las estimaciones de costo el recargo de 1,1× por inferencia exclusiva en EE. UU. para espacios de trabajo con residencia de datos (/cost, línea de estado, --max-budget-usd), lleva la mensajería entre sesiones a Windows, muestra los plugins sincronizados con claude.ai como name@synced (administrables con claude plugin enable/disable, sin reemplazar nunca una instalación local con el mismo nombre), enseña a ListAgents el nombre de la propia sesión y sus compañeros de equipo activos, extiende "readline" a las teclas de palabras de Bash, reduce la frecuencia de las comprobaciones de /goal (30 min → 1 h → 2 h) y ofrece el renderizador de pantalla completa en Bedrock/Vertex/Foundry; v2.1.240–241 (22–23 de agosto) son versiones de corrección de errores. El resumen de documentación de esa misma semana registra dos cambios de estado: /design — una skill en vista previa de investigación que publica un lienzo con mesas de trabajo de interfaz editables mediante artifacts (Pro/Max/Team/Enterprise, requiere v2.1.233+) — y Remote Control deja la vista previa de investigación, con las computadoras que ejecutan claude remote-control apareciendo como tarjetas de dispositivo en la aplicación de Claude.²⁰⁵ Desde v2.1.174–176 (12 de junio de 2026), la lista de permitidos availableModels puede limitar ahora el modelo Default mediante la nueva configuración administrada enforceAvailableModels (la configuración de usuario o proyecto no puede ampliar una lista administrada), los títulos de sesión se generan en el idioma de tu conversación (puedes fijar uno mediante la configuración language), y completan la versión las nuevas configuraciones footerLinksRegexes y wheelScrollAccelerationEnabled, un diálogo de atribución /usage en VSCode y una corrección para que las condiciones if de los hooks coincidan con patrones de rutas de Read/Edit/Write.¹⁷² Desde v2.1.173 (11 de junio de 2026), un nombre de modelo Fable 5 con el sufijo [1m] se normaliza/elimina automáticamente — Fable 5 ya incluye contexto de 1M de forma predeterminada, por lo que el sufijo es innecesario (solo tuvo sentido para Opus/Sonnet). Desde v2.1.172 (10 de junio de 2026), los subagents podían generar recursivamente sus propios subagents, hasta una profundidad de 5 niveles — un valor predeterminado que se mantuvo hasta v2.1.216 y se desactivó en v2.1.217 (consulta arriba) —, Bedrock lee su región desde ~/.aws cuando AWS_REGION no está definida (/status muestra la fuente), /plugin añade una barra de búsqueda de marketplaces y la métrica OTEL claude_code.lines_of_code.count incorpora un atributo model. Desde v2.1.170 (9 de junio de 2026), Claude Fable 5 — un nuevo nivel de modelo superior a Opus — puede seleccionarse en Claude Code mediante /model fable después de claude update (admite toda la escala de esfuerzo de low a max, pero no permite desactivar el razonamiento); Opus 4.8 sigue siendo el modelo agéntico predeterminado. Desde v2.1.169 (8 de junio de 2026), --safe-mode (y CLAUDE_CODE_SAFE_MODE) inicia una sesión limpia con todas las personalizaciones desactivadas para solucionar problemas, /cd traslada una sesión a un nuevo directorio de trabajo sin invalidar la caché del prompt, y disableBundledSkills oculta al modelo las skills y los comandos slash integrados. Desde v2.1.166 (6 de junio de 2026), una configuración fallbackModel encadena hasta tres modelos de respaldo cuando el principal está sobrecargado, el glob "*" funciona en las reglas de denegación de MCP, y MAX_THINKING_TOKENS=0 / --thinking disabled desactivan por completo el razonamiento en los modelos que lo activan de forma predeterminada. Desde v2.1.154 (28 de mayo de 2026), Opus 4.8 es el nuevo modelo predeterminado, con esfuerzo alto de forma predeterminada y un nivel /effort xhigh, los flujos de trabajo dinámicos coordinan de decenas a cientos de agentes en segundo plano mediante /workflows, el modo rápido en Opus 4.8 cuesta 2× la tarifa estándar a cambio de una velocidad 2,5× mayor, el prompt de sistema reducido es ahora el predeterminado para todos los modelos excepto Haiku/Sonnet/Opus 4.7 y anteriores, /simplify volvió a ser una revisión exclusivamente de limpieza (separada de /code-review --fix), claude agents acepta ! <command> para generar sesiones de shell en segundo plano, los plugins pueden declarar defaultEnabled: false, la ejecución de herramientas en streaming está siempre activada, y los servidores MCP stdio reciben CLAUDE_CODE_SESSION_ID junto con CLAUDECODE=1 en el entorno. v2.1.153 añadió skipLfs a los marketplaces de plugins, hizo que /model se guardara como valor predeterminado (presiona s para aplicarlo solo a la sesión) e incorporó COLUMNS/LINES al entorno de la línea de estado. v2.1.152 introdujo /code-review --fix (aplica los hallazgos al árbol de trabajo), disallowed-tools en el frontmatter de las skills, /reload-skills, el nuevo evento de hook MessageDisplay, las salidas reloadSkills/sessionTitle del hook SessionStart, la configuración administrada pluginSuggestionMarketplaces, el cambio de --fallback-model a mitad de sesión y la eliminación de la activación voluntaria del modo automático.^{162 163 164 165 166 167 168 169 170 245 171}

Claude Code funciona como un sistema agéntico, no como una interfaz de chat con conocimientos de programación. El CLI lee tu base de código, ejecuta comandos, modifica archivos, administra flujos de trabajo de git, se conecta con servicios externos mediante MCP y delega tareas complejas en subagents especializados. Todo se realiza mediante una interfaz de línea de comandos que se integra en la forma de trabajar de los desarrolladores. En febrero de 2026, el 4 % de los commits públicos de GitHub (unos 135.000 al día) son obra de Claude Code: un crecimiento de 42.896× en los 13 meses transcurridos desde la vista previa de investigación; además, el 90 % del código del propio Anthropic está escrito por IA.¹⁰³

La diferencia entre un uso ocasional y uno eficaz de Claude Code se reduce a cinco sistemas fundamentales. Domínalos y Claude Code se convertirá en un multiplicador de fuerza:

1. Jerarquía de configuración: controla el comportamiento
2. Sistema de permisos: controla las operaciones
3. Sistema de hooks: permite la automatización determinista
4. Protocolo MCP: amplía las capacidades
5. Sistema de subagents: se encarga de tareas complejas de varios pasos

Conclusiones clave

• Cinco sistemas determinan tu eficacia: la jerarquía de configuración, los permisos, los hooks, MCP y los subagents controlan todo, desde el comportamiento hasta la automatización.
• Traslada el trabajo a la capa de delegación: los subagents evitan que el contexto se sature al aislar la exploración en ventanas de contexto limpias y devolver únicamente resúmenes.
• Los hooks garantizan la ejecución; los prompts no: usa hooks para el linting, el formato y las comprobaciones de seguridad que deban ejecutarse siempre, independientemente del comportamiento del modelo.
• La asignación por niveles de modelo reduce costos sin sacrificar calidad: dirige la exploración de los subagents a modelos más económicos y reserva Opus para el razonamiento arquitectónico verdaderamente complejo; o estandariza en Opus si la calidad es tu única variable.
• MCP conecta Claude con tu cadena de herramientas: las bases de datos, GitHub, Sentry y más de 3.000 integraciones amplían Claude más allá de la lectura de archivos y los comandos bash.

Pasé meses llevando Claude Code al límite en bases de código de producción, pipelines de CI/CD e implementaciones empresariales. Esta guía condensa esa experiencia en la referencia completa que me habría gustado tener cuando empecé. Cada función incluye la sintaxis real, ejemplos de configuración auténticos y los casos límite que causan problemas incluso a usuarios experimentados.

Elige tu ruta

Cómo usar esta guía

Esta es una referencia de más de 5.000 líneas; no necesitas leerla de principio a fin. Empieza por la sección que corresponda a tu nivel de experiencia:

Usa Ctrl+F / Cmd+F en tu navegador para buscar flags, comandos o claves de configuración específicos. La Tarjeta de referencia rápida al final ofrece un resumen fácil de consultar de todos los comandos principales.

Análisis relacionados en profundidad

Estas publicaciones del blog exploran en detalle aspectos específicos de Claude Code:

Inicio rápido en 60 segundos

Si solo quieres ejecutar Claude Code y ver el resultado, sigue estos pasos en orden:

# 1. Install (pick one)
npm install -g @anthropic-ai/claude-code          # npm users
brew install anthropic/claude/claude              # macOS + Homebrew
curl -sL claude.ai/install.sh | sh                # native installer

# 2. Launch in any project directory
cd ~/your-project && claude

# 3. Authenticate (browser opens automatically on first run)
/login

# 4. Ask your first question
> What does this repo do? Read the key files and summarize.

Eso es todo. El contenido que aparece después de esta sección amplía las opciones de instalación, configura permisos y hooks, conecta servidores MCP y aborda la implementación empresarial, pero nada de eso es necesario para comenzar.

Requisitos previos: Node 22+ solo para el método heredado mediante npm (el requisito aumentó desde la versión 18 con v2.1.198; la documentación de instalación vigente indica «Node.js 22 o posterior», verificado el 7 de agosto de 2026); el instalador nativo recomendado no depende de Node. Se admiten macOS, Linux y Windows 10+. El uso está cubierto por una suscripción Pro, Max, Team o Enterprise de Claude, o por una clave de API de Anthropic con pago por token. Consulta ¿Cómo instalo Claude Code? para conocer los detalles específicos de cada plataforma, solucionar problemas y usar el binario nativo (la opción predeterminada desde v2.1.113). La evidencia de la versión más reciente incluida en esta guía se actualiza con cada lanzamiento; consulta la fila más reciente del registro de cambios para ver la fecha de verificación actual.²⁴⁵

Cómo funciona Claude Code: el modelo mental

Antes de profundizar en sus funciones, conviene entender cómo la arquitectura de Claude Code determina todo lo que haces con esta herramienta. El sistema opera en tres capas:

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │           Subagents (20 concurrent default)      │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

Capa central: Tu conversación principal. Cada mensaje, lectura de archivos y resultado de herramientas consume contexto de una ventana compartida (200.000 tokens de forma estándar⁹¹ y 1 millón de tokens con Opus 4.6 o modelos de contexto ampliado). Cuando el contexto se llena, Claude pierde el hilo de las decisiones anteriores y la calidad disminuye. Esta capa genera costos por token.

Capa de delegación: Los subagents se inician con contextos limpios, realizan tareas específicas y devuelven resúmenes. Los resultados de la exploración no saturan tu conversación principal; solo regresan las conclusiones. Asigna los subagents a niveles de modelos más económicos para las tareas de exploración, o utiliza tu modelo principal en todo momento si la calidad te importa más que el costo.

Capa de extensión: MCP conecta servicios externos (bases de datos, GitHub, Sentry). Los hooks garantizan la ejecución de comandos del shell independientemente del comportamiento del modelo. Las skills codifican conocimientos especializados que Claude aplica automáticamente. Los plugins agrupan todos estos elementos para distribuirlos.

La idea clave: La mayoría de los usuarios trabaja exclusivamente en la capa central y observa cómo aumentan el contexto y los costos. Los usuarios avanzados trasladan la exploración y el trabajo especializado a la capa de delegación, mantienen la capa de extensión configurada para su flujo de trabajo y reservan la capa central para la coordinación y las decisiones finales.

Tabla de contenido

1. ¿Cómo instalo Claude Code?
2. Inicio rápido: tu primera sesión
3. Modos principales de interacción
4. Análisis detallado del sistema de configuración
5. ¿Qué modelo debo elegir?
6. ¿Cuánto cuesta Claude Code?
7. Marcos para la toma de decisiones
8. ¿Cómo funciona el sistema de permisos?
9. ¿Cómo funcionan los hooks?
10. ¿Qué es MCP (Model Context Protocol)?
11. ¿Qué son los subagents?
12. ¿Qué es el modo de pensamiento ampliado?
13. Estilos de salida
14. Comandos con barra diagonal
15. ¿Cómo funcionan las skills?
16. Sistema de plugins
17. ¿Cómo funciona la memoria?
18. Entrada de imágenes y contenido multimodal
19. Modo de voz
20. ¿Cómo funciona la integración con Git?
21. ¿Cómo uso Claude Code en mi IDE?
22. Patrones de uso avanzado
23. Agentes remotos y en segundo plano [VERSIÓN PRELIMINAR DE INVESTIGACIÓN]
24. Claude en Chrome
25. Claude Code en Slack [VERSIÓN PRELIMINAR DE INVESTIGACIÓN]
26. Claude Code en la web [VERSIÓN PRELIMINAR DE INVESTIGACIÓN]
27. Claude en Microsoft 365 (mayo de 2026)
28. Optimización del rendimiento
29. ¿Cómo depuro problemas?
30. Implementación empresarial
31. Referencia de atajos de teclado
32. Prácticas recomendadas
33. Recetas de flujos de trabajo
34. Guía de migración
35. Orientación para públicos específicos
36. Tarjeta de referencia rápida
37. Registro de cambios
38. Referencias

¿Cómo instalo Claude Code?

Requisitos del sistema

Claude Code funciona en macOS 13+, Ubuntu 20.04+/Debian 10+ y Windows 10+ (nativo o WSL). El sistema requiere un mínimo de 4 GB de RAM y una conexión a internet activa.⁹² La compatibilidad de shell es mejor con Bash, Zsh o Fish.

En Windows funcionan tanto WSL 1 como WSL 2. Git Bash también sirve si prefieres Windows nativo. Alpine Linux y otros sistemas basados en musl requieren paquetes adicionales:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Matriz de compatibilidad por plataforma

Instalar, actualizar y desinstalar de un vistazo

Consulta rápida: todos los métodos, todos los comandos y la verificación de versión en una sola pantalla. Las subsecciones siguientes cubren los detalles de cada método y la resolución de problemas.

Desde la v2.1.113, el CLI canónico lanza un binario nativo de Claude Code mediante una dependencia opcional específica de cada plataforma en lugar de JavaScript incluido: usa el instalador nativo para la distribución probada. La ruta de npm todavía funciona, pero es la primera en recibir el aviso de obsolescencia agregado en la v2.1.15.

Métodos de instalación

Instalación nativa (recomendada)

El binario nativo ofrece la experiencia más limpia, sin dependencia de Node.js:

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

# Homebrew alternative
brew install --cask claude-code

# 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

Para instalar una versión específica:

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Una versión que nunca debes fijar detrás de un proxy o gateway: la 2.1.275. En esa compilación, todas las solicitudes fallan con 400 ... Input tag 'advisor_20260301' cuando ANTHROPIC_BASE_URL apunta a un proxy o gateway; la 2.1.276 corrige la regresión.²¹⁸

Instalación con NPM (obsoleta)

Nota: A partir de la v2.1.15, las instalaciones con npm muestran un aviso de obsolescencia. El binario nativo es ahora el método de instalación recomendado. Migra con claude install.

Para entornos heredados donde npm todavía es necesario:

npm install -g @anthropic-ai/claude-code

Nunca uses sudo en la instalación con npm. Genera problemas de permisos que complican todo lo que venga después.

Migración desde una instalación existente

Si tienes una instalación antigua basada en npm, migra al binario nativo:

claude install

Opciones de autenticación

Claude Code admite tres rutas de autenticación, cada una con sus propias ventajas y desventajas:

Claude Console (facturación de API)

Conéctate directamente a la API de Anthropic a través de platform.claude.com (antes console.anthropic.com). Crea una cuenta, configura la facturación y autentícate mediante el CLI. La Console ofrece facturación por uso con acceso completo a la API. Se crea automáticamente un workspace dedicado llamado “Claude Code”; no puedes crear claves de API para ese workspace, pero sí monitorear el uso. A partir de la v2.1.243, /login → Anthropic Console ofrece una ruta sin claves, “Sign in with your Console account” (recomendada), junto con la creación de una clave de API, de modo que las organizaciones que no permiten claves de API igual pueden iniciar sesión con credenciales de Console.²²⁸

Suscripción a Claude Pro o Max

Usa las credenciales de tu cuenta de claude.ai. La suscripción cubre tanto la interfaz web como el uso del CLI dentro de un mismo plan mensual. Simplifica la facturación para usuarios individuales que quieren costos predecibles.

Plataformas empresariales

AWS Bedrock, Google Vertex AI y Microsoft Foundry ofrecen acceso de nivel empresarial con las relaciones de facturación en la nube que ya tengas. Asistente de configuración de Bedrock (v2.1.92+): un asistente interactivo en la pantalla de inicio de sesión te guía por la autenticación de AWS, la selección de región, la verificación de credenciales y la fijación de modelo.¹³⁷ Asistente de configuración de Vertex AI (v2.1.98+): un asistente equivalente para Google Cloud, que guía la autenticación de GCP, la configuración de proyecto y región, la verificación de credenciales y la fijación de modelo.¹⁴² Workload Identity Federation con mTLS en Vertex AI (v2.1.121+): Vertex AI ahora acepta Workload Identity Federation basada en certificados X.509 (credenciales predeterminadas de aplicación con mTLS): tokens de GCP de corta duración emitidos a partir de un certificado de cliente, sin necesidad de una JSON de cuenta de servicio.¹⁵⁴ Confianza en los certificados CA del sistema operativo (v2.1.101+): los proxies TLS empresariales ahora funcionan de forma predeterminada, ya que Claude Code confía en el almacén de certificados del sistema operativo. Define CLAUDE_CODE_CERT_STORE=bundled para usar únicamente las CA incluidas.¹⁴³

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

# Amazon Bedrock via Mantle (v2.1.94+)
export CLAUDE_CODE_USE_MANTLE=1

Para despliegues empresariales detrás de proxies o a través de gateways de LLM:

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

Encabezados de sugerencia para gateways (v2.1.273, opcional): con CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 definido, Claude Code agrega cinco encabezados de solicitud que un gateway de LLM puede enrutar y observar: x-claude-code-request-class, x-claude-code-agent-type, x-claude-code-prev-tool-durations, x-claude-code-compaction y x-claude-code-context-compacted.²¹⁷

Verificación

claude doctor

El comando informa el tipo de instalación, la versión, la configuración del sistema y cualquier problema detectado.

Gestión de autenticación (v2.1.41+)

Administra la autenticación sin entrar al REPL:⁹⁰

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

A partir de la v2.1.268, claude auth status --json incluye configDirectory: el directorio de configuración que el CLI está leyendo realmente, útil cuando la indirección de CLAUDE_CONFIG_DIR vuelve eso ambiguo.²¹⁶

A partir de la v2.1.273, iniciar sesión con una cuenta de Claude también solicita acceso a tus plugins de claude.ai.²¹⁷

Flujo de trabajo habitual para cambiar entre cuentas u organizaciones:

claude auth logout && claude auth login

Consulta también: ¿Cómo depuro problemas? para resolver fallas de autenticación.

Actualizaciones

Claude Code se actualiza automáticamente de forma predeterminada: revisa al iniciar y de manera periódica durante las sesiones. Las actualizaciones se descargan en segundo plano y se aplican en el siguiente arranque.

Desactivar las actualizaciones automáticas:

export DISABLE_AUTOUPDATER=1

O en settings.json:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Actualización manual:

claude update

Desinstalación

Instalación nativa (macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

Instalación nativa (Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

Configuración limpia (elimina toda la configuración):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

Inicio rápido: tu primera sesión

1. Instala e inicia:

claude                           # Launch in current directory

2. Ve a un proyecto:

cd ~/my-project && claude        # Or launch from any git repo

3. Pídele a Claude que haga algo:

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. Usa atajos de teclado durante la sesión:

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. Retoma la sesión más adelante:

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

Consejo experto: Crea un archivo CLAUDE.md en la raíz de tu proyecto con los comandos de compilación, las convenciones de código y las notas de arquitectura. Claude lo lee en cada sesión; es lo que más puede mejorar la calidad con el menor esfuerzo.

Modos principales de interacción

REPL interactivo

Inicia Claude Code sin argumentos para entrar en el bucle interactivo de lectura, evaluación e impresión:

cd your-project
claude

El REPL mantiene el contexto de la conversación entre turnos. Escribe consultas directamente, recibe respuestas y continúa hasta salir con /exit o Ctrl+D.

Comienza con un prompt inicial para enfocar la sesión:

claude "explain the authentication flow in this project"

Consejo experto: El REPL conserva el estado durante los eventos de compactación. Cuando el contexto crece demasiado, Claude resume automáticamente la conversación anterior, a la vez que conserva las decisiones clave y los fragmentos de código. Puedes activar este proceso manualmente con /compact o agregar instrucciones personalizadas sobre qué preservar.

Modo no interactivo

El modo de impresión (-p) ejecuta una sola consulta y finaliza:

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

Para obtener una salida estructurada apta para procesarla en scripts:

claude -p "count lines by file type" --output-format json

La salida JSON incluye todo lo necesario para la automatización:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

Para procesar en tiempo real la salida transmitida:

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

Opciones de formato de salida:

Texto de subagents en stream-json (v2.1.211+): De forma predeterminada, la salida stream-json solo contiene los eventos de la sesión principal; el trabajo realizado dentro de subagents aparece como un resumen. El indicador --forward-subagent-text (o CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1) también reenvía al flujo el texto y el razonamiento de los subagents, de modo que los sistemas de ejecución y las canalizaciones de registros puedan observar el trabajo delegado mientras ocurre, en lugar de ver únicamente el informe final.¹⁸⁸

Los subagents anidados ahora también se reenvían (v2.1.219). Originalmente, solo aparecían los subagents de profundidad 1. Ahora, los subagents creados en la profundidad 2 y posteriores también aparecen en el flujo reenviado, cada uno identificado mediante el id de tool_use de la llamada a Agent que lo creó. Así, una canalización puede reconstruir el árbol de delegación en lugar de ver una lista plana de texto. Esto se complementa directamente con la restauración, en la misma versión, de la creación anidada hasta una profundidad predeterminada de 3: sin ella, 2 de los 3 niveles habrían sido invisibles.¹⁹⁶

Los subagents enviados a segundo plano ya no quedan incomunicados (v2.1.273): La salida de SDK y stream-json dejó de descartar los mensajes restantes y el informe final de un subagent cuando este pasa a segundo plano durante la ejecución (por ejemplo, mediante CLAUDE_AUTO_BACKGROUND_TASKS).²¹⁷

Códigos de salida:

Control del comportamiento autónomo en el modo -p:

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-5

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+)
claude -p "count files" --bare

# Channel permission relay: send approval prompts to Telegram/Discord (v2.1.81+)
claude --channels

# Restricted mode for eval harnesses and shared machines (v2.1.248+)
claude --restricted -p "query" --tools "Read,Grep,Glob"

# Unattended hosts: deny anything that would prompt (v2.1.259+)
claude -p "run the nightly checks" --permission-prompts none

Modo restringido (v2.1.248+): --restricted (o CLAUDE_CODE_RESTRICTED=1) está diseñado para sistemas de evaluación que ejecutan claude en una máquina compartida. Elimina las herramientas integradas que ejecutan comandos o código, así como WebFetch, a menos que las indiques individualmente en --tools —el ajuste preestablecido default no cuenta—; restringe las herramientas de archivos integradas a los directorios de trabajo; carga únicamente la configuración administrada y --settings (se ignoran los archivos de configuración del usuario, del proyecto y locales); rechaza bypassPermissions; y no permite crear sesiones en la nube.²⁰⁶²⁰⁹

--permission-prompts none (v2.1.259): el complemento para hosts sin supervisión. Todo lo que generaría una solicitud de permiso se rechaza automáticamente, mientras que el modo de permisos activo —incluido el modo automático— continúa tomando todas las decisiones que puede tomar sin ti. No lo confundas con --permission-prompt-tool, que delega las solicitudes a una herramienta MCP en lugar de rechazarlas. La referencia de CLI aún no incluye el nuevo indicador; el CHANGELOG es la fuente.²¹¹

cd persiste entre turnos en sesiones no interactivas (v2.1.265): Las sesiones -p que reciben entradas stream-json, las sesiones de SDK de Agent y las sesiones en la nube ya no restablecen el directorio de trabajo del shell con cada mensaje nuevo del usuario: un cd ejecutado en un turno ahora se mantiene en el siguiente.²¹⁵

--system-prompt-snapshot off (v2.1.267): De forma predeterminada, una conversación reutiliza el prompt del sistema registrado en cada solicitud. Este indicador hace que el prompt del sistema vuelva a generarse en cada solicitud; es la opción indicada para iterar sobre su texto cuando cada ejecución debe incorporar la edición más reciente en lugar de la instantánea, a costa de la estabilidad de la caché del prompt que dicha instantánea busca proteger.²¹⁶

Patrón de integración con CI/CD:

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

Administración de sesiones

Las sesiones conservan el historial de la conversación para poder continuarla. Esta persistencia es esencial para trabajos complejos que abarcan varias sesiones:

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

Traslada una sesión en curso con /cd (v2.1.169+; configuración inmediata desde v2.1.246): /cd path cambia el directorio de trabajo sin afectar la caché del prompt. Desde v2.1.246, la configuración del proyecto, los hooks, los servidores de .mcp.json (sujetos a la solicitud de aprobación habitual), las skills y los agents del nuevo directorio surten efecto inmediatamente después del traslado, en lugar de esperar a --resume.²⁴⁰²²⁷

Sesiones vinculadas a PR (v2.1.27+, ampliadas en v2.1.119+): Inicia una sesión vinculada a una solicitud de incorporación de cambios o de fusión específica. Desde v2.1.119, --from-pr acepta URL de MR de GitLab, PR de Bitbucket y PR de GitHub Enterprise, además de github.com:⁷⁴¹⁵²

claude --from-pr 123                                                # GitHub PR number (assumes current repo's remote)
claude --from-pr https://github.com/org/repo/pull/123               # GitHub URL
claude --from-pr https://gitlab.com/org/repo/-/merge_requests/45    # GitLab MR (v2.1.119+)
claude --from-pr https://bitbucket.org/org/repo/pull-requests/67    # Bitbucket PR (v2.1.119+)
claude --from-pr https://ghe.example.com/org/repo/pull/89           # GitHub Enterprise (v2.1.119+)

Las sesiones también se vinculan automáticamente a los PR cuando los creas mediante gh pr create durante una sesión. Esto facilita retomar más adelante el trabajo de un PR específico. La insignia del PR en el pie de página puede dirigir a una URL personalizada de revisión de código mediante la configuración prUrlTemplate (v2.1.119+), lo que resulta útil cuando tu equipo enlaza los PR con una herramienta de revisión independiente.¹⁵²

/resume acepta URL de PR (v2.1.122+). Al pegar una URL de PR en el cuadro de búsqueda de /resume, ahora se encuentra la sesión que creó originalmente ese PR. Funciona con github.com, GitHub Enterprise, gitlab.com (incluidas las instancias de GitLab con alojamiento propio) y bitbucket.org.¹⁵⁴

Sesiones con nombre: Asigna nombres a las sesiones al iniciarlas o durante una sesión:

# Name session at startup (v2.1.76+)
claude -n "auth-refactor"                  # --name flag sets display name[^125]

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

Nota: --session-id requiere un UUID válido (por ejemplo, 550e8400-e29b-41d4-a716-446655440000). Para asignar nombres legibles a las sesiones, usa /rename y --resume.

/fork crea una sesión en segundo plano; /subtask es la bifurcación dentro de la sesión (v2.1.212). El comando /fork ahora copia la conversación actual en una nueva sesión en segundo plano. Esta obtiene su propia fila en claude agents, por lo que puedes enviar la copia a explorar una alternativa mientras continúa la sesión principal. El comportamiento anterior —bifurcar dentro de la sesión actual— continúa disponible con el nuevo nombre /subtask.¹⁸⁹ Desde v2.1.214, una sesión que comienza como bifurcación informa "fork" como origen del hook SessionStart (antes era "resume"), lo que permite que los hooks que filtran por origen distingan ambas opciones.¹⁹⁰ v2.1.216 reduce la confirmación de /fork a una sola línea que muestra el nombre de la sesión nueva y su id de claude attach.¹⁹² Desde v2.1.221, una sesión bifurcada crea su propio worktree en lugar de trabajar en el checkout de la sesión original. De este modo, la bifurcación que explora una alternativa ya no puede entrar en conflicto con los archivos sin confirmar de la sesión principal, que era el principal riesgo al enviar una copia para experimentar.¹⁹⁹ v2.1.232 también convierte la bifurcación en el comportamiento predeterminado de los subagents: un subagent con subagent_type: "fork" hereda toda la conversación y la caché del prompt, y las ejecuciones de agents que no sean compañeros de equipo dentro de sesiones interactivas ahora se realizan en segundo plano de forma predeterminada.²³³

Claude Code almacena las sesiones como transcripciones JSONL. La ejecución de Agent asigna valores agentId únicos y almacena las transcripciones como agent-{agentId}.jsonl. Al reanudar una sesión, se conserva todo el contexto de las conversaciones anteriores.

Modo de planificación

El modo de planificación restringe Claude a la exploración de solo lectura: no permite editar archivos, ejecutar Bash ni realizar acciones destructivas. Claude diseña un enfoque de implementación, lo escribe en un archivo de planificación y espera tu aprobación antes de ejecutar cualquier acción.

Cómo entrar en el modo de planificación:

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or use the /plan command with an optional description (v2.1.72+)
/plan                                     # Enter plan mode
/plan refactor the auth module            # Enter plan mode with a description

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

Cómo funciona:

1. Claude entra en el modo de planificación (automáticamente para tareas complejas o mediante Shift+Tab)
2. Explora el código fuente con herramientas de solo lectura: Read, Glob, Grep, WebSearch, WebFetch
3. Escribe un plan en .claude/plans/{session-slug}.md
4. Sale del modo de planificación con ExitPlanMode y presenta el plan para que lo revises
5. Apruebas, solicitas cambios o rechazas el plan

Herramientas disponibles en el modo de planificación: Read, Glob, Grep, LS, WebSearch, WebFetch, AskUserQuestion. Las herramientas de edición (Edit, Write, Bash, NotebookEdit) están bloqueadas.

Después de aprobar el plan (v2.1.32+): Claude ofrece tres opciones: - “Sí, borra el contexto y acepta automáticamente las ediciones” (Shift+Tab) — comienza desde cero con todo el contexto disponible para el plan - “Sí, y aprueba manualmente las ediciones” — conserva el contexto y tú apruebas cada cambio - “Sí, acepta automáticamente las ediciones” — conserva el contexto y Claude ejecuta el plan sin solicitar aprobación para cada edición

Borrar automáticamente el contexto al aprobar es el flujo de trabajo recomendado. Esto proporciona al plan una ventana de contexto nueva, lo que mejora considerablemente su cumplimiento: Claude mantiene el rumbo durante más tiempo sin que interfiera la conversación anterior.

Cuándo usar el modo de planificación: - Implementaciones de funciones nuevas que requieren decisiones de arquitectura - Refactorizaciones de varios archivos en las que quieres revisar primero el enfoque - Bases de código desconocidas que conviene explorar antes de modificarlas - Cualquier tarea con varios enfoques válidos en la que quieras aportar tu opinión

Consejo experto: Cuanto más tiempo dediques al modo de planificación, más probable será que Claude implemente la solución correctamente. Este modo permite explorar prácticamente sin costo: no hay llamadas riesgosas a herramientas ni ediciones desperdiciadas. Úsalo con frecuencia.

Modo de lector de pantalla (v2.1.208)

Claude Code incluye un modo específico de lector de pantalla que adapta la interfaz de la terminal para tecnologías de asistencia. Puedes activarlo de cualquiera de estas tres maneras:¹⁸⁶

# Flag at launch
claude --ax-screen-reader

# Environment variable
export CLAUDE_AX_SCREEN_READER=1

# Or persistently in settings.json
{ "axScreenReader": true }

Anthropic documenta el modo —y sus patrones de interacción— en una nueva página de accesibilidad de la documentación oficial.¹⁸⁶

Análisis profundo del sistema de configuración

Claude Code usa un sistema de configuración por capas. Entender la jerarquía es esencial, porque los niveles superiores anulan a los inferiores y la configuración empresarial no se puede eludir de ninguna manera.

Jerarquía de configuración

Definir configuración desde el prompt: /config key=value (v2.1.181)

A partir de la v2.1.181, /config key=value define cualquier ajuste en línea desde el prompt —por ejemplo, /config thinking=false— sin abrir la interfaz interactiva de /config, y funciona en sesiones interactivas, con -p y de Remote Control. /config --help (v2.1.183) lista las claves abreviadas disponibles. La v2.1.183 también cambió la interfaz interactiva de /config para que Enter y Espacio alternen el ajuste seleccionado y Esc guarde y cierre (antes revertía).¹⁷⁴

Referencia completa de settings.json

Una configuración completa que demuestra todas las opciones principales:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "label": "Team tips",
    "tips": [
      "Custom tip 1",
      {"id": "tip-2", "text": "Custom tip 2", "cooldownSessions": 5, "priority": 1}
    ],
    "tipsFile": "~/.claude/team-tips.json",
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "bedrock": "us.anthropic.claude-opus-5",
    "vertex": "claude-opus-5",
    "foundry": "claude-opus-4-8"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

skillOverrides resulta útil cuando un equipo tiene una biblioteca de skills grande pero quiere una exposición más ajustada en tiempo de ejecución. Usa off para ocultar una skill tanto del modelo como del selector de comandos slash, user-invocable-only para que siga siendo invocable por nombre pero se elimine de la selección del modelo, y name-only para dejar visible únicamente el nombre de la skill sin su descripción completa.¹⁵⁶

Ajustes más recientes (v2.1.174–176):

• availableModels / enforceAvailableModels (gestionado, v2.1.175+): la lista de permitidos availableModels restringe qué modelos puede seleccionar una sesión. Con enforceAvailableModels: true, la lista de permitidos también limita el modelo Default: un Default que se resolvería en un modelo no permitido recurre al primer modelo permitido, y la configuración de usuario o de proyecto ya no puede ampliar una lista availableModels gestionada. Una corrección complementaria (v2.1.176) cierra el hueco por el que la elección de un alias podía redirigir a un modelo bloqueado mediante ANTHROPIC_DEFAULT_*_MODEL, y /fast ahora se niega a cambiar a un modelo fuera de la lista de permitidos.¹⁷² A partir de la v2.1.187, las organizaciones pueden imponer restricciones de modelo directamente en el selector /model, en --model, en /model y en ANTHROPIC_MODEL: al seleccionar un modelo restringido aparece un mensaje que indica que está “restricted by your organization’s settings”.¹⁷⁶
• language (refinamiento de la v2.1.176): además de definir el idioma de las respuestas, los títulos de sesión ahora se generan de forma predeterminada en el idioma de tu conversación; define language para fijar un idioma concreto para los títulos.¹⁷²
• footerLinksRegexes (v2.1.176): insignias de enlaces detectadas por regex en la fila del pie, configurables mediante la configuración de usuario o gestionada.¹⁷²
• wheelScrollAccelerationEnabled (v2.1.174): ponlo en false para desactivar la aceleración del desplazamiento con la rueda del mouse en modo de pantalla completa.¹⁷²

Ajustes más recientes (v2.1.207–v2.1.212):

• vimInsertModeRemaps (v2.1.208): reasignaciones de teclas personalizadas para el modo de inserción de vim; el ejemplo clásico es asignar jj a Escape (consulta Modo Vim).¹⁸⁶
• axScreenReader (v2.1.208): activa el modo lector de pantalla de forma persistente (consulta Modo lector de pantalla).¹⁸⁶
• processWrapper (v2.1.208): enruta cada proceso que Claude Code genera para sí mismo a través de un ejecutable contenedor; pensado para lanzadores corporativos (consulta Lanzador corporativo).¹⁸⁶
• Restricción de origen de autoMode (v2.1.207): el ajuste autoMode ya no se lee desde el .claude/settings.local.json de un repositorio; configúralo en ~/.claude/settings.json en su lugar. Esto cierra una vía por la que un repo clonado podía traer consigo la configuración del modo automático.¹⁸⁵

Ajustes más recientes (v2.1.217):

• emojiCompletionEnabled (v2.1.217): autocompletado de códigos abreviados de emoji en la entrada del prompt: escribe :heart: para insertar ❤️, o algo parcial como :hea para ver sugerencias. Activado de forma predeterminada; ponlo en false para desactivarlo.¹⁹⁴

Ajustes más recientes (v2.1.219):

• sandbox.network.strictAllowlist (v2.1.219): deniega los hosts que no están en la lista de permitidos para comandos en sandbox sin preguntar, en lugar de mostrar un diálogo de permisos. Consulta Modo sandbox.¹⁹⁶
• workflowSizeGuideline (v2.1.219): define la guía orientativa de tamaño de los workflows dinámicos desde cualquier archivo de configuración —de usuario, de proyecto o gestionado— y no solo a través de /config. Los workflows dinámicos usan de forma predeterminada una guía medium (“apunta a menos de 15 agentes”); la fila de /config se oculta mientras un archivo de configuración proporcione el valor. Es orientativo, no un límite impuesto. Consulta Subagents.¹⁹⁶

Ajustes más recientes (v2.1.242–243):

• modelPicker (de usuario o gestionado, v2.1.242+): personaliza el selector /model con una lista ordenada y etiquetada de modelos. Es un objeto con un array options (cada fila lleva un model obligatorio más label y description opcionales; model se toma literalmente, así que funcionan tanto los alias como los IDs de Anthropic y los de Bedrock/Vertex/Foundry/gateway) y un booleano opcional replaceBuiltInOptions (false, el valor predeterminado, añade las filas después de la lista integrada; true muestra solo tus filas, Default y el modelo que la sesión ya está ejecutando). Claude Code lee la clave de la configuración gestionada, de --settings y de la configuración de usuario, y la ignora en la configuración de proyecto y local, de modo que un repositorio clonado no puede reetiquetar el selector; la fuente de mayor jerarquía que la define aporta la lista completa. Una lista de permitidos availableModels sigue aplicándose a cada fila, y una etiqueta cambia lo que muestra el selector, no qué modelo se ejecuta.²²⁸²²⁶
• promptCacheTtl / subagentPromptCacheTtl (cualquier archivo, v2.1.242+): "5m" o "1h" por bucket de solicitudes, de modo que quienes usan una clave de API o proveedores en la nube pueden mantener una caché de una hora en la conversación principal mientras los subagents se quedan en cinco minutos. Consulta Estrategias de caché.²²⁸²²⁶
• modelPricing (gestionado, v2.1.243+): las tarifas contratadas por modelo de una organización y su multiplicador de descuento, que /cost, la línea de estado y las cifras de costo de telemetría usan en lugar del precio de lista. Consulta Ver costos.²²⁸

Ajustes más recientes (v2.1.247): - feedbackDrafts (v2.1.247): controla la nueva herramienta SendFeedback: cuando algo sale mal en una sesión, Claude puede redactar un informe de retroalimentación para que lo revises y lo envíes desde /feedback; desactiva la redacción con esta configuración. Consulta la fila de /feedback en Comandos de barra.²²³ - Extensión de la forma de spinnerTipsOverride (v2.1.247): las entradas de consejos ahora pueden ser objetos {id, text, cooldownSessions, priority} además de cadenas simples, y el objeto gana las claves tipsFile y label, de modo que las organizaciones pueden rotar sus propios consejos junto con los integrados (el ejemplo anterior muestra la forma extendida). La documentación de configuración aún no documenta las claves nuevas: el CHANGELOG es la única fuente para ellas.²²³

Configuraciones más recientes (v2.1.248–251):

• desktopSessionCleanupPeriodDays (v2.1.248): limita cuánto tiempo las sesiones escritas desde el escritorio permanecen exentas de la limpieza de transcripciones. La corrección que lo acompaña importa más que la perilla: las sesiones de Claude Desktop y Cowork solían desaparecer después de cleanupPeriodDays (30 días por defecto); ahora la limpieza las conserva mientras estén en la aplicación, salvo que la política de la organización administre la retención.²⁰⁶
• Restricciones de env a nivel de proyecto (v2.1.251): un bloque env en un .claude/settings.json a nivel de proyecto ya no puede definir CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR ni TMPDIR/TMP/TEMP; defínelos en tu shell o en la configuración de usuario o administrada, para que un repositorio clonado no pueda redirigir dónde Claude Code escribe su configuración y sus archivos temporales.²⁰⁶

Configuraciones más recientes (v2.1.257-259):

• timeFormat / timeZone (v2.1.257): controlan cómo Claude Code muestra las horas: el reloj de finalización al terminar un turno y las marcas de tiempo de la transcripción. timeFormat acepta 12 horas, 24 horas, 24 horas UTC o un patrón strftime explícito; timeZone nombra la zona horaria. La documentación de configuración todavía no los documenta: el CHANGELOG es la fuente.²¹¹
• permissions.blockReadsOutsideWorkingDirectories (v2.1.257): rechaza de plano las lecturas de archivos fuera de los directorios de trabajo de la sesión. Sin esta opción, el modo automático ahora pregunta una vez antes de la primera lectura de ese tipo en la sesión (consulta Modo automático).²¹¹ La v2.1.273 cierra dos brechas: un comando de Bash que el verificador no puede analizar por completo genera una solicitud de confirmación en lugar de omitir la verificación, y un directorio de memoria elegido por la configuración de un repositorio no se carga, ni se recuerda, ni se indexa bajo esta configuración.²¹⁷
• managedMcpServers / managedSourcesBehavior: claves de alcance administrado, tratadas en Despliegue empresarial: organizaciones que proporcionan servidores MCP a todos los usuarios (v2.1.259) y la fusión opcional entre fuentes administradas (refinada en la v2.1.257).²¹¹²²²

Configuraciones más recientes (v2.1.261):

• bashOutputMaxChars / taskOutputMaxChars (v2.1.261): aumentan cuánta salida de comandos (y de tareas en segundo plano, respectivamente) recibe Claude en línea antes de que el resto se guarde en un archivo, hasta 128K caracteres. Es un mecanismo distinto del de la variable de entorno BASH_MAX_OUTPUT_LENGTH, que fija la ventana de relectura del archivo de salida de trabajo del comando (30.000 caracteres por defecto, con un tope de 150.000): estas claves rigen el umbral entre lo que va en línea y lo que se persiste en un archivo; pasado ese punto, la salida aterriza en un archivo que Claude puede leer cuando lo necesite, en lugar de quedar truncada.²¹⁴ A partir de la v2.1.265, el lado persistido también tiene un techo: los resultados de herramientas guardados en disco están limitados a 1 GB, y la vista previa dentro de la conversación indica cuándo un archivo guardado fue truncado.²¹⁵

Configuraciones más recientes (v2.1.267-269):

• maxEffortLevel (v2.1.267): limita el nivel de esfuerzo que pueden elegir los usuarios —a nivel superior o por modelo bajo modelSettings— y se aplica en todos los proveedores, Bedrock, Vertex y Foundry incluidos. Los usuarios todavía pueden elegir un nivel por debajo del tope; es el complemento del lado del administrador para /effort.²¹⁶
• bashEditDiffEnabled (v2.1.269): cuando la herramienta Bash realiza la edición de un archivo, el resultado de la herramienta incluye un diff de los archivos que el comando modificó, de modo que la conversación muestra lo que realmente hizo una edición al estilo sed.²¹⁶

Configuraciones más recientes (v2.1.275):

• syncClaudeAiSkills / syncClaudeAiPlugins (v2.1.275): las skills y los plugins habilitados en tu cuenta de claude.ai ahora se sincronizan con las sesiones de terminal que inicien sesión con esa cuenta. Define cualquiera de las dos claves en false para que las sesiones de terminal usen únicamente skills y plugins locales. Consulta Skills y Sistema de plugins.²¹⁸

Búsqueda de configuraciones: los flags más consultados

Si llegaste aquí buscando una configuración específica por nombre, este es el índice breve. Cada entrada nombra la versión en la que salió y, cuando un alcance la controla, cuál:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers; credential/org/routing/API-behavior headers set from managed or project settings require approval (v2.1.251)[^238]

Configuración de modelos:

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_MODEL=claude-opus-5           # Model new sessions START on; a /model pick overrides + persists (v2.1.236)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5      # What the `opus` alias resolves to (Opus 5 since v2.1.219)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Default model for subagents; an agent's model: field and per-spawn picks win (v2.1.251 demoted it from override to default)[^238]
CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1              # Force every subagent onto CLAUDE_CODE_SUBAGENT_MODEL (or the main model), ignoring agent-definition and per-spawn overrides -- the pre-v2.1.251 behavior, opt-in (v2.1.257)[^243]
CLAUDE_CODE_WORKFLOWS=1                         # Enable Workflow tool for deterministic multi-agent orchestration (v2.1.147+)
MAX_THINKING_TOKENS=10000                       # (Opus 4.6 and Sonnet 4.6 only — removed in Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

Configuración del proveedor de nube:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Bedrock service tier (v2.1.122+): 'default', 'flex', or 'priority'; sent as X-Amzn-Bedrock-Service-Tier header[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in gateway /v1/models discovery for /model picker (v2.1.129+)[^164]
CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS=3000  # Extend the LLM gateway /v1/models discovery timeout (default 3s; v2.1.269+)[^252]
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1              # Send five x-claude-code-* hint headers (request-class, agent-type, prev-tool-durations, compaction, context-compacted) for LLM gateways (opt-in; v2.1.273+)[^253]
CLAUDE_CODE_AUTO_MODE_SERVER=1                  # Use the platform's server-side auto-mode classifier on Bedrock/Vertex/Foundry; since v2.1.273 the local classifier is the default there "for now"[^253]

Control del comportamiento:

DISABLE_AUTOUPDATER=1                           # Prevent automatic background updates
DISABLE_UPDATES=1                               # Block ALL update paths including manual `claude update` (v2.1.118+, stricter than DISABLE_AUTOUPDATER)[^160]
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Homebrew/WinGet installs run package-manager upgrade in background, then prompt restart (v2.1.129+)[^164]
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
CLAUDE_CODE_RESTRICTED=1                        # Restricted mode: no command/code tools or WebFetch unless named in --tools; only managed settings load (v2.1.248+)[^238]
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls
ENABLE_PROMPT_CACHING_1H=1                      # Opt into 1-hour prompt cache TTL (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Deprecated alias for the above; v2.1.108+ still honors it on Bedrock but logs a deprecation notice
FORCE_PROMPT_CACHING_5M=1                       # Force 5-minute cache TTL (v2.1.108+)
CLAUDE_CODE_PROMPT_CACHE_TTL=1h                 # Main-conversation cache TTL, 5m or 1h; beats the promptCacheTtl setting (v2.1.242+)[^234]
CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=5m        # TTL for subagents, workflows, forks, compaction, titles; beats subagentPromptCacheTtl (v2.1.242+)[^234]
ENABLE_TOOL_SEARCH=true                         # Re-enable tool search on Vertex AI (disabled by default v2.1.119+ to avoid unsupported beta header). Valid values: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Hide the working directory in the startup logo (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=1                     # Enable forked subagents on external builds (v2.1.117+)[^160]
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Force synchronized terminal output when auto-detection misses it, such as Emacs eat (v2.1.129+)[^164]
CLAUDE_CODE_SESSION_ID=...                      # Read-only: present in the Bash tool subprocess; matches the session_id passed to hooks (v2.1.132+)[^168]
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1          # Skip the fullscreen alternate-screen renderer; keep the conversation in the terminal's native scrollback (v2.1.132+)[^168]
CLAUDE_EFFORT=...                               # Read-only: current effort level inside hooks and Bash tool subprocess (v2.1.133+)[^169]
CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1             # Include subagent text + thinking in stream-json output; pairs with --forward-subagent-text (v2.1.211+). Covers depth-2+ nested subagents as of v2.1.219[^205][^213]
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=200    # Per-session WebSearch cap (default 200; v2.1.212+)[^206]
CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS=900000        # WebFetch per-URL session cache TTL (default 15 min; v2.1.233+)[^226]
CLAUDE_CODE_WEBFETCH_DEADLINE_MS=300000         # WebFetch hard deadline: a server that never finishes its response fails the fetch after 300s by default; 0 disables (v2.1.268+)[^252]
CLAUDE_CODE_PROJECT_DIR_NAME=myproj             # Short name for the per-project transcript directory, for hosts that give each session its own config dir (v2.1.234+)[^227]
CLAUDE_CODE_GOAL_CHECKIN_MINUTES=30             # How long background tasks may keep a /goal waiting before Claude checks in on them; 0 disables (v2.1.234+)[^227]
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200       # Per-session subagent-spawn cap (default 200 in v2.1.212–223; the default cap was REMOVED in v2.1.224 — set this to reimpose one)[^206][^218]
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20         # Cap on concurrently-RUNNING subagents (default 20; distinct from the per-session total above; v2.1.217+)[^211]
CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0        # Disable the v2.1.229 workflow fan-out stagger (same-prefix sibling agents launch staggered so they read the cached prompt prefix instead of re-paying it)[^224]
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=64   # Raise the Workflow tool's per-run concurrent agent limit, 1-256, for inference-bound fan-outs (v2.1.269+)[^252]
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3          # Nested subagent spawn depth. Default 3 as of v2.1.219; set 1 to disable nesting. Default history: 5 (v2.1.172–v2.1.216) → 1 (v2.1.217) → 3 (v2.1.219). Set it explicitly[^211][^213]

Configuración de herramientas:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Read-back window from the Bash working output file (default 30,000 chars, hard ceiling 150,000)
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=120000       # Threshold before a long MCP tool call moves to the background (default 2 min; v2.1.212+)[^206]
CLAUDE_CODE_MCP_STARTUP_WAIT_MS=10000           # Bound how long the FIRST non-interactive turn waits for still-connecting MCP servers; 0 = don't wait (v2.1.274+)[^254]
CLAUDE_CODE_TOOL_MEMORY_LIMIT=4096              # Opt-in Linux memory cgroup (MB) for Bash tool commands — a runaway build can't stall the session (v2.1.233+)[^226]
CLAUDE_CODE_ENABLE_TODO_TOOLS=1                 # Offer the TodoWrite/TaskCreate-family tools on models outside v2.1.268's allowlist (Claude 3.x, Opus 4.0-4.7, Sonnet 4.0-4.6, Haiku 4.5); elsewhere they are off unless set (first turned off on newer models in v2.1.233)[^226][^252]
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

Red y proxy:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

UI y terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory; not settable from project-settings env (v2.1.251)[^238]
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory; not settable from project-settings env, nor are TMPDIR/TMP/TEMP (v2.1.251)[^50][^238]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Hold ALL native-1M models to 200K via auto-compaction (v2.1.223 widened scope)[^103][^217]
CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1  # Let unrecognized model IDs exceed the assumed context window (v2.1.223)[^217]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Enable Windows PowerShell tool on Linux/macOS (requires pwsh on PATH; v2.1.111+)[^153]
CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1           # Disable mouse click/drag/hover in fullscreen mode; wheel scroll still works (v2.1.195+)[^196]
CLAUDE_ENABLE_STREAM_WATCHDOG=0              # Disable the streaming idle watchdog (on by default for all providers since v2.1.196: aborts+retries after 5 min of silence)[^198]
CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1 # Turn off automatic memory-pressure reaping of idle background shell commands (v2.1.193+)[^196]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
CLAUDE_CODE_BG_TASKS_REPORT_RUNNING=0         # Restore pre-v2.1.269 behavior: remote/headless sessions may report "waiting for your input" while background agents still run[^252]
CLAUDE_AX_SCREEN_READER=1                     # Enable screen reader mode; same as --ax-screen-reader or "axScreenReader": true (v2.1.208+)[^203]
OTEL_LOG_RAW_API_BODIES=1                     # Emit full API request/response bodies as OTel log events (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

Exportadores de OpenTelemetry + control de campos sensibles:²⁴⁶

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter (supports 'none' for disable; v2.1.85 fixed crash)
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in to emitting tool content in OTel spans (v2.1.101+, sensitive by default)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in to tool_parameters in OTel tool_result events (v2.1.85+); as of v2.1.273 also puts real agent, skill, plugin, and MCP server names on cost and token metrics[^253]
OTEL_LOG_USER_PROMPTS=1                       # Opt in to emitting user prompts in OTel traces (v2.1.101+, sensitive by default)
OTEL_LOG_ASSISTANT_RESPONSES=0                # Gate the claude_code.assistant_response log event holding the model's response text (v2.1.193+)
OTEL_METRICS_INCLUDE_REPOSITORY=1             # Tag OTel metrics and events with vcs.* repository attributes; with OTEL_LOG_TOOL_DETAILS, commit events carry vcs.ref.head.* (v2.1.269+)[^252]
CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH=60000     # Truncation limit for OTel content attributes (default 60 KB; v2.1.214+)[^207]
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # Disable release-notes fetch (v2.0.17+); v2.1.110 also stopped the auto-title Haiku request in headless/SDK when set

Atributos de span de solicitudes LLM en v2.1.121+: stop_reason, gen_ai.response.finish_reasons y user_system_prompt ahora se emiten en los spans de solicitud LLM. user_system_prompt está condicionado a OTEL_LOG_USER_PROMPTS=1, ya que puede contener información personal identificable (PII).¹⁵⁴

Cambios a nivel de evento en v2.1.122+: Los atributos numéricos de los eventos de log api_request y api_error ahora se emiten como números (antes eran cadenas de texto), lo que corrige los colectores OTel posteriores que tipaban el esquema de forma estricta. El nuevo evento de log claude_code.at_mention se dispara cuando Claude Code resuelve una mención con @.¹⁵⁴

Evento de log claude_code.assistant_response en v2.1.193+: Claude Code puede emitir el texto completo de la respuesta del modelo como evento de log de OTel, condicionado a OTEL_LOG_ASSISTANT_RESPONSES. Ese control tiene un detalle de actualización que conviene conocer: cuando OTEL_LOG_ASSISTANT_RESPONSES no está definido, sigue a OTEL_LOG_USER_PROMPTS, así que cualquier despliegue que ya registre el contenido de los prompts empezará a recibir el contenido de las respuestas del asistente al actualizar. Define OTEL_LOG_ASSISTANT_RESPONSES=0 para mantener la telemetría solo con los prompts.¹⁷⁹

Adiciones de telemetría en v2.1.214: Los eventos de log de OTel ahora llevan los atributos message.uuid, client_request_id y tool_source para correlación a nivel de mensaje y procedencia de herramientas; el payload de subagentStatusLine incluye el esfuerzo de razonamiento del subagente, de modo que las filas personalizadas de la status line pueden mostrar modelo y esfuerzo juntos; y la nueva variable de entorno CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH configura el límite de truncado de 60 KB en los atributos de contenido de OTel.¹⁹⁰

Telemetría del gateway en v2.1.265: Las sesiones del gateway de apps de Claude ahora exportan OpenTelemetry directamente a un colector cuando la configuración gestionada del gateway nombra uno en OTEL_EXPORTER_OTLP_ENDPOINT, en lugar de enrutarlo a través del relay del gateway; las sesiones sin un colector nombrado siguen usando el relay. La misma versión agrega user.email y user.groups a la telemetría que Claude Desktop y Cowork envían a través de un gateway de apps de Claude, igualando a las sesiones de terminal.²¹⁵

API / Control de modelos:²⁴⁶

CLAUDE_CODE_EXTRA_BODY='{...}'                # Inject extra body fields into API calls; v2.1.113 fixed 400 errors with output_config.effort on Vertex/subagent calls
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Override max context tokens (pre-existing var; v2.1.98 fixed handling of DISABLE_COMPACT when both are set)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Override default token limit for file read operations (v2.1.0+)
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Do not fall back to non-streaming API on streaming failures (v2.1.83+)
ANTHROPIC_BETAS=beta1,beta2                   # Enable beta API headers; v2.1.78 fixed silent ignore on Haiku models
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # Fast model ID (Bedrock ARN supported; v0.2.125 stopped escaping slashes in ARN)

Plugins / MCP:²⁴⁶

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Plugin cache directory (v2.1.72 fixed literal '~' dir on some shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserve plugin marketplace cache when git pull fails (offline-friendly; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Passed to MCP headersHelper scripts so one helper can serve multiple servers (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Passed to MCP headersHelper scripts alongside the name (v2.1.85+)
MCP_SDK_GENERATION=v1                         # Opt out of the v2 MCP client; v2.1.274 made v2 the default on the last holdouts (Bedrock/Vertex/Foundry + telemetry-disabled installs)[^254]
MCP_PROTOCOL_NEGOTIATION=legacy               # Opt out of MCP 2026-07-28 protocol negotiation with direct HTTP servers (default everywhere as of v2.1.274)[^254]

Shell / IDE:²⁴⁶

CLAUDE_CODE_SHELL_PREFIX="time "              # Wrap every Claude-invoked shell command with a prefix (v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Custom Git Bash path on Windows (v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK: exit after N ms idle (v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # Disable IDE auto-connection (v1.0.61+)

Empresa / autenticación:²⁴⁶

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Opt into proxy-side DNS resolution (v2.0.55 moved this from default-on to opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL for dynamically generated API keys via apiKeyHelper (apiKeyHelper refresh added v0.2.74 with 5-min default; env var added v0.2.117)
CLAUDE_CODE_PROCESS_WRAPPER=/path/to/wrapper  # Route all Claude Code self-spawned processes through a wrapper executable; same as the processWrapper setting (v2.1.208+)[^203]

Variables de skills (v2.1.69+):

${CLAUDE_SKILL_DIR}                            # Self-reference for skills to locate their own directory[^117]

Identidad del invocador de SDK (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=user@example.com        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

Depuración:

ANTHROPIC_LOG=debug                             # Enable API request logging

¿Qué modelo debería elegir?

Elegir el modelo adecuado para cada tarea influye considerablemente tanto en el costo como en la calidad. Claude Code permite cambiar de modelo con flexibilidad en varios niveles.

Modelos disponibles

Dos cambios incompatibles al migrar un entorno de Opus 4.8 a Opus 5:¹⁹⁷

1. El razonamiento está activado de forma predeterminada. En Opus 4.8, una solicitud sin el campo thinking se ejecutaba sin razonamiento; en Opus 5, esa misma solicitud se ejecuta con razonamiento adaptativo. max_tokens sigue siendo un límite estricto para la salida total —el razonamiento más el texto de la respuesta—, por lo que debes volver a comprobar el margen disponible en cualquier carga de trabajo que antes se ejecutara sin razonamiento. Usa thinking: {type: "disabled"} para restablecer el comportamiento anterior, sujeto a la siguiente condición.
2. Al desactivar el razonamiento, el esfuerzo queda limitado a high. Combinar thinking: {type: "disabled"} con el esfuerzo xhigh o max devuelve un error 400. La validación se aplica a cada solicitud: aumentar el esfuerzo a xhigh mientras el razonamiento está desactivado se rechaza, aunque se hayan aceptado turnos anteriores de la misma conversación.

Específicamente en Claude Code: el valor predeterminado de effort es high en Opus 5 (al igual que en Claude API) y está disponible toda la escala: low, medium, high, xhigh, max. La propia guía de migración de Anthropic recomienda probar el esfuerzo max cuando la capacidad importe más que el consumo de tokens. El modo rápido incluye Opus 5 a $10/$50 por MTok (consulta Modo rápido).¹⁹⁷¹⁹⁸

Claude Fable 5.1 (1 de septiembre de 2026): Es el nuevo modelo insignia del nivel Fable y, desde la versión v2.1.257, el modelo al que apunta el alias fable (a menos que ANTHROPIC_DEFAULT_FABLE_MODEL fije otro); ahora best significa «el modelo Fable más reciente disponible para ti». La versión mínima requiere una aclaración: la documentación de configuración de modelos indica que el alias cambió en la versión v2.1.255 y la página del modelo afirma que Fable 5.1 «requiere Claude Code v2.1.255 o una versión posterior», pero las versiones 2.1.253-256 nunca se publicaron en npm – v2.1.257 (1 de septiembre) es la primera versión instalable que lo incluye. ID del modelo: claude-fable-5-1 (Bedrock: anthropic.claude-fable-5-1). Conserva el mismo nivel y precio por token que Fable 5 – $10/MTok de entrada, $50/MTok de salida, contexto de 1M, salida máxima de 128K, razonamiento adaptativo siempre activo y valor predeterminado high para effort –, con un cambio de precio importante para las sesiones largas con agentes: las lecturas de caché cuestan $0.25/MTok, 0.025 veces el precio de entrada (2.5%), frente al 10% estándar; solo Fable 5.1 y Mythos 5.1 tienen esa tarifa, mientras que las escrituras en caché conservan la tarifa estándar ($12.50 por 5 minutos y $20 por 1 hora). Fecha límite de conocimiento fiable: junio de 2026 (los datos de entrenamiento también llegan hasta junio de 2026) – la más reciente entre todos los modelos actuales de Claude. No se retirará antes del 1 de septiembre de 2027. Presenta tres cambios incompatibles respecto de Fable 5: forzar el uso de herramientas devuelve un error, los modelos anteriores no pueden leer sus bloques de razonamiento y editar turnos anteriores invalida los bloques de razonamiento. También incorpora cinco cambios: esfuerzo por mensaje (beta), mensajes del sistema limitados al turno (beta), actualizaciones de progreso entre llamadas a herramientas (display: "updates", beta), lecturas de caché más económicas y procedencia del contenido. Claude Mythos 5.1 es el mismo modelo con las mismas especificaciones, disponible únicamente por invitación mediante Project Glasswing. Con este lanzamiento, Fable 5 pasa a la tabla de modelos heredados de la documentación, junto con Opus 4.8/4.7/4.6/4.5 y Sonnet 4.6/4.5. Las notas de la versión señalan una salvedad relacionada con la puerta de enlace: en las sesiones de la puerta de enlace de las aplicaciones de Claude, fable y best siguen apuntando por ahora a Fable 5 – una puerta de enlace que todavía no esté configurada para la versión 5.1 la rechazará –, así que selecciona Fable 5.1 explícitamente en /model; ten en cuenta que, antes de la versión v2.1.260, el selector de /model no mostraba Fable 5.1, por lo que seleccionarlo de forma explícita exigía escribir el comando completo /model claude-fable-5-1 (consulta las correcciones posteriores al lanzamiento más abajo). Los modelos predeterminados de cada plan no cambian: Opus 5 en los planes prémium y Sonnet 5 en Pro y Team Standard.^211219220

Correcciones posteriores al lanzamiento de Fable 5.1 (v2.1.260, 3 de septiembre): la primera versión posterior al lanzamiento corrige cuatro problemas iniciales. Ahora el selector de /model muestra Fable 5.1 para las organizaciones que pueden utilizarlo – antes de esta corrección, el modelo solo se aceptaba al escribir su nombre completo como /model claude-fable-5-1. Ahora, el almacenamiento en caché de instrucciones en Fable 5.1 incluye el contexto adjunto después de los resultados de las herramientas, que antes se reenviaba como entrada no almacenada en caché en cada turno con una llamada a una herramienta – lo que reducía discretamente las ventajas económicas de la tarifa de lectura de caché de 0.025 veces justo en las sesiones largas con agentes para las que existe. Cambiar /effort durante una sesión ya no invalida la caché de instrucciones. Además, los agentes con model: fable ahora respetan la etiqueta [1m] en un modelo fijado mediante ANTHROPIC_DEFAULT_FABLE_MODEL, en lugar de ejecutarse silenciosamente con una ventana de contexto de 200K.²¹²

Claude Fable 5 (9 de junio de 2026; heredado desde el 1 de septiembre de 2026): Un nuevo nivel de modelos superior a Opus — el modelo más potente e inteligente de Anthropic, con resultados de vanguardia en casi todas las pruebas comparativas en las que se ha evaluado y diseñado para mantener la coherencia a lo largo de millones de tokens de contexto. Fable 5 es el modelo de frontera de «clase Mythos» adaptado para un uso general seguro: incluye clasificadores de seguridad que recurren a Opus 4.8 para consultas sobre ciberseguridad, bioquímica y destilación de modelos (Claude Mythos 5 es el mismo modelo, pero sin esas salvaguardas para investigadores autorizados). Se pudo seleccionar en Claude Code a partir de la versión v2.1.170 (9 de junio de 2026) — ejecuta claude update y, luego, /model fable (el alias corto, que desde la versión v2.1.257 apunta a Fable 5.1 – actualmente, selecciona Fable 5 con /model claude-fable-5) —, y su implementación en los planes de suscripción se completó el 22 de junio de 2026. ID del modelo: claude-fable-5. Fable 5 incluye una ventana de contexto de 1M de forma predeterminada, por lo que el sufijo [1m] es innecesario; además, desde la versión v2.1.173 (11 de junio de 2026), el nombre de modelo claude-fable-5[1m] se normaliza automáticamente a claude-fable-5 eliminando el sufijo (este solo tuvo utilidad para Opus/Sonnet, que condicionan el contexto de 1M al uso de [1m]); la salida máxima es de 128K. El precio es de $10/MTok de entrada y $50/MTok de salida — aproximadamente el doble que Opus 4.8 —, así que resérvalo para razonamientos verdaderamente difíciles, no para ediciones rutinarias. Comparte la interfaz de solicitudes de Opus 4.8 (solo razonamiento adaptativo; se eliminaron temperature/top_p/top_k y budget_tokens), con una particularidad nueva: usar explícitamente thinking: {type: "disabled"} devuelve un error 400, así que omite por completo el parámetro thinking para ejecutar el modelo sin razonamiento.²³⁹ En Claude Code específicamente: Fable 5 admite toda la escala de esfuerzo (low/medium/high/xhigh/max, con high de forma predeterminada), al igual que Opus 5. El thinking no se puede desactivar en Fable 5: el interruptor de thinking de la sesión, la configuración alwaysThinkingEnabled y MAX_THINKING_TOKENS=0 no tienen ningún efecto; siempre razona de forma adaptativa. Una superficie de configuración completa para la familia fable refleja los controles de Opus: ANTHROPIC_DEFAULT_FABLE_MODEL fija el modelo al que resuelve el alias fable (útil en Bedrock/Vertex/Foundry), DISABLE_PROMPT_CACHING_FABLE excluye a Fable del almacenamiento en caché de prompts y la conmutación automática por error basada en el contenido se aplica en las puertas de enlace empresariales. /model opus ahora selecciona Opus 5 (esfuerzo high de forma predeterminada, /effort xhigh para las tareas más difíciles), y la configuración predeterminada inicial depende de tu plan: Opus 5 en los planes premium y Sonnet 5 en Pro/Team Standard; selecciona deliberadamente el nivel Fable mediante /model fable cuando quieras la capacidad máxima absoluta, que desde la versión v2.1.257 corresponde a Fable 5.1.^239197207220

Opus 4.7 (16 de abril de 2026): El modelo insignia de la generación anterior, que sigue estando disponible por completo. Ventana de contexto de 1 millón de tokens con precios estándar, sin recargo por contexto largo. Salida máxima de 128K, solo thinking adaptativo (se eliminó extended thinking) y un nuevo nivel de esfuerzo xhigh, recomendado como punto de partida para programación y cargas de trabajo con agentes.¹⁴⁵ Fecha límite de conocimiento fiable: enero de 2026. Fecha límite de los datos de entrenamiento: enero de 2026. ID del modelo: claude-opus-4-7. Su precio coincide con el de Opus 4.6: $5/$25 por MTok, con escritura en caché de 5 minutos por $6.25, escritura en caché de 1 hora por $10 y lectura de caché por $0.50 por MTok.¹⁴⁴ Opus 4.7 resuelve 3 veces más tareas de producción en SWE-Bench que Opus 4.6, obtiene un 70% en CursorBench (frente al 58% de 4.6) y eleva la tasa de resolución un 13% en el benchmark interno de programación de 93 tareas de Anthropic.¹⁴⁴ Utiliza un nuevo tokenizador: para el mismo texto, espera aproximadamente entre 1× y 1,35× tokens; aumenta el margen de max_tokens y los umbrales que activan la compactación.¹⁴⁵ La función de visión admite imágenes de hasta 2.576 px/3,75 MP con coordenadas de píxeles 1:1.¹⁴⁵

Benchmarks de programación de Opus 4.7 (abril de 2026):¹⁵¹

Modelo predeterminado según el plan (Claude Code):²⁰⁷

Cambios incompatibles de Messages API en Opus 4.7 (visibles para quien realiza la llamada):¹⁴⁵

• Se eliminó budget_tokens de extended thinking. Usa thinking: {type: "adaptive"} en su lugar. El thinking adaptativo está desactivado de forma predeterminada; las solicitudes sin el campo thinking se ejecutan sin thinking.
• Establecer temperature, top_p o top_k en un valor distinto del predeterminado devuelve HTTP 400. Omite estos parámetros y orienta el modelo mediante prompts.
• El contenido de thinking se omite de las respuestas de forma predeterminada. Establece thinking.display: "summarized" para volver a mostrar el razonamiento (obligatorio si tu producto transmite el thinking a los usuarios).

Los presupuestos de tareas (encabezado beta task-budgets-2026-03-13) permiten indicarle al modelo un objetivo de tokens para todo un ciclo con agentes mediante output_config.task_budget; el mínimo es de 20K tokens.¹⁴⁵

Opus 4.6 (heredado): Sigue disponible como claude-opus-4-6, con 1 millón de tokens de contexto y una salida máxima de 128K. Considera migrar a Opus 4.7 para obtener un mejor rendimiento en programación con agentes. Opus 4.6 se lanzó originalmente el 5 de febrero de 2026.⁷⁹¹⁴⁴ Desde v2.1.117 (22 de abril de 2026), los suscriptores de Pro y Max usan de forma predeterminada el esfuerzo high en Opus 4.6 y Sonnet 4.6 (antes era medium); Opus 4.7 se mantiene en xhigh. Este cambio restauró la inteligencia tras la reducción de esfuerzo del 4 de marzo al 7 de abril, documentada en el análisis retrospectivo del 23 de abril.¹⁵²¹⁵³

Sonnet 5 (30 de junio de 2026): El nivel Sonnet actual, presentado como «la mejor combinación de velocidad e inteligencia». Anthropic afirma que su rendimiento es cercano al de Opus 4.8, pero a precios más bajos, y que representa una mejora sustancial frente a Sonnet 4.6 en razonamiento con agentes, uso de herramientas, programación y trabajo intelectual; al mismo tiempo, presenta una tasa general menor de comportamientos indeseables y una capacidad de ciberseguridad mucho más limitada que los modelos Opus (la concesión en materia de seguridad que permitió lanzarlo sin bloqueos por controles de exportación). ID del modelo: claude-sonnet-5 (instantánea fija sin fecha). Ventana de contexto de 1 millón de tokens, salida máxima de 128K (hasta 300K en Batches API con el encabezado beta output-300k-2026-03-24) y solo thinking adaptativo. Fecha límite de conocimiento fiable: enero de 2026. Precio: $2/$10 por MTok de entrada/salida, ahora el precio de lista estándar. Anthropic anunció $2/$10 en el lanzamiento como precio introductorio hasta el 31 de agosto de 2026 y luego lo mantuvo: la página de precios indica que el aumento a $3/$15 previsto para el 1 de septiembre «no se llevará a cabo», y v2.1.243 actualizó el selector /model y el skill claude-api incluido para mostrar $2/$10 como precio de lista, en lugar de una promoción temporal.²²⁹ Es un 60% menos que los $5/$25 de Opus 5. En Claude Code, el parámetro effort usa high de forma predeterminada en Sonnet 5 (establécelo explícitamente para cambiarlo). Selecciónalo con /model sonnet (o /model claude-sonnet-5).¹⁸⁰ v2.1.197 (30 de junio de 2026) convirtió a Sonnet 5 en el modelo predeterminado de Claude Code para las sesiones nuevas en ese momento; hoy sigue siendo el predeterminado en el nivel estándar (Pro, Team Standard), mientras que los planes premium y Anthropic API usan Opus 5 de forma predeterminada; consulta la tabla de planes anterior.¹⁸¹²⁰⁷

Sonnet 4.6 (17 de febrero de 2026, ahora reemplazado por Sonnet 5): Modelo equilibrado; reemplazó a Sonnet 4.5 como opción predeterminada en claude.ai y Claude Cowork.⁹³ Mismo precio que Sonnet 4.5 ($3/$15 por MTok). Mejor rendimiento de búsqueda con agentes y menor consumo de tokens. Admite extended thinking, thinking adaptativo y una ventana de contexto de 1 millón de tokens (beta). Salida máxima de 64K (límite superior de 128K en v2.1.77).¹¹⁹ Fecha límite de conocimiento: agosto de 2025 (fiable), enero de 2026 (datos de entrenamiento). ID del modelo: claude-sonnet-4-6.

Claude Mythos Preview (7 de abril de 2026): Un modelo de frontera en versión preliminar de investigación para tareas de ciberseguridad defensiva, ofrecido mediante Project Glasswing.¹³⁹ Solo está disponible por invitación, no para el público general. Anthropic presenta a Opus 4.7 como deliberadamente menos capaz que Mythos en aspectos de ciberseguridad —una concesión en materia de seguridad— y abrió un Cyber Verification Program en https://claude.com/form/cyber-use-case para investigadores de seguridad legítimos que necesiten acceso ampliado.¹⁴⁶

Por qué importan estas diferencias de precio: Una sesión de programación típica consume entre 50K y 200K tokens de entrada y entre 10K y 50K tokens de salida. Con Haiku, eso cuesta entre $0.10 y $0.45 por sesión. Con Opus, la misma sesión cuesta entre $0.50 y $2.25, es decir, 5 veces más. Reserva Opus para problemas realmente difíciles.¹

Cuándo usar cada modelo

Haiku: Úsalo para subagents que realizan exploraciones, búsquedas sencillas de archivos y consultas rápidas. Es aproximadamente 5 veces más barato que Opus y responde con mayor rapidez. Es perfecto para tareas en segundo plano que no requieren un razonamiento profundo. Sonnet: El modelo de batalla para el desarrollo diario cuando el costo importa, y el modelo predeterminado en el nivel estándar, Pro y Team Standard (contexto nativo de 1M, $2/$10 por MTok como precio de lista estándar; el aumento previsto para el 1 de septiembre fue cancelado).^181229207 Se encarga de la mayoría de las tareas de programación: implementar funciones, corregir errores, escribir pruebas y revisar código. Antecedentes: durante mucho tiempo se informó —incluso aquí— que v2.1.197 (30 de junio de 2026) convirtió a Sonnet 5 en el modelo predeterminado en todos los niveles, pero la documentación de configuración de modelos indica que el valor predeterminado de premium/API, según el plan, corresponde a Opus 4.8 desde v2.1.154 y a Opus 5 desde v2.1.219, por lo que «todos los niveles» en realidad se refería al nivel estándar. Sonnet 4.6 desempeñó la función de Sonnet hasta junio de 2026.^93147207 Usa Sonnet cuando necesites tokens más económicos, menor latencia o costos más convenientes para los subagents.

Opus: El nivel de razonamiento profundo; desde v2.1.219, el alias opus selecciona Claude Opus 5 ($5/$25 por MTok, contexto de 1M y effort configurado de manera predeterminada en high).¹⁹⁷ El párrafo siguiente describe Opus 4.7 cuando se lanzó el 16 de abril de 2026 y se conserva como referencia histórica.¹⁴⁴¹⁴⁷ Reserva el razonamiento de mayor costo para los casos en los que realmente compense: decisiones de arquitectura, depuración compleja, comprensión de sistemas complejos, análisis de seguridad y trabajo agéntico de largo alcance. Opus 4.7 resuelve 3 veces más tareas de producción en SWE-Bench que Opus 4.6, obtiene un 70 % en CursorBench (frente al 58 %) y mejora un 13 % la tasa de resolución en una evaluación interna de programación con 93 tareas.¹⁴⁴ Claude Code usa de manera predeterminada el nivel de esfuerzo xhigh con Opus 4.7, que puedes ajustar mediante /effort (v2.1.111+).¹⁴⁶¹⁴⁷ Auto Mode está disponible para suscriptores de Max con Opus 4.7 mediante Anthropic API, sin necesidad de usar --enable-auto-mode; en otros planes y proveedores, la disponibilidad depende del plan y de los controles del administrador.¹⁴⁶ Contexto de 1M con el precio estándar, sin recargo por contexto largo. Cambios de comportamiento que conviene conocer: Opus 4.7 sigue las instrucciones de manera más literal, adapta la extensión de sus respuestas a la complejidad de la tarea, ejecuta menos subagents de forma predeterminada y adopta un tono más directo, con menos expresiones orientadas a validar al usuario. Si tus prompts incluyen instrucciones auxiliares para forzar mensajes provisionales de progreso o comprobaciones adicionales, prueba eliminarlas.¹⁴⁵

Opusplan: Un modo híbrido que usa Opus para la planificación (donde más importa la calidad del razonamiento) y Sonnet para la ejecución (donde importa la velocidad). Es excelente para refactorizaciones complejas en las que quieres el mejor plan, pero no necesitas razonamiento al nivel de Opus para cada modificación individual.

Cambiar de modelo

Durante una sesión:

> /model opus
> /model sonnet
> /model haiku

Al iniciar:

claude --model opus

Mediante el entorno:

export ANTHROPIC_MODEL=opus

En settings.json:

{
  "model": "claude-sonnet-5"
}

Personaliza el selector (modelPicker, v2.1.242+): un archivo de configuración del usuario o administrado puede enumerar los modelos que ofrece /model, en el orden que elijas y con tus propias etiquetas, en lugar de limitar el menú a la selección integrada. Cada fila especifica un model (cualquier formato que acepte --model, incluidos los ID de Vertex y Bedrock), con label y description opcionales; configura replaceBuiltInOptions como true para mostrar únicamente esas filas, además de Default y el modelo actual de la sesión. La configuración del proyecto y la local se ignoran para esta clave, y una lista de permitidos availableModels sigue filtrando las filas. Claude Code descarta las filas correspondientes a modelos que no puede proporcionar, muestra en gris las que todavía no puedes seleccionar junto con el motivo y vuelve a la selección integrada si no queda ninguna fila disponible.²²⁸²²⁶

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

Específicamente para subagents:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

A partir de v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL establece el modelo predeterminado de los subagents en lugar de anular todas las demás opciones: el valor model: de la definición de un agente y un modelo indicado explícitamente al crear cada instancia tienen prioridad.²⁰⁶ A partir de v2.1.257, CLAUDE_CODE_SUBAGENT_MODEL_FORCE permite recuperar voluntariamente el comportamiento anterior: aplica CLAUDE_CODE_SUBAGENT_MODEL (o el modelo de la conversación principal cuando esa variable no está configurada) a todos los subagents e ignora las selecciones realizadas al crear cada instancia y el valor model: de las definiciones de agentes.²¹¹

Cadena de modelos alternativos (v2.1.166+): la opción fallbackModel permite configurar hasta tres modelos alternativos, que se prueban en orden cuando el modelo principal está sobrecargado o no está disponible. La opción --fallback-model (que antes solo permitía cambiar de modelo durante una sesión) ahora también se aplica desde el inicio a las sesiones interactivas.²⁴¹

{
  "model": "claude-opus-4-8",
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

Cuando API devuelve un error inesperado que no admite reintentos, Claude Code también vuelve a intentar una vez el turno con el modelo alternativo antes de mostrar el fallo, de modo que un problema transitorio del modelo principal se resuelve de forma gradual en lugar de descartar el turno.²⁴¹

A partir de v2.1.178, la compactación también respeta la cadena de modelos alternativos: si el modelo principal está sobrecargado o deja de estar disponible durante la compactación, este paso recurre a la cadena configurada mediante fallbackModel/--fallback-model en lugar de hacer que falle el turno. En una ejecución autónoma prolongada, esto elimina el problema por el cual una compactación que podría haberse recuperado hacía perder la sesión debido a un error transitorio del modelo.¹⁷³

Contexto extendido

Para bases de código grandes o sesiones prolongadas, habilita el contexto de 1M tokens:

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.7 with 1M context

O durante una sesión:

> /model sonnet[1m]
> /model opus[1m]

Opus 4.7, Opus 4.6 y Sonnet 4.6 incluyen la ventana de contexto completa de 1M tokens con el precio estándar, sin recargo por contexto largo.¹⁴⁸ Una solicitud de 900K tokens se factura con la misma tarifa por token que una de 9K tokens. Los descuentos por almacenamiento en caché de prompts y procesamiento por lotes se aplican con las tarifas estándar en toda la ventana de contexto.

En las suscripciones Max, Team y Enterprise, Opus con contexto de 1M se incluye automáticamente, sin necesidad del sufijo [1m] (habilitado de manera predeterminada desde v2.1.75, el 13 de marzo de 2026).¹¹⁷¹⁴⁷ En Pro, puedes acceder al contexto de 1M mediante el uso adicional. Los usuarios de API y de pago por uso disponen de acceso completo a 1M con las tarifas estándar por token.¹⁴⁷

Para deshabilitar las variantes de contexto de 1M en el selector de modelos, configura CLAUDE_CODE_DISABLE_1M_CONTEXT=1. A partir de v2.1.223, cambió el alcance de la variable: mediante la compactación automática, limita a 200K todos los modelos que tengan una ventana nativa de 1M, no solo una lista fija de variantes conocidas, y muestra una advertencia al iniciar cuando la compactación automática no mantiene realmente la sesión dentro del límite de 200K. Si configuras esta variable para obtener costos predecibles con una familia de modelos, ahora también limita los nuevos modelos de 1M desde el día de su lanzamiento, en lugar de dejar de aplicarse silenciosamente. La misma versión hace que la compactación automática mantenga las sesiones con ID de modelos no reconocidos dentro de la ventana de contexto estimada, en lugar de permitir que la superen; CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 restaura el comportamiento anterior para las puertas de enlace que registran ID personalizados con ventanas reales más grandes.²⁰⁰

A partir de v2.1.247, la ventana predeterminada de compactación automática de Sonnet 5 abarca su contexto completo de 1M: las sesiones que usan la ventana de 1M ahora se compactan automáticamente al llegar aproximadamente a 967K tokens, en lugar de hacerlo alrededor de los 934K.²²³ v2.1.260 extiende la compactación automática cerca del límite al resto del nivel de 1M: las sesiones de Opus y Fable ahora también se compactan poco antes de alcanzar el límite de 1M tokens, y la compactación de recuperación en contextos muy grandes ya no agota el tiempo de espera a los 10 minutos.²¹²

A partir de v2.1.271, --resume conserva la ventana [1m]: reanudar una sesión cuya familia de modelos difiere del modelo predeterminado configurado ya no elimina el sufijo [1m].²¹⁶

v2.1.273 corrige el medidor de contexto y la compactación automática, que contabilizaban los turnos de la herramienta de asesoría aproximadamente al doble de su tamaño real de contexto; la compactación automática se activaba al llegar aproximadamente a la mitad de la ventana real.²¹⁷

Consultar el modelo actual

> /status

El comando muestra el modelo actual, la información de la cuenta, la configuración aplicada y otros datos del estado de la sesión.

Etiquetas del selector de modelos (v2.1.51+): el selector /model ahora muestra etiquetas legibles (por ejemplo, «Sonnet 4.6») en lugar de ID de modelos sin formato para las versiones fijadas, junto con sugerencias de actualización cuando hay versiones más recientes disponibles.⁹⁸ v2.1.219 corrige la fila combinada de Opus para que aparezca simplemente como «Opus» en lugar de «Opus (contexto de 1M)», y restringe el resaltado de nueva versión únicamente al nombre del modelo más reciente, de modo que indique lo que realmente se lanzó en vez de resaltar una parte arbitraria de la lista.¹⁹⁶

Fast Mode (v2.1.36+)

Fast Mode proporciona resultados considerablemente más rápidos con el mismo modelo; no cambia a un modelo más económico. Actívalo o desactívalo durante una sesión con /fast.⁸⁶

> /fast            # Toggle fast mode on/off

Qué modelos (a partir de v2.1.219): el modo rápido se aplica a Claude Opus 5 y Claude Opus 4.8. v2.1.219 eliminó Opus 4.7 del modo rápido, y la función nunca estuvo disponible en Sonnet, Haiku ni Fable. Sigue siendo una vista previa de investigación disponible únicamente en Claude API (incluidos Claude Managed Agents), no en Amazon Bedrock, Google Cloud, Microsoft Foundry ni Claude Platform on AWS. El acceso está restringido: comunícate con tu gerente de cuenta o únete a la lista de espera.¹⁹⁶¹⁹⁸

Sesiones remotas (v2.1.271): el modo rápido ahora llega a las sesiones de Claude Code Remote, tanto las sesiones en la nube como los runners autohospedados. Se aplica la configuración de modo rápido del host, o puedes escribir /fast en la propia sesión; ambas opciones solo funcionan cuando tu organización permite el modo rápido. La misma versión corrige /fast off: ahora desactiva el modo rápido en lugar de responder “Fast mode unavailable” cuando la organización lo tiene deshabilitado.²¹⁶

Precios (modo rápido de Opus 5 / Opus 4.8):¹⁹⁸

La trampa de Opus 4.7 (v2.1.219). Los modelos no compatibles no se comportan de la misma manera. Una solicitud a claude-opus-4-7 con speed: "fast" ahora devuelve un error; no recurre silenciosamente a la velocidad estándar. Opus 4.6 es la excepción que hace importante conocer este detalle: acepta speed: "fast", pero se ejecuta de todos modos a velocidad estándar, factura con las tarifas estándar e informa usage.speed: "standard". Si tu harness estaba fijado en 4.7 y dependía de que las solicitudes en modo rápido pasaran discretamente al modo estándar, ahora fallarán por completo; cambia la versión fijada a Opus 5 u Opus 4.8.¹⁹⁸

Cuándo usar el modo rápido: - Al iterar rápidamente sobre cambios pequeños cuando la latencia es el cuello de botella - Al generar pruebas, código repetitivo o estructuras base donde la velocidad importa más que el costo - Al trabajar secuencialmente en una lista de tareas similares

Cuándo NO usar el modo rápido: - Tareas agénticas de larga duración (el costo se duplica durante toda la ejecución) - Trabajo de subagents en segundo plano (nadie está esperando el resultado) - Sesiones con un presupuesto limitado

El modo rápido incluye la ventana de contexto completa de 1M (v2.1.50+). El precio aplica un multiplicador fijo a todo el contexto, incluidas las solicitudes con más de 200K tokens de entrada, sin recargo adicional por contexto largo, y se acumula con los multiplicadores del almacenamiento en caché de prompts y la residencia de datos.⁹⁶¹⁹⁸

Notas operativas. El modo rápido tiene su propio límite de tasa, independiente de los límites estándar de Opus; si se supera, devuelve un 429 con retry-after (los encabezados de respuesta anthropic-fast-*-tokens-* indican la capacidad restante). Cambiar entre los modos rápido y estándar invalida la caché de prompts: las solicitudes con velocidades diferentes no comparten prefijos almacenados en caché, por lo que alternar /fast durante una sesión provoca un fallo de caché. El modo rápido no está disponible con Batch API ni con un compromiso de Priority Tier.¹⁹⁸

Consejo experto: El modo rápido no se combina con opusplan (opusplan ya mezcla Opus y Sonnet; el modo rápido solo afecta la parte de Opus). Úsalo cuando la latencia importe más que el costo y desactívalo para trabajos autónomos o por lotes. /fast requiere uso adicional; es posible que los administradores de Team/Enterprise deban habilitarlo primero (corrección de v2.1.37). Desactívalo por completo con CLAUDE_CODE_DISABLE_FAST_MODE=1. A partir de v2.1.218, Claude Code avisa cuando un cambio de modelo mediante /config model=<x> o Remote Control modifica el estado del modo rápido, y v2.1.219 corrigió que los clientes de Remote Control conservaran un estado obsoleto del modo rápido después de cambiar de modelo, volver a conectarse o fallar una comprobación de la organización.^86149195196

Control del esfuerzo (v2.1.111+, Opus 4.7)

Opus 4.7 incorpora un nuevo selector de esfuerzo que ajusta el equilibrio entre velocidad e inteligencia. Usa /effort durante una sesión:

> /effort              # opens an interactive slider (arrow keys + Enter)
> /effort xhigh        # set directly

Guardado por modelo (v2.1.251+): /effort ahora guarda tu nivel de esfuerzo predeterminado por modelo, de modo que cada modelo conserva su propia configuración cuando cambias de uno a otro; así, la costumbre de usar xhigh en Opus ya no te acompaña al pasar a Haiku (CHANGELOG: “Se cambió /effort para guardar tu nivel de esfuerzo predeterminado por modelo, de modo que cada modelo conserve su propia configuración cuando cambias”). La excepción de max, que solo se aplica a la sesión, sigue vigente.²⁰⁶ v2.1.257 perfecciona ambos selectores: /effort acepta s para elegir una opción solo durante la sesión, siguiendo la convención de /model, y el flag --effort ahora se limita a la sesión: suspende la aplicación del esfuerzo predeterminado de un nuevo modelo únicamente durante esa sesión, no de forma permanente (según la referencia de CLI, “reemplaza” el valor predeterminado “para esta sesión y no persiste”).²¹¹²²¹

Auto Mode en Max (v2.1.111+)

Auto Mode es el modo de permisos predeterminado en los planes Pro, Max y Team desde el 14 de agosto de 2026 (anunciado el 7 de agosto); consulta Modos de permisos para conocer las cifras del estudio incluidas en el anuncio, las formas de desactivarlo y los planes y gateways donde todavía debe habilitarse expresamente.²⁰³ Surgió como una alternativa más segura a --dangerously-skip-permissions y estuvo disponible inicialmente para los suscriptores de Max que usaban Opus 4.7 mediante Anthropic API.¹⁴⁶ Un modelo clasificador independiente —Claude Sonnet 5 desde v2.1.210— revisa cada acción antes de ejecutarla para comprobar que coincida con la intención y sea segura.¹⁸⁷ Nota (v2.1.111+): se eliminó el flag --enable-auto-mode; para iniciar una sesión en Auto Mode, usa --permission-mode auto. Pro estuvo excluido durante la mayor parte de la existencia de Auto Mode, una restricción que termina con su implementación predeterminada del 14 de agosto. Bedrock/Vertex/Foundry (v2.1.158+): Auto Mode pasó a estar disponible mediante activación expresa en Opus 4.7 y Opus 4.8 en esos gateways con CLAUDE_CODE_ENABLE_AUTO_MODE=1.²⁴⁴ A partir de v2.1.207, ya no es necesaria la activación expresa: Auto Mode funciona en AWS Bedrock, Google Vertex AI y Microsoft Foundry sin CLAUDE_CODE_ENABLE_AUTO_MODE, y los administradores que quieran deshabilitarlo pueden usar la configuración administrada disableAutoMode. La misma versión hace que Bedrock, Vertex AI y Claude Platform on AWS usen Claude Opus 4.8 de forma predeterminada, y deja de leer la configuración autoMode desde .claude/settings.local.json de un repositorio; configura las reglas de Auto Mode en ~/.claude/settings.json.¹⁸⁵ A partir de v2.1.247, las solicitudes de permisos de Bash incluyen un consejo que apunta a Auto Mode, con la opción de una sola tecla “Sí, y cambiar a Auto Mode”.²²³ A partir de v2.1.273, Auto Mode en Bedrock, Vertex AI y Foundry usa el clasificador local de forma predeterminada “por ahora”; establece CLAUDE_CODE_AUTO_MODE_SERVER=1 para usar el clasificador del lado del servidor de la plataforma. Se trata de un cambio de estado en un aspecto distinto al de la nota sobre los valores predeterminados del clasificador de v2.1.236: local frente al lado del servidor es un mecanismo que las versiones anteriores nunca habían expuesto.²¹⁷ Lo que Auto Mode no es: un límite de seguridad. La mayor parte de lo que sigue refuerza un clasificador, y un clasificador no es un sandbox. El 26 de agosto de 2026, el investigador de inyección de prompts Johann Rehberger publicó una cadena funcional contra Claude Code Opus 5 en auto mode y reportó una tasa de éxito del ataque del 60-80 % en muestras pequeñas: 3 de 5 ejecuciones para la cadena principal, que genera un proceso secundario aislado de python3, y 3 de 5 y 4 de 5 ejecuciones para dos configuraciones de una variante cuya carga útil genera una instancia sin interfaz gráfica de claude -p. Él mismo advierte que se trata de muestras pequeñas y no de una medición universal de la tasa de éxito del ataque.²¹⁰ Vale la pena entender la cadena porque cada paso, por separado, parece razonable: un servidor responde a WebFetch con HTTP 415, por lo que el agente recurre a curl; el archivo comprimido descargado se extrae en un directorio temporal que contiene un manifiesto, siete registros de datos codificados con Base85/zlib, un binario nativo y un archivo struct.py; Claude se niega a ejecutar el binario no confiable y luego escribe su propio decodificador Python y lo ejecuta desde ese directorio; el decodificador importa base64, base64 importa struct y Python resuelve primero el archivo struct.py del atacante. Ninguna instrucción de la secuencia es evidentemente maliciosa: la inyección solo tiene que hacer que la ruta comprometida parezca la forma más razonable de completar la tarea. Rehberger también informa que, en algunas ejecuciones, Claude intentó finalizar el proceso del malware al detectar la intrusión, pero auto mode rechazó el comando de limpieza.²¹⁰ Enmarca todo el hallazgo frente a una cifra que Anthropic ha promocionado: una evaluación encargada a un tercero reportó una tasa de éxito de ataques de inyección de prompts del 0,00 % para Opus 5 en auto mode, en 72 escenarios ejecutados diez veces cada uno. Su cadena no formaba parte de ese conjunto, lo que explica que un resultado de referencia del 0,00 % y una cadena funcional de ejecución de código puedan ser ciertos al mismo tiempo; a su juicio, ambos mensajes son incompatibles.²¹⁰ También conviene observar la clasificación: en su actualización del 30 de agosto, Simon Willison respalda la observación de un lector de que esto no es una inyección de prompts clásica —el modelo nunca lee ni sigue las instrucciones del atacante—, sino un ataque de entorno confuso.²¹⁰

Anthropic cerró el reporte como Informativo —el comportamiento funciona según lo previsto—, y la postura que Rehberger dice haber recibido como respuesta es la que debe orientar el diseño: auto mode es un clasificador de mejor esfuerzo, no una garantía de seguridad; las cadenas de inyección deliberadas, compuestas por pasos individualmente benignos, quedan fuera de lo que cabe esperar que detecte un clasificador; y el verdadero límite de contención es el aislamiento en el nivel del sistema operativo junto con el control del tráfico de red saliente.²¹⁰ Esto no contradice las medidas de refuerzo descritas a continuación; es el marco correcto para entenderlas. Auto mode reduce la cantidad de solicitudes de aprobación que respondes y bloquea una lista documentada de operaciones destructivas, pero no vuelve segura una sesión que procesa entradas no confiables. Si una sesión va a interactuar con contenido influido por atacantes —páginas obtenidas, archivos comprimidos descargados, texto de incidencias o servidores MCP de terceros—, los controles que realmente limitan el daño son los externos al modelo: un contenedor o una máquina virtual, tráfico de red saliente restringido, supervisión de lo que el agente hace realmente y un directorio de inicio que no contenga las claves SSH ni las credenciales de servicios en la nube que no querrías perder. La aprobación de auto mode no demuestra que una acción fuera segura.

Reglas personalizadas sin perder las predeterminadas (v2.1.118+). En versiones anteriores, autoMode.allow, autoMode.soft_deny y autoMode.environment eran mutuamente excluyentes: si definías tu propia lista, perdías las reglas de seguridad integradas. El marcador $defaults resuelve este problema: se expande en línea a la lista integrada exactamente en la posición donde lo colocas, lo que te permite superponer reglas personalizadas alrededor de ella:¹⁵²

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // your additions, prepended
      "$defaults",                // built-in allow list inserted here
      "Bash(git push:origin/feature/*)"  // appended after
    ]
  }
}

Edita las reglas del clasificador desde /permissions (v2.1.246). Ejecuta /permissions y abre la pestaña Auto mode, que solo aparece cuando auto mode está disponible para la sesión. Allí se enumeran las entradas allow, soft_deny, hard_deny y environment de todos los ámbitos que lee el clasificador, y se indica si las reglas integradas están activas en cada sección; las entradas provenientes de la configuración administrada o de --settings son de solo lectura, y todos los cambios se guardan en ~/.claude/settings.json. Al agregar la primera regla a una sección, también se inserta "$defaults" para mantener activas las reglas integradas. Puedes activar o desactivar las reglas integradas de cada sección —una sección necesita al menos una regla propia para poder desactivarlas—, mientras que environment se abre como un único documento en tu editor.²²⁷²²⁵

Opción «Don’t ask again» (v2.1.118+). La solicitud de activación de Auto Mode ahora ofrece la opción «Don’t ask again», para que quienes lo usan con frecuencia puedan ocultar la explicación sin tener que automatizar un flag.¹⁵²

Protecciones contra comandos destructivos (v2.1.183). Auto mode ahora bloquea por completo un conjunto de comandos irreversibles, a menos que los hayas solicitado explícitamente durante la sesión: operaciones destructivas de git (git reset --hard, git checkout -- ., git clean -fd, git stash drop) cuando no pediste descartar el trabajo local; git commit --amend cuando el agente no creó el commit durante esta sesión; y la eliminación de infraestructura (terraform destroy, pulumi destroy, cdk destroy), salvo que hayas indicado el stack específico. Esto reduce el alcance destructivo del clasificador precisamente para las operaciones que pueden provocar la pérdida silenciosa de trabajo o eliminar entornos. El agente aún puede ejecutarlas, pero solo cuando se lo indiques explícitamente, no por iniciativa propia.¹⁷⁴

Clasifica cada comando de shell (v2.1.193). De forma predeterminada, el clasificador de auto mode solo revisa los comandos de shell que coinciden con patrones de ejecución de código arbitrario; los comandos rutinarios no pasan por él. La nueva configuración autoMode.classifyAllShell hace que todos los comandos de Bash/PowerShell pasen por el clasificador, a cambio de un poco más de latencia, cuando quieres que se examine cada llamada al shell. La misma versión también muestra los motivos de rechazo de auto mode en la transcripción, en la notificación de rechazo y en los rechazos recientes de /permissions, de modo que un comando bloqueado ahora explica por qué se bloqueó.¹⁷⁹

Tres reglas adicionales de refuerzo (v2.1.205). Auto mode ahora impide la manipulación de los archivos de transcripción de la sesión: el propio registro de auditoría queda fuera del alcance del agente; solicita aprobación antes de ejecutar rm -rf sobre una variable cuyo valor no puede determinar a partir del contexto, lo que evita la clase de accidentes de rm -rf $DIR con un $DIR desconocido; y las notificaciones de tareas en segundo plano ahora indican explícitamente que no ha habido intervención humana, por lo que una línea falsa de «aprobación del usuario» dentro de una transcripción no puede hacerse pasar por una aprobación válida y ejecutable.¹⁸³ La tercera es una defensa contra la inyección de prompts que conviene interiorizar: la aprobación debe llegar a través del canal de aprobación, y el entorno de ejecución ahora explicita esa premisa.

La sustitución de comandos no puede ocultar una catástrofe (v2.1.208). Las eliminaciones catastróficas como rm -rf ~ ahora solicitan aprobación incluso cuando están ocultas dentro de $(...), acentos graves o sustituciones de procesos (<(...)), y la solicitud aparece incluso en --dangerously-skip-permissions y auto mode. Envolver un comando destructivo en una sustitución ya no permite evadir la protección.¹⁸⁶

Restablece el estado de auto mode: claude auto-mode reset (v2.1.212). Un nuevo subcomando restablece el estado de auto mode desde la terminal; pasa --yes para omitir la solicitud de confirmación:¹⁸⁹

claude auto-mode reset          # Confirmation prompt
claude auto-mode reset --yes    # Skip confirmation (scripts)

Menos cuadros de diálogo, el mismo nivel de escrutinio (v2.1.218). Tres comprobaciones que antes interrumpían auto mode con un cuadro de diálogo de permisos —un rm peligroso, & en segundo plano y rutas sospechosas de Windows— ya no lo hacen; ahora el clasificador de auto mode toma la decisión, por lo que la revisión de seguridad sigue realizándose sin pedirte que intervengas en cada caso. La misma versión también extiende este comportamiento al plan mode con auto: los comandos de Bash que el analizador estático no puede confirmar como de solo lectura ya no solicitan aprobación; el clasificador los evalúa en lugar de recurrir a un cuadro de diálogo.¹⁹⁵

Regla contra escapes de contención (v2.1.257). La lista de acciones que el clasificador nunca aprueba automáticamente incorpora una regla de «Containment Escape»: la obtención de credenciales desde servicios de metadatos en la nube, la evasión de controles del tráfico de red saliente y el acceso entre tenants ya no se aprueban automáticamente, salvo que el entorno los marque como esperados. Interprétalo según el marco establecido por la advertencia anterior: es una medida adicional de refuerzo del clasificador —otra clase documentada de rechazo—, no un cambio en la naturaleza de auto mode.²¹¹ Aviso único al leer fuera de los directorios de trabajo (v2.1.257). Ahora, el modo automático solicita confirmación una vez antes de leer el primer archivo de la sesión que esté fuera de los directorios de trabajo. La configuración complementaria permissions.blockReadsOutsideWorkingDirectories convierte el aviso en un rechazo: esas lecturas se bloquean por completo.²¹¹ v2.1.273 extiende ambos comportamientos a lo que el verificador no puede ver: un comando Bash que no pueda analizar por completo solicita confirmación en lugar de omitir la comprobación, y un directorio de memoria seleccionado mediante la configuración de un repositorio deja de cargarse en el prompt, recuperarse, indexarse o utilizarse para la extracción de memoria cuando está activada la configuración de bloqueo.²¹⁷

Las URL de renderizadores de diagramas cuentan como cargas (v2.1.261). Un enlace que encapsula contenido en la URL de un renderizador público de diagramas —al estilo de mermaid.live, con los datos codificados en la propia URL— ya no se aprueba automáticamente, a menos que lo hayas solicitado. El clasificador considera ese enlace una carga: los datos encapsulados viajan en la propia URL, donde los scripts del sitio del renderizador pueden leerlos una vez abierta la página. En los enlaces al estilo de mermaid.live, la carga útil se incluye en el fragmento de la URL, que el navegador entrega al JavaScript de la página en lugar de enviarlo con la solicitud de red. Se aplica el mismo marco que en la salvedad anterior: es otro canal de exfiltración cerrado por un clasificador reforzado, no un límite nuevo.²¹⁴

El shell ! en línea queda fuera del clasificador; las devoluciones de control de los subagents pasan a formar parte de él (v2.1.271). Se trata de 2 cambios de funcionamiento, no de nuevas clases de denegación. Los comandos de shell ! en línea de una skill o un slash command ahora siguen las reglas de permisos del modo predeterminado en lugar de pasar por el clasificador: si ninguna regla determina qué hacer con un comando, este se ejecuta como una llamada a una herramienta sujeta a revisión. Además, un subagent ahora devuelve el resultado a quien lo invocó mediante una llamada específica de devolución de control que revisa el clasificador de seguridad, en lugar de revisar su último mensaje después del hecho; el punto de control pasó de estar después de la transferencia a formar parte de la propia transferencia.²¹⁶

Nuevos comandos en v2.1.105–v2.1.114¹⁴⁶¹⁵⁰

Notificaciones push (v2.1.110+)

Cuando Remote Control está configurado con la opción «Push when Claude decides» habilitada, Claude puede enviar notificaciones push al dispositivo móvil según su propio criterio mediante una nueva herramienta de notificaciones push. Esto complementa la interfaz móvil y web existente de Remote Control.¹⁴⁶ /context, /exit y /reload-plugins ahora también funcionan desde clientes de Remote Control.

Herramienta nativa de Windows PowerShell (v2.1.111+, implementación gradual)

Claude Code está implementando gradualmente una herramienta nativa de Windows PowerShell. En Linux/macOS, actívala con CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (requiere pwsh en PATH). En Windows, esa misma variable controla la activación o desactivación durante la implementación gradual.¹⁴⁶

Aprobación automática según el modo de permisos (v2.1.119+). Los comandos de la herramienta PowerShell ahora pueden aprobarse automáticamente en el modo de permisos, igual que los comandos Bash. Las reglas de autorización como PowerShell(Get-*:*) y la sintaxis de patrones existente ahora omiten el aviso para las operaciones de solo lectura, lo que ofrece la misma ergonomía operativa que los equipos ya tienen en Linux/macOS.¹⁵²

Reducción de solicitudes de permisos: Bash de solo lectura (v2.1.111+)

Los patrones de Bash de solo lectura con argumentos glob (por ejemplo, ls *.ts, cat src/*.md) y los comandos que comienzan con cd <project-dir> && ya no activan una solicitud de permiso.¹⁴⁶ En combinación con /less-permission-prompts, esto reduce considerablemente las interrupciones en los flujos de trabajo cotidianos.

Rastreo distribuido (v2.1.110+)

Las sesiones de SDK y sin interfaz ahora leen TRACEPARENT y TRACESTATE desde el entorno, lo que vincula las ejecuciones de Claude Code con trazas distribuidas. Combínalo con OTEL_LOG_RAW_API_BODIES=1 (v2.1.111+) para emitir los cuerpos completos de las solicitudes y respuestas de API como eventos de registro de OpenTelemetry con fines de depuración.¹⁴⁶

Distribución mediante binarios nativos (v2.1.113+)¹⁵⁰

v2.1.113 cambia la forma en que se inicia CLI: ahora, claude genera un binario nativo de Claude Code mediante una dependencia opcional específica de cada plataforma, en lugar de ejecutar el JavaScript incluido. Los comandos de instalación y actualización no cambian, y los equipos no necesitan modificar sus scripts de implementación.

Atajos del editor de prompts (v2.1.113+)¹⁵⁰

El editor de prompts incorpora navegación al estilo de readline en entradas multilínea, además de desplazamiento de la ventana gráfica en pantalla completa:

Tiempo de espera por bloqueo de subagents (v2.1.113+)¹⁵⁰

Los subagents que se bloqueen durante una transmisión ahora fallan con un error claro después de 10 minutos, en lugar de quedarse suspendidos sin indicación alguna. Combínalo con CLAUDE_STREAM_IDLE_TIMEOUT_MS (v2.1.84+) para ampliar la cobertura de procesos bloqueados en API con transmisión.

Corrección de estabilidad de v2.1.114¹⁵⁰

v2.1.114 (18 de abril de 2026) incluye una única corrección: el cuadro de diálogo de permisos podía bloquearse cuando un integrante de un equipo de agentes solicitaba permiso para usar una herramienta. Actualiza si utilizas Agent Teams.

Marcado de contenido: marcas de agua en texto y metadatos C2PA en archivos (agosto de 2026)

Anthropic anunció el marcado legible por máquinas para contenido generado por Claude, impulsado por el artículo 50 de la Ley de IA de la UE (aplicable desde el 2 de agosto de 2026 a los sistemas de IA lanzados recientemente). El sistema tiene 2 componentes: una marca de agua estadística invisible en el texto generado y metadatos de procedencia firmados —conforme al estándar abierto C2PA— en archivos generados como .svg, .png y .jpg.²³⁰²⁰⁴ Hay un detalle que los titulares desdibujan: ambos componentes siguen el mismo calendario de modelos. Según la página de soporte, «los modelos de Claude lanzados el 2 de agosto de 2026 o después admitirán el marcado legible por máquinas desde su lanzamiento». Los modelos lanzados antes de esa fecha —es decir, toda la línea actual (Fable 5, Opus 5, Sonnet 5, Haiku 4.5)— están sujetos al período de transición de la legislación de la UE, mientras Anthropic «trabaja para añadir compatibilidad con el marcado también a esos modelos».²⁰⁴ Nada de lo que generes hoy mediante Claude Code incluye una marca, ya sea en texto o en archivos; las salidas de modelos futuros sí la incluirán en todas las interfaces —Claude Platform (API), claude.ai, Claude Code, Claude Cowork, Claude Tag y las puertas de enlace en la nube—, puesto que el marcado se aplica a nivel del modelo. Vale la pena señalar una consecuencia, ya que una publicación viral afirmó lo contrario: cualquier cambio de estilo o comportamiento que percibas en un modelo actual no puede deberse a una marca de agua, pues todavía no está activa en ninguno de ellos.

Cómo funciona: utiliza una variante de SynthID-Text de Google DeepMind. La marca de agua modifica «la fuente de aleatoriedad utilizada para elegir entre palabras» cuando Claude selecciona entre opciones semánticamente equivalentes; no añade caracteres ni aplica procesamiento posterior y, según las pruebas internas de Anthropic, «la marca de agua no afecta el contenido, el nivel de creatividad ni la legibilidad».²³⁰ Lo que les importará a los usuarios de Claude Code: el código lleva una marca de agua discreta. El código funcional deja poco margen para decisiones arbitrarias, por lo que la marca se concentra donde sí hay libertad —en los comentarios y los nombres—, con lo que Anthropic denomina «un efecto insignificante en el código generado».²³⁰ Su persistencia es probabilística y varía según el componente: en el texto, una edición ligera «probablemente no eliminará por completo la marca de agua», una reescritura total sí lo hará, y una traducción generada por Claude llevará su propia marca nueva; en los metadatos de archivos, la conversión de formato, volver a guardar y las capturas de pantalla pueden eliminar la firma C2PA.²⁰⁴ Está prevista una herramienta de detección API; un resultado positivo demuestra que «es probable que Claude haya intervenido en el contenido en algún momento» y, explícitamente, no permite distinguir entre «Claude escribió esto» y «Claude editó esto de forma sustancial». Además, según la página de soporte, la ausencia de la marca tampoco demuestra nada. No se menciona ninguna opción para desactivarla en ningún nivel de cliente.²³⁰²⁰⁴

¿Cuánto cuesta Claude Code?

Comprender y controlar los costos es esencial para usar Claude Code de forma sostenible. Consulta también Selección de modelos para conocer las capacidades de cada modelo y Marcos de decisión para elegir el modelo adecuado para cada tarea.

Consulta de costos

> /cost

Salida:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

Los usuarios con suscripción ven en /cost un desglose por modelo y aciertos de caché, que muestra exactamente qué modelos consumieron tokens y cuánto contenido se obtuvo de la caché (v2.1.92+).¹³⁷

Tarifas contratadas en lugar del precio de lista (modelPricing, administrado, v2.1.243+): las organizaciones que hayan negociado tarifas por modelo o un multiplicador de descuento pueden implementarlos mediante la configuración administrada modelPricing; /cost, la línea de estado y las cifras de costos de telemetría usarán entonces esas tarifas en lugar del precio de lista, para que los números que ven los desarrolladores coincidan con lo que paga la organización.²²⁸ Desde la versión v2.1.271, el multiplicador también puede ser superior a 1 —hasta 10— para las organizaciones que cobran a sus equipos internos tarifas con recargo.²¹⁶

Línea de caché de prompts por sesión (v2.1.251+): /cost agrega una línea de caché de prompts para la sesión —proporción de aciertos, fallos, tokens almacenados de nuevo en caché y si la caché está caliente o fría—, junto con un objeto prompt_cache equivalente para los scripts de la línea de estado. El objeto aparece después de la primera respuesta de API de la conversación principal, no cuenta las solicitudes de subagents y se calcula a partir de los recuentos de tokens de caché en las respuestas de API, por lo que funciona con todos los proveedores. /usage muestra las mismas estadísticas en su línea Prompt cache (main).²⁰⁶²⁰⁹ Desde la versión v2.1.260, la línea de /cost y el objeto prompt_cache de la línea de estado también indican una causa probable de los fallos de caché; por ejemplo, que hayan cambiado las definiciones de las herramientas o el prompt del sistema, o que la sesión haya permanecido inactiva más allá del TTL de la caché.²¹²

El tráfico de agentes ya no interrumpe su propio prefijo de caché (v2.1.265): 2 correcciones eliminan fugas de la caché de prompts en el trabajo delegado. Reanudar un subagent iniciado en primer plano ya no modifica su lista de herramientas ni el prefijo del prompt del sistema; además, los agentes compañeros y los subagents reanudados ya no sacan del prefijo del prompt, en turnos posteriores, el contexto del hook SubagentStart ni las skills precargadas. Ambos errores impedían reutilizar la caché de prompts: el prefijo cambiaba, por lo que todo lo posterior se volvía a enviar como entrada sin almacenar en caché, precisamente en las sesiones prolongadas con agentes donde más importa la economía de la caché (el mismo modo de fallo que la versión v2.1.260 corrigió en los turnos con llamadas a herramientas de Fable 5.1).²¹⁵

El conjunto de mejoras de estabilidad de la caché de v2.1.267: una versión, unas 10 correcciones y un mismo modo de fallo: algo reescribía el prefijo del prompt a mitad de una conversación y todo lo posterior se volvía a enviar como entrada sin almacenar en caché. Las sesiones reanudadas ya no reescriben las listas de herramientas, vuelven a renderizar sus descripciones ni modifican anuncios anteriores de herramientas de MCP antes de que sus conectores se reconecten; cambiar de modelo con /model ya no vuelve a enviar todas las definiciones de herramientas (el texto de atribución de commits y PR ahora llega como una nota de la conversación que se actualiza al cambiar de modelo); los subagents y las sesiones iniciadas con --system-prompt o --append-system-prompt registran una sola vez el prompt del sistema y las definiciones de herramientas; y las herramientas de MCP y plugins incorporadas a mitad de la sesión llegan a las sesiones sin ToolSearch como definiciones diferidas, en lugar de hacerlo mediante una lista de herramientas reescrita. Este conjunto extiende las correcciones de las versiones v2.1.260 y v2.1.265 a la reanudación, el cambio de modelo y la reconexión de MCP.²¹⁶

v2.1.273 mantiene el hilo de la conversación: /login, /upgrade y /extra-usage descartaban el razonamiento previo de la conversación, lo que obligaba a reescribir por completo la caché de prompts en la siguiente solicitud.²¹⁷

Planes de suscripción

Límites de uso (agosto de 2025): Anthropic introdujo límites semanales para los suscriptores de pago. Los suscriptores de Max pueden comprar uso adicional más allá del límite a las tarifas estándar de API.¹⁴

Duplicación de los límites de uso (6 de mayo de 2026): durante el evento Code with Claude SF, Anthropic duplicó los límites de 5 horas de Claude Code en los planes Pro, Max, Team y Enterprise por puesto, eliminó la reducción durante las horas pico en las cuentas Pro y Max, y aumentó «considerablemente» los límites de API para los modelos Claude Opus. El respaldo de capacidad es el acuerdo con Colossus 1 de SpaceX: «más de 300 megavatios de nueva capacidad (más de 220.000 GPU de NVIDIA) durante el mes».¹⁵⁷

Límites semanales desde el 14 de septiembre de 2026 (anunciados el 29 de agosto): el aumento temporal del 50 % de los límites semanales, vigente desde el incremento de mayo, termina el 14 de septiembre y se sustituye por un aumento permanente del 25 % respecto del valor de referencia anterior a ese incremento para los planes Pro, Max, Team y Enterprise por puesto. Según los propios cálculos de Anthropic sobre el cambio: «En comparación con hoy, esto equivale a una reducción del 17 % en los límites semanales de Claude Code». Si tu límite semanal actual es de 150 unidades, pasará a ser de 125 el 14 de septiembre. Los límites de 5 horas no forman parte de este anuncio; la duplicación de mayo se mantiene. Si ejecutas sesiones prolongadas sin supervisión, prepárate desde ahora para el límite más bajo: la opción de continuar automáticamente después del restablecimiento (v2.1.234) y /usage son los 2 controles importantes.²¹³

Precios por token de API (abril de 2026)¹¹⁴⁴

Para los usuarios cuya facturación se basa en API, los precios por millón de tokens son:

Precio del contexto de 1M (abril de 2026): Opus 4.7, Opus 4.6, Sonnet 4.6 y Mythos Preview incluyen 1M con las tarifas estándar por MTok, sin recargo por contexto largo.¹⁴⁸ Esta consolidación es reciente; las indicaciones anteriores según las cuales Opus 4.6 o Sonnet 4.6 costaban 2 veces más por la entrada y 1,5 veces más por la salida al superar los 200K tokens de entrada ya no están vigentes. Opus 4.5 y los modelos anteriores conservan sus estructuras de precios originales.

Precios por residencia de datos: especificar que la inferencia se realice solo en Estados Unidos mediante inference_geo aplica un multiplicador de 1,1 a todos los precios por token, incluidas las lecturas y escrituras en caché (modelos Opus 4.6+).¹⁴⁸

El almacenamiento de prompts en caché reduce considerablemente los costos de las entradas repetidas: escribir en la caché cuesta 1,25 veces la tarifa base (caché de 5 minutos) o 2 veces (caché de 1 hora), pero leerla cuesta solo 0,1 veces, lo que supone un ahorro del 90 %; además, únicamente en Claude Fable 5.1 y Mythos 5.1, las lecturas bajan a 0,025 veces ($0,25/MTok en Fable 5.1), con un ahorro del 97,5 %.²¹⁹ En los sistemas RAG y los asistentes de programación con contexto repetido, la caché puede reducir los costos entre un 88 % y un 95 %.

La modalidad por lotes de API ofrece un descuento del 50 % con un plazo de entrega de 24 horas para tareas que no son urgentes, como conjuntos de pruebas nocturnos.

Política sobre varias cuentas⁵²

¿Puedes tener varias cuentas de Claude? Sí, para casos de uso legítimos. Anthropic permite explícitamente tener varias cuentas cuando cumplen propósitos distintos.

Qué está permitido:

Límites técnicos: - Se pueden verificar hasta 3 cuentas con el mismo número de teléfono - Se admiten explícitamente varias suscripciones de pago desde la misma IP o red - Las cuentas son completamente independientes; no es posible transferir chats ni proyectos entre ellas

Qué está prohibido (según la Política de uso): - Crear cuentas para eludir bloqueos después de haber recibido uno - Coordinar actividades maliciosas entre varias cuentas para evitar la detección - Usar varias cuentas para eludir límites de uso o créditos del nivel gratuito

Nota sobre un caso real: en enero de 2026, las 22 cuentas Max del usuario avanzado Jeffrey Emanuel (@doodlestein) se marcaron automáticamente y se bloquearon de manera temporal. Thariq (@trq212), empleado de Anthropic, resolvió el caso en menos de 4 horas tras confirmar que se trataba de un uso legítimo. Si utilizas Claude Code de forma intensiva para proyectos laborales y personales en varias cuentas, eso es precisamente para lo que está diseñado el servicio, pero no intentes aprovecharte del sistema.

En caso de duda: comunícate con el equipo de soporte de Anthropic para obtener una confirmación por escrito sobre tu configuración específica.

Factores de costo

Ejemplos de costos reales

Consejo para ahorrar costos: usar Haiku para los subagents de exploración y Sonnet para la implementación suele reducir los costos entre un 40 % y un 50 % frente a utilizar Sonnet para todo.

Gestión de costos para equipos

TPM/RPM recomendados según el tamaño del equipo:

Cargos ocultos de las herramientas

Además del precio por token, algunas herramientas generan cargos independientes:⁹

Estos cargos se acumulan en los bucles de agentes. Un ciclo de depuración de 100 iteraciones con Bash cuesta unos 24.500 tokens de entrada adicionales solo en sobrecarga.

Estrategias para ahorrar costos

1. Usa Haiku para los subagents: La mayor parte de la exploración no necesita Sonnet
2. Activa la caché de prompts: Está activada de forma predeterminada, pero comprueba que no se haya deshabilitado
3. Establece un máximo de turnos: claude --max-turns 5 evita conversaciones descontroladas
4. Establece un límite en dólares: claude --max-budget-usd 5 detiene por completo la sesión al alcanzar el límite de gasto. Desde la versión v2.1.217, el límite también controla los subagents en segundo plano: cuando se alcanza, se rechazan las nuevas ejecuciones y se detienen los agentes que estén funcionando en segundo plano (antes, los agentes en segundo plano escapaban al presupuesto)¹⁹⁴
5. Usa el modo de planificación para explorar: Sin ejecución, no hay operaciones costosas accidentales
6. Compacta de forma proactiva: Menos contexto = menos tokens
7. Limita la salida: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. Usa API por lotes para el trabajo que no sea urgente: 50 % de descuento tanto en los tokens de entrada como en los de salida
9. Analiza el gasto de API de Claude de un proyecto: /claude-api cost-optimize (v2.1.247+) analiza el gasto actual de API de Claude de un proyecto y aborda los factores de costo (caché, uso eficiente de tokens, procesamiento por lotes, esfuerzo y elección del modelo) mediante un cambio medido a la vez; está destinado a las aplicaciones que creas con API, no a la propia sesión de Claude Code²²³

Supervisión del uso

• Consola de Claude: platform.claude.com (requiere el rol Admin o Billing)
• Límites del espacio de trabajo: Establece límites de gasto por espacio de trabajo
• Bedrock/Vertex: Usa la supervisión de costos nativa de la nube
• LiteLLM: Para obtener un seguimiento detallado por usuario con proveedores externos

Consumo de tokens en segundo plano

Algunas operaciones consumen tokens en segundo plano: - Resumen de conversaciones para /resume - Comandos /cost y /status - Compactación automática

Por lo general, cuestan menos de $0,04 por sesión.

API de análisis de Claude Code (Team/Enterprise)⁴⁶

Accede mediante programación a los análisis de uso y las métricas de productividad de Claude Code de tu organización a través de la API de administración.

Endpoint: GET /v1/organizations/usage_report/claude_code

Requisitos: - Clave de API de administración (sk-ant-admin...) - Plan Team o Enterprise - Rol Admin, Billing o Developer

Métricas disponibles:

Ejemplo de solicitud:

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

Casos de uso: - Análisis de la productividad de los desarrolladores (sesiones, commits y PR) - Métricas de uso de herramientas (tasas de aceptación/rechazo de Edit, Write, etc.) - Seguimiento y asignación de costos entre equipos - Justificación de ROI para herramientas de programación con IA

Nota: Los datos aparecen en un plazo de 1 hora desde que finaliza la actividad. Para garantizar la coherencia, las respuestas solo incluyen datos con más de 1 hora de antigüedad.

Marcos de decisión

No basta con conocer las funciones disponibles. Necesitas saber cuándo usar cada una. Estos árboles de decisión convierten el conocimiento en acción.

¿Qué modelo debo usar?

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus 5 (high effort default; /effort xhigh for harder)
                  │         Cost: ~$2.00/task
                  │         Quality: Highest (1M context at standard price, adaptive reasoning)
                  │
                  └── NO → Use Sonnet
                           Cost: ~$0.75/task
                           Balance: Best overall when cost matters

Regla general: el modelo predeterminado depende de tu plan: Opus 5 en los planes premium y en Anthropic API, y Sonnet 5 en Pro y Team Standard; /model opus escala una sesión de Sonnet a Opus 5.^181197207 Usa Haiku para los subagents. Cambia a Opus cuando la respuesta de Sonnet parezca superficial. Con los equipos de agentes (v2.1.32+), Opus puede coordinar varios agentes que trabajan en paralelo en distintas subtareas.⁷⁹

¿Comando, skill, subagent o equipo de agentes?

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Is there one subtask or many parallel subtasks?
                  │         │
                  │         ├── ONE → Use Subagent (Task tool)
                  │         │         Example: Deep exploration, parallel analysis
                  │         │         Prevents context bloat in main conversation.
                  │         │
                  │         └── MANY → Use Agent Team (v2.1.32+)
                  │                   Example: 5 agents reviewing different modules simultaneously
                  │                   Opus coordinates; each agent works independently.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

¿Hook o prompt?

Must the action ALWAYS happen, regardless of Claude's judgment?
│
├── YES → Use Hook (deterministic)
│         Examples:
│         - Format code after every edit
│         - Log all bash commands
│         - Block access to .env files
│         Claude cannot skip, forget, or decide otherwise.
│
└── NO → Use Prompt (probabilistic)
         Examples:
         - "Consider adding tests"
         - "Think about edge cases"
         - "Review for security if relevant"
         Claude decides based on context.

¿Cuándo conviene usar el razonamiento extendido?

Is this a genuinely hard problem?
│
├── Architectural decision with many tradeoffs → YES, use thinking
├── Complex debugging with unclear root cause → YES, use thinking
├── Security analysis requiring careful reasoning → YES, use thinking
├── Understanding unfamiliar codebase → YES, use thinking
│
├── Routine bug fix → NO, skip thinking
├── Simple refactoring → NO, skip thinking
├── Code formatting → NO, skip thinking
└── Quick questions → NO, skip thinking

Actívalo o desactívalo con Alt+T durante la sesión. Los presupuestos de razonamiento más altos cuestan más; comienza con el mínimo y auméntalo solo si las respuestas parecen apresuradas.

Razonamiento adaptativo de Opus 4.6: Opus 4.6 ajusta automáticamente la profundidad del razonamiento según la complejidad del problema. Para la mayoría de las tareas, no es necesario controlar explícitamente el presupuesto de razonamiento: Opus lo aumenta para los problemas difíciles y mantiene la rapidez en los sencillos. Activar o desactivar manualmente el razonamiento resulta especialmente útil con Sonnet cuando quieres forzar un análisis más profundo.

¿Qué entorno de ejecución conviene usar?

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools

Equipos de agentes, subagents o sesiones paralelas

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL

¿Qué tipo de hook conviene usar?

What kind of automation do you need?
│
├── Run a shell command at a specific event?
│   │
│   └── Use Command Hook
│       Trigger: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Example: "Run prettier after every file edit"
│       Config: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── Modify Claude's system prompt based on context?
│   │
│   └── Use Prompt Hook (v2.1.35+)
│       Trigger: Same events
│       Example: "Inject project rules when working in /src/auth/"
│       Config: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── Have Claude make a judgment call before proceeding?
    │
    └── Use Agent Hook (v2.1.35+)
        Trigger: Same events
        Example: "Evaluate if this bash command is safe before running"
        Config: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

¿Cuándo conviene usar /fast?

Is response speed more important than depth right now?
│
├── YES → Use /fast   (Opus 5 or Opus 4.8 only, v2.1.219+)
│         Same model, ~2.5× output speed at 2× price
│         Good for: quick questions, simple edits, code explanations,
│                   file searches, formatting tasks
│
└── NO → Stay in normal mode
         Good for: architecture decisions, complex debugging,
                   security reviews, multi-file refactors,
                   anything requiring deep reasoning

/fast activa o desactiva el modo rápido para la sesión actual. Usa el mismo modelo —Opus 5 u Opus 4.8, los únicos 2 modelos compatibles con el modo rápido a partir de la versión v2.1.219— con una velocidad de salida optimizada. NO cambia a un modelo más económico y, con un precio de $10/$50 por MTok, tampoco cuesta menos.¹⁹⁶¹⁹⁸

¿Cómo funciona el sistema de permisos?

El sistema de permisos de Claude Code ofrece un control detallado sobre las operaciones que pueden ejecutarse. Comprenderlo es fundamental tanto para la seguridad como para la eficiencia del flujo de trabajo. Consulta también Implementación empresarial para conocer la configuración administrada que aplica permisos en toda la organización.

Niveles de permisos

Herramientas de solo lectura (aprobadas automáticamente): - Read - Lee el contenido de archivos - Glob - Busca archivos por patrón - Grep - Busca en el contenido de archivos - WebSearch - Busca en la web - LSP - Proporciona inteligencia de código (ir a la definición, buscar referencias y documentación al pasar el cursor)¹⁸

Capacidades de la herramienta LSP (v2.0.74+): La herramienta LSP ofrece inteligencia de código similar a la de un IDE: - Ir a la definición: Salta al lugar donde se define un símbolo - Buscar referencias: Enumera todos los usos de un símbolo en el código base - Documentación al pasar el cursor: Obtén información de tipos y documentación de cualquier símbolo - Funciona con TypeScript, Python, Go, Rust y otros lenguajes compatibles con LSP - Requiere que el servidor de lenguaje esté disponible (normalmente se instala con tu cadena de herramientas)

Herramientas de modificación (requieren aprobación): - Edit - Modifica archivos existentes - Write - Crea archivos nuevos - Bash - Ejecuta comandos de shell - WebFetch - Obtiene el contenido de una URL - NotebookEdit - Modifica cuadernos de Jupyter

La primera vez que se ejecuta una herramienta de modificación, Claude Code solicita aprobación. Las aprobaciones se mantienen durante la sesión, a menos que se configure explícitamente lo contrario.

Herramienta EndConversation (v2.1.214). Claude Code ahora tiene la misma capacidad para finalizar conversaciones que Claude tiene en claude.ai desde 2025: en casos excepcionales de entradas extremadamente abusivas o intentos persistentes de jailbreak, Claude puede finalizar la sesión de inmediato mediante la herramienta integrada EndConversation. Es una medida de resistencia al abuso y bienestar del modelo, no una función del flujo de trabajo; nunca se activa durante sesiones normales de desarrollo.¹⁹⁰¹⁹³

Modos de permisos

El modo default se denomina “Manual” desde la v2.1.200. El cambio de nombre abarca CLI, --help, VS Code y JetBrains; el valor de configuración no cambió, por lo que "defaultMode": "default" sigue funcionando, y ahora --permission-mode manual / "defaultMode": "manual" se aceptan como alias. El comportamiento es idéntico —solicitar aprobación la primera vez que se usa cada herramienta—; simplemente, la etiqueta dejó de presentarlo como «el modo que recibes de manera predeterminada» cuando en realidad es el modo de aprobación manual. En la misma versión, los cuadros de diálogo de AskUserQuestion ya no continúan automáticamente de forma predeterminada; ahora, un subagent que hace una pregunta espera tu respuesta en vez de proseguir cuando se agota el tiempo, y puedes volver a habilitar un tiempo de espera por inactividad mediante /config.

El modo auto es el predeterminado de Pro, Max y Team desde el 14 de agosto de 2026; se anunció el 7 de agosto y se confirmó como activo en la documentación oficial sobre los modos de permisos el día del cambio. Su redacción actual añade 2 detalles de alcance que conviene conocer: el valor predeterminado se aplica a las sesiones nuevas, y «un valor predeterminado que hayas establecido se mantiene, salvo que aceptes la solicitud única para cambiarlo, mientras que un valor predeterminado administrado por tu organización no se modifica». Las sesiones nuevas de esos planes comienzan en modo auto, que «hace pasar cada llamada a herramientas por un clasificador orientado a bloquear acciones irreversibles, destructivas o dirigidas fuera de tu entorno». El argumento de Anthropic a favor del cambio: en un estudio con 1.053 participantes, el modo auto detectó el 89 % de los comandos peligrosos, frente al 13,6 % de la revisión humana; además, los usuarios aprueban el 97 % de las solicitudes de permisos, lo que debilita la revisión manual en la práctica. La sobrecarga de tokens del clasificador ya no se factura en Pro/Max/Team (desde el anuncio). Para volver al modo anterior basta con pulsar Shift+Tab (o usar el menú desplegable de modos en la aplicación de escritorio); fija otro valor predeterminado mediante defaultMode en la configuración. Los administradores de la organización pueden deshabilitar por completo el modo auto mediante la configuración administrada disableAutoMode. Enterprise, Claude API, Claude Platform en AWS, Bedrock, Agent Platform de Google Cloud y Foundry siguen requiriendo activación por ahora; Anthropic planea extenderles este valor predeterminado «durante el próximo mes».²⁰³ Para conocer lo que el modo auto no promete —y la evasión demostrada por investigadores que llevó a Anthropic a aclararlo—, consulta Modo auto en Max.

Los archivos de configuración que permiten ejecutar código ahora generan una solicitud incluso con acceptEdits (v2.1.160). acceptEdits aprueba automáticamente las ediciones ordinarias, pero desde la v2.1.160 se detiene y solicita aprobación antes de escribir en archivos que pueden permitir la ejecución silenciosa de comandos: archivos de inicio del shell (.zshenv, .zlogin, .bash_login), ~/.config/git/ y configuraciones de herramientas de compilación (.npmrc, .yarnrc*, bunfig.toml, .bazelrc, .pre-commit-config.yaml, .devcontainer/ y similares). La razón es que editar cualquiera de ellos convierte el siguiente shell, instalación o commit en un vector de ejecución, por lo que reciben un control deliberado incluso en un modo para proyectos de confianza que normalmente deja pasar las ediciones. Es el mismo modelo de amenazas que las protecciones de escritura existentes para .claude/, .git/ y .vscode/, ampliado al conjunto más extenso de archivos donde «editar equivale a ejecutar».²⁴³

Modo auto (v2.1.85+): Una alternativa más segura a --dangerously-skip-permissions. Un modelo clasificador independiente —Claude Sonnet 5 desde la v2.1.210 (originalmente Sonnet 4.6)— revisa cada acción antes de ejecutarla para comprobar que coincida con la intención del usuario y sea segura.¹²⁴¹⁸⁷

Cómo funciona: - Las acciones de solo lectura y las ediciones de archivos dentro del directorio de trabajo se aprueban automáticamente - Las reglas personalizadas para permitir o denegar se resuelven primero - Todo lo demás se envía al clasificador para su evaluación - Si se bloquea una acción, Claude intenta automáticamente otro enfoque

Bloqueos automáticos predeterminados: curl | bash, force-push a main, implementaciones o migraciones en producción, eliminaciones masivas en la nube, cambios de IAM o permisos y envío externo de datos confidenciales.¹²⁵

Disyuntor: 3 bloqueos consecutivos o 20 en total durante una sesión hacen que se vuelva a las solicitudes de aprobación manuales.¹²⁵

# Enable at startup
claude --permission-mode auto

# Or cycle into it during a session
Shift+Tab  # Cycles through: Manual (aka default) → acceptEdits → auto → plan

El modo auto ya no requiere activación previa (v2.1.152), funciona en Bedrock/Vertex/Foundry sin una variable de entorno (v2.1.207) y es el modo predeterminado de Pro/Max/Team desde el 14 de agosto de 2026.^245185203

Modo YOLO (v2.0.68+): Para un funcionamiento completamente autónomo y sin ningún clasificador de seguridad, usa la opción --dangerously-skip-permissions. Esta opción acepta todo: ediciones de archivos, comandos bash y todas las llamadas a herramientas. La palabra «peligroso» es intencional. El modo auto es la alternativa recomendada para la mayoría de los casos de uso.⁵⁴

claude --dangerously-skip-permissions

Establece el modo mediante CLI:

claude --permission-mode auto  # or acceptEdits, plan, bypassPermissions

Cámbialo durante la sesión:

Shift+Tab  # Cycles through modes

En settings.json:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Restricción de alcance de defaultMode (v2.1.257): los archivos .claude/settings.json o .claude/settings.local.json de un proyecto ya no pueden establecer defaultMode: "bypassPermissions"; el valor se ignora allí, igual que ya ocurría con "auto". La documentación ahora expresa la regla con claridad: los valores auto y bypassPermissions de permissions.defaultMode «no surten efecto desde la configuración local o del proyecto»; debes establecerlos en la configuración del usuario o administrada, o para cada sesión mediante --permission-mode. Por lo tanto, un repositorio clonado no puede incluir un archivo de configuración que inicie sesiones omitiendo los permisos. (El ejemplo anterior usa acceptEdits, que puede establecerse desde cualquier ámbito; esta guía tampoco había documentado la restricción preexistente de auto, pero ahora ambas quedan registradas).²¹¹²²¹

Sintaxis de las reglas de permisos

Las reglas detalladas controlan operaciones específicas. Se evalúan en orden: se aplica la primera coincidencia.

Patrones de comandos Bash:

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

El asterisco permite buscar coincidencias por prefijo: Bash(npm run test:*) permite npm run test, npm run test:unit y npm run test:integration.

Limitación importante: Los patrones de Bash solo buscan coincidencias por prefijo; no son expresiones regulares. Un patrón como Bash(curl http:*) no coincidirá con curl -X GET http://... porque las opciones aparecen antes de la URL. Para bloquear de manera confiable, deniega todo el comando: Bash(curl:*).

Coloca el * después del subcomando. Claude Code hace coincidir literalmente todo lo que aparece antes del primer *, por lo que esas palabras son las que limitan la regla: Bash(git log *) solo permite comandos git log, mientras que en Bash(git * main) el * sustituye al subcomando y a todas las opciones anteriores. Eso incluye -c, que hace que git ejecute un programa especificado por ti, por lo que Bash(git * main) también aprueba git -c core.fsmonitor=<script> diff main. Desde la v2.1.246, Claude Code muestra una advertencia al iniciar cuando una regla de autorización contiene un comodín antes del subcomando, ya sea que se encuentre en un archivo de configuración, en la configuración administrada o en un valor de --allowedTools/--settings; la solución es indicar el valor exacto que necesitas, como Bash(git checkout main) en vez de Bash(git * main).²²⁷²²⁵

Las reglas para denegar archivos atraviesan las redirecciones; la ampliación a los argumentos se publicó y revirtió en el plazo de un día (v2.1.257-260). Las reglas para denegar Read(...) y Edit(...) en comandos Bash abarcan las redirecciones de entrada (< file) y los comandos de lectura como tac y egrep (v2.1.257), la versión más limitada prometida cuando las comprobaciones de redirección de entrada de la v2.1.232 se revirtieron en la v2.1.233; esa parte sigue vigente. La v2.1.259 extendió la misma cobertura a las rutas de archivo ocultas en valores de opciones y operandos (argumentos como --ignore-revs-file=.env, -f.env y @file; operandos de git diff y git grep; comandos compuestos como cd DIR && cat FILE; y grep -r/cp -r sobre un directorio que contuviera un archivo denegado solicitaban permiso primero), pero la v2.1.260 revirtió esa ampliación al día siguiente: denegaba npm run build bajo una regla Read(./**/build/**) en todos los modos y hacía que cd ... && grep solicitara aprobación incluso en modo auto. Este es el tercer cambio de rumbo sobre la cobertura de argumentos: la v2.1.232 la incorporó, la v2.1.233 la revirtió, la v2.1.257 añadió el subconjunto de redirecciones y comandos de lectura que sigue vigente, la v2.1.259 la extendió a los argumentos y la v2.1.260 revirtió esa ampliación. Por lo tanto, desde la v2.1.260, las reglas de denegación detectan redirecciones y comandos de lectura, pero no rutas ocultas en argumentos arbitrarios de comandos; este estado, establecido por la v2.1.260, continúa vigente. Lo que vino después fueron correcciones puntuales para evasiones concretas, no un cuarto cambio de rumbo (consulta el siguiente párrafo).²¹¹²¹²

Correcciones puntuales posteriores a la reversión y una segunda reversión limitada (v2.1.268-273). La reversión de los argumentos sigue vigente; estas versiones corrigen evasiones específicas, aunque una de esas correcciones también terminó revirtiéndose. v2.1.268: las reglas para denegar y solicitar aprobación en directorios del sistema enlazados simbólicamente (/etc, /tmp y /var en macOS; /bin en Linux) ahora se aplican cuando una ruta se expresa mediante su ubicación real, y los comandos Bash ya no ignoran las reglas de denegación escritas con una ruta de enlace simbólico; ambos cambios siguen vigentes. La misma versión también hizo que un comando env -C, eval o similar que el verificador de permisos no pudiera analizar en la misma línea dejara de evadir las reglas para denegar Read o Edit, pero la v2.1.273 revirtió específicamente esa comprobación: «los comandos como time -p make build vuelven a solicitar aprobación en vez de denegarse». v2.1.269: las reglas para denegar Edit() y la comprobación de rutas de escritura ahora abarcan el archivo en el que escribe un comando Bash tee; una regla de autorización Bash(tee:*) ya no incluye destinos fuera de los directorios de trabajo; y una regla de denegación o solicitud que comienza con ! solo se aplica dentro de la fuente de configuración que la definió (se ignora una negación ! aislada). La v2.1.271 corrige el propio verificador: se comprueba el archivo que leen fmt, column y comandos similares aunque aparezca después de una opción que el verificador no reconoce; se comprueban los archivos expandidos por un comodín cuando este aparece en un patrón o valor de opción (por ejemplo, grep -v dir/* file); las opciones de declaración de variables del shell ya no pueden representar incorrectamente el comando ejecutado; y los comandos con 2 cambios de directorio, un subshell o una cadena de cd y git ya no omiten la solicitud de aprobación cuando permissions.blockReadsOutsideWorkingDirectories está activo en los modos bypass y auto. La v2.1.273 combina su reversión con 3 correcciones puntuales propias: un comando Bash que no puede analizarse ya no omite la solicitud cuando permissions.blockReadsOutsideWorkingDirectories está activo; un subshell que oculta un rm peligroso ya no omite la confirmación en modo bypass; y un directorio de memoria elegido por la configuración de un repositorio ya no se carga, recupera ni indexa bajo esa configuración. En términos sencillos, la regla final para las líneas Bash que el verificador no puede analizar es: las reglas de denegación solicitan aprobación en vez de denegar, y blockReadsOutsideWorkingDirectories solicita aprobación en vez de omitirla.²¹⁶²¹⁷

Patrones de operaciones con archivos:

{
  "allow": [
    "Edit(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

Sintaxis de rutas: - Rutas relativas: Edit(src/**) - relativas al directorio de trabajo - Rutas absolutas desde el archivo de configuración: Edit(/build/**) - relativas a la ubicación del archivo de configuración - Rutas absolutas reales: Edit(//tmp/**) - comienzan con // - Directorio principal: Read(~/.zshrc)

Las reglas de autorización dir/** de un solo segmento ahora solo coinciden con <cwd>/dir (v2.1.214); audita tus reglas existentes. Antes de la v2.1.214, una regla de autorización como Edit(src/**) aprobaba automáticamente las escrituras en cualquier directorio llamado src en cualquier parte del árbol: vendor/src/, packages/foo/src/, todos ellos. Ahora solo coincide con el directorio src situado directamente bajo el directorio de trabajo. Si dependías del antiguo comportamiento a cualquier profundidad, reescribe la regla como Edit(**/src/**). Las reglas deny y ask mantienen sus coincidencias a cualquier profundidad; el cambio limita lo que se aprueba automáticamente, nunca lo que se bloquea. Una regla que deja de coincidir silenciosamente se manifiesta como nuevas solicitudes de permisos después de actualizar, no como un error, así que revisa todas las reglas de autorización escritas en el formato de un solo segmento. Las condiciones if: de los hooks recibieron el mismo ámbito respecto al directorio de trabajo en esta versión (consulta Selectores).¹⁹⁰

Usa Edit(path)/Read(path), no Write(path)/NotebookEdit(path)/Glob(path) (v2.1.210). Claude Code ahora muestra una advertencia al iniciar cuando existen reglas de permisos escritas para Write(path), NotebookEdit(path) o Glob(path). Las formas canónicas son las 2 familias de reglas que realmente controlan el acceso a archivos: Edit(path) abarca todas las herramientas de escritura de archivos (incluidas Write y NotebookEdit), mientras que Read(path) abarca las herramientas de lectura (incluida Glob). Migra todas las reglas heredadas para eliminar la advertencia y mantener explícita su intención.¹⁸⁷

La opción “Always allow” guarda las reglas en la raíz del repositorio (v2.1.211). Las reglas de permisos creadas mediante la opción «Always allow» de la solicitud ahora se escriben en la raíz del repositorio en vez de en el worktree actual, por lo que una aprobación concedida en un worktree se mantiene entre sesiones y en todos los worktrees de ese repositorio; ya no es necesario volver a aprobar el mismo comando en cada checkout paralelo.¹⁸⁸

Las rutas con paréntesis y los patrones malformados fallan de forma segura (v2.1.260). Se corrigieron 3 problemas de análisis en las reglas de permisos de archivos; el primero es una corrección de seguridad. Las reglas Edit/Write/Read cuya ruta contenía paréntesis —por ejemplo, un grupo de rutas de Next.js como Edit(src/app/(admin)/**)— se descartaban como inválidas o el sandbox de Bash las ignoraba, lo que dejaba con permisos de escritura carpetas que un administrador creía de solo lectura; ahora sí se aplican. Una regla para denegar archivos con un patrón que no pudiera compilarse (por ejemplo, un [ sin cerrar) antes hacía que todas las ediciones de archivos fallaran con Invalid regular expression; ahora esa regla protege la ruta literal que especifica. Además, el error de configuración de una regla como Edit(C:\dir\(name)\**), donde \( se interpreta como un paréntesis escapado y no como un separador de ruta, ahora propone una escritura inequívoca. La misma versión también deja de ignorar silenciosamente las reglas con texto después del paréntesis de cierre (Bash(ls) x nunca coincidía con nada); ahora se señalan como configuración inválida.²¹²

Patrones de herramientas de MCP:

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

Usa la sintaxis con comodín mcp__server__* para permitir o denegar todas las herramientas de un servidor de MCP específico.³² Esta sintaxis resulta útil para habilitar rápidamente todas las herramientas de servidores de confianza o bloquear servidores completos de fuentes no confiables.

Desde la v2.1.166, las reglas de denegación también aceptan un glob en la posición del nombre de la herramienta: un "*" aislado en esa posición deniega todas las herramientas, de modo que puedes bloquearlo todo y después volver a permitir un conjunto reducido. En cambio, las reglas de autorización rechazan los globs que no sean de MCP; no puedes autorizarlo todo de manera general del mismo modo, lo que mantiene restrictiva la postura predeterminada.²⁴¹

Coincidencia a nivel de parámetros: Tool(param:value) (v2.1.178):

Además del nombre de la herramienta, una regla puede hacer coincidir sus parámetros de entrada, usando * como comodín en el valor:

{
  "deny": [
    "Agent(model:opus)"
  ]
}

Agent(model:opus) bloquea cualquier subagent iniciado en el nivel Opus; se deniega la propia creación, no se limita a pedirle al prompt que la evite. Esto amplía el control de permisos desde «qué herramienta» hasta «cómo se llama», mediante una regla determinista en lugar de una petición en el prompt. Se combina con la configuración administrada enforceAvailableModels: la lista de permitidos define qué niveles de modelos existen para la sesión, mientras que las reglas Tool(model:...) limitan cómo los utilizan los subagents.¹⁷³

Desde la v2.1.186, estas reglas Agent(...) también se aplican a la creación de subagents con nombre: las reglas de denegación Agent(agent_type) y las restricciones de tipos permitidos Agent(x,y) ahora se aplican cuando se inicia un agente específico con nombre (mediante un flujo de trabajo, --agents o un equipo de agentes), no solo en las creaciones anónimas de estilo Task. La creación se bloquea al iniciarse, lo que cierra una brecha que permitía a un agente con nombre eludir una regla destinada a restringirlo.¹⁷⁵

Patrones de WebFetch:

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

Desde la v2.1.268, las reglas simples para denegar o solicitar aprobación de WebFetch ya no se aplican a las lecturas y actualizaciones de la herramienta Artifact; escribe una regla Artifact o WebFetch(domain:claude.ai) para bloquearlas o someterlas a aprobación.²¹⁶

Directorios adicionales

Amplía el acceso de Claude más allá del proyecto actual:

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

Los directorios adicionales son esenciales para monorepos o cuando Claude necesita consultar código ubicado en directorios hermanos.

Modo sandbox

Habilita el aislamiento del sistema de archivos y la red:

> /sandbox

O configúralo en la configuración:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true,
      "deniedDomains": ["pastebin.com", "transfer.sh", "0x0.st"]
    }
  }
}

Desde la v2.1.187, la configuración sandbox.credentials impide que los comandos ejecutados en el sandbox lean archivos de credenciales y variables de entorno secretas, lo que ofrece defensa en profundidad contra la filtración de secretos por parte de un comando aislado.¹⁷⁶

Desde la v2.1.221, los archivos de credenciales incorporan un tercer modo además de permitir y denegar: mode: "mask" (Linux y WSL). Un comando en el sandbox que lea el archivo recibe una copia con valores centinela —ya sea todo el archivo o solo los segmentos capturados mediante una expresión regular extract— y el proxy del sandbox sustituye el valor real al salir. El comando funciona (puede autenticarse a través del proxy) sin que el secreto llegue a estar presente en su entorno, que es precisamente la propiedad deseable cuando un comando afectado por una inyección de prompt busca tokens. En macOS, donde el mecanismo de sustitución del proxy no está disponible, mask utiliza deny como alternativa; de este modo, una configuración escrita para CI en Linux se degrada de forma segura en vez de exponer silenciosamente el archivo.¹⁹⁹

La v2.1.224 amplía el enmascaramiento más allá del contenido estático de archivos. extract y onExtractNoMatch gestionan valores de entorno estructurados; decode: "jwt" con maskClaims enmascara claims específicos dentro de un JWT en vez de ocultar todo el token, por lo que un comando aún puede leer los metadatos de enrutamiento del token mientras los claims confidenciales permanecen como valores centinela; y awsPairs/sigv4 vuelven a firmar las solicitudes AWS SigV4 en el proxy, lo que hace posible usar el enmascaramiento con los CLIs de AWS: de lo contrario, una clave enmascarada no superaría la verificación de firma. Todas estas opciones requieren network.tlsTerminate y solo se respetan desde los ámbitos del usuario, administrado o --settings; un repositorio no puede incluir una configuración de enmascaramiento que redirija tus credenciales silenciosamente.²⁰¹

Desde la v2.1.216, la configuración sandbox.filesystem.disabled omite el aislamiento del sistema de archivos, pero mantiene el control del tráfico saliente de la red; resulta útil cuando la prisión del sistema de archivos impide que funcione una herramienta de compilación, pero aún quieres aplicar la lista de dominios permitidos al tráfico saliente.¹⁹²

Desde la v2.1.219, la configuración sandbox.network.strictAllowlist deniega directamente los hosts que no están en la lista de permitidos, sin solicitar aprobación. De forma predeterminada, cuando un comando en el sandbox intenta comunicarse con un host ajeno a allowedDomains, se muestra una solicitud de permisos; con strictAllowlist habilitado, la conexión simplemente se rechaza. Esta es la configuración indicada para ejecuciones desatendidas —CI, agentes en segundo plano y ciclos nocturnos— donde una solicitud que nadie responde provoca un bloqueo y donde «pregúntame si aparece tráfico saliente inesperado» tampoco es la política adecuada. Completa la tríada de red: allowedDomains indica qué se permite, deniedDomains (más adelante) introduce excepciones en una autorización amplia y strictAllowlist determina si todo lo demás solicita aprobación o falla.¹⁹⁶ La v2.1.229 también refuerza la sintaxis de las listas de dominios: los literales IPv6 deben escribirse entre corchetes ([::1]:443), las formas ambiguas se tratan como denegadas por seguridad y /doctor las señala.²³⁵ La v2.1.236 añade 2 medidas adicionales de refuerzo: en macOS, las reglas con comodines para denegar lecturas (por ejemplo, **/.env) ahora prevalecen dentro de las regiones de lectura permitidas, abarcan el contenido de los directorios coincidentes y no pueden evadirse cambiando el nombre del archivo denegado; además, mientras el modo auto está activo, las reglas de autorización para Monitor se dejan de lado: los comandos de Monitor reciben la misma revisión del clasificador que los comandos Bash. El propio clasificador del modo auto ahora se ejecuta con los mismos valores predeterminados que en Claude API —incluida la clasificación puntuada por gravedad— en Bedrock, Vertex AI y Foundry, así como cuando la telemetría está deshabilitada.²²⁴ La v2.1.273 cambia el mecanismo predeterminado en esas puertas de enlace: allí, el modo auto ahora utiliza de forma predeterminada el clasificador local «por ahora», mientras que CLAUDE_CODE_AUTO_MODE_SERVER=1 habilita el clasificador del lado del servidor de la plataforma.²¹⁷

allowed_domains por comando en modo auto (v2.1.271): con el sandbox habilitado, los comandos Bash, PowerShell y Monitor del modo auto pueden incluir sus propios allowed_domains: los hosts que necesita un comando se revisan junto con este y se habilitan únicamente para ese comando; los demás hosts se rechazan. El tráfico saliente deja de ser una concesión para toda la sesión: cada comando especifica sus destinos y la revisión abarca exactamente esa combinación.²¹⁶

Modo sandbox estricto y la excepción ! (sandbox.allowUnsandboxedCommands, v2.1.260). Esta guía aún no había mencionado esta configuración: de forma predeterminada, un comando que falla dentro del sandbox puede volver a intentarse fuera de él mediante la vía de escape dangerouslyDisableSandbox, sujeto al flujo de permisos habitual. sandbox.allowUnsandboxedCommands: false —que aparece como Strict sandbox mode en la pestaña Overrides de /sandbox— deshabilita esa vía: se ignora el parámetro y todos los comandos deben ejecutarse en el sandbox o estar incluidos en excludedCommands. Desde la v2.1.260, los comandos que escribes personalmente en el prompt del modo bash ! se ejecutan fuera del sandbox incluso en el modo sandbox estricto, «como si los escribieras en tu propia terminal»; la restricción determina lo que ejecuta Claude, no lo que escribes tú. Si tu modelo de amenazas dependía de que los comandos ! heredaran el aislamiento, ya no lo hacen.²¹²

En el sandbox: - El acceso al sistema de archivos se limita al directorio del proyecto - El acceso a la red está controlado - Ciertos comandos quedan excluidos de las restricciones del sandbox - Los comandos Bash se permiten automáticamente si autoAllowBashIfSandboxed es true

Consejo para expertos: El modo sandbox es excelente para ejecutar Claude en bases de código no confiables. Habilítalo cuando explores proyectos desconocidos o quieras una capa adicional de protección. Las pruebas internas de Anthropic determinaron que el sandbox reduce las solicitudes de permisos en un 84 %.³⁸ El sandbox utiliza mecanismos del sistema operativo (seatbelt en macOS y bubblewrap en Linux) para aislar el sistema de archivos y la red, por lo que incluso una inyección de prompt exitosa queda completamente contenida. Anthropic ha publicado como código abierto el entorno de ejecución del sandbox para los equipos que desarrollan sus propios agentes.⁸²

Notas de seguridad (v2.1.34+): Los comandos excluidos del sandbox mediante sandbox.excludedCommands o dangerouslyDisableSandbox antes podían eludir la regla de solicitud de permisos de Bash cuando autoAllowBashIfSandboxed estaba habilitado; esto se corrigió en la v2.1.34.⁸⁷ Desde la v2.1.38, las escrituras en .claude/skills se bloquean en el modo sandbox, lo que impide que una inyección de prompt modifique las definiciones de skills.⁸⁸ La v2.1.77 añade una configuración allowRead para el sistema de archivos del sandbox que permite volver a autorizar el acceso de lectura dentro de regiones denyRead; resulta útil cuando quieres bloquear la mayor parte de un árbol de directorios, pero permitir subdirectorios específicos.¹¹⁹

Exención para la configuración de agentes en .claude/ (v2.1.121+): --dangerously-skip-permissions ya no solicita aprobación para escribir en .claude/skills/, .claude/agents/ y .claude/commands/.¹⁵⁴

Resolución de directorios .claude/ anidados (v2.1.178): Las skills de directorios .claude/skills anidados ahora se cargan automáticamente cuando trabajas en archivos bajo ese directorio, no solo desde la raíz del repositorio; si hay un conflicto de nombres, puedes acceder a la skill anidada como <dir>:<name>, por lo que ambas siguen disponibles. El resto de la superficie del proyecto se resuelve de la misma manera: cuando el nombre de un agente, flujo de trabajo o estilo de salida entra en conflicto entre directorios .claude/ anidados, prevalece el más cercano al directorio de trabajo, y un flujo de trabajo guardado en el ámbito del proyecto se dirige al .claude/workflows/ existente más cercano. En un monorepo o un repositorio de repositorios, esto proporciona herramientas específicas para cada paquete que se activan según el contexto, en vez de una sola superficie global y plana.¹⁷³

Rutas personalizadas para bubblewrap y socat (v2.1.133+): Las configuraciones administradas sandbox.bwrapPath y sandbox.socatPath permiten que los administradores dirijan las implementaciones en Linux/WSL a ubicaciones no estándar de los binarios bubblewrap y socat. Resultan útiles cuando las distribuciones instalan estas herramientas fuera de $PATH o cuando la organización distribuye compilaciones reforzadas propias.¹⁶⁰

Refuerzo de seguridad en la v2.1.113:¹⁵⁰

• sandbox.network.deniedDomains bloquea hosts específicos incluso cuando un comodín más amplio de allowedDomains los permitiría. Usa la lista de bloqueo para impedir el acceso a servicios de pegado de texto, alojamiento de archivos o hosts maliciosos conocidos sin reescribir toda tu política de autorización. Combínala con sandbox.network.strictAllowlist (v2.1.219, descrita anteriormente) cuando quieras rechazar silenciosamente todo lo ajeno a la lista de permitidos en vez de solicitar aprobación.
• Reglas para denegar comandos envoltorio. Las reglas de denegación de Bash ahora coinciden con comandos envueltos en env, sudo, watch, ionice, setsid y envoltorios de ejecución similares. Las reglas como Bash(rm:*) ahora detectan env rm -rf, sudo rm -rf y patrones de evasión relacionados.
• Las reglas de autorización Bash(find:*) ya no aprueban automáticamente find -exec ni find -delete. Estas opciones ejecutan comandos y eliminan archivos, por lo que Claude Code las dirige al flujo de permisos normal.
• Protección contra eliminaciones en macOS. Las reglas de autorización Bash(rm:*) ahora consideran /private/etc, /private/var, /private/tmp y /private/home destinos peligrosos para eliminaciones. /var, /etc y /tmp son enlaces simbólicos hacia /private/, por lo que la forma anterior de la regla no detectaba los destinos canónicos.

Refuerzo de permisos con denegación segura en la v2.1.214:¹⁹⁰

Una sola versión cerró un conjunto de brechas en la comprobación de permisos, siempre en dirección a la denegación segura: cuando el analizador no puede determinarlo con certeza, solicita aprobación.

• Se corrigió la evasión en Windows PowerShell 5.1. Antes, los comandos ejecutados en sesiones de PowerShell 5.1 podían eludir la comprobación de permisos.
• Las redirecciones de descriptores de archivo de Bash fallan de forma segura. Las formas de redirección que bash analiza de manera distinta al analizador de permisos ahora solicitan aprobación en vez de ejecutarse.
• Los comandos con más de 10.000 caracteres siempre solicitan aprobación. Antes, los comandos muy largos se evaluaban incorrectamente; ahora nunca se ejecutan automáticamente.
• Los subíndices y modificadores de zsh dentro de [[ ]] solicitan aprobación. Los subíndices y modificadores de variables dentro de comparaciones [[ ]] se trataban como texto inerte; pueden ejecutar código, por lo que ahora requieren aprobación.
• Las variantes no seguras de help/man ya no se aprueban automáticamente. Algunas invocaciones podían ejecutar opciones no seguras, sustituciones de comandos o rutas con barras invertidas bajo la apariencia de consultar documentación.
• Orden de las solicitudes en sesiones remotas. Las solicitudes de permisos en sesiones remotas ya no pueden proseguir antes del cuadro de confirmación local.
• Las opciones de redirección del daemon de docker solicitan aprobación. Los comandos docker (incluido el shim docker de Podman) que incluían --url, --connection, --identity o el modo remoto de Podman antes se ejecutaban sin solicitar aprobación; estas opciones dirigen el comando a un daemon completamente distinto.
• file pierde su autorización automática de solo lectura cuando se le indica dónde escribir. file -m/--magic-file y -f/--files-from ahora requieren permiso en vez de aprobarse automáticamente como operaciones de solo lectura.

¿Cómo funcionan los hooks?

Los hooks ejecutan comandos de shell deterministas en puntos específicos del flujo de trabajo de Claude Code. A diferencia de pedirle a Claude mediante un prompt que realice acciones, los hooks garantizan la ejecución sin importar el comportamiento del modelo. Son esenciales para hacer cumplir los estándares del equipo y automatizar tareas repetitivas. Consulta Marcos de decisión para ver el árbol de decisión «¿Qué tipo de hook?» que abarca hooks de comandos, prompts y agentes.

Por qué usar hooks en lugar de prompts: Decirle a Claude «ejecuta siempre Prettier después de editar archivos» funciona algunas veces. Pero Claude podría olvidarlo, priorizar la rapidez o decidir que el cambio es «demasiado pequeño». Los hooks garantizan la ejecución: cada Edit o Write activa el formateador, siempre, sin excepciones. Para el cumplimiento normativo, la seguridad y los estándares del equipo, lo determinista supera a lo probabilístico.⁴

Eventos disponibles