آموزش تنظیمات dsh و اتصال به DeepSeek API

محل ذخیره‌سازی پیکربندی dsh

ابزار dsh (مخفف DeepSeek Harness) پیکربندی خود را در یک دایرکتوری به نام $DSH_HOME نگه می‌دارد که مسیر پیش‌فرض آن ~/.dsh است. هر تنظیمی که در رابط کاربری وب اعمال می‌کنید، در آنجا به صورت فایل‌های متنی ساده ذخیره می‌شود. با کپی کردن این دایرکتوری به سروری دیگر، سیستم جدید دقیقاً مشابه سیستم قبلی عمل خواهد کرد.

چهار مسیر اصلی وجود دارد که تمام موارد مورد نیاز شما را در بر می‌گیرند:

• مسیر ~/.dsh/settings.yaml شامل تنظیمات دستی و تنظیمات ایجاد شده توسط رابط کاربری، از جمله مسیرهای ارائه‌دهنده (provider) و مدل (model) است.
• مسیر ~/.dsh/.credentials.yaml محل نگهداری اسرار (secrets) است. تنظیمات فقط ارجاعی به اعتبارنامه‌ها را نگه می‌دارند، بنابراین مقدار اصلی کلید در یک فایل مجزا قرار دارد.
• مسیر ~/.dsh/profiles/ پروفایل‌های نام‌گذاری‌شده و مسیر ~/.dsh/storages/ نشست‌های (sessions) ذخیره‌شده را در خود جای داده است.
• مسیر ~/.dsh/cordis.patch.yml لایهٔ اصلاحی (patch) شخصی شماست. این لایه برای هر پروفایل، روی پیکربندی پیش‌فرض اعمال می‌شود.

DeepSeek این ابزار را در تاریخ 17 August 2026 به عنوان یک پیش‌نمایش توسعه‌دهنده با مجوز MIT منتشر کرد و در فایل README ذکر شده است که تغییرات ناسازگار با نسخه‌های قبلی در راه است. نام فیلدها و مسیرهای ذکر شده در این راهنما، مطابق با مستندات مخزن در تاریخ August 2026 است. پیش از کپی کردن پیکربندی از هر راهنمایی (از جمله این مورد)، حتماً آن‌ها را با مستندات نسخهٔ نصب‌شدهٔ خود تطبیق دهید، زیرا در نسخه‌های پیش‌نمایش، نام‌گذاری‌ها بین هر release تغییر می‌کنند.

حداقل‌های لازم برای اولین خروجی

برنامه dsh به Node.js نسخه 22.19 یا بالاتر در شاخه 22، یا نسخه 24 و بالاتر نیاز دارد. Node 23 در این محدوده قرار نمی‌گیرد. ابتدا نسخه را بررسی کنید، زیرا عدم تطابق نسخه باعث شکست در راه‌اندازی می‌شود و پیام خطا ممکن است به اشتباه نشان‌دهنده خرابی بسته باشد.

node -v
npx @deepseek-ai/dsh web

دستور npx بسته را از مخزن npm دانلود کرده و رابط کاربری وب را روی http://127.0.0.1:3080 اجرا می‌کند. این برنامه روی آدرس loopback متصل می‌شود، به این معنی که حتی اگر فایروال شما اجازه دهد، پورت از ماشین‌های دیگر قابل دسترسی نیست. روی یک VPS، به‌جای باز کردن پورت 3080 به روی اینترنت، آن را از طریق SSH فوروارد کنید.

ssh -N -L 3080:127.0.0.1:3080 you@your-server

آدرس http://127.0.0.1:3080 را در لپ‌تاپ خود باز کنید، سپس به بخش Settings و بعد Models بروید. کارت DeepSeek دارای یک فیلد برای API key است. کلید را از platform.deepseek.com کپی کرده، در این فیلد قرار دهید و ذخیره کنید. مسیر مدل بلافاصله قابل استفاده می‌شود و نیازی به راه‌اندازی مجدد نیست، زیرا سرور در حال اجرا، اعتبارنامه را ذخیره کرده و ارجاع را به‌صورت زنده حل می‌کند. بخش دسترسی به رابط کاربری وب dsh روی سرور راه دور تونل و حالت reverse proxy را پوشش می‌دهد و نصب DeepSeek Harness روی VPS آماده‌سازی سرور که این راهنما فرض کرده است را توضیح می‌دهد.

پس از ذخیره‌سازی، بررسی کنید برنامه چه چیزی ایجاد کرده است.

ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yaml

شما باید settings.yaml، .credentials.yaml و profiles/ را ببینید. اگر stat حالتی غیر از 600 را نشان داد، دستور chmod 600 ~/.dsh/.credentials.yaml را اجرا کنید. یک فایل اعتبارنامه که برای گروه یا همه قابل خواندن باشد، کلید شما را در اختیار سایر حساب‌های کاربری روی سیستم قرار می‌دهد.

برای اولین اجرا بدون مرورگر، یک دستور کافی است.

npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"

پروفایل headless یک نشست واحد اجرا کرده و پاسخ نهایی را چاپ می‌کند.

متغیرهای محیطی یا فایل پیکربندی

دو روش برای ارائه کلید به dsh وجود دارد که با یکدیگر قابل جایگزینی نیستند.

یک ارائه‌دهنده کاتالوگ (مانند DeepSeek، Anthropic، OpenAI و سایر موارد موجود در لیست پیش‌فرض) کلید خود را از طریق صفحه Models دریافت می‌کند. مقدار کلید در ~/.dsh/.credentials.yaml قرار می‌گیرد و تنظیمات شما فقط یک ارجاع به آن را نگه می‌دارد. رابط کاربری وب پس از ذخیره کردن، دیگر کلید را نمایش نمی‌دهد.

یک ارائه‌دهنده سفارشی می‌تواند به جای آن، نام یک متغیر محیطی را با استفاده از apiKeyEnv مشخص کند. این همان قالبی است که مستندات برای ~/.dsh/settings.yaml ارائه می‌دهند.

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

ابتدا یک ارائه‌دهنده را از طریق رابط کاربری وب اضافه کنید، سپس ~/.dsh/settings.yaml را باز کرده و ساختاری که توسط برنامه نوشته شده است را کپی کنید. در طول دوره پیش‌نمایش توسعه‌دهندگان، بخش nesting بیشترین احتمال تغییر را دارد و فایلی که برنامه به‌تازگی نوشته است، همیشه معتبرترین نسخه است.

apiKeyEnv از محیط پردازش dsh خوانده می‌شود، نه از shell ورود شما. کلیدی که در یک نشست تعاملی export شده باشد، برای یک unit در systemd نامرئی است؛ بنابراین همان پیکربندی که هنگام اجرای دستی dsh web کار می‌کند، در صورتی که به عنوان یک سرویس اجرا شود، خطای MISSING_CREDENTIAL را برمی‌گرداند. برای unit یک فایل اختصاصی در نظر بگیرید.

[Service]
EnvironmentFile=/etc/dsh/dsh.env

آن فایل را با دسترسی 600 و مالکیت کاربری که سرویس با آن اجرا می‌شود، نگهداری کنید.

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

هر ارائه‌دهنده‌ای که پیکربندی شده باشد در انتخابگر مدل ظاهر می‌شود. انتخاب یک مدل، آن را به عنوان پیش‌فرض برای نشست‌های جدید نیز تعیین می‌کند. نشست‌هایی که از قبل وجود دارند، مدل ثبت‌شده در خود را حفظ می‌کنند، بنابراین تغییر مدل باعث بازنویسی یک گفتگوی قدیمی نمی‌شود.

شناسه ارائه‌دهنده (Provider ID) دائمی است. درخواست‌ها، نشست‌های ذخیره‌شده، مدل‌های پیش‌فرض و ارجاعات اعتبارنامه همگی به آن اشاره دارند، به همین دلیل دکمه‌ای برای تغییر نام وجود ندارد. تغییر آن به معنای ایجاد یک ارائه‌دهنده جدید و حذف ارائه‌دهنده قدیمی است. نامی را انتخاب کنید که با آن راحت باشید: local-ollama به جای test2.

مدل‌ها فقط متنی هستند مگر اینکه خلاف آن را اعلام کنید. برای اعلام پشتیبانی از تصویر، input: [text, image] را به ورودی مدل اضافه کنید، یا defaultInput را در سطح مسیر (route) به عنوان جایگزین برای مدل‌هایی که در کاتالوگ توصیف نشده‌اند، تنظیم کنید. مسیر chat-completions اختصاصی DeepSeek فقط متنی است و نمی‌توان آن را به شکل دیگری پیکربندی کرد، بنابراین تصویری که به آن مسیر پیوست شود، پیش از ارسال هرگونه داده‌ای رد می‌شود.

اشاره dsh به یک endpoint محلی برای نگهداری کد روی سرور

Ollama یک API سازگار با OpenAI را روی http://127.0.0.1:11434/v1 ارائه می‌دهد. dsh از طریق یک provider سفارشی با هر base URL سازگار با OpenAI ارتباط برقرار می‌کند، بنابراین این دو بدون واسطه به هم متصل می‌شوند. ابتدا سرور مدل را راه‌اندازی کنید: میزبانی LLM با Ollama روی VPS مراحل نصب و دریافت مدل را پوشش می‌دهد.

پیش از کار با dsh، پاسخ‌دهی endpoint را تأیید کنید.

ollama list
curl -s http://127.0.0.1:11434/v1/models

ollama list تگ دقیق هر مدلی که دریافت کرده‌اید را چاپ می‌کند. آن رشته را کپی کنید. curl همان مدل‌ها را به صورت JSON برمی‌گرداند. لیست خالی به این معنی است که Ollama در حال اجراست اما مدلی دریافت نشده است. Connection refused یعنی Ollama در حال اجرا نیست یا روی پورت 11434 گوش نمی‌دهد.

اکنون provider را اضافه کنید. Ollama به یک فیلد API key نیاز دارد اما مقدار آن را نادیده می‌گیرد، بنابراین هر رشته غیرخالی کار می‌کند.

llm-pi-ai:
  providers:
    local-ollama:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://127.0.0.1:11434/v1
      models:
        - id: <the exact tag printed by ollama list>

متغیر را طوری export کنید که فرآیند dsh آن را ببیند.

sudo install -d -m 700 /etc/dsh
printf 'OLLAMA_API_KEY=ollama\n' | sudo tee /etc/dsh/dsh.env
sudo chmod 600 /etc/dsh/dsh.env

سه خطا تقریباً تمام تلاش‌ها برای این کار را پوشش می‌دهند. MISSING_CREDENTIAL یعنی dsh نتوانسته متغیر نام‌گذاری شده توسط apiKeyEnv را بخواند، بنابراین محیط فرآیند را بررسی کنید، نه محیط ترمینال خود را. UNKNOWN_MODEL یعنی id با مدل پیکربندی‌شده مطابقت ندارد، بنابراین آن را کاراکتر به کاراکتر با ollama list مقایسه کنید، از جمله تگ بعد از دونقطه. خطای 401 هنگام دریافت مدل‌های موجود از بخش کشف مدل ناشی می‌شود که GET /models را روی base URL شما فراخوانی می‌کند؛ endpointهایی که این مسیر را ارائه نمی‌دهند، نیاز دارند مدل‌هایشان به صورت دستی وارد شود.

یک تله دیگر، base URL است. /v1 را از انتهای آن حذف نکنید؛ در غیر این صورت درخواست‌ها به مسیرهایی می‌روند که Ollama ارائه نمی‌دهد، بنابراین فراخوانی با خطای 404 برمی‌گردد و مدل هرگز اجرا نمی‌شود. این پسوند بخشی از سطح سازگار با OpenAI است، نه یک تزئین.

اگر Ollama روی ماشین دیگری اجرا می‌شود، آدرس آن ماشین به base URL تبدیل می‌شود و پرامپت‌های شما از طریق شبکه به صورت متن ساده (cleartext) روی HTTP معمولی منتقل می‌شوند. آن را روی همان میزبان نگه دارید، یا آن را پشت TLS (امنیت لایه انتقال) و احراز هویت قرار دهید: ایمن‌سازی یک endpoint در معرض Ollama.

چه داده‌هایی در هر حالت از دستگاه خارج می‌شوند

با استفاده از کلید DeepSeek، هر درخواست به API شرکت DeepSeek ارسال می‌شود. این درخواست شامل پرامپت شما، محتوای فایل‌هایی که عامل (agent) برای پاسخ‌دهی خوانده است، خروجی دستوراتی که اجرا کرده و هر نتیجه‌ای از ابزارهاست که برای گنجاندن در پاسخ انتخاب کرده است. هر زمان که عامل فایلی را باز کند، کد منبع شما در این محموله (payload) قرار می‌گیرد. این نحوهٔ عملکرد یک مدل میزبانی‌شده (hosted) است و به همین دلیل باید در مورد دایرکتوری‌ای که عامل را در آن اجرا می‌کنید، دقت داشته باشید.

در صورت استفاده از ارائه‌دهندهٔ کاتالوگ دیگر یا gateway شرکتی، همان محموله به جای DeepSeek به آن فروشنده ارسال می‌شود. آدرس base URL دقیقاً مشخص می‌کند که مقصد کجاست.

در حالت استفاده از endpoint محلی، درخواست مدل به 127.0.0.1:11434 ارسال شده و روی همان دستگاه باقی می‌ماند. هیچ بخشی از کد شما به فروشندهٔ مدل نمی‌رسد. با این حال، سه مورد همچنان از شبکه عبور می‌کنند: npx بسته را از رجیستری npm دانلود می‌کند. هر ابزاری که عامل اجرا می‌کند می‌تواند به‌طور مستقل به اینترنت دسترسی داشته باشد، از جمله سرورهای MCP (پروتکل زمینه مدل) که به آن‌ها متصل شده‌اید؛ موضوعی که در اجرای سرورهای MCP روی یک VPS به‌طور مفصل بررسی شده است. مورد سوم نیز تله‌متری است، اگر آن را فعال کرده باشید.

تله‌متری تا زمانی که خودتان رضایت ندهید، غیرفعال است. DSH_TELEMETRY_MODE سوئیچ رضایت است و مقادیر تنظیم‌نشده، خالی یا ناشناخته به DISABLED تفسیر می‌شوند. در این وضعیت، dsh هیچ ارائه‌دهنده، پردازشگر یا صادرکنندهٔ OpenTelemetry (OTel) ایجاد نمی‌کند، بنابراین یک پروفایل جدید هیچ درخواست شبکه‌ای برای تله‌متری ارسال نخواهد کرد. FEEDBACK_ONLY امکان اشتراک‌گذاری لاگ نشست (session log) را با بازخورد کاربر فعال می‌کند. FULL نیز گزارش‌دهی لانچر را مجاز می‌سازد. فید نشست می‌تواند محتوای نشست، داده‌های ابزارها، پرامپت‌ها و مسیرهای فضای کاری را صادر کند، بنابراین FULL را به منزلهٔ ارسال کار خود به DeepSeek در نظر بگیرید.

برای توقف قطعی که به درستیِ رشتهٔ حالت (mode string) وابسته نباشد، DSH_TELEMETRY_DISABLED=1 را تنظیم کنید. هر مقدار غیرخالی به معنای انصراف قطعی (opt-out) است و پیش از شروع اجرا خوانده می‌شود، بنابراین کد پروژه نمی‌تواند آن را در میانهٔ نشست دوباره فعال کند. آدرس پیش‌فرض جمع‌آوری‌کننده harness-telemetry.deepseeksvc.com است که دانستن این نام هنگام بررسی لاگ‌های فایروال خودتان مفید خواهد بود.

به جای اعتماد به تنظیمات، آن‌ها را راستی‌آزمایی کنید. در حالی که یک تسک در حال اجراست، اتصالات خروجیِ آن پردازش را لیست کنید.

sudo ss -tnp | grep -i node

در حالت مدل محلی (local-model)، باید فقط اتصال loopback به 11434 را ببینید و هیچ اتصالی به آدرس عمومی وجود نداشته باشد. هر مورد دیگری پیش از ادامه کار، ارزش بررسی و شناسایی دارد. آنچه یک عامل برنامه‌نویسی به خانه می‌فرستد همین بررسی را روی سایر ابزارها انجام می‌دهد و نحوهٔ خواندن نتایج را توضیح می‌دهد.

مکان‌هایی که نباید اسرار را در آن‌ها قرار داد

• تاریخچه شل (Shell history). export DEEPSEEK_API_KEY=sk-... به‌صورت متن ساده در ~/.bash_history نوشته می‌شود و حتی مدت‌ها پس از چرخش (rotate) کلید، در آنجا باقی می‌ماند. هنگامی که HISTCONTROL=ignorespace تنظیم شده است، پیش از دستور یک فاصله (space) قرار دهید، یا از شل صرف‌نظر کرده و مقدار را مستقیماً با حالت 600 در یک فایل بنویسید.
• فایل‌های dotfiles که commit شده‌اند. اگر dotfiles خود را در git نگه می‌دارید، یک کلید در ~/.bashrc یا ~/.zshrc تنها به اندازه یک git add با یک مخزن عمومی فاصله دارد. پیش از push کردن، git grep -I -n 'sk-' را در آن مخزن اجرا کنید.
• settings.yaml. برای ارائه‌دهندگان سفارشی از apiKeyEnv استفاده کنید تا فایل به‌جای یک راز، حاوی نام متغیر باشد. فایل‌های پیکربندی ممکن است در گزارش‌های خطا و چت‌های پشتیبانی کپی شوند، اما فایل‌های حاوی اعتبارنامه‌ها (credentials) نباید چنین باشند.
• خروجی env و اسکرین‌شات‌های ترمینال. هر چیزی که کل محیط (environment) را چاپ کند، کلید را نیز به همراه آن چاپ می‌کند.
• پشتیبان‌گیری (Backups). ارزش ~/.dsh برای پشتیبان‌گیری بالاست و .credentials.yaml درون آن یک راز فعال محسوب می‌شود. آن فایل را مستثنی کنید یا آرشیو را رمزنگاری نمایید.

این قوانین مختص dsh نیستند و دور نگه داشتن اسرار از فایل‌های env در Compose همین مشکل را در سمت کانتینرِ همان سرور پوشش می‌دهد.

کار با نسخه پیش‌نمایش توسعه‌دهنده

نسخه‌ای را که آزمایش کرده‌اید ثابت (Pin) کنید، زیرا نسخه پیش‌نمایش ممکن است در یک وصله (patch release) کلید پیکربندی را تغییر دهد و در نتیجه ارائه‌دهنده شما قادر به بارگذاری نباشد. فایل‌های settings.yaml و cordis.patch.yml را در سیستم کنترل نسخه نگهداری کنید و فایل حاوی اعتبارنامه‌ها را از آن مستثنی کنید تا بتوانید تغییرات پس از ارتقا را مشاهده کنید.

هنگامی که یک پروفایل رفتار غیرمنتظره‌ای دارد، دو فلگ به شما کمک می‌کنند. فلگ --dump-default-config پیکربندی پیش‌فرض ترکیب‌شده را بدون راه‌اندازی سرویس چاپ می‌کند و --dump-config پیکربندی ترکیب‌شده برای پروفایل شما را به همان روش نمایش می‌دهد. مقایسه این دو نشان می‌دهد که لایه وصله شما دقیقاً چه چیزی را تغییر داده است؛ این روش بسیار سریع‌تر از بررسی دستی لایه‌هاست.

dsh --profile web --dump-config

هنگامی که پس از ارتقا مشکلی پیش آمد، ابتدا آن دستور را اجرا کنید. کلیدی که بین نسخه‌ها جابه‌جا شده است، به صورت یک شاخه (branch) مفقود در خروجی ظاهر می‌شود و اصلاح آن به جای نصب مجدد، تنها با یک ویرایش تک‌خطی انجام می‌شود.

FAQ

dsh کلید API مربوط به DeepSeek من را کجا ذخیره می‌کند؟

در $DSH_HOME/.credentials.yaml، که اگر خودتان DSH_HOME را تنظیم نکنید، همان ~/.dsh/.credentials.yaml خواهد بود. صفحه Models کلید را در آنجا می‌نویسد و تنظیمات شما فقط حاوی یک ارجاع به آن است، بنابراین این دادهٔ محرمانه در یک فایل قرار می‌گیرد. وضعیت دسترسی (mode) را با stat -c '%a %n' ~/.dsh/.credentials.yaml بررسی کنید و اگر مقداری غیر از 600 دارد، آن را به 600 تغییر دهید. با تعریف یک متغیر محیطی توسط apiKeyEnv، می‌توانید از ذخیره فایل توسط یک ارائه‌دهنده سفارشی کاملاً جلوگیری کنید.

چگونه dsh را وادار کنم به‌جای API مربوط به DeepSeek از یک مدل محلی استفاده کند؟

یک ارائه‌دهنده سفارشی اضافه کنید که base URL آن، endpoint محلی سازگار با OpenAI شما باشد. برای Ollama این آدرس http://127.0.0.1:11434/v1 است، به همراه api: openai-completions و نام مدلی که دقیقاً از ollama list کپی شده باشد، یعنی id. Ollama به یک مقدار برای کلید API نیاز دارد اما آن را نادیده می‌گیرد، بنابراین هر رشتهٔ غیرخالی کارساز است. پیش از ویرایش هرگونه تنظیمات dsh، با curl -s http://127.0.0.1:11434/v1/models تأیید کنید که endpoint پاسخ می‌دهد، زیرا یک endpoint غیرفعال و یک تنظیمات اشتباه، خطاهای مشابهی ایجاد می‌کنند.

آیا dsh به‌صورت پیش‌فرض کد من را به جایی می‌فرستد؟

در صورت استفاده از مدل میزبانی‌شده (hosted)، بله. prompt شما و محتویات فایل‌هایی که agent خوانده است، درون درخواست API به آن ارائه‌دهنده قرار می‌گیرند. با یک endpoint محلی، آن درخواست به loopback می‌رود و روی همان ماشین باقی می‌ماند. تله‌متری یک جریان دادهٔ جداگانه است و به‌صورت پیش‌فرض غیرفعال است: DSH_TELEMETRY_MODE در صورت تنظیم‌نشدن به DISABLED تبدیل می‌شود و در این حالت هیچ exporter ایجاد نمی‌شود. برای انصراف (opt-out) که پیش از شروع اجرا خوانده می‌شود، DSH_TELEMETRY_DISABLED=1 را تنظیم کنید.

چرا با وجود تنظیم متغیر، dsh خطای MISSING_CREDENTIAL گزارش می‌دهد؟

زیرا dsh متغیری که توسط apiKeyEnv نام‌گذاری شده را از محیط پردازش (process environment) خودش می‌خواند. متغیری که در shell شما export شده است، به یک سرویس systemd، نشست (session) یک کاربر دیگر، یا پردازشی که پیش از export کردن شما شروع شده، نمی‌رسد. مقدار را در یک EnvironmentFile با دسترسی 600 برای آن unit قرار دهید، یا آن را در همان shell که dsh را شروع می‌کند، export کنید. با استفاده از sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ تأیید کنید که پردازش در حال اجرا واقعاً چه مقداری را در اختیار دارد.

dsh به کدام نسخه از Node.js نیاز دارد؟

Node.js 22.19 یا نسخه‌های بالاتر در شاخه 22، یا نسخه 24 و بالاتر. Node 23 خارج از محدوده پشتیبانی‌شده قرار دارد. پیش از هر کاری node -v را اجرا کنید، زیرا شکست در راه‌اندازی به دلیل runtime پشتیبانی‌نشده، شبیه به خرابی نصب به نظر می‌رسد و باعث می‌شود کاربران به‌جای ارتقای runtime، بسته را مجدداً نصب کنند.