---
title: "安装 DeepSeek Harness 并启动 DSH Web UI"
seo_title: "DeepSeek Harness 安装教程：用 npx 启动 DSH Web UI"
description: "从 Node.js 环境检查开始，使用 npx 启动 DeepSeek Harness（DSH）Web UI，并完成端口、Workspace、模型和第一次只读任务验证。"
canonical: https://52dsh.com/tutorials/deepseek-harness-install-web-ui/
authors: ["52DSH 编辑部"]
audience: ["第一次安装 DeepSeek Harness 的用户","需要重新确认 DSH Web UI 启动流程的开发者"]
outcomes: ["Web UI 在本机地址正常打开","Workspace 与模型选择状态明确","完成一次不修改文件的只读任务"]
prerequisites: ["可使用系统终端"]
difficulty: beginner
estimated_action_time: "10～20 分钟"
next_steps: {"success":["/errors/dsh-workspace-not-selected/","/tutorials/deepseek-harness-model-provider/","/tutorials/dsh-complete-guide/"],"failure":["/errors/web-ui-start-failed/","/errors/dsh-port-3080-in-use/"]}
published_at: 2026-08-18
updated_at: 2026-09-30
verified_on: 2026-09-30
maintenance_status: community
verification_level: source_reviewed
risk_level: medium
dsh_version: 0.2.0-rc.2
plugin_id: null
tutorial_kind: null
related_plugin_url: null
---

# 安装 DeepSeek Harness 并启动 DSH Web UI

从 Node.js 环境检查开始，使用 npx 启动 DeepSeek Harness（DSH）Web UI，并完成端口、Workspace、模型和第一次只读任务验证。

## 当前基线与首次验证

2026-09-30 复核：默认精确版本为 `0.2.0-rc.2`，仍为候选版；相对 0.1.7-rc.2 没有新的会话或设置迁移；官方 Node 范围为 `^22.19.0 || >=24.0.0`，与 0.1.5、0.1.7 系列相同。`dsh web`、`--port`、`--no-open` 的用法和默认地址 `http://127.0.0.1:3080` 都没有变化。本文命令依据[固定 CLI](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/apps/cli/reference/README.zh.md)审阅，未执行安装或真实模型调用。

新会话默认模型为 `deepseek-flash`，已有显式模型配置优先，不需要为跟随教程覆盖原设置。先在模型页确认实际 Provider 和模型，再做无敏感信息的简单任务；上传文件不代表已被读取。功能变化见[0.2.0-rc.2 官方发行说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.0-rc.2)。

## 已有环境先确认数据与版本

本页使用固定 `0.2.0-rc.2` 命令，不依赖 latest 或 next 的滚动指向。已经在用 0.1.7 系列的环境，升级到 0.2.0 没有新的会话或设置迁移，仍建议先按维护页保存备份。**已经在用 0.1.5 系列、有会话或插件的环境，不要直接运行本页命令**：0.1.7 会把会话迁移为 V4 格式，旧程序不能降级读取；旧 `settings.yaml` 会被改名后逐项导入；模型配置里的 `protocol` 字段会导致官方适配器拒绝加载。先按[升级前必读](/tutorials/dsh-update-uninstall/#017-alpha1升级前先检查数据与设置)保存匹配的程序、配置和数据副本；单独 Profile 不自动隔离所有存储。能安装不代表第三方插件兼容。需要了解首次引入 Session V3 时的迁移限制，可读[alpha.1 历史版本说明](/tutorials/deepseek-harness-0-1-5-alpha-1/)。

## 最短安装方式

截至 2026-09-30，npm `latest` 与 `next` 均为 `0.2.0-rc.2`。为让本页操作与固定源码一致，使用精确版本启动：

```bash
npx @deepseek-ai/dsh@0.2.0-rc.2 web
```

官方也提供未锁版本的 `npx @deepseek-ai/dsh web`；它会受 npm 分发、本地安装和缓存状态影响。先记录终端显示的实际版本，不把本文版本当作本机检测结果。默认地址为 `http://127.0.0.1:3080`。成功结果是页面打开、Workspace 与模型明确，并完成只读任务。本站完成的是固定源码审阅，未执行 DSH 安装实测。

## 采用默认安装基线还是评估预发布版

| 你的目标 | 推荐路径 | 版本边界 |
|---|---|---|
| 第一次打开 DSH | 本页锁定 `0.2.0-rc.2` 的命令 | npm 默认通道已切换，RC 仍不是正式稳定版 |
| 已有 0.1.5 系列环境与重要会话 | 先读[升级前必读](/tutorials/dsh-update-uninstall/#017-alpha1升级前先检查数据与设置)；暂不升级可继续使用 `0.1.5-rc.3` | V4 不支持降级读取，先保留匹配环境和数据副本 |
| 维护旧插件 | 保留原 DSH 与插件组合，逐项核对 | 网站默认版更新不代表第三方插件自动兼容 |

rc.1 已包含网络访问的一次性 token 认证。按终端输出的启动链接访问；不要公开 token 或把 Web 直接暴露到公网。切换版本前阅读[更新与回退指南](/tutorials/dsh-update-uninstall/)。

## 第一步：检查 Node.js 版本

根包声明的 Node.js 范围是 `^22.19.0 || >=24.0.0`。执行：

```bash
node --version
npx --version
```

符合条件的例子包括 Node 22.19.0 及之后的 22.x，以及 Node 24 或更高版本。Node 23 不在官方声明范围内。预期结果是两个命令都能显示版本号，且 Node 位于支持范围；否则先处理运行时，不要把命令缺失误判成 DSH 故障。

## 第二步：选择启动目录并打开 Web UI

进入一个准备作为默认 Workspace 根位置的测试项目目录，再启动 DSH：

```bash
cd /path/to/your-project
npx @deepseek-ai/dsh@0.2.0-rc.2 web
```

Windows PowerShell、macOS 和 Linux 的核心命令一致，路径写法按各自终端调整。本机启动会尝试打开默认浏览器，也可以手动访问 `http://127.0.0.1:3080`。终端保持运行且页面能加载，就是这一步的预期结果。

地址打不开时先保存第一条和最后一条错误，进入[DSH Web UI 启动失败总诊断](/errors/web-ui-start-failed/)；若明确提示 3080 已被使用，进入[3080 端口占用修复](/errors/dsh-port-3080-in-use/)。

## 第三步：添加并选择 Workspace

0.1.7 起，**全新安装第一次启动**会自动创建默认工作区 `Documents/deepseek-harness/default-workspace`（远程 Web 是服务器账户的 Documents），并选中一个空白会话，不需要先选文件夹。已经登记过工作区、或存在会话记录的环境不会自动创建。预期结果是输入区可以直接输入；准备在其他项目目录里工作时，再在界面中添加并选择那个明确允许 Agent 访问的目录。触发条件、目录位置和失败时的手动步骤见[首次默认工作区](/errors/dsh-workspace-not-selected/#017-alpha1首次默认工作区何时生效)。

0.1.5 系列（包括 `0.1.5-rc.3`）不会自动选中 Workspace：启动目录只是默认文件系统位置，需要在界面中添加并选择项目目录，输入区才会从不可用变为可以输入。

页面已打开但输入框灰色或不能输入时，不要反复重启服务器，直接按[Workspace 未选择修复](/errors/dsh-workspace-not-selected/)核对 Workspace、Session 和启动目录的区别。

## 第四步：配置模型与 Provider

进入 `设置 → 模型`，配置对应 Provider 的凭据并保存，再从会话模型选择器选择模型。从 0.1.5 系列升级的环境，如果配置里写过 `protocol` 或 `baseURL: https://api.deepseek.com`，先看[模型配置的 0.1.7 小节](/tutorials/deepseek-harness-model-provider/#017-rc1官方适配器只用-messages)。保存凭据不等于当前会话已经选中模型；预期结果是模型选择器显示明确的 Provider 和模型，最小文本请求能够获得回答。

遇到 `MISSING_CREDENTIAL`、`UNKNOWN_MODEL` 或 401 时，进入[DSH 模型、API Key 与 Provider 配置](/tutorials/deepseek-harness-model-provider/)。不要把真实 API Key 粘贴进聊天、截图或公开日志。

## 第五步：完成第一次只读任务

在专用测试 Workspace 中发送：

```text
只列出当前工作区的一级文件和目录，不要修改文件，不要运行安装命令。
```

“不要修改”是任务要求，不是强制只读沙箱。需要限制写入时先按[权限与沙箱指南](/tutorials/dsh-permissions-sandbox/)核对实际策略，再执行测试。核对返回内容只涉及预期目录，没有文件变化，也没有出现新的凭据或权限请求。然后再进入[DeepSeek Harness 中文入门](/tutorials/dsh-complete-guide/)学习 Session、权限和后续任务。

## 修改端口

默认 3080 已被占用时，可以指定另一个本地端口：

```bash
npx @deepseek-ai/dsh@0.2.0-rc.2 web --port 8080
```

然后访问 `http://127.0.0.1:8080`。官方 CLI 当前有意拒绝 `--host 0.0.0.0`；`--trusted-host` 增加的是浏览器 API 接受的具名 authority，并不等价于开放监听地址。

## npx 启动与源码开发不是同一路径

npx 适合直接使用已发布的 DSH。只有准备参与开发或审计源码时，才按官方源码流程执行：

```bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
git checkout dsh-v0.2.0-rc.2
pnpm install
pnpm run build
pnpm dsh web
```

源码运行需要 pnpm 和构建产物；普通 npx 快速启动不会替你建立源码开发环境。CLI 的插件管理命令同样会把参数转发给 pnpm，准备安装第三方插件时还需阅读[DSH 插件安装与管理](/plugins/dsh-plugin-profile-guide/)。

## 原始来源

- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.0-rc.2
- https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/package.json
- https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.7-rc.2
- https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/package.json
- https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/packages/api/workspace-controller/src/default-workspace.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/46a7f68b0922371ce7144b668b90e377d8e799f4/.agents/notes/implemented/feature/2026-09-20-default-workspace.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/46a7f68b0922371ce7144b668b90e377d8e799f4/packages/api/workspace-controller/src/default-directory.ts
- https://github.com/deepseek-ai/deepseek-harness/compare/dsh-v0.1.5-rc.2...dsh-v0.1.5-rc.3
- https://github.com/deepseek-ai/deepseek-harness/blob/a4c74a91e06b00fe0b0937bde982170c526cc842/package.json
- https://github.com/deepseek-ai/deepseek-harness/blob/a4c74a91e06b00fe0b0937bde982170c526cc842/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.2
- https://github.com/deepseek-ai/deepseek-harness/blob/fb2c4b9e698e30edb738bca4cf0618587db7d203/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/fb2c4b9e698e30edb738bca4cf0618587db7d203/package.json
- https://github.com/deepseek-ai/deepseek-harness/blob/fb2c4b9e698e30edb738bca4cf0618587db7d203/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-alpha.1
- https://github.com/deepseek-ai/deepseek-harness/blob/5dda764ed3aa172535a7967b06ff95d9cbfe536a/packages/session/session-format-v2-to-v3/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/5dda764ed3aa172535a7967b06ff95d9cbfe536a/packages/session/session-persistence-jsonl/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.3-alpha.1
- https://github.com/deepseek-ai/deepseek-harness/blob/fb2c4b9e698e30edb738bca4cf0618587db7d203/package.json
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.2-alpha.1
- https://registry.npmjs.org/@deepseek-ai%2Fdsh/latest
- https://github.com/deepseek-ai/deepseek-harness/blob/fb2c4b9e698e30edb738bca4cf0618587db7d203/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/fb2c4b9e698e30edb738bca4cf0618587db7d203/package.json
- https://github.com/deepseek-ai/deepseek-harness/blob/fb2c4b9e698e30edb738bca4cf0618587db7d203/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/fb2c4b9e698e30edb738bca4cf0618587db7d203/docs/user/guide/index.zh.md