dsh 配置指南:API 密钥、模型与本地端点设置
详解 dsh 在 Linux 上的配置路径与文件结构。本文说明如何配置 DeepSeek API 密钥及 Ollama 本地端点,并针对 0.2.0-rc.2 版本提供 Node.js 环境要求与配置优先级说明,帮助您正确管理凭据并避免旧版 settings.yaml 的兼容性陷阱。
dsh 的配置存放位置
dsh(DeepSeek Harness)将 harness 数据存放在 $DSH_HOME 下,默认路径为 ~/.dsh;共享 agent 配置则从另一个根目录 $DSH_AGENTS_HOME 读取,默认路径为 ~/.agents。您在 Web UI 中设置的任何内容都会以纯文本文件形式写入这些目录。将配置迁移到另一台服务器时,请复制 harness 主目录,以及共享 agent 根目录中的全局指令和 skills。
以下 4 个路径包含主要的 harness 设置、密钥和会话日志。
~/.dsh/profiles/<profile>/cordis.patch.yml保存 Web UI 为该配置文件写入的设置,包括 provider 和 model 路由。dsh web运行web配置文件,因此该文件为~/.dsh/profiles/web/cordis.patch.yml。~/.dsh/.credentials.yaml保存密钥。设置中只保留 credential 的引用,因此密钥值本身存放在其中一个文件中。~/.dsh/profiles/保存命名配置文件,~/.dsh/sessions/保存已保存的会话日志。~/.dsh/cordis.patch.yml是您自己的补丁层。它会应用于每个配置文件的内置配置之上,并且优先级高于配置文件。因此,如果 Web UI 的修改会被该层覆盖,dsh 会拒绝保存,而不是写入该修改。
共享 agent 根目录位于 $DSH_HOME 之外,因为其他 agent 工具也会使用它。dsh 从 ~/.agents/AGENTS.md 读取用户级全局指令,并扫描 ~/.agents/skills/ 中的 skills;设置 DSH_AGENTS_HOME 可更改该根目录的位置。
早期版本将这些设置保存在 ~/.dsh/settings.yaml 中。当前版本会将该文件导入活动配置文件一次,然后将其重命名为 settings.yaml.imported。因此,旧指南中要求编辑 settings.yaml 的说明现在指向 dsh 已不再读取的文件。
DeepSeek 以 MIT 许可发布 harness 的开发者预览版,README 说明后续会出现不兼容的变更。本指南中的字段名称和路径与当前仓库文档一致,文档核查时间为 5 November 2026。在从任何指南(包括本指南)复制配置前,请根据您安装的版本检查这些内容,因为预览版会在不同发行版本之间重命名配置项。
首次输出的诚实最低要求
dsh 需要 Node.js 24.9 或更高版本。截至 5 November 2026,其 package.json 声明为 >=24.9.0,因此不支持 22 系列。Node 24.0 至 24.8 也不够。请先检查版本,因为版本不匹配会导致启动失败,而错误信息看起来像软件包损坏。
node -v
npx @deepseek-ai/dsh webnpx 从 npm 注册表下载软件包,并在 http://127.0.0.1:3080 上启动 Web UI。它绑定到环回地址,因此即使防火墙允许访问,该端口也无法从其他机器访问。在 VPS 上,应通过 SSH 转发端口,而不是将 3080 暴露到互联网。如果输出的 URL 令人困惑,请参阅dsh 为什么在该地址启动,了解环回绑定可以保护什么,以及不能保护什么。
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 Web UI介绍 SSH 隧道和反向代理场景,在 VPS 上安装 DeepSeek Harness介绍本指南所假设的服务器准备工作。
保存后,查看应用创建的内容。
ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yaml您应看到 .credentials.yaml 和 profiles/,Web UI 的设置位于 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"无头配置文件运行单个会话,并输出最终答案。
环境变量或配置文件
dsh 可以从已保存的凭据或环境变量回退值中解析密钥。
目录中的提供商(DeepSeek、Anthropic、OpenAI 以及内置列表中的其他提供商)可通过 Models 页面接收密钥;如果没有已保存的凭据提供密钥,则使用其支持的环境变量回退值。该值会写入 ~/.dsh/.credentials.yaml,您的设置中只保存对它的引用。保存后,Web UI 不会再次显示该密钥。
自定义提供商可以通过 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]先通过 Web UI 添加一个提供商,然后打开配置文件中的 cordis.patch.yml,复制其中写入的结构。在开发预览期间,最可能发生变化的是嵌套结构;应用刚刚写入的文件始终是最新格式。
apiKeyEnv 按以下顺序通过凭据存储解析:已保存的文件优先,其次是启动环境、调用目录中的 .env,最后是 $DSH_HOME/.env。仅在交互式会话中导出的密钥对 systemd 单元不可见。因此,如果没有其他凭据来源,同一份配置在您手动输入 dsh web 时可以正常工作,但在服务中会返回 MISSING_CREDENTIAL。请为该单元提供单独的文件。
[Service]
EnvironmentFile=/etc/dsh/dsh.env将该文件的权限设置为 600,并将所有者设为运行服务的用户。
选择模型,以及无法重命名的 ID
每个已配置的提供商都会显示在模型选择器中。选择模型后,它也会成为新会话的默认模型。已经发送过请求的会话会保留其中记录的模型,因此切换模型不会改写旧对话。
Provider ID 是永久的。请求、已保存的会话、模型默认值和凭据引用都指向该 ID,因此没有重命名按钮。更改 ID 就意味着创建新的提供商并删除旧的提供商。请选择一个长期使用也合适的名称:local-ollama,而不是 test2。
未继承图像能力的自定义模型默认为纯文本模型,除非另行声明。在模型条目中添加 input: [text, image] 可声明图像支持;也可以在路由级别设置 defaultInput,作为目录未描述这些模型时的后备值。在 DeepSeek 自有路由上,未声明模态的模型会被视为纯文本模型,因此在附加图像前,请选择支持图像的目录条目(默认为 deepseek-flash)。向未声明支持图像的模型发送图像时,请求会在发送任何内容前被拒绝。
将 dsh 指向本地端点,让代码留在本机
Ollama 在 http://127.0.0.1:11434/v1 提供兼容 OpenAI 的 API。dsh 可通过自定义提供商连接到任意兼容 OpenAI 的基础 URL,因此两者可以直接连接。先设置模型服务器:在 VPS 上使用 Ollama 自托管 LLM介绍安装和拉取模型的步骤。
操作 dsh 前,先确认端点能够正常响应。
ollama list
curl -s http://127.0.0.1:11434/v1/modelsollama 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,原因是模型发现功能会在基础 URL 上调用 GET /models;不提供该路径的端点需要手动填写模型。
基础 URL 还有一个容易出错的地方。不要省略其中的 /v1,否则请求会发送到 Ollama 未提供的路径,调用将返回 404,模型也不会运行。该后缀是兼容 OpenAI 接口的一部分,不是装饰内容。
如果 Ollama 运行在另一台机器上,该机器的地址就是基础 URL。此时,提示词会通过普通 HTTP 以明文形式在网络上传输。应让 Ollama 与 dsh 位于同一台主机,或为其配置 TLS(传输层安全)和身份验证:保护暴露在公网的 Ollama 端点。
每种模式下哪些内容会离开机器
使用 DeepSeek key 和默认端点时,模型请求会发送到 DeepSeek API。该请求包含您的提示词、代理为回答提示词而读取的文件内容、代理运行的命令输出,以及代理选择包含的任何工具结果。只要代理打开过文件,您的源代码就会包含在该请求中。这是托管模型的工作方式,也是您需要考虑从哪个目录启动代理的原因。
当前版本还会默认通过原生 DeepSeek 适配器,将会话事件日志中尚未接受的后缀附加到请求中;即使配置了网关,也同样适用。该内容作为独立的 dsh_session_log 字段发送。模型不会看到它,但请求的目标端会收到它。在 Settings、General 中关闭 “Upload Session Log when using the official model API”,或在 session-log-deepseek 插件上设置 enabled: false。下面的遥测开关不会控制此上传。
随附的配置文件还会通过原生 DeepSeek 适配器,在独立的 dsh_plugin_packages 字段中发送已启用的插件包名称和版本。在 plugin-package-inventory-deepseek 上设置 enabled: false,即可停止发送这些信息。
使用其他模型目录提供商或公司网关时,相同的请求负载会发送到对应的供应商。base URL 会明确告诉您请求的目标位置。
使用本地端点时,模型请求会发送到 127.0.0.1:11434,但仅凭回环地址并不能保证请求留在本机。Ollama 文档说明:“要通过此服务器使用云模型,请登录 Ollama。”因此,通过同一本地服务器选择的云模型会将您的提示词和代码发送到 Ollama 云端。只有模型本身在本地运行时,模型请求才会留在本机。即使如此,仍有三类内容会跨越网络。npx 会从 npm registry 下载软件包。代理运行的任何工具都可以自行访问互联网,包括您连接的 MCP(模型上下文协议)服务器;在 VPS 上运行 MCP 服务器对此有详细说明。插件也属于同一类,因为安装插件会以代理的权限运行其他作者的代码。因此,安装前应先检查插件可以访问哪些内容。此外还有遥测:当前版本在您提交反馈时,会授权将遥测导出到 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使用本地运行的模型时,模型流量会通过回环地址的 11434 端口,但即使没有提交任何反馈,工具仍可能建立公网连接。随附的配置文件包含网页搜索和抓取功能,默认权限预设不会限制网络访问。在将连接归因于遥测之前,请识别每个公网目标;仅凭连接时间不能证明它是反馈导出。此快照也可能遗漏短暂连接。此检查只覆盖 dsh 进程:云模型的流量会从 Ollama 服务器发出,因此还应确认模型 id 不是云端标签。其他任何连接都应在继续操作前完成识别。编码代理会向外发送什么会对其他代理框架执行相同检查,并说明如何解读结果。
不应存放密钥的位置
- Shell 历史记录。
export DEEPSEEK_API_KEY=sk-...会以明文写入~/.bash_history,即使轮换密钥后也会长期保留。设置HISTCONTROL=ignorespace后,在命令前加一个空格;或者跳过 Shell,直接将值写入权限模式为 600 的文件。 - 已提交的点文件。如果将点文件纳入 git 管理,
~/.bashrc或~/.zshrc中的密钥只需git add一步就可能进入公开代码仓库。推送前,在该仓库中运行git grep -I -n 'sk-'。 - 配置文件补丁。对于自定义提供程序,使用
apiKeyEnv,这样cordis.patch.yml中保存的是变量名,而不是密钥。配置文件经常会被粘贴到问题报告和支持聊天中,凭据文件不会。 env的输出和终端屏幕截图。任何会输出完整环境变量的命令,也会同时输出密钥。- 备份。
~/.dsh值得备份,但其中的.credentials.yaml是有效密钥。排除该文件,或加密归档文件。
这些规则并不只适用于 dsh;不要将密钥放入 Compose 环境文件介绍了同一台服务器容器侧的相同问题。
体验开发者预览版
请固定已测试的版本,因为预览版可能在补丁版本中更改配置键,导致您的提供商无法加载。如果固定版本的安装仍拒绝启动,或者 npx 持续提供您未请求的构建版本,请参阅预览版产生的安装和版本错误,其中介绍了 npx 缓存以及 Node 自带的 npm。将主目录中的 cordis.patch.yml 和 profiles/ 下的补丁文件纳入版本控制,但排除凭据文件。这样升级后即可查看发生了哪些变化。
配置文件行为异常时,两个选项很有帮助。--dump-default-config 会在不启动的情况下输出组合后的默认配置,--dump-config 则以相同方式输出您配置文件的组合配置。比较两者即可看出补丁层实际更改了什么,比手动阅读各层配置更快。
dsh --profile web --dump-config升级后出现问题时,先运行该命令。版本发布之间移动的配置键会在转储中显示为缺失分支。修复只需编辑一行,无需重新安装。
FAQ
dsh 将 DeepSeek API 密钥存储在哪里?
存储在 $DSH_HOME/.credentials.yaml 中;如果您未自行设置 DSH_HOME,其路径就是 ~/.dsh/.credentials.yaml。Models 页面会将密钥写入该文件,您的设置中只保存对它的引用,因此密钥只存在于一个文件中。使用 stat -c '%a %n' ~/.dsh/.credentials.yaml 检查文件权限;如果权限比 600 更宽松,请将其设置为 600。自定义提供商可以通过使用 apiKeyEnv 指定环境变量,完全避免使用该文件。
如何让 dsh 使用本地模型,而不是 DeepSeek API?
添加一个自定义提供商,将基础 URL 设置为本地的 OpenAI 兼容端点。对于 Ollama,该地址是 http://127.0.0.1:11434/v1;其中 api: openai-completions 和模型 id 必须从 ollama list 中逐字复制。为此配置提供一个非空的 API 密钥值;本地 Ollama 服务器会忽略该值。在修改任何 dsh 配置前,使用 curl -s http://127.0.0.1:11434/v1/models 确认端点能够响应,因为端点不可用和配置错误会产生相似的错误。
dsh 默认会将我的代码发送到其他位置吗?
如果使用托管模型,会发送。您的提示词以及代理读取的文件内容都会包含在发送给该供应商的 API 请求中。通过原生 DeepSeek 适配器发送的请求(包括经过已配置网关的请求)默认还会携带会话日志后缀,直到您在 Settings、General 中关闭该上传功能。使用 Ollama 在本地运行的模型时,请求会发送到回环地址并保留在本机上;但对于 gemma4:cloud 这类云模型,请求会通过同一个回环地址转发到 Ollama 云端。内置的 Web 搜索和抓取功能、其他工具及插件都可能独立联系公共服务,与反馈无关。
遥测是单独的数据流。在当前版本中,如果未设置 DSH_TELEMETRY_MODE,它会解析为 FEEDBACK_ONLY。因此,对于每个提供商(包括本地模型),反馈都会授权通过该事件导出会话日志前缀,其中包括继承的上下文。数据不保证一定送达;已授权的上传也可能在反馈操作结束后继续进行。将其设置为 DISABLED 可禁用导出器;也可以设置 DSH_TELEMETRY_DISABLED=1,以便在运行开始前读取退出遥测设置。
为什么变量已设置,dsh 仍报告 MISSING_CREDENTIAL?
因为 apiKeyEnv 指定的引用必须能在 dsh 的凭据来源中解析。已保存的凭据优先级最高,其次是启动环境,最后是启动目录中的 .env 和 $DSH_HOME/.env。在 shell 中导出的变量不会传递给 systemd 服务、其他用户的会话,或在导出变量之前启动的进程。请将值写入 EnvironmentFile,并将文件权限设置为 600,然后供该单元使用;或者在启动 dsh 的同一个 shell 中导出变量。使用 sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ 确认运行中的进程实际持有的值。
dsh 需要哪个 Node.js 版本?
根据仓库中的 package.json,截至 5 November 2026,需要 Node.js 24.9 或更高版本。22 系列已不再受支持,Node 24.0 到 24.8 也不满足要求。先运行 node -v,因为不受支持的运行时导致的启动失败看起来像安装损坏,容易让用户重新安装软件包,而不是安装正确的运行时。