راه‌اندازی Qoder با QCode (BYOK)

QCode را به تنظیمات مدل سفارشی Qoder اضافه کنید: OpenAI Compatible (Chat Completions یا Responses) برای GPT و مدل‌های چینی، Anthropic Compatible برای Claude.

به کلید API نیاز دارید؟ ثبت‌نام ←·نقاط پایانی و Base URL ←

آخرین بازبینی: 2026-11-10 · 📄 بر اساس مستندات رسمی (Qoder 0.5.7 و Qoder CLI 1.1.86، هر دو منتشرشده در 2026-11-09؛ مستندات در 2026-11-10 خوانده شد)

یک نگاه کلی¶

Qoder IDE، محصولی جداگانه در همین خانواده، صفحه مدل‌های سفارشی اختصاصی خود را دارد (docs.qoder.com/user-guide/chat/custom-models) که فقط ارائه‌دهندگان از پیش تعیین‌شده را فهرست می‌کند. Base URL سفارشی در اپلیکیشن دسکتاپ Qoder (از نسخه 0.1.8، 2026-09-05) و در Qoder CLI — که کاربران نسخه شخصی، آن‌ها را از صفحه Custom در /model مدیریت می‌کنند (از نسخه 1.1.50، 2026-09-11) — در دسترس است؛ این صفحه همان دو مورد را پوشش می‌دهد.

کدام پروتکل¶

فرم نقطه پایانی سفارشی دو نوع ارائه‌دهنده ارائه می‌دهد، و سازگار با OpenAI گزینه دومی برای نوع API دارد. ردیفی را انتخاب کنید که با خانواده مدل مطابقت دارد:

مدل‌های Claude فقط روی پروتکل Anthropic کار می‌کنند، پس شناسه‌های claude-… را پشت سازگار با Anthropic قرار دهید؛ مدل‌های GPT فقط روی دو پروتکل OpenAI کار می‌کنند. چهار خانواده چینی روی هر دو کار می‌کنند. برای جدول کامل، نقاط پایانی و مسیرهای API را ببینید و شناسه‌های مدل را از qcode.cc/models کاراکتربه‌کاراکتر کپی کنید.

فرم Base URL. به گفته خود Qoder: «Base URL دقیقی را که سرویس مدل ارائه می‌دهد وارد کنید. Qoder قالب نمونه را به‌صورت https://api.example.com/v1 نمایش می‌دهد.» آن نمونه به /v1 ختم می‌شود، بنابراین برای گزینه‌های OpenAI، URL مربوط به QCode را که به /v1 ختم می‌شود وارد کنید. برای گزینه Responses API این کار جواب می‌دهد چون QCode مسیرهای /openai/responses و /openai/v1/responses را یکسان ارائه می‌دهد. مستندات Qoder نمی‌گویند Qoder کدام مسیر را برای سازگار با Anthropic اضافه می‌کند. با Base URL مربوط به Anthropic در QCode، یعنی https://api.qcode.cc/api (بدون اسلش انتهایی) شروع کنید. اگر اعتبارسنجی و افزودن مدل شکست خورد، https://api.qcode.cc/api/v1 را وارد کنید و دوباره اعتبارسنجی کنید: هر دو به همان نقطه پایانی QCode یعنی /api/v1/messages می‌رسند، و تنها تفاوت این است که Qoder خودش چند بخش مسیر اضافه می‌کند.

در آسیا یا آمریکای شمالی می‌توانید دامنه را با asia.qcode.cc یا us.qcode.cc عوض کنید؛ مسیرها یکسان می‌مانند.

نصب¶

اپلیکیشن دسکتاپ را از صفحه دانلود Qoder (macOS 12+، Windows 10+ یا Linux) دانلود کنید و وارد شوید. برای CLI، همان صفحه موارد زیر را فهرست می‌کند:

# macOS / Linux
curl -fsSL https://qoder.com/install | bash

# Windows PowerShell
irm https://qoder.com/install.ps1 | iex

Qoder CN اپلیکیشن و مستندات خودش را در docs.qoder.cn دارد. نسخه‌ای را که اجرا می‌کنید با نسخه‌های بالا بررسی کنید.

پیکربندی¶

دسکتاپ: تنظیمات → مدل‌ها¶

این‌ها مراحل صفحه رسمی مدل‌های سفارشی هستند، با عبارت‌پردازی رابط کاربری مستندات انگلیسی:

1. تنظیمات را باز کنید، سپس در ناوبری سمت چپ مدل‌ها را انتخاب کنید.
2. روی افزودن مدل کلیک کنید. برای یک نقطه پایانی سفارشی، ارائه‌دهنده را باز کنید و زیر سفارشی، سازگار با OpenAI یا سازگار با Anthropic را انتخاب کنید.
3. برای سازگار با OpenAI، Chat Completions API یا Responses API را انتخاب کنید.
4. Base URL، کلید API خود و حداقل یک شناسه مدل را وارد کنید. برای پیکربندی مدل‌های بیشتر برای همان نقطه پایانی، روی افزودن شناسه مدل کلیک کنید.
5. قابلیت‌هایی را که صفحه فهرست می‌کند پیکربندی کنید: نام نمایشی، پنجره زمینه (مقادیر پشتیبانی‌شده را انتخاب کنید، سپس یک پنجره زمینه پیش‌فرض)، بینایی (وقتی مدل تصاویر را می‌پذیرد آن را روشن کنید) و تفکر (وقتی مدل از استدلال پشتیبانی می‌کند آن را روشن کنید، سپس سطوح تلاش آن را انتخاب کنید).
6. روی اعتبارسنجی و افزودن مدل کلیک کنید. «Qoder اتصال را اعتبارسنجی می‌کند و مدل را پس از موفقیت اعتبارسنجی ذخیره می‌کند.»
7. مدل جدید را در رابط چت انتخاب کنید.

مقادیری که باید برای QCode وارد کنید (جای‌نگهدار کلید cr_xxx):

برای هر پروتکلی که نیاز دارید یک ورودی اضافه کنید؛ هر ورودی Base URL خودش را دارد.

تفاوت‌های جهانی و CN. ارائه‌دهنده‌های از پیش تعیین‌شده‌ای که در صفحه جهانی فهرست شده‌اند عبارت‌اند از Alibaba Cloud Model Studio، DeepSeek، Z.ai، Kimi، MiniMax، Xiaomi MIMO، OpenAI، Google و OpenRouter. صفحه CN شامل Alibaba Cloud Model Studio، DeepSeek، Zhipu، Kimi، MiniMax و Xiaomi MIMO است، بدون OpenAI، Google و OpenRouter. هر دو همان دو ارائه‌دهنده سفارشی، سازگار با OpenAI و سازگار با Anthropic، و همان مراحل را فهرست می‌کنند.

برای تغییر کلید در ادامه، از عملیات ویرایش در پنل مدل‌ها استفاده کنید؛ گزینه حذف مدل را حذف می‌کند.

CLI: /model → سفارشی¶

1. Qoder CLI را اجرا کنید و /model را وارد کنید.
2. به تب سفارشی بروید.
3. افزودن مدل سفارشی... را انتخاب کنید و Enter را فشار دهید.
4. از ویزارد پیروی کنید: «Provider → model type → model»، سپس کلید API و هر اطلاعات دیگری را که درخواست می‌کند وارد کنید.
5. پس از موفقیت اعتبارسنجی، پیکربندی به‌طور خودکار ذخیره می‌شود و مدل بلافاصله قابل انتخاب است. آن را از تب سفارشی انتخاب کنید؛ برای حذف مدل، در آنجا روی یک مدل d را فشار دهید.

صفحه رسمی همچنین می‌گوید: «BYOK را به‌صورت دستی در settings.json پیکربندی نکنید؛ ارائه‌دهنده‌ها، مدل‌ها و فیلدهای اعتبارنامه موجود توسط کاتالوگ BYOK قابل‌دسترس برای حساب کاربری فعلی تعیین می‌شوند.» صفحه CLI فیلدهای ویزارد را فهرست نمی‌کند. یادداشت انتشار CLI 1.1.50 می‌گوید کاربران نسخه شخصی می‌توانند مدل‌های BYOK را «با نقاط پایانی URL سفارشی از صفحه سفارشی در /model» پیکربندی کنند، و حساب رسمی Qoder در X آن را به‌صورت وارد کردن Base URL، شناسه مدل و کلید API توصیف کرده است. برای آن فیلدها از مقادیر QCode در جدول بالا استفاده کنید.

بررسی¶

1. مدلی را که اضافه کرده‌اید انتخاب کنید و یک پیام کوتاه مانند ping بفرستید.
2. probe.qcode.cc را باز کنید، کلید QCode خود را وارد کنید و بررسی کنید که درخواست با همان مدل نمایش داده می‌شود.
3. برای آزمایش کلید و مسیر بدون Qoder:

KEY="cr_your_key"

# OpenAI Compatible, Chat Completions API
curl -sS https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-6.1-sol","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'

# Anthropic Compatible
curl -sS https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'

عیب‌یابی¶

پرسش‌های متداول رسمی درباره افزودن مدلی که شکست می‌خورد، پنج بررسی را فهرست می‌کند. این موارد به این صورت به QCode نگاشت می‌شوند:

دو پیام مخصوص QCode وجود دارد: model_not_available_on_endpoint یعنی یک شناسه claude-… زیر یک گزینه OpenAI اضافه شده است؛ بنابراین آن را به‌جای آن زیر سازگار با Anthropic اضافه کنید؛ این یک ناسازگاری پروتکل است، نه مشکل کلید. Invalid API key یک مشکل کلید است.

صفحه رسمی درباره CLI می‌گوید: اگر زبانه Custom یا گزینه افزودن وجود ندارد، تأیید کنید که BYOK برای حساب کاربری و پلن فعلی در دسترس است؛ اگر ارائه‌دهنده یا مدلی وجود ندارد، کاتالوگ زنده ویزارد مرجع نهایی است.

محدودیت‌های شناخته‌شده¶

• رسمی: «تولید تصویر و ویدیو در حال حاضر هنگام استفاده از مدل‌های متصل‌شده با کلید API خودتان (BYOK) در دسترس نیست.»
• رسمی: هزینه‌های مدل سفارشی به حساب API ارائه‌دهنده شما صورت‌حساب می‌شوند و «از Qoder Credits استفاده نمی‌کنند». Repo Wiki از یک مدل ثابت استفاده می‌کند و همچنان Qoder Credits مصرف می‌کند.
• Qoder نمونه https://api.example.com/v1 را فقط به‌عنوان یک قالب نمایش می‌دهد؛ مستندات توضیح نمی‌دهند که Qoder برای هر پروتکل کدام مسیر را اضافه می‌کند، بنابراین نتیجه Validate and add model حرف آخر را می‌زند.
• QoderWork یک محصول جداگانه است. صفحه مدل‌های آن سطح‌های Premium، Advanced و Standard به‌همراه Qwen3.7-Max و Qwen3.7-Plus را فهرست می‌کند و تا تاریخ 2026-11-10 ورودی مدل سفارشی ندارد. صفحه دانلود Qoder می‌گوید QoderWork در 5 سپتامبر 2027 عملیات خود را متوقف می‌کند و جابه‌جایی به Qoder Desktop را توصیه می‌کند که شامل ابزارهای ورود داده است.
• سطح مدل Lite در 18 سپتامبر 2026 ساعت 14:00 به وقت سنگاپور (UTC+8)، بر اساس اطلاعیه رسمی، از انتخاب‌گر مدل حذف شد.

مرتبط¶

• نقاط پایانی و مسیرهای API — جدول پروتکل × خانواده مدل
• مرور سازگاری ابزارها — کدام ابزارها با کدام پروتکل صحبت می‌کنند
• DeepSeek Harness — ابزار دیگری با فرم مدل سفارشی
• LobsterAI — یک عامل دسکتاپ که ارائه‌دهندگان سفارشی آن نیز قالب‌های Anthropic و OpenAI را می‌پذیرند
• مدل‌های چینی — شناسه‌ها و مسیرهای GLM / Kimi / DeepSeek / Qwen
• راهنمای BYOK مدل سفارشی Qoder در qcode.cc — تاریخ‌ها و پیشینه

سازمانی ←