Nota del autor: a partir de las notas de actualización de Claude Code v2.1.318, repasamos las causas y los pasos de diagnóstico para siete tipos de problemas en directorios home de red compartidos, como la pérdida de configuración, el mensaje «Not logged in» y el vencimiento de la sesión.
En entornos como salas de informática universitarias, clústeres HPC o servidores de salto corporativos, el directorio home suele estar montado en NFS u otro sistema de archivos de red, y varias máquinas comparten el mismo ~. Al usar Claude Code en estas condiciones, pueden aparecer problemas como configuraciones de servidores MCP que desaparecen de un día para otro, sesiones que se restablecen justo después de cerrarlas, tareas en segundo plano que de repente muestran «Not logged in» o archivos ~/.claude.json que quedan vacíos. En este artículo veremos cómo diagnosticar problemas de configuración y acceso de Claude Code en directorios home de red compartidos, para que puedas identificar si la causa está en la versión, el sistema de archivos o las propias credenciales.
Esta no es una lista de soluciones improvisadas. Claude Code v2.1.318, publicado el 4 de noviembre de 2026, corrigió una serie de problemas relacionados con los «directorios home de red compartidos». Los pasos de diagnóstico de este artículo se basan en esas notas de actualización.
Lo esencial: al terminar de leer, podrás identificar por los síntomas los fallos de configuración o acceso de Claude Code en un home compartido y saber si necesitas actualizar, restaurar una copia de seguridad o cambiar de método de autenticación.
Puntos clave de la configuración y el inicio de sesión de Claude Code en un directorio home de red compartido
Empecemos por lo general. Claude Code mantiene principalmente tres tipos de información en el directorio home: el archivo de configuración global ~/.claude.json (servidores MCP, directorios de confianza, etc.), los archivos de ajustes y las credenciales de inicio de sesión guardadas. En un home de red compartido, varios procesos y equipos leen y escriben estos archivos al mismo tiempo. Además, el sistema de archivos de red gestiona los bloqueos, la caché y las cuotas de forma distinta a un disco local. La siguiente tabla resume los cambios de la versión v2.1.318 relacionados directamente con este escenario:
| Punto clave | Descripción | Qué aporta |
|---|---|---|
| Los fallos de escritura ya no se notifican como éxitos | Si no se puede actualizar la configuración en un home compartido, /logout, claude auth logout y claude mcp remove ya no indican que la operación se completó correctamente |
Evita creer que cerraste sesión cuando en realidad sigue abierta |
| Volver a iniciar sesión desde otro equipo ya no interrumpe las tareas | Si se vuelve a iniciar sesión con la misma cuenta y organización desde otra terminal u otro equipo que comparte el mismo home, las tareas en ejecución ya no terminan con el mensaje Not logged in | Mayor estabilidad al ejecutar tareas en paralelo en varios equipos |
| Bloqueo de escritura para la configuración de MCP | claude mcp add/remove espera a que se libere el bloqueo de configuración y, si no puede obtenerlo, termina con el código de salida 1 |
Reduce los daños en la configuración causados por escrituras simultáneas |
| La caducidad de la sesión es visible | claude auth status incorpora loginExpiresAt, y el resultado JSON de claude -p añade credential_expires_at |
Permite detectar con antelación cuándo está por caducar una sesión |
| Archivos de configuración más resistentes | Al guardar ~/.claude.json, los archivos de ajustes y las credenciales de inicio de sesión en un home compartido, es menos probable que se eliminen, queden vacíos temporalmente o se sobrescriban con copias antiguas |
Reduce la probabilidad de que la configuración «desaparezca» |
Por qué la configuración de Claude Code puede fallar en un home compartido
En un disco local, el proceso con el que Claude Code guarda la configuración puede considerarse prácticamente una operación atómica. En un sistema de archivos de red, operaciones como «escribir un archivo temporal y luego reemplazar el original» o «comprobar si existe un archivo» pueden dar resultados incorrectos debido a la caché del cliente. Por ejemplo, un archivo puede existir y, aun así, aparecer como ausente. Las versiones anteriores podían interpretar que no había configuración y arrancar sin los servidores MCP ni los directorios de confianza. En v2.1.318, si se informa por error de que falta el archivo de configuración, se vuelve a comprobar, lo que reduce los arranques con una configuración vacía.
Otro riesgo es la cuota de disco. Las notas de la actualización describen una situación en la que el home de red ya no tiene espacio para escribir datos, pero todavía permite crear archivos nuevos. Al guardar las credenciales de inicio de sesión, el archivo de credenciales se reemplazaba por uno vacío y el usuario perdía la sesión. La nueva versión corrige el problema. Si tu clúster tiene una cuota de home muy ajustada, sigue siendo recomendable revisar periódicamente el espacio disponible con df o con el comando de quota del propio clúster.
Problemas de concurrencia al iniciar sesión en Claude Code con un home compartido
El estado de inicio de sesión es otro punto propenso a fallos. Cuando varias máquinas comparten el mismo home, volver a iniciar sesión en la máquina A con claude auth login podía hacer que un trabajo por lotes claude -p en ejecución en la máquina B terminara con el mensaje Not logged in. La versión v2.1.318 corrige este problema, siempre que se trate de la misma cuenta y la misma organización. Además, los comandos de la familia claude plugin podían terminar antes de que se guardara una renovación lenta del token, de modo que al ejecutarlos de nuevo la sesión aparecía cerrada. Esto también se ha corregido.
Hay otro caso más difícil de detectar: otro inicio de sesión en la misma máquina guarda una lista allowedProviders y, al arrancar, esa lista rechaza tu sesión. Esto podía ocurrir cuando varias personas compartían una máquina de salto o cuando un mismo usuario iniciaba sesión en distintas organizaciones. La nueva versión evita este rechazo erróneo.
Guía rápida para resolver problemas de Claude Code con un directorio home compartido
Siguiendo las convenciones de este artículo, no incluimos bloques de código: los comandos y campos aparecen en línea. El proceso de diagnóstico se divide en cuatro pasos que conviene seguir en orden.
Paso 1: comprueba la versión de Claude Code y el estado de la sesión
Primero ejecuta claude --version para ver la versión. Si es anterior a v2.1.318, conviene actualizarla con claude update o mediante el método que usaste para instalarla. Muchos de los problemas que se describen aquí solo pueden sortearse en versiones antiguas, sin una solución definitiva. Después de actualizar, ejecuta claude auth status para comprobar la cuenta y la organización actuales, así como el nuevo campo loginExpiresAt.
Si usas claude -p principalmente en scripts, puedes configurarlo para que devuelva el resultado en JSON y leer el campo credential_expires_at en tu pipeline, de modo que puedas generar una alerta antes de que caduque. En el modo de salida de texto, la nueva versión imprime una advertencia en stderr a partir de 10 días antes de que caduque la sesión guardada de claude.ai. Basta con estar atento a los registros.
| Comando/campo | Función | Qué revisar durante el diagnóstico |
|---|---|---|
claude --version |
Consultar la versión actual | Si es ≥ v2.1.318 |
claude auth status |
Consultar el estado de la sesión | Si loginExpiresAt está próximo |
claude -p (salida JSON) |
Invocación desatendida | El campo credential_expires_at |
claude auth login |
Volver a iniciar sesión en la cuenta de claude.ai | Ejecutarlo siguiendo las instrucciones cuando caduque la sesión |
claude setup-token |
Generar un token para uso desatendido | Adecuado para CI y procesamiento por lotes |
claude mcp add / claude mcp remove |
Gestionar servidores MCP | El código de salida 1 indica que no se obtuvo el bloqueo de configuración |
Segundo paso: comprueba que ~/.claude.json esté intacto
Un archivo ~/.claude.json dañado es la causa más frecuente de la aparente pérdida de toda la configuración cuando se comparte el directorio home. La versión v2.1.318 cambió varios aspectos relacionados: si durante un inicio no interactivo se detecta que el archivo no contiene JSON válido, ya no se sobrescribe con valores predeterminados. En su lugar, el inicio falla, se indican los pasos para recuperarlo y se conserva el archivo original sin cambios (issue #87551). Si el archivo está vacío y no hay copia de seguridad, la nueva versión arranca normalmente, como si el archivo no existiera, sin informar de que está dañado.
Los comandos de recuperación que muestra la nueva versión también son más fiables. Antes podían apuntar a una copia de seguridad vacía o truncada, y también fallaban si el archivo era de solo lectura. Ambos problemas se han corregido. Además, en los directorios home donde solo se ejecuta claude -p, la limpieza por período de retención podía eliminar la última copia de seguridad de ~/.claude.json. Ahora se crea una copia nueva antes de borrar las antiguas.
Tercer paso: resuelve los problemas de inicio de sesión y las credenciales caducadas
Si aparece un error de inicio de sesión, comprueba primero si el mensaje indica que «la sesión guardada de claude.ai ha llegado a su límite de tiempo». La nueva versión lo explica directamente y, en el caso de claude -p, ofrece dos opciones: claude auth login y claude setup-token. La primera es para uso interactivo; la segunda suele ser más adecuada para tareas que se ejecutan durante largos períodos en segundo plano.
En las máquinas con forceLoginOrgUUID activado, que obliga a iniciar sesión en una organización específica, las versiones anteriores tenían un problema: al iniciar con un token generado mediante setup-token, este se rechazaba incluso si pertenecía a la organización permitida. Se corrigió en v2.1.318. Si te ocurre en un entorno empresarial, actualizar suele resolverlo.
Paso 4: Reducir el riesgo de escrituras concurrentes
Cuando varias máquinas modifican a la vez la configuración de MCP, existe un riesgo inherente al uso de un directorio home compartido. Las nuevas versiones de claude mcp add y claude mcp remove esperan a que se libere el bloqueo de configuración y, si no lo consiguen, terminan con el código de salida 1 en lugar de escribir sin bloqueo. Hay un matiz importante: las notas de actualización también indican que, si otra tarea guarda la configuración, todavía podría sobrescribir una entrada de servidor que acabas de guardar. Por eso, cuando hagas cambios masivos en la configuración de MCP, procura ejecutarlos de forma secuencial desde una sola máquina.
Además, en las ejecuciones desatendidas (claude -p y aplicaciones SDK), ~/.claude.json ya no se reescribe cada vez si la configuración no ha cambiado. Esto reduce considerablemente la presión de escritura sobre el archivo cuando se ejecutan muchas tareas en paralelo. Si tu clúster todavía usa una versión anterior para procesar grandes lotes de tareas, esta es otra razón para actualizar.
🚀 Inicio rápido: Si tu equipo usa Claude Code para ejecutar procesos por lotes en un clúster y no quiere depender de que caduque la sesión de la cuenta de claude.ai, puede acceder mediante la API. APIYI apiyi.com ofrece acceso mediante API a los modelos de la familia Claude, compatible tanto con el formato de interfaz de OpenAI como con el de Anthropic. Encontrarás las instrucciones de integración en el centro de documentación: docs.apiyi.com.
Problemas habituales de Claude Code con un home compartido
La siguiente tabla reúne los síntomas más comunes, sus posibles causas y las acciones recomendadas para que puedas buscar directamente por síntoma.
| Síntoma | Posible causa | Acción recomendada |
|---|---|---|
/logout indica que se ejecutó correctamente, pero la siguiente vez que se inicia sigue habiendo una sesión activa |
La versión anterior informaba de que la operación había terminado correctamente aunque fallara al escribir la configuración en un home compartido | Actualiza a v2.1.318, ejecuta claude auth logout y comprueba el resultado |
| Una tarea en segundo plano muestra de repente Not logged in | Otro terminal o máquina volvió a iniciar sesión en el mismo home | Actualiza; el problema ya está corregido para la misma cuenta dentro de la misma organización |
| Al iniciar desaparecen todos los servidores MCP y directorios de confianza | El sistema de archivos de red informó erróneamente de que faltaba el archivo de configuración | Actualiza para activar la lógica de nueva comprobación y, si es necesario, restaura desde una copia de seguridad |
| El archivo de credenciales queda vacío | El espacio del home está lleno, pero todavía se pueden crear archivos nuevos | Libera espacio de la cuota, vuelve a iniciar sesión y actualiza |
| El inicio no interactivo falla inmediatamente y solicita una recuperación | ~/.claude.json no contiene JSON válido |
Sigue el comando de recuperación indicado; no sobrescribas el archivo manualmente |
| El inicio es rechazado por allowedProviders | Interfiere la lista guardada por otra sesión en la misma máquina | Actualiza y vuelve a intentarlo |
| Fallan todas las conexiones de red | NODE_EXTRA_CA_CERTS apunta a un archivo vacío o que no está en formato PEM | La nueva versión usará los certificados legibles y mostrará una advertencia en stderr; corrige también el archivo de certificados |
Hay un escenario entre distintos usuarios que merece una explicación aparte. Si alguien ejecutó sudo claude y dejó un proceso activo que pertenece a otro usuario, la limpieza de versiones de la versión anterior podía considerar erróneamente que el proceso había terminado y eliminar el ejecutable que estaba usando. En un problema relacionado, si una actualización o limpieza de versiones eliminaba el binario de un proceso que seguía activo, el host de remote-control, los procesos en segundo plano y los runners autohospedados mostraban spawn ENOENT al iniciar una nueva sesión. Ambos problemas se corrigieron en v2.1.318. Aun así, en entornos compartidos se recomienda evitar ejecutar Claude Code con sudo.
Claude Code v2.1.318: comparativa para entornos con home compartido
| Escenario | Antes de v2.1.318 | A partir de v2.1.318 |
|---|---|---|
| Fallo al escribir la configuración del home compartido | El cierre de sesión y la eliminación de MCP seguían notificándose como exitosos; los cambios de confianza y de configuración de MCP se descartaban sin avisar | Ya no se notifican como exitosos |
~/.claude.json con JSON no válido |
El inicio no interactivo lo sobrescribía con valores predeterminados | El inicio falla, indica cómo recuperar los datos y conserva el archivo original |
~/.claude.json vacío y sin copia de seguridad |
Se notificaba como dañado | Se inicia normalmente, como si el archivo no existiera |
| Sesión caducada | Solo se mostraba un error de inicio de sesión genérico | Se indica claramente que ha caducado y se sugieren claude auth login y claude setup-token |
| Aviso previo de caducidad | Ninguno | Se emite una advertencia en stderr con 10 días de antelación; el comando de estado permite consultar la fecha de caducidad |
| Ejecución desatendida | Se reescribía ~/.claude.json en cada ejecución |
Ya no se reescribe si el contenido no ha cambiado |
Como muestra la tabla, el enfoque de las correcciones de v2.1.318 es informar de los fallos tal como ocurren y preservar los datos del usuario siempre que sea posible cuando la configuración está dañada. Para los equipos de operaciones, esto significa menos situaciones que parecen normales aunque ya haya un error, una detección más temprana y menos tiempo de diagnóstico.
Si ejecutas procesos por lotes a gran escala en un clúster compartido, una opción más segura es seguir usando el inicio de sesión con una cuenta para el desarrollo interactivo y autenticar las tareas por lotes con un token generado por setup-token o directamente mediante la API. Así, las credenciales de ambos entornos no interfieren entre sí.
Conectar Claude Code mediante API para evitar problemas de inicio de sesión con un directorio home compartido
Muchos de los problemas de inicio de sesión en un home compartido se deben a que varios equipos utilizan las mismas credenciales de claude.ai. Si las tareas por lotes usan una clave API para autenticarse, las credenciales se inyectan mediante variables de entorno y dejan de depender de los archivos de sesión guardados en el directorio home. Así, problemas como las sesiones que se cierran entre equipos o la caducidad del inicio de sesión prácticamente desaparecen. Claude Code permite especificar el endpoint y la clave API mediante variables de entorno como ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN. Consulta la documentación oficial para conocer los nombres exactos de las variables y las versiones compatibles.
🎯 Recomendación técnica: APIYI apiyi.com ofrece acceso mediante API a los modelos de la serie Claude y es compatible tanto con el formato nativo de Anthropic como con el de OpenAI. Esto permite configurar un endpoint común para Claude Code y otras herramientas. Para obtener la Base URL, conseguir una clave y consultar ejemplos de configuración, revisa la documentación de APIYI en docs.apiyi.com.
| Aspecto | Inicio de sesión con cuenta de claude.ai | Acceso con clave API (como APIYI) |
|---|---|---|
| Almacenamiento de credenciales | Sesión guardada en el directorio home | Variables de entorno o sistema de gestión de claves |
| Efecto del home compartido | Varios equipos comparten las credenciales, con posibles problemas de concurrencia y caducidad | Se inyectan de forma independiente en cada tarea, sin interferencias |
| Gestión de la caducidad | Hay que vigilar loginExpiresAt | Depende de la vigencia y la cuota de la clave |
| Formato de la interfaz | Integrado en Claude Code | Compatible con los formatos de Anthropic y OpenAI |
| Facturación | Según las reglas de suscripción y uso de la cuenta | Según los datos vigentes en la página de precios de APIYI: docs.apiyi.com/models |
💰 Nota sobre costos: Para conocer los detalles de facturación, como los precios de los modelos, las tarifas de entrada y salida o los precios de caché, consulta los datos actualizados de la página de precios de APIYI en docs.apiyi.com/models. Este artículo no incluye cifras concretas para evitar que los cambios de precio puedan resultar engañosos.
Preguntas frecuentes FAQ
Q1: ¿Qué es un directorio home compartido por red y por qué Claude Code puede dar más problemas en este entorno?
Es el directorio personal de un usuario montado mediante un sistema de archivos de red, como NFS, y compartido entre varios equipos. Claude Code guarda la configuración global, los ajustes y las credenciales de inicio de sesión en home. Las escrituras simultáneas de varios procesos, los informes erróneos de la caché del sistema de archivos y los comportamientos anómalos al escribir cuando se agota la cuota pueden provocar la pérdida de configuración o invalidar el inicio de sesión.
Q2: ¿Qué cambia para Claude Code en un home compartido antes y después de v2.1.318?
Las versiones anteriores podían informar silenciosamente de que una escritura había tenido éxito cuando había fallado, o sobrescribir una configuración dañada con valores predeterminados. A partir de v2.1.318, se informa del error, se conserva el archivo original y se ofrecen instrucciones de recuperación. También se ha mejorado la estabilidad al guardar archivos de configuración en un home compartido y se ha añadido un campo con la fecha de vencimiento del inicio de sesión.
Q3: ¿Cuándo se publicaron estas correcciones?
Las correcciones están incluidas en Claude Code v2.1.318, cuya fecha de publicación en GitHub Release es el 4 de noviembre. Puedes comprobar la versión instalada con `claude –version`. Si es anterior, conviene actualizar antes de buscar la causa del problema.
Q4: ¿Qué hago si las tareas en segundo plano muestran constantemente Not logged in?
Primero, comprueba si se ha vuelto a iniciar sesión en la misma cuenta desde otro terminal o equipo que use el mismo home. Tras actualizar a v2.1.318, este problema queda resuelto cuando se trata de la misma cuenta y organización. Si se inicia sesión en distintas organizaciones o las credenciales ya han vencido, para las tareas de larga duración conviene usar un token generado con `claude setup-token` o la autenticación mediante clave API.
Q5: ¿Cómo puedo hacer que Claude Code invoque modelos mediante API sin iniciar sesión en una cuenta?
Puedes especificar el endpoint y la clave API de Claude Code mediante variables de entorno. APIYI apiyi.com ofrece acceso por API a los modelos Claude y es compatible con los formatos de interfaz de Anthropic y OpenAI, por lo que puede utilizarse como endpoint unificado. Consulta los pasos de configuración en docs.apiyi.com y los precios en docs.apiyi.com/models.
Q6: Si ~/.claude.json está dañado, ¿puedo eliminarlo y volver a crearlo directamente?
No es recomendable eliminarlo directamente. Si encuentra JSON no válido, la nueva versión detiene el inicio y muestra un comando de recuperación. Lo mejor es seguir esas indicaciones para restaurar el archivo desde una copia de seguridad. Si el archivo está vacío y no hay copia, la nueva versión arrancará con normalidad como si el archivo no existiera, pero tendrás que volver a añadir los servidores MCP y los directorios de confianza configurados anteriormente.
Q7: Después de actualizar a v2.1.318, ¿qué limitaciones conocidas quedan en un home compartido?
Las notas de la actualización indican que, aunque `claude mcp add/remove` ya utiliza un bloqueo, otra tarea que guarde la configuración todavía podría sobrescribir una entrada de servidor que acabas de guardar. Los problemas de cuota ajustada o de una caché demasiado agresiva del sistema de archivos también solo se pueden mitigar parcialmente. En entornos con mucha concurrencia, conviene gestionar la configuración de forma secuencial o separar las credenciales del procesamiento por lotes de las del uso interactivo.
Puntos clave para solucionar problemas de Claude Code con un directorio home compartido
- Revisa primero la versión: antes de diagnosticar el problema, confirma que Claude Code sea v2.1.318 o posterior. La mayoría de los problemas con directorios home compartidos se resuelven al actualizar.
- Anticípate al vencimiento de la sesión: usa el campo
loginExpiresAtdeclaude auth statuspara detectar cuándo está por vencer. - No borres la configuración sin más: si hay un problema con
~/.claude.json, sigue el comando de recuperación que indique la nueva versión para conservar la configuración. - Serializa los cambios concurrentes: realiza los cambios de configuración de MCP desde una sola máquina para evitar que distintos hosts sobrescriban sus cambios.
- Vigila la cuota: si se agota el espacio del directorio home, las credenciales pueden quedar vacías. Revísalo periódicamente.
- Separa las credenciales para procesos por lotes: usa un token generado con setup-token o una clave API para las tareas de larga duración, aparte del inicio de sesión interactivo.
- La conexión mediante API es opcional: APIYI es compatible con los formatos de Anthropic y OpenAI. Consulta la facturación en docs.apiyi.com/models.
Resumen
Los puntos clave para solucionar problemas de configuración e inicio de sesión de Claude Code en un directorio home compartido en red son:
- La versión es lo primero: v2.1.318 corrige, entre otros problemas, los cierres de sesión que parecían exitosos pero no lo eran, los inicios de sesión desde otros hosts que interrumpían tareas y la configuración que se sobrescribía o quedaba vacía. Actualizar es el primer paso.
- Identifica el problema según los síntomas: si se pierde la configuración, revisa primero
~/.claude.jsony sus copias de seguridad; si falla el inicio de sesión, comprueba la fecha de vencimiento y el archivo de credenciales; si se interrumpen tareas, revisa las escrituras concurrentes y la cuota de disco. - Separa las credenciales según su uso: inicia sesión con una cuenta para el desarrollo interactivo y usa un token o una clave API para los procesos por lotes. Así reduces desde el principio los conflictos que puede causar un directorio home compartido.
Si tu equipo usa Claude Code a gran escala en un clúster compartido, conviene planificar claramente los métodos de autenticación. Si necesitan un endpoint de API unificado, pueden consultar la documentación de APIYI en apiyi.com y docs.apiyi.com para evaluarlo. Para los detalles de facturación, consulten los datos vigentes en docs.apiyi.com/models.
📚 Referencias
- Notas de la versión Claude Code v2.1.318: fuente de información sobre todas las correcciones mencionadas en este artículo
- Enlace:
github.com/anthropics/claude-code/releases/tag/v2.1.318 -
Descripción: incluye las notas completas sobre directorios home compartidos en red, vencimiento de la sesión, recuperación de
~/.claude.jsony otras actualizaciones -
Centro de documentación de APIYI: guía de integración con la API y configuración de herramientas
- Enlace:
docs.apiyi.com -
Descripción: URL base, obtención de la clave API y métodos de integración con los formatos de Anthropic y OpenAI
-
Página de precios de modelos de APIYI: fuente oficial de datos sobre la facturación de modelos
- Enlace:
docs.apiyi.com/models - Descripción: consulta los datos actualizados de esta página para conocer los precios de entrada, salida y caché, entre otros conceptos de facturación
Autor: Equipo técnico de APIYI
Consultas técnicas: Si tienes problemas al desplegar Claude Code en un entorno compartido, puedes contactarnos desde la página principal de APIYI, apiyi.com. Encontrarás más recursos de integración en el centro de documentación, docs.apiyi.com.
