نمای کلی ACP

پروتکل Agent Client: یک پیکربندی که در Zed، Devin Desktop و JetBrains کار می‌کند — Claude Code را به‌عنوان یک عامل ACP با محیطی که به QCode اشاره می‌کند اجرا کنید

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

آخرین بازبینی: 2026-10-15 · 📄 بر پایه مستندات رسمی (agentclientprotocol.com، بررسی‌شده در همان روز)

در یک نگاه¶

پروتکل Agent Client (ACP) یک استاندارد باز است که ویرایشگرها را از عامل‌های هوش مصنوعی جدا می‌کند — مثل LSP فکر کنید، اما برای عامل‌ها. هر ویرایشگری که از ACP پشتیبانی می‌کند می‌تواند هر عاملی را که از ACP پشتیبانی می‌کند میزبانی کند، بدون هیچ یکپارچه‌سازی اختصاصی برای هر عامل.

برای کاربران QCode یک پیامد بسیار کاربردی دارد:

🔑 خود عامل را (مثلاً Claude Code CLI) روی QCode پیکربندی کنید، و همه میزبان‌ها به‌طور خودکار تبعیت می‌کنند. میزبان‌های ACP عامل را به‌عنوان یک فرایند فرزند اجرا می‌کنند، پس محیط شما را به ارث می‌برد. وقتی ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN تنظیم شوند، نشست‌ها در Zed، Devin Desktop و JetBrains همگی از QCode عبور می‌کنند — لازم نیست پیکربندی را برای هر ویرایشگر تکرار کنید.

میزبان‌هایی که از ACP پشتیبانی می‌کنند¶

عامل‌هایی که از ACP پشتیبانی می‌کنند¶

موارد شاخص شامل Claude Agent (نامی که در فهرست رسمی ثبت شده — رَپِر ACP مربوط به Claude Agent SDK، claude-agent-acp) و OpenCode است؛ فهرست کامل در agentclientprotocol.com قرار دارد. هر چیزی که ACP را پیاده‌سازی کند قابل اتصال است. هر میزبان آداپتور و فرمان اجرای خودش را دارد، پس به مستندات میزبان مراجعه کنید.

راه‌اندازی: یک‌بار پیکربندی کنید، همه‌جا کار می‌کند¶

Claude Code (نقطه پایانی Anthropic)¶

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_qcode_key"

آن‌ها را در ~/.zshrc / ~/.bashrc ماندگار کنید. از سرزمین اصلی چین، از https://asia.qcode.cc/api استفاده کنید.

همچنین می‌توانید آن‌ها را در بلوک env فایل ~/.claude/settings.json قرار دهید تا همان اثر را داشته باشد. متغیرهای محیطی را ببینید.

Codex CLI (نقطه پایانی OpenAI Responses)¶

Codex از طریق TOML با base_url که به /openai ختم می‌شود پیکربندی می‌شود. راهنمای Codex را ببینید.

🔴 یک تله رایج: ویرایشگرهایی که از GUI اجرا می‌شوند، محیط پوسته شما را نمی‌بینند¶

در macOS و Linux، ویرایشگری که از Dock، یک لانچر یا یک آیکون دسکتاپ اجرا می‌شود ~/.zshrc را نمی‌خواند. نشانه: claude از یک ترمینال به QCode می‌رسد، اما نشست ACP درون ویرایشگر در احراز هویت شکست می‌خورد.

دو راه برای رسیدگی به آن وجود دارد:

1. ویرایشگر را از یک ترمینال اجرا کنید (مثلاً zed .) تا محیط پوسته فعلی را به ارث ببرد
2. پیکربندی را در فایل پیکربندی خود عامل قرار دهید نه در پروفایل پوسته (Claude Code: بلوک env در ~/.claude/settings.json)

گزینه 2 مقاوم‌تر است زیرا به نحوه شروع ویرایشگر بستگی ندارد.

بررسی رسیدن ترافیک به QCode¶

KEY="cr_your_qcode_key"
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" -H "anthropic-version: 2023-06-01"
# 400 = path and key are both fine (a missing body is expected); 401 = key problem

وقتی نقطه پایانی درست کار کرد، یک نشست در میزبان باز کنید. اگر همچنان شکست خورد، مشکل در نحوه اجرای عامل توسط میزبان است (معمولاً همان تله محیطی بالا)، نه در QCode.

هر درخواست از طریق QCode به probe.qcode.cc گزارش می‌شود — کلید API خود را وارد کنید تا تأیید کنید درخواست‌ها واقعاً می‌رسند.

ACP چگونه عامل را شروع می‌کند: چرا متغیرهای محیطی «به ارث می‌رسند»¶

تا تاریخ 2026-10-15، بر اساس مستندات رسمی انتقال ACP: ACP پیام‌ها را به‌صورت JSON-RPC کدگذاری می‌کند، و با انتقال stdio توصیه‌شده کلاینت (ویرایشگر) عامل را به‌عنوان یک زیرفرایند اجرا می‌کند؛ عامل پیام‌های JSON-RPC را از ورودی استاندارد می‌خواند و پیام‌ها را به خروجی استاندارد می‌نویسد که با خطوط جدید از هم جدا می‌شوند، و ممکن است لاگ‌ها را به خطای استاندارد (stderr) بنویسد. پروتکل همچنین عامل را از نوشتن هر چیزی به stdout که پیام معتبر ACP نباشد منع می‌کند.

دو نتیجه عملی برای عیب‌یابی به دست می‌آید:

• یک زیرفرایند به‌طور پیش‌فرض محیط هر چیزی را که آن را اجرا کرده به ارث می‌برد، بنابراین اینکه ANTHROPIC_BASE_URL تنظیم‌شده در پوسته شما اثر می‌کند یا نه به نحوه شروع خود ویرایشگر بستگی دارد (تله اجرا از GUI در بالا را ببینید).
• اگر عامل را در اسکریپت خودتان بپیچید، داخل آن به stdout echo سلام‌واحوال‌پرسی یا خروجی اشکال‌زدایی نکنید، وگرنه به‌عنوان پیام نامعتبر تلقی می‌شود؛ در عوض چنین خروجی را به stderr بنویسید.

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

خطاهای رایج و روش عیب‌یابی¶

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

آیا باید QCode را در هر ویرایشگر جداگانه پیکربندی کنم؟¶

خیر. شما خود عامل را پیکربندی می‌کنید (برای مثال Claude Code)؛ ویرایشگر فقط آن را راه‌اندازی می‌کند. پس از اتصال عامل به QCode، نشست‌های ACP در Zed، Devin Desktop و JetBrains از همان پیکربندی استفاده می‌کنند.

ACP چه رابطه‌ای با LSP دارد؟¶

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

چگونه مطمئن شوم ویرایشگری که از Dock اجرا شده متغیرهای محیطی را دریافت کرده است؟¶

یک نشست ACP در ویرایشگر باز کنید و یک پیام بفرستید، سپس کلید خود را در probe.qcode.cc وارد کنید تا ببینید آن درخواست ظاهر می‌شود یا نه. اگر ظاهر نشد، متغیرها به عامل نرسیده‌اند؛ به‌جای آن پیکربندی را در بلوک env فایل ~/.claude/settings.json قرار دهید.

آیا نشست‌های ACP می‌توانند از GPT استفاده کنند؟¶

این به عاملی بستگی دارد که به کار می‌گیرید. عامل‌های خانواده Claude فقط از رابط Anthropic با مدل‌های Claude و مدل‌های چینی استفاده می‌کنند. برای GPT، یک عامل سبک Codex به کار بگیرید و base_url آن را همان‌طور که Codex انتظار دارد روی https://api.qcode.cc/openai تنظیم کنید. QCode در حال حاضر مدل‌های Gemini را ارائه نمی‌دهد.

در سرزمین اصلی چین از کدام دامنه استفاده کنم؟¶

api.qcode.cc را با asia.qcode.cc (نقطه پایانی آسیا) جایگزین کنید؛ کلید ثابت می‌ماند. اگر ناپایدار بود، به حالت قبل برگردید.

مطالب مرتبط¶

• نقاط پایانی و مسیرهای API — جدول پروتکل × خانواده مدل
• متغیرهای محیطی
• راه‌اندازی Zed · راه‌اندازی Devin Desktop · IDEهای JetBrains

سازمانی ←