mirror of
https://gitea.toothfairyai.com/ToothFairyAI/tf_code.git
synced 2026-04-07 01:08:58 +00:00
300 lines
13 KiB
Plaintext
300 lines
13 KiB
Plaintext
---
|
|
title: استكشاف الأخطاء وإصلاحها
|
|
description: المشكلات الشائعة وكيفية حلها.
|
|
---
|
|
|
|
لاستكشاف المشكلات في OpenCode وإصلاحها، ابدأ بالتحقق من السجلات والبيانات المحلية التي يخزنها على القرص.
|
|
|
|
---
|
|
|
|
## السجلات
|
|
|
|
يتم حفظ ملفات السجل في:
|
|
|
|
- **macOS/Linux**: `~/.local/share/opencode/log/`
|
|
- **Windows**: اضغط `WIN+R` والصق `%USERPROFILE%\.local\share\opencode\log`
|
|
|
|
تتم تسمية ملفات السجل بطوابع زمنية (مثل `2025-01-09T123456.log`) ويتم الاحتفاظ بأحدث 10 ملفات سجل.
|
|
|
|
يمكنك ضبط مستوى السجل باستخدام خيار سطر الأوامر `--log-level` للحصول على معلومات تصحيح أكثر تفصيلا. على سبيل المثال: `opencode --log-level DEBUG`.
|
|
|
|
---
|
|
|
|
## التخزين
|
|
|
|
يخزن opencode بيانات الجلسات وبيانات التطبيق الأخرى على القرص في:
|
|
|
|
- **macOS/Linux**: `~/.local/share/opencode/`
|
|
- **Windows**: اضغط `WIN+R` والصق `%USERPROFILE%\.local\share\opencode`
|
|
|
|
يحتوي هذا الدليل على:
|
|
|
|
- `auth.json` - بيانات المصادقة مثل مفاتيح API ورموز OAuth
|
|
- `log/` - سجلات التطبيق
|
|
- `project/` - بيانات خاصة بالمشروع مثل بيانات الجلسة والرسائل
|
|
- إذا كان المشروع داخل مستودع Git، فسيتم تخزينه في `./<project-slug>/storage/`
|
|
- إذا لم يكن داخل مستودع Git، فسيتم تخزينه في `./global/storage/`
|
|
|
|
---
|
|
|
|
## تطبيق سطح المكتب
|
|
|
|
يشغل OpenCode Desktop خادما محليا لـ OpenCode (العملية الجانبية `opencode-cli`) في الخلفية. معظم المشكلات سببها إضافة لا تعمل بشكل صحيح، أو ذاكرة تخزين مؤقت تالفة، أو إعداد خادم غير صحيح.
|
|
|
|
### فحوصات سريعة
|
|
|
|
- أغلق التطبيق تماما ثم أعد تشغيله.
|
|
- إذا عرض التطبيق شاشة خطأ، انقر **Restart** وانسخ تفاصيل الخطأ.
|
|
- على macOS فقط: قائمة `OpenCode` -> **Reload Webview** (يفيد إذا كانت الواجهة فارغة/متجمدة).
|
|
|
|
---
|
|
|
|
### تعطيل الإضافات
|
|
|
|
إذا كان تطبيق سطح المكتب يتعطل عند التشغيل، أو يتوقف عن الاستجابة، أو يتصرف بشكل غريب، فابدأ بتعطيل الإضافات.
|
|
|
|
#### تحقق من الإعدادات العامة
|
|
|
|
افتح ملف الإعدادات العام وابحث عن المفتاح `plugin`.
|
|
|
|
- **macOS/Linux**: `~/.config/opencode/opencode.jsonc` (أو `~/.config/opencode/opencode.json`)
|
|
- **macOS/Linux** (عمليات تثبيت أقدم): `~/.local/share/opencode/opencode.jsonc`
|
|
- **Windows**: اضغط `WIN+R` والصق `%USERPROFILE%\.config\opencode\opencode.jsonc`
|
|
|
|
إذا كانت لديك إضافات مضبوطة، فقم بتعطيلها مؤقتا بإزالة المفتاح أو ضبطه على مصفوفة فارغة:
|
|
|
|
```jsonc
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"plugin": [],
|
|
}
|
|
```
|
|
|
|
#### تحقق من أدلة الإضافات
|
|
|
|
يمكن لـ OpenCode أيضا تحميل إضافات محلية من القرص. انقلها مؤقتا إلى مكان آخر (أو أعد تسمية المجلد) ثم أعد تشغيل تطبيق سطح المكتب:
|
|
|
|
- **إضافات عامة**
|
|
- **macOS/Linux**: `~/.config/opencode/plugins/`
|
|
- **Windows**: اضغط `WIN+R` والصق `%USERPROFILE%\.config\opencode\plugins`
|
|
- **إضافات المشروع** (فقط إذا كنت تستخدم إعدادات لكل مشروع)
|
|
- `<your-project>/.opencode/plugins/`
|
|
|
|
إذا عاد التطبيق للعمل، فأعد تفعيل الإضافات واحدة تلو الأخرى لمعرفة أيها يسبب المشكلة.
|
|
|
|
---
|
|
|
|
### مسح ذاكرة التخزين المؤقت
|
|
|
|
إذا لم يساعد تعطيل الإضافات (أو كانت عملية تثبيت إضافة عالقة)، فامسح ذاكرة التخزين المؤقت حتى يتمكن OpenCode من إعادة بنائها.
|
|
|
|
1. أغلق OpenCode Desktop تماما.
|
|
2. احذف دليل ذاكرة التخزين المؤقت:
|
|
|
|
- **macOS**: Finder -> `Cmd+Shift+G` -> الصق `~/.cache/opencode`
|
|
- **Linux**: احذف `~/.cache/opencode` (أو شغّل `rm -rf ~/.cache/opencode`)
|
|
- **Windows**: اضغط `WIN+R` والصق `%USERPROFILE%\.cache\opencode`
|
|
|
|
3. أعد تشغيل OpenCode Desktop.
|
|
|
|
---
|
|
|
|
### إصلاح مشكلات اتصال الخادم
|
|
|
|
يمكن لـ OpenCode Desktop إما تشغيل خادمه المحلي (افتراضيا) أو الاتصال بعنوان URL لخادم قمت بتهيئته.
|
|
|
|
إذا ظهرت نافذة **"Connection Failed"** (أو لم يتجاوز التطبيق شاشة البداية)، فتحقق مما إذا كان هناك عنوان URL مخصص للخادم.
|
|
|
|
#### مسح عنوان URL الافتراضي لخادم سطح المكتب
|
|
|
|
من شاشة Home، انقر اسم الخادم (مع نقطة الحالة) لفتح محدد الخوادم. في قسم **Default server**، انقر **Clear**.
|
|
|
|
#### إزالة `server.port` / `server.hostname` من الإعدادات
|
|
|
|
إذا كان `opencode.json(c)` يحتوي على قسم `server`، فأزله مؤقتا ثم أعد تشغيل تطبيق سطح المكتب.
|
|
|
|
#### تحقق من متغيرات البيئة
|
|
|
|
إذا كان `OPENCODE_PORT` مضبوطا في بيئتك، فسيحاول تطبيق سطح المكتب استخدام ذلك المنفذ للخادم المحلي.
|
|
|
|
- أزل ضبط `OPENCODE_PORT` (أو اختر منفذا متاحا) ثم أعد التشغيل.
|
|
|
|
---
|
|
|
|
### Linux: مشكلات Wayland / X11
|
|
|
|
على Linux، قد تتسبب بعض إعدادات Wayland في نوافذ فارغة أو أخطاء في مدير التركيب (compositor).
|
|
|
|
- إذا كنت تستخدم Wayland وكانت نافذة التطبيق فارغة/يتعطل، فجرّب التشغيل مع `OC_ALLOW_WAYLAND=1`.
|
|
- إذا جعل ذلك الأمور أسوأ، فأزل هذا المتغير وجرّب التشغيل ضمن جلسة X11 بدلا من ذلك.
|
|
|
|
---
|
|
|
|
### Windows: بيئة تشغيل WebView2
|
|
|
|
على Windows، يتطلب OpenCode Desktop وجود **WebView2 Runtime** الخاصة بـ Microsoft Edge. إذا فتح التطبيق نافذة فارغة أو لم يبدأ، فقم بتثبيت/تحديث WebView2 ثم جرّب مجددا.
|
|
|
|
---
|
|
|
|
### Windows: مشكلات الأداء العامة
|
|
|
|
إذا كنت تواجه بطءا في الأداء، أو مشكلات في الوصول إلى الملفات، أو مشكلات في الطرفية على Windows، فجرّب استخدام [WSL (نظام Windows الفرعي لـ Linux)](/docs/windows-wsl). يوفر WSL بيئة Linux تعمل بسلاسة أكبر مع ميزات OpenCode.
|
|
|
|
---
|
|
|
|
### الإشعارات لا تظهر
|
|
|
|
لا يعرض OpenCode Desktop إشعارات النظام إلا عندما:
|
|
|
|
- تكون الإشعارات مفعلة لـ OpenCode في إعدادات نظام التشغيل، و
|
|
- تكون نافذة التطبيق غير نشطة.
|
|
|
|
---
|
|
|
|
### إعادة تعيين تخزين تطبيق سطح المكتب (كحل أخير)
|
|
|
|
إذا لم يبدأ التطبيق ولم تتمكن من مسح الإعدادات من داخل الواجهة، فأعد تعيين الحالة المحفوظة لتطبيق سطح المكتب.
|
|
|
|
1. أغلق OpenCode Desktop.
|
|
2. اعثر على هذه الملفات واحذفها (توجد في دليل بيانات تطبيق OpenCode Desktop):
|
|
|
|
- `opencode.settings.dat` (عنوان URL الافتراضي لخادم سطح المكتب)
|
|
- `opencode.global.dat` و `opencode.workspace.*.dat` (حالة الواجهة مثل الخوادم/المشاريع الأخيرة)
|
|
|
|
للعثور على الدليل بسرعة:
|
|
|
|
- **macOS**: Finder -> `Cmd+Shift+G` -> `~/Library/Application Support` (ثم ابحث عن أسماء الملفات أعلاه)
|
|
- **Linux**: ابحث ضمن `~/.local/share` عن أسماء الملفات أعلاه
|
|
- **Windows**: اضغط `WIN+R` -> `%APPDATA%` (ثم ابحث عن أسماء الملفات أعلاه)
|
|
|
|
---
|
|
|
|
## الحصول على المساعدة
|
|
|
|
إذا كنت تواجه مشكلات مع OpenCode:
|
|
|
|
1. **الإبلاغ عن المشكلات على GitHub**
|
|
|
|
أفضل طريقة للإبلاغ عن الأخطاء أو طلب الميزات هي عبر مستودعنا على GitHub:
|
|
|
|
[**github.com/anomalyco/opencode/issues**](https://github.com/anomalyco/opencode/issues)
|
|
|
|
قبل إنشاء مشكلة جديدة، ابحث في المشكلات الموجودة لمعرفة ما إذا كانت مشكلتك قد تم الإبلاغ عنها بالفعل.
|
|
|
|
2. **انضم إلى Discord**
|
|
|
|
للحصول على مساعدة فورية ونقاشات المجتمع، انضم إلى خادم Discord الخاص بنا:
|
|
|
|
[**opencode.ai/discord**](https://opencode.ai/discord)
|
|
|
|
---
|
|
|
|
## مشكلات شائعة
|
|
|
|
فيما يلي بعض المشكلات الشائعة وكيفية حلها.
|
|
|
|
---
|
|
|
|
### OpenCode لا يبدأ
|
|
|
|
1. تحقق من السجلات بحثا عن رسائل الخطأ
|
|
2. جرّب التشغيل مع `--print-logs` لرؤية المخرجات في الطرفية
|
|
3. تأكد من أنك تستخدم أحدث إصدار عبر `opencode upgrade`
|
|
|
|
---
|
|
|
|
### مشكلات المصادقة
|
|
|
|
1. جرّب إعادة المصادقة باستخدام الأمر `/connect` في واجهة TUI
|
|
2. تحقق من أن مفاتيح API الخاصة بك صالحة
|
|
3. تأكد من أن شبكتك تسمح بالاتصال بواجهة API الخاصة بالمزوّد
|
|
|
|
---
|
|
|
|
### النموذج غير متاح
|
|
|
|
1. تحقق من أنك قمت بالمصادقة مع المزوّد
|
|
2. تأكد من أن اسم النموذج في الإعدادات صحيح
|
|
3. قد تتطلب بعض النماذج صلاحيات وصول محددة أو اشتراكات
|
|
|
|
إذا واجهت `ProviderModelNotFoundError` فمن المرجح أنك تشير إلى نموذج بشكل غير صحيح في مكان ما.
|
|
يجب الإشارة إلى النماذج بهذه الصيغة: `<providerId>/<modelId>`
|
|
|
|
أمثلة:
|
|
|
|
- `openai/gpt-4.1`
|
|
- `openrouter/google/gemini-2.5-flash`
|
|
- `opencode/kimi-k2`
|
|
|
|
لمعرفة النماذج التي لديك صلاحية الوصول إليها، شغّل `opencode models`
|
|
|
|
---
|
|
|
|
### ProviderInitError
|
|
|
|
إذا واجهت ProviderInitError، فمن المحتمل أن إعداداتك غير صالحة أو تالفة.
|
|
|
|
لحل ذلك:
|
|
|
|
1. أولا، تحقق من أن المزوّد مضبوط بشكل صحيح باتباع [دليل المزوّدين](/docs/providers)
|
|
2. إذا استمرت المشكلة، فجرّب مسح الإعدادات المخزنة لديك:
|
|
|
|
```bash
|
|
rm -rf ~/.local/share/opencode
|
|
```
|
|
|
|
على Windows، اضغط `WIN+R` واحذف: `%USERPROFILE%\.local\share\opencode`
|
|
|
|
3. أعد المصادقة مع المزوّد باستخدام الأمر `/connect` في واجهة TUI.
|
|
|
|
---
|
|
|
|
### AI_APICallError ومشكلات حزم المزوّد
|
|
|
|
إذا واجهت أخطاء في استدعاءات API، فقد يكون السبب حزم مزوّد قديمة. يقوم opencode بتثبيت حزم المزوّد (OpenAI و Anthropic و Google وغير ذلك) ديناميكيا عند الحاجة ويقوم بتخزينها مؤقتا محليا.
|
|
|
|
لحل مشكلات حزم المزوّد:
|
|
|
|
1. امسح ذاكرة التخزين المؤقت لحزم المزوّد:
|
|
|
|
```bash
|
|
rm -rf ~/.cache/opencode
|
|
```
|
|
|
|
على Windows، اضغط `WIN+R` واحذف: `%USERPROFILE%\.cache\opencode`
|
|
|
|
2. أعد تشغيل opencode لإعادة تثبيت أحدث حزم المزوّد
|
|
|
|
سيجبر ذلك opencode على تنزيل أحدث إصدارات حزم المزوّد، وهو ما يحل غالبا مشكلات التوافق مع معاملات النماذج وتغييرات API.
|
|
|
|
---
|
|
|
|
### النسخ/اللصق لا يعمل على Linux
|
|
|
|
يحتاج مستخدمو Linux إلى تثبيت إحدى أدوات الحافظة التالية حتى تعمل ميزة النسخ/اللصق:
|
|
|
|
**لأنظمة X11:**
|
|
|
|
```bash
|
|
apt install -y xclip
|
|
# or
|
|
apt install -y xsel
|
|
```
|
|
|
|
**لأنظمة Wayland:**
|
|
|
|
```bash
|
|
apt install -y wl-clipboard
|
|
```
|
|
|
|
**للبيئات بدون واجهة رسومية (Headless):**
|
|
|
|
```bash
|
|
apt install -y xvfb
|
|
# and run:
|
|
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
|
|
export DISPLAY=:99.0
|
|
```
|
|
|
|
سيكتشف opencode ما إذا كنت تستخدم Wayland ويفضل `wl-clipboard`، وإلا فسيحاول العثور على أدوات الحافظة بالترتيب التالي: `xclip` ثم `xsel`.
|