Configuración

La mayoría de los ajustes persistentes de Zshell se guardan en un único archivo:

~/.config/zshell/config.toml

La ventana Ajustes (Cmd+,) escribe en este mismo archivo. Algunos ajustes gestionados por macOS —el idioma y las actualizaciones automáticas— se guardan en otro lugar y se enumeran al final de esta página.

Las nuevas configuraciones activan las sugerencias de comandos de Vim, la restauración del historial de sesiones y las notificaciones de comandos fallidos. Las descargas automáticas de actualizaciones también están activadas de forma predeterminada. Se conservan las configuraciones existentes y las elecciones guardadas.

Cómo se comporta el archivoCopiar enlace

Antes de editarlo a mano, ten en cuenta lo siguiente:

• Los cambios se leen durante la ejecución. Las ediciones externas válidas se aplican automáticamente; los ajustes para terminales nuevos siguen requiriendo un panel nuevo. Un archivo ilegible o mal formado conserva los últimos ajustes válidos. Un archivo vacío intencionadamente restaura los valores predeterminados tras una breve espera.
• Zshell lo reescribe cada vez que cambia un ajuste guardado en el archivo. El archivo se genera de nuevo desde cero, por lo que los comentarios y las claves desconocidas se pierden la próxima vez que uses uno de esos controles. Elige un solo medio para editarlo o conserva una copia de referencia entre tus archivos de configuración.
• Se omite la mayoría de los valores predeterminados. font-size, terminal.vim-command-hints, terminal.restore-history, terminal.notify-on-error siempre se guardan. Eliminar una de estas tres claves del terminal en un archivo existente desactiva esa función; eliminar otras claves restaura sus valores predeterminados.
• El analizador es pequeño de forma deliberada. Admite claves simples, claves con puntos, cabeceras [table], comentarios # y valores de cadena, número o booleano. No admite arrays, tablas en línea ni cadenas multilínea.
• Los valores incorrectos usan alternativas seguras. Un tamaño fuera de rango, un motor desconocido o un tema mal escrito no impiden que Zshell se inicie.

Al guardar se conservan los enlaces simbólicos de archivos y carpetas: se actualiza su destino de forma atómica y se mantienen sus permisos. La edición externa no reescribe comentarios ni claves desconocidas; guardar después desde Ajustes sigue regenerando el archivo como se indica arriba.

Presencia de la aplicaciónCopiar enlace

app-presenceCopiar enlace

"dock" · "dock-and-menu-bar" · "menu-bar" — predeterminado "dock"

Elige Ajustes → General → Mostrar Zshell en para cambiar al instante. "dock" muestra solo el icono del Dock, "dock-and-menu-bar" muestra ambos y "menu-bar" muestra solo el icono de la barra de menús.

La barra de menús abre el espacio de trabajo actual, el terminal rápido, los ajustes y la búsqueda de actualizaciones. En ambos modos con barra de menús, cerrar la última ventana la oculta y mantiene sus terminales y tareas en ejecución. Abrir espacio de trabajo vuelve a la misma ventana, proyecto y sesión. Cerrar otra ventana, panel o proyecto sigue terminando sus tareas. Salir respeta terminal.preserve-sessions; Salir y finalizar todas las sesiones las termina. El modo se conserva al reiniciar.

AparienciaCopiar enlace

themeCopiar enlace

"system" · "light" · "dark" — predeterminado: "system"

Elige la apariencia de la aplicación. "system" sigue a macOS; los otros dos valores fijan una apariencia para Zshell.

theme-dark y theme-lightCopiar enlace

cadena — valores predeterminados: "Default Dark" y "Default Light"

El tema de color para cada apariencia. Un tema cambia a la vez los colores de los paneles de terminal, el marco de la ventana, las barras laterales, el editor y las diferencias. Los temas predeterminados conservan la barra lateral translúcida de Zshell; los demás la pintan con su paleta.

Ajustes muestra el catálogo de temas seleccionados que comparten ambos motores de terminal. Un nombre escrito a mano debe coincidir exactamente con uno de los nombres mostrados, incluidas mayúsculas y minúsculas; de lo contrario, Zshell vuelve al tema predeterminado correspondiente.

toolbar.visibilityCopiar enlace

"hide" · "auto" · "always" — predeterminado: "hide"

Controla la barra compacta situada debajo de la pestaña activa:

• "hide" la mantiene fuera de la ventana.
• "auto" la muestra solo cuando el directorio del proyecto es un repositorio Git.
• "always" mantiene visible el acceso a Git en todos los proyectos, incluido el estado Sin repositorio Git.

Consulta La barra de herramientas de Git para saber qué muestra.

TextoCopiar enlace

font-familyCopiar enlace

cadena — predeterminado: "", que indica JetBrains Mono incluida con la aplicación

El terminal, el editor y el visor de diferencias comparten esta familia para caracteres latinos. Indica el nombre de una familia, no de un estilo: "IBM Plex Mono", no "IBM Plex Mono Regular". Las familias desconocidas o no monoespaciadas usan la predeterminada incluida.

El orden de sustitución del terminal es la familia latina, la fuente CJK opcional de abajo, Symbols Nerd Font incluida y, por último, la sustitución del sistema del motor. El editor y el visor de diferencias siguen usando su sustitución normal de macOS/WebKit.

terminal.font-fallback-familyCopiar enlace

cadena — predeterminado: "", que indica la sustitución del motor o del sistema

Añade una familia CJK instalada a la cadena ordenada de fuentes de sustitución del terminal. El selector de Ajustes incluye familias con glifos representativos del chino, japonés o coreano; no exige que sean estrictamente monoespaciadas porque solo aportan los glifos que faltan en la fuente latina principal.

font-sizeCopiar enlace

número, 8–32 — predeterminado: 13

Tamaño de fuente en puntos compartido por el terminal, el editor y las diferencias. Es la única clave que Zshell escribe incluso cuando tiene el valor predeterminado.

interface.scaleCopiar enlace

número, 0.9–1.5 — predeterminado: 1

Escala pestañas, iconos, botones, barras laterales y el resto de la interfaz. El contenido del terminal, el editor y las diferencias conserva el tamaño de fuente configurado por separado más arriba.

sidebar.font-sizeCopiar enlace

número, 9–24 — predeterminado: 14

Tamaño base del texto de ambas barras laterales. Las cabeceras de sección, filas, metadatos y controles mantienen su jerarquía relativa al cambiar la base.

terminal.font-thickenCopiar enlace

booleano — predeterminado: false

Representa los glifos del terminal con trazos algo más gruesos, parecidos al suavizado de fuentes clásico de macOS. Ambos motores respetan la opción y la vista previa de Ajustes muestra el resultado. Las configuraciones antiguas con font-thicken se siguen leyendo y después se reescriben con la clave actual con puntos.

terminal.font-thicken-strengthCopiar enlace

entero, 0–255 — predeterminado: 255

Controla el engrosamiento cuando terminal.font-thicken es true. Cero es el engrosamiento más ligero disponible, no lo desactiva. Ghostty usa su intensidad nativa de macOS; Alacritty asigna el mismo rango a un trazo de CoreText, de modo que la dirección y los extremos coinciden, aunque los píxeles rasterizados pueden diferir.

terminal.line-heightCopiar enlace

número, 0.75–2 — predeterminado: 1

Multiplica la altura natural de celda de cada motor de terminal y mantiene los glifos centrados verticalmente. Solo cambia las filas del terminal, no el espaciado del editor ni de las diferencias.

Zshell no ofrece un control de peso base de fuente. Ghostty selecciona estilos con nombre o ejes de variación, mientras que Alacritty/CoreText resuelve las variantes regular y negrita mediante atributos; un único valor compartido no conservaría de forma coherente la distinción regular/negrita ni los pesos de sustitución entre fuentes estáticas y variables.

editor.wrap-linesCopiar enlace

booleano — predeterminado: true

Ajusta visualmente las líneas largas al ancho del panel en el editor de archivos. Con false, las líneas largas se desplazan horizontalmente. No cambia el ajuste de líneas de un terminal ni de una vista de diferencias.

TerminalCopiar enlace

terminal.startup-program / terminal.startup-argumentsCopiar enlace

cadenas — sin valor predeterminado

Eligen el ejecutable y el vector de argumentos de los terminales creados a partir de ese momento. Cuando no existe terminal.startup-program, Zshell sigue usando el shell de inicio de sesión de la cuenta con -l. El programa debe ser una ruta absoluta a un ejecutable; si la ruta no existe o no es ejecutable, se usa el shell de inicio de sesión en lugar de abrir un panel inutilizable.

terminal.startup-arguments se divide en argumentos sin invocar un shell. Las comillas y las barras inversas conservan sus límites, incluidos espacios y argumentos vacíos, pero no se expanden variables, patrones glob ni sustituciones de comandos. Las comillas no válidas también hacen que se use el shell de inicio de sesión. Un argv explícito proporcionado por la CLI de Zshell conserva la prioridad para ese terminal.

terminal.backendCopiar enlace

"libghostty" · "alacritty" — predeterminado: "libghostty"

Elige el emulador de los terminales creados a partir de ese momento. Los paneles existentes conservan el motor con el que se iniciaron. Ambos son nativos, tienen aceleración por GPU, admiten imágenes y usan los mismos temas de Zshell; Alacritty suele consumir menos memoria.

Consulta Motores de terminal para conocer las variables de entorno y las garantías de compatibilidad.

terminal.macos-option-as-altCopiar enlace

booleano — predeterminado: false

Con true, las combinaciones de la tecla Opción se envían a los programas de terminal como atajos Alt/Meta. El valor predeterminado deja Opción en manos de la fuente de entrada activa de macOS para que distribuciones como Polish Pro puedan escribir sus caracteres compuestos.

terminal.bellCopiar enlace

booleano — predeterminado: true

Controla el sonido de alerta y la llamada de atención visual de macOS cuando un programa de terminal activa la campana. Con false, Zshell no reproduce el sonido, no publica una notificación de campana ni solicita atención en el Dock. Las tecnologías de accesibilidad siguen recibiendo la campana como anuncio semántico. Ambos motores respetan este ajuste.

terminal.vim-command-hintsCopiar enlace

booleano — predeterminado: true

Muestra comandos de Vim / Neovim según el modo debajo de la información de sesión en la barra lateral Información. Se aplica inmediatamente en ambos motores, incluidos editores reconocibles a través de SSH. Consulta Sugerencias de comandos de Vim para conocer los requisitos de detección de modo.

terminal.restore-historyCopiar enlace

booleano — predeterminado: true

Restaura el historial de salida anterior de cada terminal sobre un shell nuevo al volver a iniciar. El contenido restaurado es texto estático, no un proceso que haya sobrevivido.

El historial restaurado se guarda en disco, por lo que puede incluir secretos mostrados en el terminal. Los proyectos, pestañas y distribución de paneles se restauran en cualquier caso.

AutomatizaciónCopiar enlace

ai.enabledCopiar enlace

booleano — predeterminado: true

Permite que los agentes de programación compatibles coordinen paneles de Zshell en segundo plano cuando lo pides con lenguaje natural, y muestra en la interfaz el estado del ciclo de vida comunicado por el proveedor. Zshell no infiere el estado del texto del terminal. Se recomienda cambiarlo desde el interruptor de Ajustes porque los errores aparecen junto al control y las configuraciones existentes que entren en conflicto se dejan intactas.

El flujo de trabajo para el usuario se describe en Trabajar con agentes de IA.

Al compartir el app-server de Codex, Zshell asocia los ID de conversación verificados al panel en primer plano. Las coincidencias ambiguas no se vinculan. La integración administrada añade session-id al título de Codex y conserva sus demás elementos.

ai.resume-conversationsCopiar enlace

booleano — predeterminado true

Al restaurar los paneles de terminal, reanuda la conversación original exacta registrada de Claude Code, Codex, Pi u OpenCode cuando su PTY original no está disponible. Requiere ai.enabled = true. Sin una conversación verificada, el panel abre una nueva shell; Zshell nunca elige la conversación más reciente por directorio.

Se controla en Ajustes → Automatización → Reanudar conversaciones de agentes. Es independiente de terminal.restore-history.

Ajustes adicionalesCopiar enlace

Copias de seguridad y migraciónCopiar enlace

Usa Zshell → Exportar ajustes… para guardar un archivo TOML e Importar ajustes… para cargarlo. La importación pide confirmar la sustitución e intenta guardar una copia del archivo actual como config.toml.bak en el mismo directorio.

La importación lee todas las opciones admitidas. Las claves omitidas usan los valores del lector; omitir ai.enabled conserva el ajuste actual de IA. El idioma y las variables de entorno de proyectos y pestañas se guardan aparte.

Un ejemplo completoCopiar enlace

theme = "dark"
theme-dark = "Catppuccin Mocha"
theme-light = "Catppuccin Latte"
font-family = "IBM Plex Mono"
font-size = 14
interface.scale = 1.25
sidebar.font-size = 13
toolbar.visibility = "auto"
terminal.font-fallback-family = "PingFang SC"
terminal.font-thicken = true
terminal.font-thicken-strength = 180
terminal.line-height = 1.15
terminal.macos-option-as-alt = false
terminal.bell = false
terminal.startup-program = "/opt/homebrew/bin/fish"
terminal.startup-arguments = "--no-config"
terminal.backend = "alacritty"
terminal.restore-history = true
editor.wrap-lines = true
ai.enabled = true
ai.resume-conversations = true

Todas las claves son opcionales. Elimina una clave para devolver ese ajuste a su valor predeterminado.

Atajos de tecladoCopiar enlace

Abre Ajustes → Atajos para registrar un atajo nuevo para un comando principal. Zshell rechaza combinaciones en conflicto e indica qué comando ya las utiliza. Restaurar atajos predeterminados elimina todas las personalizaciones. La referencia de teclado enumera los valores predeterminados incluidos.

Ajustes fuera de este archivoCopiar enlace

• Idioma. Ajustes ofrece Predeterminado del sistema y 17 idiomas, los mismos que el sitio web. Los cambios se aplican inmediatamente y las sesiones de terminal siguen en ejecución. La selección usa la preferencia de idioma por aplicación de macOS, por lo que se guarda en las preferencias de Zshell y no en TOML. Predeterminado del sistema sigue el orden de idiomas de macOS.
• Actualizaciones automáticas. Los interruptores de comprobación, descarga e instalación automáticas de Ajustes → Actualizaciones usan preferencias de la aplicación fuera de TOML y recuerdan tus elecciones entre inicios. La opción de instalación solo se muestra cuando las descargas automáticas están activadas. Consulta Instalación.
• Estado de ventanas y distribución. El tamaño de ventana, los anchos de las barras laterales, los paneles seleccionados, los proyectos, pestañas, paneles, URL del navegador y preferencias de controles de diferencias se guardan en las preferencias de macOS de Zshell y en la instantánea de sesión.
• Archivos de configuración de los motores. Zshell no lee ~/.config/ghostty ni una configuración de Alacritty. Los ajustes de Zshell son la interfaz admitida para ambos.