# یکپارچه‌سازی Hermes Agent

> **آخرین بازبینی**: 2026-09-18 · 📄 طبق مستندات رسمی (Hermes Agent v0.21.3 / tag v2026.9.14، منتشر شده در 2026-09-14)

## در یک نگاه

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (پروتکل Anthropic) · GPT ✅ · مدل‌های چینی ✅ · Gemini ❌ (هیچ آداپتور Gemini در فهرست مقادیر رسمی transport وجود ندارد) |
| پروتکل و 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` توسط پروژه حذف شده است.

## راه‌اندازی

### مسیر A: ارائه‌دهنده‌های نام‌دار (توصیه‌شده؛ 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 فقط زمانی transport را به‌طور خودکار تشخیص می‌دهد که URL ارائه‌دهنده به `/anthropic` ختم شود؛ `api.qcode.cc/api` **باعث تشخیص نمی‌شود**، بنابراین `transport` باید صریحاً نوشته شود.

### مسیر B: نقطه پایانی واحد (فقط نقطه پایانی سازگار با 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: enum رسمی transport آداپتر Gemini ندارد، بنابراین مدل‌های `gemini-*` در دسترس نیستند.
- `OPENAI_BASE_URL` QCode را به هیچ جایی هدایت نمی‌کند: مستندات می‌گویند این متغیر فقط برای ارائه‌دهنده `openai-api` رعایت می‌شود. از `config.yaml` استفاده کنید.
- سقف توکن‌های خروجی قابل پیکربندی نیست: 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)