> ## Documentation Index
> Fetch the complete documentation index at: https://docs.teamsoclo.site/llms.txt
> Use this file to discover all available pages before exploring further.

# استكشاف الأخطاء وإصلاحها

> العَرَض ← السبب ← الحل، إضافة إلى الأسئلة الشائعة

## بحث سريع

| يقول التطبيق | على الأرجح | الحل |
| - | - | - |
| `401 Unauthorized`، `Invalid token` | مفتاح خاطئ أو حروف ناقصة أو منتهي الصلاحية أو معطّل | الصق المفتاح في [صفحة التحقق](https://gpt.teamsoclo.site/check) |
| `404 Not Found` | Base URL يفتقد `/v1` (أو مضاعف إلى `/v1/v1`) | صحِّح Base URL |
| `No available channel for model ... under group ...` | مفتاح إحدى الباقات يستدعي نموذج الباقة الأخرى | استخدم نموذج باقتك، انظر [النماذج](/ar/models) |
| `model not found`، خطأ فوري في اسم النموذج | خطأ إملائي في اسم النموذج | انسخ الاسم من [جدول النماذج](/ar/models) |
| `429 Too Many Requests` | تجاوز حد الطلبات في الدقيقة | انتظر الدقيقة التالية، بطِّئ |
| `insufficient quota` | استنفد المفتاح رموزه | اشترِ كوداً جديداً |
| الإعداد مُعدَّل لكن لا شيء يتغير | التطبيق لم يُغلق كلياً أو الطرفية لم تُعاد فتحها | أغلق كلياً وأعد الفتح |

## المفاتيح والحصة

### مفتاح خاطئ أو مقتطع

المشكلة الأكثر شيوعاً ليست مفتاحاً معطوباً بل **فقدان بعض الأحرف** عند تحديد النص بالماوس. استخدم دائماً زر **Copy** في صفحة الاستبدال. الصق المفتاح في [صفحة التحقق](https://gpt.teamsoclo.site/check): إن قالت صالح، المفتاح جيد والمشكلة في إعداد التطبيق.

### انتهاء صلاحية المفتاح

لكل باقة فترة صلاحية تُعدّ من الاستبدال (مطبوعة على المنتج). بعد الانتهاء كل طلب يُعيد 401 حتى لو بقي رصيد. صفحة التحقق تُظهر تاريخ الانتهاء. الرموز غير المستخدمة لا تنتقل إلى كود جديد.

### الحصة مستنفدة

كل شيء كان يعمل ثم فجأة كل طلب يفشل بـ *insufficient quota*. راجع الرصيد المتبقي في صفحة التحقق. تناقص الرصيد بسرعة غير اعتيادية عادةً يعني وكيلاً يقرأ المستودع كاملاً أو محادثة طويلة جداً تُعاد إرسالها في كل دور.

### مفتاح مفقود

استبدل كود CDK ذاته مجدداً في [redeem.teamsoclo.site](https://redeem.teamsoclo.site)؛ تعرض الصفحة المفتاح الأصلي. لا تُعاد إصدار الأكواد بمفتاح جديد.

### كم جهازاً لكل مفتاح

لا يوجد حد للأجهزة، لكن **حد الطلبات في الدقيقة** مشترك بين كل الأجهزة التي تستخدم المفتاح. مشاركة المفتاح تعني المنافسة على الحد ذاته والوصول إلى 429 أسرع.

## الاتصال

### غياب /v1

Base URL الصحيح: `https://gpt.teamsoclo.site/v1`. بدون `/v1` تصطدم الطلبات بالموقع لا بالواجهة البرمجية ويبلغ التطبيق بـ 404 أو "could not connect".

<Warning>
  العكس أيضاً يفشل: بعض التطبيقات (Chatbox، بعض إصدارات Cline) تضيف `/v1` تلقائياً. إن أضفته وحصلت على 404، جرِّب بدون `/v1`؛ ربما صارت العنوان الحقيقي `/v1/v1`.
</Warning>

### استدعاء نموذج الباقة الأخرى

`No available channel for model gpt-astra under group default` يعني أن مفتاح GPT يستدعي نموذج Astra (أو العكس). كل مفتاح يستدعي نموذج باقته فقط. تحقق بـ:

```bash theme={null}
curl https://gpt.teamsoclo.site/v1/models -H "Authorization: Bearer sk-xxx"
```

### 429 Too Many Requests

لكل مفتاح حد أقصى لعدد الطلبات الناجحة في الدقيقة تحدده الباقة. تجاوزه يُعيد 429 برسالة "request limit reached". انتظر الدقيقة التالية. في السكريبتات الدفعية أضف تأخيراً بين الاستدعاءات، أو اشترِ كوداً آخر لتوزيع الحمل.

### الرد ينقطع في المنتصف

للأسئلة التي تتطلب تفكيراً طويلاً، قد يُسقط الطلب غير المتدفق قبل الرمز الأول. فعِّل `stream: true`. معظم تطبيقات الدردشة تفعل ذلك بالفعل؛ أضفه عند الاستدعاء من الكود.

### `Unsupported parameter: reasoning_effort`

فقط Chat Completions يقبل `reasoning_effort` على المستوى الأعلى. مع Responses API استخدم `"reasoning": {"effort": "high"}`. Codex يتعامل مع هذا تلقائياً.

## Codex

### `codex: command not found` بعد التثبيت

أكمل npm لكن الطرفية الحالية لم تُعد تحميل PATH. **افتح طرفية جديدة**. إن استمر الفشل، تحقق أن مجلد bin في npm موجود في PATH:

```bash theme={null}
npm config get prefix
```

هذا المجلد مضافاً إليه `/bin` يجب أن يكون في `$PATH`.

### Codex ما زال يطلب تسجيل دخول OpenAI

المتغير `TEAMSOCLO_API_KEY` لم يصل إلى عملية Codex:

* الطرفية: افتح تبويباً جديداً، تحقق بـ `echo $TEAMSOCLO_API_KEY`.
* VS Code على macOS: أغلق بـ `Cmd + Q` وأعد الفتح. أمر التثبيت عيّن المتغير لتطبيقات GUI عبر `launchctl`.
* VS Code على Linux: شغِّل VS Code من طرفية (`code .`)، أو سجِّل الخروج والدخول.
* Windows: افتح PowerShell أو VS Code **جديداً** بعد `setx`.

تحقق أن `config.toml` يحتوي `requires_openai_auth = false` و`env_key = "TEAMSOCLO_API_KEY"`.

### عدَّلت config.toml لكن Codex لا يتغير

الإعداد يُقرأ فقط عند بدء العملية. **Reload Window لا يكفي**؛ أغلق VS Code كلياً (macOS `Cmd + Q`، Windows أغلق كل النوافذ والعمليات الخلفية). هذا أكثر سؤال يُطرح عن Codex.

### `EACCES: permission denied` عند npm install

ثُبِّت Node بصلاحيات النظام، وهو شائع في Linux. غيِّر prefix في npm:

```bash theme={null}
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
```

أضف سطر `export` إلى `~/.bashrc` أو `~/.zshrc`. على المدى البعيد ثبِّت Node عبر nvm، انظر [البدء](/ar/getting-started).

### Windows: `running scripts is disabled on this system`

PowerShell يحظر ملفات `.ps1`، و`codex` / `npm` المكتوبتان في PowerShell تمران عبر shims `.ps1` الخاصة بـ npm. شغِّل مرة واحدة:

```powershell theme={null}
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

ثم افتح PowerShell جديداً. أو اكتب `codex.cmd` و`npm.cmd` بدلاً منهما.

### Windows: `EBUSY: resource busy or locked`

Codex يعمل (CLI أو الإضافة أو التطبيق) لذا لا يستطيع npm الكتابة فوق `codex.exe`. أغلق كل ما يشغِّل Codex وأعد تشغيل أمر التثبيت. الإعداد كُتب بالفعل قبل هذه الخطوة؛ فقط ترقية CLI تخطّت.

### Windows: خطأ ترميز ملف الإعداد

التعديل بـ PowerShell 5.1 و`Set-Content -Encoding UTF8` يضيف BOM لا يستطيع Codex قراءته. أعد تشغيل [أمر التثبيت](/ar/setup/codex) (يكتب UTF-8 بدون BOM)، أو احفظ الملف في VS Code كـ **UTF-8** (ليس UTF-8 with BOM).

### استعادة الإعداد السابق

كل تشغيل لأمر التثبيت يحتفظ بالإعداد القديم بجانب الجديد:

```bash theme={null}
ls ~/.codex/*.bak.*
cp ~/.codex/config.toml.bak.20260925143000 ~/.codex/config.toml
```

مع الأداة اختر **Reset** وستُستعاد تلقائياً.

## أسئلة شائعة

### كيف أغير المفاتيح

أعد تشغيل [أمر تثبيت Codex](/ar/setup/codex) بالمفتاح الجديد، أو أعد تشغيل الأداة. لـ Cursor وCline وChatbox، عدِّل حقل API Key في الإعدادات.

### هل من الآمن تشغيل أمر التثبيت عدة مرات

نعم. صُمِّم لإعادة التشغيل: الإعداد القديم يُحفظ كـ `.bak.<timestamp>`، يُرقَّى CLI، ويُستبدل سطر المفتاح القديم في shell rc.

### هل يرسل الأمر مفتاحي في أي مكان

لا. تلصق المفتاح في الأمر على جهازك؛ يكتب فقط متغير بيئة وملف إعداد محلي. الأمر كاملاً معروض في الصفحة، اقرأ كل سطر قبل التشغيل.

### إزالة كل شيء

انظر **Uninstall** في صفحة [Codex](/ar/setup/codex). للتطبيقات الأخرى فقط احذف المفتاح من إعدادات التطبيق.

## لا يزال لا يعمل

<Steps>
  <Step title="هل المفتاح حي">
    الصقه في [صفحة التحقق](https://gpt.teamsoclo.site/check). الخطأ هنا يعني المفتاح (خاطئ، منتهٍ، نفدت الحصة)، لا التطبيق.
  </Step>

  <Step title="استدعِ الواجهة البرمجية مباشرة بـ cURL">
    ```bash theme={null}
    curl https://gpt.teamsoclo.site/v1/chat/completions \
      -H "Authorization: Bearer sk-xxx" \
      -H "Content-Type: application/json" \
      -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"hi"}]}'
    ```

    إن نجح هذا والتطبيق لا، المشكلة في إعداد التطبيق.
  </Step>

  <Step title="أعد التحقق من ثلاثة أشياء في التطبيق">
    Base URL ينتهي بـ `/v1`، المفتاح كامل، النموذج يطابق باقتك. هذه تتسبب في تقريباً كل مشكلة.
  </Step>

  <Step title="تواصل مع الدعم">
    أرسل لقطة شاشة للخطأ وآخر 4 أحرف من مفتاحك إلى [t.me/teamsoclo](https://t.me/teamsoclo). لا ترسل المفتاح كاملاً أبداً.
  </Step>
</Steps>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.