راه‌اندازی Zed + Claude Code با ACP (v1.27.0)

Zed 1.27.0 (2026-11-04): Claude Code را در پنل عامل روی ACP اجرا کنید، یا QCode.cc را به‌عنوان ارائه‌دهنده anthropic_compatible / openai_compatible در settings.json اضافه کنید.

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

آخرین بازبینی: 2026-11-09 · 📄 بر اساس مستندات رسمی (Zed پایدار نسخه v1.27.0، منتشرشده در 2026-11-04؛ مدخل‌های ACP و ارائه‌دهنده که در ادامه به آن‌ها اشاره شده از یادداشت‌های انتشار 1.21.0 تا 1.25.2 آمده‌اند؛ 1.25.2 در 2026-10-21 منتشر شد)

یک نگاه کلی¶

Zed یک ویرایشگر کد مدرن و پرکارایی است که با Rust نوشته شده و از سه‌ماهه نخست 2026 به‌صورت بومی از Agent Client Protocol (ACP) پشتیبانی می‌کند — یک استاندارد باز که ارتباط IDE با عامل هوش مصنوعی را جدا می‌کند، همان‌طور که LSP این کار را برای سرورهای زبان انجام داد. Zed از طریق ACP، Claude Agent (پوشش claude-agent-acp برای Claude Agent SDK) را یکپارچه می‌کند و پنلی برای عامل در اختیار می‌گذارد تا وظایف کدنویسی چندمرحله‌ای را هماهنگ کنید. این راهنما نشان می‌دهد چگونه QCode.cc را به‌عنوان نقطه پایانی API برای Claude Code داخل Zed پیکربندی کنید و چگونه QCode را مستقیماً به‌عنوان ارائه‌دهنده سازگار با Anthropic / سازگار با OpenAI در settings.json ویرایشگر Zed اضافه کنید.

QCode در سراسر این فرایند از یک کلید API واحد استفاده می‌کند (که با cr_ شروع می‌شود). همین کلید از پروتکل‌های Anthropic، OpenAI Chat، OpenAI Responses و تصویر پشتیبانی می‌کند و به سه دامنه ورودی نگاشت می‌شود — api / asia / us (کاربران سرزمین اصلی چین بهتر است asia.qcode.cc را ترجیح دهند).

چرا از Zed استفاده کنیم¶

• یکپارچگی بومی ACP: نشست‌های Claude Code را داخل پنل عامل باز کنید و استدلال عامل و فراخوانی ابزارها را به‌صورت زنده در ویرایشگر ببینید
• زمینه 1M: حالت BYOK از کل پنجره زمینه 1M توکن مدل‌های Opus 5 / 4.8 / 4.7 پشتیبانی می‌کند
• کارایی Rust: شروع سرد بسیار سریع و مصرف حافظه یک مرتبه بزرگی کمتر از VS Code / ویرایشگرهای مبتنی بر Electron
• چیدمان چندپنجره‌ای: ویرایشگر + ترمینال + پنل عامل در کنار هم برای یک جریان کاری جمع‌وجور
• دو مسیر یکپارچه‌سازی: اجرا از طریق Claude Code CLI (سطح کامل ابزارها)، یا افزودن QCode به‌عنوان ارائه‌دهنده داخلی در settings.json

مقایسه دو مسیر یکپارچه‌سازی¶

Zed دو مسیر مکمل برای دسترسی به QCode ارائه می‌دهد — بر اساس نیاز خود انتخاب کنید:

بخش «مراحل پیکربندی» در ادامه مسیر A را پوشش می‌دهد؛ «پیکربندی ارائه‌دهنده در settings.json» مسیر B را پوشش می‌دهد.

پیش‌نیازها¶

• Zed نصب شده باشد (macOS / Linux)
• Claude Code CLI نصب شده باشد (یکپارچه‌سازی ACP در Zed از CLI به‌عنوان بک‌اند استفاده می‌کند؛ اگر فقط از مسیر B استفاده می‌کنید، از این مورد صرف‌نظر کنید)
• یک کلید API QCode.cc (که با cr_ شروع می‌شود) که از داشبورد در دسترس است
• Claude Code CLI از قبل با متغیرهای محیطی QCode پیکربندی شده باشد (طبق شروع سریع)

مراحل پیکربندی (مسیر A: ACP / Claude Code)¶

گام 1: بررسی کارکرد Claude Code CLI در ترمینال شما¶

Zed با ایجاد یک فرایند claude، ACP را راه‌اندازی می‌کند؛ بنابراین ابتدا کارکرد CLI را در ترمینال بررسی کنید:

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxx"
claude --version   # should print a version number (trust this machine + official Releases)
echo "ping" | claude   # simple echo test

ANTHROPIC_BASE_URL نباید اسلش انتهایی داشته باشد؛ SDK Anthropic خودش /v1/messages را اضافه می‌کند. این دو متغیر محیطی را در پیکربندی شل خود (~/.zshrc / ~/.bashrc) ماندگار کنید تا Zed هنگام راه‌اندازی آن‌ها را به ارث ببرد.

گام 2: باز کردن پنل عامل Zed¶

• macOS: Cmd + ?
• Linux: Ctrl + ?

نخستین باری که آن را باز می‌کنید، Zed از شما می‌خواهد یک ارائه‌دهنده عامل انتخاب کنید — Claude Code را انتخاب کنید (BYOK Anthropic API را انتخاب نکنید؛ آن مسیر CLI را دور می‌زند و مستلزم آن است که Base URL را جداگانه در تنظیمات Zed وارد کنید — مسیر B را ببینید).

گام 3: بررسی نشست عامل¶

در ورودی پنل عامل تایپ کنید: «نمادهای صادرشده در فایل فعلی را فهرست کنید.» Zed فایل باز فعلی را به‌عنوان زمینه به Claude Code می‌فرستد و عامل ابزارهای read / grep را برای تجزیه و پاسخ فراخوانی می‌کند.

اگر فرایند عامل نتواند شروع شود، می‌توان فرمان عامل ACP را به‌صراحت از طریق agent_servers.<name>.command / args / env در settings.json تثبیت کرد (کلید تنظیم agent.path وجود ندارد). نام‌ها و فیلدها: از مستندات رسمی پیروی کنید.

تنظیمات عامل / دستیار Zed بین انتشارها به‌سرعت تغییر می‌کند؛ برای نام‌های دقیق کلیدها، به مستندات رسمی Zed مراجعه کنید.

پیکربندی ارائه‌دهنده در settings.json (مسیر B)¶

اگر ترجیح می‌دهید CLI را نصب نکنید، QCode را در settings.json اضافه کنید — خودِ فایل JSON از طریق Cmd+Alt+, باز می‌شود (Ctrl+Alt+, در Linux؛ Cmd+, رابط ویرایشگر تنظیمات را باز می‌کند)؛ این فایل در ~/.config/zed/settings.json قرار دارد (در Windows: %APPDATA%/Zed/settings.json) و بدون راه‌اندازی مجدد اعمال می‌شود. برای درگاه‌های شخص ثالث، ورودی‌های توصیه‌شده رسمی، ارائه‌دهنده‌های سفارشی anthropic_compatible / openai_compatible هستند. QCode با هر دو پروتکل با همان کلید cr_ کار می‌کند.

ارائه‌دهنده سازگار با Anthropic¶

پایه ارائه‌دهنده Anthropic داخلی Zed را به نقطه پایانی Anthropic در QCode تنظیم کنید:

{
  "language_models": {
    "anthropic_compatible": {
      "QCode": {
        "api_url": "https://api.qcode.cc/api"
      }
    }
  }
}

کلید را از طریق یک متغیر محیطی تأمین کنید (که Zed هنگام راه‌اندازی آن را به ارث می‌برد):

export QCODE_API_KEY="cr_xxxxxxxx"

language_models.anthropic.api_url داخلی نیز وجود دارد و کار می‌کند، اما نقطه ورود مستندشده Zed برای درگاه‌های شخص ثالث، ارائه‌دهنده anthropic_compatible است که در بالا نشان داده شد. Base URL به /api ختم می‌شود — بدون /v1 — و Zed خودش /v1/messages را اضافه می‌کند. کلیدهای API را در settings.json قرار ندهید (قاعده رسمی)؛ از متغیر تولیدشده <PROVIDER_NAME>_API_KEY استفاده کنید.

ارائه‌دهنده سازگار با OpenAI¶

Zed همچنین از یک ارائه‌دهنده سازگار با OpenAI پشتیبانی می‌کند که می‌تواند به مدل‌های خانواده GPT در QCode دسترسی پیدا کند. پایه را به نقطه پایانی OpenAI Chat در QCode تنظیم کنید:

{
  "language_models": {
    "openai_compatible": {
      "QCodeOpenAI": {
        "api_url": "https://api.qcode.cc/openai/v1",
        "available_models": [
          { "name": "gpt-5.6-terra" },
          { "name": "gpt-5.6-sol" },
          { "name": "glm-5.3" },
          { "name": "deepseek-v4-flash" }
        ]
      }
    }
  }
}

کلید نیز از یک متغیر محیطی می‌آید:

export QCODEOPENAI_API_KEY="cr_xxxxxxxx"

پایه OpenAI Chat برابر https://api.qcode.cc/openai/v1 است (سپس SDK خودش /chat/completions را اضافه می‌کند). بدون اسلش انتهایی. نام فیلدها در available_models (name / max_tokens و غیره) باید مطابق مستندات رسمی Zed باشند.

تغییرات پس از 1.20.2 که بر این تنظیمات اثر می‌گذارند (2026-10-26)¶

انتشار پایدار Zed اکنون 1.27.0 است (منتشرشده در 2026-11-04)؛ 1.25.2 در 2026-10-21 منتشر شد. این مدخل‌های یادداشت انتشار به مسیرهای ACP و ارائه‌دهنده در بالا مربوط می‌شوند (نقل مستقیم):

• 1.21.0 — «سازگاری ACP و مدیریت بیدارسازی وظیفه ناهمگام بهبود یافت.» و «پشتیبانی BYOK برای Claude Opus 5.5 با کلید API Anthropic اضافه شد.»
• 1.23.2 — «به‌روزرسانی‌های پلن از عامل‌های ACP، از جمله بازآوری پنل پس از تغییر وضعیت، بهبود یافت.» و تنظیم agent.max_idle_retained_threads.
• 1.24.2 — «پشتیبانی از مدل‌های سفارشی Amazon Bedrock با امکان پیکربندی کاربرد ابزار، تصاویر و تفکر بهبود یافت.» (مسیریابی Bedrock؛ QCode از طریق ارائه‌دهنده‌های سازگار بالا پیکربندی می‌شود.)
• 1.25.2 — «اعلان‌های نشست و فشرده‌سازی زمینه برای عامل‌های خارجی که از ACP استفاده می‌کنند فعال شد.» به‌همراه افزودن مدل‌های Bedrock.

کلیدهای تنظیمات استفاده‌شده در بالا در مستندات رسمی بررسی‌شده در 2026-10-26 بدون تغییر مانده‌اند: language_models.anthropic_compatible / openai_compatible، api_url، available_models و متغیر تولیدشده <PROVIDER_NAME>_API_KEY.

انتخاب مدل¶

همان کلید QCode مدل‌هایی از چند ارائه‌دهنده را در دسترس قرار می‌دهد. در صورت نیاز، مدل را از منوی کشویی مدل در پنل عامل یا دستیار تغییر دهید:

کدام پروتکل: claude-* فقط روی ارائه‌دهنده Anthropic کار می‌کند (https://api.qcode.cc/api)؛ gpt-* فقط روی ارائه‌دهنده OpenAI کار می‌کند (https://api.qcode.cc/openai/v1). ترکیب آن‌ها model_not_available_on_endpoint را برمی‌گرداند.

جدول بالا توصیه فعلی است. شناسه‌های 4.x مانند claude-sonnet-4-6، claude-opus-4-8 و claude-opus-4-7 همچنان به فروش می‌رسند؛ فهرست به‌روز qcode.cc/models است.

• در مسیر A (Claude Code)، مدل با پیکربندی خودِ Claude Code تعیین می‌شود (با /model تغییر دهید یا ANTHROPIC_MODEL را تنظیم کنید).
• در مسیر B با ارائه‌دهنده Anthropic، از شناسه‌های مدل claude-* استفاده کنید؛ با ارائه‌دهنده OpenAI، از شناسه‌های مدل gpt-* استفاده کنید.
• پروتکل تصویر (gpt-image-2) لزوماً به‌صورت بومی در دستیار Zed ارائه نمی‌شود؛ آن را مستقیماً از CLI / اسکریپت‌ها فراخوانی کنید — نقاط پایانی و مسیرهای API و تولید تصویر gpt-image-2 را ببینید.

نمونه‌های استفاده¶

پنل عامل: وظایف میان‌فایلی¶

پنل عامل در وظایف چندمرحله‌ای و میان‌فایلی می‌درخشد. برای مثال:

«همه IO همگام زیر utils/ را به ناهمگام تبدیل کنید و فراخوانی‌کنندگان را به‌روزرسانی کنید.»

عامل با grep مکان‌یابی می‌کند، با read بررسی می‌کند و با edit تغییر می‌دهد و تفاوت‌ها را گام‌به‌گام در ویرایشگر نشان می‌دهد تا بتوانید هر یک را بپذیرید یا رد کنید.

ارسال اسکرین‌شات‌ها به عامل (ورودی بینایی)¶

Claude Opus 5 / Sonnet 5 و GPT-5.x همگی از قابلیت بینایی پشتیبانی می‌کنند. می‌توانید ماکت‌های رابط کاربری، اسکرین‌شات‌های خطا یا نمودارهای معماری را به‌عنوان ورودی به عامل بدهید:

• یک تصویر را جای‌گذاری کنید (Ctrl+V) یا آن را به ورودی پنل عامل بکشید و رها کنید
• یا در prompt خود به مسیر یک فایل تصویر محلی ارجاع دهید

موارد استفاده معمول: ساخت رابط کاربری از روی ماکت، اشکال‌زدایی از روی اسکرین‌شات خطا، خواندن نمودارهای معماری / چارت‌ها.

توجه: این مطلب درباره ارسال تصاویر به مدل (ورودی بینایی) است، نه تولید تصاویر. برای تولید تصاویر از gpt-image-2 استفاده کنید — تولید تصویر gpt-image-2 را ببینید.

Dynamic Workflows (هماهنگ‌سازی عامل‌های فرعی پس‌زمینه)¶

Claude Code از Dynamic Workflows پشتیبانی می‌کند: ده‌ها تا صدها عامل فرعی پس‌زمینه را هماهنگ می‌کند؛ ایده‌آل برای بازبینی کل پایگاه کد، مهاجرت و وظایف پژوهشی. آن را با گنجاندن کلیدواژه ultracode در prompt خود فعال کنید یا صرفاً درخواست کنید «یک گردش‌کار اجرا شود»؛ اجراهای فعال را با فرمان /workflows ببینید. عامل‌های فرعی در پس‌زمینه به کار خود ادامه می‌دهند تا شما به کارهای دیگر ادامه دهید. این قابلیت روی هر مدلی که Claude Code با آن پیکربندی شده باشد اجرا می‌شود — بنابراین وقتی Claude Code به QCode متصل است کار می‌کند. مطالعه بیشتر: عامل‌های فرعی.

قالب‌های خروجی بدون رابط / خودکارسازی¶

هنگام فراخوانی Claude Code در CI / اسکریپت‌ها، از claude -p همراه با --output-format استفاده کنید:

# JSON: one structured object with result / total_cost_usd / usage / session_id
claude -p "Summarize this change" --output-format json | jq .result

# stream-json: newline-delimited JSON event stream, good for real-time pipelines
claude -p "Refactor this module" --output-format stream-json

# text: plain text (default)
claude -p "Explain this code" --output-format text

استفاده بیشتر در خودکارسازی و CI/CD.

سایر نقاط پایانی¶

اگر نقطه پایانی فعلی در دسترس نیست، ANTHROPIC_BASE_URL (یا api_url در settings.json) را تغییر دهید:

برای مسیر سازگار با OpenAI، دامنه را به همین ترتیب عوض کنید — برای مثال، نشانی پایه OpenAI Chat در آسیا https://asia.qcode.cc/openai/v1 است. برای مرجع کامل نقاط پایانی، نقاط پایانی و مسیرهای API را ببینید.

سهمیه مشترک¶

عامل Claude Code درون Zed همان کلید API و سهمیه QCode را با CLI / Claude Desktop / Codex CLI به اشتراک می‌گذارد — صورتحساب مضاعف وجود ندارد. مسیر A و مسیر B نیز سهمیه همان کلید را به اشتراک می‌گذارند. برای جزئیات، صورتحساب را ببینید.

محدودیت‌ها و نکات¶

• حالت مستقیم Anthropic با BYOK در Zed از ارائه‌دهنده داخلی Anthropic در Zed استفاده می‌کند و از CLI Claude Code عبور نمی‌کند. این حالت نیازمند آن است که api_url را در تنظیمات Zed به‌صورت دستی تنظیم کنید تا به QCode اشاره کند (مسیر B). حالت ACP / Claude Code که در اینجا پوشش داده شده (مسیر A) ترجیح داده می‌شود — مجموعه کامل ابزارهای CLI (هوک‌ها، مهارت‌ها، MCP) را حفظ می‌کند.
• Base URL نباید اسلش انتهایی داشته باشد. یک درخواست خودآزمایی که به مسیر پایه ارسال می‌شود 401 برمی‌گرداند، که مورد انتظار است (مسیر درست است، فقط احراز هویت ندارد).
• یکپارچه‌سازی ACP در بتای عمومی است (از 2026-04)؛ ممکن است برخی APIها هنوز تغییر کنند. اگر تفاوت‌هایی در رفتار مشاهده کردید، مستندات رسمی Zed مرجع است.
• کاربران سندباکس Linux: اگر Zed از طریق Flatpak نصب شده باشد، ایجاد زیرفرایند claude ممکن است توسط سندباکس مسدود شود. توصیه می‌کنیم نسخه .deb / AppImage / Homebrew را مستقیماً نصب کنید.
• Gemini CLI بازنشسته شده است (EOL در 2026-06-18 برای نسخه‌های غیرسازمانی؛ کلیدهای پولی سازمانی تحت تأثیر قرار نمی‌گیرند)؛ جانشین آن Google Antigravity CLI است. توجه کنید که Antigravity CLI فقط نقطه پایانی سازگار با Gemini را می‌پذیرد (از طریق GOOGLE_GEMINI_BASE_URL)، نه نقطه پایانی سازگار با OpenAI. QCode در حال حاضر مدل‌های Gemini را ارائه نمی‌دهد — Antigravity CLI را ببینید.

پرسش‌های متداول¶

پنل عامل خطای «Failed to start agent» را گزارش می‌کند¶

• آیا claude در ترمینال شما به‌درستی اجرا می‌شود؟ ابتدا احتمال مشکل پیکربندی سمت CLI را رد کنید.
• آیا Zed متغیرهای محیطی ANTHROPIC_* را به ارث برده است؟ در macOS، اجرای Zed از ترمینال با open -a Zed وراثت را تضمین می‌کند.
• آیا agent.path در تنظیمات شما به مسیری معتبر اشاره می‌کند؟ با which claude بررسی کنید.

ارائه‌دهنده settings.json خطای 401 / شکست احراز هویت را برمی‌گرداند¶

• تأیید کنید که متغیر محیطی درست تنظیم شده و کلیدی از QCode با پیشوند cr_ است: ارائه‌دهنده‌های سفارشی از <PROVIDER_NAME>_API_KEY استفاده می‌کنند (برای مثال QCODE_API_KEY / QCODEOPENAI_API_KEY)؛ فقط ارائه‌دهنده‌های داخلی از ANTHROPIC_API_KEY / OPENAI_API_KEY استفاده می‌کنند.
• آیا Zed آن متغیر محیطی را به ارث برده است؟ برای بررسی، Zed را از ترمینال اجرا کنید.
• آیا api_url به‌طور تصادفی اسلش انتهایی گرفته است؟ آن را حذف کنید.

مدلی که می‌خواهم در منوی کشویی نیست¶

• ارائه‌دهنده OpenAI در مسیر B نیاز دارد مدل‌ها به‌صراحت در available_models فهرست شوند تا در منوی کشویی ظاهر شوند.
• مدل‌های در دسترس مسیر A توسط Claude Code تعیین می‌شوند؛ برای مشاهده و تغییر از /model استفاده کنید.

«Invalid model» / 404¶

• دوباره بررسی کنید که املای شناسه مدل دقیقاً با جدول مطابقت دارد (برای مثال claude-opus-5).
• مطمئن شوید پروتکل Base URL با مدل مطابقت دارد: claude-* از نقطه پایانی Anthropic استفاده می‌کند، gpt-* از نقطه پایانی OpenAI.

تفاوت با حالت BYOK Anthropic¶

مراحل بعدی¶

• آموزش Claude Code — مرجع کامل قابلیت‌های CLI
• نقاط پایانی و مسیرهای API — مرجع کامل برای هر سه دامنه ورودی
• زیرعامل‌ها — گردش‌کارهای پویا و هماهنگ‌سازی چندعاملی
• خودکارسازی و CI/CD — حالت بدون رابط گرافیکی و قالب‌های خروجی
• تولید تصویر gpt-image-2 — تولید تصویر (متمایز از ورودی بینایی)
• یکپارچه‌سازی VS Code — مقایسه با ویرایشگرهای مبتنی بر Electron
• صورتحساب — قواعد سهمیه مشترک

می‌خواهید قیمت‌گذاری زنده و مشخصات زمینه هر مدل را ببینید؟ به صفحه قیمت‌گذاری QCode بروید.

سازمانی ←