安装并启动本地 Web 控制台

约 30 分钟

在满足 Node.js 版本要求的机器上执行 npx @deepseek-ai/dsh web 启动 dsh，并验证本地 Web 控制台可访问。

DeepSeek Harness（简称 dsh）是深度求索于 2026 年 8 月开源的 Agent 运行时，MIT 许可证，代码以 TypeScript 编写。它采用“一切皆插件”的开放架构：模型、工具、会话、存储与 Agent 循环都可以自由替换。项目当前处于 developer preview，官方明确提示兼容性破坏的变更随时可能发生。

接下来要完成的目标只有一个：在满足 Node.js 版本要求的机器上，用 npx @deepseek-ai/dsh web 启动 dsh，并在浏览器确认本地控制台可访问。启动命令来自 dsh-cli，浏览器里打开的是 web-ui，两个概念随后定义。先核对 Node.js 版本，再启动，最后在浏览器里验证。若打印的地址与你看到的不一致，以启动器实际输出的为准。

核心概念

dsh-cli：命令行入口

把 Agent 想成一架无人机：模型是飞控芯片，负责决策；dsh 是机身，负责提供工具、文件与会话；dsh-cli 则是遥控器上的开机键——一条命令把整架机器带起来。

技术定义：dsh-cli 是 DeepSeek Harness 的命令行程序，通过 npm 包 @deepseek-ai/dsh 分发，web 与 headless 是随包提供的两种 profile 模板。npx @deepseek-ai/dsh web 会按需拉取包并启动默认的 Web 控制台模式，不需要全局安装。dsh 当前处于 developer preview，版本不保证兼容稳定，这也是后面要锁定版本的原因。

核心概念

web-ui：本地控制台

把控制台想成汽车仪表盘：引擎在车头，你操作的是方向盘与仪表——web-ui 就是 dsh 的仪表盘，显示状态、接受指令。

技术定义：web-ui 是 dsh 的默认浏览器界面，由 dsh web 启动，默认监听 http://127.0.0.1:3080。首屏先显示 preview（预览版）提示，再给出 API 密钥设置入口，并提供工作区、模型与预设等控件。它只是控制面，不代表本地推理：默认 DeepSeek 适配器把请求发送给需要凭据的远程 API，界面在本机、模型在远端。

启动前先核对 Node.js 版本。打开终端执行：

bash
node --version

dsh 要求 Node.js 满足 ^22.19.0 或 >=24.0.0。注意：即使 npx 本身能运行，过旧的 Node.js 也可能不满足包的引擎（engine）要求，启动时直接报错。版本不达标就先升级 Node.js，再继续。

选一个空目录作为启动目录——默认文件系统位置就是你启动 dsh 的那个目录，工作区与会话数据都落在附近。用一次性目录练习，避免 Agent 碰到真实项目。多数启动问题来自三处：Node 版本不达标、包版本漂移、端口被占用。先核对这三样，能省掉大部分排查。

首次启动时，页面会按顺序出现这些入口：preview 提示 → API 密钥设置 → 工作区选择 → 模型选择 → Agent 预设。配置 API 凭据属于下一步，现在只需要确认这些入口确实出现在页面上。只要看到 preview 提示与 API 密钥设置入口，就说明控制台已经可访问。

启动并验证本地控制台

  1. 1

    核对 Node.js 版本，确认满足 ^22.19.0 或 >=24.0.0。

    bash
    node --version
  2. 2

    在一个空目录里执行启动命令，启动 web 模式。

    bash
    npx @deepseek-ai/dsh web
  3. 3

    可选：锁定已验证版本，避免后续发布引入破坏性变更。

    bash
    npx @deepseek-ai/[email protected] web
  4. 4

    等待启动器打印本地地址。

    text
    dsh web: http://127.0.0.1:3080
  5. 5

    若浏览器未自动打开，手动访问 http://127.0.0.1:3080。

  6. 6

    观察首屏：先出现 preview 提示与 API 密钥设置入口，再确认工作区、模型与预设等控件存在。

你应该看到

浏览器打开本地控制台，地址栏为 http://127.0.0.1:3080，页面显示 preview 提示、API 密钥设置入口，以及工作区、模型与预设等首屏控件。尚未配置 API 密钥不影响“控制台可访问”的验证，凭据配置在下一步完成。

遇到问题：执行启动命令后报错，或浏览器打不开 http://127.0.0.1:3080。

可能原因

  • Node.js 版本不满足 ^22.19.0 或 >=24.0.0；过旧的版本即使能运行 npx，也可能不满足包引擎要求。
  • 使用了无作用域的包名或同名第三方项目的安装方式，装到了错误的包。
  • 端口 3080 已被其他进程占用。

排查步骤

  1. 运行 node --version 核对版本；不达标则升级 Node.js 到 ^22.19.0 或 >=24.0.0 后重试。
  2. 确认命令是 npx @deepseek-ai/dsh web，包名带 @deepseek-ai 作用域。
  3. 端口被占用时换端口启动（例如 --port 3081），随后访问对应地址；或先结束占用 3080 的进程。
  4. 浏览器未自动打开时，手动输入 http://127.0.0.1:3080。
自检：启动 dsh 本地控制台的命令是什么？默认监听地址和 Node.js 版本要求分别是什么？

命令是 npx @deepseek-ai/dsh web。默认监听 http://127.0.0.1:3080。Node.js 需满足 ^22.19.0 或 >=24.0.0。首次启动显示 preview 提示与 API 密钥设置入口，并提供工作区、模型与预设控件。