Настройка
Все постоянные параметры Zshell, их назначение и место хранения.
Большинство постоянных настроек Zshell хранится в одном файле:
~/.config/zshell/config.tomlОкно настроек (Cmd+,) записывает тот же файл. Некоторые параметры macOS — язык и автоматические обновления — хранятся отдельно и перечислены в конце страницы.
В новых конфигурациях включены подсказки команд Vim, восстановление истории сеансов и уведомления о неудачных командах. Автоматическая загрузка обновлений также включена по умолчанию. Существующие конфигурации и сохранённые решения сохраняются.
Как работает файл
Перед ручным редактированием полезно знать:
- Изменения читаются во время работы. Корректные внешние правки применяются автоматически; настройки для новых терминалов по-прежнему требуют нового окна терминала. Нечитаемый или некорректный файл оставляет последние действующие настройки. Намеренно пустой файл после небольшой задержки восстанавливает значения по умолчанию.
- Zshell перезаписывает файл при каждом изменении хранящегося в нём параметра. Файл создаётся заново, поэтому комментарии и неизвестные ключи будут потеряны при следующем использовании такого элемента управления. Выберите один способ редактирования или храните основную копию в своих dotfiles.
- Большинство стандартных значений не записывается.
font-size,terminal.vim-command-hints,terminal.restore-history,terminal.notify-on-errorсохраняются всегда. Удаление одного из этих трёх ключей терминала из существующего файла выключает функцию; удаление остальных ключей восстанавливает значения по умолчанию. - Парсер намеренно ограничен. Он поддерживает простые и разделённые точками ключи, заголовки
[table], комментарии#, строки, числа и логические значения. Массивы, встроенные таблицы и многострочные строки не поддерживаются. - Неверные значения безопасно заменяются стандартными. Размер вне диапазона, неизвестный движок или ошибка в имени темы не мешают запуску Zshell.
Сохранение оставляет символические ссылки на файлы и каталоги, атомарно обновляет целевой файл и сохраняет права. Внешние правки не переписывают комментарии и неизвестные ключи; последующее сохранение через настройки всё ещё пересоздаёт файл, как описано выше.
Отображение приложения
app-presence
"dock" · "dock-and-menu-bar" · "menu-bar" — по умолчанию "dock"
Выберите Настройки → Основные → Показывать Zshell в, чтобы сразу изменить режим. "dock" показывает только значок Dock, "dock-and-menu-bar" — оба значка, "menu-bar" — только значок строки меню.
Из строки меню можно открыть текущую рабочую область, быстрый терминал, настройки и проверку обновлений. В обоих режимах со строкой меню закрытие последнего окна скрывает его, а терминалы и задачи продолжают работать. Открыть рабочую область возвращает то же окно, проект и сеанс. Закрытие другого окна, панели или проекта по-прежнему завершает его задачи. Команда Завершить следует terminal.preserve-sessions; Завершить и закрыть все сеансы останавливает их. Режим сохраняется после перезапуска.
Оформление
theme
"system" · "light" · "dark" — по умолчанию "system"
Выбирает оформление приложения. "system" следует macOS, два других значения фиксируют светлое или тёмное оформление.
theme-dark и theme-light
Строки — по умолчанию "Default Dark" и "Default Light"
Цветовая тема для каждого оформления. Тема одновременно меняет цвета терминалов, элементов окна, боковых панелей, редактора и сравнений. Стандартные темы сохраняют полупрозрачную боковую панель; другие окрашивают её в соответствии со своей палитрой.
В настройках доступен подобранный каталог тем, общий для обоих движков. Введённое вручную имя должно точно совпадать с отображаемым именем, включая регистр, иначе используется соответствующая стандартная тема.
toolbar.visibility
"hide" · "auto" · "always" — по умолчанию "hide"
Управляет компактной панелью инструментов под активной вкладкой:
"hide"полностью скрывает её."auto"показывает её только тогда, когда каталог проекта — репозиторий Git."always"оставляет доступ к Git во всех проектах, включая состояние Нет репозитория Git.
Содержимое описано в разделе Панель инструментов Git.
Текст
font-family
Строка — по умолчанию "", то есть встроенный JetBrains Mono
Это семейство для латиницы используется терминалом, редактором и просмотрщиком сравнений. Указывайте семейство, а не начертание: "IBM Plex Mono", а не "IBM Plex Mono Regular". Неизвестные или немоноширинные семейства заменяются встроенным шрифтом.
Порядок подстановки в терминале: семейство латиницы, необязательное семейство CJK ниже, встроенный Symbols Nerd Font, затем системная подстановка движка. Редактор и сравнения продолжают использовать обычную подстановку macOS/WebKit.
terminal.font-fallback-family
Строка — по умолчанию "", то есть подстановка движка/системы
Добавляет одно установленное семейство CJK в цепочку подстановки терминала. Список настроек включает семейства с характерными китайскими, японскими или корейскими символами; строгая моноширинность не требуется, поскольку они предоставляют только символы, отсутствующие в основном латинском шрифте.
font-size
Число, 8–32 — по умолчанию 13
Общий размер шрифта терминала, редактора и сравнений в пунктах. Это единственный ключ, который Zshell записывает даже при стандартном значении.
interface.scale
Число, 0.9–1.5 — по умолчанию 1
Масштабирует вкладки, значки, кнопки, боковые панели и остальной интерфейс. Содержимое терминала, редактора и сравнений сохраняет отдельно настроенный выше размер шрифта.
sidebar.font-size
Число, 9–24 — по умолчанию 14
Базовый размер текста обеих боковых панелей. Заголовки разделов, строки, метаданные и элементы управления сохраняют относительную иерархию при изменении базы.
terminal.font-thicken
Логическое значение — по умолчанию false
Немного утолщает штрихи символов терминала, подобно классическому сглаживанию macOS. Поддерживается обоими движками; результат виден в предпросмотре настроек. Старый ключ font-thicken по-прежнему читается, а затем перезаписывается современным ключом с точкой.
terminal.font-thicken-strength
Целое число, 0–255 — по умолчанию 255
Регулирует утолщение, когда terminal.font-thicken равно true. Ноль означает минимальное утолщение, а не отключение. Ghostty использует нативную интенсивность macOS, Alacritty сопоставляет тот же диапазон обводке CoreText. Направление и крайние значения совпадают, но растровые пиксели могут различаться.
terminal.line-height
Число, 0.75–2 — по умолчанию 1
Умножает естественную высоту ячейки каждого движка, сохраняя символы по вертикальному центру. Меняет только строки терминала, не интервалы редактора и сравнений.
Zshell не предоставляет отдельную настройку базовой насыщенности шрифта. Ghostty выбирает именованные начертания или оси вариаций, а Alacritty/CoreText определяет обычное и жирное начертания по признакам. Одно общее значение не обеспечило бы одинакового различия обычного/жирного начертания и насыщенности подстановочных шрифтов для статических и вариативных семейств.
editor.wrap-lines
Логическое значение — по умолчанию true
Переносит длинные строки по ширине панели в редакторе файлов. При false длинные строки прокручиваются горизонтально. Перенос в терминале и сравнениях не меняется.
Терминал
terminal.startup-program / terminal.startup-arguments
Строки — по умолчанию не заданы
Выбирают исполняемый файл и вектор аргументов для создаваемых после изменения терминалов. Без terminal.startup-program Zshell использует оболочку входа учётной записи с -l. Программа должна быть исполняемым файлом по абсолютному пути. Если путь отсутствует или не исполняемый, запускается оболочка входа, чтобы не создавать неработающую панель.
terminal.startup-arguments разбивается на аргументы без вызова оболочки. Кавычки и обратные косые черты сохраняют границы, включая пробелы и пустые аргументы, но переменные, шаблоны и подстановки команд не раскрываются. Неверные кавычки также возвращают оболочку входа. Явный argv из CLI Zshell имеет приоритет для соответствующего терминала.
terminal.backend
"libghostty" · "alacritty" — по умолчанию "libghostty"
Выбирает эмулятор для новых терминалов. Существующие панели сохраняют исходный движок. Оба варианта нативные, ускоряются GPU, поддерживают изображения и одни и те же темы Zshell; Alacritty обычно расходует меньше памяти.
Переменные окружения и совместимость описаны в разделе Движки терминала.
terminal.macos-option-as-alt
Логическое значение — по умолчанию false
При true сочетания с Option передаются терминальным программам как Alt/Meta. По умолчанию Option остаётся у активного источника ввода macOS, чтобы раскладки вроде Polish Pro могли вводить составные символы.
terminal.bell
Логическое значение — по умолчанию true
Управляет звуком и визуальным привлечением внимания macOS при сигнале терминальной программы. При false Zshell не воспроизводит звук, не отправляет уведомление о звонке и не запрашивает внимание в Dock. Вспомогательные технологии всё равно получают семантическое объявление сигнала. Настройка действует в обоих движках.
terminal.vim-command-hints
Логическое значение — по умолчанию true
Показывает команды Vim / Neovim с учётом режима под информацией о сеансе на панели Информация. Применяется сразу в обоих движках, включая распознаваемые редакторы через SSH. Требования распознавания режима приведены в разделе Подсказки команд Vim.
terminal.restore-history
Логическое значение — по умолчанию true
После перезапуска восстанавливает предыдущий вывод терминала над новой оболочкой. Восстановленное содержимое — статический текст, а не продолжающий работу процесс.
История сохраняется на диске и может содержать показанные в терминале секреты. Проекты, вкладки и расположение панелей восстанавливаются в любом случае.
Автоматизация
ai.enabled
Логическое значение — по умолчанию true
Позволяет поддерживаемым агентам программирования координировать фоновые панели Zshell по вашему запросу обычными словами и показывает сообщённое провайдером состояние жизненного цикла. Zshell не определяет состояние по тексту терминала. Лучше менять параметр переключателем настроек: ошибки показываются рядом, а конфликтующая существующая настройка не изменяется.
Пользовательский процесс описан в разделе Работа с ИИ-агентами.
При общем Codex app-server Zshell сопоставляет проверенные ID диалогов с активной панелью. Неоднозначные соответствия не привязываются. Управляемая интеграция добавляет session-id в заголовок терминала Codex, сохраняя остальные элементы.
ai.resume-conversations
логическое значение — по умолчанию true
При восстановлении панелей терминала возобновляет именно сохранённый исходный диалог Claude Code, Codex, Pi или OpenCode, если исходный PTY недоступен. Требуется ai.enabled = true. Панель без проверенного диалога открывает новую оболочку; Zshell никогда не выбирает последний диалог по каталогу.
Настройка находится в Настройки → Автоматизация → Возобновлять диалоги агентов и не зависит от terminal.restore-history.
Дополнительные настройки
| Ключ | По умолчанию | Значения / диапазон | Действие |
|---|---|---|---|
app-icon | "default" | "default" / "light" / "dark" | Значок приложения |
editor.external-editor | "default" | "default" / "vscode" / "zed" / "cursor" | Внешний редактор файлов и папок |
terminal.theme-only | false | Логическое значение | Применять палитру только к терминалу |
terminal.cursor-shape | "bar" | "bar" / "block" / "underline" | Форма курсора терминала |
terminal.cursor-blinking | true | Логическое значение | Мигание курсора |
terminal.copy-on-select | true | Логическое значение | Копирование выделенного текста терминала |
terminal.focus-follows-mouse | false | Логическое значение | Фокус следует за мышью |
terminal.shift-enter-newline | true | Логическое значение | Расширенная последовательность новой строки по Shift+Enter; требуется поддержка приложения |
terminal.background-opacity | 1 | 0.2–1 | Непрозрачность фона терминала |
terminal.background-blur | false | Логическое значение | Размытие полупрозрачного фона |
terminal.notify-finish-seconds | 0 | 0 / 5 / 10 / 30 / 60 | Уведомление после завершения команды, работавшей не менее этого времени, в новых терминалах zsh; 0 отключает |
terminal.notify-on-error | true | Логическое значение | Уведомление об ошибке команды в новых терминалах zsh |
quick-terminal.mode | "reuse" | "reuse", "fresh" | Повторно использовать рабочую область / Новая рабочая область каждый раз |
quick-terminal.size | 0.75 | 0.35–0.95 | Размер быстрого терминала относительно экрана |
quick-terminal.opacity | 0.5 | 0.05–1 | Непрозрачность фона быстрого терминала |
quick-terminal.shortcut | Cmd+I | Запись в настройках | Запишите глобальное сочетание в настройках; коды клавиш сохраняются автоматически |
panes.show-focus-ring | true | Логическое значение | Рамка вокруг активной панели |
panes.focus-ring-opacity | 0.85 | 0.05–1 | Непрозрачность рамки фокуса |
Резервное копирование и перенос
Выберите Zshell → Экспортировать настройки…, чтобы сохранить TOML, и Импортировать настройки…, чтобы загрузить его. Импорт запрашивает подтверждение замены и пытается сохранить текущий файл как config.toml.bak в том же каталоге.
Импорт читает все поддерживаемые настройки. Пропущенные ключи используют значения по умолчанию считывателя; без ai.enabled сохраняется текущая настройка ИИ. Язык и переменные окружения проектов и вкладок хранятся отдельно.
Полный пример
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Все ключи необязательны. Удалите ключ, чтобы вернуть его стандартное значение.
Сочетания клавиш
В Настройки → Сочетания клавиш можно записать новое сочетание основной команды. Zshell отклоняет конфликты и показывает команду, уже использующую сочетание. Восстановить стандартные сочетания сбрасывает все переопределения. Стандартные значения перечислены в справочнике клавиатуры.
Настройки вне этого файла
- Язык. В настройках доступны системный язык и 17 языков сайта. Изменение применяется немедленно, терминальные сеансы продолжают работать. Выбор использует языковую настройку macOS для приложения и хранится в предпочтениях Zshell, не в TOML. Системное значение следует порядку языков macOS.
- Автоматические обновления. Переключатели автоматической проверки, загрузки и установки в Настройки → Обновления хранятся вне TOML и сохраняются между запусками. Установка показывается только при включённой автоматической загрузке. См. Установка.
- Состояние окна и расположения. Размер окна, ширина боковых панелей, выбранные панели, проекты, вкладки, панели содержимого, URL браузеров и предпочтения сравнений хранятся в предпочтениях macOS и снимке сеанса Zshell.
- Файлы движков. Zshell не читает
~/.config/ghosttyили настройки Alacritty. Для обоих поддерживается настройка через Zshell.