FAQ

订阅下载失败或配置无效

添加和更新订阅时，脚本先下载内容，再使用内核校验；默认在配置校验失败后尝试本地订阅转换。空响应、HTML 页面或下载失败需要先检查链接是否有效，以及订阅服务是否要求特定的 User-Agent。
查看命令报错和 clashctl sub log。若命令提示保留了调试文件，可检查 $CLASHCTL_HOME/data/last-failed.yaml 或 last-failed.raw；提交问题前请隐藏订阅链接、节点凭据等敏感信息。
可以将订阅保存为本地文件后导入，无需重新安装。相关讨论：#14

clashctl sub add --use "file:///绝对路径/config.yaml"

订阅、Mixin 和运行配置位于 $CLASHCTL_HOME/data/。自定义配置请使用 clashctl mixin -e，不要直接修改每次应用配置都会重新生成的 data/runtime.yaml。

安装完成后，需要按安装器提示在当前终端加载 Shell 配置，或重新打开终端。根据当前 Shell 执行对应命令：

仍然找不到命令时，检查安装是否完成，以及上述文件是否包含安装器写入的 CLASHCTL_HOME 和脚本加载配置。clashon 等简写命令也需要加载这些配置。

执行 clashctl status 查看内核状态，使用 clashctl sub ls 确认已启用订阅，再查看 clashctl log 中的连接错误。
clashctl on 为当前终端设置代理环境变量。浏览器或其他不读取这些变量的程序，需要单独设置代理，或按需使用 TUN。代理端口以 clashctl mixin -r 显示的运行配置为准。相关讨论：#60
主机只有 IPv6 时，确认订阅节点的地址和服务端支持 IPv6，必要时咨询订阅提供方。
Git 使用 SSH 地址且连接无响应时，可以尝试通过 HTTPS 端口建立 SSH 连接。该设置不适用于 HTTPS 仓库地址。
开启 TUN 后无法访问 Docker 容器内服务时，检查路由与 Mixin 配置。相关讨论：#53
网络波动时可重试，并在 Web 面板中切换可用节点。相关讨论：#55

ping 使用 ICMP，不经过 HTTP 或 SOCKS 代理。clashctl on 设置的代理环境变量不会使 ping 流量走代理，不能仅据此判断代理是否可用。
可以通过 clashctl tun on 启用 TUN，并用 clashctl tun 查看状态。TUN 需要相应的系统权限和设备支持；容器或受限 VPS 可能无法启用。
开启 TUN 也不保证目标响应 ping。使用 fake-IP 时，解析结果可能是虚拟地址；请结合实际网页访问、节点测试和日志判断连接是否正常。详见 Mihomo TUN 配置和 DNS 配置。

先执行 clashctl ui 获取当前面板地址。该命令会按需准备面板资源，并尝试启动内核；启动失败时请查看 clashctl status 和 clashctl log。

检查运行配置中的 external-controller 地址和端口。若只监听 127.0.0.1，其他主机无法直接访问；需要远程访问时可使用 SSH 端口转发，或调整监听地址并设置访问密钥。相关讨论：#35
远程访问时，检查云服务器安全组、系统防火墙，以及容器是否映射了实际控制端口，不要只按默认的 9090 排查。相关讨论：#51
浏览器使用代理时，为面板的内网地址设置直连规则，避免请求经远端节点转发。
面板能打开但无法连接内核时，核对控制地址、端口和密钥；使用 clashctl secret 查看当前密钥，使用 clashctl secret "新密钥" 修改。相关讨论：#40
HTTPS 面板连接 HTTP 控制接口时，浏览器可能拦截混合内容。优先使用 clashctl ui 提供的本机或内网 HTTP 地址，或为控制接口配置 HTTPS 反向代理。HTTP 访问说明、浏览器混合内容说明、HTTPS 面板讨论：#516

面板使用示例可参考讨论：#47。