Claude Code 2.1.310: errores de gateway y hooks de Windows

Si Claude Code falla al conectarse mediante un gateway con Unexpected value(s) y una referencia a effort-2025-11-24, o con Unexpected role "system", actualiza a 2.1.310 o posterior y vuelve a intentar la solicitud en la conversación afectada. Los equipos que usan Windows también deben comprobar si un fallo del intérprete de un hook bloquea realmente la llamada a una herramienta. Si has configurado un valor extremo de cleanupPeriodDays y han desaparecido imágenes pegadas, conserva los datos que aún existen antes de cambiar la retención.

A fecha de 2026-10-25, las notas oficiales de la versión 2.1.310 confirman las correcciones para estos casos de gateways, hooks de Windows y limpieza de archivos. Los procedimientos siguientes permiten diagnosticar cada fallo por separado.

Comprueba que el ejecutable activo sea 2.1.310 o posterior

Comprueba qué ejecutable inicia tu terminal y actualízalo mediante el mismo método que utilizaste para instalarlo. Ejecuta lo siguiente en Bash, o sin cambios en Windows PowerShell:

claude --version
claude doctor

claude doctor ofrece diagnósticos de solo lectura sobre la instalación y la configuración. Guarda la salida de la versión para compararla después de actualizar.

Utiliza el comando correspondiente de las instrucciones de instalación y actualización de Anthropic:

Instalación existente	Shell	Comando de actualización
Instalador nativo	Bash o PowerShell	`claude update`
Cask stable de Homebrew	Bash	`brew upgrade claude-code`
Cask latest de Homebrew	Bash	`brew upgrade claude-code@latest`
WinGet	PowerShell	`winget upgrade Anthropic.ClaudeCode`
npm	Bash o PowerShell	`npm install -g @anthropic-ai/claude-code@latest`

Las actualizaciones nativas siguen el canal de versiones configurado. El cask claude-code de Homebrew sigue stable, mientras que claude-code@latest sigue latest; por eso, una actualización puede completarse correctamente y dejarte en una versión inferior a la necesaria.

Si ya tienes una instalación nativa, la CLI también permite instalar una versión concreta con claude install 2.1.310. En un despliegue gestionado mediante paquetes, selecciona un paquete o canal que proporcione la versión necesaria siguiendo el procedimiento habitual de ese despliegue.

Vuelve a ejecutar claude --version y abre una nueva sesión de Claude Code. Si sigue apareciendo una versión antigua, busca instalaciones en conflicto con which -a claude en Bash o where.exe claude en PowerShell. Si utilizas la terminal de un editor, quizá debas reiniciar también el editor para que reconozca los cambios en PATH.

Identifica qué reintento corresponde al error del gateway

Elige la corrección según el texto del error devuelto. Un 400 genérico no identifica qué capacidad ha rechazado el gateway.

La guía de compatibilidad con gateways de Anthropic documenta estas vías de recuperación:

Patrón de la respuesta	Ajuste automático del reintento	Qué comprobar
`400` que empieza por `Unexpected value(s)` y menciona `effort-2025-11-24` para `anthropic-beta`	Omite el campo effort y su beta para ese modelo hasta que se cierra Claude Code.	Elimina ese valor si lo añadiste manualmente a `ANTHROPIC_BETAS`.
`400` que menciona `output_config.effort` con `Extra inputs are not permitted`, o indica que effort no es compatible	Aplica el reintento sin effort.	Confirma que effort sea el campo rechazado.
`400`, por ejemplo `Unexpected role "system"`	Traslada el texto de sistema intercalado en la conversación a mensajes de usuario; conserva ese formato hasta `/clear` o la compactación del contexto.	Vuelve a intentar la solicitud en la conversación afectada.

Este mecanismo modifica la solicitud. El parámetro effort controla cómo gasta tokens el modelo, por lo que un reintento exitoso sin ese parámetro no demuestra que se haya respetado el nivel de effort solicitado. Del mismo modo, trasladar texto de sistema a mensajes de usuario conserva el texto, pero cambia su representación.

Reproduce el fallo en la misma conversación

Mantén el mismo gateway, la misma fuente de credenciales y el mismo modelo seleccionado mientras compruebas la actualización. Así podrás comparar los resultados: cambiar a la vez de proveedor y de versión impediría determinar la causa.

Primero, inicia Claude Code y ejecuta /status. Las instrucciones de conexión a un gateway explican cómo confirmar ahí la URL base activa y la fuente de credenciales. Si no aparece el gateway previsto, corrige esa configuración antes de investigar su compatibilidad con la beta.

Después, sal y vuelve a abrir la conversación afectada con un registro de diagnóstico local. En Bash:

claude --resume --debug-file ./claude-gateway-debug.log

Elige la sesión que falló en el selector y repite la solicitud más pequeña que reproduzca el problema. Estas opciones están documentadas en la referencia de la CLI.

La comprobación inmediata consiste en obtener una respuesta útil del asistente donde antes fallaba la solicitud. Para confirmar que la recuperación se debe al ajuste de compatibilidad, revisa los diagnósticos disponibles del cliente y, si los tienes, los de las solicitudes del gateway: busca el rechazo seguido del reintento modificado. Que el primer mensaje de una conversación nueva funcione no comprueba todas las estructuras que pueden aparecer más adelante.

En BetterToken, las instrucciones de configuración de Claude Code especifican ANTHROPIC_BASE_URL=https://bettertoken.ai sin /v1; mantén esa ruta documentada mientras verificas la actualización del cliente.

Si el cliente actualizado sigue fallando

Conserva el cuerpo de los errores del servicio de origen: sustituir un rechazo reconocible por un error opaco del gateway puede impedir que el cliente detecte cuándo debe ajustar el reintento. Además, CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 conserva effort y las entradas de sistema intercaladas en la conversación, por lo que no resuelve universalmente estos fallos.

Elige el siguiente paso según la evidencia que quede:

Se repite el mismo rechazo reconocido: comprueba el ejecutable activo, los valores beta añadidos manualmente y si el gateway modifica el error del servicio de origen.
Falla la autenticación: sigue las instrucciones de credenciales del gateway. La guía de conexión distingue ANTHROPIC_AUTH_TOKEN para autenticación Bearer de ANTHROPIC_API_KEY para x-api-key; utiliza el esquema documentado por tu proveedor.
El error menciona otro campo: investiga los requisitos de compatibilidad de ese campo. No atribuyas todos los rechazos de esquema al fallo de effort.
La conexión falla antes de recibir una respuesta de la API: revisa el endpoint, el proxy, DNS o la conexión TLS.

Para escalar el problema, reúne la versión del cliente, el sistema operativo, el ID del modelo seleccionado, la hora o el ID de la solicitud, el estado HTTP y el error exacto. Comparte un extracto del diagnóstico con los datos sensibles eliminados, no las credenciales ni el registro completo de la conversación.

Comprueba que los hooks de Windows realmente bloqueen la llamada

Actualiza, como mínimo, a 2.1.310 y prueba qué ocurre cuando falla un hook del que dependes para aplicar políticas. Las dos versiones consecutivas cubren casos diferentes:

2.1.309 corrige el tratamiento de los códigos de salida de los hooks de PowerShell y los fallos por ausencia de Git cuando el hook selecciona PowerShell explícitamente.
2.1.310 corrige el caso adicional en el que falta Git Bash y el comando del hook contiene únicamente cadenas entre comillas.

Un error del hook no equivale automáticamente a una denegación. La referencia de hooks ofrece onFailure: "block" para los hooks de comando y HTTP que deban detener la acción que los activó si fallan.

Comprueba la regresión de los comandos entre comillas

Utiliza un entorno de prueba desechable con Windows nativo, sin Git Bash, con una conexión funcional de Claude Code y sin hooks ni plugins ajenos a la prueba que alteren el resultado. Así comprobarás el caso de ausencia de Git Bash sin quitar Git de tu equipo de trabajo.

En PowerShell, crea un directorio nuevo para la prueba y un archivo inofensivo:

$hookProbe = Join-Path $env:TEMP ("claude-hook-probe-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path (Join-Path $hookProbe '.claude') -Force | Out-Null
Set-Location $hookProbe
Set-Content -LiteralPath .\probe.txt -Value ([guid]::NewGuid().ToString())
Test-Path 'C:\__claude_hook_probe_missing__\python.exe'
claude --version

Test-Path debe devolver False, y la versión debe ser al menos 2.1.310.

Crea .claude/settings.local.json en este directorio de prueba con el siguiente contenido:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "\"C:\\__claude_hook_probe_missing__\\python.exe\""
          }
        ]
      }
    ]
  }
}

La omisión de los campos shell, args y onFailure es deliberada: esta fase comprueba el propio mecanismo alternativo de ejecución del comando entre comillas.

Inicia la sesión en PowerShell:

claude --tools Read --debug-file .\phase1.log

Acepta la confianza en el espacio de trabajo para este directorio desechable. Después, ejecuta /hooks y confirma que el hook PreToolUse coincida con Read. Pide lo siguiente:

Utiliza la herramienta Read exactamente una vez para leer probe.txt. Si la llamada queda bloqueada, indícalo y detente. No utilices otro método.

Resultado esperado: la llamada a Read queda bloqueada y aparece PowerShell started no program en el error o en los diagnósticos. PowerShell normalmente evalúa una ruta entre comillas como una cadena; la documentación de Microsoft sobre el operador de llamada explica por qué ejecutar esa ruta requiere otra sintaxis.

Un resultado exitoso de Read significa que esta comprobación ha fallado. Si Claude nunca intenta llamar a Read, el resultado no es concluyente. Inspecciona el resultado de la herramienta y el registro, sin aceptar como prueba únicamente la descripción del modelo.

Si /hooks no muestra la configuración, sigue las comprobaciones de carga de hooks. La configuración suele recargarse automáticamente, pero reiniciar fuerza su lectura si el observador de archivos no detectó el cambio. Si una política de la organización solo permite hooks administrados, esta prueba a nivel de proyecto tampoco se habrá ejecutado.

Comprueba el fallo de un intérprete que realmente no existe

Utiliza una política de fallo explícita para comprobar qué ocurre cuando el intérprete no puede iniciarse. Sal de la sesión de prueba y sustituye únicamente el objeto interno del hook por:

{
  "type": "command",
  "command": "C:\\__claude_hook_probe_missing__\\python.exe",
  "args": [],
  "onFailure": "block"
}

Aquí, args selecciona la invocación directa del ejecutable. La ausencia del archivo provoca ahora un fallo real de inicio, en lugar de evaluar una expresión de cadena entre comillas.

Vuelve a iniciar la sesión en PowerShell y repite la misma instrucción para Read:

claude --tools Read --debug-file .\phase2.log

Resultado esperado: Read queda bloqueado porque el intérprete no pudo iniciarse. Esto comprueba la gestión explícita del fallo independientemente de que Git Bash esté disponible; es una prueba distinta de la regresión del comando entre comillas.

Después de revisar los resultados, elimina la configuración de prueba. En los hooks que aplican políticas reales, restablece el intérprete funcional y conserva una política explícita de bloqueo si una comprobación fallida debe detener la acción.

Estas pruebas ejercitan PreToolUse. Un hook PermissionRequest necesita una comprobación independiente con una acción que llegue a la fase de permisos. Su denegación normal utiliza hookSpecificOutput.decision.behavior con el valor "deny"; el código de salida 2 por sí solo no deniega ese evento. Un fallo real con onFailure: "block" sí deniega la solicitud.

Sustituye los valores extremos de retención de forma deliberada

Utiliza el valor predeterminado documentado de 30 días, salvo que tu equipo necesite otro plazo de retención, y archiva el historial que quieras conservar antes de reducir el período existente.

La corrección de limpieza resuelve la eliminación de archivos recientes asociada a valores extremadamente altos de cleanupPeriodDays. No convierte ese ajuste en un sistema de archivo ni restaura los archivos ya eliminados.

Conserva los datos existentes antes de cambiar el plazo

Detén las sesiones activas y copia los datos que aún necesitas a una ubicación fuera de los directorios gestionados por Claude Code. Incluye los datos pertinentes de ~/.claude, o de %USERPROFILE%\.claude en Windows, junto con los adjuntos de imagen que todavía existan.

La documentación actual sobre los datos de la aplicación sitúa las nuevas imágenes pegadas en directorios images/ por sesión, bajo el directorio raíz temporal de Claude Code, controlado por CLAUDE_CODE_TMPDIR. Por tanto, copiar únicamente ~/.claude no demuestra que hayas conservado las copias actuales de las imágenes.

Después de preservar los datos, incorpora este ajuste al archivo de configuración correspondiente:

{
  "cleanupPeriodDays": 30
}

Para establecer tu valor predeterminado personal, ese archivo es ~/.claude/settings.json, o %USERPROFILE%\.claude\settings.json en Windows. Conserva las demás claves.

Según la documentación consultada el 2026-10-25, el mínimo es 1; 0 no supera la validación. Reducir el período hace que los datos más antiguos puedan quedar sujetos a la limpieza, de ahí que debas conservarlos primero.

Ejecuta claude doctor para comprobar la validez de la configuración. Si no se aplica el valor previsto, revisa la precedencia de la configuración: los ajustes administrados y los ajustes de sesión o proyecto de mayor prioridad pueden prevalecer sobre tu archivo personal. /status muestra las fuentes cargadas, no el valor efectivo de cada clave individual.

Recupera los adjuntos perdidos por separado

Restaura la imagen que falta desde su archivo original o una copia de seguridad existente del sistema de archivos, y adjunta esa copia recuperada a la conversación. Comprueba que el archivo se abra localmente y que Claude pueda utilizar de nuevo el adjunto.

Cambiar el ajuste de retención no puede reconstruir los bytes eliminados. Tampoco debes dar por hecho que /rewind recuperará un adjunto: las instantáneas de los puntos de control también caducan, y la restauración puede fallar si ya no existen las instantáneas necesarias.

Si tu equipo ya exporta telemetría, inspecciona un evento claude_code.retention_sweep completado. La referencia de monitorización documenta result: "complete" y period_days como una cadena; "30" confirma que esa ejecución concreta de limpieza utilizó un plazo de 30 días.

Un reinicio breve no basta para demostrar que se haya ejecutado la limpieza. El proceso se ejecuta en segundo plano como máximo una vez por sesión, y una ejecución durante las 24 horas anteriores retrasa la de la siguiente sesión al menos 10 minutos. Trata la posibilidad de abrir los adjuntos y la evidencia de una limpieza completada como observaciones independientes.

La disponibilidad de Monitor es un cambio independiente

La versión 2.1.310 también amplía la disponibilidad de la herramienta Monitor y de los monitores de plugins a Bedrock, Vertex y Foundry, incluidas las configuraciones con telemetría o tráfico no esencial desactivados. Las notas de la versión también indican que las esperas prolongadas en primer plano quedan bloqueadas en esos entornos.

Si Monitor no estaba disponible en uno de esos despliegues, comprueba la versión en ejecución antes de cambiar la política de telemetría. Ese cambio de disponibilidad es independiente de que un gateway concreto acepte los ajustes de effort o las entradas de sistema intercaladas en la conversación.