# نمای کلی ACP

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

## در یک نگاه

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | به عامل متصل‌شده بستگی دارد: Claude Agent / Claude Code (نقطه پایانی Anthropic) ✅ · GPT ✅ (عامل‌های سبک Codex) · مدل‌های چینی ✅ · Gemini فعلاً توسط QCode ارائه نمی‌شود |
| پروتکل و Base URL | در **خود عامل** پیکربندی می‌شود: نقطه پایانی Anthropic یعنی `https://api.qcode.cc/api` برای عامل‌های خانواده Claude |
| محل پیکربندی | محیط عامل / فایل پیکربندی خودِ آن؛ میزبان فقط آن را اجرا می‌کند |
| مستندات رسمی | [Agent Client Protocol](https://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 پشتیبانی می‌کنند

| میزبان | توضیحات | مستندات ما |
|------|-------|----------|
| Zed | پشتیبانی بومی؛ نشست‌ها در پنل عامل باز می‌شوند | [راه‌اندازی Zed](/docs/ide/zed) |
| Devin Desktop (پیش‌تر Windsurf) | از 2026-06-02 پشتیبانی می‌شود، در Agent Command Center | [راه‌اندازی Devin Desktop](/docs/ide/devin-desktop) |
| JetBrains IDEs | از طریق یک افزونه ACP | [JetBrains IDEs](/docs/ide/jetbrains) |
| Neovim / Emacs / Sublime / Qt Creator و غیره | در فهرست رسمی ویرایشگرها آمده‌اند | — |

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

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

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

```bash
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` قرار دهید تا همان اثر را داشته باشد.
> [متغیرهای محیطی](/docs/getting-started/environment) را ببینید.

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

Codex از طریق TOML با `base_url` که به `/openai` ختم می‌شود پیکربندی می‌شود. [راهنمای Codex](/docs/ide/codex) را ببینید.

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

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

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

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

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

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

```bash
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](https://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 بنویسید.
## توضیح تنظیم‌های کلیدی

| تنظیم | هدف | توضیحات |
|---|---|---|
| `ANTHROPIC_BASE_URL` | نقطه پایانی برای عامل‌های خانواده Claude | از `https://api.qcode.cc/api` استفاده کنید، بدون `/v1` و بدون اسلش انتهایی |
| `ANTHROPIC_AUTH_TOKEN` | کلید QCode شما | با `cr_` شروع می‌شود و به‌صورت هدر `Authorization: Bearer` ارسال می‌شود |
| بلوک `env` در `~/.claude/settings.json` | دو مقدار بالا را در پیکربندی خود عامل می‌نویسد | مستقل از نحوه راه‌اندازی ویرایشگر؛ مطمئن‌ترین گزینه |
| Codex `base_url` | نقطه پایانی برای عامل‌های سبک Codex | به `/openai` ختم می‌شود؛ [راهنمای کامل Codex](/docs/ide/codex) را ببینید |
| دستور راه‌اندازی عامل در میزبان | به ویرایشگر می‌گوید عامل را چگونه راه‌اندازی کند | بسته به میزبان متفاوت است؛ مستندات میزبان را دنبال کنید |

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

| نشانه | علت احتمالی | رفع |
|---|---|---|
| `claude` در ترمینال کار می‌کند اما نشست ACP در ویرایشگر در احراز هویت شکست می‌خورد | ویرایشگر از Dock یا لانچر اجرا شده و متغیرهای شل شما را نخوانده است | ویرایشگر را از ترمینال اجرا کنید، یا پیکربندی را در بلوک `env` فایل `~/.claude/settings.json` قرار دهید |
| 401 / `Invalid API key` | کلید نادرست یا دارای فاصله اضافی، یا یک `ANTHROPIC_API_KEY` قدیمی که احراز هویت را به دست می‌گیرد | برای یافتن باقی‌مانده‌ها `env \| grep -i anthropic` را اجرا کنید |
| 404 | `/v1` به Base URL اضافه شده، یا اسلش انتهایی وجود دارد | آن را به `https://api.qcode.cc/api` بازگردانید |
| `model_not_available_on_endpoint` | در عامل خانواده Claude مدل GPT انتخاب شده، یا در عامل سبک Codex مدل Claude | Claude از رابط Anthropic و GPT از OpenAI Responses استفاده می‌کند؛ [نقاط پایانی و قالب‌های API](/docs/getting-started/endpoints-and-api-paths) را ببینید |
| نشست روی «starting» می‌ماند یا بلافاصله قطع می‌شود | عامل نتوانسته به‌عنوان زیرفرایند اجرا شود، یا اسکریپت پوششی روی stdout چاپ می‌کند | ابتدا همان دستور راه‌اندازی را دستی در ترمینال اجرا کنید، سپس اسکریپت پوششی را بررسی کنید |
| هیچ درخواستی در سمت QCode دیده نمی‌شود | درخواست ارسال نشده یا به نشانی دیگری رفته است | با کلید خود در [probe.qcode.cc](https://probe.qcode.cc) بررسی کنید، سپس Base URL را دوباره بررسی کنید |

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

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

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

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

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

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

یک نشست ACP در ویرایشگر باز کنید و یک پیام بفرستید، سپس کلید خود را در [probe.qcode.cc](https://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](/docs/getting-started/endpoints-and-api-paths) — جدول پروتکل × خانواده مدل
- [متغیرهای محیطی](/docs/getting-started/environment)
- [راه‌اندازی Zed](/docs/ide/zed) · [راه‌اندازی Devin Desktop](/docs/ide/devin-desktop) · [IDEهای JetBrains](/docs/ide/jetbrains)