آموزش اتصال Coze (扣子) به QCode: افزونه سفارشی، درخواست HTTP و مدل سفارشی سازمانی
مرزهای واقعی اتصال Coze (扣子) به QCode و دو مسیر عملی آن را روشن میکند: حسابهای شخصی و تیمی از طریق افزونه سفارشی یا درخواست HTTP در گردشکار مدلهای claude-opus-5-5 و gpt-6.2-sol را فرا میخوانند؛ مدیران نسخه Enterprise Flagship در Coze Programming بهصورت بومی gpt-6.2-sol و مدلهای چینی را وصل میکنند.
به کلید API نیاز دارید؟ ثبتنام ←نقاط پایانی و Base URL ←
در این صفحه
- آمادهسازی: تأیید ورودی و انتخاب مسیر اتصال
- راهنمای پیکربندی گامبهگام
- ابتدا کلید و اتصال نقطه پایانی QCode را محلی بررسی کنید
- مسیر A: رابط QCode را در گره HTTP گردشکار یا افزونه سفارشی وارد کنید
- مسیر A: استخراج فیلد پاسخ را پیکربندی کنید و آزمایشی اجرا کنید
- مسیر A: انتشار و اتصال به ایجنت Coze
- مسیر B (فقط مدیر Enterprise Flagship): اتصال مدل سفارشی بومی در پنل Coze Programming
- مسیر B (فقط مدیر Enterprise Flagship): اعطای دسترسی به فضای کاری و انتخاب در ایجنت
- سابقه درخواستها را در probe.qcode.cc بررسی کنید
- بررسی موفقیت
- خطاهای رایج
- سوالات متداول
- نمای کلی اتصال و مدلهای قابل استفاده
- مستندات مرتبط
با دنبال کردن ۷ قدم زیر میتوانید بر اساس نسخه حساب 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 بمانید و نتیجه را نشان دهید (بدون خروجی جریانی کلمهبهکلمه بومی).
- در 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(از نقطه پایانی Anthropichttps://api.qcode.cc/api/v1/messages) وgpt-6.2-solو مدلهای چینی (از نقطه پایانی سازگار با OpenAIhttps://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¶
پس از موفقیت اشکالزدایی، افزونه سفارشی یا گردشکار خود را در فضای کاری فعلی منتشر کنید و سپس صفحه چینش ایجنت هدف را باز کنید:
- در بخش «مهارتها» صفحه چینش، افزونه یا گردشکاری را که تازه منتشر کردهاید به ایجنت اضافه کنید.
- در «شخصیت و منطق پاسخ (پرامپت سیستم)» قاعده فعالسازی را صریح بنویسید تا مدل پیشفرض Coze افزونه را رد نکند و خودش جواب ندهد. مثلاً:
وقتی کاربر درخواست نوشتن کد پیچیده، تحلیل عمیق یا پاسخ با مدل QCode را بهصراحت مطرح میکند، باید افزونه/گردشکار متصلشده QCode را صدا بزنید، پرسش کامل کاربر را در پارامتر `user_prompt` بگذارید و نتیجه متنی بازگشتی ابزار را دقیق به کاربر نشان دهید؛ خودتان پاسخ جایگزین نسازید.
پس از ذخیره، در کادر گفتوگوی «پیشنمایش و اشکالزدایی» سمت راست پیامی بفرستید که شرط بالا را فعال کند (مثلاً «لطفاً ابزار QCode را صدا بزن و در یک جمله خودت را معرفی کن») و ببینید آیا در فرایند اشکالزدایی واقعاً افزونه یا گردشکار صدا زده میشود.
اگر درست پیش بروید این را میبینید: در فرایند فراخوانی ناحیه پیشنمایش، سابقه اجرای افزونه یا گردشکاری که تازه متصل کردهاید دیده میشود، وضعیت موفق است و حباب گفتوگو پاسخی را نشان میدهد که QCode برگردانده است.
گیر کردهاید؟ ایجنت افزونه را صدا نمیزند و خودش جواب میدهد
سه جا را اول بررسی کنید: 1) افزونه یا گردشکار باید روی «انتشار» (发布) کلیک شده باشد؛ ذخیره پیشنویس برای فراخوانی پایدار توسط ایجنت کافی نیست؛ 2) توضیح انگلیسی/چینی ابزار افزونه و توضیح پارامتر user_prompt باید کاربرد را روشن بگویند تا مدل زمانبند آن را تشخیص دهد؛ 3) اگر میخواهید هر دور ورودی کاربر اجباری از QCode برود و مدل پیشفرض تصمیم نگیرد که فعال شود، میتوانید ایجنت را به حالت گردشکارمحور ببرید تا ورودی کاربر مستقیم به گردشکاری برود که گره HTTP مربوط به QCode را دارد.
مسیر B (فقط مدیر Enterprise Flagship): اتصال مدل سفارشی بومی در پنل Coze Programming¶
این قدم و قدم ۶ فقط برای ابرمدیر یا مدیر سازمان Enterprise Flagship در Coze است. اگر حساب شخصی معمولی دارید، مستقیم به قدم ۷ بروید و سابقه درخواستها را بررسی کنید.
- Coze Programming را در مرورگر باز کنید code.coze.cn و با حساب مدیر سازمانی خود وارد شوید.
- روی تصویر پروفایل در گوشه پایین-چپ صفحه کلیک کنید، حساب سازمانی مربوطه را انتخاب کنید، سپس روی آیکون «تنظیمات» آن سازمان کلیک کنید تا به «مدیریت سازمان Enterprise» بروید.
- در «مدیریت سازمان Enterprise» به ترتیب وارد «اتصال مدل ← مدل سفارشی» (模型接入 → 自定义模型) شوید و روی «اتصال مدل» (接入模型) کلیک کنید.
- در پنجره بازشده پارامترها را طبق جدول پایین پر کنید، سپس در صورت نیاز قابلیتهای مدل (مثل فراخوانی ابزار، تفکر عمیق) و طول زمینه را تیک بزنید و ذخیره کنید:
| فیلد فرم | مقدار | توضیح |
|---|---|---|
| نام نمایشی مدل | 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، مدل بهطور پیشفرض برای هیچ فضای کاری قابل استفاده نیست و مدیر باید دسترسی را دستی روشن کند تا اعضا آن را ببینند:
- در فهرست «مدیریت سازمان Enterprise ← اتصال مدل ← مدل سفارشی» بمانید، مدلی را که تازه وصل کردهاید پیدا کنید و روی «… ← تغییر فضاهای موجود» (修改可用空间) سمت راست همان ردیف کلیک کنید.
- در پنجره بازشده کلید فعالسازی فضای کاری هدف را روشن کنید و ذخیره کنید.
- به صفحه چینش ایجنت Coze برگردید (یا از عضو فضای کاری هدف بخواهید صفحه چینش را باز کند)، انتخابگر مدل را باز کنید و در گروه «مدل سفارشی» مدل
QCode GPT 6.2 Solرا که تازه وصل کردهاید انتخاب کنید. - در کادر گفتوگوی سمت راست «سلام، در یک جمله خودت را معرفی کن» بنویسید و بفرستید و ببینید پاسخ جریانی درست کلمهبهکلمه بیرون میآید یا نه.
اگر درست پیش بروید این را میبینید: کلید فعالسازی فضای کاری هدف روشن است؛ در گروه «مدل سفارشی» فهرست مدلهای ایجنت میتوانید این مدل را انتخاب کنید و پس از ارسال پیام، پاسخ جریانی عادی میآید، بدون خطای 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 جواب نداده است:
- در مرورگر probe.qcode.cc را باز کنید.
- همان کلید API
cr_را که در Coze استفاده کردهاید بچسبانید و روی «查询» (جستوجو) کلیک کنید. - به فهرست درخواستها پایین بروید و بررسی کنید زمان درخواست آخرین رکورد با لحظهای که در 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 و مدل سفارشی بومی سازمانی — را خوب میشناسید. از اینجا میتوانید:
- نقاط اتصال و قالب API
- اتصال مدلهای چینی
- توضیح صورتحساب
- عیبیابی
- و بعد: در صفحه قیمتها پلنها را مقایسه کنید
- به داشبورد برگردید و مصرف و موجودی را ببینید
خطاهای رایج¶
| متن / نشانه خطا | علت | چه کار کنید |
|---|---|---|
| ورودی «اتصال مدل ← مدل سفارشی» پیدا نمیشود | مدل سفارشی بومی فقط برای ابرمدیر یا مدیر سازمان 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 ببینید.
مستندات مرتبط¶
- نقاط اتصال و قالب API — جدول مرجع پروتکل × خانواده مدل
- اتصال مدلهای چینی — فهرست مدلهای چینی قابل استفاده در نقطه پایانی سازگار با OpenAI
- توضیح صورتحساب — قواعد صورتحساب پلنها و بستههای پرداخت بهازای مصرف
- عیبیابی — کدهای وضعیت عمومی و بررسی اتصال شبکه
- مستندات رسمی اتصال مدل سفارشی Coze — توضیح رسمی اتصال بومی در Enterprise Flagship
با QCode شروع کنید
یک کلید API برای Claude Code، Codex و بیشتر — بر اساس توکن، قیمت هر مدل در qcode.cc/models