Troubleshooting Guide
Relevant source files
The following files were used as context for generating this wiki page:This guide provides solutions and diagnostic steps for common issues encountered while using the Self-Rule Clash configuration. It covers problems related to basic setup, connectivity, rule application, and DNS resolution. The information herein is derived exclusively from the configuration and script files within this repository.
The primary configuration file is Clash/GeneralClashConfig.yml, which controls the core behavior of the Clash client. Rule and provider files, located in Clash/Providers/, dictate how traffic is routed. Understanding these components is key to resolving most issues.
1. Basic Configuration and Setup
Initial problems often stem from incorrect settings in Clash/GeneralClashConfig.yml. Ensure the file is placed in $HOME/.config/clash/config.yml or the directory where Clash is running.
Key Configuration Parameters
This table outlines the most important startup parameters. Incorrect values here can prevent Clash from starting or accepting connections.
| Parameter | Default Value | Description |
|---|---|---|
mixed-port | 7890 | The primary port for both HTTP and SOCKS5 proxy services. |
socks-port | 7891 | A dedicated port for SOCKS5 proxy services. |
allow-lan | true | Allows other devices on the local network to connect to the proxy. |
bind-address | * | Binds to all network interfaces when allow-lan is true. |
log-level | info | Sets the verbosity of logs. Change to debug for detailed troubleshooting. |
external-controller | 127.0.0.1:9090 | The address for the Clash RESTful API, used by dashboards. |
Sources: Clash/GeneralClashConfig.yml:6-30
If you cannot connect to the proxy from another device on your LAN, verify that allow-lan is set to true and that your firewall is not blocking the specified ports.
Logging
To diagnose complex issues, increase the log level. The default is info, but debug provides the most detailed output.
# 5 个级别：silent / error / warning / info / debug。级别越高日志输出量越大，越倾向于调试，若需要请自行开启。
log-level: info
Sources: Clash/GeneralClashConfig.yml:28-29
2. Connection and Routing Issues
If a specific website or service is not working as expected (e.g., it's slow, blocked, or not using the proxy), the cause is likely related to system proxy settings or routing rules.
System Proxy Bypass (cfw-bypass)
For Clash for Windows (CFW), the cfw-bypass list defines domains that should not go through the proxy. If a site you expect to be proxied is being bypassed, check if it matches a pattern in this list. The list is extensive and includes many common Chinese domains and services.
This diagram shows how a request is handled by CFW's system proxy.
This flowchart illustrates the decision-making process for traffic when using the system proxy feature in Clash for Windows.
Sources: Clash/GeneralClashConfig.yml:211-828
A snippet from the bypass list:
cfw-bypass:
# 直连列表
# MyList
- "*.13th.tech"
- "*.423down.com"
# ... many more entries
# CN域名直连(中国|公司|网络)
- "*.cn"
- "*.xn--fiqs8s"
# ...
# Alibaba
- "*.1688.com"
- "*.alibaba.com"
# ...
Sources: Clash/GeneralClashConfig.yml:213-400
Conversely, the UnBan.yaml provider lists domains that should explicitly not be blocked by ad-blocking rules, which can resolve issues where a necessary service (like tracking.miui.com) is inadvertently blocked.
Sources: Clash/Providers/UnBan.yaml
Connection Breaking Strategy
When switching proxies or modes, existing connections might be interrupted. The cfw-conn-break-strategy setting controls this behavior. If your downloads or streams are interrupted after a profile switch, you might adjust these settings.
| Strategy | Options | Description |
|---|---|---|
proxy | none, chain, all | none (default) doesn't break connections. all breaks all connections. |
profile | true, false | true (default) breaks connections on profile switch. |
mode | true, false | false (default) does not break connections on mode switch. |
Sources: Clash/GeneralClashConfig.yml:181-186
3. Rule and Provider Problems
The repository uses Python scripts to generate provider files from .list files. An issue with this process can lead to incorrect or outdated routing rules.
Rule Generation Flow
The update_providers.py script reads .list files from the Clash/ directory (excluding config and Providers) and converts them into .yaml provider files under Clash/Providers/.
This diagram shows the process of converting .list rule files into .yaml provider files that Clash can use.
Sources: update_providers.py:11-34
The script handles comments and specific rule types like USER-AGENT by commenting them out in the final .yaml file. If a rule seems to be ignored, check the corresponding .yaml provider file to see how it was processed.
# update_providers.py
# ...
elif line.lstrip().startswith("USER-AGENT"):
f_out.write(f" # {line.strip()}")
elif line.lstrip().startswith("URL-REGEX"):
f_out.write(f" # {line.strip()}")
# ...
else:
f_out.write(f" - {line.strip()}")
Sources: update_providers.py:27-32
A similar script, update_sing_box.py, converts .list files into the JSON format required by sing-box and then compiles them into .srs rule-sets.
Sources: update_sing_box.py:48-100
Provider Content
If a specific service (e.g., OpenAI, Wikipedia) is not being proxied correctly, examine its dedicated provider file. For example, Clash/Providers/Ruleset/AI.yaml lists domains related to AI services.
# Clash/Providers/Ruleset/AI.yaml
payload:
# 内容：内容：AI平台-国外
# 数量：39条
- DOMAIN-KEYWORD,anthropic
- DOMAIN-KEYWORD,claude
- DOMAIN-KEYWORD,openai
- DOMAIN,ai.google.dev
# ...
Sources: Clash/Providers/Ruleset/AI.yaml:1-8
The ProxyLite.yaml and ProxyGFWlist.yaml files contain large lists of domains and IP ranges that are routed through the proxy. If a foreign site is not working, it might be missing from these lists.
Sources: Clash/Providers/ProxyLite.yaml, Clash/Providers/ProxyGFWlist.yaml
4. DNS Resolution
DNS issues can cause sites to be unreachable or resolve to incorrect addresses. The GeneralClashConfig.yml file details the DNS resolution logic, although the dns section is commented out by default.
DNS Request Logic
When enabled, Clash uses a sophisticated DNS resolution strategy to balance speed and accuracy.
- A request is sent concurrently to all DNS servers in both the
nameserverandfallbacklists. - Clash prioritizes the fastest result from the
nameserverlist (typically fast, domestic DNS servers). - However, if the resolved IP address is determined to be foreign (based on GeoIP), Clash will instead use the fastest result from the
fallbacklist (typically secure, non-polluted DNS servers like DoH/DoT).
This flow is designed to provide fast resolution for domestic sites while ensuring foreign sites resolve to non-polluted IPs.
This diagram illustrates the DNS resolution logic used by Clash to select the appropriate DNS result.
Sources: Clash/GeneralClashConfig.yml:85-93
If you experience DNS-related problems, you can uncomment and customize the dns section in your configuration file. Ensure you use reliable and non-polluting servers in the fallback group for resolving foreign domains.
Sources: Clash/GeneralClashConfig.yml:45-83
5. Historical Changes
Sometimes, a recent update can introduce a problem. The Tool/New.md file contains a detailed changelog that can be useful for tracking down when a specific rule or behavior was changed. For example, if you notice an issue with ad-blocking, you can check the log for recent modifications to ad-related rules.
# 3.16
# 2017年3月16日00:01:08 81
去重
合并中国IP段
完善百度、letv、金立手机
添加UC浏览器广告过滤
添加墨迹天气，增强sohu、sougou等
添加大量广告联盟，屏蔽效果更好
添加爱奇艺广告ip段
添加起点 掌阅 书旗 app广告
Sources: Tool/New.md:4-14
This historical context can help correlate the start of an issue with a specific change in the rule set, providing a valuable clue for troubleshooting.