Claude Code effort level: qué es y por qué vuelve a medium

El effort de Claude Code (la documentación en español lo llama «nivel de esfuerzo») es cuánto trabajo pone Claude en cada petición: cuánto razona, cuántos archivos lee, cuántas herramientas llama y hasta dónde avanza antes de volver a preguntarte. No cambia el modelo que responde. Por eso ver medium en la barra inferior no significa que Claude rinda menos de lo normal: a 2 de noviembre de 2026, Opus 5.5, Sonnet 5.5 y Haiku 5.5 empiezan en medium por diseño, mientras que Fable 5.1, Opus 5 y los modelos anteriores empiezan en high, y Opus 4.7 en xhigh.

Para saber en qué nivel corre tu sesión, escribe /effort status. Para subirlo de forma permanente, escribe /effort high (o xhigh): Claude Code lo guarda solo para el modelo activo, dentro de la clave modelSettings de ~/.claude/settings.json. Si pusiste a mano "effortLevel": "high" en ese archivo y Opus 5.5 sigue en medium, no es un fallo: Opus 5.5 ignora esa clave antigua en los ajustes de usuario.

Dos excepciones explican casi todos los casos de «no se guarda». max no se guarda ni con /effort ni en los ajustes, así que dura solo la sesión, salvo que lo fijes con la variable de entorno CLAUDE_CODE_EFFORT_LEVEL=max. Y si esa variable ya está definida en tu shell, gana a cualquier nivel que elijas dentro de Claude Code.

Nivel de effort por defecto de cada modelo en Claude Code

Cada modelo trae su propio nivel por defecto y su propia lista de niveles, así que el mismo Claude Code puede arrancar en medium con un modelo y en high con otro. Según la guía de configuración de modelos de Claude Code, a 2 de noviembre de 2026 todos los modelos con effort empiezan en high, excepto Opus 5.5, Sonnet 5.5 y Haiku 5.5, que empiezan en medium, y Opus 4.7, que empieza en xhigh.

Para comprobar qué envía Claude Code de verdad, el 2 de noviembre de 2026 se ejecutó Claude Code 2.1.316 en macOS con una carpeta de configuración vacía y ANTHROPIC_BASE_URL apuntando a un servidor local que solo registra las peticiones, sin llamar a ningún modelo real. Con claude -p "Reply with OK", el ID de cada modelo en --model y nada más configurado, el campo output_config.effort de cada petición coincidió con la documentación:

Fable 5, Sonnet 5 y Opus 4.8 admiten los cinco niveles y empiezan en high; Sonnet 4.6 admite los mismos cuatro que Opus 4.6. Los modelos que no aparecen en la documentación no admiten effort. Si eliges un nivel que el modelo no tiene, Claude Code baja sin avisar al más alto disponible por debajo: en la prueba, --effort xhigh con Opus 4.6 envió high. Todas las pruebas de esta página tienen el mismo límite: muestran qué envía Claude Code, no cómo responde el modelo ni cuántos tokens gasta.

El medium de Opus 5.5 no equivale al medium de Opus 5, porque Anthropic calibra la escala por modelo. Según sus propias pruebas, Opus 5.5 en medium iguala o supera a Opus 5 en high en evaluaciones de programación y de trabajo de conocimiento, y a igual nivel piensa más por turno; por eso recomienda empezar en medium al migrar en lugar de arrastrar el nivel antiguo. Fuera de Claude Code cambia otra cosa: si llamas directamente a la Claude API sin indicar effort, Sonnet 5.5 corre en high, no en medium, como se detalla en Claude Sonnet 5.5: precio, effort y qué cambia frente a Sonnet 5.

Qué nivel de effort usar: low, medium, high, xhigh o max

Para el trabajo diario con un alcance claro, el nivel por defecto del modelo suele bastar; sube a high cuando importe verificar o haya casos límite, y reserva max para problemas difíciles que Claude deba resolver sin ti. Según la guía oficial de Claude Code, cada nivel encaja con un tipo de trabajo y tiene su propio coste:

La diferencia entre high, xhigh y max no es solo de grado. max es el único nivel que Claude Code no guarda: lo aplica a la sesión actual, y si lo pones en effortLevel o en modelSettings se ignora. La propia documentación advierte que max «puede mostrar rendimientos decrecientes y es propenso a pensar de más», así que conviene probarlo en una tarea concreta antes de dejarlo fijo con la variable de entorno. Si quieres un nivel alto y permanente, xhigh sí se guarda, salvo en Opus 4.6 y Sonnet 4.6, donde se ejecuta como high.

Antes de subir el effort, decide si el problema es el nivel o el modelo. El artículo de Anthropic Choosing a Claude model and effort level in Claude Code da una regla útil: si Claude tenía el contexto y aun así se equivocó, necesitas un modelo más capaz; si se saltó un archivo, no ejecutó los tests o abandonó una refactorización a medias, necesitas más effort. También recomienda ajustarlo como preferencia general según el tipo de trabajo, no tarea por tarea. Si dudas entre Sonnet en high y Opus en medium, la comparación de coste está en Claude Sonnet 5.5 vs Opus 5.5: cuál gasta menos por tarea. Un nivel más alto gasta más tokens por tarea; para ver cuánto se lleva cada sesión de tu cuota, sigue Límite de uso en Claude Code: cómo verlo y auditar tus tokens.

Cómo cambiar el effort y cuánto dura cada método

Cada forma de fijar el effort tiene una duración distinta y una prioridad distinta, y Claude Code se queda con la primera fuente que encuentra en este orden: la variable CLAUDE_CODE_EFFORT_LEVEL, un nivel elegido dentro de la sesión, el flag --effort al arrancar, los ajustes guardados y, por último, el valor por defecto del modelo. Fíjate en que un nivel elegido con /effort dentro de la sesión gana al --effort con el que arrancaste.

Hay contextos en los que /effort nunca guarda nada: en una ejecución con -p, en una sesión de un worker remoto, en el Agent SDK y cuando eliges el nivel desde un móvil o un navegador con Remote Control, el cambio vale solo para esa sesión. El mensaje que imprime /effort indica cuál de los dos casos se aplicó.

La prueba del 2 de noviembre de 2026 confirmó el orden con Opus 5.5. Con CLAUDE_CODE_EFFORT_LEVEL=low y --effort high a la vez, se envió low; con --effort max se envió max, y con CLAUDE_CODE_EFFORT_LEVEL=max también. Un valor mal escrito no rompe nada, pero se pierde: --effort banana imprimió en stderr el aviso siguiente y la petición salió con el medium por defecto.

Warning: Unknown --effort value 'banana' — ignoring it and using the default effort. Valid values: low, medium, high, xhigh, max.

Si prefieres editar el archivo a mano, este es el formato que escribe /effort high cuando trabajas con Opus 5.5 (requiere Claude Code v2.1.251 o posterior). El nombre del modelo es el canónico, y los alias, las variantes con fecha y [1m] usan la misma entrada:

{
  "modelSettings": {
    "claude-opus-5-5": {
      "effortLevel": "high"
    }
  }
}

Con ese archivo en los ajustes de usuario, la prueba envió high para Opus 5.5 y medium para Sonnet 5.5, porque la entrada solo vale para su modelo; con el mismo archivo y --effort low, se envió low. Como atajo de teclado, las flechas izquierda y derecha mueven el nivel en el deslizador de /effort (v2.1.284 o posterior) y en el de /model.

Por qué el effort no se guarda o vuelve a medium

Casi siempre hay una fuente con más prioridad, una clave que el modelo ignora o un nivel que solo vale para la sesión. La tabla cruza cada síntoma con su causa; las filas marcadas como probadas se reprodujeron el 2 de noviembre de 2026 con Claude Code 2.1.316 en los ajustes de usuario (los ajustes de proyecto y los administrados no entraron en la prueba, y lo que se dice de ellos viene de la documentación).

La última fila sale de la sección sobre IDs de proveedor de la guía de configuración de modelos de Claude Code: la misma variable existe con los sufijos de Sonnet, Haiku y Fable, y cuando la defines Claude Code activa solo las capacidades que enumeras. Esas variables _SUPPORTED_CAPABILITIES solo tienen efecto con Bedrock, Google Cloud Agent Platform y Microsoft Foundry. Si usas una pasarela a través de ANTHROPIC_BASE_URL, de esa familia solo se aplican _NAME y _DESCRIPTION, y con la API directa de Anthropic no se aplica ninguna, así que declarar capacidades no cambia el effort en esos dos casos.

Cómo comprobar el nivel de effort que se envía de verdad

El indicador de la barra muestra el nivel que fijaste, no necesariamente el que se está usando, así que conviene revisar las fuentes en el mismo orden en que Claude Code las aplica. Estos pasos sirven tanto con suscripción como con clave de API o pasarela propia:

1. Escribe /effort status dentro de la sesión. Con una configuración limpia y Opus 5.5, la prueba del 2 de noviembre de 2026 devolvió Effort level: auto (currently medium): no has elegido nivel, pero Claude Code sigue enviando el medium por defecto del modelo. Si aparece Effort level: auto sin paréntesis, no se envía ningún nivel.
2. Mira el pie de la terminal. En la prueba pasó de ◐ medium · /effort al arrancar a ● high tras /effort high y a ◈ max tras /effort max. El encabezado de la sesión («with low effort», por ejemplo) también refleja el ajuste.
3. En el shell desde el que lanzas claude, ejecuta echo $CLAUDE_CODE_EFFORT_LEVEL. Si devuelve algo, ese valor manda sobre todo lo demás.
4. Abre ~/.claude/settings.json y los ajustes del proyecto, y busca maxEffortLevel, modelSettings y un effortLevel de nivel superior. Un effortLevel en los ajustes de proyecto, locales o administrados sí se aplica a todos los modelos, incluido Opus 5.5.
5. En ejecuciones con -p, lee la salida de error: ahí aparecen el aviso de valor desconocido y el de tope superado.

El cambio no afecta a la respuesta que Claude ya está escribiendo. Cuando /effort confirma el nivel, se aplica desde el siguiente mensaje que envíes; si quieres que entre a mitad de una tarea larga, pon en cola un mensaje como keep going mientras Claude trabaja. En /model, el nuevo nivel empieza como muy tarde con tu siguiente mensaje.

Qué significa auto: /effort auto frente a CLAUDE_CODE_EFFORT_LEVEL=auto

Los dos «auto» hacen cosas distintas. /effort auto borra el nivel que guardaste para el modelo activo, de modo que Claude Code vuelve a enviar el valor por defecto de ese modelo; la variable de entorno con valor auto (o unset, que equivale a lo mismo) hace que Claude Code no envíe ningún nivel, y entonces decide el valor por defecto de la API.

La prueba del 2 de noviembre de 2026 lo muestra con Opus 5.5. Tras /effort high, /effort auto respondió Effort level set to auto, la entrada claude-opus-5-5 de settings.json quedó vacía ({}), el siguiente mensaje salió en medium y /effort status volvió a mostrar Effort level: auto (currently medium). En cambio, con CLAUDE_CODE_EFFORT_LEVEL=auto la petición salió sin ningún campo de effort; según la documentación, el encabezado y el pie dejan entonces de mostrar el nivel.

La diferencia importa con Sonnet 5.5: con la variable en auto, Claude Code deja de enviar su medium y se aplica el valor por defecto de la Claude API, que según la documentación de effort de la Claude API es high para ese modelo. Si además tienes un maxEffortLevel por debajo de max, Claude Code sigue enviando su propio valor por defecto recortado al tope, y /effort status lo indica con auto (currently …).

Ultracode no es un nivel de effort (salvo con --effort ultracode)

Ultracode es un interruptor de Claude Code, no un sexto nivel: con él activado, Claude organiza flujos de trabajo dinámicos para las tareas de cierta entidad, con el nivel de effort que tenga la sesión. Por eso la pregunta «¿max o ultracode?» no tiene una sola respuesta: puedes tener ultracode activado con medium, con max o con cualquier otro nivel. Se activa con /effort ultracode, se apaga con /effort ultracode off, se alterna con Tab en el deslizador de /effort (donde la prueba mostró Ultracode off · Tab to toggle) y se fija con "ultracode": true en los ajustes. Encenderlo o apagarlo no cambia el nivel.

La excepción es el flag de arranque. claude --effort ultracode activa ultracode y además fija xhigh: en la prueba del 2 de noviembre de 2026, con Opus 5.5 se envió xhigh, y con Opus 4.6, que no tiene xhigh, se envió high (en ese caso la documentación indica que ultracode arranca desactivado). La orquestación de flujos en sí no se probó. Ni effortLevel ni CLAUDE_CODE_EFFORT_LEVEL aceptan ultracode, y el comportamiento descrito aquí es el de v2.1.284 en adelante; antes, activar ultracode ponía la sesión en xhigh y elegir otro nivel lo desactivaba.

Ultrathink y «think hard»: qué cambia solo en un turno

Escribir ultrathink en cualquier parte del mensaje pide un razonamiento más profundo para ese turno sin tocar el nivel de la sesión. «think», «think hard» o «think more» no son palabras clave: Claude Code los envía como texto normal.

Lo que hace ultrathink depende de dónde lo escribas, según la prueba del 2 de noviembre de 2026 con la sesión en medium. En la terminal interactiva, el turno «ultrathink about this and reply with OK» se envió en xhigh, el siguiente mensaje normal volvió a medium y el pie siguió marcando medium. Con claude -p "ultrathink: reply with OK", en cambio, la petición se quedó en medium y Claude Code solo añadió al contexto esta instrucción: The user included the keyword "ultrathink", requesting deeper reasoning on this turn. Reason as thoroughly as the task warrants. Con -p "think hard: reply with OK" no añadió nada.

Según la documentación, la subida a xhigh requiere v2.1.311 o posterior, y cuando es posible la palabra aparece con colores de arcoíris (algo que la captura de texto de la prueba no puede mostrar). Si no se colorea, la solución depende de la causa. Si CLAUDE_CODE_EFFORT_LEVEL está definida por debajo de xhigh, quítala del shell y del perfil donde la exportas, porque mientras exista ningún /effort le gana. Si lo impide un tope, sube tu maxEffortLevel a xhigh o más, o pide al administrador que suba el límite de la organización. Si el modelo no lo permite, cambia con /model a Opus 5.5, Sonnet 5.5, Haiku 5.5 o Fable 5.1. Solo donde la palabra no puede subir ningún turno, como en Amazon Bedrock, la alternativa es fijar directamente un nivel más alto.

Limitar el effort de un equipo o de un modelo con maxEffortLevel

Para poner un techo, la clave es maxEffortLevel (v2.1.267 o posterior), no effortLevel. Cualquier nivel por encima del tope se ejecuta en el tope, venga de /effort, de /model, de --effort, de la variable de entorno, del frontmatter de un skill o subagente o del propio valor por defecto del modelo, y los niveles superiores dejan de aparecer en el deslizador. Claude Code aplica el tope en el cliente antes de cada petición, así que funciona con cualquier proveedor, incluidos Amazon Bedrock, Google Cloud Agent Platform y Microsoft Foundry.

Este ejemplo de la referencia de ajustes limita todos los modelos a medium y deja libre a Sonnet 4.6, porque "max" equivale a no tener tope:

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

En la prueba del 2 de noviembre de 2026, con "maxEffortLevel": "high" y --effort max, se envió high y stderr mostró Effort 'max' exceeds the cap for claude-opus-5-5 set by your settings or organization; using 'high'. Con el mismo tope y CLAUDE_CODE_EFFORT_LEVEL=xhigh también se envió high, pero esta vez sin ningún mensaje en la salida de -p, así que un tope puede bajar el nivel sin que lo notes.

Para un equipo, coloca el tope en los ajustes administrados: si varios archivos definen uno, se aplica el más bajo, y nadie puede subirlo desde otro nivel de configuración. En Claude Enterprise, los administradores también pueden fijar límites por rol y por modelo (v2.1.195 o posterior), y cuando coinciden con maxEffortLevel manda el menor. Un effortLevel en los ajustes administrados solo fija el punto de partida, y cada usuario puede cambiarlo con /effort o --effort.

Preguntas frecuentes sobre effort en Claude Code

¿Un skill o un subagente puede usar su propio effort?

Sí. Si el frontmatter del archivo markdown de un skill o de un subagente incluye effort, ese nivel sustituye al de la sesión mientras dura el turno del skill o mientras corre el subagente, salvo que la invocación del subagente indique otro. Hay dos excepciones, según la guía de configuración de modelos de Claude Code a 2 de noviembre de 2026: si CLAUDE_CODE_EFFORT_LEVEL está definida, se usa su valor, y un maxEffortLevel o un límite de la organización sigue recortándolo.

¿Qué significa «Effort 'xhigh' isn't available with thinking turned off»?

El mensaje completo es API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0). Aparece cuando desactivas el pensamiento (por ejemplo con MAX_THINKING_TOKENS=0) en un modelo que no acepta niveles por encima de high sin él, como Opus 5. La solución es la que indica el propio mensaje: /effort high o quitar esa variable. Desde v2.1.251, Claude Code envía high por su cuenta a los modelos que sabe que rechazan la combinación, y en Opus 5.5, Sonnet 5.5, Haiku 5.5 y los modelos Fable el pensamiento no se puede desactivar, así que allí el único control es el effort. Las versiones anteriores a v2.1.242 mostraban otro texto: API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model.