连接
连接是指让一个区块(block)指向本机以外的某个 shell:通过 SSH 连接远程主机,或连接本地的
WSL 发行版(仅限 Windows)。终端区块一旦连上,文件预览、系统监控组件、以及终端内的 Agent
也都可以跟着这条连接走到远程一侧——前提是远程侧的助手程序(wsh)已经在那边跑起来。
本页介绍 SSH 与 WSL 两种连接。AWS S3 连接是第三种、完全不同的连接类型——它只能用在文件预览 区块里(S3 没有 shell,跑不了终端),本页不涉及。
打开一个连接

每个终端区块的标题栏都会显示一个连接指示器(一个电脑图标 + 连接名称,本机则显示"本地")。 点击它即可打开连接切换器。
切换器是一个支持输入过滤的候选列表,分为几组:
- 本地 —— 你自己的机器,以及 Termia 找到的所有 WSL 发行版(仅限 Windows)。
- 远程 —— SSH 主机,来源是你保存在 Vaults 里的主机条目(并不是实时解析
~/.ssh/config得到的,见下文)。 - 断开连接 条目,仅当该区块当前连接处于已连接状态时出现。
- 重新连接 条目,仅当该区块当前连接处于断开或错误状态、且你还没有输入任何内容时出现。
用方向键 + Enter 选择条目,或直接输入进行过滤。Escape 会关闭切换器且不做任何改动。
在切换器里添加一个全新的 SSH 连接
如果你输入的内容在列表里找不到匹配项,切换器会提示把它创建为一个新连接——但仅当它形如
`user@203.0.113.10`(一个字面量的 IPv4 或 IPv6 地址)时才会被接受。输入一个裸主机名,
或者一个切换器尚不认识的 ~/.ssh/config 别名,都会被拒绝,提示"Invalid format. Use user@ip
(IPv4 or IPv6)."(格式无效,请使用 user@ip,IPv4 或 IPv6)。
要按主机名连接(~/.ssh/config 里的别名,或者还没保存在任何地方的主机名),请改用下面几种
方式之一——它们都接受任意主机名:
- 把这台主机保存进 Vaults——保存后它就会出现在切换器的"远程"列表里。
- 在已有的终端里运行
`wsh ssh user@host`(加上-n会打开一个新区块,而不是切换当前 区块)。 - 直接写进
connections.json——见下文的 下文的"单个连接的配置"一节——或者用`wsh conn add user@host`。
只要某台主机通过以上任意一种方式成功连接过一次,之后它就会一直出现在切换器里,因为 Termia
会把它写回 connections.json,另外还会(分开地)写进 Vaults(见下文的
密码一节)。
WSL 发行版
在 Windows 上,Termia 每次打开切换器时都会从 Windows 注册表读取已安装的 WSL 发行版列表——
无需任何配置。从"本地"分组里选一个,或者运行 `wsh wsl -d <发行版名称>`;不带 -d 时
使用你的 WSL 默认发行版。macOS 和 Linux 上不存在 WSL 支持(因为没有发行版注册表可读)。
~/.ssh/config 是怎么被读取的
一旦你连接某台主机——无论是从切换器、Vaults、wsh ssh,还是 wsh conn connect——Termia 都会
按下面这三层顺序解析连接设置(后面的层级会覆盖前面的):
- 你的
~/.ssh/config(以及/etc/ssh/ssh_config,Windows 上是%PROGRAMDATA%\ssh\ssh_config)。 - 该连接在
connections.json里的条目——前提是没有设置`conn:ignoresshconfig`(默认 如此)。如果设置了,第 1 步会被完全跳过,只使用 OpenSSH 内置默认值加上connections.json。 - 身份文件(identity file)单独处理,是叠加而非覆盖的关系——见下文的 身份认证。
解析器忽略 Match 指令,不应用对应条件配置;包含 Match 不会导致整个文件解析失败。支持 ProxyJump,但尚未实现 ProxyCommand 与面向用户的本地/远端/SOCKS 隧道管理界面。依赖这些功能的配置需要单独验证。下列支持的关键字会影响连接设置:
| 关键字 | Termia 如何处理 |
|---|---|
Host | 只有不含 *、?、! 的模式才会被列为可选连接;带通配符的模式在解析某个具体主机的取值时依然会被查阅。 |
User | 未设置时默认为你本机操作系统的用户名。 |
HostName | 未设置时默认为 Host 模式本身。 |
Port | 默认为 22。 |
IdentityFile | 可重复出现;按顺序依次尝试(见身份认证)。 |
BatchMode | yes 会关闭所有交互式提示(密码、密钥口令、键盘交互)。其它取值一律视为 no。 |
PubkeyAuthentication | 除 no 以外的取值都视为启用——包括 unbound 和 host-bound,Termia 不对它们做进一步区分。 |
PasswordAuthentication | 除 no 以外的取值都视为启用。 |
KbdInteractiveAuthentication | 除 no 以外的取值都视为启用。 |
PreferredAuthentications | 逗号分隔,决定 publickey、keyboard-interactive、password 的尝试顺序。gssapi-with-mic 和 hostbased 未实现,出现在列表里会被跳过。 |
AddKeysToAgent | 只有字面量 yes 才会把解密后的密钥加入本机 SSH agent;confirm 或时间值都按 no 处理。 |
IdentityAgent | agent socket 的路径。未设置时,Termia 读取你本机 shell 里的 $SSH_AUTH_SOCK。 |
IdentitiesOnly | yes/no;限定只使用列出的身份文件(以及 Vaults 或 connections.json 额外添加的,见下文)。 |
ProxyJump | 逗号分隔的跳板主机列表(none 表示禁用)。见跳板机。 |
UserKnownHostsFile / GlobalKnownHostsFile | 空格分隔的 known_hosts 文件列表。默认是 ~/.ssh/known_hosts ~/.ssh/known_hosts2 和 /etc/ssh/ssh_known_hosts /etc/ssh/ssh_known_hosts2。如果你是 root,只会查阅全局文件。 |
配置文件里其它关键字会被忽略,虽然解析器仍会读过它们。
身份认证

Termia 会根据 PreferredAuthentications(默认 publickey,keyboard-interactive,password)
决定要尝试哪些认证方式,上面判定为禁用的方式会被跳过。
密钥
身份文件来自四个来源,每次连接尝试时按下面的顺序依次尝试,重复项会被去重(保留第一次 出现的):
- 本机 SSH agent(
$SSH_AUTH_SOCK,或IdentityAgent指定的 socket)——agent 已经提供的每 个签名者都会最先被尝试。如果IdentitiesOnly为yes,这一步会被完全跳过。 - Vaults 中某条匹配主机条目上选定的密钥——可以是一个密钥文件路径,也可以是 保存在 Termia 自己的加密密钥库里的密钥(本次会话中第一次用到时会提示输入口令解锁)。
- 你直接在
connections.json里为该连接设置的`ssh:identityfile`。 ~/.ssh/config里的IdentityFile行(如果没有设置且开启了`conn:ignoresshconfig`,则使用 OpenSSH 的默认密钥文件名)。
每个候选密钥都是逐个尝试的——Termia 特意不会把整批密钥一次性交给 SSH 库,这样口令提示只会
针对当前正在尝试的那一个密钥出现,解析失败的密钥也只是被静默跳过,而不会中断整个尝试列表。
如果某个密钥文件需要口令,会提示你输入(除非开启了 BatchMode,这会关闭提示并跳过该密钥)。
配合 `AddKeysToAgent yes`,成功解密的密钥文件会被加入本机 agent,本次会话内不会再问。
密码
如果你输入密码完成了认证,并且连接成功,Termia 会把这个密码自动保存到 Vaults 中对应该 IP + 用户名的主机条目里。下次连接时,密码回调会先查 Vaults,静默复用已保存的密码——只有找不到匹配的已保存密码时才会再次提示你输入。这个查找是按 IP 和用户名精确匹配的,不是按 SSH 配置里的别名。
如果 agent、Vaults、配置里的密钥都没能解决认证,且密码/键盘交互认证是启用的,就会弹出对话框 提示你输入。服务器发来的键盘交互问题会逐条展示,并遵循服务器关于是否遮盖/回显每个答案的要求。
主机密钥提示
Termia 会用与 OpenSSH 相同的校验逻辑,对照你的 known_hosts 文件(按上文方式解析出的
UserKnownHostsFile / GlobalKnownHostsFile)检查主机密钥:
- 未知主机(任何地方都没有匹配条目):会向你展示密钥指纹并要求确认。确认后会把它追加到
Termia 能写入的第一个
known_hosts文件里;如果一个都不存在,则会先创建该文件(及其上级 目录)。 - 主机密钥发生变化(存在条目但对不上):连接会被直接拒绝,并给出说明涉及哪些文件和密钥
的错误信息。Termia 不提供应用内的方式来接受一个变化了的密钥——你需要像用 OpenSSH 时一样,
自己从提示的
known_hosts文件里删掉那条旧记录(或者在 Vaults 里把该主机删除再重新添加, 这会清掉该 host+port 在应用内的缓存会话)。 - 已吊销的密钥:直接拒绝,不会有任何提示。
agent 转发
Termia 没有实现 OpenSSH 那种 agent 转发(ForwardAgent)——没有选项可以把你本机的
agent socket 转发进远程会话,让那台主机用你本机的密钥再往第三台主机认证。它支持的是用本机
agent 对你正在连接的这台主机进行认证(见上文密钥),以及跳板机(见下一节)——这是
两种不同的机制。
跳板机
ProxyJump(逗号分隔的主机列表)通过 TCP 转发串联多个连接:Termia 先直接连接第一个跳板机,
然后透过这个已经建立的 SSH 连接去拨号下一跳,依此类推直到到达真正的目标主机。链条中的每一
跳都完全按该跳自己的名字从 ~/.ssh/config/connections.json 里解析设置——你为最终目标传入
的标志或关键字不会应用到中间跳板上。超过 10 跳的链条会被拒绝。
单个连接的配置(connectionsjson)
除了 ~/.ssh/config,Termia 还维护着自己的单连接配置文件 connections.json,存放在应用的
配置目录里。用下面的命令找到确切路径:
wsh wavepath config
(该目录下的 connections.json 就是这个文件)。它是一个以连接的显示名称为键的 JSON
对象——就是你输入来连接时用的那个字符串,比如 `myuser@myhost` 或
`wsl://Ubuntu`——每个键下面可以包含以下任意配置项:
| 键 | 类型 | 含义 |
|---|---|---|
conn:wshenabled | bool | 该连接是否使用远程助手(wsh)。第一次回答安装提示时会自动写入;在此之前默认沿用全局设置 conn:wshenabled(true)。 |
conn:askbeforewshinstall | bool | 是否在给该连接安装 wsh 前先询问。一旦该连接对象存在(即成功连接过一次)且这个键缺失,Termia 就会认为已经问过了,不再询问——这就是为什么版本更新后的重装是静默进行的。 |
conn:wshpath | string | 覆盖远程上 wsh 可执行文件的路径。默认为 `~/.termia/bin/wsh`。 |
conn:shellpath | string | 覆盖在远程启动的 shell。默认使用远程的 $SHELL。 |
conn:ignoresshconfig | bool | 该连接完全跳过 ~/.ssh/config;只应用 OpenSSH 内置默认值加上本文件。默认 false。 |
display:hidden | bool | 在切换器里隐藏该连接。默认 false。 |
display:order | number | 在切换器里的排序位置(升序)。默认 0。 |
term:fontsize、term:fontfamily、term:theme | number / string / string | 针对该连接的终端外观覆盖;区块级别的元数据仍然优先于这里的设置。 |
cmd:env | object | 在该连接的 shell 会话里额外注入的环境变量(需要 wsh)。 |
cmd:initscript、cmd:initscript.sh、cmd:initscript.bash、cmd:initscript.zsh、cmd:initscript.pwsh、cmd:initscript.fish | string | 一段脚本,或指向脚本的路径,在 wsh 初始化会话时运行一次。匹配度最高(最贴近具体 shell)的那一个生效(需要 wsh)。 |
ssh:user、ssh:hostname、ssh:port | string | 覆盖 ~/.ssh/config 里对应的取值;如果开启了 conn:ignoresshconfig,则直接以此为准。 |
ssh:identityfile | string[] | 额外的身份文件,会先于 ~/.ssh/config 里的被尝试。成功连接时用 `wsh ssh -i <文件>` 会自动追加到这里。 |
ssh:identitiesonly、ssh:batchmode、ssh:pubkeyauthentication、ssh:passwordauthentication、ssh:kbdinteractiveauthentication、ssh:addkeystoagent | bool | 含义与 ~/.ssh/config 里对应的关键字相同。 |
ssh:preferredauthentications | string[] | 含义与 PreferredAuthentications 相同。 |
ssh:identityagent | string | 含义与 IdentityAgent 相同。 |
ssh:proxyjump | string[] | 含义与 ProxyJump 相同。 |
ssh:userknownhostsfile、ssh:globalknownhostsfile | string[] | 含义与 ~/.ssh/config 里对应的关键字相同。 |
举例——隐藏一个你只用来做 Git 操作的连接,并给另一个连接单独设置主题:
{
"git@github.com": {
"display:hidden": true
},
"myuser@myhost": {
"term:theme": "warmyellow",
"term:fontsize": 16
}
}
也可以不手动改文件,用命令行管理单个字段——见 wsh conn 参考里
的 add / set / rm。
远程一侧会安装什么(~/.termia)
当某个连接启用了 wsh(默认启用;下面会说明何时会先询问),一次成功的连接会在远程主机的
家目录下做以下这些事:
- 探测远程的操作系统/架构(
uname -sm),并通过同一条 SSH/WSL 会话把匹配的wsh可执行 文件拷贝到`~/.termia/bin/wsh`(不会另开一条文件传输通道)。 - 在远程用同一条会话启动
`wsh connserver`,并打开一个 Unix domain socket(SSH 场景: 一个通过 SSH 转发的 Unix socket;WSL 场景:`~/.termia/wave-remote.sock`),把 RPC 连接带回你本机的 Termia。 - 为找到的每种 shell 写入 shell 集成文件,放在
`~/.termia/shell/{zsh,bash,fish,pwsh}`下,另外还有配套状态放在`~/.termia/shell-cwd`和`~/.termia/env-updates`里。这些文件让远程 shell 能把 当前目录汇报回文件预览/文件组件,并在重新连接时恢复。 - 把
`~/.termia/bin`加入该会话的PATH,并注入若干环境变量 (TERM_PROGRAM=termia、TERMIA=1、TERMIA_BLOCKID、TERMIA_CLIENTID、TERMIA_CONN、TERMIA_TABID、TERMIA_VERSION、TERMIA_WORKSPACEID),以及connections.json里配置的`cmd:env`和`cmd:initscript*`。
shell 集成只支持 bash、zsh、fish、pwsh 这四种。如果远程的默认 shell 不是这几种之一,
该会话就会跳过集成;你可以把 `conn:shellpath` 指向其中一种受支持的 shell 来解决。
如果上述任何一步失败,Termia 会退回到不带 wsh 的纯 SSH/WSL 会话——终端本身仍然可用,但
文件预览、系统监控组件和远程 Agent 在这条连接修好之前都不可用。
首次安装提示
第一次连接某台主机时,如果 conn:wshenabled 为真、且这台连接还没有记录过
conn:askbeforewshinstall(两者默认都是这样),系统会先询问你是否确认安装,并提供一个"以后
不再询问"的选项。你的回答会写回 connections.json 的 conn:wshenabled 字段,因此:
- 如果拒绝,这条连接就再也不会安装
wsh(也不会再问),除非你自己把conn:wshenabled改回true。 - 如果接受,
wsh会被安装;连接对象由此产生,之后每次重连(以及每次版本更新,见下文)都会 静默完成,不会再有任何提示。
让远程助手保持最新
每次连接(以及重新连接)都会先在远程执行 `wsh version`。Termia 用 semver 规则把这个
版本号与本机应用自身的版本比较:
- 远程版本比本机应用旧 ——
wsh和它的 shell 集成文件会被自动重新推送,不会有任何提示 (见上面的规则)。此时区块里会出现一小段"正在传输 wsh…" / "正在安装 shell 脚本…"的进度条。 - 远程版本等于或比本机新 —— 保持不动。Termia 不会把远程的
wsh降级。 - 远程报告"未安装" —— 按"版本过旧"同样处理:走完整安装流程。
不管版本如何,你都可以强制来一次全新安装——比如远程的可执行文件损坏了,或者你改了
conn:wshpath:
wsh conn reinstall <connection>
或者在终端区块里,点击连接指示器旁边那个在 wsh 未能正常起来时出现的"眼睛划掉"/"Wsh 未安装"
图标;点击它会重新启用 conn:wshenabled,按需连接,重装,然后重新连接。
连接状态与错误
连接指示器的颜色和区块的状态浮层会反映连接的当前状态:
- 连接中 —— SSH/WSL 握手以及(如果启用)
wsh安装正在进行时,会显示一个动态指示器。 - 已连接 —— 正常状态;指示器使用一组循环颜色中的一种,每个活跃连接对应一种颜色,方便你 一眼分辨出哪些区块连的是不同主机。
- 已断开 —— 干净关闭后的状态,区块里会出现"重新连接"操作。
- 错误 —— SSH/WSL 连接本身失败了(认证、网络、主机密钥等)。区块里会显示错误文本,带一个 复制按钮,以及一个可重试的"重新连接"操作。
除此之外,一个连接也可能处于已连接但没有 wsh 的状态——终端能用,但横幅会说明远程助手为
什么起不来,具体原因会被归纳成几种提示之一:远程磁盘已满、安装目录不可写、远程文件系统只读、
或者远程操作系统/架构不受支持。横幅上的一个按钮可以让你彻底为该连接关闭 wsh(会把
`conn:wshenabled: false` 写进 connections.json),如果你不想解决根本问题、只想不再看
到这个警告的话;另一个按钮则只是把当前这次错误提示关掉,不改动配置。
调试一个连接
区块的齿轮菜单里有一个"调试连接"子菜单(关闭 / 信息 / 详细)。打开它之后,SSH/WSL 握手、
密钥尝试过程、以及 wsh 的安装步骤都会在该终端区块(重新)连接时直接打印出来——这是查看到底
在尝试哪个身份文件或认证方式最快的办法。完整的守护进程日志随时可以查看:
wsh wavepath log --tail # 最后 100 行
wsh wavepath log -o # 在新区块里打开
断开与重新连接
关闭一个连接(切换器里的"断开连接"条目、`wsh conn disconnect`,或者远程那端主动断开
会话)会拆除 SSH 客户端或 WSL 命令、domain socket,以及远程的 connserver 进程。只有切换器
的"断开连接"条目会同时把该区块切回你的本地 shell(ConnDisconnectCommand 本身从不改动某个
区块指向的连接)。
一次意外掉线——网络抖动、远程重启、笔记本被系统挂起——会被当作"已断开"处理,而不是"错误",
所以区块只会显示重新连接的操作,而不是吓人的错误状态。重新连接会把整个流程从头跑一遍:
SSH/WSL 握手、认证、主机密钥检查,以及上面那套按版本决定是否更新 wsh 的检查——不会假定
上一次会话里的任何东西仍然有效。
如果同一个标签页里有几个终端区块是作为一个同步分组一起打开的,通过切换器改变其中一个区块的 连接会自动把新连接带给分组里的其它区块;单独断开或重新连接某一个区块则不会。