配置 — Zshell

Zshell 大多数持久化设置都在一个文件里：

~/.config/zshell/config.toml

设置窗口（Cmd+,）写的也是这个文件。少数由 macOS 管理的设置——语言和自动更新——存在别处，列在本页末尾。

这个文件的行为

手动改之前值得先知道：

启动时读取。 Zshell 运行中改文件不会立即生效，要重启。设置窗口里的改动通常立即生效，控件另有说明的除外。
只要文件型设置有变化，Zshell 就会重写它。 文件会从头生成，所以你的注释和未知键会在下次使用这些控件时丢失。最好只选一种方式维护它，或者把权威版本放在 dotfiles 里。
通常只写非默认值。 唯一例外是 font-size，它总会出现。删掉其他键就恢复默认值。
解析器有意保持精简。 支持扁平键、点号键、[table] 表头、# 注释，以及字符串、数字和布尔值；不支持数组、内联表和多行字符串。
错误值会安全回退。 超出范围的字号、未知后端或拼错的主题名不会让 Zshell 启动失败。

外观

`theme`

"system" · "light" · "dark"——默认 "system"

选择应用外观。"system" 跟随 macOS，另外两个把 Zshell 固定为浅色或深色。

`theme-dark` 和 `theme-light`

字符串——默认 "Default Dark" 和 "Default Light"

两种外观各自使用的配色主题。它会同时重绘终端、窗口装饰、侧边栏、编辑器和 diff。Zshell 自带的默认主题保留半透明侧边栏，其他主题会把侧边栏刷成与自身配色一致。

设置窗口列出两个终端后端共同支持的精选主题。手写名称必须与列表里的显示名完全一致，包括大小写；否则会回退到对应的默认主题。

`toolbar.visibility`

"hide" · "auto" · "always"——默认 "hide"

控制当前标签页下方的紧凑工具栏：

"hide" 始终隐藏。
"auto" 只在项目目录是 Git 仓库时显示。
"always" 在每个项目里显示；不是仓库时会显示 No Git Repository。

它具体展示什么，见 Git 工具栏。

文字

`font-family`

字符串——默认 ""，表示内置的 JetBrains Mono

终端、编辑器和 diff 共用这个字族。请写字族名，不要写具体字重："IBM Plex Mono"，而不是 "IBM Plex Mono Regular"。不存在或非等宽的字族会回退到内置默认值。

Zshell 还会附加 Symbols Nerd Font 作为后备，所以即使选中的字族不是打过补丁的 Nerd Font， Powerline 分隔符和图标字形也能正常显示。

`font-size`

数字，8–32——默认 13

终端、编辑器和 diff 共用的字号，单位是磅。这是唯一一个即使等于默认值，Zshell 也会写进文件的键。

`sidebar.font-size`

数字，9–18——默认 14

左右侧边栏的基础字号。调整后，分区标题、列表、元数据和控件仍会保持原本的大小层级。

`terminal.font-thicken`

布尔值——默认 false

用稍粗的笔画渲染终端文字，效果类似经典 macOS 字体平滑。两个终端后端都支持，设置窗口里的预览也会反映效果。旧的 font-thicken 仍能读取，但保存后会改写成现在的点号键。

`editor.wrap-lines`

布尔值——默认 false

在文件编辑器里按窗格宽度软折行。关闭时长行横向滚动；它不会改变终端或 diff 里的折行行为。

终端

`terminal.backend`

"libghostty" · "alacritty"——默认 "libghostty"

选择之后新建终端使用的模拟器；已经打开的窗格继续使用启动时的后端。两者都是原生 GPU 加速，都支持图片渲染并共用 Zshell 主题；Alacritty 通常占用更少内存。

环境变量与兼容约定见终端后端。

`terminal.macos-option-as-alt`

布尔值——默认 false

打开后，Option 组合键会作为 Alt/Meta 快捷键发送给终端程序。默认关闭，让 Option 继续交给当前 macOS 输入源，因此 Polish Pro 之类的键盘布局仍能输入组合字符。

`terminal.bell`

布尔值——默认 true

控制终端程序触发铃声时的提示音和 macOS 视觉提醒。关闭后，Zshell 不会播放提示音、发送终端铃声通知或请求 Dock 提醒；辅助技术仍会收到铃声的语义公告。两个终端后端都遵循此设置。

`terminal.restore-history`

布尔值——默认 false

重启后，在全新 shell 上方恢复每个终端之前的滚动历史。恢复的是静态文本，不是仍在运行的进程。

恢复的滚动历史会保存在磁盘上，所以终端里显示过的密钥也可能包含在内。这个设置默认关闭。项目、标签页和窗格布局无论如何都会恢复。

自动化

`ai.enabled`

布尔值——默认 false

让受支持的编码 agent 按照你的自然语言要求协调 Zshell 后台窗格，并在界面里显示 provider 报告的生命周期状态。Zshell 不会根据终端文字推断状态。推荐用设置窗口的开关，因为错误会直接显示出来，而且冲突的现有配置会保持原样。

具体怎么使用，见与 AI Agent 协作。

一份完整的例子

~/.config/zshell/config.toml

theme = "dark"
theme-dark = "Catppuccin Mocha"
theme-light = "Catppuccin Latte"
font-family = "IBM Plex Mono"
font-size = 14
sidebar.font-size = 13
toolbar.visibility = "auto"
terminal.font-thicken = true
terminal.macos-option-as-alt = false
terminal.bell = false
terminal.backend = "alacritty"
terminal.restore-history = true
editor.wrap-lines = true
ai.enabled = true

每个键都是可选的。删掉某个键，就让那项设置恢复默认值。

不在这个文件里的设置

语言。 设置里可选「跟随系统」、English、简体中文和日本語。它使用 macOS 的单应用语言偏好，并且要重启后生效，所以不存进 TOML。
自动检查更新。 设置 → Updates 里的开关属于 Sparkle。见安装。
窗口与布局状态。 窗口尺寸、侧边栏宽度、当前面板、项目、标签页、窗格、浏览器 URL 和 diff 控件偏好，都存在 Zshell 的 macOS 偏好设置或会话快照里。
后端自己的配置文件。 Zshell 不读取 ~/.config/ghostty，也不读取 Alacritty 配置。Zshell 的设置就是两个后端共同支持的配置面。
快捷键。 目前快捷键是固定的。

配置

本页目录