配置
文档编写中
部分内容可能尚不完整。
ThinkTerm 用一个 Lua 文件配置，方式与 WezTerm 相同。配置项名称、模块名和语法都没有改动 —— ThinkTerm 的配置文件开头依然是：
local wezterm = require 'wezterm'不同的只是文件从哪里读、数据往哪里写。
两处配置，不是一处
Lua 文件是你手写的那一份，装着终端自身的配置项。
在它旁边，~/.config/thinkterm/settings.json 由设置窗口写出，存放那些在设置里有开关的选择 —— 主题、窗口透明度、快捷键、滚动方式与叠加滚动条、界面字号与侧边栏宽度、界面语言、渲染器、标签图标。它不是用来手工编辑的。两边重叠时，几乎总是以设置窗口里的选择为准；例外见下文。
你在使用过程中，这个文件也会被不断改写 —— 拖动或收起侧边栏、移动窗口 —— 但这些都不会重新加载 Lua 配置，所以不会因此重新加载字体，也不会关掉命令面板。如果有人从外部改了它，比如用编辑器或别的程序，ThinkTerm 会立刻读到，并像设置窗口那样把改动生效，而不是放着不用，等下一次保存时再用旧的那份把它覆盖掉。
设置窗口
设置 可以从侧边栏底部的齿轮打开，macOS 上也可以按 ⌘,，其他平台按 Ctrl+Shift+,。它的各个页面，以及每页在哪里有说明：
| 页面 | 里面有什么 | 说明见 |
|---|---|---|
| 通用 | 语言、渲染器、恢复主窗口位置与大小、加载的是哪个配置文件、后台会话 server、重新打开时恢复窗格内容、重启与退出 | 本页、窗口、远程 |
| 外观 | 主题、当前配色方案、应用图标、字体排版、窗口透明度，macOS 26 上的玻璃效果，侧栏、标签栏和终端的颜色深浅，以及侧边栏里的图标与状态标记 | 窗口、窗口透明度、图标与状态 |
| 标签图标 | pane 标签上的程序图标 | 窗口 |
| 侧栏与插件 | 右侧面板、状态、已安装的插件 | 窗口、插件、Agent 状态 |
| 终端 | 默认 Shell、字体、滚动方式、滚动条、最低文字对比度、光标形状与光标闪烁、鼠标与剪贴板、分屏动画、远程分屏缩放、底部语录 | 本页、窗口、复制与粘贴、远程、隐私与安全 |
| 工作区 | 远程文件连接空闲超时、下载文件夹、远程拖放目标、提示音、系统通知，macOS 上还有 Dock 图标数字 | 文件与笔记、Agent 状态、本页 |
| Agent | 识别哪些编程 Agent，以及如何识别 | Agent 状态 |
| 网页 | 浏览器访问，以及发出去的链接 | 网页访问 |
| 共享与同步 | 分享终端：让这台机器上的其他账户看你的终端，标有实验性 | — |
| 权限 | 仅 macOS：终端里的程序拥有哪些权限 | 本页 |
| 已归档 | 已归档的 Project | Space、Project 与 Thread |
| 快捷键 | 一个会显示每个键作用的键盘，可以为命令分配快捷键 | 快捷键与命令 |
| 命令面板 | 命令面板的快捷键、行数、字号和搜索 | 快捷键与命令 |
| 导入 | 一次性导入 WezTerm 配置、编辑器、编程 agent 和 cmux 用过的文件夹和 Herdr 会话 | 本页 |
| 辅助功能 | 显示按钮形状：让侧栏添加按钮的圆形底始终显示 | — |
| 备份 | 导出和导入 ThinkTerm 的状态 | 本页 |
| 软件更新 | 检查更新、检查的频率与安装 | 本页、更新 |
| 关于 | 版本、构建、链接，以及文件放在哪里 | 本页 |
开发者 页有一个开关，可以显示更多页面，那是给开发 ThinkTerm 本身用的，不是日常设置。列表上方的搜索框可以按页面里的设置项找到页面。
关于页与问题报告
设置 › 关于 显示版本、构建、平台和许可证，并能打开源代码、发布说明、配置文件、数据目录、第三方声明和隐私政策。复制信息 把问题报告需要的细节放到剪贴板上：版本和构建、目标平台和操作系统、配置文件与数据目录的路径，以及（检查过更新之后）看到的最新版本。这些路径里含有你的主目录名，贴到公开的地方之前先看一眼。
设置与配置文件重叠的地方
有几项选择两边都能做。在这些项上，设置窗口说了算，而且每项都有办法把选择交还给配置文件：
| 设置窗口里 | 挡在谁前面 | 怎样重新跟随配置文件 |
|---|---|---|
设置 › 终端 › 默认 Shell | default_prog，作用于本机新开的终端 | 选 跟随 thinkterm.lua(default_prog)；配置文件没设置时它显示为 系统默认 |
设置 › 终端 › 字号，8 到 48 | font_size，立即作用于已打开的终端 | 重置这一行 |
通过 设置 › 外观 › 当前配色方案 或命令面板的 更换主题 选定的方案 | color_scheme | 更换主题 里的 使用配置默认值 |
设置 › 终端 › 最低文字对比度 | text_min_contrast_ratio | 关 |
设置 › 命令面板 › 字体大小 | command_palette_font_size | 重置这一行 |
在 设置 › 快捷键 里设置的快捷键 | keys 里的同一个键，以及它的内置默认值 | 对该快捷键点 恢复默认，或点 全部恢复默认 |
设置 › 外观 › 窗口透明度 | window_background_opacity，在 macOS 上还有 macos_window_background_blur | 恢复默认 |
设置 › 终端 › 光标形状 选了 竖线 或 下划线 | default_cursor_style 里的形状 | 选 方块 |
设置 › 终端 › 光标闪烁 选了 平滑 或 硬闪 | 光标是否闪烁（本来由 default_cursor_style 决定）；选 硬闪 时还有 cursor_blink_ease_in 和 cursor_blink_ease_out | 选 不闪 |
设置 › 软件更新 › 自动检查更新 和 检查频率 | 这两行用过之后，是 check_for_updates 和 check_for_updates_interval_seconds | 没有；见更新检查 |
默认 Shell 列出这台机器上找到的 shell，下一次打开终端时生效。只有本机的终端跟随它，包括放在本机会话 server 里的那些；远程服务端运行的是它自己配置里写的。选定之后又被卸载的 shell 会退回系统默认，而不是让你一个终端都打不开。
在 Windows 上，这个列表还会提供 Git Bash（以登录 shell 启动），前提是在 Program Files、%LOCALAPPDATA%\Programs\Git 下或 Scoop 安装里找到了 Git for Windows。存在 wsl.exe 时，它最多列出三个 WSL 发行版，默认的排在最前，每个显示为 <name> (WSL)；Docker Desktop 自带的 docker-desktop 发行版不在其中。
字体本身不在其中：设置 › 终端 › 字体 只是显示配置文件里指定的字体，要改得改文件里的 font。
有一项是反过来的。配置文件里的 enable_scroll_bar = true 会把 ThinkTerm 的叠加滚动条换成 WezTerm 自己的，不管 设置 › 终端 › 滚动条 怎么设。
在 设置 › 快捷键 里设置的快捷键保存在 settings.json 里，压过 keys 里的同一个键和内置默认值；配置文件本身从不被改写。运行配置文件里某个 Lua 函数的快捷键，只能在文件里改。见 快捷键与命令。
窗口透明度 是一个从 30% 到 100% 的滑块，每档 5%，带 Beta 标记，没动过它时显示 默认。拖动它会为所有窗口设置 window_background_opacity；在 macOS 上，窗口透明时还会加上半径为 20 的背景模糊，除非配置文件自己设置了 macos_window_background_blur。它在 Linux 上是灰的，不过配置文件里的 window_background_opacity 照常有效；设置里注明它在 Windows 上还不够稳定，那里的 win32_system_backdrop 仍由配置文件决定，而毛玻璃会随着透明度在 ThinkTerm 重启后出现。见 窗口。
没有选定方案时，浅色界面还会自带一个浅色终端配色 —— 见 窗口。
在设置里选的配色方案和窗口透明度，无论有没有配置文件都会生效。
配置文件的读取顺序
ThinkTerm 会加载它找到的第一个文件，顺序如下：
- 命令行上的
--config-file PATH $THINKTERM_CONFIG_FILE$WEZTERM_CONFIG_FILE- 可执行文件同目录下的
thinkterm.lua—— 仅 Windows - 可执行文件同目录下的
wezterm.lua—— 仅 Windows ~/.config/thinkterm/thinkterm.lua~/.config/thinkterm/wezterm.lua~/.thinkterm.lua
还有两个命令行标志和第一条一同起作用。--skip-config（-n）完全跳过这轮搜索，直接用内置默认值运行；--config name=value 可以重复给出，在已加载的配置之上覆盖单个配置项。三者都是全局标志，要写在子命令前面。
$THINKTERM_CONFIG_DIR 和 $WEZTERM_CONFIG_DIR 不参与这个搜索。它们是 ThinkTerm 在配置加载完成之后写出的 —— 指向配置文件所在的目录，供你启动的程序读取。自己设置它们并不能选中某份配置。
那两条仅限 Windows 的规则是有意为之：配置文件放在可执行文件旁边时优先级最高，这样 ThinkTerm 可以装在 U 盘里带走，在一台没有自己配置、或者装着别人配置的机器上运行。
其中的 wezterm.lua 文件名也不是遗留物：它让一份现成的 WezTerm 配置可以直接放进 ThinkTerm 的目录，不必改名。
ThinkTerm 会从 WezTerm 安装里取用什么
你的 WezTerm 配置文件不会被加载。上面所有位置都不指向 ~/.config/wezterm/wezterm.lua，ThinkTerm 也从不写入它。
但这个隔离并不彻底，有两条通路值得知道。
WEZTERM_CONFIG_FILE 会被遵循。 它排在上面的搜索顺序里，所以如果你的环境里导出了这个变量（如果你当初就是这样配置 WezTerm 的，很可能就是如此），ThinkTerm 会加载它指向的文件。WezTerm 还会在它打开的每个终端里设置这个变量，所以从 WezTerm 里的 shell 启动的 ThinkTerm，加载的是 WezTerm 的配置。设置 THINKTERM_CONFIG_FILE，或者取消那个 WezTerm 的变量，就能让两套安装互不干扰。
WezTerm 的配置目录仍会被搜索 Lua 模块和配色方案。 ~/.config/wezterm/ 和 ~/.wezterm/ 位于 Lua 的 package.path 上，~/.config/wezterm/colors/ 也会被搜索配色方案。所以在 ThinkTerm 配置里写 require 'mymodule'，会找到你为 WezTerm 写的模块。被隔离的是配置文件本身，不是整个目录。
导入
设置 › 导入 导入这台电脑上另一个程序已有的东西：WezTerm 配置里的设置、你的编辑器、编程 agent 和 cmux 用过的文件夹，以及 Herdr 的会话。每次导入都只做一次 —— 之后与来源不再有任何联系。
这一页分三步：选择来源、预览内容 和 导入结果。第一步把各个来源列成卡片，继续 读取你选的那个。返回 回到卡片，最后一步的 继续导入 从卡片重新开始。WezTerm 始终在列表里。项目文件夹 只在 ThinkTerm 在这台电脑上找到受支持的编辑器、编程 agent 或 cmux 时出现，Herdr 带有 Beta 标记，在 macOS、Linux 和 Windows 上都提供。
ThinkTerm 第一次打开时，欢迎页会在找到这些东西时把它们列出来，每一项都有一个按钮，直接在该来源的 预览内容 一步打开这一页 —— 见 安装。
从 WezTerm 导入
WezTerm 卡片把现有 WezTerm 配置里你选中的设置复制进 ThinkTerm 的配置。之后两个文件相互独立，WezTerm 文件后来的改动只有再导入一次才会进到 ThinkTerm。
它按下面的顺序找 WezTerm 配置，用第一个存在的：
~/.wezterm.lua$XDG_CONFIG_HOME/wezterm/wezterm.lua；没设置XDG_CONFIG_HOME时是~/.config/wezterm/wezterm.lua$XDG_CONFIG_DIRS里每个目录下的wezterm/wezterm.lua—— 仅 macOS 和 Linux
WEZTERM_CONFIG_FILE 在这里不起作用，尽管它在上面 ThinkTerm 自己的配置搜索里起作用。
继续 会加载那个文件 —— 它是 Lua，所以会像在 WezTerm 里一样被执行 —— 预览内容 一步先显示 WezTerm 配置和 ThinkTerm 自己的配置分别在哪里找到，再列出文件里可导入的设置。只有文件自己设置了的项才会出现：留着 WezTerm 默认值的项不会，所以导入永远不会把 WezTerm 的默认值写到 ThinkTerm 的默认值上面。第一次时，找到的每一项都是选中的，计数旁边有 全选 和 清除。可导入的设置共十五个：
color_scheme、window_background_opacity、macos_window_background_blur、inactive_pane_hsb、font、font_size、line_height、cell_width、default_prog、default_cwd、front_end、window_decorations、disable_default_key_bindings、keys、key_tables
这个列表限定的是导入器替你复制的范围，不是 ThinkTerm 支持的范围。其他任何 WezTerm 配置项，手写进 ThinkTerm 的配置文件里同样有效。
重新读取 会再读一遍文件。没有找到 WezTerm 配置时，它和 导入所选项 都是灰的；一项都没勾选时，导入所选项 也是灰的。导入所选项 把选中的值写成一个普通的 Lua 表，存到 ~/.config/thinkterm/imported_from_wezterm.lua。这个文件归导入器管：每次导入都会整个替换它，所以在里面做的改动下次就没了。要改请改你自己的配置。
接下来怎样，取决于 ~/.config/thinkterm/ 里是否已经有 ThinkTerm 配置：
- 还没有：导入会同时创建
~/.config/thinkterm/thinkterm.lua，它加载导入的文件并返回结果。不需要再做什么。 - 已经有 ——
thinkterm.lua或wezterm.lua—— 你的文件不会被改动，导入的值在你的文件加载它们之前不起作用。在返回配置的那一行之前加上这段，其中config是你的文件返回的那个表：
local imported = require 'imported_from_wezterm'
for key, value in pairs(imported) do
config[key] = value
end写在这个循环之后的赋值会覆盖导入的值。
放在其他位置的配置不会被察觉。如果你的配置是 ~/.thinkterm.lua，导入创建的 thinkterm.lua 在搜索顺序里排在它前面，会被加载而取代它。
从编辑器、编程 agent 和 cmux 导入项目文件夹
项目文件夹 卡片（副标题是 来自编辑器和编程 agent）提供你用过的文件夹。来源有三类：
- 编辑器。 VS Code 及其衍生编辑器打开过的文件夹：VS Code、VS Code Insiders、Code - OSS、VSCodium 及其 Insiders 版本、Cursor、Windsurf、Antigravity、Kiro、Positron、Trae 和 Void。每个编辑器只在它自己的用户数据文件夹里查找。多根工作区（编辑器记录的是一个
.code-workspace文件，而不是文件夹）会被跳过。 - 编程 agent。 Claude Code、Codex 和 Pi 启动时所在的文件夹，从它们各自保存的会话记录里读：Claude Code 的项目列表在
~/.claude.json，Codex 的会话在~/.codex/sessions，Pi 的在~/.pi/agent/sessions。 - cmux（macOS）。每个 workspace 的文件夹，以及它各个终端所在的文件夹，来自 cmux 保存在
~/Library/Application Support/cmux的会话。日期取 cmux 最后一次保存这份会话的时间。
只有文件夹路径和最后使用的日期会被导入。文件夹里的内容一概不读取，agent 会话里说过什么也不读取。
预览内容 一步按最近使用的先后列出这些文件夹，每个编辑器、agent 或 cmux 有一个按钮，用来缩小范围。最近 30 天用过的文件夹一开始是勾选的。已经是所选 Space 里某个 Project 的，显示为 已在侧栏，一开始不勾选。添加到 选择放进哪个本地 Space —— 如果打开设置的那个 Space 是本地的，就是它 —— 每个勾选的文件夹成为一个带一个 Thread 的 Project。列表下方有一行，统计通过 SSH、WSL 或容器打开、暂时不能添加的文件夹。
从 Herdr 导入
Herdr 卡片把一个 Herdr 会话导入为一个新的 Space，名为 Herdr — <会话>。每个 Herdr workspace 成为一个带一个 Thread 的 Project，里面是该 workspace 的标签和 pane。它带有 Beta 标记。ThinkTerm 在 Herdr 的配置文件夹 ~/.config/herdr 或 $XDG_CONFIG_HOME/herdr（Windows 上，没设置 XDG_CONFIG_HOME 时是 %APPDATA%\herdr）里找会话：默认会话，以及 sessions/ 下的每一个。
继续 会读取会话。只有一个时，直接打开它的预览；有多个时，每个都有一个 预览 按钮，已经导入过的会话带一个 已导入 标记。预览页的标题是 导入预览，写明新 Space 的名字，统计 Project、一级标签和终端的数量，并列出每个 Project 的终端。重新预览 会再读一遍会话。如果预览之后会话的结构、运行状态或保存的布局变了，导入会中止，并要求先重新预览。导入已经导入过的会话会给出警告，因为那会另建一个 Space。
Herdr 自己的文件保持不变，所以再次启动 Herdr 时，它可能恢复旧布局并继续它保存的内容。
两种模式用哪一种，取决于会话是否正在运行：
| 运行中的会话 | 保存的布局 | |
|---|---|---|
| 按钮 | 迁移运行中的会话 | 导入布局 |
| 做什么 | 把会话的终端迁入 ThinkTerm；现有进程继续运行 | 在保存的目录里打开新的 shell |
| 不会带过来的 | 完整的回滚历史和图片。全屏程序可能需要重绘 | 保存的启动命令和 Agent 恢复命令不会执行 |
| 需要 | Herdr 支持 live_handoff，且协议版本兼容 | 保存的目录必须存在，布局格式须受当前 ThinkTerm 支持 |
在 Windows 上，Herdr 无法交出运行中的终端，所以只有 导入布局：它读取 Herdr 在每次改动几秒后保存的布局，不管 Herdr 是否正在运行，把其中的标签、分屏和文件夹带过来，每个 pane 新开一个 shell。这个 shell 是 设置 › 终端 › 默认 Shell 里选的那个；没选的话，是 default_prog（当它指向一个 shell 时）；再不行就是命令处理器。Herdr 可以开着，里面正在运行的东西不会被动。
条件不满足时，导入会被拒绝，并显示原因。两种模式都要求会话属于你的账号、会话目录可以访问。运行中的会话还要求 Herdr 和 ThinkTerm 共用临时目录、socket 和 ThinkTerm 程序，Linux 上 /tmp 不能以 noexec 挂载。
有远程服务器上的 Space 时，从哪台机器导入 会列出 本机 和这些主机；未连接的主机在选中时会先连接。从远程主机导入读取的是那台服务器上的 Herdr，进程仍留在那台服务器上。会话必须属于远程连接所用的账号。
导入过程中连接中断时，页面会提供 检查导入结果，它会重新连接并取回那次请求的结果。请用它，不要另行发起第二次导入。导入完成后，打开 Space 会打开新建的 Space。
数据存放位置
macOS
- 配置文件 ——
~/.config/thinkterm/ - 工作区数据 ——
~/Library/Application Support/ThinkTerm/ - 终端状态 ——
~/Library/Application Support/thinkterm/ - 缓存 ——
~/Library/Caches/thinkterm/ - 运行时 ——
~/.local/share/thinkterm/
Linux
- 配置文件 ——
~/.config/thinkterm/ - 工作区数据 ——
~/.local/share/ThinkTerm/ - 终端状态 ——
~/.local/share/thinkterm/ - 缓存 ——
~/.cache/thinkterm/ - 运行时 ——
$XDG_RUNTIME_DIR/thinkterm/
Windows
- 配置文件 ——
%USERPROFILE%\.config\thinkterm\ - 工作区数据 ——
%APPDATA%\ThinkTerm\ - 凭据 ——
%LOCALAPPDATA%\ThinkTerm\ssh\ - 终端状态 ——
%APPDATA%\thinkterm\ - 缓存 ——
%LOCALAPPDATA%\thinkterm\ - 运行时 ——
~/.local/share/thinkterm/
上面有四点容易踩坑。
配置路径不遵循各平台惯例。 所有操作系统上都使用 ~/.config/thinkterm/，Windows 也不例外 —— 不是 %APPDATA%。因此配置与数据在每个平台上都是分开存放的，Linux 也一样 —— 那里配置在 ~/.config 下，数据在 ~/.local/share 下。
有两个仅大小写不同的数据目录。 工作区数据 —— Space、Project 与 Thread 结构，片段，以及在 Unix 上还包括 SSH 主机簿和它的加密密钥 —— 写在 ThinkTerm/。终端与多路复用状态写在 thinkterm/。macOS 和 Windows 的文件系统默认对大小写不敏感，两者通常会合并成同一个目录 —— 但在大小写敏感的 APFS 卷上不会。在 Linux 上它们始终是独立的两个目录。无论落在哪里，两者都属于 ThinkTerm。
Windows 上，凭据被刻意挪出漫游配置文件。 SSH 主机簿和它的加密密钥不和其余工作区数据一起放在 %APPDATA%，而是放在 %LOCALAPPDATA% 下，这样域账户注销时不会把它们复制到配置文件服务器上。旧安装里的那两个文件会在 ThinkTerm 第一次需要时成对迁移过去。网页监听器的证书和私钥出于同样的理由也放在那里。
运行时目录同样不随平台惯例。 多路复用 socket、pid 文件和 TLS 材料在 Linux 上位于 $XDG_RUNTIME_DIR/thinkterm/，在 macOS 和 Windows 上回落到 ~/.local/share/thinkterm/ —— 这两个平台上本来并没有别的东西放在那里。thinkterm cli 找不到服务端时，这一条值得想起来。
笔记库不存放在上述任何一处。它是你自己选定的目录，里面是普通的 Markdown 文件；ThinkTerm 只记录这个绑定关系。
从 WezTerm 带过来的数据
当 WezTerm 的数据目录存在时 —— macOS 上是 ~/Library/Application Support/wezterm/，Linux 上是 ~/.local/share/wezterm/，Windows 上是 %APPDATA%\wezterm\ —— ThinkTerm 在启动时会从中复制四样东西到自己的终端状态目录：
| 项目 | 是什么 |
|---|---|
plugins | wezterm.plugin.require 取回的 Lua 插件 |
recent-commands.json | 命令面板的最近命令 |
recent-emoji.json | 字符选择器的最近选择 |
repl-history | 调试浮层的 Lua 历史 |
每一样都只在 ThinkTerm 自己还没有时才复制，所以实际上只发生一次，也从不覆盖任何东西。WezTerm 那边的文件原样留着，那个目录里的其他东西也不会被读取。
备份与恢复
设置 › 备份 把 ThinkTerm 自己的状态导出到你选定的文件夹，也能从这样的文件夹里恢复。你不导出，就不会有任何备份。
导出会新建一个文件夹，名字是 ThinkTerm Backup 加上日期和时间。里面是普通的 JSON 文件，旁边的 thinkterm-backup.json 列出了它们：
| 文件 | 内容 |
|---|---|
workspace_threads.json | Space、Project 与 Thread |
ssh_hosts.json | ThinkTerm 自己的 SSH 主机簿 |
snippets.json | 片段 |
recent-commands.json | 最近使用的命令 |
Space 是从 ThinkTerm 内存里的状态写出的，所以即便上一次保存还没落盘，导出的也是屏幕上看到的样子。在 macOS 和 Linux 上，每个文件都以 0600 权限写出。
secret.key 被有意排除在外。已保存的密码仍以这台机器的密钥加密、随主机簿一起导出，所以到了另一台机器上需要重新输入。Lua 配置、settings.json 和笔记库也不在其中；它们是普通文件，照常复制即可。
导入不能在窗口运行时替换这些文件 —— 窗口把它们读在内存里，之后还会写回去。所以导入会先检查备份里的每个文件，然后等待：它由下一次启动、且发现没有其他 ThinkTerm 窗口在运行的那个进程应用，赶在任何东西读取状态之前；页面上的 退出 ThinkTerm 就是为此准备的。每个被替换的文件都会以 <name>.before-import-<time>.json 的名字保留在原文件旁边。只要有一个文件放不到位，已经替换掉的那些会还原，所以失败的导入什么都不会改变；失败会显示在备份页上，不会自动重试。
有一样东西是合并而不是替换的。本机会话 server 里仍然保留着的 Space，会在 ThinkTerm 下次连接它时被加回来，两边都有的以 server 上的名字为准。导入带回的是备份里有的东西，不会删掉 server 留着的东西。
界面语言
设置 › 通用 › 语言 会立即切换 ThinkTerm 自身界面的语言，无需重启。跟随系统 从系统设置取值，并显示实际解析到的语言。
界面提供英语、简体中文、日语、法语、德语和俄语。这只影响 ThinkTerm 自己的界面——终端内容以及所有由 WezTerm 渲染的部分都不受影响。
命令名也跟着语言走：命令面板里、macOS 菜单栏里、快捷键页里都是。切换语言的那一刻，菜单栏就会重建。命令面板按英文名记住你运行过的命令，所以换了语言，历史记录仍然有效。
在 macOS 上，显示中文需要苹方（PingFang），而它是 macOS 按需下载的字体。当这台 Mac 把简体中文排在日语和韩语前面读、又没有苹方时，ThinkTerm 会用系统自带的冬青黑体（Hiragino Sans GB）绘制汉字、CJK 标点和假名，免得只有简体里才有的字画成空框。这时 设置 › 通用 › 语言 那一行下面会多一条提示，请你在“字体册”里下载 PingFang SC，再重启 ThinkTerm。装有苹方，或这台 Mac 并不最先读简体中文时，冬青黑体只绘制其他字体都没有的汉字。
渲染器
设置 › 通用 › 渲染器 在 OpenGL 和 WebGpu 之间选择，作用于终端窗口和设置窗口。和语言不同，它要到 ThinkTerm 下次启动时才生效。没有选过时，它跟随配置文件里的 front_end；这个选项不设置时，Windows 上是 OpenGL，其他平台是 WebGpu，所以默认如此；那里写 OpenGL 或 Software 都用 OpenGL。
其中一个失败并不致命。当前使用的渲染器启动不了 —— 找不到可用的 WebGpu 适配器，或者 OpenGL 太旧、跑不了 ThinkTerm 的着色器 —— 窗口会改用另一个打开，设置窗口也一样，这样一台只有其中一个能用的机器，不会连那个能把它切换回来的开关都打不开。只有两个都失败时，窗口才打不开。front_end = 'Software' 从不回退。
光标
设置 › 终端 › 显示 里有两行和光标有关。
光标形状 可选 方块、竖线、下划线。默认的 方块 把形状交给配置文件里的 default_cursor_style，它不写就是方块。竖线 和 下划线 会替换配置文件给的形状，并保留它的闪烁与否。
光标闪烁 可选 不闪、平滑、硬闪。默认的 不闪 让光标保持配置文件里的样子：除非 default_cursor_style 要求闪烁，否则不闪。平滑 和 硬闪 会让光标闪烁。平滑 沿 cursor_blink_ease_in 和 cursor_blink_ease_out 的曲线渐入渐出；硬闪 则在完全亮和完全灭之间直接切换，不管那两项怎么写。每一段持续 cursor_blink_rate 那么久，不设置就是 600 毫秒。
程序自己指定了光标样式时（比如编辑器切换模式时），以程序为准。两项选择都会立刻作用于所有已打开的窗口，不需要重新加载配置。
更新检查
桌面应用会自己检查有没有新版本，设置 › 软件更新 里有两行与此有关：开关 自动检查更新，和 检查频率，后者可选 每 12 小时、每天、每周，开关关着时是灰的。这两行用到之前，跟随配置文件：开关是 check_for_updates，频率是 check_for_updates_interval_seconds；用过之后，以这一行为准，不再读配置文件里的那一项。改动在一分钟内生效，不用重启。
距离记录里上一次检查满了一个频率的时间，就到该检查的时候了，不管上一次是怎么发生的 —— 你自己点 检查更新 也算。所以每周一次的检查跨启动也还是每周一次：ThinkTerm 启动几秒后，只有过了这么久才会检查。上次检查 显示的就是那个时间。开关关着时，只有你点 检查更新 才会查。其余流程见 更新，请求带了什么见 隐私与安全。
恢复窗格内容
ThinkTerm 的终端按正常流程停下时 —— 你连同其中的终端一起退出了 ThinkTerm、电脑关机或你注销了、会话 server 被停掉 —— 它可以把每个 pane 里显示的内容留下来，等下次恢复那个 Thread 的布局时放回去。开关是 设置 › 通用 › 重新打开时恢复窗格内容。
在桌面应用所在的机器上它默认是开的：应用启动时，只要这一项没被明确设成开或关，就会把它打开；关掉之后会记下“已关”，所以保持关闭。它只管这台电脑上的终端。在别的机器上，比如远程主机，要先在那里的终端运行 thinkterm cli restore-output on 才会开；restore-output off 再把它关上，并删除已保存的内容，restore-output status 告诉你现在是开还是关。
保存下来的是每个本地 pane 的主屏幕和回滚历史，以文字和颜色的形式，最多 10,000 行。全屏程序的画面和图片不保存。写入之前，看起来像密码、token 或私钥的内容会被换成 •，所以原文永远不会落到磁盘上。记录放在终端状态目录（见下文）的 kept-output 里。布局一回来，对应的记录就被删除；如果那个 Thread 一直没再打开，15 天后也会删除。
恢复的 pane 里，旧输出出现在新 shell 的上方，接着是一行暗色的 ── closed … · restored … ──，写着关闭和恢复的时间，shell 从它下面开始。回来的是旧输出，不是旧进程：当时在跑的东西不会重新运行。
崩溃或断电来不及保存，所以这两种情况下布局会回来，输出不会。
macOS 上的文件夹访问
Project 绑定到一个文件夹，而这个文件夹能不能读由 macOS 决定。访问被拒绝时，Project 页面会说明情况，并指向 系统设置 › 隐私与安全性 › 文件和文件夹 › ThinkTerm。
有两点是 ThinkTerm 特有的。
Project 右键菜单提供 授权文件夹访问…。 它调用的是被拦截页面里同一个选择器，随后会打开该 Project 的第一个 Thread，让这次授权被真正验证过，而不是假定成功。
会话 server 是以自己的名义申请的。 当本地终端跑在后台会话 server 里时，那个守护进程带有独立的 macOS 隐私身份，因此它需要的权限未必就是你已经授给 GUI 的那一份。如果拒绝来自 server，页面会说明这一点，并提供直接打开系统设置对应位置的入口。
被拒绝的文件夹现在会报错，而不是静默回退。早先的构建会不声不响地退回主目录，结果拒绝根本传不到界面上，也就永远无法授权。
环境变量 THINKTERM_NO_PRIVACY_DISCLAIM 会跳过让守护进程取得这个独立身份的那一步。
macOS 上的权限
macOS 把你在 ThinkTerm 终端里运行的每个程序都算在 ThinkTerm 名下。设置 › 权限 只在 macOS 上有，它报告这些程序可能拥有的四项权限：完全磁盘访问、屏幕与系统录音、麦克风 和 摄像头。每一行显示 已允许、没有、被拒绝、还没问过 或 查不到，打开系统设置 按钮会打开系统设置里对应的面板。查看本身从不会让 macOS 向你弹出提问。麦克风和摄像头在有程序第一次想用之前显示 还没问过。完全磁盘访问和屏幕录音分不清是被拒绝了还是从没问过，所以显示 没有。
完全磁盘访问 有一条单独的警告。一旦允许，终端里的任何程序 —— 包括脚本和编程 agent —— 都可以读写桌面、文稿、下载、邮件和其他应用的数据，macOS 不会再问。只在确实需要时打开，用完就到系统设置里关掉。它也必须手动添加：在系统设置里点 +，把对应的程序拖进列表。
这个程序是谁，取决于本地终端跑在哪里。放在后台会话 server 里时（这是默认），权限属于 server 自己，最后一行的标题是 ThinkTerm 后台服务；否则是 ThinkTerm。授给其中一个的权限不属于另一个，这就是你为 ThinkTerm 允许过的文件夹可能要再允许一次的原因。那一行的按钮会在访达中显示这个程序。为什么提示里写的是 ThinkTerm，见 隐私与安全。
提示音、通知与 Dock 数字
设置 › 工作区 里的 通知 卡片最多有三种方式让你知道某个 Thread 的动静：提示音、系统通知，以及仅 macOS 有的 Dock 图标数字，后者在 ThinkTerm 的 Dock 图标上显示还有多少个 Thread 里有你没看过的东西。三种默认都是开的。
每一种下面都有一组要不要通知的场合：完成、等你 和 出错，取消之前都是勾选的。把 提示音 下面的 完成 取消，Thread 完成时就不再响，但等待的提示音还在；另外两项同理。Dock 数字只在勾选了 完成 时才计入已完成的 Thread，对需要处理的 Thread，则看它在等什么，只在勾选了 等你 或 出错 时才计入。状态和提示音见 Agent 状态，系统通知带了什么见 隐私与安全。
配置项参考
绝大多数配置项都原样来自 WezTerm，因此参考文档在上游：
三点提醒。
ThinkTerm 于 2026 年 3 月 31 日从 WezTerm 分叉，此后上游新增的配置项这里可能尚未提供。
有些配置项名称和含义没变，但默认值变了；它们列在下文。
另外 ThinkTerm 有自己新增的配置项，上游文档里查不到：
| 配置项 | 控制什么 |
|---|---|
agent_status_detection | 是否运行会话状态检测 |
web_servers | 多路复用服务端启动时打开的网页监听器。见 网页访问 |
ui_colors | ThinkTerm 自身界面的颜色；colors 仍然是终端调色板。见 界面颜色 |
remote_mux_auto_claim_on_open | 主动连接远程主机时是否立刻接管它的终端 |
note_spellcheck_enabled | Markdown 编辑器中的拼写检查 |
note_remote_images_enabled | 笔记中是否加载远程 URL 图片 |
note_reading_max_width | 笔记正文栏最宽能到多少，单位是逻辑像素（macOS 上即点）。默认 820；笔记区更宽时正文栏居中 |
right_sidebar_search_respects_gitignore | 文件搜索是否跳过被忽略的文件。文件树里仍然会显示它们 |
unfocused_fps | 可见但未聚焦的窗口因终端输出而重绘的频率。默认 10；0 表示不限制 |
kitty_image_memory_budget_mib | 每个 pane 最多保留多少图片数据，单位 MiB。默认 128；0 表示不限。见 窗口 |
live_overview_preview_refresh_ms | Live Overview 卡片重新读取终端内容的间隔。默认 300 |
text_min_contrast_ratio 是上游的配置项，但 设置 › 终端 › 最低文字对比度 压在它上面：在那里选了比例就以它为准，选 关 则交回配置文件里的值。
插件不在 Lua 文件里配置。见 插件。
与 WezTerm 不同的默认值
这些配置项的含义和上游一样，但配置文件不设置时，起点不同：
| 配置项 | WezTerm | ThinkTerm |
|---|---|---|
front_end | OpenGL | WebGpu，Windows 上是 OpenGL |
initial_cols | 80 | 120 |
initial_rows | 24 | 32 |
max_fps | 60 | 120 |
default_cwd | 未设置 | 你的主目录 |
native_macos_fullscreen_mode | false | true |
color_scheme（macOS） | 未设置 | Apple System Colors，前提是 colors 也没设置 |
adjust_window_size_when_changing_font_size（macOS） | 未设置 | false |
cursor_blink_rate | 800 | 600 |
command_palette_font_size | 14 | 13 |
default_cwd 在终端没有别的依据时才起作用 —— 它自己没有目录，打开它的那个终端也没报告目录。这时它从你的主目录开始，而不是从 ThinkTerm 本身被启动时所在的目录开始。adjust_window_size_when_changing_font_size 为关时，改字号会保持窗口大小不变，改变的是里面能放下多少行和列。
还有两项在不设置时由终端调色板推出来。非活动 pane 的压暗 inactive_pane_hsb 在浅色配色下比深色配色下更轻，而不再是固定的一个值；pane 分割线的颜色也是从终端背景混合出来的。一旦显式写死，它们的行为就和上游文档描述的完全一致。
配色方案也可以在设置窗口里决定，而不是在文件里；见 设置与配置文件重叠的地方。
界面颜色
ui_colors 覆盖 ThinkTerm 画在终端周围的颜色 —— 侧边栏、标签栏、pane 上方的标签条、设置窗口、菜单。每一项都是可选的，没设置的项保持主题本来会用的颜色，所以一个写了两种颜色的表只改两种颜色：
config.ui_colors = {
sidebar_bg = '#282828',
accent = '#d79921',
}颜色的写法和配置文件里其他地方一样。可用的项：
| 分组 | 项 |
|---|---|
| 底面 | window_bg（最底下的背景）、sidebar_bg、workspace_sidebar_bg（凹下去一层的侧栏底色；设置窗口里的页面列表）、header_bg（标签上方的条）、card_bg（window_bg 上的卡片）、group_bg（卡片里成组的行）、separator |
| 控件 | control_bg、control_hover_bg、control_pressed_bg、control_border、track_off（开关关闭的那一半） |
| 侧边栏 | sidebar_button_bg、sidebar_button_hover_bg、sidebar_row_hover_bg、sidebar_row_pressed_bg、sidebar_row_active_bg、sidebar_row_active_border |
| 选中与强调色 | selected_bg、selected_text、accent、accent_hover、on_accent（强调色上的文字和图标）、danger（破坏性操作和错误） |
| 文字 | text、secondary_text、muted_text |
| 其他 | scrollbar_thumb（叠加滚动条）、spelling_error（拼写错误下面的那条线） |
在 跟随终端配色 下，底面和文字会挪到终端背景上，但 accent、accent_hover、on_accent、selected_bg、danger 和 spelling_error 保持设计时的值：配色方案自带的蓝色在它自己的背景上常常难以看清。想让它们也一致，就在这里设置。
环境变量
ThinkTerm 启动的每个终端里都设置了这些：
| 变量 | 值 |
|---|---|
THINKTERM | 1 |
THINKTERM_VERSION | ThinkTerm 的版本 |
TERM_PROGRAM、TERM_PROGRAM_VERSION | WezTerm 和版本号。保留它们是为了让认得 WezTerm 的工具继续工作；要区分 ThinkTerm，请检查 THINKTERM |
WEZTERM_PANE | 这个 pane 的 id，thinkterm cli 把它当作默认 pane |
WEZTERM_UNIX_SOCKET | 多路复用 socket，ThinkTerm 有的时候才设置 |
THINKTERM_MUX_SERVER_ID | pane 跑在哪个多路复用服务端里。thinkterm tui 用它拒绝连接到自己正运行于其中的那个服务端 |
THINKTERM_CONFIG_FILE、WEZTERM_CONFIG_FILE | 加载的配置文件，有加载时才设置 |
THINKTERM_CONFIG_DIR、WEZTERM_CONFIG_DIR | 配置文件所在的目录 |
ThinkTerm 会读取这些：
| 变量 | 作用 |
|---|---|
THINKTERM_CONFIG_FILE、WEZTERM_CONFIG_FILE | 要加载的配置文件。见 读取顺序 |
THINKTERM_DISABLE_SOUND | 设为任何值，都会让提示音静音，不管设置里怎么选 |
THINKTERM_UPDATE_TOKEN | 更新检查时发送的 GitHub token，用来解除匿名请求的频率限制。环境里的 GITHUB_TOKEN 永远不会被发送。见 更新 |
THINKTERM_NO_PRIVACY_DISCLAIM | 跳过给会话 server 独立 macOS 隐私身份的那一步。见 macOS 上的文件夹访问 |
THINKTERM_TUI_CONFIG | thinkterm tui 读取设置的位置。见 TUI |
WEZTERM_LOG | 日志过滤，与 WezTerm 相同 |