配置
Termia 的全局设置都在一个 JSON 文件里:settings.json。它是一个扁平文件——不用嵌套对象,而是用
: 作为命名空间分隔符(如 term:fontsize、window:transparent)。本页说明这个文件在各平台的
位置、如何编辑它、它与连接级 / Block 级覆盖之间的关系,以及它声明的每一个键。
settings.json 在哪里
Termia 把可编辑配置放在一个"点目录"风格的目录里,三个平台上位置相同,与体积更大的数据目录 (SQLite 数据库、日志、tab 缓存状态)分开:
| 默认位置 | |
|---|---|
配置目录(settings.json、presets.json、widgets.json、termthemes.json、connections.json) | macOS、Linux、以及 Windows 上均为 ~/.config/termia/ |
| 数据目录(数据库、日志、Vaults 同步状态) | macOS:~/Library/Application Support/termia/;Linux:~/.local/share/termia/(或 $XDG_DATA_HOME/termia);Windows:%LOCALAPPDATA%\termia\Data |
配置目录刻意没有采用各平台约定的 Application Support / %APPDATA% 位置——Termia 把配置目录
当作一个你会去编辑、纳入版本管理的点目录,在每个操作系统上都保持一致。它按下面的顺序解析:
- 如果
~/.termia存在且其中有wave.lock文件(pre-v0.9 的合并安装形态),配置目录改为~/.termia/config。 - 否则看环境变量
TERMIA_CONFIG_HOME,如果设置了就用它。 - 否则看
XDG_CONFIG_HOME,如果设置了就用XDG_CONFIG_HOME/termia。 - 否则用
~/.config/termia。
settings.json 直接放在这个目录下:默认就是 ~/.config/termia/settings.json。如果文件或目录
还不存在,Termia 会在第一次写入时自动创建。
编辑设置

在应用内
通过标签栏头像、齿轮或应用菜单打开设置。当前使用分组侧栏:基础(通用、外观、终端、窗口)、能力(网页、AI、同步)与系统(安全、隐私、更新、高级、关于)。账号与资料同步位于同步页;语言在通用页,快捷键在终端页。**AI → 管理 Provider 与模型…**打开 TT Agent 的 Provider/BYOK 管理;安全 → 主机密码安全显示本地主密钥与迁移状态。
界面覆盖常用偏好与能力设置;其余高级选项可以通过 JSON 配置。每项注明生效范围:部分立即更新,部分只用于下次创建的终端或需要重启,不能把所有设置都视为即时生效。参见当前功能、快捷键与凭据/同步。
手动编辑
在任意终端 Block 里运行下面的命令,会在 Termia 内置编辑器里打开 settings.json:
wsh editconfig
传入不同的文件名(presets.json、widgets.json、termthemes.json、connections.json)就能
用同样的方式编辑其他配置文件。你也可以直接用任意外部文本编辑器打开它——就是普通 JSON。
不想打开编辑器的话,也可以直接设置某个键:
wsh setconfig term:fontsize=14
wsh setconfig 会对照下面的 schema 校验键名和值的类型,未知键或类型不对的值会被拒绝。
让密钥不落在文件里
任意配置文件里的任意字符串值,都可以用 $ENV:VARIABLE_NAME 或
$ENV:VARIABLE_NAME:fallback 的写法引用环境变量,而不是写字面值:
{
"web:defaulturl": "$ENV:TERMIA_HOMEPAGE:https://github.com/open-fusion/termia"
}
如果对应的环境变量没有设置,就使用给出的 fallback;如果连 fallback 都没给,就解析为空字符串。
覆盖优先级
很多 term:* 键、以及少数其他键可以在不止一个层级设置。Block 读取这类键时,Termia 按下面的
顺序解析,命中第一个有值的层级就停止:
- Block 元数据——用
wsh setmeta设置在单个 Block 上,例如wsh setmeta this term:theme=default-light,只对这一个 Block 生效。 - 连接配置——在
connections.json里按连接单独设置(参见 Connections)。 目前只有少数几个键同时也声明在连接对象上:term:fontsize、term:fontfamily、term:theme、conn:wshenabled、conn:askbeforewshinstall。其余的键会直接跳过这一层。 - 全局 settings.json——即下面的表格。在没有更具体设置的地方生效。
还有一个独立的机制可以一次性清空整个命名空间:在一次更新里把 <prefix>:* 键(app:*、
ai:*、term:*、web:*、blockheader:*、autoupdate:*、widget:*、window:*、
telemetry:*、conn:*、vaultmemory:*)设为 true,会先清掉该前缀下所有已有的键,再应用
更新里剩下的部分。应用预设时能保证是"干净地套用"而不是叠加在旧键上,靠的就是
这个机制;你通常不需要手写它。
设置参考
下面的表格按前缀分组列出了设置 schema 里声明的每一个键,分组顺序与底层 Go 结构体里字段出现的 顺序一致。"默认值"留空表示 Termia 不下发默认值,功能会退回到"描述"列里说明的硬编码默认行为。
同一个 schema 里还有一小撮键(native:startpage、native:autoreconnect、native:keymap、
native:newtablayout、termia:termtheme、termia:singlepaneheader、term:macosoptionasalt)
只被独立的 macOS 原生客户端读取,这个应用不读——参见 macOS 设置。下面的
表格里不再列出它们。
termia:* —— 产品身份
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
termia:sku | string | saas | 产品 SKU(saas 或 enterprise),决定走哪一套登录/计费流程和初始化向导。首次启动时从构建期的 TERMIA_SKU 写入一次;手动改它不会让一个按另一种 SKU 编译出来的安装包"变身"。 |
termia:centerurl | string | (无) | Termia Center 网关的基础地址。relay、center API、Supabase 鉴权都通过路径前缀经它转发。首次启动时从构建期的 TERMIA_CENTER_URL 写入一次,或者由企业版初始化向导写入。 |
termia:theme | string(system|light|dark) | dark | 应用整体主题。从 Settings → Appearance 设置。 |
termia:lang | string | (无) | 界面语言(如 en、zh-CN)。从 Settings → Language 设置;会立刻广播到所有已打开的 tab。 |
app:* —— 窗口外观与全局热键
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
app:* | bool | app: 命名空间的整体重置开关——参见覆盖优先级。 | |
app:globalhotkey | string | (无) | 一个系统级快捷键,即使 Termia 未获得焦点也生效,用来把最近使用的 Termia 窗口带到前台(没有窗口就新建一个)。键名之间用 : 连接,例如 Ctrl:Option:e。允许的键名见下方的全局热键可用键名。 |
app:dismissarchitecturewarning | bool | false | 关闭"Termia 正在 ARM64 转译模式下运行"(例如 Apple Silicon 上跑了 Intel 版本)这一启动警告。 |
app:defaultnewblock | string | term | 新建 Block 时用的视图:term 为终端,launcher 为启动器 Block;其他值一律回退到 term。 |
app:showoverlayblocknums | bool | true | 按住 Block 编号修饰键时,是否在每个 Block 上显示编号浮层。 |
app:dismissedhints | string | (无) | 逗号分隔的一次性提示条 id 列表,记录已关闭的提示。schema 里已声明,但当前版本还没有接到任何可见的提示条上。 |
ai:* —— Termia Agent 凭据(大多已是遗留字段)
这一组里绝大部分键都是从已移除的 AI 聊天视图继承下来的 schema,现在没有任何代码再读取它们。
如今的模型选择在 Settings → AI 里完成(一个综合 relay 与 BYOK 提供方的选择器),
而不是通过某个 ai:preset 的值——参见 Termia Agent。这组里只有
ai:apikey 还在起作用。
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
ai:* | bool | ai: 命名空间的整体重置开关——参见覆盖优先级。 | |
ai:apikey | string | (无) | 已登录的 Termia Agent 用来调用 relay 的网关凭据。由登录/退出登录流程自动写入和清空;支持 $ENV: 解析,但不建议手动编辑。 |
ai:relayurl | string | (无) | 遗留的 relay 地址字段。每次登录都会被清空——relay 地址现在从 termia:centerurl 派生。wsh setconfig 仍然会监听这个键的变化,并在它变化时重新同步(清空后的)relay bundle。 |
ai:relaybundle | string | (无) | 遗留字段,曾经存放一份 JSON 格式的 relay 下发凭据包,会被同步进环境变量 vaults。和 ai:relayurl 一样,每次登录都会被清空。 |
ai:centerurl | string | (无) | 遗留的按预设区分的 center 地址。退出登录时会被清空;已被顶层的 termia:centerurl 取代。 |
ai:preset | string | ai@global | 遗留字段:聊天 Block 默认使用哪个 ai@ 预设。现在已经不再内置任何 ai@ 预设,也没有代码读取这个键。 |
ai:apitype | string | (无) | 遗留的聊天服务商类型(open_ai、azure、anthropic、perplexity)。未使用。 |
ai:baseurl | string | (无) | 已移除聊天视图遗留的 OpenAI 兼容 Base URL。未使用。 |
ai:apitoken | string | (无) | 已移除聊天视图遗留的字面 API token。未使用——注意不要和仍在生效的 ai:apikey 搞混。 |
ai:name | string | (无) | 遗留的聊天服务商显示名称。未使用。 |
ai:model | string | gpt-5-mini | 遗留的聊天模型名称。未使用。 |
ai:orgid | string | (无) | 遗留的 OpenAI 组织 id。未使用。 |
ai:apiversion | string | (无) | 遗留的 Azure API 版本号。未使用。 |
ai:maxtokens | float | 4000 | 已移除聊天视图遗留的最大 token 数设置。未使用。 |
ai:timeoutms | float | 60000 | 已移除聊天视图遗留的请求超时设置。未使用。 |
ai:proxyurl | string | (无) | 遗留的 AI 请求 HTTP 代理地址。未使用。 |
ai:fontsize | float | (无) | 遗留的聊天正文字号。未使用。 |
ai:fixedfontsize | float | (无) | 遗留的聊天代码块字号。未使用。 |
term:* —— 终端 Block
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
term:* | bool | term: 命名空间的整体重置开关——参见覆盖优先级。 | |
term:fontsize | float | (无) | 终端字号(点)。也可以按连接、按 Block 单独设置。 |
term:fontfamily | string | (无) | 终端字体族。也可以按连接、按 Block 单独设置。 |
term:theme | string | (无) | termthemes.json 里某个主题的 id(参见 Customization)。不设置时,终端会自动跟随应用的亮/暗模式(default-light / default-dark)。也可以按连接、按 Block 单独设置。 |
term:disablewebgl | bool | false | 关闭 WebGL 渲染器,回退到 canvas 渲染。 |
term:localshellpath | string | (无) | 覆盖新建本地终端时使用的 shell 可执行文件路径。 |
term:localshellopts | string[] | (无) | 传给 term:localshellpath(或默认 shell)的额外参数,例如 PowerShell 用 ["-NoLogo"]。 |
term:scrollback | int | (无,代码默认 2000) | 终端回滚缓冲区行数,最大会被限制到 50000。 |
term:copyonselect | bool | true | 选中终端文本时自动复制到剪贴板。 |
term:transparency | float | (无,代码默认 0.5) | 终端背景透明度,0(不透明)到 1(完全透明)。 |
term:allowbracketedpaste | bool | false | 允许终端使用括号粘贴(bracketed paste)转义序列。 |
term:shiftenternewline | bool | false | 开启后,Shift+Enter 发送的是转义符加换行(\n)而不是普通回车——对 TT Agent 等把这个序列当作"插入换行、不要提交"的工具很有用。 |
term:showagentscenario | bool | false | 在全新的终端 Block 上,首次显示"启动一个 Agent"入口(以及悬浮按钮),提示你启动 Termia Agent 而不是普通 shell。 |
term:confirmcloserunning | bool | true | schema 里声明了默认值,但当前应用的关闭确认逻辑并没有读取这个键(关闭正在运行 Termia Agent 或检测到 TUI 的 Block 时总会弹确认,与这个键无关)。 |
editor:* —— 代码编辑器 Block
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
editor:minimapenabled | bool | true | 在代码编辑器 Block 里显示 Monaco 小地图。也可以按 Block 单独设置。 |
editor:stickyscrollenabled | bool | false | 滚动时把当前所在的类/函数标题固定在顶部。也可以按 Block 单独设置。 |
editor:wordwrap | bool | false | 长行自动换行,而不是横向滚动。也可以按 Block 单独设置。 |
editor:fontsize | float | (无) | 代码编辑器字号(点),会被限制在 6–64 之间。也可以按 Block 单独设置。 |
web:* —— 网页 Block
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
web:* | bool | web: 命名空间的整体重置开关——参见覆盖优先级。 | |
web:openlinksinternally | bool | false | 在网页 Block 内点击的链接直接在 Termia 里打开,而不是跳到系统浏览器。 |
web:defaulturl | string | https://github.com/open-fusion/termia | 网页 Block 没有指定 URL 时显示的主页。 |
web:defaultsearch | string | https://www.google.com/search?q={query} | 在网页 Block 地址栏直接输入搜索词时使用的搜索模板;其中的 `{query}` 会被替换成搜索内容。 |
blockheader:* —— Block 标题栏
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
blockheader:* | bool | blockheader: 命名空间的整体重置开关——参见覆盖优先级。 | |
blockheader:showblockids | bool | false | 在每个 Block 的标题栏上显示其 id 的前 8 位,方便用 wsh 针对某个 Block 写脚本时引用。 |
autoupdate:* —— 应用自动更新(均需重启生效)
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
autoupdate:* | bool | autoupdate: 命名空间的整体重置开关——参见覆盖优先级。 | |
autoupdate:enabled | bool | false | 开启后台更新检查。 |
autoupdate:intervalms | float | 3600000 | 两次更新检查之间的间隔,毫秒。 |
autoupdate:installonquit | bool | true | 下次退出应用时,自动安装已下载好的更新。 |
autoupdate:channel | string | (无) | 跟踪的更新渠道。 |
markdown:* —— Markdown 预览
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
markdown:fontsize | float | (无) | 预览 Block 渲染 Markdown 时正文的字号。也可以按 Block 单独设置。 |
markdown:fixedfontsize | float | (无) | 预览 Block 渲染 Markdown 时代码块的字号。也可以按 Block 单独设置。 |
preview:* —— 文件预览 Block
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
preview:showhiddenfiles | bool | (无,代码默认 true) | 在目录预览里显示隐藏文件(点文件)。 |
tab:* —— 新 tab 默认值
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
tab:preset | string | (无) | 自动套用到新 tab 上的 bg@ 预设 id(参见 Presets),例如 bg@green。 |
style:* —— 外观记忆
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
style:lastlighttheme | string | (无) | 上一次在亮色模式下选用的整体主题;切回亮色模式时会自动恢复。 |
style:lastdarktheme | string | (无) | 上一次在暗色模式下选用的整体主题。 |
style:transparency | float | (无) | Block 与窗口外观的全局透明度(0–1)。不设置时跟随当前亮/暗主题自身的默认值。 |
style:backgroundblurpx | int | (无) | Block 与窗口外观的全局背景模糊,单位 CSS 像素。 |
widget:* —— 右侧 widget 栏
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
widget:* | bool | widget: 命名空间的整体重置开关——参见覆盖优先级。 | |
widget:showhelp | bool | (无) | 在 widget 栏里显示帮助/提示条目。 |
window:* —— 窗口外观(大多数需要重启生效)
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
window:* | bool | window: 命名空间的整体重置开关——参见覆盖优先级。 | |
window:transparent | bool | false | 让窗口背景透明。不能和 window:blur 同时使用。需要重启。 |
window:blur | bool | false | 给窗口背景加毛玻璃模糊。不能和 window:transparent 同时使用;如果 window:transparent 已经开启,这个键会被忽略。需要重启。 |
window:opacity | float | (无,代码默认 0.8) | 开启 window:transparent 或 window:blur 时的窗口不透明度(0–1)。 |
window:bgcolor | string | (无) | 窗口的基础背景色(十六进制),配合 window:transparent/window:blur 使用。 |
window:reducedmotion | bool | false | 关闭大部分动画,在跟随操作系统的"减弱动态效果"设置之外再加一层开关。 |
window:tilegapsize | int | 3 | 平铺 Block 之间的间距,单位 CSS 像素。 |
window:showmenubar | bool | false | 使用操作系统原生菜单栏,而不是浮层菜单(Windows/Linux)。需要重启。 |
window:nativetitlebar | bool | true | 使用操作系统原生标题栏,而不是 Termia 的浮层标题栏。需要重启。 |
window:disablehardwareacceleration | bool | false | 关闭 Chromium 的 GPU 加速,用来规避某些图形花屏问题。需要重启。 |
window:maxtabcachesize | int | 10 | 常驻内存以便瞬间切换的 tab 数量上限。需要重启。 |
window:magnifiedblockopacity | float | 0.6 | 放大(聚焦)某个 Block 时,背后遮罩的不透明度。 |
window:magnifiedblocksize | float | 0.9 | 放大的 Block 相对其所在布局的尺寸占比。 |
window:magnifiedblockblurprimarypx | int | 10 | 放大 Block 正后方的背景模糊,单位 CSS 像素。 |
window:magnifiedblockblursecondarypx | int | 2 | 某个 Block 被放大时,其余(未放大)Block 上应用的背景模糊,单位 CSS 像素。 |
window:confirmclose | bool | true | 关闭窗口前需要确认。 |
window:savelastwindow | bool | true | 下次启动 Termia 时,重新打开上一次关闭的窗口。 |
window:dimensions | string | (无) | 全新窗口(还没有保存过尺寸)的默认大小,格式为 WIDTHxHEIGHT(像素),例如 1920x1080。 |
window:zoom | float | (无) | schema 里已声明,但当前应用里没有任何代码读取这个键。 |
telemetry:* —— 遥测
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
telemetry:* | bool | telemetry: 命名空间的整体重置开关——参见覆盖优先级。 | |
telemetry:enabled | bool | false | 开启遥测。具体收集/不收集什么参见 Telemetry。 |
conn:* —— 连接默认值
这些是全局默认值;connections.json(参见 Connections)里针对某个连接
单独设置的值,会覆盖这里对该连接的取值。
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
conn:* | bool | conn: 命名空间的整体重置开关——参见覆盖优先级。 | |
conn:askbeforewshinstall | bool | true | 在新的远程连接上安装 wsh 助手前先询问。 |
conn:wshenabled | bool | true | 对没有单独覆盖这个设置的连接,启用远程 wsh 助手。 |
conn:passwordsaveenabled | bool | true | 允许保存 SSH 密码,这样重新连接时不用每次都输入。 |
conn:passwordcachetimeout | int(秒) | 2592000 | 保存的 SSH 密码在需要重新输入之前的缓存时长(默认 30 天)。 |
userconfig:* —— 设备配置同步
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
userconfig:uploadintervalms | float | 300000 | 同步开启时,本设备配置多久上传一次,毫秒。 |
userconfig:autosync | bool | false | 开启自动上传配置。 |
vaultssync: / vaultsautosync: —— Vaults 云同步
具体同步哪些内容参见 Vaults Sync and Versioning。
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
vaultssync:termiasync | bool | false | Termia 云同步 Vaults 数据的总开关。也可以从 Settings → Sync 设置。 |
vaultsautosync:enabled | bool | true | 按下面的间隔自动同步,而不是只能手动点"立即同步"。也可以从 Settings → Sync 设置。 |
vaultssync:intervalms | float | 300000 | 自动同步的间隔,毫秒。也可以从 Settings → Sync 设置。 |
vaultmemory:* —— Vaults 笔记本记忆文件
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
vaultmemory:* | bool | vaultmemory: 命名空间的整体重置开关——参见覆盖优先级。 | |
vaultmemory:enabled | bool | true | 启用 Vaults 记忆文件集成。 |
vaultmemory:basedir | string | vaultsmem | 记忆文件存放的子目录(相对于数据目录)。 |
vaultmemory:maxfilesize | int(字节) | 1048576 | 单个记忆文件的最大大小(1 MiB)。 |
vaultmemory:maxtotalsize | int(字节) | 104857600 | 所有记忆文件加起来的最大总大小(100 MiB)。 |
vaultmemory:cleanupinterval | int(秒) | 3600 | 清理过期记忆文件的间隔,秒。 |
全局热键可用键名
app:globalhotkey 里的键名用 : 连接(例如 Ctrl:Option:e,或者单独一个 F5)。支持的键名:
Ctrl、Cmd、Shift、Alt、Option、Meta、Super- 字母
a–z - 数字键
c{Digit0}到c{Digit9}(主键盘区,非小键盘) - 小键盘数字
c{Numpad0}到c{Numpad9},以及Decimal、Add、Subtract、Multiply、Divide F1–F20,以及Soft1–Soft4(对应F21–F24)Space(或者直接一个空格)Enter、Tab、CapsLock、NumLock、Backspace、Delete、InsertArrowUp、ArrowDown、ArrowLeft、ArrowRight、Home、End、PageUp、PageDown、EscAudioVolumeUp、AudioVolumeDown、AudioVolumeMuteMediaTrackNext、MediaTrackPrevious、MediaPlayPause、MediaStopPrintScreen
例如,把 F5 设为全局热键:运行 wsh setconfig app:globalhotkey=F5,然后重启 Termia。