---
title: "配置"
description: "配置文件与设置窗口、每个设置页里有什么、从 WezTerm、编辑器、编程 agent 和 Herdr 导入、光标、更新检查、恢复窗格内容、数据存放位置、环境变量，以及 ThinkTerm 与 WezTerm 不同的默认值。"
url: "https://docs.closex.org/zh/thinkterm/configuration.html"
markdown_url: "https://docs.closex.org/zh/thinkterm/configuration.md"
site: "CloseX Docs"
product: "ThinkTerm"
language: "zh-Hans"
last_updated: "2026-11-08T12:04:16.000Z"
alternates:
  en: "https://docs.closex.org/thinkterm/configuration.md"
  zh-Hans: "https://docs.closex.org/zh/thinkterm/configuration.md"
  ja: "https://docs.closex.org/ja/thinkterm/configuration.md"
---

# 配置

> **文档编写中**
> 部分内容可能尚不完整。

ThinkTerm 用一个 Lua 文件配置，方式与 WezTerm 相同。配置项名称、模块名和语法都没有改动 —— ThinkTerm 的配置文件开头依然是：

```lua
local wezterm = require 'wezterm'
```

不同的只是文件从哪里读、数据往哪里写。

## 两处配置，不是一处

Lua 文件是你手写的那一份，装着终端自身的配置项。

在它旁边，`~/.config/thinkterm/settings.json` 由设置窗口写出，存放那些在设置里有开关的选择 —— 主题、窗口透明度、快捷键、滚动方式与叠加滚动条、界面字号与侧边栏宽度、界面语言、渲染器、标签图标。它不是用来手工编辑的。两边重叠时，几乎总是以设置窗口里的选择为准；[例外见下文](#设置与配置文件重叠的地方)。

你在使用过程中，这个文件也会被不断改写 —— 拖动或收起侧边栏、移动窗口 —— 但这些都不会重新加载 Lua 配置，所以不会因此重新加载字体，也不会关掉命令面板。如果有人从外部改了它，比如用编辑器或别的程序，ThinkTerm 会立刻读到，并像设置窗口那样把改动生效，而不是放着不用，等下一次保存时再用旧的那份把它覆盖掉。

## 设置窗口

`设置` 可以从侧边栏底部的齿轮打开，macOS 上也可以按 ⌘,，其他平台按 Ctrl+Shift+,。它的各个页面，以及每页在哪里有说明：

| 页面 | 里面有什么 | 说明见 |
|---|---|---|
| 通用 | 语言、渲染器、恢复主窗口位置与大小、加载的是哪个配置文件、后台会话 server、重新打开时恢复窗格内容、重启与退出 | 本页、[窗口](https://docs.closex.org/zh/thinkterm/window.md)、[远程](https://docs.closex.org/zh/thinkterm/remote.md) |
| 外观 | 主题、当前配色方案、应用图标、字体排版、窗口透明度，macOS 26 上的玻璃效果，侧栏、标签栏和终端的颜色深浅，以及侧边栏里的图标与状态标记 | [窗口](https://docs.closex.org/zh/thinkterm/window.md)、[窗口透明度](https://docs.closex.org/zh/thinkterm/window.md#窗口透明度)、[图标与状态](https://docs.closex.org/zh/thinkterm/window.md#侧边栏里的图标与状态) |
| 标签图标 | pane 标签上的程序图标 | [窗口](https://docs.closex.org/zh/thinkterm/window.md#标签图标) |
| 侧栏与插件 | 右侧面板、状态、已安装的插件 | [窗口](https://docs.closex.org/zh/thinkterm/window.md#右侧面板)、[插件](https://docs.closex.org/zh/thinkterm/plugins.md)、[Agent 状态](https://docs.closex.org/zh/thinkterm/agents.md) |
| 终端 | 默认 Shell、字体、滚动方式、滚动条、最低文字对比度、光标形状与光标闪烁、鼠标与剪贴板、分屏动画、远程分屏缩放、底部语录 | 本页、[窗口](https://docs.closex.org/zh/thinkterm/window.md)、[复制与粘贴](https://docs.closex.org/zh/thinkterm/window.md#复制与粘贴)、[远程](https://docs.closex.org/zh/thinkterm/remote.md)、[隐私与安全](https://docs.closex.org/zh/thinkterm/privacy.md#links-and-pastes-a-program-prints) |
| 工作区 | 远程文件连接空闲超时、下载文件夹、远程拖放目标、提示音、系统通知，macOS 上还有 Dock 图标数字 | [文件与笔记](https://docs.closex.org/zh/thinkterm/files-and-notes.md)、[Agent 状态](https://docs.closex.org/zh/thinkterm/agents.md)、[本页](#sounds-notifications-and-the-dock-count) |
| Agent | 识别哪些编程 Agent，以及如何识别 | [Agent 状态](https://docs.closex.org/zh/thinkterm/agents.md) |
| 网页 | 浏览器访问，以及发出去的链接 | [网页访问](https://docs.closex.org/zh/thinkterm/web.md) |
| 共享与同步 | `分享终端`：让这台机器上的其他账户看你的终端，标有实验性 | — |
| 权限 | 仅 macOS：终端里的程序拥有哪些权限 | [本页](#macos-上的权限) |
| 已归档 | 已归档的 Project | [Space、Project 与 Thread](https://docs.closex.org/zh/thinkterm/spaces.md) |
| 快捷键 | 一个会显示每个键作用的键盘，可以为命令分配快捷键 | [快捷键与命令](https://docs.closex.org/zh/thinkterm/keyboard.md#keymap-page) |
| 命令面板 | 命令面板的快捷键、行数、字号和搜索 | [快捷键与命令](https://docs.closex.org/zh/thinkterm/keyboard.md) |
| 导入 | 一次性导入 WezTerm 配置、编辑器、编程 agent 和 cmux 用过的文件夹和 Herdr 会话 | [本页](#导入) |
| 辅助功能 | `显示按钮形状`：让侧栏添加按钮的圆形底始终显示 | — |
| 备份 | 导出和导入 ThinkTerm 的状态 | [本页](#备份与恢复) |
| 软件更新 | 检查更新、检查的频率与安装 | [本页](#更新检查)、[更新](https://docs.closex.org/zh/thinkterm/updates.md) |
| 关于 | 版本、构建、链接，以及文件放在哪里 | [本页](#关于页与问题报告) |

`开发者` 页有一个开关，可以显示更多页面，那是给开发 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 函数的快捷键，只能在文件里改。见 [快捷键与命令](https://docs.closex.org/zh/thinkterm/keyboard.md#keymap-page)。

`窗口透明度` 是一个从 30% 到 100% 的滑块，每档 5%，带 Beta 标记，没动过它时显示 `默认`。拖动它会为所有窗口设置 `window_background_opacity`；在 macOS 上，窗口透明时还会加上半径为 20 的背景模糊，除非配置文件自己设置了 `macos_window_background_blur`。它在 Linux 上是灰的，不过配置文件里的 `window_background_opacity` 照常有效；设置里注明它在 Windows 上还不够稳定，那里的 `win32_system_backdrop` 仍由配置文件决定，而毛玻璃会随着透明度在 ThinkTerm 重启后出现。见 [窗口](https://docs.closex.org/zh/thinkterm/window.md#窗口透明度)。

没有选定方案时，浅色界面还会自带一个浅色终端配色 —— 见 [窗口](https://docs.closex.org/zh/thinkterm/window.md#两套颜色)。

在设置里选的配色方案和窗口透明度，无论有没有配置文件都会生效。

## 配置文件的读取顺序

ThinkTerm 会加载它找到的第一个文件，顺序如下：

1. 命令行上的 `--config-file PATH`
2. `$THINKTERM_CONFIG_FILE`
3. `$WEZTERM_CONFIG_FILE`
4. 可执行文件同目录下的 `thinkterm.lua` —— 仅 Windows
5. 可执行文件同目录下的 `wezterm.lua` —— 仅 Windows
6. `~/.config/thinkterm/thinkterm.lua`
7. `~/.config/thinkterm/wezterm.lua`
8. `~/.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 第一次打开时，欢迎页会在找到这些东西时把它们列出来，每一项都有一个按钮，直接在该来源的 `预览内容` 一步打开这一页 —— 见 [安装](https://docs.closex.org/zh/thinkterm/install.md#第一次打开)。

### 从 WezTerm 导入

WezTerm 卡片把现有 WezTerm 配置里你选中的设置复制进 ThinkTerm 的配置。之后两个文件相互独立，WezTerm 文件后来的改动只有再导入一次才会进到 ThinkTerm。

它按下面的顺序找 WezTerm 配置，用第一个存在的：

1. `~/.wezterm.lua`
2. `$XDG_CONFIG_HOME/wezterm/wezterm.lua`；没设置 `XDG_CONFIG_HOME` 时是 `~/.config/wezterm/wezterm.lua`
3. `$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` 是你的文件返回的那个表：

```lua
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 启动几秒后，只有过了这么久才会检查。`上次检查` 显示的就是那个时间。开关关着时，只有你点 `检查更新` 才会查。其余流程见 [更新](https://docs.closex.org/zh/thinkterm/updates.md)，请求带了什么见 [隐私与安全](https://docs.closex.org/zh/thinkterm/privacy.md)。

## 恢复窗格内容

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 允许过的文件夹可能要再允许一次](#macos-上的文件夹访问)的原因。那一行的按钮会在访达中显示这个程序。为什么提示里写的是 ThinkTerm，见 [隐私与安全](https://docs.closex.org/zh/thinkterm/privacy.md#macos-上的权限提示)。

## 提示音、通知与 Dock 数字 {#sounds-notifications-and-the-dock-count}

`设置 › 工作区` 里的 `通知` 卡片最多有三种方式让你知道某个 Thread 的动静：`提示音`、`系统通知`，以及仅 macOS 有的 `Dock 图标数字`，后者在 ThinkTerm 的 Dock 图标上显示还有多少个 Thread 里有你没看过的东西。三种默认都是开的。

每一种下面都有一组要不要通知的场合：`完成`、`等你` 和 `出错`，取消之前都是勾选的。把 `提示音` 下面的 `完成` 取消，Thread 完成时就不再响，但等待的提示音还在；另外两项同理。Dock 数字只在勾选了 `完成` 时才计入已完成的 Thread，对需要处理的 Thread，则看它在等什么，只在勾选了 `等你` 或 `出错` 时才计入。状态和提示音见 [Agent 状态](https://docs.closex.org/zh/thinkterm/agents.md)，系统通知带了什么见 [隐私与安全](https://docs.closex.org/zh/thinkterm/privacy.md)。

## 配置项参考

绝大多数配置项都原样来自 WezTerm，因此参考文档在上游：

- [WezTerm 配置文件](https://wezterm.org/config/files.html)

三点提醒。

ThinkTerm 于 2026 年 3 月 31 日从 WezTerm 分叉，此后上游新增的配置项这里可能尚未提供。

有些配置项名称和含义没变，但默认值变了；它们列在[下文](#与-wezterm-不同的默认值)。

另外 ThinkTerm 有自己新增的配置项，上游文档里查不到：

| 配置项 | 控制什么 |
|---|---|
| `agent_status_detection` | 是否运行会话状态检测 |
| `web_servers` | 多路复用服务端启动时打开的网页监听器。见 [网页访问](https://docs.closex.org/zh/thinkterm/web.md) |
| `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` 表示不限。见 [窗口](https://docs.closex.org/zh/thinkterm/window.md#终端里的图片) |
| `live_overview_preview_refresh_ms` | Live Overview 卡片重新读取终端内容的间隔。默认 `300` |

`text_min_contrast_ratio` 是上游的配置项，但 `设置 › 终端 › 最低文字对比度` 压在它上面：在那里选了比例就以它为准，选 `关` 则交回配置文件里的值。

插件不在 Lua 文件里配置。见 [插件](https://docs.closex.org/zh/thinkterm/plugins.md)。

## 与 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 上方的标签条、设置窗口、菜单。每一项都是可选的，没设置的项保持主题本来会用的颜色，所以一个写了两种颜色的表只改两种颜色：

```lua
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` 永远不会被发送。见 [更新](https://docs.closex.org/zh/thinkterm/updates.md) |
| `THINKTERM_NO_PRIVACY_DISCLAIM` | 跳过给会话 server 独立 macOS 隐私身份的那一步。见 [macOS 上的文件夹访问](#macos-上的文件夹访问) |
| `THINKTERM_TUI_CONFIG` | `thinkterm tui` 读取设置的位置。见 [TUI](https://docs.closex.org/zh/thinkterm/tui.md) |
| `WEZTERM_LOG` | 日志过滤，与 WezTerm 相同 |

## 相关

- [窗口](https://docs.closex.org/zh/thinkterm/window.md) —— 外观页和终端页在屏幕上改变了什么
- [快捷键与命令](https://docs.closex.org/zh/thinkterm/keyboard.md) —— 命令面板和它的设置页
- [远程](https://docs.closex.org/zh/thinkterm/remote.md) —— 主机簿，以及把本地终端放进会话 server
- [插件](https://docs.closex.org/zh/thinkterm/plugins.md) —— 插件带来什么、在哪里开关
- [更新](https://docs.closex.org/zh/thinkterm/updates.md) —— `check_for_updates` 以及更新流程的其余部分
- [隐私与安全](https://docs.closex.org/zh/thinkterm/privacy.md) —— ThinkTerm 什么时候通过网络发送什么