DeepSeek Harness 安装配置教程

DeepSeek Harness（DSH）是 DeepSeek AI 开源的 Agent 运行框架，支持大模型读写本地文件、执行命令和任务拆分。以下是详细的安装配置流程。

一、环境准备

1.1 Node.js 环境安装

DeepSeek Harness 基于 Node.js 开发，需要 Node.js v22.19.0 或更高版本。

Windows 系统推荐使用 nvm 管理 Node.js 版本：

powershell 复制代码

# 1. 安装 nvm-windows
# 从 https://github.com/coreybutler/nvm-windows/releases 下载 nvm-setup.exe 安装

# 2. 安装 Node.js v22.19.0
nvm install 22.19.0

# 3. 使用指定版本
nvm use 22.19.0

# 4. 验证安装
node --version  # 应显示 v22.19.0
npm --version   # 应显示对应版本

macOS/Linux 系统：

bash 复制代码

# 使用 fnm 或 nvm 管理 Node.js
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 22.19.0
fnm use 22.19.0

1.2 环境验证

bash 复制代码

# 检查 Node.js 和 npm 版本
nodev  # 应 >= 22.19.0
npm -v   # 应 >= 10.0.0

# 检查 Python（某些插件可能需要）
python --version

二、安装 DeepSeek Harness

2.1 快速启动方式（推荐）

使用 npx 直接运行，无需全局安装：

bash 复制代码

npx @cordisjs/harness

首次运行会自动下载依赖并启动服务，访问地址：http://127.0.0.1:3080 。

2.2 全局安装方式

如需频繁使用，可全局安装：

bash 复制代码

# 全局安装
npm install -g @cordisjs/harness

# 启动服务
dsh
# 或
harness

2.3 桌面版安装（macOS/Windows）

对于桌面用户，可下载桌面客户端：

平台	下载文件	安装方式
macOS	DeepSeek Harness Desktop.dmg	拖拽到 Applications 文件夹
Windows	DeepSeek Harness Desktop Setup.exe	双击运行安装向导

桌面版启动后会在系统托盘显示图标，点击可打开 Web 界面。

三、API 配置

3.1 获取 DeepSeek API Key

访问 DeepSeek 开放平台
注册/登录账号
进入 "API Keys" 页面
点击 "Create new API key" 生成密钥

3.2 配置模型供应商

在 Harness Web 界面（http://127.0.0.1:3080）进行配置：

yaml 复制代码

# 配置示例结构
providers:
 name: deepseek
    type: openai
    config:
      apiKey: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      baseURL: "https://api.deepseek.com"

具体操作步骤：

打开 Harness 设置面板
进入 "模型供应商" 或 "Providers" 选项卡
点击 "添加供应商" 或 "Add Provider"
选择 "OpenAI 兼容" 类型
填写配置信息：

配置项	值	说明
供应商名称	deepseek	自定义标识名称
API 类型	OpenAI Compatible	选择 OpenAI 兼容
Base URL	`https://api.deepseek.com`	DeepSeek API 地址
API Key	`sk-xxxxxxxxxx`	从平台获取的密钥
模型列表	deepseek-chat, deepseek-coder	可用模型名称

3.3 配置第三方 API 供应商（可选）

Harness 支持 30+ 大模型提供商，如 llapi.org、OpenRouter 等：

yaml 复制代码

# llapi.org 配置示例
 name: llapi
  type: openai
  config:
    apiKey: "your-llapi-key"
    baseURL: "https://api.llapi.org/v1"

四、工作区与插件配置

4.1 创建工作区

bash 复制代码

# 在 Harness 界面中操作：
# 1. 点击 "工作区" 或 "Workspace"
# 2. 选择 "创建新工作区"
# 3. 设置工作区名称和路径
# 4. 配置默认模型供应商

4.2 插件管理

Harness 采用 Cordis 插件架构，支持功能扩展：

javascript 复制代码

// 插件安装示例
// 在 Harness 插件市场或通过命令行安装

# 查看可用插件
dsh plugin list

# 安装文件操作插件
dsh plugin install @cordisjs/plugin-filesystem

# 安装命令执行插件
dsh plugin install @cordisjs/plugin-commands

4.3 OpenClaw 图形化配置（可选）

对于复杂配置，可使用 OpenClaw 辅助工具：

bash 复制代码

# 安装 OpenClaw
npm install -g openclaw

# 启动配置向导
openclaw config

五、服务测试与验证

5.1 启动服务验证

bash 复制代码

# 启动 Harness 服务
npx @cordisjs/harness

# 或使用桌面版直接启动
# 检查服务状态
curl http://127.0.0.1:3080/health

5.2 API 连接测试

在 Harness 界面中：

进入 "测试" 或 "Playground" 选项卡
选择配置的模型供应商
发送测试消息，如 "Hello, world!"
验证是否收到正常响应

5.3 任务派发测试

javascript 复制代码

// 示例任务：文件读取
任务描述：读取当前目录下的 README.md 文件并总结内容

// Harness 应能自动调用文件系统插件执行

六、常见问题解决

问题	原因	解决方案
端口 3080 被占用	其他服务占用端口	修改 Harness 配置端口或停止冲突服务
API Key 无效	密钥错误或过期	重新生成 API Key 并更新配置
Node.js 版本过低	版本 < 22.19.0	使用 nvm/fnm 升级 Node.js
插件加载失败	网络或权限问题	检查网络连接，以管理员权限重试
桌面版无法启动	系统兼容性问题	确认系统版本，尝试兼容模式运行

七、高级配置

7.1 自定义配置文件

创建 harness.config.js 进行高级配置：

javascript 复制代码

// harness.config.js
module.exports = {
  port: 3080,
  host: '127.0.0.1',
  providers: [
    {
      name: 'deepseek',
      type: 'openai',
      config: {
        apiKey: process.env.DEEPSEEK_API_KEY,
        baseURL: 'https://api.deepseek.com'
      }
    }
  ],
  plugins: [
    '@cordisjs/plugin-filesystem',
    '@cordisjs/plugin-commands'
  ]
};

7.2 环境变量配置

bash 复制代码

# 设置环境变量（Linux/macOS）
export DEEPSEEK_API_KEY="skxxxxxxxxxx"

# Windows PowerShell
$env:DEEPSEEK_API_KEY="sk-xxxxxxxxxx"

# 启动时引用环境变量
npx @cordisjs/harness --config ./harness.config.js

7.3 服务自启动配置

bash 复制代码

# 使用 systemd（Linux）
sudo nano /etc/systemd/system/deepseek-harness.service

# 服务文件内容
[Unit]
Description=DeepSeek Harness Service
After=network.target

[Service]
Type=simple
User=yourusername
WorkingDirectory=/path/to/harness
Environment="DEEPSEEK_API_KEY=sk-xxxxxxxxxx"
ExecStart=/usr/bin/npx @cordisjs/harness
Restart=always

[Install]
WantedBy=multi-user.target

八、安全注意事项

API Key 保护：不要将 API Key 提交到版本控制系统，使用环境变量管理
本地运行风险：Harness 具有文件读写和命令执行权限，仅在自己信任的环境运行
网络隔离：生产环境建议在防火墙后运行，限制外部访问
定期更新：关注官方更新，及时升级版本获取安全修复

安装完成后，即可通过 Web 界面创建 AI Agent，配置工具插件，开始使用 DeepSeek 大模型进行任务自动化处理。