استكشاف أخطاء Claude Code WebFetch وإصلاحها بالكامل: 4 خطوات لحل مشكلة Unable to verify if domain

الطبقة 4 · تجاوز WebFetch استبدال Bash(curl:*) أو الاتصال بـ fetch-mcp / خادم Playwright MCP سيناريوهات فشل حاويات CI / preflight بالكامل · تجاوز فحص preflight الخاص بـ claude.ai تماماً 15 دقيقة الحل النهائي

المستوى الأول: الوكيل (Proxy) ومتغير البيئة NO_PROXY

هذه هي العقبة الأولى والأكثر شيوعاً للمستخدمين. يتبع Claude Code متغيرات بيئة الوكيل القياسية، ويقرأها وفقاً للأولوية التالية:

https_proxy > HTTPS_PROXY > http_proxy > HTTP_PROXY

الحد الأدنى من الإعدادات على macOS / Linux:

# ~/.zshrc أو ~/.bashrc
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export NO_PROXY="localhost,127.0.0.1,::1,api.apiyi.com,vip.apiyi.com"

على Windows PowerShell:

$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1,api.apiyi.com,vip.apiyi.com"

يمكنك أيضاً الكتابة مباشرة في كتلة env داخل ملف ~/.claude/settings.json:

{
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:7890",
    "HTTP_PROXY": "http://127.0.0.1:7890",
    "NO_PROXY": "localhost,127.0.0.1,api.apiyi.com,vip.apiyi.com"
  }
}

⚠️ تفاصيل مهمة: يجب عليك إضافة نطاقات خدمة وكيل APIYI (api.apiyi.com / vip.apiyi.com) إلى NO_PROXY! وإلا فإن استدعاءات API الخاصة بـ Claude Code ستمر عبر الوكيل، مما يجعلها بطيئة وقد تتعرض للاعتراض من قبل عقدة الوكيل. ننصح بالاتصال المباشر بـ APIYI عبر NO_PROXY بينما يمر فحص WebFetch الأولي عبر الوكيل للوصول إلى claude.ai، فهذا المسار هو الأكثر استقراراً.

وكيل المصادقة الأساسية (شائع في بيئات الشركات):

export HTTPS_PROXY=http://username:[email protected]:8080

ملاحظة: لا يدعم Claude Code وكيل SOCKS؛ إذا كان الوكيل لديك يعمل بنمط SOCKS فقط، استخدم privoxy أو v2ray لتحويل SOCKS إلى HTTP.

المستوى الثاني: التفويض المسبق لـ WebFetch(domain:xxx)

في بعض الأحيان، ينجح الفحص الأولي (preflight)، لكن Claude Code يستمر في سؤالك "هل تسمح بجلب هذا النطاق؟". أضف النطاقات المستخدمة بكثرة إلى permissions.allow ولن يسألك Claude مجدداً:

{
  "permissions": {
    "allow": [
      "WebFetch(domain:www.weather.com.cn)",
      "WebFetch(domain:github.com)",
      "WebFetch(domain:developer.mozilla.org)",
      "WebFetch(domain:docs.python.org)"
    ],
    "ask": [
      "WebFetch"
    ]
  }
}

مرجع سريع لقواعد الصيغة:

🎯 نصيحة إدارية: في بيئات الشركات، نوصي باستخدام managed-settings.json لإنشاء قائمة بيضاء بالنطاقات المسموح بجلبها، ووضعها في /Library/Application Support/ClaudeCode/managed-settings.json (على macOS) أو /etc/claude-code/managed-settings.json (على Linux)، مع تفعيل allowManagedPermissionRulesOnly: true لإلزام جميع المطورين بالسياسة. يمكن لفرق التطوير التي تستخدم Claude API عبر APIYI استخدام نفس القواعد لضمان توحيد سياسات الأذونات.

المستوى الثالث: شهادات CA الخاصة بالشركات واعتراض TLS

إذا كانت شركتك تستخدم منتجات أمنية تعتمد على اعتراض TLS مثل Zscaler / CrowdStrike / Cato Networks، فستقوم هذه المنتجات بإعادة إصدار شهادات HTTPS، مما يؤدي إلى ظهور أخطاء SSL مثل UNABLE_TO_GET_ISSUER_CERT في بيئة تشغيل Node.js الخاصة بـ Claude Code.

طريقة الحل: قم بتصدير شهادة الجذر (Root CA) الخاصة بالشركة ثم أشر إليها:

export NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem

أو أضفها إلى ~/.claude/settings.json:

{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/Users/you/certs/company-root-ca.pem",
    "CLAUDE_CODE_CERT_STORE": "bundled,system"
  }
}

القيم المتاحة لـ CLAUDE_CODE_CERT_STORE:

المصادقة الثنائية mTLS (للبيئات الأكثر صرامة):

export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

المستوى الرابع: تجاوز WebFetch واستخدام Bash curl أو MCP كبديل

إذا لم تنجح المستويات الثلاثة السابقة، فإن الطريقة الأكثر موثوقية هي عدم استخدام WebFetch؛ اطلب من Claude استخدام أداة Bash للقيام بـ curl مباشرة، أو الاتصال بخادم MCP لجلب البيانات.

الخيار أ: السماح لـ Bash باستخدام curl/wget

{
  "permissions": {
    "allow": [
      "Bash(curl:*)",
      "Bash(wget:*)"
    ]
  }
}

ثم أخبر Claude في المحادثة: "يرجى استخدام curl لجلب محتوى الصفحة الرئيسية لـ www.weather.com.cn" — سيتجاوز Claude أداة WebFetch ويستخدم Bash مباشرة. هذا المسار لا يطلق فحصاً أولياً (preflight)، ويكفي أن يكون إعداد الوكيل يسمح بالوصول للموقع المستهدف.

الخيار ب: الاتصال بـ fetch-mcp أو Playwright MCP

# تثبيت خادم fetch MCP التابع لجهة خارجية
claude mcp add fetch npx -- @modelcontextprotocol/server-fetch

طلبات الشبكة الخاصة بأدوات MCP يتم إطلاقها بواسطة عملية خادم MCP نفسها، ولا تمر عبر مسار الفحص الأولي لـ Claude Code، مما يزيد من الاستقرار بشكل ملحوظ. بالنسبة للمواقع الديناميكية التي تتطلب تنفيذ JavaScript، فإن استخدام Playwright MCP هو الخيار الأنسب.

مصفوفة مقارنة حلول استكشاف أخطاء WebFetch وإصلاحها ★ كلما زاد العدد كان ذلك أكثر ملاءمة · انظر إلى العمود الذي يحتوي على أكبر قدر من اللون الداكن

أبعاد التقييم

أ. إعدادات الوكيل HTTPS_PROXY

ب. التفويض المسبق للصلاحيات WebFetch(domain)

C. شهادة سلطة المؤسسة (CA) NODE_EXTRA_CA_CERTS

د. تجاوز WebFetch Bash curl + MCP

صعوبة التكوين ★★★★☆ ★★★★★ ★★☆☆☆ ★★★★☆

حل نطاق المشكلات ★★★★★ ★★☆☆☆ ★★★☆☆ ★★★★★

تأثير الأداء ★★★☆☆ ★★★★★ ★★★★☆ ★★★★☆

امتثال الشركات ★★★☆☆ ★★★★★ ★★★★★ ★★★☆☆

التكيف المحلي ★★★★☆ ★★★☆☆ ★★☆☆☆ ★★★★★

💡 نوصي المستخدمين المحليين بالتركيبة التالية: A (وكيل أساسي) + B (نطاق شائع) + D (بديل)

بعد أن استعرضنا الجانب النظري، دعونا نلقي نظرة على سير عمل الحل الكامل في ثلاثة سيناريوهات واقعية.

السيناريو الأول: جلب البيانات من weather.com.cn على جهاز MacBook داخل الصين (سيناريو لقطة الشاشة)

المشكلة: يظهر خطأ Unable to verify بشكل متكرر عند محاولة جلب www.weather.com.cn.

خطوات التحقق:

# الخطوة 1: التأكد من حالة الوكيل (Proxy)
echo $HTTPS_PROXY  # يجب أن يظهر شيء مثل http://127.0.0.1:7890

# الخطوة 2: التحقق يدوياً مما إذا كان claude.ai متاحاً
curl -I https://claude.ai/code/ -x http://127.0.0.1:7890
# إذا عاد الخطأ 403 + cf-mitigated، فهذا يعني أن Cloudflare يحظر الطلب، انتقل للخطوة 3
# إذا عاد 200، فهذا يعني أن الفحص المسبق (preflight) سليم، تحقق من الأذونات (permissions)

# الخطوة 3: تبديل الخطة داخل Claude Code — استخدم Bash + curl بدلاً من ذلك
# قل له مباشرة في المحادثة:
# "لا تستخدم WebFetch، استخدم curl لجلب الصفحة الرئيسية لـ http://www.weather.com.cn"

الإعداد النهائي (~/.claude/settings.json):

{
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:7890",
    "HTTP_PROXY": "http://127.0.0.1:7890",
    "NO_PROXY": "localhost,127.0.0.1,api.apiyi.com,vip.apiyi.com"
  },
  "permissions": {
    "allow": [
      "WebFetch(domain:www.weather.com.cn)",
      "Bash(curl:*)",
      "Bash(wget:*)"
    ]
  }
}

🎯 نصيحة عملية للمستخدمين في الصين: التوليفة الأكثر استقراراً هي «استخدام APIYI (apiyi.com) لاستدعاء النموذج + تشغيل WebFetch عبر الوكيل + الرجوع (fallback) إلى curl عند الضرورة». عند إضافة base_url الخاص بـ APIYI إلى NO_PROXY في إعداداتك، لن يتم توجيه طلبات API الخاصة بـ Claude Code عبر الوكيل، مما يضمن استقراراً وسرعة استجابة تضاهي الاتصال المباشر من الخارج.

السيناريو الثاني: أجهزة الشركة + اعتراض TLS بواسطة Zscaler

المشكلة: يظهر خطأ SELF_SIGNED_CERT_IN_CHAIN أو UNABLE_TO_VERIFY_LEAF_SIGNATURE عند استخدام WebFetch.

الحل:

# الخطوة 1: احصل على شهادة CA الجذر الخاصة بالشركة من قسم تكنولوجيا المعلومات (عادةً تكون بصيغة .pem أو .crt)
# الخطوة 2: قم بتهيئة Claude Code للوثوق بهذه الشهادة
export NODE_EXTRA_CA_CERTS=~/certs/company-zscaler-root.pem

# الخطوة 3: الوثوق أيضاً بمخزن شهادات النظام (عادة ما يتم حقن Zscaler فيه)
export CLAUDE_CODE_CERT_STORE=bundled,system

# الخطوة 4: أعد تشغيل Claude Code

السيناريو الثالث: التشغيل بدون واجهة رسومية (headless) داخل Docker / CI

المشكلة: يعمل الكود محلياً، لكنه يفشل بنسبة 100% في بيئة CI.

السبب: لا توجد وكالات (proxies) أو متصفحات داخل الحاوية، مما يجعل حماية البوتات من Cloudflare تكتشف عميل CLI وترفض الاتصال.

الحل: تعطيل WebFetch في بيئة CI وإجبار النظام على استخدام Bash:

# .github/workflows/claude.yml أو ما يشابهه
env:
  CLAUDE_CODE_DISABLE_WEBFETCH: "true"  # إذا كان متغير البيئة هذا مفعلاً

أو عبر وسيط التشغيل --disallowedTools:

claude --disallowedTools WebFetch --allowedTools "Bash(curl:*)"

🎯 نصيحة لتكامل CI: في بيئات الحاويات، قم بتوجيه مفتاح API إلى عقدة الترحيل المستقرة الخاصة بـ APIYI (apiyi.com) لتجنب فشل CI بسبب تقلبات الشبكة الدولية. نوصي بضبط ANTHROPIC_BASE_URL=https://vip.apiyi.com و ANTHROPIC_API_KEY=sk-xxx في أسرار (secrets) GitHub Actions / GitLab CI، مع سياسة تعطيل WebFetch، لضمان استقرار مهام Claude Code في CI بنسبة تزيد عن 99%.

أفضل الممارسات الهندسية لأخطاء WebFetch في Claude Code

من السهل تشغيل تجربة فردية، لكن لضمان استخدام مستقر لـ Claude Code من قبل جميع أعضاء الفريق، هناك نقاط أساسية يجب مراعاتها.

الممارسة الأولى: ملف managed-settings.json موحد

قم بتوزيع ملف managed-settings.json موحد على الفريق لتجنب قيام كل فرد بإعداداته الخاصة:

{
  "env": {
    "HTTPS_PROXY": "http://corp-proxy:8080",
    "NODE_EXTRA_CA_CERTS": "/opt/company/ca.pem",
    "NO_PROXY": "*.corp.example.com,api.apiyi.com,vip.apiyi.com"
  },
  "permissions": {
    "allow": [
      "WebFetch(domain:*.corp.example.com)",
      "WebFetch(domain:github.com)",
      "WebFetch(domain:stackoverflow.com)",
      "Bash(curl:*)"
    ],
    "deny": [
      "WebFetch(domain:*)"
    ]
  },
  "allowManagedPermissionRulesOnly": true
}

مسارات الملف:

الممارسة الثانية: استراتيجية الرجوع (fallback) ثلاثية المستويات

وضح أولوية اختيار الأدوات في ملف CLAUDE.md ليقوم Claude بتجربتها بالترتيب:

## أولويات أدوات استخراج البيانات من الويب (Web Scraping)

1. الخيار الأول: WebFetch (للنطاقات المصرح بها مسبقاً).
2. في حال فشل WebFetch، يتم الانتقال تلقائياً (Fallback) إلى Bash curl.
3. للمواقع الديناميكية، استخدم Playwright MCP.
4. لا تستخدم أبداً `curl -k` لتجاهل أخطاء الشهادات.

```bash
# عند وضع هذه التعليمات في ملف CLAUDE.md، سيقوم Claude بالتبديل تلقائياً إلى curl عند حدوث خطأ في WebFetch، مما يحسن تجربة المستخدم بشكل ملحوظ.

الممارسة الثالثة: نص برمجي للفحص الصحي (Preflight)

اكتب نصاً برمجياً للتشخيص السريع، وقم بتشغيله أولاً عند استكشاف الأخطاء وإصلاحها:

#!/bin/bash
# claude-code-doctor.sh

echo "=== متغيرات البيئة ==="
env | grep -iE "proxy|claude_code|node_extra"

echo "=== اختبار الفحص المسبق لـ claude.ai ==="
curl -sI -o /dev/null -w "HTTP %{http_code} · %{time_total}s\n" \
  https://claude.ai/code/

echo "=== اختبار api.anthropic.com ==="
curl -sI -o /dev/null -w "HTTP %{http_code} · %{time_total}s\n" \
  https://api.anthropic.com/

echo "=== اختبار خدمة وكيل APIYI ==="
curl -sI -o /dev/null -w "HTTP %{http_code} · %{time_total}s\n" \
  https://vip.apiyi.com/

echo "=== تحليل DNS ==="
nslookup claude.ai

إذا أرجع claude.ai/code/ رمز الحالة 403 مع ترويسة الاستجابة cf-mitigated، فهذه مشكلة نموذجية في فحص Cloudflare المسبق؛ انتقل مباشرة إلى حل الطبقة الرابعة (Layer 4).

🎯 نصيحة تشخيصية: عند حدوث خلل في Claude Code، يمكن حل 80% من المشكلات باستخدام مجموعة أدوات التشخيص هذه. بالنسبة للمستخدمين في الصين، يُنصح بإضافة vip.apiyi.com كعقدة توجيه (Proxy) لـ API ضمن قائمة الفحص. إذا كان APIYI متاحاً بينما موقع Anthropic الرسمي غير متاح، استخدم خدمة وكيل APIYI (apiyi.com) لمواصلة العمل وتجنب توقف سير العمل بسبب مشاكل الشبكة.

الأسئلة الشائعة حول أخطاء WebFetch في Claude Code

س1: لماذا تظهر رسالة خطأ تقول "سياسات أمان المؤسسة تحظر claude.ai"، مع أن شركتي لا تستخدم أي برامج أمنية؟

هذه الرسالة من Anthropic غير دقيقة. ما يحدث فعلياً هو اعتراض من نظام حماية البوتات الخاص بـ Cloudflare أمام claude.ai؛ حيث يصنف Cloudflare عملية CLI كـ "بوت" ويرسل تحدي JS (JS Challenge)، ولا يستطيع CLI إكمال هذا التحدي فيظهر الخطأ. لا علاقة للأمر بسياسات تكنولوجيا المعلومات في شركتك عادةً.

س2: هل يمكن لخدمة وكيل APIYI حل أخطاء WebFetch؟

جزئياً. تتولى APIYI (apiyi.com) مسؤولية توجيه طلبات API الخاصة بـ api.anthropic.com فقط، مما يضمن استقرار محادثات Claude Code وقرارات استدعاء الأدوات. لكن الفحص المسبق لـ WebFetch يستهدف claude.ai (وليس api.anthropic.com)، وهذا المسار لا تغطيه APIYI؛ لذا يجب حله عبر وكيل محلي. يُنصح بالجمع بينهما: استخدم APIYI للاتصال المباشر بـ API، واستخدم وكيل للاتصال بالفحص المسبق، فالمساران منفصلان.

س3: هل يوجد خيار إعداد باسم skipWebFetchPreflight؟

هناك نقاشات مجتمعية، ولكن حتى أبريل 2026 لم يتم توثيق ذلك رسمياً. ذكرت قضية GitHub رقم #39896 أن هذه ميزة ينتظرها المجتمع لتخطي التحقق المسبق. قبل الدعم الرسمي، يُنصح باستخدام حل الطبقة الرابعة (Bash curl + نطاقات مصرح بها) لتجاوز هذه المشكلة، فالنتيجة مماثلة وأكثر تحكماً.

س4: لماذا يستمر WebFetch في إظهار خطأ رغم تفعيل وكيل Clash العام؟

نمط الوكيل العام في Clash لا يضبط متغيرات البيئة تلقائياً. Claude Code هو عملية Node.js CLI، وهو يقرأ فقط متغيرات البيئة مثل HTTPS_PROXY ولا يكتشف إعدادات الوكيل في النظام. يجب عليك تصدير متغيرات الوكيل صراحة في ملف تعريف shell الخاص بك، أو إضافتها إلى كتلة env في ملف ~/.claude/settings.json.

س5: نجح WebFetch ولكن النتيجة غير مكتملة، هل هناك محتوى مفقود؟

هذا بسبب قيود max_content_tokens في Claude Code. لا يمكن تعديلها في قواعد الأذونات، ولكن إذا قمت باستدعاء أداة web_fetch مباشرة عبر API الخاص بـ Claude (وليس عبر CLI)، يمكنك ضبط "max_content_tokens": 100000 لزيادة حجم الاستخراج للصفحة الواحدة. في هذه الحالة، يُنصح بالاتصال المباشر بـ API عبر APIYI لمرونة أكبر.

س6: هل يمكن تجنب أخطاء WebFetch تماماً عن طريق تعطيله؟

نعم، يمكنك إضافة المعامل عند التشغيل:

claude --disallowedTools WebFetch

أو في ملف settings.json:

{
  "permissions": {
    "deny": ["WebFetch"]
  }
}

بالتزامن مع السماح بـ Bash(curl:*)، سيقوم Claude تلقائياً بالتبديل إلى curl، وهو ما يوفر تجربة أفضل للمستخدمين في الصين.

س7: كيف يمكن إعداد Claude Code في GitHub Actions / GitLab CI؟

في حاويات CI، يُنصح بشدة بتعطيل WebFetch؛ فالحاوية لا تحتوي على بيئة متصفح، وسيفشل الفحص المسبق بالتأكيد. في الوقت نفسه، وجه طلبات API إلى عقدة APIYI المستقرة:

env:
  ANTHROPIC_BASE_URL: https://vip.apiyi.com
  ANTHROPIC_API_KEY: ${{ secrets.APIYI_KEY }}
  CLAUDE_CODE_DISALLOWED_TOOLS: "WebFetch"

ملخص أخطاء Claude Code WebFetch وقائمة الإجراءات

بمراجعة الموضوع، فإن جوهر أخطاء Claude Code WebFetch يعود إلى قيود التصميم الخاصة بـ Cloudflare preflight وواجهة سطر الأوامر (CLI) التي لا تحتوي على متصفح، وليس بسبب مشكلة في شبكتك أو سياسات تكنولوجيا المعلومات لديك. باختصار:

✅ الحلول الثلاثة الأساسية للمستخدمين: استخدام APIYI (apiyi.com) للاتصال المباشر بـ API + استخدام وكيل محلي لـ claude.ai preflight + استخدام Bash curl كخيار احتياطي (fallback)، وهذا يحل 90% من أخطاء WebFetch.

قائمة الإجراءات التنفيذية

قم بتنفيذ الخطوات الخمس التالية حسب الأولوية:

1. إعداد الوكيل: قم بضبط HTTPS_PROXY و HTTP_PROXY مع إضافة نطاق APIYI إلى NO_PROXY.
2. التفويض المسبق للنطاقات: أضف المواقع التي تزورها بشكل متكرر إلى permissions.allow ضمن WebFetch(domain:...).
3. التعامل مع شهادات CA المؤسسية: إذا كنت تعمل في بيئة Zscaler أو CrowdStrike، قم بضبط NODE_EXTRA_CA_CERTS.
4. تجهيز الخيار الاحتياطي: اسمح بـ Bash(curl:*) لتمكين Claude من التبديل تلقائيًا عند مواجهة عقبات.
5. برنامج فحص الحالة: أضف claude-code-doctor.sh إلى سلسلة أدوات فريقك.

أفضل الممارسات للمستخدمين المحليين · بنية مقسمة حسب المسار والطبقات فصل مسار API عن مسار WebFetch · لا يؤثر أحدهما على الآخر

جهاز المطور المحلي Claude Code CLI إعداد NO_PROXY: api.apiyi.com

① مسار API APIYI خدمة وكيل API شفافة vip.apiyi.com (اتصال مباشر)

② مسار التحقق المسبق (Preflight) وكيل محلي 127.0.0.1:7890

③ احتياطي Bash(curl:*) اتصال مباشر بالموقع المستهدف

Anthropic API api.anthropic.com استنتاج النموذج + اتخاذ قرار الأداة

claude.ai/code/ نقطة نهاية التحقق من اسم النطاق (حماية Cloudflare)

الموقع المستهدف weather.com.cn إلخ اتصال مباشر (بدون الحاجة إلى preflight)