CLAUDE_CONFIG_DIR: qué hace en Claude Code

Qué hace la variable

La referencia de variables de entorno de Anthropic describe CLAUDE_CONFIG_DIR como una forma de sustituir el directorio de configuración, que de forma predeterminada es ~/.claude. Todos los ajustes, el historial de sesiones y los plugins se guardan en la ruta que le indiques.

No cambia nada más de Claude Code. El comando claude es el mismo programa; simplemente lee y escribe en otra carpeta. Si lo inicias con un valor, obtienes una configuración. Si lo inicias con otro, obtienes una segunda, independiente de la primera.

Qué hay en un directorio de configuración

Según la guía de Anthropic sobre el directorio .claude, cuando defines CLAUDE_CONFIG_DIR, todas las rutas que normalmente estarían en ~/.claude pasan a estar en tu directorio. Eso incluye:

Tu CLAUDE.md personal, settings.json, habilidades (skills), comandos, subagentes y estilos de salida.
Las transcripciones de sesiones en projects/, además de la memoria automática de cada proyecto.
Las instantáneas de archivos que se usan para restaurar puntos de control, los archivos de planes y tu historial de prompts.
Los atajos de teclado y los temas personalizados.

Los archivos del proyecto no se ven afectados. El CLAUDE.md, la carpeta .claude/ y el .mcp.json de un repositorio pertenecen al proyecto, así que todos los directorios de configuración los ven.

Cómo se separan los inicios de sesión en un Mac

En macOS, Claude Code guarda las credenciales en el Llavero cifrado. Las notas sobre gestión de credenciales de Anthropic indican que, con CLAUDE_CONFIG_DIR definido, Claude Code asocia la entrada del Llavero a ese directorio, así que una sesión con otro directorio lee otra entrada. Si el Llavero rechaza la escritura, el archivo de respaldo .credentials.json también se guarda en ese directorio.

Hay una excepción documentada. Los directorios separados no mantienen aparte dos inicios de sesión de Claude Console hechos sin clave de API, porque Claude Code guarda ese tipo de inicio de sesión fuera del directorio de configuración (documentación de autenticación, a octubre de 2026).

Las variables de entorno también pueden anular el inicio de sesión en todos los directorios. Si ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN o CLAUDE_CODE_OAUTH_TOKEN se exporta en tu shell, puede imponerse a la cuenta con la que iniciaste sesión. Consulta cómo cambiar de cuenta en Claude Code para ver el orden completo.

Dónde definirla

La forma más sencilla es un alias de shell, que es el ejemplo que da Anthropic. Añádelo a ~/.zshrc y abre una ventana nueva de Terminal:

alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

La primera ejecución te guía por el inicio de sesión y la configuración del nuevo directorio. El claude de siempre sigue usando ~/.claude.

También puedes definir la variable en los ajustes de usuario o en los ajustes gestionados. En un archivo de ajustes, escribe la ruta absoluta. Claude Code la ignora en los ajustes de proyecto y locales, así que no se puede definir por repositorio de esa forma.

Para comprobar qué directorio usa una shell, ejecuta claude auth status. En versiones recientes, su salida JSON incluye un campo configDirectory (referencia de la CLI).

Errores habituales

Olvidar la variable en una ventana. Una pestaña de Terminal sin ella usa ~/.claude y su inicio de sesión, y es fácil no darse cuenta. Los alias lo evitan.
Usar ~ en un archivo de ajustes. Los archivos de ajustes necesitan la ruta absoluta, como /Users/you/.claude-work.
Copiar una carpeta entera para crear otra. Así se copian el historial y el estado de una cuenta en la otra. Empieza con una carpeta vacía y añade lo que necesites. Compartir habilidades y servidores MCP lo explica.
Esperar que las sesiones antiguas te sigan. Las transcripciones viven en el directorio que las creó, así que claude --resume en otro directorio no las mostrará. Consulta reanudar sesiones de Claude Code.
Una clave de API exportada. Anula el inicio de sesión en todos los directorios.

Cómo la usa Switch en Claude Desktop

Claude Code dentro de Claude Desktop no lee los alias de tu shell. Switch se ocupa de ese caso. Cada perfil de Switch abre la app Claude Desktop de Anthropic con su propia carpeta de datos. Con Keep coding preferences separate (mantener separadas las preferencias de código) activado, que es lo predeterminado en los perfiles nuevos, el perfil también tiene su propia carpeta de configuración de Claude Code, y Switch abre el Claude Desktop de ese perfil con CLAUDE_CONFIG_DIR apuntando a ella.

Switch no añade ningún comando de Terminal, y cada cuenta conserva su propio plan y sus límites de uso. Cómo gestiona Switch Claude Code.