---
title: "安装 DeepSeek Harness 并启动 DSH Web UI"
seo_title: "DeepSeek Harness 安装教程：用 npx 启动 DSH Web UI"
description: "从 Node.js 24.9 环境检查开始，使用 npx 启动 DeepSeek Harness（DSH）0.2.2-rc.1 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: ["可使用系统终端","Node.js 24.9.0 或更高版本"]
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-11-06
verified_on: 2026-11-06
maintenance_status: community
verification_level: source_reviewed
risk_level: medium
dsh_version: 0.2.2-rc.1
plugin_id: null
tutorial_kind: null
related_plugin_url: null
---

# 安装 DeepSeek Harness 并启动 DSH Web UI

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

## 当前基线与首次验证

不想安装 Node.js，或者更习惯桌面应用，可以改用官方桌面端（macOS Apple Silicon 与 Windows x64），见[桌面端安装与使用](/tutorials/dsh-desktop-app-guide/)。本页介绍的是用 npx 在浏览器中运行的 Web 版。

2026-11-06 复核：npm `latest` 与 `next` 均为 **0.2.2-rc.1**，仍为候选版。本页使用固定提交 `66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db` 的根包、CLI 与凭据资料，未安装或运行 DSH。Web 默认地址仍是 `http://127.0.0.1:3080`。

**Node.js 要求已提高到 24.9.0 或更高。** rc.5 还接受 Node 22.19 起的 22.x；0.2.2-rc.1 的[根包](https://github.com/deepseek-ai/deepseek-harness/blob/66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db/package.json)与 [CLI 包](https://github.com/deepseek-ai/deepseek-harness/blob/66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db/apps/cli/package.json)都声明 `>=24.9.0`。Node 22 环境直接运行未锁版本的 `npx @deepseek-ai/dsh web`，现在会取得 0.2.2-rc.1，先升级运行时再启动；处理方法见 [Node 版本错误](/errors/dsh-node-version-error/)。

从 0.2.1 或 0.2.0 系列升级时，先核对 Node、第三方插件和 Profile 组合包，见[0.2.2-rc.1 默认版本升级检查](/tutorials/dsh-update-uninstall/#022-rc1默认版本升级检查)。Web 已保存的同名 Key 仍优先于启动环境，保存配置不等于请求成功；官方端点的 API Key 模型目录会按条件从服务端更新，不要把旧的固定模型表当作当前账号权限。

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

本页使用固定 `0.2.2-rc.1` 命令，不依赖 latest 或 next 的滚动指向。已经在用 0.1.7、0.2.0 或 0.2.1 系列的环境，先按维护页核对当前版本的凭据、Profile、数据与插件边界并保存匹配备份；官方没有承诺 0.2.2-rc.1 写入的数据可由旧版直接读取，不要把切回旧命令当作完整回退。**已经在用 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-11-06，npm `latest` 与 `next` 均为 `0.2.2-rc.1`。为让本页操作与固定源码一致，使用精确版本启动：

```bash
npx @deepseek-ai/dsh@0.2.2-rc.1 web
```

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

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

| 你的目标 | 推荐路径 | 版本边界 |
|---|---|---|
| 第一次打开 DSH | 本页锁定 `0.2.2-rc.1` 的命令 | 需要 Node.js ≥24.9.0；RC 仍不是正式稳定版 |
| 暂时不能升级 Node 22 | 保留 `npx @deepseek-ai/dsh@0.2.1-rc.5 web`，按[更新与回退](/tutorials/dsh-update-uninstall/#021-rc5默认版本升级检查)维护 | 旧版不再是 npm 默认版本，新功能和修复不会回补 |
| 已有 0.1.5 系列环境与重要会话 | 先读[升级前必读](/tutorials/dsh-update-uninstall/#017-alpha1升级前先检查数据与设置)；暂不升级可继续使用 `0.1.5-rc.3` | V4 不支持降级读取，先保留匹配环境和数据副本 |
| 维护旧插件 | 保留原 DSH 与插件组合，逐项核对 | 网站默认版更新不代表第三方插件自动兼容 |

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

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

0.2.2-rc.1 根包声明的 Node.js 范围是 `>=24.9.0`。执行：

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

符合条件的是 Node 24.9.0 及之后的版本。Node 22.x、Node 23 和 24.9.0 之前的 24.x 都不在声明范围内；这些版本只能继续运行仍接受它们的旧 DSH 版本。预期结果是两个命令都能显示版本号，且 Node 位于支持范围；否则先处理运行时，不要把命令缺失误判成 DSH 故障。

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

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

```bash
cd /path/to/your-project
npx @deepseek-ai/dsh@0.2.2-rc.1 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.2-rc.1 web --port 8080
```

然后访问 `http://127.0.0.1:8080`。官方 CLI 当前有意拒绝 `--host 0.0.0.0`；`--trusted-host` 增加的是浏览器 API 接受的具名 authority，并不等价于开放监听地址。0.2.2-rc.1 自带的网页抓取可以访问本机与内网地址，在共享服务器或能访问内网的机器上启动前，先看[网页抓取边界](/tutorials/dsh-web-search-fetch-guide/)。

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

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

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

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

## 原始来源

- https://github.com/deepseek-ai/deepseek-harness/blob/66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db/package.json
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.2-rc.1
- https://github.com/deepseek-ai/deepseek-harness/blob/66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db/apps/cli/package.json
- https://github.com/deepseek-ai/deepseek-harness/blob/66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db/packages/credentials/credentials-local/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.1-rc.5
- https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/package.json
- https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/credentials/credentials-local/README.zh.md
- 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
