آموزش تنظیمات و پیکربندی dsh و API Key

محل نگهداری پیکربندی dsh

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

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

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

DeepSeek این ابزار را در تاریخ 17 اوت 2026 به عنوان یک پیش‌نمایش توسعه‌دهنده با مجوز MIT منتشر کرد و در فایل README ذکر شده است که تغییرات ناسازگار با نسخه‌های قبلی در راه است. نام فیلدها و مسیرهای ذکر شده در این راهنما، مطابق با مستندات مخزن تا اوت 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 فوروارد کنید. اگر URL نمایش‌داده‌شده مبهم است، دلیل اجرای dsh روی این آدرس توضیح می‌دهد که اتصال به loopback از چه چیزی محافظت می‌کند و چه کاری انجام نمی‌دهد.

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

آدرس http://127.0.0.1:3080 را در لپ‌تاپ خود باز کنید و سپس به بخش Settings و Models بروید. کارت DeepSeek دارای یک فیلد برای کلید API است. کلید را از 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 سفارشی با هر 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 را روی URL پایهٔ شما فراخوانی می‌کند؛ endpointهایی که این مسیر را ارائه نمی‌دهند، نیاز دارند مدل‌هایشان به صورت دستی وارد شود.

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

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

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

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

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

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

تله‌متری تا زمانی که خودتان رضایت ندهید، غیرفعال است. DSH_TELEMETRY_MODE کلید رضایت است و مقادیر تنظیم‌نشده، خالی یا ناشناخته به DISABLED تفسیر می‌شوند. در این حالت، dsh هیچ ارائه‌دهنده، پردازشگر یا صادرکنندهٔ OpenTelemetry (OTel) ایجاد نمی‌کند، بنابراین یک پروفایل جدید هیچ درخواست شبکهٔ تله‌متری ارسال نخواهد کرد. FEEDBACK_ONLY امکان اشتراک‌گذاری لاگ‌های نشست (session) بر اساس بازخورد را فعال می‌کند. 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 در یک فایل بنویسید.
• فایل‌های dotfile که commit شده‌اند. یک کلید در ~/.bashrc یا ~/.zshrc اگر dotfileها را در git نگهداری می‌کنید، تنها به اندازه یک git add با یک مخزن عمومی فاصله دارد. پیش از push کردن، git grep -I -n 'sk-' را در آن مخزن اجرا کنید.
• settings.yaml. برای ارائه‌دهندگان سفارشی از apiKeyEnv استفاده کنید تا فایل به‌جای یک راز، حاوی نام متغیر باشد. فایل‌های پیکربندی در گزارش‌های خطا و چت‌های پشتیبانی کپی می‌شوند، اما فایل‌های حاوی اعتبارنامه‌ها نباید چنین باشند.
• خروجی env و اسکرین‌شات‌های ترمینال. هر چیزی که کل محیط (environment) را چاپ کند، کلید را نیز به همراه آن چاپ می‌کند.
• پشتیبان‌گیری (Backups). ~/.dsh ارزش پشتیبان‌گیری دارد و .credentials.yaml درون آن یک راز فعال است. آن فایل را مستثنی کنید یا آرشیو را رمزنگاری نمایید.

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

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

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

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

dsh --profile web --dump-config

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

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 و یک مدل id که دقیقاً از ollama list کپی شده است. 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، بسته را دوباره نصب کنند.