# تكامل Hermes Agent

> **آخر تحقق**: 2026-09-18 · 📄 وفقًا للوثائق الرسمية (Hermes Agent v0.21.3 / الوسم v2026.9.14، صدر في 2026-09-14)

## نظرة سريعة

| العنصر | التفاصيل |
|---|---|
| النماذج المتاحة للاستخدام | Claude ✅ (بروتوكول Anthropic) · GPT ✅ · النماذج الصينية ✅ · Gemini ❌ (لا يوجد محوّل Gemini في تعداد النقل الرسمي) |
| البروتوكول وBase URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| مكان الإعداد | `~/.hermes/config.yaml` (توجد المفاتيح في `~/.hermes/.env`)؛ تثبيتات Windows الأصلية ضمن `%LOCALAPPDATA%\hermes` |
| الوثائق الرسمية | [المزوّدون](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/integrations/providers.md) |

Hermes Agent هو **وكيل ذكاء اصطناعي عام** بنته Nous Research (يتعلم المهارات من الخبرة): واجهة TUI طرفية بالإضافة إلى بوابة متعددة القنوات لـ Telegram / Discord / Slack / CLI. **إنه ليس محرر أكواد** — رغم أنه يمكنه العمل كخادم ACP خلف محررات متوافقة مع ACP (راجع [نظرة عامة على ACP](/docs/ide/acp)). توجد جميع نقاط نهاية النماذج في `config.yaml` الخاص به، بشكل مستقل عن أي محرر مضيف.

## المتطلبات المسبقة

- تثبيت Hermes Agent (اتبع [README الرسمي](https://github.com/NousResearch/hermes-agent)؛ لا تكرر هذه الصفحة أوامر التثبيت).
- مفتاح `cr_` من QCode.cc ([لوحة التحكم](https://qcode.cc/dashboard)). لا حاجة إلى حساب Nous Portal أو حساب مزوّد نموذج.
- اعرف تقسيم المسؤوليات: الأسرار توضع في `~/.hermes/.env`، وإعدادات السلوك في `config.yaml`. `config.yaml` هو المصدر الوحيد للحقيقة للنموذج ونقطة النهاية — وقد أزال المشروع متغير البيئة القديم `LLM_MODEL`.

## الإعداد

### المسار أ: مزوّدون مسمّون (موصى به؛ Claude وGPT/النماذج الصينية جنبًا إلى جنب)

في `~/.hermes/config.yaml`:

```yaml
# ~/.hermes/config.yaml
model:
  provider: custom:qcode_claude
  default: claude-sonnet-5

providers:
  qcode_claude:
    api: https://api.qcode.cc/api
    key_env: QCODE_API_KEY
    transport: anthropic_messages
    default_model: claude-sonnet-5
    discover_models: false
  qcode_openai:
    api: https://api.qcode.cc/openai/v1
    key_env: QCODE_API_KEY
    transport: chat_completions
    default_model: glm-5.3
```

ثم ضع المفتاح في `~/.hermes/.env`:

```text
# ~/.hermes/.env
QCODE_API_KEY=cr_your-QCode-key
```

نقاط أساسية (كلها من وثيقة المزوّدين الرسمية):

- لقيمة `transport` ثلاث قيم أساسية فقط: `chat_completions` / `anthropic_messages` / `codex_responses` (بحروف صغيرة وشرطات سفلية). يجب أن تستخدم نماذج Claude على QCode القيمة `anthropic_messages`.
- مفتاح URL في كل إدخال مزوّد هو `api` في الأمثلة الرسمية (`base_url` / `url` اسمان بديلان مقبولان)؛ ومفتاح البروتوكول هو `transport` (`api_mode` هو الاسم البديل).
- يحدد `key_env` اسم متغير بيئة (من دون `$`)؛ وتوجد قيمته في `.env`.
- يكتشف Hermes آلية النقل تلقائيًا فقط عندما ينتهي URL المزوّد بـ `/anthropic`؛ ولا يفعّل `api.qcode.cc/api` الاكتشاف، لذا يجب كتابة `transport` صراحةً.

### المسار ب: نقطة نهاية واحدة (نقطة نهاية متوافقة مع OpenAI فقط)

لتشغيل GPT / النماذج الصينية أولًا، استخدم الصيغة الرسمية المسطحة (`provider: custom` = أي نقطة نهاية متوافقة مع OpenAI):

```yaml
model:
  provider: custom
  base_url: https://api.qcode.cc/openai/v1
  api_key: cr_your-QCode-key
  default: gpt-5.6-sol
```
## تبديل النماذج أثناء الجلسة

```text
/model custom:qcode_claude:<model-id>
/model custom:qcode_openai:<model-id>
```

`<model-id>` هو أي معرّف نموذج أعلنت عنه لهذا المزوّد (نقطة نهاية Claude مثل `claude-sonnet-5`، ونقطة نهاية OpenAI مثل `glm-5.3`).

التوزيع الرسمي للمهام: يبدّل `/model` فقط بين المزوّدين والنماذج التي قمت بإعدادها مسبقًا؛ **تتطلب إضافة مزوّد الخروج من الجلسة وتشغيل معالج `hermes model`**.

## التحقق من أنه يعمل

شغّل `hermes` واسأل عن أي شيء. إذا فشل، فتحقق بالترتيب:

1. هل يصل المسار والمفتاح (نقطة نهاية OpenAI):

```bash
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $QCODE_API_KEY"
# → 401 = key invalid; 400 = path fine (missing body is expected)
```

2. مسافة بادئة YAML لمدخلات `providers:` (مسافتان، كعناصر شقيقة).
3. تتطابق أسماء `key_env` مع `.env` تمامًا.
4. يُسجّل كل طلب في [probe.qcode.cc](https://probe.qcode.cc)؛ هل ما زلت تواجه مشكلة؟ استخدم [دليل استكشاف الأخطاء وإصلاحها](/docs/reference/troubleshooting).

## القيود المعروفة

- **نقطة نهاية Anthropic لم تُختبر في بيئة حية**: يستخدم كل مثال رسمي لـ `anthropic_messages` عنوان URL لمضيف + بادئة **دون `/v1`** (مثل `https://proxy.example.com/anthropic`)، لذلك تستخدم هذه الصفحة `https://api.qcode.cc/api`؛ ولم نتحقق من كيفية بناء Hermes للمسار النهائي. إذا أعادت الطلبات 404، فاضبط `api` على المسار الكامل `https://api.qcode.cc/api/v1/messages` بدلًا من ذلك.
- `discover_models: false`: يستكشف Hermes المسار `<base>/models` على نقاط النهاية المخصصة. هذا المسار موجود على نقطة نهاية OpenAI لدى QCode، لكن `/api/models` غير موجود (404، مُختبَر) — عطّل الاستكشاف في مدخل Claude كما هو موضّح، وسمّ النماذج عبر `default_model` / `models`.
- لا توجّه النماذج الصينية عبر `codex_responses` — نقطة نهاية Responses لدى QCode تخدم نماذج GPT فقط (المصفوفة: [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths)).
- لا يوجد دعم لـ Gemini: لا يتضمن تعداد وسائل النقل الرسمي أي محوّل لـ Gemini، لذا فإن نماذج `gemini-*` غير متاحة.
- لن يوجّه `OPENAI_BASE_URL` QCode إلى أي وجهة: تنص الوثائق على أنه يُعتمد فقط مع المزوّد `openai-api`. استخدم `config.yaml`.
- لا يمكن ضبط حدود token الإخراج: توقّف Hermes عن قراءة `model.max_tokens` وما شابهها، لذا فإن الدروس القديمة متقادمة.

## الوثائق ذات الصلة

- [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths)
- [نظرة عامة على توافق الأدوات](/docs/ide/tool-compatibility)
- [نظرة عامة على ACP](/docs/ide/acp)
- [النماذج الصينية](/docs/usage/cn-models)
- [استكشاف الأخطاء وإصلاحها](/docs/reference/troubleshooting)