接入应用与 Clash 类客户端

概览

Umbra 客户端在本机提供 SOCKS5 入口。应用或现有代理客户端把请求交给它，再由 Umbra 连接远端的 Umbra 服务端。规则分流、界面和系统代理可以继续由你熟悉的客户端负责；Umbra 本身不是 TUN 接口，安装二进制不会自动代理其他应用。

1. 配置并启动 Umbra

先按服务端指南准备好服务端。把匹配的身份材料填写到 client.toml；下面的占位符必须替换，不是真实凭证：

server = "198.51.100.10:443"
transport = "tcp"
public_key = "<X25519_PUBLIC_BASE64>"
short_id = "<SHORT_ID_HEX>"
server_name = "cover.example"
fingerprint = "chrome-latest"
mldsa_verify = "<MLDSA_VERIFY_BASE64>"
socks_listen = "127.0.0.1:1080"

server 是你的 Umbra 服务器地址；server_name 是与服务端一致的真实站点 SNI，不是任意填写的伪装域名。确认后运行：

umbra client -c client.toml

保留回环绑定。本地 SOCKS5 不提供密码认证，不能直接暴露到公网或不可信局域网。

2. 直接连接支持 SOCKS5 的应用

在应用的代理设置中选择 SOCKS5，地址填 127.0.0.1，端口填 1080，不填写用户名和密码。应用必须与 Umbra 运行在同一设备或同一可访问该回环入口的网络命名空间。

验证一次 HTTPS 请求时，可把下面地址替换为你要测试的站点：

curl --proxy socks5h://127.0.0.1:1080 https://example.com/

socks5h 让 curl 把目标域名交给代理处理，而不是先在本地解析。其他应用的 DNS 行为由其自身设置决定；仅配置 SOCKS5 不代表设备上的所有 DNS 查询都会经过代理。

3. 使用 Clash 类客户端保留规则

将以下节点合并进现有客户端配置的 proxies 列表，并在你使用的代理组中选择它。不要直接覆盖完整配置：

proxies:
  - name: Umbra Local
    type: socks5
    server: 127.0.0.1
    port: 1080
    udp: true

规则仍由现有客户端执行，远端连接由本地 Umbra 完成。确保远端 Umbra 服务器地址不再次被规则送回 Umbra Local，否则可能形成代理循环。具体规则、DNS 和 TUN 设置以你使用的客户端为准。

这里使用的是标准 SOCKS5 节点，不是原生 Umbra 协议支持。VLESS / VMess / Trojan 节点和订阅不能直接改一个名称就变成 Umbra 节点；连接两端都需要匹配的 Umbra 程序与身份材料。

4. 可选：TCP 使用 Vision，UDP 使用 QUIC

向已有 client.toml 合并：

transport = "tcp"
udp_transport = "quic"
mux = false

服务端同时开启 listen 和 udp_listen，防火墙允许相应 TCP 与 UDP 端口。udp: true 允许 Clash 类客户端发送 UDP 请求，不会改变 TCP 请求的传输。UDP 中继端点由 SOCKS 协商，不要求固定监听 UDP 1080。

如果 UDP 不可达，先用 TCP 验证普通应用请求。这里没有自动 QUIC 到 TCP 的故障切换，具体选择见传输模式。

验证与排查

1. 先直接用 SOCKS5 测试一个应用，再接入规则客户端，避免把规则问题误认为传输失败。
2. 对照两端的公钥、验证密钥、short ID、SNI 与服务器地址，检查系统时间和防火墙。
3. 分别验证 TCP 与 UDP；网页打开成功不代表 UDP 已经可用。
4. 一次只调整一个传输或性能选项；升级自适应 mux 时同步升级两端。

下一步

• 客户端配置字段
• 完整配置示例
• 连接故障排查