DeepSeek Harness Linux/macOS/Windows 本地下载、启动与模型配置指南

编程的一拳超人

1424人浏览 · 2026-08-25 10:22:42

编程的一拳超人 · 2026-08-25 10:22:42 发布

📃作者主页：编程的一拳超人

⛺️ 欢迎关注：👍点赞 👂🏽留言 🌟收藏 💞 💞 💞

于高山之巅，方见大河奔涌；于群峰之上，更觉长风浩荡。

请添加图片描述
在这里插入图片描述

📌 专栏系列：DeepSeek Harness 安装 / 大模型工具调用 / 智能编程助手
⭐ 如果本文对你有帮助，欢迎点赞、收藏、关注三连支持！
💬 问题交流：评论区留言或私信，看到必回

DeepSeek Harness Linux/macOS/Windows 本地下载、启动与模型配置指南

DeepSeek Harness Linux/macOS/Windows 本地下载、启动与模型配置指南

本文针对官方仓库 deepseek-ai/deepseek-harness，简称 dsh。当前官方版本处于 Developer Preview，版本迭代较快，配置字段和命令可能发生不兼容变化。

本文同时覆盖 Linux、macOS 和 Windows。Harness 的 npm/pnpm 启动命令三个平台基本相同，主要差异在 Node.js/Git 安装方式、终端语法和用户数据目录写法。

平台约定：

平台	常用终端	默认 Harness 数据目录	环境变量写法
Windows	PowerShell	C:\Users<用户名>.dsh	$env:DSH_HOME = ‘D:/dsh-data’
macOS	Terminal、zsh	~/.dsh	export DSH_HOME=“$HOME/.dsh-data”
Linux	Bash、zsh	~/.dsh	export DSH_HOME=“$HOME/.dsh-data”

如果只想快速启动，直接跳到第 4 节；如果还没有 Node.js 和 Git，先看下面的跨平台安装说明。

1. 先分清两种“本地使用”

方式	Harness/Web UI	模型推理	是否需要 DeepSeek API Key
本地 Harness + DeepSeek 云端模型	本地	云端	需要
本地 Harness + Ollama/LM Studio/vLLM	本地	本地	不需要真实 DeepSeek Key
从源码运行	本地	可选云端或本地	取决于模型路由

“本地启动”默认只表示 Web UI 和 Harness 进程在本机运行；如果配置的是 DeepSeek API，提示词和代码仍会发往云端。要让模型推理也在本机完成，应使用 Ollama、LM Studio 或 vLLM，并在 Harness 中添加本地 OpenAI 兼容端点。

完全离线仍需要先联网下载 Harness npm 包和模型文件；下载完成后，模型请求可以只访问 127.0.0.1。如果要求严格离线，不要启用 Web 搜索、需要联网的 MCP 或云端模型。

2. 三个平台的运行环境安装

在这里插入图片描述

2.1 Windows

推荐从 Node.js 官网安装 Node.js 22.19+ 或 24+，安装时保持将 Node.js 加入 PATH。也可以使用 Windows Package Manager：

winget install OpenJS.NodeJS.LTS
winget install Git.Git

安装完成后重新打开 PowerShell，检查：

node --version
npm --version
git --version

如果 Node.js 版本低于 22.19，或版本是 23，请升级到 Node.js 22.19+ 或 24+。

2.2 macOS

可以从 Node.js 官网安装，也可以使用 Homebrew：

brew install node git

检查：

node --version
npm --version
git --version

如果使用 Apple Silicon Mac，Node.js、Ollama 和模型运行时应优先安装 arm64 原生版本；如果使用 Intel Mac，安装 x64 版本。

2.3 Linux

推荐使用 nvm 安装 Node.js，这样不会受 Ubuntu/Debian 软件源中旧 Node.js 版本影响。先安装 Git：

sudo apt update
sudo apt install -y git curl

安装 nvm 后，在当前 shell 中加载它，并安装 Node.js 22：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

不同发行版的 shell 配置文件可能是 _/.zshrc、/.bash_profile 或 ~/.profile；如果 nvm 命令找不到，重新打开终端后再试。

检查：

node --version
npm --version
git --version

Fedora、Arch 等发行版也可以使用系统包管理器安装 Node.js 和 Git，但必须确认 Node.js 满足 22.19+ 或 24+。

2.4 三个平台都需要的依赖

只运行已发布版本，至少需要：

Node.js 22.19+ 或 24+。注意 Node.js 23 不在官方 engines 范围内。
npm（随 Node.js 安装）。
如果用源码方式下载，还需要 Git 和 pnpm。
如果使用本地模型，还需要 Ollama、LM Studio 或 vLLM，以及足够的磁盘空间和显存/内存。

如果使用严格企业环境，建议从各项目官网下载安装包，不要执行来源不明的安装脚本。

2.5 源码开发额外依赖

官方源码当前固定使用 pnpm 11.7.0。首次配置：

corepack enable
pnpm --version

该命令在 Windows PowerShell、macOS zsh 和 Linux Bash 中相同。

如果 Corepack 没有自动解析版本，可以执行：

corepack prepare pnpm@11.7.0 --activate
pnpm --version

源码构建通常不需要单独安装 Python 才能启动 Web UI；Python SDK 和部分开发/测试能力属于额外用途。

3. 跨平台路径和终端命令

3.1 项目目录

同一个 Harness 命令在三个系统上都能使用，只有进入项目目录的写法不同：

平台	进入项目目录示例
Windows PowerShell	Set-Location C:/work/my-project
macOS/Linux	cd ~/work/my-project

路径中包含空格时请加引号，例如 Windows 使用 cd ‘C:/My Projects/demo’，macOS/Linux 使用 cd “$HOME/work/My Projects/demo”。

3.2 设置 DSH_HOME

默认情况下三个平台都使用用户主目录下的 .dsh。如果要把 Harness 数据放到其他磁盘或目录：

Windows PowerShell：

$env:DSH_HOME = 'D:/dsh-data'

macOS/Linux Bash 或 zsh：

export DSH_HOME="$HOME/.dsh-data"

这两个设置只对当前终端会话生效。需要永久生效时，请使用对应系统的用户环境变量设置，或把 export 命令加入 _/.bashrc、/.zshrc 等 shell 配置文件。

3.3 端口和浏览器

三个平台默认都使用：

http://127.0.0.1:3080

如果不希望 Harness 自动打开浏览器，三个平台都使用：

npx -y @deepseek-ai/dsh web --no-open

如果浏览器没有自动打开，手动访问上面的地址即可。停止服务时，三个平台都可以在运行窗口按 Ctrl+C。

4. 方式 A：直接下载并启动已发布版本

这是普通用户最推荐的方式，不需要克隆完整源码仓库。

4.1 在项目目录启动

先进入要操作的项目根目录。例如：

cd C:/work/my-project
npx -y @deepseek-ai/dsh web

官方命令默认启动：

http://127.0.0.1:3080

本机启动时通常会自动打开默认浏览器。使用 --no-open 可以只启动服务器：

npx -y @deepseek-ai/dsh web --no-open

指定端口：

npx -y @deepseek-ai/dsh web --port 3080

启动命令所在的目录会作为默认文件系统位置。打开 Web UI 后还需要点击“选择工作区”，添加并选中该项目目录；没有工作区时，输入框可能不可用。

停止服务：在运行窗口按 Ctrl+C。

4.2 固定版本，避免自动跟随最新预览版

截至本文更新时间，npm latest 为 0.1.1-rc.2。如果希望复现同一版本：

npx -y @deepseek-ai/dsh@0.1.1-rc.2 web --no-open

npx 会把 npm 包下载到 npm 缓存并执行，不会把源码检出到当前项目。第一次运行需要网络。

4.3 直接全局安装命令

也可以安装全局命令：

npm install --global @deepseek-ai/dsh@0.1.1-rc.2
dsh web --no-open

升级时重新执行 npm install --global。如果 Windows 找不到 dsh，关闭并重新打开 PowerShell，或检查 npm 全局 bin 目录是否在 PATH 中。

5. 方式 B：从源码下载、构建和启动

适合需要修改插件、调试源码或跟踪最新提交的情况。

cd C:/work
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

corepack enable
pnpm install
pnpm run build
pnpm dsh web --no-open

源码方式的关键点：

pnpm install 安装 monorepo 依赖。
pnpm run build 准备 Harness 和 Web 前端产物。
pnpm dsh web 使用已构建产物启动，不会替你重新构建。
改动源码后，通常需要再次执行 pnpm run build。

确认源码环境是否搭建完成：

pnpm run typecheck

6. 首次使用 Web UI

启动 web。
浏览器打开 http://127.0.0.1:3080。
点击“选择工作区”，添加项目目录并选中。
打开“设置 → 模型”。
添加或编辑模型提供方。
在模型选择器中选中模型，然后新建会话。

模型变更会在下一次请求时生效，通常不需要重启服务器。已经发出过请求的会话会保留自己的模型记录；切换模型时建议新建会话。

7. 配置 DeepSeek 云端模型

在这里插入图片描述

打开“设置 → 模型”。
找到 DeepSeek 卡片。
输入从 DeepSeek Platform 获取的 API Key。
保存。
在模型选择器中选择可用模型。

API Key 是只写的：页面不会再次收到明文密钥。官方文档说明，凭据存放在 $DSH_HOME/.credentials.yaml，设置文件只保留凭据引用。

不要把真实 Key 写进 README、脚本、Git 仓库或截图中。

8. 配置本地 Ollama 模型

8.1 安装并启动 Ollama

三个平台都可以从 Ollama 官网安装。安装方式可按平台选择：

平台	安装方式
Windows	下载并运行官方安装程序；也可以尝试 winget install Ollama.Ollama
macOS	下载官方 App；Homebrew 用户也可以尝试 brew install ollama
Linux	按 Ollama 官网的 Linux 安装说明安装，并用系统服务或 ollama serve 启动

安装完成后，在对应终端确认命令可用：

ollama --version

下载一个本机实际可用、并且支持工具调用的模型。以下只是示例，模型标签以你安装时的 Ollama 列表为准：

ollama pull qwen2.5-coder:7b
ollama list

如果 Ollama 没有作为后台服务运行，可以启动：

ollama serve

另开一个终端检查 OpenAI 兼容接口。Windows PowerShell：

Invoke-RestMethod http://127.0.0.1:11434/v1/models

macOS/Linux：

curl http://127.0.0.1:11434/v1/models

默认 Ollama OpenAI 兼容地址是：

http://127.0.0.1:11434/v1

8.2 在 Harness 页面添加提供方

打开“设置 → 模型 → 添加自定义提供方”，填写：

字段	示例值
Provider ID	ollama
显示名称	Ollama Local
基础 URL	http://127.0.0.1:11434/v1
API 协议	openai-completions / OpenAI Completions
API Key	留空
模型 ID	ollama list 显示的精确标签，例如 qwen2.5-coder:7b

Provider ID 会被保存会话、默认模型和凭据引用使用，创建后不要随意改名。模型 ID 必须与 ollama list 的值完全一致，包括冒号和版本标签。

如果页面支持“获取可用模型”，可以尝试查询 http://127.0.0.1:11434/v1/models；如果发现接口返回 404 或列表不完整，直接手动添加模型 ID 即可。

8.3 Ollama 不响应或返回 400 时的兼容配置

某些 Ollama 版本或模型对 OpenAI 请求字段的兼容范围较窄。可以在 Harness 的 $DSH_HOME/settings.yaml 中加入以下路由配置：

llm-pi-ai:
  providers:
    ollama:
      api: openai-completions
      baseURL: http://127.0.0.1:11434/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: qwen2.5-coder:7b
          contextWindow: 32768
          maxTokens: 4096

把 qwen2.5-coder:7b 换成 ollama list 的真实模型标签。对于本地模型，contextWindow 和 maxTokens 是部署描述；如果不确定，可以先只写 id，再根据模型实际能力调整。

8.4 使用本地模型时的实际限制

普通聊天不代表完整 agent 能力；Harness 会调用文件、终端和其他工具，优先选择支持 tool calling 的 instruct/coder 模型。
模型越大，对显存/内存和响应速度要求越高。
上下文窗口设置过小会导致长项目任务报上下文超限。
如果本地模型不支持工具调用，可能能回答问题，但无法可靠执行“读文件、改文件、运行测试”等任务。
Ollama 默认监听本机地址即可，不要为了远程访问随意绑定到 0.0.0.0。

9. 配置 LM Studio 或 vLLM

9.1 LM Studio

在 LM Studio 中下载模型并启动本地 Server，常见地址为：

http://127.0.0.1:1234/v1

在 Harness 添加自定义提供方：

Provider ID: lmstudio
Base URL:    http://127.0.0.1:1234/v1
API:         openai-completions
API Key:     留空
Model ID:    以 LM Studio /v1/models 返回的 id 为准

9.2 vLLM

以 vLLM 的 OpenAI 兼容服务器为例：

vllm serve <模型名称> --host 127.0.0.1 --port 8000 --api-key local-key

Harness 配置：

Provider ID: vllm
Base URL:    http://127.0.0.1:8000/v1
API:         openai-completions
API Key:     local-key
Model ID:    与 vLLM 服务端注册的模型 ID 完全一致

如果服务端只接受 max_tokens，在 settings.yaml 的该路由加入：

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens

10. Harness 数据目录和手工配置

Harness 默认使用用户主目录下的 .dsh：

Windows: C:/Users/<用户名>/.dsh
Linux/macOS: ~/.dsh

也可以在当前终端会话中指定数据目录。

Windows PowerShell：

$env:DSH_HOME = 'D:/dsh-data'
npx -y @deepseek-ai/dsh web --no-open

macOS/Linux Bash 或 zsh：

export DSH_HOME="$HOME/.dsh-data"
npx -y @deepseek-ai/dsh web --no-open

常见文件：

$DSH_HOME/settings.yaml       # 模型路由等设置
$DSH_HOME/.credentials.yaml   # 凭据，不要提交到 Git
$DSH_HOME/profiles/           # web/headless 等 profile 数据

$DSH_HOME 是文档里的跨平台写法；实际路径由 DSH_HOME 环境变量或默认用户目录决定。

手工配置自定义 OpenAI 兼容路由的最小形式：

llm-pi-ai:
  providers:
    local-gateway:
      api: openai-completions
      baseURL: http://127.0.0.1:8000/v1
      models:
        - id: local-model

如果端点需要 Key，可以让页面保存凭据，也可以使用环境变量引用：

llm-pi-ai:
  providers:
    local-gateway:
      apiKeyEnv: LOCAL_GATEWAY_API_KEY
      api: openai-completions
      baseURL: http://127.0.0.1:8000/v1
      models:
        - id: local-model

然后在启动 Harness 的同一个终端会话中。Windows PowerShell：

$env:LOCAL_GATEWAY_API_KEY = '你的本地网关密钥'
npx -y @deepseek-ai/dsh web --no-open

macOS/Linux Bash 或 zsh：

export LOCAL_GATEWAY_API_KEY='你的本地网关密钥'
npx -y @deepseek-ai/dsh web --no-open

只有在确实需要认证时才设置 apiKeyEnv。如果本地端点不需要认证，省略该字段；如果写了 apiKeyEnv 却没有提供对应值，Harness 会报 MISSING_CREDENTIAL。

11. 常用 CLI 用法

启动 Web UI：

npx -y @deepseek-ai/dsh web

不打开浏览器：

npx -y @deepseek-ai/dsh web --no-open

查看组合后的配置树：

npx -y @deepseek-ai/dsh --profile web --dump-config

运行一次性 headless 任务：

npx -y @deepseek-ai/dsh --profile headless "总结当前工作区并列出主要文件"

源码 checkout 下对应使用：

pnpm dsh web --no-open
pnpm dsh --profile headless "总结当前工作区"

12. 常见错误排查

MISSING_CREDENTIAL

原因：路由写了 apiKeyEnv，但环境变量或凭据存储中没有对应值。

处理：

云端提供方：在“设置 → 模型”重新保存 Key。
本地无认证服务：删掉该路由的 apiKeyEnv。
本地有认证服务：设置正确的环境变量，或在模型页面输入 Key。

UNKNOWN_MODEL

原因：Harness 的模型 ID 不在当前提供方的模型列表中。

处理：把模型 ID 改成 ollama list、LM Studio /v1/models 或 vLLM 实际使用的精确值。

“获取可用模型”返回 401/404

原因：Key 不正确，或者本地端点没有实现 GET /v1/models。

处理：检查 URL 和认证，并改为手动填写模型 ID。模型发现失败不等于聊天接口一定不可用。

Key 和 URL 都正确，但网关每次都返回 400

原因：网关虽然是 OpenAI 兼容接口，但请求字段形状与 Harness 推断的不一致。

先尝试：

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens

图片发送前被拒绝

自定义模型默认按纯文本处理。只有确认端点支持图片时，才在模型项中声明：

models:
  - id: vision-model
    input: [text, image]

不要为了绕过校验而给纯文本模型声明图片能力。

Web UI 能打开，但不能输入

先点击“选择工作区”并添加项目目录；全新的 Web UI 默认不会自动选中工作区。

运行源码时构建失败

按顺序检查：

node --version
corepack enable
pnpm --version
pnpm install
pnpm run build

源码仓库当前要求 Node.js 22.19+ 或 24+，并使用 pnpm 11.7.0。

13. 推荐的最短验证流程

如果目标是“本地 Harness + Ollama 本地模型”，三个平台都按下面顺序验证。

Windows PowerShell：

# 终端 1：确认本地模型已下载
ollama list

# 终端 2：确认 Ollama API 正常
Invoke-RestMethod http://127.0.0.1:11434/v1/models

# 终端 3：从项目目录启动 Harness
cd C:/work/my-project
npx -y @deepseek-ai/dsh@0.1.1-rc.2 web --no-open

macOS/Linux Bash 或 zsh：

# 终端 1：确认本地模型已下载
ollama list

# 终端 2：确认 Ollama API 正常
curl http://127.0.0.1:11434/v1/models

# 终端 3：从项目目录启动 Harness
cd ~/work/my-project
npx -y @deepseek-ai/dsh@0.1.1-rc.2 web --no-open

然后在 http://127.0.0.1:3080 中：