SSD Nodes Learn Hosting plans →
Руководства Matt ConnorАвтор: Matt Connor · Обновлено 2026-11-06

Настройка dsh: API ключи, модели и эндпоинты

Узнайте, где dsh хранит конфигурацию в Linux, как настроить API ключ DeepSeek или локальный эндпоинт Ollama. Разбираем структуру файлов и безопасность передачи данных.

Где dsh хранит конфигурацию

dsh (DeepSeek Harness) хранит данные окружения в $DSH_HOME, путь по умолчанию — ~/.dsh, а общую конфигурацию агента считывает из отдельного корневого каталога $DSH_AGENTS_HOME, путь по умолчанию — ~/.agents. Все параметры, заданные через веб-интерфейс, сохраняются там в виде обычных файлов. При переносе конфигурации на другой сервер скопируйте домашний каталог окружения, а также все глобальные инструкции и навыки из общего корневого каталога агента.

Основные настройки, секреты и журналы сессий распределены по четырем путям.

  • ~/.dsh/profiles/<profile>/cordis.patch.yml содержит настройки, которые веб-интерфейс записывает для конкретного профиля, включая маршруты к провайдерам и моделям. dsh web использует профиль web, поэтому файл находится по адресу ~/.dsh/profiles/web/cordis.patch.yml.
  • ~/.dsh/.credentials.yaml хранит секреты. В настройках содержится только ссылка на учетные данные, поэтому само значение ключа находится в отдельном файле.
  • ~/.dsh/profiles/ содержит именованные профили, а ~/.dsh/sessions/ — сохраненные журналы сессий.
  • ~/.dsh/cordis.patch.yml — это ваш собственный слой исправлений. Он применяется поверх встроенной конфигурации для каждого профиля и имеет приоритет над файлом профиля. Если вы попытаетесь изменить через веб-интерфейс параметр, который переопределяется этим слоем, система отклонит сохранение.

Общий корневой каталог агента находится вне $DSH_HOME, так как его используют и другие инструменты агентов. dsh считывает глобальные инструкции пользователя из ~/.agents/AGENTS.md и сканирует ~/.agents/skills/ на наличие навыков; чтобы изменить этот корневой каталог, установите DSH_AGENTS_HOME.

В ранних сборках эти настройки хранились в ~/.dsh/settings.yaml. Текущие сборки один раз импортируют этот файл в активный профиль и переименовывают его в settings.yaml.imported. Поэтому старые руководства, предлагающие редактировать settings.yaml, ссылаются на файл, который dsh больше не считывает.

DeepSeek выпускает этот инструмент в виде предварительной версии для разработчиков (developer preview) под лицензией MIT. В файле README указано, что возможны изменения, нарушающие обратную совместимость. Имена полей и пути в этом руководстве соответствуют текущей документации репозитория по состоянию на 5 ноября 2026 года. Перед копированием конфигурации из любого руководства, включая это, сверяйтесь с документацией к установленной у вас версии, так как в предварительных версиях названия могут меняться от релиза к релизу.

Минимально необходимые действия для первого запуска

Для dsh требуется Node.js версии 24.9 или новее. По состоянию на 5 ноября 2026 года в файле package.json указана версия >=24.9.0, поэтому ветка 22 не поддерживается. Версии Node с 24.0 по 24.8 также недостаточно. Сначала проверьте версию, так как несоответствие версий приводит к сбою при запуске, а сообщение об ошибке выглядит как повреждение пакета.

node -v
npx @deepseek-ai/dsh web

Команда npx загружает пакет из реестра npm и запускает веб-интерфейс на http://127.0.0.1:3080. Она привязывается к адресу обратной петли (loopback), что означает, что порт недоступен с другого компьютера, даже если ваш межсетевой экран разрешает соединения. На VPS перенаправьте его через SSH вместо открытия порта 3080 для доступа из Интернета. Если выведенный 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 на удаленном сервере рассматриваются случаи использования туннеля и обратного прокси-сервера, а в установке DeepSeek Harness на VPS описана подготовка сервера, на которую опирается данное руководство.

После сохранения проверьте, что создало приложение.

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

Вы должны увидеть .credentials.yaml и profiles/, а настройки веб-интерфейса находятся в profiles/web/cordis.patch.yml. В домашнем каталоге, созданном более старой сборкой, также может находиться settings.yaml.imported. Если 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/profiles/web/cordis.patch.yml.

- id: llm-pi-ai
  config:
    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]

Сначала добавьте одного провайдера через веб-интерфейс, затем откройте cordis.patch.yml профиля и скопируйте созданную структуру. На этапе предварительного просмотра для разработчиков (developer preview) структура вложенности может меняться, поэтому файл, созданный приложением, всегда является актуальным.

apiKeyEnv разрешается через хранилище учетных данных: приоритет имеет сохраненный файл, затем переменные окружения при запуске, .env в директории вызова, и в последнюю очередь $DSH_HOME/.env. Ключ, экспортированный только в интерактивной сессии, недоступен для systemd-юнита. Поэтому без другого источника учетных данных та же конфигурация, которая работает при ручном вводе dsh web, вернет MISSING_CREDENTIAL при запуске в качестве службы. Создайте для юнита отдельный файл.

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

Установите для этого файла права доступа 600 и владельца, под которым работает служба.

Выбор моделей и идентификатор, который нельзя переименовать

Каждый настроенный провайдер отображается в средстве выбора моделей. Выбор модели также делает её используемой по умолчанию для новых сессий. В сессиях, где запрос уже был отправлен, модель сохраняется, поэтому переключение не перезаписывает старую переписку.

Идентификатор провайдера (Provider ID) является постоянным. Запросы, сохранённые сессии, настройки моделей по умолчанию и ссылки на учётные данные — всё это указывает на него, поэтому кнопки переименования не существует. Изменение идентификатора означает создание нового провайдера и удаление старого. Выбирайте имя, которое вас устроит: local-ollama вместо test2.

Пользовательские модели без унаследованной возможности работы с изображениями являются текстовыми, если вы не укажете иное. Добавьте input: [text, image] в запись модели, чтобы объявить поддержку изображений, или установите defaultInput на уровне маршрута в качестве резервного варианта для моделей, которые не описаны в каталоге. На собственном маршруте DeepSeek модель без объявленных модальностей считается только текстовой, поэтому выберите запись из каталога с поддержкой изображений (по умолчанию deepseek-flash), прежде чем прикреплять изображение. Изображение, отправленное модели, которая не заявляет о поддержке изображений, будет отклонено до того, как что-либо будет отправлено.

Настройка dsh на локальную конечную точку для работы кода внутри сервера

Ollama предоставляет API, совместимый с OpenAI, на http://127.0.0.1:11434/v1. dsh взаимодействует с любым базовым URL, совместимым с OpenAI, через пользовательский провайдер, поэтому они соединяются напрямую. Сначала настройте сервер моделей: в self-hosting an LLM with Ollama on a VPS описаны установка и загрузка моделей.

Убедитесь, что конечная точка отвечает, прежде чем переходить к dsh.

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

ollama list выводит точный тег каждой загруженной вами модели. Скопируйте эту строку. curl возвращает список тех же моделей в формате JSON. Пустой список означает, что Ollama запущена, но модели не загружены. Connection refused означает, что Ollama не запущена или не слушает порт 11434.

Выберите модель, которая работает на этой машине. Авторизованный сервер Ollama также предоставляет доступ к облачным моделям через тот же локальный адрес, поэтому облачный тег, такой как gemma4:cloud, будет выполняться на серверах Ollama. В этом случае ваши промпты покинут сервер, хотя dsh взаимодействует только с 127.0.0.1.

Теперь добавьте провайдера в патч профиля. Укажите непустое значение API-ключа для этой конфигурации; локальный сервер Ollama игнорирует его.

- id: llm-pi-ai
  config:
    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>

Экспортируйте переменную так, чтобы процесс 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 означает, что ссылка, указанная в apiKeyEnv, не разрешилась, поэтому проверьте сохраненные учетные данные и среду запуска, а не только терминал. UNKNOWN_MODEL означает, что id не соответствует настроенной модели, поэтому сравните их с ollama list посимвольно, включая тег после двоеточия. Ошибка 401 при получении списка доступных моделей возникает из-за механизма обнаружения моделей, который обращается к GET /models по вашему базовому URL; если конечные точки не обслуживают этот путь, модели нужно вводить вручную.

Еще одна ловушка — базовый URL. Если не добавить /v1, запросы будут направляться по путям, которые Ollama не обслуживает, поэтому вы получите 404, а модель не запустится. Этот суффикс является частью интерфейса, совместимого с OpenAI, а не декоративным элементом.

Если Ollama запущена на другой машине, адрес этой машины становится базовым URL, и ваши промпты будут передаваться по сети в открытом виде через обычный HTTP. Держите сервис на том же хосте или защитите его с помощью TLS (transport layer security) и аутентификации: locking down an exposed Ollama endpoint.

Что покидает машину в каждом режиме

При использовании ключа DeepSeek и стандартного endpoint запросы к модели отправляются через API DeepSeek. В такой запрос включается ваш промпт, содержимое файлов, которые агент прочитал для подготовки ответа, вывод выполненных им команд и результаты работы любых инструментов. Ваш исходный код попадает в этот payload каждый раз, когда агент открывает файл. Так работают облачные модели, и именно поэтому важно учитывать, в какой директории вы запускаете агент.

Текущие релизы также по умолчанию прикрепляют к запросам через нативный адаптер DeepSeek (включая настроенные шлюзы) непереданный суффикс лога событий сессии в виде отдельного поля dsh_session_log. Модель его не видит, но получатель запроса — да. Отключите это в Settings, General («Upload Session Log when using the official model API») или установите enabled: false для плагина session-log-deepseek. Переключатели телеметрии, описанные ниже, не управляют этой отправкой.

Поставляемые профили также отправляют имена и версии активных пакетов плагинов через нативный адаптер DeepSeek в отдельном поле dsh_plugin_packages. Установите enabled: false для plugin-package-inventory-deepseek, чтобы прекратить эту передачу.

При использовании другого провайдера каталога или корпоративного шлюза тот же payload отправляется соответствующему поставщику. Базовый URL точно указывает, куда именно.

При использовании локального endpoint запрос к модели уходит на 127.0.0.1:11434, но один лишь loopback-адрес не гарантирует, что данные останутся на машине. Документация Ollama гласит: «Чтобы использовать облачные модели через этот сервер, войдите в Ollama». Таким образом, облачная модель, выбранная через тот же локальный сервер, отправляет ваши промпты и код в облако Ollama. Запрос к модели остается на машине только в том случае, если сама модель запущена локально. Даже в этом случае три типа данных покидают сеть. npx загружает пакет из реестра npm. Любой инструмент, запускаемый агентом, может самостоятельно выйти в интернет, включая серверы MCP (model context protocol), к которым вы подключились (подробнее об этом в запуске MCP-серверов на VPS). Плагин относится к той же категории: его установка запускает код стороннего автора с правами вашего агента, поэтому стоит проверить доступные плагину ресурсы перед установкой. Телеметрия, которую текущие релизы разрешают экспортировать в DeepSeek при отправке обратной связи, работает с локальной моделью точно так же, как и с облачной.

По умолчанию телеметрия ограничена обратной связью. DSH_TELEMETRY_MODE выбирает режим, и в текущей базовой конфигурации пустое или не заданное значение соответствует FEEDBACK_ONLY. В этом режиме обычная активность не разрешает сбор телеметрии. Когда вы отправляете письменный отзыв, создаете или редактируете оценку, редактируете заметку или отзываете обратную связь, dsh разрешает экспорт префикса лога сессии (еще не переданного экспортеру) через событие обратной связи, включая унаследованный контекст, на адрес https://dsh-otel-collector.deepseeksvc.com/v1/logs. Полная доставка не гарантируется: событие слишком большого размера отклоняется без обрезки, а длинные префиксы могут остаться частично неотправленными при завершении работы CLI. Авторизованные пакеты данных могут продолжать отправляться без дополнительного взаимодействия или вызова модели. README по телеметрии гласит, что это применимо «для всех пользователей и провайдеров», поэтому запуск модели локально не отключает эту функцию. DISABLED не создает транспорт OpenTelemetry (OTel) вовсе. FULL больше не поддерживается: любое значение, отличное от двух указанных, отклоняется с ошибкой unsupported mode. Экспорт обратной связи может содержать текст сообщений, аргументы и результаты инструментов, а также пути к рабочим пространствам, поэтому считайте отправку отзыва разрешением на передачу этого префикса сессии в DeepSeek.

Для принудительной остановки, не зависящей от корректности строки режима, установите DSH_TELEMETRY_DISABLED=1. Любое непустое значение является авторитарным отказом, включая 0 и false; оно считывается до начала запуска, поэтому код проекта не сможет включить его обратно в середине сессии. Адрес сборщика по умолчанию — dsh-otel-collector.deepseeksvc.com; DSH_TELEMETRY_OTLP_URL переопределяет его.

Проверяйте настройки, а не полагайтесь на них. Во время выполнения задачи выведите список исходящих соединений, удерживаемых процессом.

sudo ss -tnp | grep -i node

При локально запущенной модели трафик модели использует loopback-порт 11434, но публичные соединения все равно могут исходить от инструментов без отправки обратной связи. Поставляемые профили включают поиск в сети и fetch, а стандартный пресет разрешений не ограничивает доступ к сети. Идентифицируйте каждый публичный пункт назначения, прежде чем приписывать его телеметрии; время соединения само по себе не доказывает, что это экспорт обратной связи. Этот снимок также может пропустить кратковременные соединения. Данная проверка охватывает только процесс dsh: трафик облачной модели исходит от сервера Ollama, поэтому убедитесь, что модель id не является облачным тегом. Любое другое соединение стоит идентифицировать перед продолжением работы. Что агент для программирования отправляет «домой» содержит описание аналогичной проверки для других инструментов и объясняет, как интерпретировать результат.

Где не следует хранить секреты

  • История командной оболочки. export DEEPSEEK_API_KEY=sk-... записывается в ~/.bash_history в открытом виде и остается там долгое время после ротации ключа. Добавляйте пробел перед командой, если установлена переменная HISTCONTROL=ignorespace, или не используйте оболочку и записывайте значение напрямую в файл с правами доступа 600.
  • Коммиты в dotfiles. Ключ в ~/.bashrc или ~/.zshrc может оказаться в публичном репозитории в один git add, если вы храните dotfiles в git. Запустите git grep -I -n 'sk-' в этом репозитории перед отправкой изменений (push).
  • Файлы патчей профилей. Используйте apiKeyEnv для пользовательских провайдеров, чтобы в cordis.patch.yml хранилось имя переменной, а не секрет. Файлы конфигурации часто копируют в отчеты об ошибках и чаты поддержки. Файлы с учетными данными — нет.
  • Вывод env и скриншоты терминала. Любая команда, выводящая все переменные окружения, выводит и ключ вместе с ними.
  • Резервные копии. ~/.dsh стоит копировать, но .credentials.yaml внутри него — это активный секрет. Исключите этот файл из архива или зашифруйте архив.

Эти правила не ограничиваются только dsh, а защита секретов в файлах окружения Compose описывает ту же проблему применительно к контейнерам на том же сервере.

Работа с developer preview

Зафиксируйте версию, которую вы протестировали, так как в preview-версиях ключи конфигурации могут меняться даже в патч-релизах, из-за чего провайдер перестанет загружаться. Если зафиксированная установка отказывается запускаться или npx продолжает выдавать сборку, которую вы не запрашивали, в ошибках установки и версий, возникающих в preview описана работа с кэшем npx и npm, поставляемым с вашим Node. Храните домашнюю директорию cordis.patch.yml и файлы патчей в profiles/ под контролем версий, исключив файл с учетными данными, чтобы видеть изменения после обновления.

Два флага помогают, если профиль работает некорректно. --dump-default-config выводит составную конфигурацию по умолчанию без запуска, а --dump-config аналогичным образом выводит составную конфигурацию для вашего профиля. Сравнение этих двух выводов показывает, что именно изменил ваш слой патчей; это быстрее, чем просматривать слои вручную.

dsh --profile web --dump-config

Если после обновления что-то перестало работать, запустите это в первую очередь. Ключ, перемещенный между релизами, будет виден как отсутствующая ветка в дампе, и исправление сведется к редактированию одной строки, а не к переустановке.

FAQ

Где dsh хранит мой API-ключ DeepSeek?

В $DSH_HOME/.credentials.yaml, который по умолчанию является ~/.dsh/.credentials.yaml, если вы не задали DSH_HOME самостоятельно. Страница Models записывает ключ в этот файл, а ваши настройки содержат только ссылку на него, поэтому секрет хранится в одном месте. Проверьте права доступа с помощью stat -c '%a %n' ~/.dsh/.credentials.yaml и установите их на 600, если они менее строгие. Пользовательский провайдер позволяет полностью избежать использования файла, если указать переменную окружения через apiKeyEnv.

Как заставить dsh использовать локальную модель вместо API DeepSeek?

Добавьте пользовательского провайдера, базовым URL которого будет ваш локальный OpenAI-совместимый эндпоинт. Для Ollama это http://127.0.0.1:11434/v1, с api: openai-completions и именем модели id, скопированным в точности из ollama list. Укажите любое непустое значение API-ключа для этой конфигурации; локальный сервер Ollama игнорирует его. Убедитесь, что эндпоинт отвечает на запросы с помощью curl -s http://127.0.0.1:11434/v1/models, прежде чем редактировать конфигурацию dsh, так как неработающий эндпоинт и неверная конфигурация вызывают схожие ошибки.

Отправляет ли dsh мой код куда-либо по умолчанию?

При использовании облачной модели — да. Ваш промпт и содержимое файлов, прочитанных агентом, передаются в API-запросе к этому поставщику. Запросы через нативный адаптер DeepSeek, включая настроенные шлюзы, также по умолчанию содержат суффикс сессионного лога, пока вы не отключите эту отправку в разделе Settings, General. Если модель запущена локально через Ollama, запрос уходит на loopback и остаётся на машине, однако облачная модель, такая как gemma4:cloud, передаёт данные в облако Ollama через тот же loopback-адрес. Встроенные инструменты поиска в сети, загрузки данных и плагины могут обращаться к публичным сервисам независимо от системы обратной связи. Телеметрия — это отдельный поток: в текущих релизах DSH_TELEMETRY_MODE разрешается в FEEDBACK_ONLY, если значение не задано. Обратная связь разрешает экспорт префикса сессионного лога через это событие, включая унаследованный контекст, для любого провайдера, включая локальные модели. Доставка не гарантируется, а авторизованная выгрузка данных может продолжаться и после взаимодействия с формой обратной связи. Установите значение DISABLED, чтобы отключить экспортёр, или DSH_TELEMETRY_DISABLED=1 для отказа от участия (opt-out), который считывается перед началом работы.

Почему dsh сообщает MISSING_CREDENTIAL, хотя переменная установлена?

Потому что ссылка, указанная в apiKeyEnv, должна разрешаться в источниках учётных данных dsh. Сохранённые учётные данные имеют приоритет над переменными окружения запуска, за ними следуют .env и $DSH_HOME/.env в директории запуска. Переменная, экспортированная в вашей оболочке, не попадает в systemd-сервис, сессию другого пользователя или процесс, запущенный до экспорта переменной. Поместите значение в EnvironmentFile с правами 600 для юнита или экспортируйте его в той же оболочке, из которой запускаете dsh. Проверьте, какие переменные фактически видит запущенный процесс, с помощью sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ.

Какая версия Node.js требуется для dsh?

Node.js 24.9 или новее, согласно файлу package.json в репозитории на 5 ноября 2026 года. Ветка 22 больше не поддерживается, а версии Node с 24.0 по 24.8 недостаточно. Выполните node -v перед любыми другими действиями, так как сбой при запуске из-за неподдерживаемой среды выполнения выглядит как повреждённая установка и заставляет пользователей переустанавливать пакет вместо обновления среды выполнения.

Была ли эта статья полезной?