اتصال Ollama به coding agent برای اجرای مدل محلی
با تنظیم base URL روی http://localhost:11434 و وارد کردن یک رشته دلخواه به جای API key، مدلهای محلی را به coding agent متصل کنید. محدودیت context length را در این راهنما بررسی کنید.
آنچه متصل میکنید
شما میتوانید از Ollama در کنار coding agent خود استفاده کنید و این اتصال بسیار سادهتر از آن چیزی است که تصور میشود. کافی است یک base URL را تغییر دهید و یک نام مدل انتخاب کنید. فیلد API key همچنان به یک مقدار نیاز دارد، اما سرور محلی آن را نادیده میگیرد، بنابراین هر رشتهای (string) در آن کار میکند.
Ollama روی پورت 11434 گوش میدهد و همزمان دو قالب درخواست را پشتیبانی میکند. /v1/chat/completions قالب سازگار با OpenAI است و مستندات Ollama در آنجا ذکر کردهاند که کلید (key) الزامی است اما نادیده گرفته میشود. /v1/messages قالب سازگار با Anthropic است که Claude Code از آن استفاده میکند. عامل (agent) شما از قبل با یکی از این دو قالب سازگار است، بنابراین هیچ تغییر دیگری در آن لازم نیست.
این بخش حدود 5 دقیقه زمان میبرد. اینکه نتیجه نهایی قابل استفاده باشد یا خیر، به دو تنظیماتی بستگی دارد که تقریباً هیچکس آنها را تغییر نمیدهد: طول کانتکست (context length) و keep-alive، و همچنین سپردن کارهایی به مدل که در آنها مهارت دارد. هر دو مورد بخش مخصوص به خود را دارند و محدودیتهای واقعی در پایان ذکر شدهاند.
کدام ایجنتهای برنامهنویسی از base URL محلی پشتیبانی میکنند
آزمون این موضوع یک پرسش ساده است: آیا ابزار تنظیماتی برای base URL ارائه میدهد؟ اگر پاسخ مثبت است، میتواند با سرور شما ارتباط برقرار کند.
Ollama صفحات یکپارچهسازی را برای Claude Code، OpenCode، Codex، Cline، Roo Code، Zed، محیطهای توسعه JetBrains و VS Code منتشر کرده است. Aider پشتیبانی اختصاصی خود از Ollama را بهصورت جداگانه مستند کرده است. این موارد اکثر ابزارهایی را که در آگوست 2026 تحت عنوان ایجنت برنامهنویسی شناخته میشوند، پوشش میدهد. همه این ابزارها از پروتکل یکسانی استفاده نمیکنند و همین تفاوت، نقطه شکست تنظیمات است.
- اکثر ایجنتها به یک endpoint سازگار با OpenAI نیاز دارند. به آنها base URL
http://localhost:11434/v1و هر رشته غیرخالی به عنوان API key بدهید. - ابزار Claude Code بههیچوجه base URL مربوط به OpenAI را نمیپذیرد. این ابزار از Anthropic Messages API استفاده میکند، بنابراین نیاز دارد که
ANTHROPIC_BASE_URLرویhttp://localhost:11434تنظیم شود، جایی که Ollama سرویس/v1/messagesرا ارائه میدهد. - ابزار Codex از OpenAI Responses API استفاده میکند. Ollama نیز از نسخه 0.13.3 به بعد، سرویس
/v1/responsesرا برای این منظور ارائه میدهد. - ایجنتی که تنظیمات base URL ندارد، قابل تغییر مسیر نیست، زیرا endpoint در داخل کلاینت سختکد شده است. در عوض، یک لایه ترجمه مانند یک gateway LiteLLM خودمیزبان در مقابل آن قرار دهید و مدل خود را با فرمتی که کلاینت میطلبد، بازنشر کنید.
Ollama میتواند این پیکربندیها را برای شما بنویسد. دستور ollama launch opencode ابزار OpenCode را با یک پیکربندی درونخطی برای مدل انتخابی شما اجرا میکند، ollama launch claude همین کار را برای Claude Code انجام میدهد و ollama launch droid --config پیکربندی را بدون اجرای ابزار، در فایل مربوطه مینویسد.
نصب Ollama و دریافت مدلی با قابلیت فراخوانی ابزار
curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama lsنصبکننده یک unit برای systemd اضافه کرده و آن را اجرا میکند، بنابراین systemctl status ollama باید خروجی active (running) را نمایش دهد. اگر اینطور نیست، journalctl -e -u ollama دلیل آن را چاپ میکند.
مدل باید از قابلیت فراخوانی ابزار (tool calling) پشتیبانی کند، زیرا عاملها (agents) از طریق همین قابلیت کار میکنند. عامل یک فایل را میخواند، یک patch مینویسد، تست را اجرا میکند، سپس خطا را میخواند و دوباره تلاش میکند. مدلی که نتواند tool call صادر کند، به جای اعمال تغییرات، آن را به صورت متنی توصیف میکند و عامل دچار حلقه تکرار شده یا متوقف میشود. پیش از دانلود، برچسب tools را در صفحه مدل در ollama.com جستجو کنید. مدل qwen3-coder:30b از این قابلیت پشتیبانی میکند و تا اوت 2026، این برچسب یک دانلود 19 گیگابایتی با پنجره متنی 256K است. اگر سرور شما فقط CPU دارد یا با کمبود RAM مواجه است، محاسبات حافظه برای برچسب Qwen 27B روی یک VPS نشان میدهد که چه چیزی در فضای 8 تا 64 گیگابایت جای میگیرد تا پیش از دانلود تصمیمگیری کنید.
اکنون تأیید کنید که سرور دقیقاً چه نامهایی را ارائه میدهد:
curl http://localhost:11434/v1/modelsرشتههای موجود در آن پاسخ، دقیقاً همان چیزی هستند که باید در پیکربندی عامل شما قرار بگیرند. بررسی این مورد در ابتدا، اکثر خطاهای مربوط به پیدا نشدن مدل را برطرف میکند. اگر Ollama هنوز نصب نشده است، راهنمای کاملتر در میزبانی شخصی یک LLM با Ollama روی یک VPS موجود است.
تنظیم OpenCode برای استفاده از Ollama
فایل ~/.config/opencode/opencode.json را ویرایش کنید:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"qwen3-coder:30b": {
"name": "qwen3-coder 30b"
}
}
}
}
}کلید موجود در models همان نام مدلی است که به Ollama ارسال میشود، بنابراین باید دقیقاً با ollama ls مطابقت داشته باشد. فیلد name صرفاً برچسبی است که در انتخابگر مدل نمایش داده میشود. برنامه opencode را اجرا کنید، ارائهدهنده (provider) را روی Ollama قرار دهید و journalctl -e -u ollama را زیر نظر بگیرید تا تأیید شود که درخواست به سرور شما رسیده است و نه جای دیگر. راهاندازی خودِ agent در اجرای OpenCode روی یک VPS توضیح داده شده است.
تنظیم Claude Code برای استفاده از Ollama
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30bمتغیر ANTHROPIC_API_KEY عمداً خالی رها شده است. اگر یک کلید واقعی در محیط (environment) باقی بماند، درخواستهای شما به جای مدل محلی، به API ابری ارسال میشود که منجر به صدور صورتحساب شده و استنتاج (inference) محلی انجام نخواهد شد. دستور ollama launch claude تمام این تنظیمات را برای شما انجام میدهد.
آگاه باشید که لایهٔ سازگاری چه مواردی را پشتیبانی نمیکند. این لایه tool_choice یا کش کردن پرامپت (prompt caching) را پیادهسازی نمیکند و فاقد endpoint برای شمارش توکن است؛ بنابراین تعداد توکنهایی که مشاهده میکنید، تخمینهایی است که توسط توکنایزر خودِ مدل ارائه میشود. همچنین Claude Code یک پرامپت سیستمی بزرگ و مجموعهای گسترده از ابزارها را به همراه دارد، بنابراین به context بیشتری نسبت به یک کلاینت چت معمولی نیاز دارد. پرسش کلیتر دربارهٔ اینکه چه مواردی منتقل میشوند و چه مواردی خیر، در امکان میزبانی شخصی Claude بررسی شده است.
تنظیم Aider برای استفاده از Ollama
export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30bمستندات Aider استفاده از پیشوند ollama_chat/ را نسبت به ollama/ توصیه میکند. این ابزار همچنین به شما اجازه میدهد تا پنجرهٔ context را برای هر مدل در .aider.model.settings.yml تعیین کنید؛ این قابلیت زمانی مفید است که یک مدل خاص به پنجرهای متفاوت از مقدار پیشفرض سرور نیاز داشته باشد:
- name: ollama_chat/qwen3-coder:30b
extra_params:
num_ctx: 65536چرا یک تنظیمات فعال همچنان خروجی بیمعنی تولید میکند
این بخشی است که اهمیت دارد. Ollama طول کانتکست پیشفرض را بر اساس VRAM (حافظه ویدیویی روی GPU) که شناسایی میکند، انتخاب مینماید و این مقادیر پیشفرض منتشر شدهاند:
The data behind this chart
[
{
"label": "Under 24 GiB VRAM",
"default_context_tokens": "4,096"
},
{
"label": "24 to 48 GiB VRAM",
"default_context_tokens": "32,768"
},
{
"label": "48 GiB VRAM or more",
"default_context_tokens": "262,144"
}
]بیشتر پلنهای VPS و تمام سرورهای مبتنی بر CPU، در ردیف اول قرار میگیرند: 4,096 توکن. تنها یک GPU بزرگ میتواند به 262,144 توکن در ردیف آخر دست یابد.
یک ایجنت پیش از انجام هر کاری، 4096 توکن را مصرف میکند. پرامپت سیستم، تعاریف ابزارها، لیست مخزن و اولین فایلی که باز میکند، از قبل بزرگتر از این مقدار هستند. آنچه در ادامه رخ میدهد، کل مشکل است: هیچ خطایی رخ نمیدهد. مستندات Aider بیان میکند که Ollama بهطور بیصدا کانتکستی را که از پنجره فراتر میرود، حذف میکند. قدیمیترین توکنها خارج میشوند، بنابراین مدل با اطمینان درباره فایلی پاسخ میدهد که دیگر نمیتواند آن را ببیند، یا دستوری را که دو مرحله قبل دادهاید فراموش میکند. این مکانیزم دلیل اصلی گزارشهایی است که میگویند یک مدل محلی برای نوشتن کد بیش از حد ضعیف است.
مستندات Ollama میگوید وظایفی مانند ایجنتها و ابزارهای کدنویسی باید حداقل روی 64000 توکن تنظیم شوند. آن را روی سرور تنظیم کنید:
sudo systemctl edit ollama.serviceاین خطوط را در فایل override اضافه کنید:
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"سپس reload و restart کنید:
sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama psollama ps همان بررسی است. این دستور ستون CONTEXT را چاپ میکند و آن عدد، مقداری است که مدل واقعاً دریافت کرده است. مقادیر ID و SIZE شما متفاوت خواهند بود:
NAME ID SIZE PROCESSOR CONTEXT UNTIL
qwen3-coder:30b a1b2c3d4e5f6 24 GB 100% GPU 64000 4 minutes from nowبه دو دلیل، آن را روی سرور تنظیم کنید نه در ایجنت. طرح OpenAI chat completions هیچ فیلدی برای طول کانتکست ندارد، بنابراین یک کلاینت سازگار با OpenAI نمیتواند آن را درخواست کند. همچنین این تنظیمات برای هر سرور است، بنابراین هر ایجنتی که به آن سرور متصل کنید، آن را به ارث میبرد. اگر یک مدل به پنجره متفاوتی نیاز دارد، آن را در یک کپی با استفاده از Modelfile اعمال کنید:
FROM qwen3-coder:30b
PARAMETER num_ctx 65536ollama create qwen3-coder-64k -f Modelfileکانتکست رایگان نیست. پنجره طولانیتر حافظه بیشتری مصرف میکند، بنابراین ستون PROCESSOR را زیر نظر داشته باشید. 100% GPU همان چیزی است که میخواهید. هنگامی که بخشی از مدل به CPU منتقل شود، نرخ توکن بهقدری افت میکند که حلقه ایجنت غیرقابل استفاده میشود و اندازهگیری توکن بر ثانیه در یک LLM محلی روشی است که با آن سقف واقعی سرور خود را پیدا میکنید. تعیین ابعاد ماشین پیش از خرید آن در چه مقدار RAM و CPU برای یک VPS ایجنت کدنویسی نیاز است پوشش داده شده است.
نگهداشتن مدل در حافظه بین درخواستها
بهصورت پیشفرض، Ollama مدل را 5 دقیقه پس از آخرین درخواست از حافظه خارج میکند. این رفتار برای یک محیط چت مناسب است، اما برای کارهای مبتنی بر Agent مناسب نیست. شما برای خواندن یک diff مکث میکنید، تایمر به پایان میرسد و در درخواست بعدی، دهها گیگابایت وزن (weights) مدل باید از دیسک بارگذاری شود تا اولین توکن ظاهر گردد. این وضعیت بهصورت یک وقفه یا هنگکردن دیده میشود.
OLLAMA_KEEP_ALIVE یک رشتهٔ زمانی مانند 10m یا 24h، یک عدد ساده بر حسب ثانیه، -1 برای نگهداشتن دائمی مدل در حافظه، یا 0 برای تخلیه فوری آن میپذیرد. این مقدار را در کنار طول کانتکست (context length) تنظیم کنید:
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"فیلد درخواست keep_alive فقط در endpointهای بومی /api/generate و /api/chat در Ollama وجود دارد و در endpointهای سازگاری (compatibility) در دسترس نیست؛ بنابراین یک Agent نمیتواند آن را برای هر درخواست بهصورت جداگانه تنظیم کند. متغیر محیطی (environment variable) تنها ابزار شماست. هرگاه به حافظه نیاز داشتید، ollama stop qwen3-coder:30b مدل را بدون متوقف کردن سرور از حافظه خارج میکند.
اجرای Ollama روی یک سرور مجزا
برنامه Ollama بهصورت پیشفرض روی localhost گوش میدهد. برای دسترسی به آن از یک ماشین دیگر، مقدار OLLAMA_HOST=0.0.0.0:11434 را در همان override فایل systemd تنظیم کرده و سرویس را restart کنید.
این کار را فقط در یک شبکه خصوصی انجام دهید. مستندات Ollama تأکید میکند که API محلی نیازی به احراز هویت ندارد؛ بنابراین باز گذاشتن پورت 11434 روی اینترنت به این معناست که هر کسی میتواند از سختافزار شما استفاده کرده و تمام دادههای ارسالی توسط agent شما را بخواند. دو گزینه امن وجود دارد. اتصال را روی localhost نگه دارید و پورت را از طریق SSH از لپتاپ خود forward کنید:
ssh -N -L 11434:localhost:11434 you@your-vpsدر این حالت، agent شما همچنان به http://localhost:11434/v1 اشاره میکند و متوجه هیچ تفاوتی نخواهد شد. گزینه دیگر استفاده از VPN است که در آن Ollama بهجای 0.0.0.0، روی آدرس VPN متصل میشود. اگر قرار است چندین نفر یا چندین agent از یک سرور استفاده کنند، باید بدانید که scheduler برنامه Ollama برای چنین باری طراحی نشده است و مقایسه بین Ollama و vLLM نشان میدهد که تفاوت در توان عملیاتی (throughput) از کجا به بعد مشکلساز میشود.
جایی که مدلهای کدنویسی محلی برتری دارند و جایی که ندارند
عاملی که توسط مدلی که خودتان میزبانی میکنید هدایت میشود، در همه وظایف جایگزین APIهای پیشرفته (Frontier API) نمیشود. این مدلها در چهار نوع کار بهوضوح برتری دارند:
- ویرایشهای مکانیکی انبوه، که در آن هر تغییر کوچک است و میتوانید آن را بررسی کنید. تغییر نام در کل مخزن، افزودن type hintها، نوشتن docstringها و ترجمه کامنتها. مدل میتواند ساعتها اجرا شود و هزینهای برای شما نداشته باشد.
- کارهایی که نباید از سختافزار شما خارج شوند. کدهای مشتری که تحت قرارداد محرمانگی هستند یا مخازن داخلی که اجازه ندارید آنها را برای شخص ثالث ارسال کنید.
- ماشینهای آفلاین و ایزوله (air-gapped)، که در آنها هیچ API میزبانیشدهای برای فراخوانی وجود ندارد.
- هزینه قابل پیشبینی. پس از پرداخت هزینه سرور، عاملی که توکنها را در یک حلقه مصرف میکند هزینه اضافی ندارد، که این دقیقاً برعکس APIهای مبتنی بر پرداخت به میزان مصرف است. جایی که یک GPU VPS در برابر توکنهای API به نقطه سربهسر میرسد محاسبات مربوط به این موضوع را ارائه میدهد.
این مدلها در وظایف طولانی و چندمرحلهای شکست میخورند. وظایفی مانند «پیدا کردن دلیل شکست یک تست، رفع علت آن و بهروزرسانی فراخوانندهها» نیاز به فراخوانیهای ابزاری (tool calls) صحیح و متوالی دارد، در حالی که کل تاریخچه باید در context باقی بماند. مدلی در محدوده 8B تا 14B روی یک سرور معمولی، ممکن است یک فراخوانی ابزار ناقص تولید کند یا پس از چند مرحله، طرح کلی را فراموش کند؛ در نتیجه شما زمان بیشتری را صرف هدایت مدل میکنید تا اینکه خودتان آن کار را انجام دهید. این یک مشکل مربوط به prompt نیست که بتوانید با نوشتن یک دستور بهتر آن را حل کنید؛ این یک محدودیت ظرفیت است.
همچنین، هر جا که اشتباه کردن هزینهبر باشد و شما نخواهید هر خط را بخوانید، مدلهای محلی شکست میخورند. به مدل محلی کارهای محدودی بسپارید که خروجی آنها را بررسی میکنید و برای کارهایی که نمیخواهید مرحلهبهمرحله چک کنید، از یک مدل میزبانیشده استفاده کنید.
حالتهای شکست و پیامهایی که مشاهده خواهید کرد
curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. سرور در حال اجرا نیست یا ایجنت به میزبان دیگری اشاره میکند. دستور systemctl status ollama و سپس journalctl -e -u ollama را اجرا کنید.
ایجنت گزارش میدهد که مدل وجود ندارد. نام موجود در فایل پیکربندی شما با نامی که سرور ارائه میدهد مطابقت ندارد. آن را با curl http://localhost:11434/v1/models مقایسه کرده و رشته نام را از آنجا کپی کنید. تگ بخشی از نام است، بنابراین پیکربندی که تگی را نام میبرد که هرگز آن را دریافت (pull) نکردهاید، حتی با وجود نصب بودن مدل مشابه، با شکست مواجه میشود.
ایجنت به صورت متنی پاسخ میدهد و هیچ فایلی را ویرایش نمیکند. یا مدل از ابزارها پشتیبانی نمیکند، یا درخواست به همراه تعاریف ابزارهای آن، پنجره کانتکست (context window) را پر کرده است. برچسب tools را در صفحه مدل بررسی کنید، سپس ستون CONTEXT را در ollama ps چک کنید.
سکوت طولانی پیش از اولین توکن و سپس سرعت عادی. زمان keep-alive به پایان رسیده و وزنها دوباره از دیسک خوانده میشوند. مقدار OLLAMA_KEEP_ALIVE را تنظیم کنید.
مدل با فایلی که بهتازگی خوانده است تناقض دارد. کوتاهسازی کانتکست (Context truncation) رخ داده است. ollama ps معمولاً مقداری برای CONTEXT نشان میدهد که از آنچه تصور میکردید تنظیم کردهاید کمتر است، زیرا متغیر محیطی بهجای اعمال در systemd unit، به شل (shell) شما ارسال شده است.
همه چیز کار میکند اما بهکندی، و PROCESSOR برابر با 100% GPU نیست. مدل به همراه کانتکست آن در VRAM جا نمیشود. طول کانتکست را کاهش دهید، یا از یک مدل کوچکتر یا کوانتیزاسیون (quantisation) پایینتر استفاده کنید.
FAQ
آیا میتوانم Claude Code را به Ollama متصل کنم؟
بله، اما نه با استفاده از URL سازگار با OpenAI. برنامه Claude Code از Anthropic Messages API استفاده میکند و Ollama این ساختار را در /v1/messages روی همان پورت 11434 ارائه میدهد. متغیرهای ANTHROPIC_BASE_URL=http://localhost:11434، ANTHROPIC_AUTH_TOKEN=ollama و یک ANTHROPIC_API_KEY خالی را export کنید و سپس آن را با claude --model qwen3-coder:30b اجرا کنید. دستور ollama launch claude همین تنظیمات را برای شما مینویسد. لایه سازگاری، قابلیت tool_choice یا کش کردن پرامپت را پیادهسازی نمیکند و فاقد endpoint برای شمارش توکن است، بنابراین تعداد توکنهای گزارششده تقریبی هستند.
چرا مدل محلی من درباره کدی که نمیبیند پاسخ میدهد؟
به این دلیل که درخواست دیگر در پنجره کانتکست (context window) جا نمیشود و قدیمیترین بخش آن بدون هیچ خطایی حذف شده است. Ollama کانتکست پیشفرض خود را بر اساس VRAM شناساییشده تنظیم میکند و در مقادیر کمتر از 24 GiB، این مقدار پیشفرض 4,096 توکن است که پرامپت سیستمی و تعاریف ابزارهای یک عامل (agent) به تنهایی از آن فراتر میروند. مقدار OLLAMA_CONTEXT_LENGTH=64000 را در unit فایل systemd تنظیم کنید، Ollama را ریاستارت کنید و تأیید کنید که ستون CONTEXT در ollama ps مقدار جدید را نشان میدهد.
برای یک عامل کدنویسی روی VPS از چه مدلی استفاده کنم؟
بزرگترین مدلی را انتخاب کنید که برچسب tools دارد و همچنان با پنجره کانتکست 64k در حافظه جا میشود؛ همچنین مدلهایی که برای کدنویسی بهینهسازی شدهاند را در اولویت قرار دهید. qwen3-coder:30b پاسخ رایج برای سرورهای GPU با VRAM کافی است. در مدلهای کمتر از حدود 14B پارامتر، مدل ممکن است همچنان به سؤالات درباره کد بهخوبی پاسخ دهد اما در ویرایشهای چندمرحلهای شکست بخورد، زیرا کار عاملها خطاهای کوچک در فرمتبندی فراخوانی ابزارها را برنمیتابد. به جای استفاده از یک پرامپت نمونه، با یک کار واقعی از مخزن کد خود تست کنید.
آیا برای اجرای یک عامل کدنویسی روی مدل شخصی به GPU نیاز دارم؟
در عمل بله. استنتاج (inference) فقط با CPU کار میکند و برای سؤالات تکی مناسب است، اما یک عامل برای هر کار درخواستهای زیادی میفرستد و هر درخواست تاریخچه طولانی را دوباره میخواند؛ بنابراین سرعت پایین تولید توکن، یک کار دو دقیقهای را به یک ساعت تبدیل میکند. ستون PROCESSOR را در ollama ps بررسی کنید: هر مقداری غیر از 100% GPU به این معنی است که بخشی از مدل روی CPU در حال اجراست و سرعت تولید توکن بهشدت افت میکند.