跳到主要内容

配置

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 把配置目录 当作一个你会去编辑、纳入版本管理的点目录,在每个操作系统上都保持一致。它按下面的顺序解析:

  1. 如果 ~/.termia 存在且其中有 wave.lock 文件(pre-v0.9 的合并安装形态),配置目录改为 ~/.termia/config。
  2. 否则看环境变量 TERMIA_CONFIG_HOME,如果设置了就用它。
  3. 否则看 XDG_CONFIG_HOME,如果设置了就用 XDG_CONFIG_HOME/termia。
  4. 否则用 ~/.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 按下面的 顺序解析,命中第一个有值的层级就停止:

  1. Block 元数据——用 wsh setmeta 设置在单个 Block 上,例如 wsh setmeta this term:theme=default-light,只对这一个 Block 生效。
  2. 连接配置——在 connections.json 里按连接单独设置(参见 Connections)。 目前只有少数几个键同时也声明在连接对象上:term:fontsize、term:fontfamily、term:theme、 conn:wshenabled、conn:askbeforewshinstall。其余的键会直接跳过这一层。
  3. 全局 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:skustringsaas产品 SKU(saas 或 enterprise),决定走哪一套登录/计费流程和初始化向导。首次启动时从构建期的 TERMIA_SKU 写入一次;手动改它不会让一个按另一种 SKU 编译出来的安装包"变身"。
termia:centerurlstring(无)Termia Center 网关的基础地址。relay、center API、Supabase 鉴权都通过路径前缀经它转发。首次启动时从构建期的 TERMIA_CENTER_URL 写入一次,或者由企业版初始化向导写入。
termia:themestring(system|light|dark)dark应用整体主题。从 Settings → Appearance 设置。
termia:langstring(无)界面语言(如 en、zh-CN)。从 Settings → Language 设置;会立刻广播到所有已打开的 tab。

app:* —— 窗口外观与全局热键​

键类型默认值说明
app:*boolapp: 命名空间的整体重置开关——参见覆盖优先级。
app:globalhotkeystring(无)一个系统级快捷键,即使 Termia 未获得焦点也生效,用来把最近使用的 Termia 窗口带到前台(没有窗口就新建一个)。键名之间用 : 连接,例如 Ctrl:Option:e。允许的键名见下方的全局热键可用键名。
app:dismissarchitecturewarningboolfalse关闭"Termia 正在 ARM64 转译模式下运行"(例如 Apple Silicon 上跑了 Intel 版本)这一启动警告。
app:defaultnewblockstringterm新建 Block 时用的视图:term 为终端,launcher 为启动器 Block;其他值一律回退到 term。
app:showoverlayblocknumsbooltrue按住 Block 编号修饰键时,是否在每个 Block 上显示编号浮层。
app:dismissedhintsstring(无)逗号分隔的一次性提示条 id 列表,记录已关闭的提示。schema 里已声明,但当前版本还没有接到任何可见的提示条上。

ai:* —— Termia Agent 凭据(大多已是遗留字段)​

这一组里绝大部分键都是从已移除的 AI 聊天视图继承下来的 schema,现在没有任何代码再读取它们。 如今的模型选择在 Settings → AI 里完成(一个综合 relay 与 BYOK 提供方的选择器), 而不是通过某个 ai:preset 的值——参见 Termia Agent。这组里只有 ai:apikey 还在起作用。

键类型默认值说明
ai:*boolai: 命名空间的整体重置开关——参见覆盖优先级。
ai:apikeystring(无)已登录的 Termia Agent 用来调用 relay 的网关凭据。由登录/退出登录流程自动写入和清空;支持 $ENV: 解析,但不建议手动编辑。
ai:relayurlstring(无)遗留的 relay 地址字段。每次登录都会被清空——relay 地址现在从 termia:centerurl 派生。wsh setconfig 仍然会监听这个键的变化,并在它变化时重新同步(清空后的)relay bundle。
ai:relaybundlestring(无)遗留字段,曾经存放一份 JSON 格式的 relay 下发凭据包,会被同步进环境变量 vaults。和 ai:relayurl 一样,每次登录都会被清空。
ai:centerurlstring(无)遗留的按预设区分的 center 地址。退出登录时会被清空;已被顶层的 termia:centerurl 取代。
ai:presetstringai@global遗留字段:聊天 Block 默认使用哪个 ai@ 预设。现在已经不再内置任何 ai@ 预设,也没有代码读取这个键。
ai:apitypestring(无)遗留的聊天服务商类型(open_ai、azure、anthropic、perplexity)。未使用。
ai:baseurlstring(无)已移除聊天视图遗留的 OpenAI 兼容 Base URL。未使用。
ai:apitokenstring(无)已移除聊天视图遗留的字面 API token。未使用——注意不要和仍在生效的 ai:apikey 搞混。
ai:namestring(无)遗留的聊天服务商显示名称。未使用。
ai:modelstringgpt-5-mini遗留的聊天模型名称。未使用。
ai:orgidstring(无)遗留的 OpenAI 组织 id。未使用。
ai:apiversionstring(无)遗留的 Azure API 版本号。未使用。
ai:maxtokensfloat4000已移除聊天视图遗留的最大 token 数设置。未使用。
ai:timeoutmsfloat60000已移除聊天视图遗留的请求超时设置。未使用。
ai:proxyurlstring(无)遗留的 AI 请求 HTTP 代理地址。未使用。
ai:fontsizefloat(无)遗留的聊天正文字号。未使用。
ai:fixedfontsizefloat(无)遗留的聊天代码块字号。未使用。

term:* —— 终端 Block​

键类型默认值说明
term:*boolterm: 命名空间的整体重置开关——参见覆盖优先级。
term:fontsizefloat(无)终端字号(点)。也可以按连接、按 Block 单独设置。
term:fontfamilystring(无)终端字体族。也可以按连接、按 Block 单独设置。
term:themestring(无)termthemes.json 里某个主题的 id(参见 Customization)。不设置时,终端会自动跟随应用的亮/暗模式(default-light / default-dark)。也可以按连接、按 Block 单独设置。
term:disablewebglboolfalse关闭 WebGL 渲染器,回退到 canvas 渲染。
term:localshellpathstring(无)覆盖新建本地终端时使用的 shell 可执行文件路径。
term:localshelloptsstring[](无)传给 term:localshellpath(或默认 shell)的额外参数,例如 PowerShell 用 ["-NoLogo"]。
term:scrollbackint(无,代码默认 2000)终端回滚缓冲区行数,最大会被限制到 50000。
term:copyonselectbooltrue选中终端文本时自动复制到剪贴板。
term:transparencyfloat(无,代码默认 0.5)终端背景透明度,0(不透明)到 1(完全透明)。
term:allowbracketedpasteboolfalse允许终端使用括号粘贴(bracketed paste)转义序列。
term:shiftenternewlineboolfalse开启后,Shift+Enter 发送的是转义符加换行(\n)而不是普通回车——对 TT Agent 等把这个序列当作"插入换行、不要提交"的工具很有用。
term:showagentscenarioboolfalse在全新的终端 Block 上,首次显示"启动一个 Agent"入口(以及悬浮按钮),提示你启动 Termia Agent 而不是普通 shell。
term:confirmcloserunningbooltrueschema 里声明了默认值,但当前应用的关闭确认逻辑并没有读取这个键(关闭正在运行 Termia Agent 或检测到 TUI 的 Block 时总会弹确认,与这个键无关)。

editor:* —— 代码编辑器 Block​

键类型默认值说明
editor:minimapenabledbooltrue在代码编辑器 Block 里显示 Monaco 小地图。也可以按 Block 单独设置。
editor:stickyscrollenabledboolfalse滚动时把当前所在的类/函数标题固定在顶部。也可以按 Block 单独设置。
editor:wordwrapboolfalse长行自动换行,而不是横向滚动。也可以按 Block 单独设置。
editor:fontsizefloat(无)代码编辑器字号(点),会被限制在 6–64 之间。也可以按 Block 单独设置。

web:* —— 网页 Block​

键类型默认值说明
web:*boolweb: 命名空间的整体重置开关——参见覆盖优先级。
web:openlinksinternallyboolfalse在网页 Block 内点击的链接直接在 Termia 里打开,而不是跳到系统浏览器。
web:defaulturlstringhttps://github.com/open-fusion/termia网页 Block 没有指定 URL 时显示的主页。
web:defaultsearchstringhttps://www.google.com/search?q={query}在网页 Block 地址栏直接输入搜索词时使用的搜索模板;其中的 `{query}` 会被替换成搜索内容。

blockheader:* —— Block 标题栏​

键类型默认值说明
blockheader:*boolblockheader: 命名空间的整体重置开关——参见覆盖优先级。
blockheader:showblockidsboolfalse在每个 Block 的标题栏上显示其 id 的前 8 位,方便用 wsh 针对某个 Block 写脚本时引用。

autoupdate:* —— 应用自动更新(均需重启生效)​

键类型默认值说明
autoupdate:*boolautoupdate: 命名空间的整体重置开关——参见覆盖优先级。
autoupdate:enabledboolfalse开启后台更新检查。
autoupdate:intervalmsfloat3600000两次更新检查之间的间隔,毫秒。
autoupdate:installonquitbooltrue下次退出应用时,自动安装已下载好的更新。
autoupdate:channelstring(无)跟踪的更新渠道。

markdown:* —— Markdown 预览​

键类型默认值说明
markdown:fontsizefloat(无)预览 Block 渲染 Markdown 时正文的字号。也可以按 Block 单独设置。
markdown:fixedfontsizefloat(无)预览 Block 渲染 Markdown 时代码块的字号。也可以按 Block 单独设置。

preview:* —— 文件预览 Block​

键类型默认值说明
preview:showhiddenfilesbool(无,代码默认 true)在目录预览里显示隐藏文件(点文件)。

tab:* —— 新 tab 默认值​

键类型默认值说明
tab:presetstring(无)自动套用到新 tab 上的 bg@ 预设 id(参见 Presets),例如 bg@green。

style:* —— 外观记忆​

键类型默认值说明
style:lastlightthemestring(无)上一次在亮色模式下选用的整体主题;切回亮色模式时会自动恢复。
style:lastdarkthemestring(无)上一次在暗色模式下选用的整体主题。
style:transparencyfloat(无)Block 与窗口外观的全局透明度(0–1)。不设置时跟随当前亮/暗主题自身的默认值。
style:backgroundblurpxint(无)Block 与窗口外观的全局背景模糊,单位 CSS 像素。

widget:* —— 右侧 widget 栏​

键类型默认值说明
widget:*boolwidget: 命名空间的整体重置开关——参见覆盖优先级。
widget:showhelpbool(无)在 widget 栏里显示帮助/提示条目。

window:* —— 窗口外观(大多数需要重启生效)​

键类型默认值说明
window:*boolwindow: 命名空间的整体重置开关——参见覆盖优先级。
window:transparentboolfalse让窗口背景透明。不能和 window:blur 同时使用。需要重启。
window:blurboolfalse给窗口背景加毛玻璃模糊。不能和 window:transparent 同时使用;如果 window:transparent 已经开启,这个键会被忽略。需要重启。
window:opacityfloat(无,代码默认 0.8)开启 window:transparent 或 window:blur 时的窗口不透明度(0–1)。
window:bgcolorstring(无)窗口的基础背景色(十六进制),配合 window:transparent/window:blur 使用。
window:reducedmotionboolfalse关闭大部分动画,在跟随操作系统的"减弱动态效果"设置之外再加一层开关。
window:tilegapsizeint3平铺 Block 之间的间距,单位 CSS 像素。
window:showmenubarboolfalse使用操作系统原生菜单栏,而不是浮层菜单(Windows/Linux)。需要重启。
window:nativetitlebarbooltrue使用操作系统原生标题栏,而不是 Termia 的浮层标题栏。需要重启。
window:disablehardwareaccelerationboolfalse关闭 Chromium 的 GPU 加速,用来规避某些图形花屏问题。需要重启。
window:maxtabcachesizeint10常驻内存以便瞬间切换的 tab 数量上限。需要重启。
window:magnifiedblockopacityfloat0.6放大(聚焦)某个 Block 时,背后遮罩的不透明度。
window:magnifiedblocksizefloat0.9放大的 Block 相对其所在布局的尺寸占比。
window:magnifiedblockblurprimarypxint10放大 Block 正后方的背景模糊,单位 CSS 像素。
window:magnifiedblockblursecondarypxint2某个 Block 被放大时,其余(未放大)Block 上应用的背景模糊,单位 CSS 像素。
window:confirmclosebooltrue关闭窗口前需要确认。
window:savelastwindowbooltrue下次启动 Termia 时,重新打开上一次关闭的窗口。
window:dimensionsstring(无)全新窗口(还没有保存过尺寸)的默认大小,格式为 WIDTHxHEIGHT(像素),例如 1920x1080。
window:zoomfloat(无)schema 里已声明,但当前应用里没有任何代码读取这个键。

telemetry:* —— 遥测​

键类型默认值说明
telemetry:*booltelemetry: 命名空间的整体重置开关——参见覆盖优先级。
telemetry:enabledboolfalse开启遥测。具体收集/不收集什么参见 Telemetry。

conn:* —— 连接默认值​

这些是全局默认值;connections.json(参见 Connections)里针对某个连接 单独设置的值,会覆盖这里对该连接的取值。

键类型默认值说明
conn:*boolconn: 命名空间的整体重置开关——参见覆盖优先级。
conn:askbeforewshinstallbooltrue在新的远程连接上安装 wsh 助手前先询问。
conn:wshenabledbooltrue对没有单独覆盖这个设置的连接,启用远程 wsh 助手。
conn:passwordsaveenabledbooltrue允许保存 SSH 密码,这样重新连接时不用每次都输入。
conn:passwordcachetimeoutint(秒)2592000保存的 SSH 密码在需要重新输入之前的缓存时长(默认 30 天)。

userconfig:* —— 设备配置同步​

键类型默认值说明
userconfig:uploadintervalmsfloat300000同步开启时,本设备配置多久上传一次,毫秒。
userconfig:autosyncboolfalse开启自动上传配置。

vaultssync: / vaultsautosync: —— Vaults 云同步​

具体同步哪些内容参见 Vaults Sync and Versioning。

键类型默认值说明
vaultssync:termiasyncboolfalseTermia 云同步 Vaults 数据的总开关。也可以从 Settings → Sync 设置。
vaultsautosync:enabledbooltrue按下面的间隔自动同步,而不是只能手动点"立即同步"。也可以从 Settings → Sync 设置。
vaultssync:intervalmsfloat300000自动同步的间隔,毫秒。也可以从 Settings → Sync 设置。

vaultmemory:* —— Vaults 笔记本记忆文件​

键类型默认值说明
vaultmemory:*boolvaultmemory: 命名空间的整体重置开关——参见覆盖优先级。
vaultmemory:enabledbooltrue启用 Vaults 记忆文件集成。
vaultmemory:basedirstringvaultsmem记忆文件存放的子目录(相对于数据目录)。
vaultmemory:maxfilesizeint(字节)1048576单个记忆文件的最大大小(1 MiB)。
vaultmemory:maxtotalsizeint(字节)104857600所有记忆文件加起来的最大总大小(100 MiB)。
vaultmemory:cleanupintervalint(秒)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、Insert
  • ArrowUp、ArrowDown、ArrowLeft、ArrowRight、Home、End、PageUp、PageDown、Esc
  • AudioVolumeUp、AudioVolumeDown、AudioVolumeMute
  • MediaTrackNext、MediaTrackPrevious、MediaPlayPause、MediaStop
  • PrintScreen

例如,把 F5 设为全局热键:运行 wsh setconfig app:globalhotkey=F5,然后重启 Termia。