مرجع خطاهای پیکربندی Clash — اشتباه‌های رایج YAML و پیام‌های خطای هسته

پیکربندی ویرایش‌شده را ذخیره می‌کنید، کلاینت یک خط انگلیسی نشان می‌دهد و همین. این نوشته خطاهای رایج را به یک مرجع تبدیل می‌کند.

اول یک بررسی پیکربندی اجرا کنید

بعد از ویرایش و پیش از وارد کردن، بگذارید هسته اعتبارسنجی کند:

mihomo -t -d /path/to/config/dir

سوییچ -t حالت آزمون است: بررسی می‌کند بدون اجرا. پیام‌هایش خیلی از پنجرهٔ کلاینت مفصل‌تر است و معمولاً مستقیم می‌گوید کدام خط ایراد دارد.

کاربران Clash Verge می‌توانند این دستور را روی config.yaml در پوشهٔ پیکربندی اجرا کنند. آن پوشه کجاست:

۱. خطاهای نحوی YAML

این‌ها در مرحلهٔ تجزیه می‌افتند و پیام معمولاً شمارهٔ خط دارد.

found character that cannot start any token

علت: برای تورفتگی از تب استفاده شده. YAML فقط فاصله می‌پذیرد.

پیدا کردنش: در ویرایشگر «نمایش نویسه‌های سفید» را روشن کنید؛ تب‌ها به شکل پیکان دیده می‌شوند.

راه‌حل: همه را با فاصله جایگزین کنید. در VS Code، Ctrl+Shift+P ← «Convert Indentation to Spaces».

mapping values are not allowed in this context

علت: بعد از دونقطه فاصله نیست، یا داخل مقدار دونقطهٔ بی‌گیومه هست.

# غلط
port:7890
name: HK: 01

# درست
port: 7890
name: "HK: 01"

did not find expected key / could not find expected ':'

علت: تورفتگی ناهماهنگ.

# غلط: دو کلید با تورفتگی متفاوت
proxies:
  - name: "A"
    type: trojan
     server: a.com      # ← یک فاصلهٔ اضافه

# درست
proxies:
  - name: "A"
    type: trojan
    server: a.com

found unexpected end of stream

علت: گیومهٔ بسته‌نشده، یا فایل بریده.

بررسی کنید هر گیومه جفت داشته باشد؛ اگر پیکربندی دانلود شده، ممکن است کامل نیامده باشد.

نویسه‌های ویژه در رمز

# خطرناک: نویسهٔ # توضیح شروع می‌کند و @ و : هم می‌توانند دردسر بسازند
password: p@ss#word

# درست
password: "p@ss#word"

۲. خطاهای فیلد و ساختار

نحو سالم است، ولی هسته آنچه نوشته‌اید را نمی‌شناسد.

unmarshal error / cannot unmarshal !!str into int

علت: نوع اشتباه، مثلاً پورتی که به‌صورت رشته نوشته شده.

# غلط
port: "443"      # بعضی فیلدها صریحاً عدد می‌خواهند

# درست
port: 443

برعکسش، UUID و رمز باید رشته باشند:

uuid: 12345678-1234-1234-1234-123456789012      # ممکن است به چیز عجیبی تجزیه شود
uuid: "12345678-1234-1234-1234-123456789012"    # امن

unsupported proxy type: xxx

علت: اشتراک پروتکلی به کار برده که هستهٔ فعلی شما پشتیبانی نمی‌کند.

راه‌حل: هستهٔ Mihomo را به‌روز کنید. در Clash Verge: Settings ← Clash Core ← به‌روزرسانی.

اگر بعد از به‌روزرسانی هم پشتیبانی نشد، یعنی Mihomo واقعاً هنوز آن پروتکل را پیاده نکرده و باید از ارائه‌دهنده گره‌ای با پروتکل دیگر بگیرید.

proxy 'xxx' not found

علت: یک گروه سیاست به نام گره‌ای ارجاع می‌دهد که وجود ندارد.

محرک‌های رایج:

• غلط تایپی هنگام نوشتن دستی نام گره‌ها
• به‌روزرسانی اشتراک نام گره‌ها را عوض کرده
• نام گروه در پیکربندی توسعه‌یافته با اشتراک نمی‌خواند (تفاوت ایموجی یا فاصله)

راه‌حل: فایل اصلی اشتراک را باز کنید و نام دقیق را کپی کنید. یا برای جمع‌آوری خودکار به include-all و filter بروید؛ عبارت باقاعدهٔ گروه‌بندی گره را ببینید.

rule 'xxx' error: invalid domain

علت: قاعده بدشکل نوشته شده.

# غلط
- DOMAIN-SUFFIX,https://google.com,PROXY   # پروتکل ننویسید
- DOMAIN-SUFFIX,*.google.com,PROXY         # نویسهٔ جایگزین ننویسید
- IP-CIDR,8.8.8.8,DIRECT                   # IP-CIDR ماسک می‌خواهد

# درست
- DOMAIN-SUFFIX,google.com,PROXY
- IP-CIDR,8.8.8.8/32,DIRECT,no-resolve

rules[N] [xxx] error: unsupported rule type

علت: نوع قاعده غلط نوشته شده، یا نسخهٔ هستهٔ شما پشتیبانی‌اش نمی‌کند.

املا را بررسی کنید: DOMAIN-SUFFIX نه DOMAIN_SUFFIX، و IP-CIDR نه IPCIDR.

ارجاع حلقوی میان گروه‌های سیاست

نشانه: بارگذاری گیر می‌کند، یا پیام از بازگشتی بودن می‌گوید.

علت: در proxies گروه A نام B هست و در proxies گروه B نام A.

راه‌حل: سلسله‌مراتب را مرتب کنید تا ارجاع‌ها یک‌طرفه باشند (گروه‌های بالایی به پایینی ارجاع بدهند نه برعکس).

۳. مربوط به DNS

دامنه در default-nameserver

# غلط
default-nameserver:
  - https://doh.pub/dns-query

# درست: فقط IP ساده
default-nameserver:
  - 223.5.5.5
  - 119.29.29.29

کل هدف default-nameserver حل کردن نام سرورهای DNS دیگر شماست، پس خودش نمی‌تواند نام باشد.

نام‌های داخلی حل نمی‌شوند

خطا نیست، رفتار غلط است. علتش این است که fake-ip گرفتشان.

dns:
  fake-ip-filter:
    - "+.mycompany.com"
    - "*.lan"
    - "*.local"

توضیح پیکربندی DNS را ببینید.

۴. مجموعه‌قواعد و providerها

provider xxx: initial failed

علت: دانلود یک مجموعه قاعده یا اشتراک شکست خورده.

بررسی:

مجموعه قاعده بارگذاری می‌شود ولی کاری نمی‌کند

علت: behavior با محتوای فایل نمی‌خواند. این خطایی نمی‌دهد، فقط بی‌صدا از کار می‌افتد.

rule-set xxx not found

نام مجموعه در rules ارجاع داده شده ولی در rule-providers تعریف نشده، یا نامش غلط نوشته شده.

۵. TUN و دسترسی‌ها

operation not permitted / کلید TUN کاری نمی‌کند

علت: دسترسی کافی نیست، پس کارت مجازی ساخته نشد.

راه‌حل:

• Windows / macOS: «حالت سرویس» را نصب کنید
• Linux: sudo setcap cap_net_admin,cap_net_bind_service=+ep /path/to/mihomo

address already in use

پورت گرفته شده.

# Windows
netstat -ano | findstr :7897
tasklist | findstr <PID>

# Linux / macOS
lsof -i :7897

پورت را عوض کنید یا فرایندی که گرفته‌اش را متوقف کنید.

۶. یک راه سریع برای مکان‌یابی مشکل

وقتی پیکربندی بلند است و خطا شمارهٔ خط ندارد، دو نیم کنید:

یک پیکربندی کمینهٔ کارآمد به‌عنوان مبنا:

mixed-port: 7897
mode: rule
log-level: info
proxies:
  - name: "TEST"
    type: trojan
    server: example.com
    port: 443
    password: "pwd"
proxy-groups:
  - name: "PROXY"
    type: select
    proxies: ["TEST", DIRECT]
rules:
  - MATCH,PROXY

اگر این بارگذاری شد، محیطتان سالم است و مشکل در محتوای پیکربندی شماست.

۷. جدول مرجع خطاها

۸. پیشگیری

خلاصه

• mihomo -t -d پوشه مفیدترین دستور است؛ خطایش از خطای کلاینت بهتر است
• سه دام YAML: تورفتگی با تب، نبود فاصله بعد از دونقطه، و گیومهٔ بسته‌نشده
• proxy not found معمولاً یعنی ناهماهنگی نام — از اشتراک کپی‌اش کنید
• مجموعه قاعده‌ای که بی‌صدا می‌افتد یعنی behavior غلط است
• وقتی پیدایش نمی‌کنید، پیکربندی را دو نیم کنید

بیشتر بخوانید: توضیح ساختار YAML و پیکربندی توسعه‌یافتهٔ Merge.

مستندات مرتبط

مبانی پیکربندی ساختار YAML پیکربندی Clash — هرکدام از هشت فیلد سطح بالا چه کار می‌کنند

یک پیکربندی Clash / Mihomo از بالا تا پایین باز می‌شود — پورت‌ها، حالت، DNS، proxies، proxy-groups، rules و rule-providers — به‌همراه یک پیکربندی کمینهٔ کارآمد که مستقیم می‌شود چسباند.

2026-08-021413 واژه3 دقیقه مطالعه

مبانی پیکربندی پنج نوع proxy-groups — انواع select و url-test و fallback و load-balance و relay

هر گروه سیاست واقعاً چه می‌کند، کِی به کارش ببریم، کدام پارامترها مهم‌اند، به‌علاوهٔ یک ساختار گروه‌بندی آمادهٔ کپی و گزینه‌های include-all و filter در Mihomo.

2026-07-291503 واژه4 دقیقه مطالعه

مبانی پیکربندی توسعهٔ اشتراک با Merge، تا ویرایش‌هایتان از به‌روزرسانی جان به در ببرند

ویرایش پیکربندی دانلودشده در به‌روزرسانی بعدی از بین می‌رود. پیکربندی توسعه‌یافتهٔ Clash Verge چطور کار می‌کند: نحو prepend/append/override، ترتیب ادغام، و مجموعه‌ای از قطعه‌های کاربردی.

2026-07-091299 واژه3 دقیقه مطالعه