配置

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" 同时显示 Dock 和菜单栏图标，"menu-bar" 仅显示菜单栏图标。

菜单栏可以打开当前工作区、临时终端、设置和更新检查。在两种菜单栏模式下，关闭最后一个工作区窗口会将它隐藏，终端和任务继续运行；打开工作区 会回到同一个窗口、项目和会话。关闭其他工作区窗口、面板或项目仍会结束相应任务。明确选择 退出 时仍遵循 terminal.preserve-sessions；退出并结束所有会话 会结束它们。此模式会在重启后保留。

外观复制链接

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"。不存在或非等宽的字族会回退到内置默认值。

终端的后备顺序是：拉丁字族、下面可选的 CJK 后备字族、内置 Symbols Nerd Font，最后是 后端的系统后备字体。编辑器和 diff 继续使用 macOS/WebKit 的正常后备机制。

terminal.font-fallback-family复制链接

字符串——默认 ""，表示交给后端和系统选择

在终端的有序后备链中加入一个已安装的 CJK 字族。设置列表会显示包含代表性中文、日文或 韩文字形的字族；它们不必严格等宽，因为只负责拉丁主字体缺少的字形。

font-size复制链接

数字，8–32——默认 13

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

interface.scale复制链接

数字，0.9–1.5——默认 1

缩放标签页、图标、按钮、侧边栏和应用界面的其他部分。终端、编辑器和 diff 内容仍使用上方单独配置的字号。

sidebar.font-size复制链接

数字，9–24——默认 14

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

terminal.font-thicken复制链接

布尔值——默认 false

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

terminal.font-thicken-strength复制链接

整数，0–255——默认 255

控制 terminal.font-thicken 打开时的粗化强度。零表示最轻的可用粗化，而不是关闭。Ghostty 使用其原生 macOS 强度；Alacritty 把同一范围映射到 CoreText 描边，所以方向和端点一致， 但光栅化像素可能不同。

terminal.line-height复制链接

数字，0.75–2——默认 1

按比例调整各终端后端的自然单元格高度，同时让字形保持垂直居中。它只改变终端行，不改变 编辑器或 diff 的行距。

Zshell 不提供基础字重控件。Ghostty 使用具名字形样式或可变轴，而 Alacritty/CoreText 按 trait 解析 regular 与 bold 字体；单个共享数值无法在静态字体和可变字体之间一致地保留 regular/bold 区分及后备字体字重。

editor.wrap-lines复制链接

布尔值——默认 true

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

终端复制链接

terminal.preserve-sessions复制链接

布尔值——默认 false

让之后新建终端中的 Shell、编程 Agent 和开发服务器在退出 Zshell 后继续运行。重开后会 连接同一个存活进程，并恢复终端屏幕和输入模式，两个后端都支持。守护进程只在内存里保留 有界的屏幕历史；macOS 重启后不会继续运行。原 PTY 已结束时，窗格会打开新的 Shell。

关闭窗格、项目或窗口仍会结束其中的任务。选择 Zshell → 退出并结束所有会话，或在 退出前关闭此选项，可以结束所有后台会话，包括隐藏的快捷终端。复用模式下隐藏快捷终端会 保留 Shell；此选项控制之后新开的复用窗格是否还能在退出 Zshell 后继续运行。 新建模式在隐藏时结束本次工作区。

保留 Shell 中的 CLI 会在 Zshell 重开后绑定到原终端；GUI 关闭期间不可用。稳定 CLI 启动器在重连时更新，删除开发构建后，需要另一个 Zshell 构建重开会话才能再次使用 CLI。 终端图片摆放和后端专有图形不会恢复，应用可以自行重绘。

terminal.startup-program / terminal.startup-arguments复制链接

字符串——默认未设置

选择之后新建终端使用的可执行程序与参数向量。未设置 terminal.startup-program 时，Zshell 继续以 -l 启动账户登录 Shell。程序必须是可执行文件的绝对路径；路径不存在或不可执行时会 回退到登录 Shell，而不是打开一个立即关闭的空窗格。

terminal.startup-arguments 不经 Shell 直接拆分为参数。引号和反斜杠用于保留参数边界， 包括含空格和空字符串的参数，但不会展开变量、通配符或命令替换。引号不完整时也会回退到 登录 Shell。Zshell CLI 为单个终端显式传入的 argv 仍然优先。

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.vim-command-hints复制链接

布尔值，默认 true。

在右侧 信息 栏的会话信息下方显示按模式排序的 Vim / Neovim 常用命令。 立即作用于两种终端后端，也支持识别 SSH 中的编辑器。 检测条件见 Vim 命令提示。

terminal.restore-history复制链接

布尔值——默认 true

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

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

自动化复制链接

ai.enabled复制链接

布尔值——默认 true

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

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

多个终端共享 Codex app-server 时，Zshell 根据已验证的对话 ID 匹配前台窗格，存在歧义时不绑定。托管集成会在 Codex 终端标题中加入 session-id，并保留其他标题项。

ai.resume-conversations复制链接

布尔值——默认 true

恢复终端窗格时，如果原 PTY 已不可用，继续已记录的 Claude Code、Codex、Pi 或 OpenCode 确切原对话。需要 ai.enabled = true。没有已验证对话的窗格会打开新 shell；Zshell 不会按目录选择最近对话。

可在 设置 → 自动化 → 恢复 Agent 对话 中切换。它与 terminal.restore-history 独立。

其他配置项复制链接

备份与迁移复制链接

通过 Zshell → Export Settings… 导出 TOML 文件，使用 Import Settings… 导入。 导入前会要求确认替换，并尝试将当前配置备份为同目录的 config.toml.bak。

导入会读取全部受支持的配置项。省略项遵循配置读取器的默认规则；未包含 ai.enabled 时保留当前 AI 开关。语言及项目、标签页的环境变量单独保存。

一份完整的例子复制链接

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 的单应用语言偏好，所以不存进 TOML。「跟随系统」会按 macOS 的语言优先级选择。
• 自动更新。 设置 → 更新中的自动检查、自动下载和自动安装使用 TOML 之外的应用偏好，重启后会保留选择。开启自动下载后才显示自动安装。见安装。
• 窗口与布局状态。 窗口尺寸、侧边栏宽度、当前面板、项目、标签页、窗格、浏览器 URL 和 diff 控件偏好，都存在 Zshell 的 macOS 偏好设置或会话快照里。
• 后端自己的配置文件。 Zshell 不读取 ~/.config/ghostty，也不读取 Alacritty 配置。Zshell 的设置就是两个后端共同支持的配置面。