آموزش اتصال Coze (扣子) به QCode: افزونه سفارشی، درخواست HTTP و مدل سفارشی سازمانی

مرزهای واقعی اتصال Coze (扣子) به QCode و دو مسیر عملی آن را روشن می‌کند: حساب‌های شخصی و تیمی از طریق افزونه سفارشی یا درخواست HTTP در گردش‌کار مدل‌های claude-opus-5-5 و gpt-6.2-sol را فرا می‌خوانند؛ مدیران نسخه Enterprise Flagship در Coze Programming به‌صورت بومی gpt-6.2-sol و مدل‌های چینی را وصل می‌کنند.

به‌روزرسانی 2026-11-23

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

در این صفحه

با دنبال کردن ۷ قدم زیر می‌توانید بر اساس نسخه حساب Coze خود مسیر درست را انتخاب کنید، مدل‌های Claude، GPT و مدل‌های چینی QCode را به ایجنت یا گردش‌کار Coze وصل کنید و سابقه درخواست‌ها را در پنل بررسی کنید.

نتیجه در یک جمله: Coze هیچ کلید «Base URL مدل سفارشی سراسری» برای حساب شخصی ندارد. حساب‌های شخصی و تیمی باید از طریق «افزونه سفارشی» یا «گره درخواست HTTP در گردش‌کار» مستقیم به رابط QCode وصل شوند و می‌توانند هم‌زمان claude-opus-5-5 (رابط Anthropic) و gpt-6.2-sol (رابط سازگار با OpenAI) را فرا بخوانند؛ مدیران Enterprise Flagship می‌توانند در «Coze Programming (code.coze.cn) ← مدیریت سازمان Enterprise ← اتصال مدل ← مدل سفارشی» به‌صورت بومی gpt-6.2-sol و مدل‌های چینی را وصل کنند، اما پروتکل این ورودی ثابت روی OpenAI Chat Completions است و Claude را پشتیبانی نمی‌کند.

مسیر اتصال حساب‌های مناسب مدل‌های قابل استفاده QCode نشانی اتصال روش احراز هویت
افزونه سفارشی / HTTP گردش‌کار (Claude) همه حساب‌های Coze claude-opus-5-5 و سایر مدل‌های خانواده Claude https://api.qcode.cc/api/v1/messages سربرگ x-api-key: cr_xxxxxxxx و anthropic-version: 2023-06-01
افزونه سفارشی / HTTP گردش‌کار (GPT / مدل‌های چینی) همه حساب‌های Coze gpt-6.2-sol، مدل‌های چینی https://api.qcode.cc/openai/v1/chat/completions سربرگ Authorization: Bearer cr_xxxxxxxx
مدل سفارشی بومی (پنل Coze Programming) فقط مدیر سازمان Enterprise Flagship gpt-6.2-sol، مدل‌های چینی (Claude پشتیبانی نمی‌شود) https://api.qcode.cc/openai/v1 (خودکار /chat/completions اضافه می‌شود) احراز هویت را Authorization انتخاب کنید و cr_xxxxxxxx را وارد کنید (گزینه جایگزین Header)

بررسی‌شده در 2026-11-22 · Coze (coze.cn) و Coze Programming (code.coze.cn) · راهنمای ساختاریافته متنی

Coze (扣子) یک پلتفرم ابری برای ساختن ایجنت و گردش‌کار است که دو رابط دارد: محصول اصلی «Coze» (www.coze.cn) و «Coze Programming» (code.coze.cn) برای مدیریت سازمانی و کم‌کد. پیش از شروع، چهار محدودیت واقعی محصول را بشناسید تا در رابط دنبال گزینه‌هایی که وجود ندارند نگردید:

میزان پشتیبانی واقعی و مرزهای محدودیت: 1. ورود اجباری به حساب Coze: چه در نسخه وب و چه در نسخه دسکتاپ، باید با شماره تلفن، ایمیل یا اسکن کد وارد حساب پلتفرم Coze شوید و استفاده آفلاین بدون حساب پلتفرم ممکن نیست. 2. «اتصال مدل» بومی فقط برای مدیر Enterprise Flagship است: طبق مستندات رسمی Coze، ورودی بومی «اتصال مدل ← مدل سفارشی» فقط برای Enterprise Flagship باز است و تنها ابرمدیر سازمان یا مدیر آن را می‌بیند و می‌تواند پیکربندی کند؛ حساب‌های شخصی معمولی و فضای‌های کاری معمولی این ورودی را نمی‌بینند. 3. مدل سفارشی بومی از Claude پشتیبانی نمی‌کند: پروتکل API مدل سفارشی بومی Coze ثابت روی OpenAI Chat/completions است و همیشه از سرویس‌دهنده بالادست می‌خواهد پاسخ جریانی (stream=true) بدهد؛ هیچ گزینه‌ای برای پروتکل Anthropic Messages ندارد. نقطه پایانی سازگار با OpenAI در QCode مدل‌های Claude را نمی‌پذیرد، بنابراین claude-opus-5-5 فقط از طریق افزونه سفارشی یا درخواست HTTP در گردش‌کار قابل فراخوانی است. 4. مرزهای توانایی روش افزونه HTTP / گردش‌کار: وقتی حساب شخصی یا تیمی از طریق درخواست HTTP، QCode را صدا می‌زند، QCode نقش ابزار بیرونی ایجنت یا گره پردازش گردش‌کار را دارد و نمی‌تواند مدل زمان‌بند اصلی پیش‌فرض ایجنت را جایگزین کند؛ همچنین باید منتظر بازگشت کامل JSON بمانید و نتیجه را نشان دهید (بدون خروجی جریانی کلمه‌به‌کلمه بومی).

  • پلتفرم مناسب: نسخه وب در مرورگر (www.coze.cn / code.coze.cn)؛ به‌صورت اختیاری نسخه دسکتاپ ویندوز / macOS
  • مسیر اتصال: افزونه سفارشی / درخواست HTTP در گردش‌کار (همه حساب‌ها)؛ مدل سفارشی بومی (فقط مدیر Enterprise Flagship)
  • بررسی محتوا در: 2026-11-22
  • زمان تقریبی: 10–15 دقیقه
  • چیزهایی که لازم دارید: یک حساب Coze که وارد شده‌اید؛ یک کلید API QCode که با cr_ شروع می‌شود
  • در Coze ثبت‌نام کرده‌اید و می‌توانید وارد شوید (www.coze.cn)؛ اگر می‌خواهید از مدل سفارشی بومی استفاده کنید، مطمئن شوید سازمان شما Enterprise Flagship است، حساب فعلی ابرمدیر یا مدیر سازمان است و به Coze Programming (code.coze.cn) دسترسی دارید
  • در QCode.cc ثبت‌نام کرده‌اید و کلید API که با cr_ شروع می‌شود را از داشبورد کپی کرده‌اید. هنوز حساب ندارید؟ ابتدا ثبت‌نام QCode کنید، در صفحه قیمت‌ها پلن مناسب را انتخاب کنید و سپس در داشبورد کلید بسازید
  • مدلی که می‌خواهید صدا بزنید را مشخص کنید: اگر claude-opus-5-5 می‌خواهید از مسیر A (افزونه HTTP / گردش‌کار) استفاده کنید؛ برای gpt-6.2-sol یا مدل‌های چینی، حساب شخصی مسیر A را برود و مدیر Enterprise Flagship می‌تواند مسیر B (مدل سفارشی بومی) را برود
  • شبکه فعلی می‌تواند www.coze.cn، code.coze.cn، api.qcode.cc و probe.qcode.cc را باز کند
به کلید API نیاز دارید؟

اگر هنوز حساب QCode ندارید، ابتدا ثبت‌نام QCode کنید. اگر می‌خواهید به‌ازای مصرف پرداخت کنید، ابتدا یک بسته پرداخت به‌ازای مصرف بخرید و سپس در داشبورد کلید بسازید و کلید کاملِ ساخته‌شده را که با cr_ شروع می‌شود کپی کنید. می‌توانید با کارت اعتباری / نقدی (Visa / Mastercard)، یا Apple Pay / Google Pay، یا رمزارز پرداخت کنید — به روش‌های پرداخت مراجعه کنید.

آماده‌سازی: تأیید ورودی و انتخاب مسیر اتصال

همه پیکربندی‌های Coze را می‌توان مستقیم در مرورگر انجام داد و نصب کلاینت دسکتاپ لازم نیست. اگر به نسخه دسکتاپ عادت دارید، فقط می‌توانید در صفحه اصلی سایت رسمی Coze نشانگر را روی «下载桌面端» (دانلود نسخه دسکتاپ) ببرید و بسته نصب ویندوز یا macOS را بگیرید (Coze نرم‌افزار دسکتاپ متن‌باز نیست و بسته GitHub Releases، winget یا Microsoft Store ندارد؛ پس از نصب به‌طور پیش‌فرض وارد میزکار ایجنت Coze می‌شوید و برای پیکربندی مدل سفارشی سازمانی همچنان باید مرورگر را باز کنید و به code.coze.cn بروید).

بر اساس نسخه حساب و مدل هدف خود، مسیر مناسب را در پایین انتخاب کنید:

  • مناسب برای: همه حساب‌های Coze (شامل حساب شخصی معمولی، فضای کاری تیمی، و کاربران سازمانی که می‌خواهند claude-opus-5-5 را صدا بزنند).
  • مدل‌های پشتیبانی‌شده: هم‌زمان claude-opus-5-5 (از نقطه پایانی Anthropic https://api.qcode.cc/api/v1/messages) و gpt-6.2-sol و مدل‌های چینی (از نقطه پایانی سازگار با OpenAI https://api.qcode.cc/openai/v1/chat/completions).
  • قدم‌های کار: قدم ۱ ← قدم ۲ ← قدم ۳ ← قدم ۴ ← قدم ۷ زیر را انجام دهید (از قدم‌های ۵ و ۶ که فقط برای مدیر سازمانی است بگذرید).
  • مناسب برای: کاربرانی که Enterprise Flagship در Coze را فعال کرده‌اند و حساب فعلی‌شان ابرمدیر یا مدیر سازمان است.
  • مدل‌های پشتیبانی‌شده: gpt-6.2-sol و مدل‌های چینی (از https://api.qcode.cc/openai/v1)؛ خانواده Claude پشتیبانی نمی‌شود (ورودی بومی Coze پروتکل Anthropic ندارد).
  • مزیت اصلی: پس از اتصال و اعطای دسترسی به فضای کاری، اعضا می‌توانند در انتخاب‌گر مدل صفحه چینش ایجنت مثل مدل‌های داخلی مستقیم سوییچ کنند و پاسخ جریانی بومی هم پشتیبانی می‌شود.
  • قدم‌های کار: قدم ۱ ← قدم ۵ ← قدم ۶ ← قدم ۷ زیر را انجام دهید (نیازی به پیکربندی افزونه HTTP در قدم‌های ۲ تا ۴ نیست).

راهنمای پیکربندی گام‌به‌گام

ابتدا کلید و اتصال نقطه پایانی QCode را محلی بررسی کنید

پیش از ورود به پنل Coze، در ترمینال محلی (Windows PowerShell، ترمینال macOS یا Linux Shell) یک درخواست آزمایشی حداقلی بفرستید و مطمئن شوید کلید cr_ و مدل هدف شما درست کار می‌کنند. این‌طور اگر بعداً در Coze خطایی دیدید، فوراً می‌توانید تشخیص دهید مشکل از پیکربندی فرم Coze است نه از خود کلید.

بر اساس خانواده مدلی که می‌خواهید صدا بزنید زبانه را عوض کنید، cr_xxxxxxxx را با کلید واقعی خود جایگزین کنید و اجرا کنید:

curl -sS https://api.qcode.cc/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: cr_xxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "سلام، در یک جمله خودت را معرفی کن"}
    ]
  }'
curl -sS https://api.qcode.cc/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cr_xxxxxxxx" \
  -d '{
    "model": "gpt-6.2-sol",
    "stream": false,
    "messages": [
      {"role": "user", "content": "سلام، در یک جمله خودت را معرفی کن"}
    ]
  }'

اگر درست پیش بروید این را می‌بینید: ترمینال یک JSON کامل برمی‌گرداند؛ فیلد content[0].text در پاسخ Claude، یا فیلد choices[0].message.content در پاسخ GPT، یک معرفی یک‌جمله‌ای از خودِ مدل دارد و هیچ شیء error وجود ندارد.

گیر کرده‌اید؟ تست محلی 401 یا model_not_available_on_endpoint برمی‌گرداند

سه نکته را به ترتیب بررسی کنید: 1) کلید باید کامل و با cr_ شروع شود و بعد از گیومه و دونقطه، خط جدید یا فاصله اضافی نچسبانده باشید؛ 2) claude-opus-5-5 باید به https://api.qcode.cc/api/v1/messages و با سربرگ x-api-key درخواست شود و به /openai/v1 فرستاده نشود؛ 3) gpt-6.2-sol باید به https://api.qcode.cc/openai/v1/chat/completions و با Authorization: Bearer cr_xxxxxxxx درخواست شود. در Windows PowerShell اگر مشکل escape شدن کوتیشن تک بود، از curl.exe استفاده کنید یا درخواست را مستقیم با قابلیت تست گره HTTP در گردش‌کار Coze بررسی کنید.

مسیر A: رابط QCode را در گره HTTP گردش‌کار یا افزونه سفارشی وارد کنید

وارد سایت اصلی Coze شوید و به فضای کاری هدف بروید، سپس بر اساس روش استفاده خود یکی را انتخاب کنید:

  • گره درخواست HTTP در گردش‌کار (سریع‌ترین شروع): یک گردش‌کار بسازید یا باز کنید، در بوم یک گره «درخواست HTTP» (HTTP 请求) اضافه کنید و متد درخواست را POST بگذارید.
  • افزونه سفارشی (برای استفاده دوباره در چند ایجنت): به صفحه افزونه‌ها / کتابخانه منابع فضای کاری بروید، ساخت افزونه سفارشی بر پایه سرویس HTTP موجود را انتخاب کنید و یک ابزار با متد POST اضافه کنید.

بر اساس خانواده مدلی که می‌خواهید صدا بزنید، طبق زبانه مربوطه در پایین URL، سربرگ‌ها (Headers) و بدنه JSON (Body) را پر کنید. در این‌جا {{user_prompt}} یعنی متغیر متنی که در گره ورودی گردش‌کار یا پارامتر ورودی افزونه تعریف می‌کنید؛ در پیکربندی واقعی آن را با انتخاب‌گر متغیر رابط Coze وارد کنید:

مورد پیکربندی مقدار
متد درخواست POST
URL کامل درخواست https://api.qcode.cc/api/v1/messages (اگر افزونه آدرس پایه و مسیر را جدا می‌گیرد: آدرس پایه را https://api.qcode.cc/api و مسیر را /v1/messages بگذارید)
Header 1 Content-Type: application/json
Header 2 x-api-key: cr_xxxxxxxx (با کلید خود جایگزین کنید، پیشوند Bearer را نگذارید)
Header 3 anthropic-version: 2023-06-01

نوع Body را JSON انتخاب کنید و این را بنویسید:

{
  "model": "claude-opus-5-5",
  "max_tokens": 2048,
  "messages": [
    {
      "role": "user",
      "content": "{{user_prompt}}"
    }
  ]
}
مورد پیکربندی مقدار
متد درخواست POST
URL کامل درخواست https://api.qcode.cc/openai/v1/chat/completions (اگر افزونه آدرس پایه و مسیر را جدا می‌گیرد: آدرس پایه را https://api.qcode.cc/openai/v1 و مسیر را /chat/completions بگذارید)
Header 1 Content-Type: application/json
Header 2 Authorization: Bearer cr_xxxxxxxx (بین Bearer و کلید یک فاصله انگلیسی بگذارید)

نوع Body را JSON انتخاب کنید و این را بنویسید:

{
  "model": "gpt-6.2-sol",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": "{{user_prompt}}"
    }
  ]
}

اگر می‌خواهید از مدل چینی استفاده کنید، فقط "model" را به شناسه مدلی مثل glm-5.3، kimi-k3، deepseek-v4-pro یا qwen3.8-max تغییر دهید که نقطه پایانی سازگار با OpenAI پشتیبانی می‌کند.

اگر درست پیش بروید این را می‌بینید: متد درخواست POST است، URL دقیقاً با پروتکل خانواده مدل می‌خواند، در Headers هم کلید و هم سربرگ نسخه هست، و ویرایش‌گر JSON هیچ خط قرمز نگارشی نشان نمی‌دهد.

گیر کرده‌اید؟ JSON خطای قالب می‌دهد، یا نمی‌دانید تاریخچه چندنوبتی را چطور پر کنید

ابتدا مطمئن شوید همه گیومه‌ها گیومه دوتایی انگلیسی نیم‌عرض " هستند، بعد از آخرین فیلد کامای اضافی نمانده و "stream" روی false است (گره HTTP گردش‌کار و افزونه به‌طور پیش‌فرض پاسخ را به‌صورت یک JSON یک‌باره تفسیر می‌کنند؛ روشن کردن حالت جریانی باعث می‌شود بدنه پاسخ به قطعه‌های چندخطی data: تبدیل شود و قابل تفسیر نباشد). اگر ورودی کاربر ممکن است گیومه دوتایی یا خط جدید داشته باشد، بهتر است آن را از طریق «پیوند پارامتر JSON / ورودی ساختاریافته» در گردش‌کار یا افزونه Coze بفرستید و متن بلند escape‌نشده را مستقیم داخل رشته JSON نچسبانید.

مسیر A: استخراج فیلد پاسخ را پیکربندی کنید و آزمایشی اجرا کنید

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

ساختار پاسخ نمونه:

{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "سلام، من Claude هستم و می‌توانم در استدلال، نوشتن و کارهای برنامه‌نویسی کمکتان کنم."
    }
  ],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 32
  }
}
  • مسیر استخراج متن: content[0].text (در گردش‌کار می‌توانید همراه با «گره کد» یا پیکربندی پارامتر خروجی، مستقیم body.content[0].text را بخوانید).

ساختار پاسخ نمونه:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-6.2-sol",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "سلام، می‌توانم در پاسخ‌گویی، تحلیل و نوشتن کد کمکتان کنم."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 24,
    "total_tokens": 42
  }
}
  • مسیر استخراج متن: choices[0].message.content (با خواندن body.choices[0].message.content متن خالص پاسخ را می‌گیرید).

پس از پیکربندی پارامترهای خروجی، روی «اجرای آزمایشی / اشکال‌زدایی» گردش‌کار یا ابزار افزونه کلیک کنید، به user_prompt جمله «سلام، در یک جمله خودت را معرفی کن» بدهید و کد وضعیت بازگشتی و متن استخراج‌شده را ببینید.

اگر درست پیش بروید این را می‌بینید: اشکال‌زدایی کد وضعیت HTTP 200 برمی‌گرداند و در پنل خروجی، پاسخ متنی خالص و بدون ساختار JSON بیرونی با موفقیت استخراج می‌شود.

گیر کرده‌اید؟ اجرای آزمایشی زمان‌بندی تمام می‌شود یا فیلد خروجی خالی است

1) اگر درخواست زمان‌بندی تمام شد، ابتدا max_tokens را کمی کوچک‌تر کنید (مثلاً 1024) تا پاسخ کوتاه آزمایش شود و دامنه URL را از api.qcode.cc به گره آسیا asia.qcode.cc عوض کنید (مثلاً https://asia.qcode.cc/api/v1/messages یا https://asia.qcode.cc/openai/v1/chat/completions)؛ 2) اگر کد وضعیت 200 است اما فیلد استخراج‌شده خالی است، بدنه پاسخ خام body را باز کنید و ببینید آیا content[0].text و choices[0].message.content را جای هم نگذاشته‌اید، یا فراموش نکرده‌اید رشته بدنه پاسخ را ابتدا به شیء JSON تبدیل کنید.

مسیر A: انتشار و اتصال به ایجنت Coze

پس از موفقیت اشکال‌زدایی، افزونه سفارشی یا گردش‌کار خود را در فضای کاری فعلی منتشر کنید و سپس صفحه چینش ایجنت هدف را باز کنید:

  1. در بخش «مهارت‌ها» صفحه چینش، افزونه یا گردش‌کاری را که تازه منتشر کرده‌اید به ایجنت اضافه کنید.
  2. در «شخصیت و منطق پاسخ (پرامپت سیستم)» قاعده فعال‌سازی را صریح بنویسید تا مدل پیش‌فرض Coze افزونه را رد نکند و خودش جواب ندهد. مثلاً:
وقتی کاربر درخواست نوشتن کد پیچیده، تحلیل عمیق یا پاسخ با مدل QCode را به‌صراحت مطرح می‌کند، باید افزونه/گردش‌کار متصل‌شده QCode را صدا بزنید، پرسش کامل کاربر را در پارامتر `user_prompt` بگذارید و نتیجه متنی بازگشتی ابزار را دقیق به کاربر نشان دهید؛ خودتان پاسخ جایگزین نسازید.

پس از ذخیره، در کادر گفت‌وگوی «پیش‌نمایش و اشکال‌زدایی» سمت راست پیامی بفرستید که شرط بالا را فعال کند (مثلاً «لطفاً ابزار QCode را صدا بزن و در یک جمله خودت را معرفی کن») و ببینید آیا در فرایند اشکال‌زدایی واقعاً افزونه یا گردش‌کار صدا زده می‌شود.

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

گیر کرده‌اید؟ ایجنت افزونه را صدا نمی‌زند و خودش جواب می‌دهد

سه جا را اول بررسی کنید: 1) افزونه یا گردش‌کار باید روی «انتشار» (发布) کلیک شده باشد؛ ذخیره پیش‌نویس برای فراخوانی پایدار توسط ایجنت کافی نیست؛ 2) توضیح انگلیسی/چینی ابزار افزونه و توضیح پارامتر user_prompt باید کاربرد را روشن بگویند تا مدل زمان‌بند آن را تشخیص دهد؛ 3) اگر می‌خواهید هر دور ورودی کاربر اجباری از QCode برود و مدل پیش‌فرض تصمیم نگیرد که فعال شود، می‌توانید ایجنت را به حالت گردش‌کارمحور ببرید تا ورودی کاربر مستقیم به گردش‌کاری برود که گره HTTP مربوط به QCode را دارد.

مسیر B (فقط مدیر Enterprise Flagship): اتصال مدل سفارشی بومی در پنل Coze Programming

این قدم و قدم ۶ فقط برای ابرمدیر یا مدیر سازمان Enterprise Flagship در Coze است. اگر حساب شخصی معمولی دارید، مستقیم به قدم ۷ بروید و سابقه درخواست‌ها را بررسی کنید.

  1. Coze Programming را در مرورگر باز کنید code.coze.cn و با حساب مدیر سازمانی خود وارد شوید.
  2. روی تصویر پروفایل در گوشه پایین-چپ صفحه کلیک کنید، حساب سازمانی مربوطه را انتخاب کنید، سپس روی آیکون «تنظیمات» آن سازمان کلیک کنید تا به «مدیریت سازمان Enterprise» بروید.
  3. در «مدیریت سازمان Enterprise» به ترتیب وارد «اتصال مدل ← مدل سفارشی» (模型接入 → 自定义模型) شوید و روی «اتصال مدل» (接入模型) کلیک کنید.
  4. در پنجره بازشده پارامترها را طبق جدول پایین پر کنید، سپس در صورت نیاز قابلیت‌های مدل (مثل فراخوانی ابزار، تفکر عمیق) و طول زمینه را تیک بزنید و ذخیره کنید:
فیلد فرم مقدار توضیح
نام نمایشی مدل QCode GPT 6.2 Sol (قابل تغییر) فقط نامی را تغییر می‌دهد که اعضا در رابط می‌بینند
شناسه یکتای مدل gpt-6.2-sol مستقیم در فیلد model درخواست نوشته می‌شود؛ می‌توانید شناسه مدل چینی مثل glm-5.3 را هم بگذارید، هرگز مدل Claude نگذارید
URL مدل API https://api.qcode.cc/openai/v1 Coze خودکار /chat/completions را اضافه می‌کند، دست‌نویس نکنید /chat/completions را
پروتکل API OpenAI Chat/completions گزینه ثابت پلتفرم است و تغییر نمی‌کند
روش احراز هویت Authorization روش جایگزین Header است (راهنمای بازشوی پایین را ببینید)
کلید احراز هویت cr_xxxxxxxx کلید QCode را بگذارید؛ روش ذخیره‌سازی متن ساده کافی است و نیازی به اتصال به KMS ولکان (火山 KMS) نیست

اگر درست پیش بروید این را می‌بینید: پس از ذخیره موفق به فهرست «مدل سفارشی» برمی‌گردید و QCode GPT 6.2 Sol که تازه وصل کرده‌اید به‌طور عادی در فهرست دیده می‌شود، بدون هشدار توقف یا خطا.

گیر کرده‌اید؟ «模型接入» پیدا نمی‌شود، یا تست اتصال 401 / 404 می‌دهد
  • «اتصال مدل» به‌کل دیده نمی‌شود: مطمئن شوید حساب انتخاب‌شده سازمانی است نه شخصی، و آن سازمان Enterprise Flagship را فعال کرده و نقش شما ابرمدیر یا مدیر سازمان است. اگر شرط‌ها برقرار نباشد این ورودی نمایش داده نمی‌شود؛ از مسیر A استفاده کنید.
  • خطای 404: بررسی کنید «URL مدل API» فقط تا /openai/v1 پر شده باشد و در پایان /chat/completions یا اسلش اضافی ننوشته باشید.
  • خطای 401 / شکست احراز هویت: ابتدا مطمئن شوید کلید با cr_ شروع می‌شود و فاصله اضافی ندارد؛ اگر با Authorization هم 401 گرفتید، روش احراز هویت را به Header تغییر دهید، Header Key را Authorization و Header Value را Bearer cr_xxxxxxxx بگذارید و دوباره ذخیره و تست کنید.

مسیر B (فقط مدیر Enterprise Flagship): اعطای دسترسی به فضای کاری و انتخاب در ایجنت

پس از اتصال مدل سفارشی در Coze، مدل به‌طور پیش‌فرض برای هیچ فضای کاری قابل استفاده نیست و مدیر باید دسترسی را دستی روشن کند تا اعضا آن را ببینند:

  1. در فهرست «مدیریت سازمان Enterprise ← اتصال مدل ← مدل سفارشی» بمانید، مدلی را که تازه وصل کرده‌اید پیدا کنید و روی «… ← تغییر فضاهای موجود» (修改可用空间) سمت راست همان ردیف کلیک کنید.
  2. در پنجره بازشده کلید فعال‌سازی فضای کاری هدف را روشن کنید و ذخیره کنید.
  3. به صفحه چینش ایجنت Coze برگردید (یا از عضو فضای کاری هدف بخواهید صفحه چینش را باز کند)، انتخاب‌گر مدل را باز کنید و در گروه «مدل سفارشی» مدل QCode GPT 6.2 Sol را که تازه وصل کرده‌اید انتخاب کنید.
  4. در کادر گفت‌وگوی سمت راست «سلام، در یک جمله خودت را معرفی کن» بنویسید و بفرستید و ببینید پاسخ جریانی درست کلمه‌به‌کلمه بیرون می‌آید یا نه.

اگر درست پیش بروید این را می‌بینید: کلید فعال‌سازی فضای کاری هدف روشن است؛ در گروه «مدل سفارشی» فهرست مدل‌های ایجنت می‌توانید این مدل را انتخاب کنید و پس از ارسال پیام، پاسخ جریانی عادی می‌آید، بدون خطای 401، 404 یا model not found.

گیر کرده‌اید؟ اعضا مدل را نمی‌بینند، یا پس از ارسال پیام مدام می‌چرخد و پاسخی نمی‌آید
  • اعضا مدل را نمی‌بینند: به «تغییر فضاهای موجود» برگردید و مطمئن شوید همان فضای کاری که عضو اکنون در آن است انتخاب شده و از عضو بخواهید صفحه چینش را دوباره بارگذاری کند.
  • پیام «مدل وجود ندارد»: بررسی کنید «شناسه یکتای مدل» به‌اشتباه با نام نمایشی پر نشده باشد (مثلاً QCode GPT 6.2 Sol گذاشته باشید)؛ باید شناسه مدلی باشد که QCode واقعاً پشتیبانی می‌کند (مثل gpt-6.2-sol).
  • هنگام ارسال پیام مدام می‌چرخد: مدل سفارشی بومی Coze همیشه با حالت جریانی (stream=true) از بالادست درخواست می‌کند؛ مطمئن شوید URL روی https://api.qcode.cc/openai/v1 است (در محیط سرزمین اصلی می‌توانید https://asia.qcode.cc/openai/v1 را هم بگذارید) و سیاست خروج شبکه سازمان آن را مسدود نکرده باشد.

سابقه درخواست‌ها را در probe.qcode.cc بررسی کنید

چه مسیر A را رفته باشید و چه مسیر B، در پایان بهتر است یک‌بار لاگ واقعی درگاه را بررسی کنید تا مطمئن شوید پاسخ واقعاً از QCode آمده و مدل داخلی Coze جواب نداده است:

  1. در مرورگر probe.qcode.cc را باز کنید.
  2. همان کلید API cr_ را که در Coze استفاده کرده‌اید بچسبانید و روی «查询» (جست‌وجو) کلیک کنید.
  3. به فهرست درخواست‌ها پایین بروید و بررسی کنید زمان درخواست آخرین رکورد با لحظه‌ای که در Coze اشکال‌زدایی یا گفت‌وگو کرده‌اید یکی باشد و ستون کد وضعیت 200 نشان دهد.

اگر درست پیش بروید این را می‌بینید: بالای فهرست درخواست‌ها رکوردی می‌آید که زمانش با لحظه تست شما می‌خواند، وضعیت 200 است و داده‌های زمان تا اولین توکن و زمان کل هم دارد.

بررسی موفقیت

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

  • دستور تست محلی برای claude-opus-5-5 یا gpt-6.2-sol هر دو 200 و متن معتبر برمی‌گرداند؛
  • مسیر A: اجرای آزمایشی گره HTTP گردش‌کار یا افزونه سفارشی Coze 200 برمی‌گرداند، content[0].text (Claude) یا choices[0].message.content (GPT / مدل چینی) با موفقیت استخراج می‌شود و در ناحیه پیش‌نمایش ایجنت، فراخوانی موفق ابزار دیده می‌شود؛
  • مسیر B: وضعیت «مدل سفارشی» در Enterprise Flagship عادی است، کلید فضای کاری هدف روشن شده و اعضا پس از انتخاب gpt-6.2-sol در گروه «مدل سفارشی» ایجنت، پاسخ جریانی می‌گیرند؛
  • در probe.qcode.cc با همان کلید، رکورد درخواستی با زمان متناظر و کد وضعیت 200 پیدا می‌شود.

همه‌چیز تمام شد

شما QCode را به Coze وصل کرده‌اید و مرزهای دو مسیر — افزونه سفارشی / درخواست HTTP و مدل سفارشی بومی سازمانی — را خوب می‌شناسید. از این‌جا می‌توانید:

خطاهای رایج

متن / نشانه خطا علت چه کار کنید
ورودی «اتصال مدل ← مدل سفارشی» پیدا نمی‌شود مدل سفارشی بومی فقط برای ابرمدیر یا مدیر سازمان Enterprise Flagship باز است و حساب شخصی معمولی این منو را ندارد بررسی کنید حساب سازمانی انتخاب شده و Enterprise Flagship فعال است؛ حساب شخصی یا تیمی معمولی مستقیم از مسیر A (افزونه سفارشی / درخواست HTTP در گردش‌کار) این آموزش استفاده کند
model_not_available_on_endpoint claude-opus-5-5 را در نقطه پایانی سازگار با OpenAI (/openai/v1) یا در مدل سفارشی بومی Coze گذاشته‌اید نقطه پایانی سازگار با OpenAI در QCode مدل Claude را نمی‌پذیرد. فراخوانی claude-opus-5-5 باید از طریق درخواست HTTP مستقیم به نقطه پایانی Anthropic https://api.qcode.cc/api/v1/messages باشد؛ در مدل سفارشی بومی Coze فقط gpt-6.2-sol یا مدل چینی می‌توان گذاشت
404 Not Found مسیر URL نمی‌خواند: در مدل سفارشی بومی /chat/completions اضافه نوشته شده، یا در افزونه HTTP پسوند مسیر جا افتاده «URL مدل API» در مدل سفارشی بومی فقط تا https://api.qcode.cc/openai/v1 پر شود (Coze خودکار /chat/completions را اضافه می‌کند)؛ در گره درخواست HTTP باید آدرس کامل نوشته شود (/api/v1/messages یا /openai/v1/chat/completions)
401 Unauthorized / شکست احراز هویت کلید کامل نیست، فاصله قبل یا بعد دارد، یا قالب سربرگ احراز هویت با پروتکل رابط نمی‌خواند بررسی کنید کلید کامل با cr_ شروع شود؛ رابط Anthropic از x-api-key: cr_... + anthropic-version: 2023-06-01 استفاده می‌کند؛ رابط HTTP سازگار با OpenAI از Authorization: Bearer cr_...؛ در مدل سفارشی بومی اگر با Authorization هم 401 گرفتید، احراز هویت Header را امتحان کنید و Bearer cr_... را دست‌نویس بگذارید
Model not found / مدل وجود ندارد نام نمایشی سفارشی در شناسه مدل گذاشته شده، یا نام مدل غلط نوشته شده «شناسه یکتای مدل» یا فیلد "model" در JSON را بررسی کنید و شناسه مدلی را بگذارید که QCode واقعاً پشتیبانی می‌کند (مثل claude-opus-5-5، gpt-6.2-sol، glm-5.3)
گره HTTP در تفسیر JSON شکست می‌خورد، یا گفت‌وگوی بومی مدام می‌چرخد تنظیم جریانی برعکس موقعیت است: گره HTTP جریان SSE می‌گیرد و نمی‌تواند آن را مثل JSON عادی تفسیر کند، یا مسیر بومی سازمانی در شبکه مسدود شده بدنه درخواست افزونه HTTP / گردش‌کار باید صریح "stream": false داشته باشد؛ مدل سفارشی بومی سازمانی همیشه stream=true است، پس مطمئن شوید شبکه پایدار به api.qcode.cc وصل می‌شود یا asia.qcode.cc را امتحان کنید
اعضا مدل سفارشی تازه‌وصل‌شده را در فهرست مدل‌های ایجنت نمی‌بینند مدل تازه‌وصل‌شده در پنل سازمانی به‌طور پیش‌فرض برای همه فضاهای کاری خاموش است مدیر به فهرست «مدل سفارشی» برگردد، روی «… ← تغییر فضاهای موجود» سمت راست آن مدل کلیک کند و کلید فضای کاری هدف را دستی روشن کند

سوالات متداول

پس از انقضای کلید چه کنم؟

دو حالت دارد:

  • کلید پلن شخصی پس از انقضا تمدید نمی‌شود؛ فقط می‌توانید دوباره پلن بگیرید و کلید تازه بسازید و جایگزین کنید؛
  • کلید بسته پرداخت به‌ازای مصرف پس از انقضا با خرید یک بسته جدید به‌ازای مصرف، خودکار برمی‌گردد؛ همان کلید است و نیازی به تغییر پیکربندی در Coze نیست.

اگر کلید را عوض کردید، یادتان باشد کلید سربرگ درخواست در افزونه سفارشی / گره HTTP گردش‌کار Coze (مسیر A) را هم به‌روز کنید، یا در «Coze Programming ← مدیریت سازمان Enterprise ← اتصال مدل ← مدل سفارشی» کلید احراز هویت مدل مربوطه را ویرایش کنید (مسیر B).

چرا حساب شخصی معمولی نمی‌تواند مدل پیش‌فرض ایجنت Coze را مستقیم عوض کند؟

این محدودیت مجوز و طراحی خودِ پلتفرم Coze است: ورودی بومی «مدل سفارشی» فعلاً فقط برای ابرمدیر و مدیر سازمان Enterprise Flagship باز است و پنل حساب شخصی هیچ گزینه‌ای برای تنظیم Base URL مدل سفارشی ندارد. حساب شخصی اگر می‌خواهد در Coze از QCode استفاده کند، می‌تواند از طریق افزونه سفارشی یا گره درخواست HTTP در گردش‌کار، QCode را به‌عنوان ابزار یا گره پردازش وصل کند.

چرا در «مدل سفارشی» Enterprise Flagship نمی‌توان claude-opus-5-5 را وصل کرد؟

پروتکل API «مدل سفارشی» بومی Coze ثابت روی OpenAI Chat/completions است و پلتفرم گزینه‌ای برای پروتکل Anthropic Messages ندارد؛ از طرف دیگر نقطه پایانی سازگار با OpenAI در QCode فقط به GPT و مدل‌های چینی سرویس می‌دهد و درخواست Claude را نمی‌پذیرد. بنابراین کاربران سازمانی هم اگر بخواهند در Coze claude-opus-5-5 را صدا بزنند، باید از طریق افزونه سفارشی یا گره درخواست HTTP در گردش‌کار مستقیم به https://api.qcode.cc/api/v1/messages وصل شوند.

اگر درخواست HTTP گردش‌کار گاهی زمان‌بندی تمام کند چه کنم؟

سه جهت را بررسی کنید: 1) دامنه درخواست را از گره جهانی api.qcode.cc به گره آسیا asia.qcode.cc عوض کنید (مسیر نزدیک‌تر است و همان کلید کار می‌کند)؛ 2) در بدنه درخواست max_tokens را معقول نگه دارید (مثلاً 1024–2048) و پرامپت را کوتاه کنید تا زمان تولید هر پاسخ کم شود؛ 3) تنظیمات timeout گره HTTP گردش‌کار را کمی بزرگ‌تر کنید تا پاسخ‌های بلند زودتر از موعد توسط گره Coze بریده نشوند.

آیا Coze به نصب نسخه دسکتاپ نیاز دارد؟ بسته نصب متن‌باز دارد؟

نه. چه پیکربندی افزونه سفارشی، چه ساختن گردش‌کار و چه مدیریت مدل سفارشی سازمانی در code.coze.cn، همه در نسخه وب مرورگر انجام می‌شود. Coze نسخه دسکتاپ ویندوز و macOS هم دارد، اما نرم‌افزار متن‌باز نیست و بسته GitHub Releases، winget یا Microsoft Store ندارد؛ فقط از صفحه رسمی www.coze.cn و بخش «下载桌面端» (دانلود نسخه دسکتاپ) قابل دریافت است.

نمای کلی اتصال و مدل‌های قابل استفاده

نقاط اتصال QCode و نشانی پروتکل

سه دامنه اتصال توانایی یکسان دارند و همان کلید cr_ در همه کار می‌کند؛ بر اساس محیط شبکه‌ای که Coze در آن است یکی را انتخاب کنید:

گره رابط Anthropic (فقط درخواست HTTP مسیر A) Base URL سازگار با OpenAI (مسیر A باید /chat/completions اضافه کند؛ مسیر B تا همین‌جا پر می‌شود)
جهانی https://api.qcode.cc/api/v1/messages https://api.qcode.cc/openai/v1
آسیا (انتخاب اول سرزمین اصلی) https://asia.qcode.cc/api/v1/messages https://asia.qcode.cc/openai/v1
آمریکای شمالی / اروپا https://us.qcode.cc/api/v1/messages https://us.qcode.cc/openai/v1

مقایسه مدل‌های پیشنهادی و مسیرهای Coze

مدل شناسه مدل مسیر مناسب نقطه پایانی پروتکل
Claude Opus 5.5 claude-opus-5-5 فقط مسیر A (افزونه سفارشی / HTTP گردش‌کار) Anthropic (/api/v1/messages)
GPT 6.2 Sol gpt-6.2-sol مسیر A و مسیر B (مدل سفارشی بومی سازمانی) هر دو سازگار با OpenAI (/openai/v1)
مدل‌های اصلی چینی glm-5.3، kimi-k3، deepseek-v4-pro، qwen3.8-max و مانند آن مسیر A و مسیر B هر دو سازگار با OpenAI (/openai/v1)

QCode فعلاً مدل‌های Gemini را ارائه نمی‌کند، پس در Coze از Claude، GPT یا مدل‌های چینی استفاده کنید. فهرست کامل شناسه مدل‌های چینی در اتصال مدل‌های چینی است و مدل‌های در حال فروش لحظه‌ای را در qcode.cc/models ببینید.

مستندات مرتبط

با QCode شروع کنید

یک کلید API برای Claude Code، Codex و بیشتر — بر اساس توکن، قیمت هر مدل در qcode.cc/models

سازمانی ←