مدل‌های سفارشی CodeBuddy با QCode

افزودن QCode.cc به CodeBuddy از طریق models.json: Chat و Responses با CodeBuddy Code CLI 2.182.0 آزمایش شده‌اند، نیازی به ورود نیست؛ JSON و متغیرهای محیطی آماده کپی.

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

آخرین بازبینی: 2026-11-10 · 📄 بر اساس مستندات رسمی (CodeBuddy IDE 4.12.4، منتشر شده در 2026-11-06؛ مستندات CLI برای v2.182.0) · ✅ اتصال QCode با CodeBuddy Code CLI 2.182.0 آزمایش شده است (2026-11-10)

بله، CodeBuddy می‌تواند از کلید خودتان استفاده کند: مدل‌های سفارشی در models.json قرار می‌گیرند (سطح کاربر ~/.codebuddy/models.json)، و مستندات رسمی می‌گویند «در حال حاضر فقط از API با قالب رابط OpenAI پشتیبانی می‌کند». در تاریخ 2026-11-10، با CodeBuddy Code CLI 2.182.0 آزمایش شده است: QCode از طریق OpenAI Chat Completions (url مسیر کامل است) و OpenAI Responses (url مقدار پایه است) کار می‌کند، و CLI از این مدل‌ها بدون ورود به حساب کاربری Tencent استفاده می‌کند. مراحل IDE مطابق مستندات رسمی است.

در یک نگاه¶

CodeBuddy ابزار کدنویسی با هوش مصنوعی Tencent Cloud است. در سه شکل عرضه می‌شود: یک افزونه برای VS Code و JetBrains IDE‌ها، CodeBuddy IDE مستقل، و CodeBuddy Code، یک ابزار خط فرمان که فرمان آن codebuddy است. سایت‌ها codebuddy.cn (سرزمین اصلی چین) و codebuddy.ai (بین‌المللی) هستند؛ مسیر فایل مدل سفارشی در هر دو مجموعه مستندات یکسان است. WorkBuddy، عامل اداری همان تیم، زیربنای مشترکی دارد؛ به مدل‌های سفارشی WorkBuddy مراجعه کنید.

QCode.cc وابسته به Tencent یا CodeBuddy نیست. رابط کاربری و فیلدها از نسخه‌ای که نصب کرده‌اید پیروی می‌کنند.

کدام پروتکل¶

این پروتکل‌ها روی QCode با GPT و مدل‌های چینی کار می‌کنند. مدل‌های Claude روی نقطه پایانی Anthropic ارائه می‌شوند، و مدل‌های سفارشی CodeBuddy از آن پروتکل استفاده نمی‌کنند. اگر به Claude نیاز دارید، از ابزاری استفاده کنید که از نقطه پایانی Anthropic پشتیبانی می‌کند، مانند Claude Code، ZCode یا Qoder. این سه پروتکل در نقاط پایانی و مسیرهای API مقایسه شده‌اند. در سرزمین اصلی چین می‌توانید از asia.qcode.cc به جای api.qcode.cc استفاده کنید؛ مسیر تغییر نمی‌کند و همان کلید کار می‌کند.

نصب CodeBuddy Code CLI¶

راهنمای نصب رسمی این روش را فهرست می‌کند (پیش‌نیاز: Node.js 18.20 یا بالاتر)؛ این همان نصبی است که در آزمون 2026-11-10 استفاده شده است:

npm install -g @tencent-ai/codebuddy-code

بدون Node.js، راهنما همچنین Homebrew و یک باینری بومی (Beta) ارائه می‌دهد:

curl -fsSL https://www.codebuddy.cn/cli/install.sh | bash

در Windows PowerShell از irm https://www.codebuddy.cn/cli/install.ps1 | iex استفاده کنید. نصب را با codebuddy --version بررسی کنید (آزمون از 2.182.0 استفاده کرد). مدل‌های سفارشی زیر بدون ورود به حساب کاربری Tencent کار می‌کنند. برای IDE یا افزونه، از codebuddy.ai دانلود کنید؛ اگر فقط از IDE استفاده می‌کنید، از این بخش صرف‌نظر کنید.

پیکربندی models.json¶

مکان فایل‌ها¶

مستندات دو سطح را توصیف می‌کند:

• سطح کاربر: ~/.codebuddy/models.json، سراسری، برای همه پروژه‌ها اعمال می‌شود
• سطح پروژه: <project-root>/.codebuddy/models.json، اولویت بالاتر از سطح کاربر

اولویت ادغام به‌ترتیب سطح پروژه، سپس سطح کاربر، و سپس پیش‌فرض‌های داخلی است. مدلی با id یکسان بازنویسی می‌شود؛ مدلی با id متفاوت اضافه می‌شود. IDE و CLI همان مسیرها را می‌خوانند.

CLI: models.json حداقلی (✅ آزموده شده)¶

این را به‌عنوان ~/.codebuddy/models.json ذخیره کنید. مورد اول از Chat Completions استفاده می‌کند، دومی از Responses؛ کلید از یک متغیر محیطی می‌آید:

{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "QCode DeepSeek V4 Flash",
      "vendor": "QCode",
      "url": "https://api.qcode.cc/openai/v1/chat/completions",
      "apiKey": "${QCODE_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    },
    {
      "id": "gpt-6.1-terra",
      "name": "QCode GPT-6.1 Terra",
      "vendor": "QCode",
      "api": "openai-responses",
      "url": "https://api.qcode.cc/openai/v1",
      "apiKey": "${QCODE_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ],
  "availableModels": ["deepseek-v4-flash", "gpt-6.1-terra"]
}

سپس کلید را export کنید و به هر مدل یک تست یک‌خطی بفرستید:

export QCODE_API_KEY="cr_xxx"
codebuddy -p "Reply with exactly: OK" --model deepseek-v4-flash
codebuddy -p "Reply with exactly: OK" --model gpt-6.1-terra

پاسخ OK به این معناست که مدل کار می‌کند. id به‌عنوان نام مدل به QCode فرستاده می‌شود، بنابراین باید یک id فعال در qcode.cc/models باشد، کاراکتر به کاراکتر. برای موارد Chat می‌توانید از gpt-6.1-sol، deepseek-v4-pro، glm-5.3، kimi-k3 یا qwen3.8-max نیز استفاده کنید (به مدل‌های چینی مراجعه کنید)؛ موارد Responses شناسه‌های GPT را می‌پذیرند. قیمت هر مدل در https://qcode.cc/models است. maxInputTokens، maxOutputTokens و پرچم‌های تصویر یا استدلال را روی مقداری تنظیم کنید که مدل انتخاب‌شده پشتیبانی می‌کند.

دو قاعده url¶

برای Chat Completions (پیش‌فرض)، عبارت رسمی این است: «فیلد url باید مسیر کامل رابط باشد، معمولاً با /chat/completions پایان می‌یابد»، با این نمونه‌های نادرست:

❌ https://api.openai.com/v1
❌ https://api.myservice.com
❌ http://localhost:11434

وقتی api روی openai-responses تنظیم شود، قاعده برعکس می‌شود. عبارت رسمی: «وقتی api روی openai-responses تنظیم شود، مدل از OpenAI Responses API استفاده می‌کند: درخواست‌ها به {url}/responses می‌روند»، و «url مقدار Base URL را می‌گیرد؛ /responses در انتها اختیاری است.»

برای Responses، https://api.qcode.cc/openai نیز آزمون را پاس کرد؛ این صفحه از /openai/v1 استفاده می‌کند تا هر دو مورد یک Base URL مشترک داشته باشند. مستندات همچنین می‌گوید تنها api که به‌صراحت در مورد مدل نوشته شده باشد، پروتکل را تغییر می‌دهد.

CodeBuddy IDE (📄 طبق مستندات رسمی)¶

مستندات IDE همان مسیرهای فایل و فیلدهای Chat را فهرست می‌کند. صفحه IDE apiKey را «مقدار واقعی کلید، نه نام متغیر محیطی» توصیف می‌کند، بنابراین خود کلید را بنویسید. یک مورد Chat برای IDE:

{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "QCode DeepSeek V4 Flash",
      "vendor": "QCode",
      "url": "https://api.qcode.cc/openai/v1/chat/completions",
      "apiKey": "cr_xxx",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ]
}

جدول فیلدهای IDE هیچ فیلد api ندارد، بنابراین موارد Responses برای CLI هستند. اگر از IDE و CLI با همان ~/.codebuddy/models.json استفاده می‌کنید، در هر مورد خود کلید را بنویسید؛ CLI یک کلید تحت‌اللفظی را نیز می‌پذیرد. توصیه رسمی: یک models.json که کلید واقعی دارد را به کنترل نسخه نسپارید، و مجوزهای فایل را روی 600 تنظیم کنید (فقط خواندن/نوشتن برای مالک).

جدول فیلدها¶

صفحه CLI سه فیلد اضافه می‌کند: api (پروتکل درخواست؛ openai-responses به Responses API تغییر می‌دهد)، temperature (دمای نمونه‌گیری، 0-2) و relatedModels (کدام id مدل برای سناریوهایی مانند lite و reasoning استفاده شود). availableModels سطح بالا یک آرایه از رشته‌هاست؛ فقط idهایی که در آن فهرست شده‌اند در منوی کشویی ظاهر می‌شوند، و آرایه خالی یا غایب همه مدل‌ها را نشان می‌دهد.

ارجاع به متغیرهای محیطی با ${VAR_NAME} در CLI¶

صفحه CLI می‌گوید فیلدهای apiKey و url از نحو ارجاع ${VAR_NAME} پشتیبانی می‌کنند؛ ارجاع apiKey در بلوک بالا آزمون را پاس کرد. نکات رسمی: مقدار متغیرهای محیطی هنگام شروع CLI جایگزین می‌شود؛ اگر متغیر محیطی وجود نداشته باشد، جای‌نگهدار اصلی حفظ می‌شود، که باعث شکست درخواست API می‌شود.

بارگذاری مجدد خودکار¶

طبق مستندات، فایل‌های پیکربندی از بارگذاری مجدد خودکار پشتیبانی می‌کنند: تغییرات به‌طور خودکار با یک تأخیر 1 ثانیه‌ای تشخیص داده می‌شوند، برای هر دو فایل models.json بالا.

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

صفحه رسمی متغیرهای محیطی سه متغیر مرتبط با مدل‌های شخص ثالث را فهرست می‌کند:

تا تاریخ 2026-11-10، با CodeBuddy Code CLI 2.182.0 آزمایش شده است: CODEBUDDY_BASE_URL یک Base URL از OpenAI Chat Completions می‌پذیرد و CLI مسیر /chat/completions را به آن می‌افزاید. آن را روی https://api.qcode.cc/openai/v1 تنظیم کنید و یک مدل GPT یا چینی انتخاب کنید؛ این مسیر به models.json نیازی ندارد:

export CODEBUDDY_BASE_URL="https://api.qcode.cc/openai/v1"
export CODEBUDDY_API_KEY="cr_xxx"
codebuddy -p "Reply with exactly: OK" --model deepseek-v4-flash

CODEBUDDY_BASE_URL را روی /openai/v1 نگه دارید: با https://api.qcode.cc/api درخواست به /api/chat/completions می‌رود و QCode پاسخ HTTP 400 می‌دهد.

تأیید¶

ابتدا تأیید کنید که مسیر OpenAI در QCode از شبکه شما کار می‌کند (همان آزمون موجود در نقاط پایانی و مسیرهای API):

KEY="cr_xxx"

curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY"
# 400 = path and key both work (empty body is expected)
# 401 = bad key; 404 = wrong path prefix

سپس:

1. CLI: آزمون‌های codebuddy -p بالا را اجرا کنید؛ OK یعنی کار می‌کند. برای یک نشست تعاملی، codebuddy --model deepseek-v4-flash را اجرا کنید.
2. IDE: فهرست کشویی مدل را باز کنید. مستندات می‌گوید مدل‌هایی که از طریق models.json اضافه می‌شوند به‌طور خودکار با برچسب custom مشخص می‌شوند، که به شما کمک می‌کند آن‌ها را ببینید و فیلتر کنید. یک پیام کوتاه به مدل جدید بفرستید.
3. کلید خود را در probe.qcode.cc وارد کنید تا درخواست و مدلی را که پاسخ داده است ببینید.

عیب‌یابی¶

پیکربندی اعمال نمی‌شود¶

چک‌لیست رسمی: بررسی کنید که JSON معتبر است؛ مسیر فایل را تأیید کنید؛ گزارش‌ها را بخوانید تا ببینید آیا پیکربندی بارگذاری شده است؛ تأیید کنید که کلید API در متغیر محیطی تنظیم شده است. بارگذاری مجدد خودکار 1 ثانیه تأخیر دارد، پس مطمئن شوید که فایل واقعاً روی دیسک ذخیره شده است.

مدل در فهرست کشویی وجود ندارد¶

طبق مستندات: بررسی کنید که شناسه مدل در availableModels فهرست شده باشد و پیکربندی models درست باشد. availableModels در سطح پروژه، نسخه سطح کاربر را کاملاً بازنویسی می‌کند و ادغامی انجام نمی‌شود. فهرست عیب‌یابی رسمی «id, name, provider» را به‌عنوان فیلدهای الزامی نام می‌برد، در حالی که جدول فیلدها فقط id را الزامی علامت می‌زند و نام فیلد را vendor می‌نامد؛ پر کردن id، name و vendor هر دو را پوشش می‌دهد.

HTTP 404¶

url یک ورودی Chat به /chat/completions نمی‌رسد، یا برابر https://api.qcode.cc/api است. ورودی‌های Chat همیشه از مسیر کامل https://api.qcode.cc/openai/v1/chat/completions استفاده می‌کنند؛ فقط ورودی‌هایی با "api": "openai-responses" در /openai/v1 متوقف می‌شوند.

HTTP 400 model_not_available_on_endpoint¶

یک شناسه claude-… به مسیر OpenAI ارسال شده است، برای مثال از طریق یک ورودی models.json یا از طریق CODEBUDDY_BASE_URL تنظیم‌شده روی https://api.qcode.cc/api. مدل‌های Claude فقط روی نقطه پایانی Anthropic ارائه می‌شوند؛ اینجا از یک مدل GPT یا چینی استفاده کنید، یا به ابزاری مانند Claude Code تغییر دهید. این خطا به معنای نامعتبر بودن کلید نیست.

HTTP 401¶

کلید باید با cr_ شروع شود و هیچ فاصله‌ای نداشته باشد. در ارجاع به متغیر محیطی، بررسی کنید که متغیر واقعاً export شده است: مستندات می‌گوید متغیر غایب، جای‌نگهدار اصلی را نگه می‌دارد، بنابراین مقدار تحت‌اللفظی ${QCODE_API_KEY} به‌عنوان کلید ارسال می‌شود.

آیا باید به حساب Tencent وارد شوم؟¶

برای این مدل‌ها خیر. در آزمون 2.182.0، codebuddy -p از طریق models.json و از طریق CODEBUDDY_BASE_URL بدون نیاز به ورود پاسخ داد.

آیا یک مدل سفارشی سرآیندهای هویت پلتفرم Tencent را ارسال می‌کند؟¶

یادداشت‌های انتشار رسمی CLI v2.180.0 می‌گوید مدل‌های سفارشی دیگر سرآیندهای درخواست هویت پلتفرم را همراه ندارند: وقتی یک مدل سفارشی مستقیماً به یک نقطه پایانی شخص ثالث متصل می‌شود، اطلاعات هویت دیگر به سرویسی که پیکربندی کرده‌اید ارسال نمی‌شود.

مطالب مرتبط¶

• مدل‌های سفارشی WorkBuddy — عامل اداری از همان تیم، همچنین روی OpenAI Chat Completions
• ZCode — ارائه‌دهندگان سفارشی روی پروتکل‌های Anthropic و OpenAI، از جمله Claude
• نقاط پایانی و مسیرهای API — سه پروتکل، سه دامنه، نگاشت BASE_URL
• مدل‌های چینی — شناسه‌های مدل GLM / Kimi / DeepSeek / Qwen
• نمای کلی سازگاری ابزارها — پروتکل‌های هر ابزار و اینکه Claude کار می‌کند یا نه
• شناسه‌ها و قیمت‌های به‌روز: qcode.cc/models

سازمانی ←