OmniRoute/docs/i18n/fa/docs/guides/USER_GUIDE.md

User Guide (فارسی)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 زبانها: 🇺🇸 انگلیسی | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

راهنمای کامل پیکربندی ارائهدهندگان، ایجاد ترکیبها، یکپارچهسازی ابزارهای CLI و استقرار OmniRoute.

---

فهرست مطالب

• نگاهی سریع به قیمتگذاری
• موارد استفاده
• راهاندازی ارائهدهنده
• یکپارچهسازی CLI
• استقرار
• مدلهای موجود
• قابلیتهای پیشرفته
• مسیریابی خودکار (بدون پیکربندی)
• یکپارچهسازی MCP و A2A
• سیستم مهارتها
• سیستم حافظه
• وبهوکها
• عاملهای ابری
• مدیریت برنامهنویسیشده
• CLI داخلی
• برنامه دسکتاپ (Electron)

---

💰 نگاهی سریع به قیمتگذاری

سطح	ارائهدهنده	هزینه	بازنشانی سهمیه	بهترین کاربرد
💳 اشتراکی	Claude Code (Pro)	$20/ماه	۵ ساعت + هفتگی	کسانی که از قبل اشتراک دارند
	Codex (Plus/Pro)	$20-200/ماه	۵ ساعت + هفتگی	کاربران OpenAI
	GitHub Copilot	$10-19/ماه	ماهانه	کاربران GitHub
🔑 کلید API	DeepSeek	پرداخت بهازای مصرف	ندارد	استدلال ارزان
	Groq	پرداخت بهازای مصرف	ندارد	استنتاج فوقسریع
	xAI (Grok)	پرداخت بهازای مصرف	ندارد	استدلال Grok 4
	Mistral	پرداخت بهازای مصرف	ندارد	مدلهای میزبانیشده در اتحادیه اروپا
	Perplexity	پرداخت بهازای مصرف	ندارد	تقویتشده با جستوجو
	Together AI	پرداخت بهازای مصرف	ندارد	مدلهای متنباز
	Fireworks AI	پرداخت بهازای مصرف	ندارد	تصاویر سریع FLUX
	Cerebras	پرداخت بهازای مصرف	ندارد	سرعت در مقیاس ویفر
	Cohere	پرداخت بهازای مصرف	ندارد	RAG با Command R+
	NVIDIA NIM	پرداخت بهازای مصرف	ندارد	مدلهای سازمانی
	Baidu Qianfan	پرداخت بهازای مصرف	ندارد	مدلهای ERNIE
💰 ارزان	GLM-4.7	$0.6/1M	روزانه ساعت ۱۰ صبح	پشتیبان اقتصادی
	MiniMax M2.1	$0.2/1M	دوره چرخشی ۵ ساعته	ارزانترین گزینه
	Kimi K2	ثابت $9/ماه	10M توکن/ماه	هزینه قابل پیشبینی
🆓 رایگان	Qoder	$0	محدودیتهای ارائهدهنده اعمال میشود	فهرست فعلی را بررسی کنید
	Kiro	$0	حدود ۵۰ اعتبار/ماه	Claude رایگان

---

🎯 موارد استفاده

مورد ۱: «اشتراک Claude Pro دارم»

مشکل: سهمیه بدون استفاده منقضی میشود و هنگام کدنویسی سنگین با محدودیت نرخ مواجه میشوم

ترکیب: "maximize-claude"
  1. cc/claude-opus-4-7        (استفاده کامل از اشتراک)
  2. glm/glm-4.7               (پشتیبان ارزان هنگام اتمام سهمیه)
  3. if/qwen3.8-max-preview       (گزینه جایگزین رایگان برای مواقع اضطراری)

هزینه ماهانه: $20 (اشتراک) + حدود $5 (پشتیبان) = در مجموع $25
در مقایسه با $20 + برخورد با محدودیتها = کلافگی

مورد ۲: «هزینه صفر میخواهم»

مشکل: توان پرداخت هزینه اشتراکها را ندارم و به هوش مصنوعی قابلاعتماد برای کدنویسی نیاز دارم

ترکیب: "zero-cost"
  1. if/kimi-k2.7-code          (دسترسی رایگان فهرستشده؛ ممکن است محدودیت نرخ اعمال شود)
  2. kr/qwen3-coder-next        (گزینه جایگزین رایگان Kiro)

هزینه ماهانه: $0
کیفیت: مدل، محدودیتها، حریم خصوصی و SLA را برای حجم کاری خود بررسی کنید

مورد ۳: «به کدنویسی شبانهروزی و بدون وقفه نیاز دارم»

مشکل: مهلتهای تحویل دارم و نمیتوانم قطعی سرویس را تحمل کنم

ترکیب: "always-on"
  1. cc/claude-opus-4-7        (بهترین کیفیت)
  2. cx/gpt-5.5                (اشتراک دوم)
  3. glm/glm-4.7               (ارزان، بازنشانی روزانه)
  4. minimax/MiniMax-M2.1      (ارزانترین، بازنشانی ۵ ساعته)
  5. if/deepseek-v4-flash       (دسترسی رایگان فهرستشده؛ ممکن است محدودیت نرخ اعمال شود)

نتیجه: ۵ لایه جایگزین، تابآوری را افزایش میدهند؛ در دسترس بودن سرویسهای بالادستی تضمینشده نیست
هزینه ماهانه: $20-200 (اشتراکها) + $10-20 (پشتیبان)

مورد ۴: «در OpenClaw هوش مصنوعی رایگان میخواهم»

مشکل: به یک دستیار هوش مصنوعی در برنامههای پیامرسان نیاز دارم که کاملاً رایگان باشد

ترکیب: "openclaw-free"
  1. if/qwen3.8-max-preview     (دسترسی رایگان فهرستشده؛ ممکن است محدودیت نرخ اعمال شود)
  2. if/deepseek-v4-flash       (دسترسی رایگان فهرستشده؛ ممکن است محدودیت نرخ اعمال شود)
  3. if/kimi-k2.7-code          (دسترسی رایگان فهرستشده؛ ممکن است محدودیت نرخ اعمال شود)

هزینه ماهانه: $0
دسترسی از طریق: WhatsApp، Telegram، Slack، Discord، iMessage، Signal...

---

📖 راهاندازی ارائهدهنده

برای افزودن گروهی اتصالهای کلید API از یک فایل CSV یا JSON، از مسیر داشبورد → ارائهدهندگان → وارد کردن از فایل استفاده کنید. ترتیب ستونها ثابت است (provider,name,apiKey,baseUrl,priority)؛ مقدار provider باید از قبل بهعنوان یک ارائهدهنده مدیریتشده یا یک گره سازگار وجود داشته باشد. به وارد کردن ارائهدهندگان از یک فایل CSV یا JSON مراجعه کنید.

🔐 ارائهدهندگان اشتراکی

Claude Code (Pro/Max)

داشبورد → ارائهدهندگان → اتصال Claude Code
→ ورود با OAuth → نوسازی خودکار توکن
→ پایش سهمیه ۵ ساعته و هفتگی

مدلها:
  cc/claude-opus-4-7
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001

نکته حرفهای: برای وظایف پیچیده از Opus و برای سرعت از Sonnet استفاده کنید. OmniRoute سهمیه را بهازای هر مدل پایش میکند!

مسیرهای سازگار با Claude و Claude Code، سطح تلاش تفکر max را برای مدلهای Opus و Sonnet حفظ میکنند. مدلهای Haiku سطح تلاش max را نمیپذیرند؛ بنابراین OmniRoute پیش از ارسال درخواست به سرویس بالادستی، آن را به بودجه تفکر بالا تنزل میدهد.

OpenAI Codex (Plus/Pro)

داشبورد → ارائهدهندگان → اتصال Codex
→ ورود با OAuth (درگاه 1455)
→ بازنشانی ۵ ساعته و هفتگی

مدلها:
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.3-codex-spark

GitHub Copilot

داشبورد → ارائهدهندگان → اتصال GitHub
→ OAuth از طریق GitHub
→ بازنشانی ماهانه (روز اول ماه)

مدلها:
  gh/gpt-5.5
  gh/gpt-5.4
  gh/claude-sonnet-4.6
  gh/claude-opus-4.7
  gh/gemini-3.1-pro-preview

💰 ارائهدهندگان ارزان

GLM-4.7 (بازنشانی روزانه، $0.6/1M)

1. ثبتنام کنید: Zhipu AI
2. کلید API را از Coding Plan دریافت کنید
3. داشبورد → افزودن کلید API: ارائهدهنده: glm، کلید API: your-key

استفاده: glm/glm-4.7 — نکته حرفهای: Coding Plan با یکهفتم هزینه، ۳ برابر سهمیه ارائه میدهد! بازنشانی روزانه ساعت ۱۰:۰۰ صبح انجام میشود.

MiniMax M2.1 (بازنشانی ۵ ساعته، $0.20/1M)

1. ثبتنام کنید: MiniMax
2. کلید API را دریافت کنید → داشبورد → افزودن کلید API

استفاده: minimax/MiniMax-M2.1 — نکته حرفهای: ارزانترین گزینه برای زمینههای طولانی (۱ میلیون توکن)!

Kimi K2 (هزینه ثابت $9/ماه)

1. اشتراک تهیه کنید: Moonshot AI
2. کلید API را دریافت کنید → داشبورد → افزودن کلید API

استفاده: kimi/kimi-k2.5 — نکته حرفهای: هزینه ثابت $9/ماه برای ۱۰ میلیون توکن، یعنی هزینه مؤثر $0.90/1M!

Baidu Qianfan / ERNIE

1. ثبتنام کنید: Baidu AI Cloud Qianfan
2. یک کلید API برای Qianfan ایجاد کنید → داشبورد → افزودن کلید API: ارائهدهنده: qianfan

استفاده: qianfan/ernie-5.1، qianfan/ernie-x1.1 یا شناسه مدل دیگری از Qianfan که با OpenAI سازگار باشد.

🆓 ارائهدهندگان رایگان

ارائهدهندگان رایگان و بدون احراز هویت، در صفحه ارائهدهنده خود کلیدی در کنار بدون نیاز به احراز هویت دارند. خاموش کردن آن، ارائهدهنده را غیرفعال میکند، آن را از نماهای پیکربندیشده/فشرده ارائهدهندگان حذف میکند و مدلهایش را از /v1/models برمیدارد.

Qoder (۹ مدل رایگان)

داشبورد → اتصال Qoder → ورود با OAuth → دسترسی مشمول محدودیتهای فعلی ارائهدهنده است

مدلها: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3

Kiro (Claude رایگان)

داشبورد → اتصال Kiro → AWS Builder ID یا Google/GitHub → حدود ۵۰ اعتبار در ماه

مدلها: kr/claude-sonnet-4.5, kr/claude-haiku-4.5

---

🎨 ترکیبها

میتوانید کارتهای ترکیب را مستقیماً در داشبورد → ترکیبها با کشیدن دستگیرهٔ هر کارت مرتب کنید. ترتیب در SQLite ذخیره میشود و پس از بارگذاری مجدد بازیابی خواهد شد.

مثال ۱: بهحداکثررساندن اشتراک → پشتیبان ارزان

داشبورد → ترکیبها → ایجاد مورد جدید

نام: premium-coding
مدلها:
  1. cc/claude-opus-4-7 (مدل اصلی اشتراکی)
  2. glm/glm-4.7 (پشتیبان ارزان، $0.6/1M)
  3. minimax/MiniMax-M2.7 (ارزانترین گزینهٔ جایگزین، $0.3/1M)

استفاده در CLI: premium-coding

مثال ۲: فقط رایگان (بدون هزینه)

نام: free-combo
مدلها:
  1. if/kimi-k2.7-code (دسترسی رایگان فهرستشده؛ ممکن است محدودیتهای ارائهدهنده اعمال شوند)
  2. kr/qwen3-coder-next (گزینهٔ جایگزین رایگان Kiro)

هزینه: در حال حاضر بهصورت $0 فهرست شده است؛ شرایط و دسترسپذیری ممکن است تغییر کنند

---

🔧 یکپارچهسازی CLI

Cursor IDE

استفاده از Cursor بهعنوان کلاینت OmniRoute (هدایت گفتوگوی Cursor از طریق OmniRoute):

تنظیمات → مدلها → پیشرفته:
  نشانی پایهٔ OpenAI API: http://localhost:20128/v1
  کلید OpenAI API: [از داشبورد omniroute]
  مدل: cc/claude-opus-4-7

استفاده از OmniRoute بهعنوان ارائهدهندهٔ Cursor (OmniRoute سرویس بالادستی Cursor را فراخوانی میکند): ترجیحاً از داشبورد → ارائهدهندگان → Cursor → ورود با Cursor استفاده کنید. در Docker، به docs/providers/CURSOR-DOCKER.md مراجعه کنید.

Claude Code

فایل ~/.claude/settings.json را ویرایش کنید:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
  }
}

در اینجا از نقطهٔ پایانی ریشهٔ سازگار با Claude استفاده کنید. /v1 را به ANTHROPIC_BASE_URL اضافه نکنید.

Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"

OpenClaw

فایل ~/.openclaw/openclaw.json را ویرایش کنید:

{
  "agents": {
    "defaults": {
      "model": { "primary": "omniroute/if/kimi-k2.7-code" }
    }
  },
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://localhost:20128/v1",
        "apiKey": "your-omniroute-api-key",
        "api": "openai-completions",
        "models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
      }
    }
  }
}

یا از داشبورد استفاده کنید: ابزارهای CLI → OpenClaw → پیکربندی خودکار

Cline / Continue / RooCode

ارائهدهنده: سازگار با OpenAI
نشانی پایه: http://localhost:20128/v1
کلید API: [از داشبورد]
مدل: cc/claude-opus-4-7

---

🚀 استقرار

نصب سراسری npm (توصیهشده)

npm install -g omniroute

# ایجاد پوشهٔ پیکربندی
mkdir -p ~/.omniroute

# ایجاد فایل .env (به .env.example مراجعه کنید)
cp .env.example ~/.omniroute/.env

# راهاندازی سرور
omniroute
# یا با درگاه سفارشی:
omniroute --port 3000

CLI بهطور خودکار .env را از ~/.omniroute/.env یا ./.env بارگذاری میکند.

حالت سینی سیستم

OmniRoute را در سینی سیستم اجرا کنید:

omniroute serve --tray

پس از آمادهشدن سرور و سینی سیستم، فرمان خاتمه مییابد.

سرور بدون ترمینال به کار خود ادامه میدهد.

حالت سینی سیستم از macOS، Windows و نشستهای گرافیکی Linux پشتیبانی میکند. حالت سینی سیستم داشبورد را بهطور خودکار باز نمیکند.

برای انجام اقدامات زیر از منوی سینی سیستم استفاده کنید:

• بازکردن داشبورد.
• بازکردن /dashboard/logs.
• تغییر راهاندازی خودکار.
• توقف OmniRoute.

از --tray همراه با گزینههای زیر استفاده نکنید:

• --daemon
• --log
• --no-recovery

این حالتها به مالکیت فرایند متفاوتی نیاز دارند.

راهاندازی در ورود بعدی به سیستم را فعال کنید:

omniroute autostart enable

راهاندازی خودکار در macOS، Windows و نشستهای گرافیکی Linux از حالت سینی سیستم استفاده میکند. Linux بدون رابط گرافیکی از سرویس کاربری systemd موجود استفاده میکند.

راهاندازی در هنگام ورود را غیرفعال کنید:

omniroute autostart disable

حذف نصب

هنگامی که دیگر به OmniRoute نیاز ندارید، دو اسکریپت سریع برای حذف کامل ارائه میکنیم:

فرمان	عملکرد
npm run uninstall	برنامهٔ سیستم را حذف میکند، اما پایگاه داده و پیکربندیهای شما را در ~/.omniroute نگه میدارد.
npm run uninstall:full	برنامه را حذف میکند و همچنین تمام پیکربندیها، کلیدها و پایگاههای داده را برای همیشه پاک میکند.

نکته: برای اجرای این فرمانها، به پوشهٔ پروژهٔ OmniRoute بروید (اگر آن را کلون کردهاید) و فرمانها را اجرا کنید. در غیر این صورت، اگر بهصورت سراسری نصب شده است، میتوانید بهسادگی npm uninstall -g omniroute را اجرا کنید.

استقرار روی VPS

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build

export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"

npm run start
# یا: pm2 start npm --name omniroute -- start

استقرار با PM2 (حافظهٔ کم)

برای سرورهایی با RAM محدود، از گزینهٔ محدودیت حافظه استفاده کنید:

# با محدودیت 512MB (پیشفرض)
pm2 start npm --name omniroute -- start

# یا با محدودیت حافظهٔ سفارشی
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# یا با استفاده از ecosystem.config.js
pm2 start ecosystem.config.js

فایل ecosystem.config.js را ایجاد کنید:

module.exports = {
  apps: [
    {
      name: "omniroute",
      script: "npm",
      args: "start",
      env: {
        NODE_ENV: "production",
        OMNIROUTE_MEMORY_MB: "512",
        JWT_SECRET: "your-secret",
        INITIAL_PASSWORD: "your-password",
      },
      node_args: "--max-old-space-size=512",
      max_memory_restart: "300M",
    },
  ],
};

Docker

# ساخت ایمیج (پیشفرض = runner-cli با codex/claude/droid ازپیشنصبشده)
docker build -t omniroute:cli .

# حالت قابلحمل (توصیهشده)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli

برای حالت یکپارچه با میزبان و دارای فایلهای اجرایی CLI، به بخش Docker در مستندات اصلی مراجعه کنید.

Void Linux (xbps-src)

کاربران Void Linux میتوانند OmniRoute را با استفاده از چارچوب کامپایل متقابل xbps-src بهصورت بومی بستهبندی و نصب کنند. این چارچوب، ساخت مستقل Node.js را همراه با بایندینگهای بومی موردنیاز better-sqlite3 خودکار میکند.

مشاهده قالب xbps-src

# فایل قالب برای 'omniroute'
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false

do_build() {
	# تعیین معماری CPU هدف برای node-gyp
	local _gyp_arch
	case "$XBPS_TARGET_MACHINE" in
		aarch64*) _gyp_arch=arm64 ;;
		armv7*|armv6*) _gyp_arch=arm ;;
		i686*) _gyp_arch=ia32 ;;
		*) _gyp_arch=x64 ;;
	esac

	# 1) نصب تمام وابستگیها – بدون اجرای اسکریپتها
	NODE_ENV=development npm ci --ignore-scripts

	# 2) ساخت بسته مستقل Next.js
	npm run build

	# 3) کپیکردن داراییهای ایستا در بسته مستقل
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) کامپایل بایندینگ بومی better-sqlite3
	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")

	# 5) قراردادن بایندینگ کامپایلشده در بسته مستقل
	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
	mkdir -p "$_bs3_release"
	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"

	# 6) حذف بستههای sharp مختص معماری
	rm -rf .next/standalone/node_modules/@img

	# 7) کپیکردن وابستگیهای زمان اجرای pino که توسط تحلیل ایستای Next.js حذف شدهاند:
	for _mod in pino-abstract-transport split2 process-warning; do
		cp -r "node_modules/$_mod" .next/standalone/node_modules/
	done
}

do_check() {
	npm run test:unit
}

do_install() {
	vmkdir usr/lib/omniroute/.next
	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

	# جلوگیری از حذف دایرکتوریهای خالی مسیریاب برنامه Next.js توسط هوک پس از نصب
	for _d in \
		.next/standalone/.next/server/app/dashboard \
		.next/standalone/.next/server/app/dashboard/settings \
		.next/standalone/.next/server/app/dashboard/providers; do
		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
	done

	cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
	vbin "${WRKDIR}/omniroute"
}

post_install() {
	vlicense LICENSE
}

متغیرهای محیطی

متغیر	مقدار پیشفرض	توضیحات
JWT_SECRET	omniroute-default-secret-change-me	کلید محرمانه امضای JWT (در محیط عملیاتی تغییر دهید)
INITIAL_PASSWORD	CHANGEME	رمز عبور اولین ورود
DATA_DIR	~/.omniroute	دایرکتوری دادهها (پایگاه داده، میزان استفاده، گزارشها)
PORT	پیشفرض چارچوب	درگاه سرویس (20128 در مثالها)
HOSTNAME	پیشفرض چارچوب	میزبان اتصال (مقدار پیشفرض Docker برابر با 0.0.0.0 است)
NODE_ENV	پیشفرض زمان اجرا	برای استقرار روی production تنظیم کنید
NEXT_PUBLIC_BASE_URL	http://localhost:20128	URL پایه عمومی که در داشبورد نمایش داده شده و در اختیار سرور قرار میگیرد (جایگزین BASE_URL قدیمی)
NEXT_PUBLIC_CLOUD_URL	https://omniroute.dev	URL پایه نقطه پایانی همگامسازی ابری (جایگزین CLOUD_URL قدیمی)
API_KEY_SECRET	endpoint-proxy-api-key-secret	کلید محرمانه HMAC برای کلیدهای API تولیدشده
REQUIRE_API_KEY	false	الزام کلید API از نوع Bearer برای /v1/*
ALLOW_API_KEY_REVEAL	false	اجازه به کاربران احراز هویتشده داشبورد برای نمایش مقادیر کامل کلیدهای API ذخیرهشده در صورت درخواست
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES	70	تناوب بهروزرسانی سمت سرور برای دادههای ذخیرهشده محدودیتهای ارائهدهنده؛ دکمههای تازهسازی رابط کاربری همچنان همگامسازی دستی را آغاز میکنند
DISABLE_SQLITE_AUTO_BACKUP	false	غیرفعالسازی اسنپشاتهای خودکار SQLite پیش از نوشتن/درونریزی/بازیابی؛ پشتیبانگیری دستی همچنان کار میکند
APP_LOG_TO_FILE	true	خروجی گزارشهای برنامه و ممیزی روی دیسک را فعال میکند
AUTH_COOKIE_SECURE	false	اجبار ویژگی Secure برای کوکی احراز هویت (پشت پراکسی معکوس HTTPS)
CLOUDFLARED_BIN	تنظیمنشده	استفاده از باینری موجود cloudflared بهجای دانلود مدیریتشده
CLOUDFLARED_PROTOCOL	http2	روش انتقال برای Quick Tunnels مدیریتشده (http2، quic یا auto)
OMNIROUTE_MEMORY_MB	512	محدودیت حافظه heap در Node.js بر حسب MB
PROMPT_CACHE_MAX_SIZE	50	حداکثر تعداد ورودیهای کش پرامپت
SEMANTIC_CACHE_MAX_SIZE	100	حداکثر تعداد ورودیهای کش معنایی

برای مرجع کامل متغیرهای محیطی، به README مراجعه کنید.

---

📊 مدلهای موجود

مشاهده همه مدلهای موجود

فهرست زیر از open-sse/config/providerRegistry.ts برای v3.8.0 گردآوری شده است. کاتالوگهای ابری (Gemini، OpenRouter و غیره) بهصورت پویا همگامسازی میشوند — برای مشاهده کامل کاتالوگ زنده، به داشبورد → ارائهدهندگان → [ارائهدهنده] → مدلهای موجود بروید یا GET /api/models/catalog را فراخوانی کنید.

اگر فهرست داخلی یک ارائهدهنده قدیمی شده است، در همان صفحه از وارد کردن از ‎/models استفاده کنید (یا همگامسازی خودکار را فعال کنید) تا کاتالوگ زنده بالادستی دریافت شود. این قابلیت در v3.8.50 برای LLM7.io (gemini-3.1-flash-lite) و UncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ) تأیید شده است؛ دسترسی ناشناس Pollinations در همان مرحله آزمایش همچنان از سمت سرویس بالادستی محدود بود.

Claude Code (cc/) — OAuth پلن Pro/Max: cc/claude-opus-4-8، cc/claude-opus-4-7، cc/claude-opus-4-6، cc/claude-opus-4-5-20251101، cc/claude-sonnet-4-6، cc/claude-sonnet-4-5-20250929، cc/claude-haiku-4-5-20251001

Codex (cx/) — OAuth پلن Plus/Pro: cx/gpt-5.5 (+ سطوح تلاش: gpt-5.5-xhigh، gpt-5.5-high، gpt-5.5-medium، gpt-5.5-low)، cx/gpt-5.4، cx/gpt-5.4-mini، cx/gpt-5.3-codex، cx/gpt-5.3-codex-spark

GitHub Copilot (gh/) — OAuth: gh/gpt-5.5، gh/gpt-5.4، gh/gpt-5.4-mini، gh/gpt-5-mini، gh/gpt-5.3-codex، gh/claude-opus-4.7، gh/claude-opus-4.6، gh/claude-opus-4-5-20251101، gh/claude-sonnet-4.6، gh/claude-sonnet-4.5، gh/claude-haiku-4.5، gh/gemini-3.1-pro-preview، gh/gemini-3-flash-preview، gh/oswe-vscode-prime

Kiro (kr/) — OAuth رایگان: از کاتالوگ زنده نمایشدادهشده در داشبورد → ارائهدهندگان → Kiro → مدلهای موجود استفاده کنید. دسترسپذیری به حساب و پلن بستگی دارد.

Qoder (if/) — OAuth رایگان: if/qwen3.8-max-preview، if/qwen3.7-max، if/qwen3.7-plus، if/kimi-k3، if/kimi-k2.7-code، if/glm-5.2، if/deepseek-v4-pro، if/deepseek-v4-flash، if/minimax-m3

GLM (glm/, glm-cn/, zai/, glmt/) — ۰٫۲ تا ۰٫۶ دلار بهازای هر ۱ میلیون: glm/glm-5.1، glm/glm-5، glm/glm-5-turbo، glm/glm-4.7، glm/glm-4.7-flash، glm/glm-4.6، glm/glm-4.6v، glm/glm-4.5، glm/glm-4.5v، glm/glm-4.5-air

MiniMax (minimax/, minimax-cn/) — ۰٫۲ دلار بهازای هر ۱ میلیون: minimax/MiniMax-M2.7، minimax/MiniMax-M2.7-highspeed، minimax/MiniMax-M2.5، minimax/MiniMax-M2.5-highspeed

Kimi (kimi/, kimi-coding/, kimi-coding-apikey/) — ماهانه ۹ دلار ثابت یا پرداخت بر اساس مصرف: kimi/kimi-k2.6، kimi/kimi-k2.5

DeepSeek (ds/) — کلید API: ds/deepseek-v4-pro، ds/deepseek-v4-flash

Groq (groq/) — فوقسریع: groq/llama-3.3-70b-versatile، groq/meta-llama/llama-4-maverick-17b-128e-instruct، groq/qwen/qwen3-32b، groq/openai/gpt-oss-120b

xAI (xai/) — Grok بومی: xai/grok-4.3، xai/grok-4.20-multi-agent-0309، xai/grok-4.20-0309-reasoning، xai/grok-4.20-0309-non-reasoning

Mistral (mistral/) — میزبانیشده در اتحادیه اروپا: mistral/mistral-large-latest، mistral/mistral-medium-3-5، mistral/mistral-small-latest، mistral/devstral-latest، mistral/codestral-latest

Perplexity (pplx/) — تقویتشده با جستوجو: pplx/sonar-deep-research، pplx/sonar-reasoning-pro، pplx/sonar-pro، pplx/sonar

Together AI (together/) — متنباز: together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free (رایگان)، together/meta-llama/Llama-Vision-Free، together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free، together/deepseek-ai/DeepSeek-R1، together/Qwen/Qwen3-235B-A22B، together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8

Fireworks AI (fireworks/) — استنتاج سریع: fireworks/accounts/fireworks/models/kimi-k2p6، fireworks/accounts/fireworks/models/minimax-m2p7، fireworks/accounts/fireworks/models/qwen3p6-plus، fireworks/accounts/fireworks/models/glm-5p1، fireworks/accounts/fireworks/models/deepseek-v4-pro

Cerebras (cerebras/) — در مقیاس ویفر: cerebras/zai-glm-4.7، cerebras/gpt-oss-120b

Cohere (cohere/) — متمرکز بر RAG: cohere/command-a-reasoning-08-2025، cohere/command-a-vision-07-2025، cohere/command-a-03-2025، cohere/command-r-08-2024

NVIDIA NIM (nvidia/) — سازمانی: nvidia/z-ai/glm-5.1، nvidia/minimaxai/minimax-m2.7، nvidia/google/gemma-4-31b-it، nvidia/mistralai/mistral-small-4-119b-2603، nvidia/mistralai/mistral-large-3-675b-instruct-2512، nvidia/qwen/qwen3.5-397b-a17b، nvidia/deepseek-ai/deepseek-v4-pro، nvidia/openai/gpt-oss-120b، nvidia/nvidia/nemotron-3-super-120b-a12b

Baidu Qianfan (qianfan/) — ERNIE: qianfan/ernie-5.1، qianfan/ernie-5.0-thinking-latest، qianfan/ernie-x1.1

Ollama Cloud (ollama-cloud/): ollama-cloud/deepseek-v4-pro، ollama-cloud/deepseek-v4-flash، ollama-cloud/kimi-k2.6، ollama-cloud/glm-5.1، ollama-cloud/minimax-m2.7، ollama-cloud/gemma4:31b، ollama-cloud/qwen3.5:397b

Gemini (Google Cloud gemini/): بهصورت زنده و بر اساس کلید API با Google همگامسازی میشود — فهرست ثابتی وجود ندارد. در داشبورد → ارائهدهندگان یک کلید متصل کنید، سپس برای وارد کردن کاتالوگ فعلی از مدلهای موجود استفاده کنید (برای نمونه، gemini/gemini-3-pro و gemini/gemini-3-flash).

سایر ارائهدهندگان سازگار (منتخب): cohere، databricks، snowflake، together، vertex، alibaba، alibaba-cn، bedrock (از طریق aws-bedrock)، azure-ai، openrouter (کاتالوگ عبوری)، siliconflow، hyperbolic، huggingface، featherless-ai، cloudflare-ai، scaleway، deepinfra، vercel-ai-gateway، bazaarlink، friendliai، nous-research، reka، volcengine، ai21، gigachat. هرکدام فهرست مدلهای خود را در providerRegistry.ts نگهداری میکنند و هنگامی که ارائهدهنده یک نقطه پایانی /models ارائه دهد، امکان همگامسازی خودکار وجود دارد.

نکته درباره شناسههای مدل: OmniRoute از شناسههای بومی ارائهدهنده (claude-opus-4-8، gpt-5.5، glm-5.1، MiniMax-M2.7، kimi-k2.5، grok-4.20-0309-reasoning) استفاده میکند. برخی شناسهها شامل نسخههای نقطهدار هستند، زیرا API بالادستی آنها را به همین شکل انتظار دارد. اگر مدلی در بالا فهرست نشده است، برای تأیید دسترسپذیری omniroute models --search <term> را اجرا کنید یا GET /api/models/catalog را فراخوانی کنید.

---

🧩 قابلیتهای پیشرفته

مدلهای سفارشی

بدون انتظار برای بهروزرسانی برنامه، هر شناسهٔ مدلی را به هر ارائهدهندهای اضافه کنید:

# از طریق API
curl -X POST http://localhost:20128/api/provider-models \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}'

# فهرست: curl http://localhost:20128/api/provider-models?provider=openai
# حذف: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"

یا از داشبورد استفاده کنید: Providers → [Provider] → Custom Models.

نکات:

• ارائهدهندگان OpenRouter و سازگار با OpenAI/Anthropic فقط از طریق Available Models مدیریت میشوند. افزودن دستی، درونریزی و همگامسازی خودکار، همگی در یک فهرست واحد از مدلهای موجود قرار میگیرند؛ بنابراین برای این ارائهدهندگان بخش جداگانهای با عنوان Custom Models وجود ندارد.
• بخش Custom Models برای ارائهدهندگانی در نظر گرفته شده است که امکان درونریزی مدیریتشدهٔ مدلهای موجود را ارائه نمیکنند.

زنجیرهسازی همتایان OmniRoute

میتوان درگاه OmniRoute دیگری را بهعنوان یک ارائهدهندهٔ سفارشیِ سازگار با OpenAI اضافه کرد. از URL پایهٔ /v1 همتا و یک کلید API اختصاصی با حداقل سطح دسترسی که توسط همان همتا صادر شده است، استفاده کنید.

برای زنجیرههای دوسویه یا چندمرحلهای، محافظ حلقهٔ اختیاری را در همهٔ درگاهها فعال کنید:

# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

# gateway-b
OMNIROUTE_INSTANCE_ID=gateway-b
OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

فقط درخواستهایی که به URL همتایی ارسال میشوند که صراحتاً در فهرست مجاز قرار دارد، سربرگ X-OmniRoute-Peer-Trace را دریافت میکنند. درگاه، شناسهٔ تکراری نمونه یا تمامشدن بودجهٔ تعداد گامها را با HTTP 508 Loop Detected رد میکند؛ ارائهدهندگان بالادستی معمولی هیچ فرادادهای دربارهٔ همتا دریافت نمیکنند.

زنجیرهسازی همتاها بهمعنای تکثیر پایگاهداده یا جایگزینی میزبان هنگام خرابی نیست. هر درگاه، وضعیت SQLite، حافظههای نهان، شمارندههای نرخ و نشستهای مستقل خود را نگه میدارد. برای دسترسپذیری فعال/غیرفعال یا فعال/فعال، از پراکسی معکوس دارای بررسی سلامت یا سازوکار جایگزینی سمت کلاینت استفاده کنید و هرگز یک پایگاهدادهٔ SQLite را همزمان در چند نمونهٔ در حال اجرای OmniRoute متصل نکنید.

مسیرهای اختصاصی ارائهدهنده

درخواستها را همراه با اعتبارسنجی مدل، مستقیماً به یک ارائهدهندهٔ مشخص هدایت کنید:

POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations

اگر پیشوند ارائهدهنده وجود نداشته باشد، بهطور خودکار اضافه میشود. مدلهای ناسازگار خطای 400 برمیگردانند.

پیکربندی پراکسی شبکه

# تنظیم پراکسی سراسری
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'

# پراکسی مختص هر ارائهدهنده
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

# آزمایش پراکسی
curl -X POST http://localhost:20128/api/settings/proxy/test \
  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'

اولویت: مختص کلید → مختص ترکیب → مختص ارائهدهنده → سراسری → محیط.

API فهرست مدلها

curl http://localhost:20128/api/models/catalog

مدلها را بهصورت گروهبندیشده بر اساس ارائهدهنده و همراه با نوع (chat، embedding، image) برمیگرداند.

همگامسازی ابری

• همگامسازی ارائهدهندگان، ترکیبها و تنظیمات بین دستگاهها
• همگامسازی خودکار در پسزمینه با مهلت زمانی و توقف سریع هنگام خطا
• در محیط عملیاتی، NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL سمت سرور را ترجیح دهید

تونل سریع Cloudflare

• برای Docker و سایر استقرارهای خودمیزبان در Dashboard → Endpoints در دسترس است
• یک URL موقت https://*.trycloudflare.com ایجاد میکند که درخواستها را به نقطهٔ پایانی فعلی و سازگار با OpenAI شما در /v1 هدایت میکند
• در اولین فعالسازی، cloudflared فقط در صورت نیاز نصب میشود؛ راهاندازیهای مجدد بعدی از همان فایل اجرایی مدیریتشده استفاده میکنند
• تونلهای سریع پس از راهاندازی مجدد OmniRoute یا کانتینر، بهطور خودکار بازیابی نمیشوند؛ در صورت نیاز، آنها را دوباره از داشبورد فعال کنید
• URLهای تونل موقتی هستند و هر بار که تونل را متوقف و دوباره راهاندازی میکنید، تغییر میکنند
• تونلهای سریع مدیریتشده بهطور پیشفرض از انتقال HTTP/2 استفاده میکنند تا از هشدارهای پرشمار مربوط به بافر UDP در QUIC در کانتینرهای دارای محدودیت جلوگیری شود
• اگر میخواهید انتخاب انتقال مدیریتشده را بازنویسی کنید، CLOUDFLARED_PROTOCOL=quic یا auto را تنظیم کنید
• اگر ترجیح میدهید بهجای دانلود مدیریتشده از فایل اجرایی ازپیشنصبشدهٔ cloudflared استفاده کنید، CLOUDFLARED_BIN را تنظیم کنید
• پنلهای Cloudflare Quick Tunnel، Tailscale Funnel و ngrok Tunnel را میتوان در Settings → Appearance نمایش داد یا پنهان کرد. پنهانکردن یک پنل، تونل در حال اجرا را متوقف نمیکند.

هوشمندی درگاه LLM (مرحلهٔ 9)

• حافظهٔ نهان معنایی — پاسخهای غیرجریانی با temperature=0 را بهطور خودکار در حافظهٔ نهان ذخیره میکند (برای دورزدن آن از X-OmniRoute-No-Cache: true استفاده کنید)
• تکرارناپذیری درخواست — درخواستها را در بازهٔ 5s با استفاده از سربرگ Idempotency-Key یا X-Request-Id حذف تکراری میکند
• ردیابی پیشرفت — رویدادهای اختیاری SSE از نوع event: progress را از طریق سربرگ X-OmniRoute-Progress: true ارائه میدهد

---

محیط آزمایشی مترجم

از طریق Dashboard → Translator به آن دسترسی پیدا کنید. نحوهٔ ترجمهٔ درخواستهای API بین ارائهدهندگان توسط OmniRoute را اشکالزدایی و مصورسازی کنید.

حالت	هدف
Playground	قالبهای مبدأ/مقصد را انتخاب کنید، یک درخواست جایگذاری کنید و خروجی ترجمهشده را فوراً ببینید
Chat Tester	پیامهای زندهٔ چت را از طریق پراکسی ارسال کنید و چرخهٔ کامل درخواست/پاسخ را بررسی کنید
Test Bench	برای تأیید صحت ترجمه، آزمونهای دستهای را روی چندین ترکیب قالب اجرا کنید
Live Monitor	هنگام عبور درخواستها از پراکسی، ترجمهها را بهصورت بلادرنگ مشاهده کنید

موارد استفاده:

• اشکالزدایی علت شکست یک ترکیب مشخص کلاینت/ارائهدهنده
• اطمینان از ترجمهٔ صحیح برچسبهای تفکر، فراخوانی ابزارها و اعلانهای سیستمی
• مقایسهٔ تفاوت قالبها میان OpenAI، Claude، Gemini و قالبهای Responses API

---

راهبردهای مسیریابی

از مسیر داشبورد → تنظیمات → مسیریابی پیکربندی کنید. داشبورد شش راهبرد پرکاربرد را ارائه میدهد؛ ترکیبها و مسیریاب خودکار در داخل از مجموعه گستردهتری پشتیبانی میکنند.

راهبردهای قابلمشاهده در داشبورد (مسیریابی در سطح حساب):

راهبرد	توضیحات
پر کردن اولی	حسابها را بهترتیب اولویت استفاده میکند — حساب اصلی تا زمانی که در دسترس نباشد، همه درخواستها را مدیریت میکند
گردشی	با یک حد چسبندگی قابلتنظیم میان همه حسابها گردش میکند (پیشفرض: 3 فراخوانی برای هر حساب)
P2C (توانِ دو انتخاب)	2 حساب را بهصورت تصادفی انتخاب میکند و درخواست را به حساب سالمتر هدایت میکند — بار را با درنظرگرفتن سلامت متعادل میسازد
تصادفی	برای هر درخواست، با استفاده از درهمریزی Fisher-Yates یک حساب را بهصورت تصادفی انتخاب میکند
کماستفادهترین	درخواست را به حسابی با قدیمیترین برچسب زمانی lastUsedAt هدایت میکند و ترافیک را بهطور یکنواخت توزیع میکند
بهینهسازیشده برای هزینه	درخواست را به حسابی با کمترین مقدار اولویت هدایت میکند و ارائهدهندگان کمهزینهتر را ترجیح میدهد

راهبردهای پیشرفته ترکیبی و خودکار (برای هر ترکیب یا از طریق پیشوندهای auto/* قابلپیکربندی هستند — AUTO-COMBO.md را ببینید):

• priority — ترتیب سختگیرانه، بدون گردش نوبتی
• weighted — تقسیم متناسب ترافیک براساس وزنهای هر مدل
• fill-first — استفاده کامل از مدل اول تا رسیدن به محدودیتها
• round-robin / strict-random / random
• p2c (توانِ دو انتخاب)
• least-used و cost-optimized
• auto — مبتنی بر امتیاز در میان همه گزینهها
• lkgp (آخرین ارائهدهنده سالم شناختهشده) — به آخرین ارائهدهنده موفق متصل میماند و سپس به قواعد جایگزین رجوع میکند
• context-optimized — مدلی با بزرگترین پنجره زمینه آزاد را انتخاب میکند
• context-relay — مدلهای دارای زمینه طولانی را برای نوبتهای بعدی بهصورت زنجیرهای متصل میکند

سرآیند نشست چسبنده خارجی

برای حفظ وابستگی نشست خارجی (برای مثال، عاملهای Claude Code/Codex در پشت پراکسیهای معکوس)، این سرآیند را ارسال کنید:

X-Session-Id: your-session-key

OmniRoute همچنین x_session_id را میپذیرد و کلید مؤثر نشست را در X-OmniRoute-Session-Id برمیگرداند.

اگر از Nginx استفاده میکنید و سرآیندهایی با قالب زیرخط ارسال میکنید، این گزینه را فعال کنید:

underscores_in_headers on;

نامهای مستعار مدل با نویسه عام

برای نگاشت مجدد نام مدلها، الگوهای دارای نویسه عام ایجاد کنید:

الگو: claude-sonnet-*     →  مقصد: cc/claude-sonnet-4-6
الگو: gpt-*               →  مقصد: gh/gpt-5.3-codex

نویسههای عام از * (هر تعداد نویسه) و ? (یک نویسه) پشتیبانی میکنند.

زنجیرههای جایگزین

زنجیرههای جایگزین سراسری را تعریف کنید که بر همه درخواستها اعمال شوند:

زنجیره: production-fallback
  1. cc/claude-opus-4-7
  2. gh/gpt-5.3-codex
  3. glm/glm-4.7

---

تابآوری و قطعکنندههای مدار

از مسیر داشبورد → تنظیمات → تابآوری پیکربندی کنید.

OmniRoute تابآوری در سطح ارائهدهنده را با پنج مؤلفه پیادهسازی میکند:

1. صف درخواست و تنظیم آهنگ — شکلدهی درخواست در سطح سیستم:

   • درخواست در دقیقه (RPM) — حداکثر تعداد درخواست در دقیقه برای هر حساب
   • حداقل زمان بین درخواستها — حداقل فاصله زمانی بین درخواستها برحسب میلیثانیه
   • حداکثر درخواستهای همزمان — حداکثر تعداد درخواستهای همزمان برای هر حساب

2. دوره انتظار اتصال — پیکربندی براساس نوع احراز هویت برای یک اتصال، پس از خطاهای قابلتلاشمجدد:

   • دوره انتظار پایه — بازه پیشفرض انتظار برای خطاهای قابلتلاشمجدد بالادستی
   • استفاده از راهنمای تلاش مجدد بالادستی — در صورت ارائه، به Retry-After معتبر یا راهنمای بازنشانی پایبند میماند
   • حداکثر مراحل عقبنشینی — حداکثر سطح عقبنشینی نمایی برای خطاهای تکراری

3. قطعکننده مدار ارائهدهنده — خطاهای سرتاسری ارائهدهنده را ردیابی میکند، در آستانه هشدار پیکربندیشده وضعیت ارائهدهنده را تنزلیافته علامت میزند و با رسیدن به آستانه خطای پیکربندیشده، قطعکننده را باز میکند:

   • آستانه تنزل — تعداد خطاهای متوالی ارائهدهنده پیش از ورود به DEGRADED
   • آستانه خطا — تعداد خطاهای متوالی ارائهدهنده پیش از ورود به OPEN
   • مهلت بازنشانی — بازه زمانی پیش از آزمایش مجدد ارائهدهنده
   • CLOSED (سالم) — درخواستها بهطور عادی جریان مییابند
   • DEGRADED — درحالیکه افزایش خطاها ردیابی میشود، درخواستها همچنان جریان مییابند
   • OPEN — ارائهدهنده پس از خطاهای تکراری، موقتاً مسدود میشود
   • HALF_OPEN — بررسی میشود که آیا ارائهدهنده بازیابی شده است

   محدودیتهای نرخ 429 در سطح اتصال در دوره انتظار اتصال باقی میمانند و در قطعکننده ارائهدهنده محاسبه نمیشوند.

   وضعیت زمان اجرای قطعکننده ارائهدهنده فقط در داشبورد → سلامت نمایش داده میشود.

4. انتظار برای پایان دوره انتظار — اگر همه اتصالهای کاندید از قبل در دوره انتظار باشند، OmniRoute میتواند تا پایان نزدیکترین دوره انتظار صبر کند و همان درخواست کلاینت را بهطور خودکار دوباره امتحان کند.

5. تشخیص خودکار محدودیت نرخ — وقتی ارائهدهندگان بالادستی بازههای انتظار صریحی برمیگردانند، در صورت فعال بودن این تنظیم، آن راهنماها دوره انتظار محلی اتصال را لغو و جایگزین میکنند.

نکته حرفهای: برای بررسی و بازنشانی قطعکنندههای فعال ارائهدهندگان پس از یک قطعی، از صفحه سلامت استفاده کنید. صفحه تابآوری فقط پیکربندی را تغییر میدهد.

---

برونبری / درونریزی پایگاه داده

نسخههای پشتیبان پایگاه داده را در داشبورد → تنظیمات → سیستم و فضای ذخیرهسازی مدیریت کنید.

عملیات	توضیحات
خروجی گرفتن از پایگاه داده	پایگاه داده فعلی SQLite را بهصورت یک فایل .sqlite دانلود میکند
خروجی گرفتن از همهچیز (.tar.gz)	یک آرشیو پشتیبان کامل شامل پایگاه داده، تنظیمات، ترکیبها، اتصالهای ارائهدهندگان (بدون اطلاعات احراز هویت) و فراداده کلیدهای API را دانلود میکند
وارد کردن پایگاه داده	یک فایل .sqlite را برای جایگزینی پایگاه داده فعلی بارگذاری میکند. مگر اینکه DISABLE_SQLITE_AUTO_BACKUP=true باشد، پیش از وارد کردن بهطور خودکار یک نسخه پشتیبان ایجاد میشود

# API: خروجی گرفتن از پایگاه داده
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: خروجی گرفتن از همهچیز (آرشیو کامل)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

# API: وارد کردن پایگاه داده
curl -X POST http://localhost:20128/api/db-backups/import \
  -F "file=@backup.sqlite"

اعتبارسنجی وارد کردن: یکپارچگی فایل واردشده (بررسی pragma در SQLite)، وجود جدولهای الزامی (provider_connections، provider_nodes، combos، api_keys) و اندازه آن (حداکثر 100MB) اعتبارسنجی میشوند.

موارد استفاده:

• انتقال OmniRoute بین دستگاهها
• ایجاد نسخههای پشتیبان خارجی برای بازیابی پس از بحران
• اشتراکگذاری پیکربندیها بین اعضای تیم (خروجی گرفتن از همهچیز ← اشتراکگذاری آرشیو)

---

داشبورد تنظیمات

صفحه تنظیمات برای پیمایش آسان در 7 زبانه سازماندهی شده است:

زبانه	محتوا
عمومی	ابزارهای ذخیرهسازی سیستم، رفتار پیشفرض، نمایش تونل Endpoint
ظاهر	کنترلهای پوسته (روشن/تیره/سیستم)، نمایش نوار کناری، کلیدهای نمایش پنل برای کارتهای تونل Cloudflare/Tailscale/ngrok
هوش مصنوعی	بودجه تفکر (عبور بدون تغییر / حذف خودکار / سفارشی / تطبیقی — به THINKING_BUDGET.md مراجعه کنید)، پرامپت سیستمی سراسری، آمار کش پرامپت
امنیت	تنظیمات ورود/رمز عبور، کنترل دسترسی IP، احراز هویت API برای /models، مسدودسازی ارائهدهنده، محافظ در برابر تزریق پرامپت
مسیریابی	راهبرد مسیریابی سراسری (پر کردن اولین / نوبتگردشی / P2C / تصادفی / کماستفادهترین / بهینهسازی هزینه)، نامهای مستعار مدل با نویسه عام، زنجیرههای جایگزین، پیشفرضهای ترکیب
تابآوری	صف درخواست، دوره انتظار اتصال، پیکربندی قطعکننده ارائهدهنده و رفتار انتظار برای پایان دوره انتظار
پیشرفته	پیکربندی پراکسی سراسری (HTTP/SOCKS5)، بازنویسی پراکسی برای هر ارائهدهنده

بخش عمومی دیگر یادداشتهای فقطخواندنی مربوط به ثبت گزارش و کش را تکرار نمیکند. تنظیمات نگهداری و بهینهسازی پایگاه داده از طریق /api/settings/database ذخیره میشوند؛ پاکسازی دستی کش از DELETE /api/cache استفاده میکند. سقف تعداد ردیفهای گزارش درخواست و پراکسی توسط CALL_LOGS_TABLE_MAX_ROWS و PROXY_LOGS_TABLE_MAX_ROWS کنترل میشود.

---

مدیریت هزینهها و بودجه

از طریق داشبورد ← هزینهها در دسترس است.

زبانه	هدف
بودجه	تعیین محدودیت هزینه برای هر کلید API با بودجههای روزانه/هفتگی/ماهانه و ردیابی بلادرنگ
قیمتگذاری	مشاهده و ویرایش ورودیهای قیمتگذاری مدل — هزینه بهازای هر 1K توکن ورودی/خروجی برای هر ارائهدهنده

# API: تنظیم بودجه
curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'

# API: دریافت وضعیت فعلی بودجه
curl http://localhost:20128/api/usage/budget

ردیابی هزینه: هر درخواست، میزان استفاده از توکن را ثبت میکند و هزینه را با استفاده از جدول قیمتگذاری محاسبه میکند. جزئیات تفکیکی را بر اساس ارائهدهنده، مدل و کلید API در داشبورد ← میزان استفاده مشاهده کنید.

---

رونویسی صوتی

OmniRoute از رونویسی صوتی از طریق نقطه پایانی سازگار با OpenAI پشتیبانی میکند:

POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

# نمونه با curl
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@audio.mp3" \
  -F "model=openai/whisper-1"

deepgram/nova-3 مسیر بومی Deepgram است و به یک کلید API از Deepgram نیاز دارد. اگر فقط OpenRouter پیکربندی شده است، از openrouter/deepgram/nova-3 استفاده کنید.

ارائهدهندگان تبدیل گفتار به متن (رونویسی):

• openai/ (سازگار با whisper)
• groq/ (Groq Whisper Turbo)
• deepgram/ (خانواده Nova)
• assemblyai/
• nvidia/ (Parakeet، Canary)
• huggingface/ (گونههای whisper)
• qwen/

ارائهدهندگان تبدیل متن به گفتار (POST /v1/audio/speech):

• openai/ (tts-1، tts-1-hd)
• hyperbolic/
• deepgram/ (Aura)
• nvidia/ (Magpie TTS)
• elevenlabs/
• huggingface/
• inworld/
• cartesia/
• playht/
• kie/
• aws-polly/
• xiaomi-mimo/
• coqui/، tortoise/
• qwen/

قالبهای صوتی پشتیبانیشده برای رونویسی: mp3، wav، m4a، flac، ogg، webm. قالبهای خروجی TTS به ارائهدهنده بستگی دارند (mp3، wav، opus، pcm، mulaw).

---

راهبردهای متعادلسازی ترکیب

متعادلسازی هر ترکیب را در داشبورد ← ترکیبها ← ایجاد/ویرایش ← راهبرد پیکربندی کنید.

راهبرد	توضیحات
نوبتی	مدلها را بهصورت متوالی به گردش درمیآورد
اولویتدار	همیشه ابتدا مدل اول را امتحان میکند؛ فقط در صورت خطا به مدل بعدی میرود
تصادفی	برای هر درخواست، مدلی تصادفی از ترکیب انتخاب میکند
وزندار	مسیریابی را متناسب با وزن اختصاصیافته به هر مدل انجام میدهد
کماستفادهترین	درخواست را به مدلی با کمترین تعداد درخواستهای اخیر هدایت میکند (از معیارهای ترکیب استفاده میکند)
بهینه از نظر هزینه	درخواست را به ارزانترین مدل موجود هدایت میکند (از جدول قیمتگذاری استفاده میکند)

پیشفرضهای سراسری ترکیب را میتوان در داشبورد ← تنظیمات ← مسیریابی ← پیشفرضهای ترکیب تنظیم کرد. مهلتهای زمانی مقصدهای ترکیب بهطور پیشفرض از مهلت زمانی درخواست فعلی به ارث برده میشوند. فقط زمانی از مهلت زمانی مقصد (ثانیه) در پیشفرضهای ترکیب یا یک ترکیب خاص استفاده کنید که لازم است محدودیت کوتاهتری برای هر مقصد، بازگشت به مقصد جایگزین را سریعتر فعال کند.

بهینهسازیهای بدون تأخیر ترکیب اختیاری هستند. بهینهسازیهای بدون تأخیر را غیرفعال نگه دارید تا این قابلیتهای کاهش تأخیر از رقابت همزمان مقصدهای جایگزین، رد کردن مقصدها بر اساس سابقه TTFT یا فشردهسازی درخواستهای جایگزین جلوگیری کنند؛ فعالسازی آن اجازه میدهد پوشش ریسک پیکربندیشده، رد کردن پیشبینانه بر اساس TTFT و فشردهسازی پیشدستانه درخواست جایگزین، صحت مسیریابی/درخواست را در ازای کاهش تأخیر انتهایی کمتر کنند.

زمانی که ارائهدهندگان بالادستی به محدودیتهای سختگیرانه max_tokens / maxOutputTokens نیاز دارند، بافر توکنهای استدلال را غیرفعال کنید. در صورت فعال بودن، مسیریابی ترکیبی فقط برای مدلهای استدلالی که سقف خروجی مشخصی دارند، فضای اضافه در نظر میگیرد و وقتی مقدار امنِ بافرشده از آن سقف فراتر رود، محدودیت توکن کلاینت را بدون تغییر باقی میگذارد. اگر محدودیت کلاینت از قبل بالاتر از یک سقف مشخص باشد، OmniRoute پیش از ارسال درخواست بالادستی، آن را تا همان سقف کاهش میدهد.

---

داشبورد سلامت

از طریق داشبورد ← سلامت به آن دسترسی پیدا کنید. نمای کلی بلادرنگ سلامت سیستم با ۶ کارت:

کارت	موارد نمایشدادهشده
وضعیت سیستم	زمان کارکرد، نسخه، میزان استفاده از حافظه، پوشه دادهها
سلامت ارائهدهندگان	وضعیت زمان اجرای قطعکننده مدار سراسری ارائهدهندگان
محدودیتهای نرخ	دورههای انتظار فعال اتصال برای هر حساب بههمراه زمان باقیمانده
قفلهای فعال	قفلهای فعال مختص مدل و محرومیتهای موقت
کش امضا	آمار کش حذف موارد تکراری (کلیدهای فعال، نرخ اصابت)
تلهمتری تأخیر	تجمیع تأخیر p50/p95/p99 برای هر ارائهدهنده

نکته حرفهای: صفحه سلامت هر ۱۰ ثانیه بهطور خودکار تازهسازی میشود. از کارت قطعکننده مدار برای شناسایی ارائهدهندگانی که با مشکل مواجهاند استفاده کنید.

---

🤖 مسیریابی خودکار (بدون نیاز به پیکربندی)

OmniRoute همراه با یک مسیریاب خودکار مبتنی بر امتیازدهی عرضه میشود که برای هر درخواست، بهترین مدل را از میان تمام ارائهدهندگان متصل انتخاب میکند — بدون نیاز به نگهداری هیچ ترکیبی. کافی است درخواست را با یکی از پیشوندهای auto/* ارسال کنید؛ OmniRoute در لحظه یک ترکیب مجازی میسازد و گزینهها را بر اساس تأخیر، هزینه، نرخ موفقیت، تناسب پنجره زمینه، مناسببودن مدل برای وظیفه، خطاهای اخیر، سهمیه و وضعیت قطعکننده مدار امتیازدهی میکند.

پیشوند	معیار بهینهسازی
auto	حالت پیشفرض متعادل (تأخیر × هزینه × نرخ موفقیت)
auto/coding	وظایف برنامهنویسی: Claude، GPT-5، GLM، Kimi، Qwen Coder و مدلهای برنامهنویسی DeepSeek را ترجیح میدهد
auto/cheap	کمترین هزینه بهازای هر توکن؛ تأخیر بیشتر را میپذیرد
auto/fast	کمترین تأخیر؛ هزینه را نادیده میگیرد
auto/offline	فقط ارائهدهندگان محلی (Ollama، vLLM، llama.cpp) — مناسب برای محیطهای ایزوله از شبکه
auto/smart	اولویت با کیفیت استدلال (Opus، GPT-5 xhigh، R1، استدلال GLM 5.1)
auto/lkgp	«آخرین ارائهدهنده مطلوب شناختهشده» — ابتدا به آخرین ارائهدهنده موفق متصل میماند، سپس به قوانین جایگزین رجوع میکند

مثال:

curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/coding",
    "messages": [{ "role": "user", "content": "این تابع Python را بازآرایی کن" }],
    "stream": true
  }'

مسیریاب خودکار بهطور کامل در AUTO-COMBO.md توضیح داده شده است — از جمله نحوه تنظیم وزنهای امتیازدهی، قراردادن ارائهدهندگان در فهرست سیاه و بررسی تصمیمهای مسیریابی در داشبورد ← ترکیب خودکار.

---

🔌 یکپارچهسازی MCP و A2A

OmniRoute هم یک سرور MCP (پروتکل زمینه مدل) و هم یک سرور A2A (JSON-RPC 2.0 عاملبهعامل) است. هر محیط توسعه یا میزبان عامل سازگار با MCP میتواند ابزارهای OmniRoute را مستقیماً فراخوانی کند — بدون نیاز به هیچ پوشش اضافی.

روشهای انتقال MCP

• SSE: http://localhost:20128/api/mcp/sse
• HTTP قابلجریان: http://localhost:20128/api/mcp/stream
• stdio: omniroute --mcp (برای افزونههای محیط توسعه که stdio را ترجیح میدهند)

اتصال Claude Desktop

فایل ~/Library/Application Support/Claude/claude_desktop_config.json را در macOS، یا فایل معادل آن را در Windows/Linux ویرایش کنید:

{
  "mcpServers": {
    "omniroute": {
      "command": "omniroute",
      "args": ["--mcp"]
    }
  }
}

اتصال Cursor / Continue / VS Code MCP

از URL مربوط به SSE یعنی http://localhost:20128/api/mcp/sse و یک کلید API از نوع Bearer که در داشبورد ← کلیدهای API ایجاد شده است، استفاده کنید.

دامنهها

MCP در حال حاضر 32 دامنه نامگذاریشده تعریف میکند. هر کلید Bearer را میتوان به دامنههای مشخصی محدود کرد — برای فهرست مرجع دامنهها و ابزارها به MCP-SERVER.md و برای طرحواره JSON-RPC به A2A-SERVER.md مراجعه کنید.

---

🧠 سیستم مهارتها

OmniRoute یک چارچوب مهارت توسعهپذیر (src/lib/skills/) ارائه میدهد تا عاملها و نقطه پایانی A2A بتوانند روالهای مختص دامنه را اجرا کنند (برای مثال code-review، summarize، extract-facts و web-research).

• رابط کاربری بازارچه — مهارتها را از مسیر داشبورد ← مهارتها مرور و نصب کنید
• دامنههای اختصاصی هر کلید — مشخص کنید کدام کلیدهای API میتوانند کدام مهارتها را فراخوانی کنند
• مهارتهای سفارشی — یک فایل TypeScript را در src/lib/a2a/skills/ قرار دهید و آن را ثبت کنید تا بلافاصله از طریق A2A قابل فراخوانی شود

مرجع کامل: SKILLS.md.

---

💾 سیستم حافظه

OmniRoute حافظه مکالمهای بلندمدت را با بازیابی ترکیبی ذخیره میکند:

• SQLite FTS5 برای جستوجوی کلیدواژهای در نوبتهای مکالمه گذشته
• ذخیرهساز برداری Qdrant (اختیاری) برای یادآوری معنایی
• استخراج خودکار واقعیتها — موجودیتها، ترجیحات و تصمیمها پس از هر نشست خلاصه شده و در جدول memory_facts ذخیره میشوند
• حافظهها بهازای هر کلید API و هر نشست تفکیک میشوند

حافظهها را در داشبورد ← حافظه مدیریت کنید (جستوجو، ویرایش، برونبری و پاکسازی). رابط HTTP (/api/memory/*) به عاملها اجازه میدهد واقعیتها را بهصورت برنامهنویسیشده ارسال و جستوجو کنند — به MEMORY.md مراجعه کنید.

---

🔔 وبهوکها

برای پایش و خودکارسازی بلادرنگ، در رویدادهای OmniRoute مشترک شوید.

• در مسیر داشبورد ← وبهوکها یک وبهوک با URL مقصد و کلید محرمانه امضای HMAC ایجاد کنید
• رویدادهای موجود: request.completed، request.failed، provider.unavailable، budget.exceeded، combo.switched، circuit_breaker.opened، circuit_breaker.closed
• هر بار ارسالی برای اعتبارسنجی شامل X-OmniRoute-Signature (HMAC-SHA256) است
• تلاشهای مجدد: 3 تلاش با تأخیر تصاعدی، سپس انتقال به صف نامههای مرده

طرحواره کامل در WEBHOOKS.md.

---

☁️ عاملهای ابری

OmniRoute با عاملهای کدنویسی ابری (OpenAI Codex Cloud، Devin، Jules و Antigravity) یکپارچه میشود تا بتوانید وظایف طولانیمدت را از همان داشبوردی که مسیریابی محلی شما را مدیریت میکند، ارسال کنید.

• وظایف را در داشبورد ← عاملهای ابری یا از طریق POST /api/v1/agents/tasks ایجاد کنید
• وضعیت، گزارشها و مصنوعات هر وظیفه را پیگیری کنید
• برای هر ارائهدهنده از کلید API خودتان استفاده کنید — اطلاعات ورود هرگز از نمونه OmniRoute خارج نمیشوند

مرجع کامل: CLOUD_AGENT.md.

---

🛠️ مدیریت برنامهنویسیشده

میتوانید تمام منابع OmniRoute (ارائهدهندگان، ترکیبها، کلیدها و تنظیمات) را از طریق HTTP و با استفاده از یک کلید Bearer دارای دامنه manage مدیریت کنید.

کلید را در مسیر داشبورد ← کلیدهای API ← کلید جدید ← دامنه: manage ایجاد کنید، سپس:

# فهرست ارائهدهندگان
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# افزودن اتصال ارائهدهنده
curl -X POST http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }'

# ایجاد یک ترکیب
curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }'

# فهرستکردن/ایجاد کلیدهای API
curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -d '{ "name": "ci-bot", "scopes": ["chat"] }'

برای مشاهده فهرست کامل نقاط پایانی و طرحوارههای درخواست/پاسخ، به API_REFERENCE.md مراجعه کنید.

---

💻 CLI داخلی

OmniRoute یک CLI داخلی (omniroute …) برای راهاندازی، عیبیابی و کنترل زمان اجرا ارائه میکند. این ابزار از صفحه «ابزارهای CLI» در داشبورد جدا است؛ آن صفحه CLIهای شخص ثالث (Claude Code، Cursor، Codex، Cline و …) را پیکربندی میکند تا بتوانند با OmniRoute ارتباط برقرار کنند.

omniroute setup                    # راهنمای تعاملی (رمز عبور، ارائهدهندگان، ترکیبها)
omniroute setup --non-interactive  # مناسب برای CI
omniroute doctor                   # عیبیابی سلامت (دایرکتوری داده، پایگاه داده، ارائهدهندگان، پورتها)
omniroute providers available      # فهرست ارائهدهندگان پشتیبانیشده
omniroute providers list           # فهرست اتصالهای پیکربندیشده
omniroute providers test <id>      # آزمایش زنده اتصال یک ارائهدهنده
omniroute combos list              # فهرست ترکیبها
omniroute combos switch <name>     # تنظیم ترکیب پیشفرض
omniroute models                   # فهرست مدلهای موجود (--json، --search)
omniroute keys add | list | remove # مدیریت کلیدهای API از ترمینال
omniroute backup                   # تهیه اسنپشات از پیکربندی و پایگاه داده
omniroute restore [<timestamp>]    # بازیابی از یک اسنپشات
omniroute health                   # جزئیات سلامت (قطعکنندهها، کش، حافظه)
omniroute quota                    # میزان مصرف سهمیه ارائهدهنده
omniroute mcp status               # وضعیت سرور MCP
omniroute a2a status               # وضعیت سرور A2A
omniroute tunnel list|create|stop  # تونلهای Cloudflare/Tailscale/ngrok
omniroute reset-password           # بازنشانی رمز عبور مدیر
omniroute --mcp                    # راهاندازی سرور MCP از طریق stdio
omniroute --port 3000              # راهاندازی سرور روی یک پورت سفارشی

نکته: omniroute doctor --json را با ابزار پایش خود همراه کنید تا درباره اتصالهای ناسالم ارائهدهندگان هشدار دریافت کنید.

---

🖥️ برنامه دسکتاپ (Electron)

OmniRoute بهعنوان یک برنامه دسکتاپ بومی برای Windows، macOS و Linux در دسترس است.

نصب

# از دایرکتوری electron:
cd electron
npm install

# حالت توسعه (اتصال به سرور توسعه در حال اجرای Next.js):
npm run dev

# حالت تولید (از بیلد مستقل استفاده میکند):
npm start

ساخت نصبکنندهها

cd electron
npm run build          # پلتفرم فعلی
npm run build:win      # Windows (.exe NSIS)
npm run build:mac      # macOS (.dmg عمومی)
npm run build:linux    # Linux (.AppImage)

خروجی ← electron/dist-electron/

قابلیتهای کلیدی

قابلیت	توضیحات
آمادگی سرور	پیش از نمایش پنجره، سرور را بررسی میکند (بدون صفحه خالی)
سینی سیستم	کوچکسازی در سینی، تغییر پورت و خروج از منوی سینی
مدیریت پورت	تغییر پورت سرور از سینی (سرور بهصورت خودکار مجدداً راهاندازی میشود)
سیاست امنیت محتوا	CSP محدودکننده از طریق هدرهای نشست
تکنمونهای	در هر لحظه فقط یک نمونه از برنامه میتواند اجرا شود
حالت آفلاین	سرور همراه Next.js بدون اینترنت کار میکند

متغیرهای محیطی

متغیر	پیشفرض	توضیحات
OMNIROUTE_PORT	20128	پورت سرور
OMNIROUTE_MEMORY_MB	512	محدودیت heap در Node.js (64–16384 MB)

📖 مستندات کامل: electron/README.md