---
url: https://limapi.com/docs/agents/deepseek-harness.md
---
# DeepSeek Harness

DeepSeek Harness（dsh）是 DeepSeek 开源的 Agent 框架，采用「一切皆插件」架构，提供 Web UI、headless 命令行、SDK 等多种使用形态。通过添加自定义 OpenAI 兼容提供方，可接入 LimAPI 使用平台上的全部模型。

## 安装 DeepSeek Harness

1. DeepSeek Harness 需要 Node.js 22.19.0 或更高版本。可通过以下命令检查 Node.js 版本：

```bash
node -v
```

2. 无需全局安装，在终端中通过 npx 直接启动 Web UI：

```bash
npx @deepseek-ai/dsh web
```

命令执行后，Web UI 默认运行在 http://127.0.0.1:3080 并自动在浏览器打开；如只需启动服务不打开浏览器，追加 `--no-open` 参数。

> 也可以从源码安装：`git clone https://github.com/deepseek-ai/deepseek-harness.git` 后依次执行 `pnpm install`、`pnpm run build`，再运行 `pnpm dsh web` 启动。

## 配置接入凭证

| 配置项 | 说明 |
| --- | --- |
| API Key | [Portal](https://limapi.com/) 创建的 LimAPI API Key（`sk-` 开头） |
| Base URL | `https://limapi.com/api/v1`（OpenAI 兼容端点） |
| API 协议 | `openai-completions` |
| 可用模型 | 平台支持的任意模型，完整列表通过 `GET /api/v1/models` 查询或在 Portal 模型广场查看 |

**方式一：Web UI 配置**

在 Web UI 中打开 Settings → Models，选择添加自定义提供方（Add a custom provider），按下表填写并保存。模型路由在下一次请求即生效，无需重启服务：

| 表单项 | 填写内容 |
| --- | --- |
| Provider ID | `limapi`（小写，保存后不可修改） |
| Base URL | `https://limapi.com/api/v1` |
| API 协议 | `openai-completions` |
| API Key | 你的 LimAPI API Key |
| 模型 | 至少添加一个模型，如 `qwen3.8-max`、`deepseek-v4-pro` |

**方式二：配置文件**

也可以直接编辑 `~/.dsh/settings.yaml`，写入以下内容：

```yaml
agent-default-model:
  provider: limapi
  model: qwen3.8-max

llm-pi-ai:
  providers:
    limapi:
      api: openai-completions
      baseURL: https://limapi.com/api/v1
      apiKeyEnv: LIMAPI_API_KEY
      models:
        - id: qwen3.8-max
        - id: qwen3.7-max
        - id: deepseek-v4-pro
        - id: kimi-k2.7-code
```

并设置环境变量 `LIMAPI_API_KEY` 为你的 LimAPI API Key：

```bash
export LIMAPI_API_KEY="YOUR_API_KEY"
```

| 字段 | 说明 |
|------|------|
| `agent-default-model` | 新会话的默认提供方与模型 |
| `api` | 固定为 `openai-completions`（OpenAI 兼容协议） |
| `baseURL` | LimAPI OpenAI 兼容端点，固定为 `https://limapi.com/api/v1` |
| `apiKeyEnv` | 引用 API Key 的环境变量名；也可在 Web UI 的 Settings → Models 页面直接填入密钥（密钥存储在 `$DSH_HOME/.credentials.yaml`，settings 只保留凭据引用） |
| `models` | 向 DeepSeek Harness 声明的模型清单，如需添加其他模型以相同格式追加 |

## 验证配置

1. 在 Web UI 中点击选择工作区，添加并选中一个项目目录。dsh 以启动时所在目录作为默认文件系统位置，选中工作区前会话输入框不可用；
2. 在模型选择器中选择 `limapi` 提供方下的模型，发送一条消息（如「你好」），模型正常返回响应即配置成功。选择模型的同时会将其设为新会话的默认模型。

也可以不打开界面，用 headless 模式运行一次性任务：

```bash
npx @deepseek-ai/dsh --profile headless "总结当前目录项目的主要模块"
```

## 常见问题

### 报错 401 或提示 MISSING\_CREDENTIAL

* 确认 `LIMAPI_API_KEY` 环境变量已设置，或密钥已在 Web UI 的 Settings → Models 页面保存，且复制完整无首尾空格；
* 确认 API Key 在 [Portal](https://limapi.com/) 的「API Keys」页面状态正常；
* 确认 `baseURL` 为 `https://limapi.com/api/v1`，不要与其他平台地址混用。

### 获取可用模型返回 401

模型发现调用 OpenAI 兼容的 `GET /models` 端点，先检查 API Key 是否正确；对不提供该端点的服务需在 `models` 中手动输入模型。

### 报错 UNKNOWN\_MODEL

默认模型指向了未配置的提供方或模型：在模型选择器中重新选择已配置的模型，或在 `~/.dsh/settings.yaml` 的 `models` 中补充对应模型 `id`。

### 密钥与地址正确但请求被拒绝

DeepSeek Harness 按 OpenAI 原生形状发送请求（推理模型的系统消息使用 `developer` 角色、输出上限使用 `max_completion_tokens`），部分网关会拒绝。可在 `~/.dsh/settings.yaml` 的 `limapi` 路由下追加兼容配置：

```yaml
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
```

### 配置后不生效

Web UI 中保存的模型变更下一次请求即生效；直接修改 `settings.yaml` 后建议重启 dsh 重新加载配置，并检查 YAML 缩进是否正确（使用两个空格缩进）。