尧图网页设计 
WezTerm SSH Domain 完整配置指南远程多路复用、本地回显与 Shell 集成【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermSSH Domain 是 WezTerm 中通过 SSH 通道连接远程 WezTerm 多路复用器multiplexer的机制也是实现跨机器共享终端会话、远程 pane/tab 管理、wezterm connect连接的核心配置对象。本文基于docs/config/lua/SshDomain.md及仓库源码config/src/ssh.rs、mux/src/ssh.rs、wezterm-client/src/domain.rs系统讲解SshDomain的全部字段、两种multiplexing模式、assume_shell远程 Shell 方言、预测性本地回显阈值以及 SSH 域与default_domain的配合用法读完即可写出可落地的远程终端连接配置。SshDomain 是什么在 WezTerm 的多路复用体系中Multiplexing 围绕multiplexing domains多路复用域展开域是一组独立的窗口与标签页集合。SSH Domain 特指经由 SSH 连接访问远程 WezTerm 多路复用器的域其中 SSH 仅作为承载通道。SshDomain是描述单个 SSH Domain 的 Lua 对象它告诉 WezTerm要连接哪台远程主机remote_address以什么身份认证username、no_agent_auth连接后如何使用远程能力multiplexing、remote_wezterm_path延迟与响应相关的行为timeout、local_echo_threshold_ms、overlay_lag_indicator。在源码层面它对应 config/src/ssh.rs 中经wezterm_dynamic派生序列化的SshDomain结构体并通过impl_lua_conversion_dynamic!宏与 Lua 配置双向转换因此你在.wezterm.lua中写下的每个字段都会被严格校验后落入该结构体。基础字段与最小可用配置SshDomain的核心字段及默认行为如下config.ssh_domains { { -- 该域的唯一名称必须与配置文件中所有类型的域含 unix/tls 域不重名 name my.server, -- 远程服务器的主机:端口 -- 可以是 DNS 名或 IP 地址末尾可带 :port remote_address 192.168.1.1, -- 是否禁用 agent 认证SSH Agent Forwarding -- 设为 true 则禁用默认 false 即启用 agent 认证 -- no_agent_auth false, -- 连接远程主机时使用的用户名 username yourusername, -- 若为 trueWeZTerm 启动时自动连接该域 -- connect_automatically true, -- 自定义读取超时时间秒默认 60 秒 -- timeout 60, -- 远程主机上 wezterm 可执行文件的路径 -- 主要用于 wezterm 未安装在 ssh 会话的 $PATH 中时 -- remote_wezterm_path /home/yourusername/bin/wezterm }, }以上注释字段均有源码佐证name字段带validate validate_domain_name校验见 config/src/ssh.rsremote_address会被 mux/src/ssh.rs 的ssh_domain_to_ssh_config()按冒号拆分为主机与端口分别写入 SSH 配置timeout的默认值由default_read_timeout()提供固定为 60 秒见 config/src/config.rs。最小配置与连接命令在docs/multiplexing.md中给出了等价的最小示例只需name、remote_address、username三项即可。配置完成后通过以下命令连接该域$ wezterm connect my.server该命令会发起 SSH 会话连接后远程拉起 wezterm 多路复用器守护进程并通过类 Unix 域套接字机制完成挂接认证阶段可能弹出交互对话框文档强烈建议使用 SSH 密钥认证。自动填充自 ~/.ssh/config自20230408-112425-69ae8472起SSH 域会自动从~/.ssh/config填充每个主机都会生成普通 SSH 域前缀SSH:与多路复用 SSH 域前缀SSHMUX:各一个。例如$ wezterm connect SSHMUX:my.server # 或在已有 WezTerm GUI 实例的新标签页中创建 $ wezterm cli spawn --domain-name SSHMUX:my.server该行为由SshDomain::default_domains()实现它读取~/.ssh/config并enumerate_hosts()逐个生成SSH:{host}multiplexing None与SSHMUX:{host}multiplexing WezTerm两类域见 config/src/ssh.rs。若需自定义该逻辑可参考 wezterm.default_ssh_domains()。ssh_option向底层 SSH 配置注入参数自20220101-133340-7edc5b5a起SshDomain支持通过ssh_option表直接覆写底层 SSH 配置项config.ssh_domains { { name my.server, remote_address 192.168.1.1, ssh_option { identityfile /path/to/id_rsa, }, }, }从实现看ssh_option是HashMapString, String见 config/src/ssh.rsssh_domain_to_ssh_config()会先解析~/.ssh/config再逐个将表项写入最终生效的配置 Map因此可以用它覆盖 ssh 配置文件中的任意选项。该函数还揭示了其他字段的底层映射关系remote_address中的:port→port配置项username→user配置项no_agent_auth true→ 写入identitiesonly yes禁用 agent 认证的底层实现ssh_backend→ 写入wezterm_ssh_backend ssh2 | libssh支持SshBackend::Ssh2与SshBackend::LibSsh两种后端默认LibSsh。config.ssh_domains { { name my.server, remote_address 192.168.1.1, -- 显式指定底层 SSH 后端Ssh2 或 LibSsh ssh_backend Ssh2, }, }multiplexing复用模式与免安装直连模式自20220319-142410-0fcdea07起可通过multiplexing指定 SSH 域的多路复用类型可选值在SshMultiplexing枚举中定义见 config/src/ssh.rsWezTerm默认使用 WezTerm 自己的多路复用客户端。此模式要求远程服务器上安装有 WezTerm连接后可获得与本地一致的标签、分屏与回滚体验。None不使用任何多路复用仅是一条与wezterm ssh机制相同的 SSH 连接断连即丢失全部 pane/tab。此模式不要求远程安装 WezTerm特别适合与 default_domain 配合让 SSH 自动连接进入如本地 WSL 实例等场景。assume_shell让远程 Shell 集成生效当multiplexing None时配合assume_shell选项可让 WezTerm 假定远程主机使用的 Shell 命令语言方言从而在新建 pane/tab 时尊重远程主机上由 Shell IntegrationOSC 7设置的工作目录。可选值定义于Shell枚举Unknown默认不假定远程 Shell无法做任何假设。Posix远程为 POSIX/Bourne Shell 兼容环境支持env -c DIR ENV1VAL1 ENV2VAL2 CMD与env -c DIR ENV1VAL1 ENV2VAL2 $SHELL语法。完整的组合示例配合default_prog与default_domainconfig.ssh_domains { { name my.server, remote_address 192.168.1.1, multiplexing None, -- 当 multiplexing None 时default_prog 用于指定 -- 新标签页/分屏中的默认程序。 -- 注意由于 ssh 的工作方式无法直接指定 default_cwd -- 但可以改变 default_prog 来进入特定目录。 default_prog { fish }, -- 假定可远程使用如下语法 -- env -C /some/where $SHELL -- 即使用远程主机上的默认命令 Shell -- 使 Shell 集成尊重远程主机上的当前目录。 assume_shell Posix, }, } config.default_domain my.server从实现看assume_shell Posix会在build_command()中走build_env_command()路径见 mux/src/ssh.rs它把 pane 的环境变量、cd目录前缀与命令拼接成一行env VARx CMD形式的远程命令若命令是默认程序还会借助perl/exec -a等可移植手段以 login shell 方式启动$SHELL从而保证远程目录感知正常工作。预测性本地回显local_echo_threshold_mslocal_echo_threshold_ms用于设置启用预测性本地回显predictive local echo的往返延迟阈值当 WeZTerm 客户端与服务器之间测得的往返延迟超过该阈值时客户端会尝试预测服务器对按键事件的响应并不等待服务器确认就在本地回显预测结果从而对用户隐藏高延迟。该选项仅适用于multiplexing WezTerm。config.ssh_domains { { name my.server, remote_address 192.168.1.1, local_echo_threshold_ms 10, }, }单位是毫秒默认值为Some(100)即 100ms见 config/src/config.rs 的default_local_echo_threshold_ms()。从源码看该阈值在客户端完成域挂接时被读取并注入ClientInner见 wezterm-client/src/domain.rs 的finish_attach()与local_echo_threshold_ms()方法Unreal/TLS/SSH 三类客户端域共用同一套阈值机制。延迟指示器overlay_lag_indicator 与状态栏方案自20221119-145034-49b9839f起延迟指示器lag indicator默认禁用。官方推荐将延迟信息显示在状态栏中可参考 get_metadata 中的示例——利用is_tardy与since_last_response_ms字段在update-status事件中渲染local wezterm require wezterm wezterm.on(update-status, function(window, pane) local meta pane:get_metadata() or {} if meta.is_tardy then local secs meta.since_last_response_ms / 1000.0 window:set_right_status(string.format(tardy: %5.1fs⏳, secs)) end end) return {}其中is_tardy仅在多路复用客户端 pane 中填充表示 WeZTerm 正在等待服务器响应since_last_response_ms表示距最近一次服务器响应经过的毫秒数。如果你仍希望把延迟信息叠加在内容区域上可设置config.ssh_domains { { name my.server, remote_address 192.168.1.1, overlay_lag_indicator true, }, }但请注意文档明确表示作者计划在将来移除overlay_lag_indicator功能因此新配置应优先采用状态栏方案。该字段同样在finish_attach()时随阈值一并注入客户端见 wezterm-client/src/domain.rs。字段速查表字段类型/取值默认值说明name字符串必填域名须在所有类型域中唯一remote_address字符串必填主机名/IP可带:portusername字符串无远程认证用户名映射为 SSHuserno_agent_auth布尔false禁用 agent 认证映射为identitiesonlyyesconnect_automatically布尔false启动时自动连接该域timeout秒60读取超时时间remote_wezterm_path字符串无远程 wezterm 可执行文件路径override_proxy_command字符串无完全覆写wezterm cli proxy调用ssh_backendSsh2/LibSshLibSsh底层 SSH 后端ssh_option表空覆写任意底层 SSH 配置项multiplexingWezTerm/NoneWezTerm多路复用模式default_prog字符串数组无新 pane/tab 的默认程序None模式可用assume_shellUnknown/PosixUnknown远程 Shell 方言假设local_echo_threshold_ms毫秒100启用预测性本地回显的延迟阈值overlay_lag_indicator布尔false内容区叠加延迟指示计划移除注override_proxy_command、ssh_backend等在 config/src/ssh.rs 结构体中同样存在connect_automatically在文档中提及而docs/multiplexing.md更推荐使用default_gui_startup_args { connect, my.server }方式实现启动连接因为它工作更可靠。典型落地场景场景一远程多路复用工作区远程需安装 WezTerm。配置multiplexing WezTerm默认随后用wezterm connect my.server挂接远程会话配合快捷键CTRLSHIFT2等可在域间创建新标签实现类似 tmux 的跨机持久会话。场景二SSH 直连 WSL / 免安装主机。设置multiplexing None加assume_shell Posix再通过config.default_domain my.server让 WezTerm 启动即进入该 SSH 域兼顾免装远程 wezterm 与远程目录跟随能力。场景三高延迟链路优化。在跨国或弱网环境下将local_echo_threshold_ms调低如10让本地回显尽早生效同时在状态栏用get_metadata展示since_last_response_ms以便观测链路质量。以上配置均写入用户自己的.wezterm.lua文件通常位于~/.wezterm.lua完成后重启 WezTerm 或使用配置重载即可生效。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 WezTerm SSH Domain 完整配置指南：远程多路复用、本地回显与 Shell 集成
WezTerm SSH Domain 完整配置指南远程多路复用、本地回显与 Shell 集成【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermSSH Domain 是 WezTerm 中通过 SSH 通道连接远程 WezTerm 多路复用器multiplexer的机制也是实现跨机器共享终端会话、远程 pane/tab 管理、wezterm connect连接的核心配置对象。本文基于docs/config/lua/SshDomain.md及仓库源码config/src/ssh.rs、mux/src/ssh.rs、wezterm-client/src/domain.rs系统讲解SshDomain的全部字段、两种multiplexing模式、assume_shell远程 Shell 方言、预测性本地回显阈值以及 SSH 域与default_domain的配合用法读完即可写出可落地的远程终端连接配置。SshDomain 是什么在 WezTerm 的多路复用体系中Multiplexing 围绕multiplexing domains多路复用域展开域是一组独立的窗口与标签页集合。SSH Domain 特指经由 SSH 连接访问远程 WezTerm 多路复用器的域其中 SSH 仅作为承载通道。SshDomain是描述单个 SSH Domain 的 Lua 对象它告诉 WezTerm要连接哪台远程主机remote_address以什么身份认证username、no_agent_auth连接后如何使用远程能力multiplexing、remote_wezterm_path延迟与响应相关的行为timeout、local_echo_threshold_ms、overlay_lag_indicator。在源码层面它对应 config/src/ssh.rs 中经wezterm_dynamic派生序列化的SshDomain结构体并通过impl_lua_conversion_dynamic!宏与 Lua 配置双向转换因此你在.wezterm.lua中写下的每个字段都会被严格校验后落入该结构体。基础字段与最小可用配置SshDomain的核心字段及默认行为如下config.ssh_domains { { -- 该域的唯一名称必须与配置文件中所有类型的域含 unix/tls 域不重名 name my.server, -- 远程服务器的主机:端口 -- 可以是 DNS 名或 IP 地址末尾可带 :port remote_address 192.168.1.1, -- 是否禁用 agent 认证SSH Agent Forwarding -- 设为 true 则禁用默认 false 即启用 agent 认证 -- no_agent_auth false, -- 连接远程主机时使用的用户名 username yourusername, -- 若为 trueWeZTerm 启动时自动连接该域 -- connect_automatically true, -- 自定义读取超时时间秒默认 60 秒 -- timeout 60, -- 远程主机上 wezterm 可执行文件的路径 -- 主要用于 wezterm 未安装在 ssh 会话的 $PATH 中时 -- remote_wezterm_path /home/yourusername/bin/wezterm }, }以上注释字段均有源码佐证name字段带validate validate_domain_name校验见 config/src/ssh.rsremote_address会被 mux/src/ssh.rs 的ssh_domain_to_ssh_config()按冒号拆分为主机与端口分别写入 SSH 配置timeout的默认值由default_read_timeout()提供固定为 60 秒见 config/src/config.rs。最小配置与连接命令在docs/multiplexing.md中给出了等价的最小示例只需name、remote_address、username三项即可。配置完成后通过以下命令连接该域$ wezterm connect my.server该命令会发起 SSH 会话连接后远程拉起 wezterm 多路复用器守护进程并通过类 Unix 域套接字机制完成挂接认证阶段可能弹出交互对话框文档强烈建议使用 SSH 密钥认证。自动填充自 ~/.ssh/config自20230408-112425-69ae8472起SSH 域会自动从~/.ssh/config填充每个主机都会生成普通 SSH 域前缀SSH:与多路复用 SSH 域前缀SSHMUX:各一个。例如$ wezterm connect SSHMUX:my.server # 或在已有 WezTerm GUI 实例的新标签页中创建 $ wezterm cli spawn --domain-name SSHMUX:my.server该行为由SshDomain::default_domains()实现它读取~/.ssh/config并enumerate_hosts()逐个生成SSH:{host}multiplexing None与SSHMUX:{host}multiplexing WezTerm两类域见 config/src/ssh.rs。若需自定义该逻辑可参考 wezterm.default_ssh_domains()。ssh_option向底层 SSH 配置注入参数自20220101-133340-7edc5b5a起SshDomain支持通过ssh_option表直接覆写底层 SSH 配置项config.ssh_domains { { name my.server, remote_address 192.168.1.1, ssh_option { identityfile /path/to/id_rsa, }, }, }从实现看ssh_option是HashMapString, String见 config/src/ssh.rsssh_domain_to_ssh_config()会先解析~/.ssh/config再逐个将表项写入最终生效的配置 Map因此可以用它覆盖 ssh 配置文件中的任意选项。该函数还揭示了其他字段的底层映射关系remote_address中的:port→port配置项username→user配置项no_agent_auth true→ 写入identitiesonly yes禁用 agent 认证的底层实现ssh_backend→ 写入wezterm_ssh_backend ssh2 | libssh支持SshBackend::Ssh2与SshBackend::LibSsh两种后端默认LibSsh。config.ssh_domains { { name my.server, remote_address 192.168.1.1, -- 显式指定底层 SSH 后端Ssh2 或 LibSsh ssh_backend Ssh2, }, }multiplexing复用模式与免安装直连模式自20220319-142410-0fcdea07起可通过multiplexing指定 SSH 域的多路复用类型可选值在SshMultiplexing枚举中定义见 config/src/ssh.rsWezTerm默认使用 WezTerm 自己的多路复用客户端。此模式要求远程服务器上安装有 WezTerm连接后可获得与本地一致的标签、分屏与回滚体验。None不使用任何多路复用仅是一条与wezterm ssh机制相同的 SSH 连接断连即丢失全部 pane/tab。此模式不要求远程安装 WezTerm特别适合与 default_domain 配合让 SSH 自动连接进入如本地 WSL 实例等场景。assume_shell让远程 Shell 集成生效当multiplexing None时配合assume_shell选项可让 WezTerm 假定远程主机使用的 Shell 命令语言方言从而在新建 pane/tab 时尊重远程主机上由 Shell IntegrationOSC 7设置的工作目录。可选值定义于Shell枚举Unknown默认不假定远程 Shell无法做任何假设。Posix远程为 POSIX/Bourne Shell 兼容环境支持env -c DIR ENV1VAL1 ENV2VAL2 CMD与env -c DIR ENV1VAL1 ENV2VAL2 $SHELL语法。完整的组合示例配合default_prog与default_domainconfig.ssh_domains { { name my.server, remote_address 192.168.1.1, multiplexing None, -- 当 multiplexing None 时default_prog 用于指定 -- 新标签页/分屏中的默认程序。 -- 注意由于 ssh 的工作方式无法直接指定 default_cwd -- 但可以改变 default_prog 来进入特定目录。 default_prog { fish }, -- 假定可远程使用如下语法 -- env -C /some/where $SHELL -- 即使用远程主机上的默认命令 Shell -- 使 Shell 集成尊重远程主机上的当前目录。 assume_shell Posix, }, } config.default_domain my.server从实现看assume_shell Posix会在build_command()中走build_env_command()路径见 mux/src/ssh.rs它把 pane 的环境变量、cd目录前缀与命令拼接成一行env VARx CMD形式的远程命令若命令是默认程序还会借助perl/exec -a等可移植手段以 login shell 方式启动$SHELL从而保证远程目录感知正常工作。预测性本地回显local_echo_threshold_mslocal_echo_threshold_ms用于设置启用预测性本地回显predictive local echo的往返延迟阈值当 WeZTerm 客户端与服务器之间测得的往返延迟超过该阈值时客户端会尝试预测服务器对按键事件的响应并不等待服务器确认就在本地回显预测结果从而对用户隐藏高延迟。该选项仅适用于multiplexing WezTerm。config.ssh_domains { { name my.server, remote_address 192.168.1.1, local_echo_threshold_ms 10, }, }单位是毫秒默认值为Some(100)即 100ms见 config/src/config.rs 的default_local_echo_threshold_ms()。从源码看该阈值在客户端完成域挂接时被读取并注入ClientInner见 wezterm-client/src/domain.rs 的finish_attach()与local_echo_threshold_ms()方法Unreal/TLS/SSH 三类客户端域共用同一套阈值机制。延迟指示器overlay_lag_indicator 与状态栏方案自20221119-145034-49b9839f起延迟指示器lag indicator默认禁用。官方推荐将延迟信息显示在状态栏中可参考 get_metadata 中的示例——利用is_tardy与since_last_response_ms字段在update-status事件中渲染local wezterm require wezterm wezterm.on(update-status, function(window, pane) local meta pane:get_metadata() or {} if meta.is_tardy then local secs meta.since_last_response_ms / 1000.0 window:set_right_status(string.format(tardy: %5.1fs⏳, secs)) end end) return {}其中is_tardy仅在多路复用客户端 pane 中填充表示 WeZTerm 正在等待服务器响应since_last_response_ms表示距最近一次服务器响应经过的毫秒数。如果你仍希望把延迟信息叠加在内容区域上可设置config.ssh_domains { { name my.server, remote_address 192.168.1.1, overlay_lag_indicator true, }, }但请注意文档明确表示作者计划在将来移除overlay_lag_indicator功能因此新配置应优先采用状态栏方案。该字段同样在finish_attach()时随阈值一并注入客户端见 wezterm-client/src/domain.rs。字段速查表字段类型/取值默认值说明name字符串必填域名须在所有类型域中唯一remote_address字符串必填主机名/IP可带:portusername字符串无远程认证用户名映射为 SSHuserno_agent_auth布尔false禁用 agent 认证映射为identitiesonlyyesconnect_automatically布尔false启动时自动连接该域timeout秒60读取超时时间remote_wezterm_path字符串无远程 wezterm 可执行文件路径override_proxy_command字符串无完全覆写wezterm cli proxy调用ssh_backendSsh2/LibSshLibSsh底层 SSH 后端ssh_option表空覆写任意底层 SSH 配置项multiplexingWezTerm/NoneWezTerm多路复用模式default_prog字符串数组无新 pane/tab 的默认程序None模式可用assume_shellUnknown/PosixUnknown远程 Shell 方言假设local_echo_threshold_ms毫秒100启用预测性本地回显的延迟阈值overlay_lag_indicator布尔false内容区叠加延迟指示计划移除注override_proxy_command、ssh_backend等在 config/src/ssh.rs 结构体中同样存在connect_automatically在文档中提及而docs/multiplexing.md更推荐使用default_gui_startup_args { connect, my.server }方式实现启动连接因为它工作更可靠。典型落地场景场景一远程多路复用工作区远程需安装 WezTerm。配置multiplexing WezTerm默认随后用wezterm connect my.server挂接远程会话配合快捷键CTRLSHIFT2等可在域间创建新标签实现类似 tmux 的跨机持久会话。场景二SSH 直连 WSL / 免安装主机。设置multiplexing None加assume_shell Posix再通过config.default_domain my.server让 WezTerm 启动即进入该 SSH 域兼顾免装远程 wezterm 与远程目录跟随能力。场景三高延迟链路优化。在跨国或弱网环境下将local_echo_threshold_ms调低如10让本地回显尽早生效同时在状态栏用get_metadata展示since_last_response_ms以便观测链路质量。以上配置均写入用户自己的.wezterm.lua文件通常位于~/.wezterm.lua完成后重启 WezTerm 或使用配置重载即可生效。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考