DeepSeek Harness 安装教程：一条命令跑起官方 Agent 框架

很多人把 DeepSeek Harness 和 Hermes Agent 搞混——它们是两回事。Hermes Agent 来自 Nous Research，是开源 AI Agent 领域的老牌玩家；DeepSeek Harness 是 DeepSeek 官方在发布 V4 模型时同步推出的开源 Agent 框架，主打「一切皆插件」架构。发布两天内在 GitHub 斩获约 11.3 万星，目前已经超过 13.6 万星。本文介绍 DeepSeek Harness 的安装方式。

什么是 DeepSeek Harness

DeepSeek Harness 是 DeepSeek 官方推出的开源 Agent 运行时环境，底层框架叫 Cordis。官方 README 的描述是：「Powered by Cordis」，而 Cordis 源自一篇名为《A Programming Paradigm for Spatiotemporal Composability》的论文。

它的核心理念是「一切皆插件」：模型是插件、工具是插件、记忆是插件、会话管理是插件、搜索是插件、子 Agent 是插件、调度是插件，甚至连 Agent 的主循环本身也是插件。这意味着你不喜欢任何一个组件，都可以替换掉而不碰核心。

前置要求

安装前确保准备好：

Node.js ^22.19.0 或 >= 24.0.0（可通过 node -v 检查版本）
一条命令即可完成安装
DeepSeek API Key（用于调用模型，可在 platform.deepseek.com/api_keys 获取）

操作系统支持 macOS、Linux 和 Windows，Windows 用户建议使用 PowerShell。

方式一：npx 一键安装（推荐）

这是官方推荐的快速上手方式，一条命令完成下载和启动，不需要克隆仓库、不需要编译：

npx @deepseek-ai/dsh web

首次运行会自动初始化 Web 配置，在终端看到服务地址：

http://127.0.0.1:3080

浏览器会自动打开这个地址，如果没有自动跳转请手动访问。

方式二：从源码构建

如果你想阅读代码、开发插件或参与贡献，需要从源码构建：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install
pnpm run build
pnpm dsh web

注意：corepack enable 这步很多人会跳过，但它是启用 pnpm 11.7.0 的关键，缺少这步可能会导致构建失败。

首次配置步骤

安装完成后，按以下顺序完成初始配置：

选择 Workspace：点击「Choose workspace」，选择项目目录（建议选择你想让 Agent 操作的文件夹）
配置模型：进入 Settings → Models，填入 DeepSeek API Key 并保存
开始使用：配置完成后就可以开始对话

注意：Workspace 必须在启动 dsh 的目录下选择，这一点很多人容易搞错——如果 Agent 说找不到文件，首先检查是否从正确的目录启动了 dsh。

常用命令一览

命令	说明
npx @deepseek-ai/dsh web	启动 Web UI（默认 3080 端口）
dsh –profile web –port 8080	自定义端口启动
dsh –help	查看所有可用命令

插件生态

DeepSeek Harness 的插件生态是它真正的护城河。发布一天内社区就发布了 421 个插件，涵盖搜索、文件处理、代码执行、Web 访问等各种能力。插件可通过 cordis.yml 配置加载，官方也有专门的插件开发文档。

官方 Discovery 机制是 GitHub 上的 dsh-plugin topic，所有插件都收录在那里。

常见问题

DeepSeek Harness 免费吗？

框架本身免费，GitHub 开源。模型调用费用由你使用的 API 提供商决定，用 DeepSeek API 则按 DeepSeek 官方定价计费。

Web UI 加载正常但会话报错 MISSING_CREDENTIAL 或 UNKNOWN_MODEL？

这不是安装问题，是模型配置问题。进入 Settings → Models 确认 API Key 已正确填入。

Windows 用户需要注意什么？

从 0.1.0-rc.8 版本起，Windows 用户有了原生的持久化 PowerShell 工具，不再只支持 bash。确保 Node 在 PATH 中即可。

Harness 和 Hermes Agent 有什么区别？

两者都是开源 Agent 框架，但定位不同。Hermes Agent 来自 Nous Research，有跨平台消息集成（支持 Telegram、WhatsApp、Discord、Teams 等）和自学习记忆系统；DeepSeek Harness 主打可插拔架构和插件生态，开发者友好度更高。

小结

DeepSeek Harness 用一条 npx 命令就能跑起来，安装难度几乎为零。它真正的门槛在于理解「一切皆插件」的设计理念，以及如何组合插件构建适合自己需求的 Agent 工作流。随着插件生态的成熟，这套架构的扩展空间值得关注。

参考来源：DeepSeek Harness 官方安装指南 | GitHub – deepseek-ai/deepseek-harness

延伸阅读

AI 自学笔记 每天更新 AI 前沿动态，订阅 RSS，或按 Ctrl/⌘+D 收藏本站，明天见。