> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# DeepSeek Harness（dsh）接入 RuAPI：一个智能体用 DeepSeek、Claude、GPT

> DeepSeek Harness（dsh）怎么接 RuAPI：自定义模型 API、deepseek-flash、Claude 和 GPT 一个密钥、关闭思考、常见报错。

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（命令是 `dsh`）是 DeepSeek 开源的 AI 智能体，带网页界面（MIT 许可）。它会自己读写文件、在终端里执行命令，把任务一步步做完，用法类似 Claude Code，只是界面在浏览器里。

通过 RuAPI，dsh 可以用一个密钥调用 `deepseek-flash`、Claude、GPT 等模型，可以用加密货币（USDT）付款，不需要境外银行卡。简要介绍见 [www.ruapi.ai/deepseek-harness-v-rossii](https://www.ruapi.ai/deepseek-harness-v-rossii?lng=zh-CN\&utm_source=docs\&utm_campaign=zh-deepseek-harness)。

> [!NOTE]
>
> dsh 自带的 **DeepSeek** 卡片接不了 RuAPI：它走 DeepSeek 自家的接口，还要用文件上传接口（`/v1/files`），RuAPI 没有这个接口。请按下面的步骤用 **自定义模型 API** 接入。

> [!WARNING]
>
> dsh 会自己执行模型给出的命令、修改文件。请在 **单独的空文件夹** 里运行（或者放在单独的服务器／虚拟机上），不要在放着重要文件的目录里跑。dsh 目前是开发者预览版，界面可能会变。

## 准备

**1. RuAPI 密钥**

[控制台 → API 密钥](https://www.ruapi.ai/console/token?utm_source=docs\&utm_campaign=zh-deepseek-harness) → 新建密钥 `sk-...`。注册后就能先用体验模型 `deepseek-flash`、`claude-haiku-5-5`、`gpt-6-luna`。

**2. Node.js 24.9 或更新**

查看版本：

```bash theme={null}
node -v
```

需要 `v24.9.0` 或更高。版本低或提示找不到命令，按[下面的步骤](#安装-node-js)安装 Node.js。

**3. 一个空文件夹**

比如 `dsh-test`，dsh 会在里面建文件、改文件。

## 安装 Node.js

需要 24.9 或更高。我们实测用的是 Node.js 24；现在 [nodejs.org 下载页](https://nodejs.org/zh-cn/download) 上标着 **LTS** 的是 26 版，按 dsh 的要求也能用，但我们没有单独测过。选标着 **LTS** 的版本即可。`npm` 和 `npx` 会随 Node.js 一起装上，不用另外装。

> [tab] Windows
>
> 1. 在 [nodejs.org 下载页](https://nodejs.org/zh-cn/download) 下载 **Windows 安装程序 (.msi)**（英文页叫 Windows Installer；大多数电脑选 x64）。
> 2. 运行安装程序，一路点 **Next**，默认设置不用改。
> 3. **关掉终端重新打开**（PowerShell 或「命令提示符」），否则它找不到 Node.js。
>
> 也可以在 PowerShell 里用一条命令装（电脑上有 `winget` 的话）：
>
> ```powershell theme={null}
> winget install OpenJS.NodeJS.LTS
> ```
>
> 装完同样要关掉终端重新打开。如果 winget 问是否同意源协议，输入 `Y`。
>
> > [!WARNING]
> >
> > 如果 PowerShell 提示「无法加载文件 …\npx.ps1，因为在此系统上禁止运行脚本」，把 `npx` 换成 `npx.cmd`：检查用 `npx.cmd -v`，启动用 `npx.cmd @deepseek-ai/dsh web`。也可以改在「命令提示符」（cmd）里运行。

> [tab] macOS
>
> 1. 在 [nodejs.org 下载页](https://nodejs.org/zh-cn/download) 下载 **macOS 安装程序 (.pkg)**（英文页叫 macOS Installer），Apple 芯片和 Intel 芯片的 Mac 都能用。
> 2. 打开文件，按提示安装。
> 3. 新开一个「终端」窗口。
>
> 装了 Homebrew 的话：
>
> ```bash theme={null}
> brew install node
> ```

> [tab] Linux（Ubuntu / Debian）
>
> 默认源里的 `nodejs` 常常低于 24.9（比如 22 版）。已经装了的话先卸掉，再从 NodeSource 源装 Node.js 24：
>
> ```bash theme={null}
> sudo apt remove -y nodejs && sudo apt autoremove -y
> sudo apt update && sudo apt install -y curl
> curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
> sudo apt install -y nodejs
> ```
>
> 用 `root` 登录的话去掉 `sudo`（和 `-E`）。我们写这篇教程时就是这样在 Ubuntu 服务器上装的。

检查是否装好：

```bash theme={null}
node -v
npx -v
```

`node -v` 应显示 `v24.9.0` 或更高；`npx -v` 显示一个版本号（比如 `11.19.1`）就说明 npx 装好了。

> [!TIP]
>
> 如果 [nodejs.org](https://nodejs.org/) 打开很慢或下载中断，可以试试从镜像 [npmmirror.com/mirrors/node](https://npmmirror.com/mirrors/node/) 下载同样的安装包：打开对应版本的文件夹（比如 `v24.22.2/`），Windows 选 `node-v…-x64.msi`，macOS 选 `node-v….pkg`。它是 nodejs.org 的同步镜像。

## 第 1 步：启动

在终端里新建一个空文件夹、进入它，再启动 dsh：

```bash theme={null}
mkdir dsh-test
cd dsh-test
npx @deepseek-ai/dsh web
```

第一次运行 npm 会问要不要安装，输入 `y`。出现 `npm warn deprecated node-domexception` 警告可以不管。

dsh 会自动在浏览器打开 `http://127.0.0.1:3080`。

> [!WARNING]
>
> 如果要自己打开网页，请把终端里**整条地址**复制下来，包括 `?token=...`：
>
> ```
> dsh web: http://127.0.0.1:3080/?token=...
> ```
>
> 不带 token 打开会显示 `dsh web authentication required`。token 相当于 dsh 的登录密码，截图时请打码。每次重启 dsh，token 都会变。

> [accordion] dsh 装在远程服务器上（没有图形界面）
>
> 登录服务器时直接带上端口转发（`user@server` 换成你的登录名和服务器地址）：
>
> ```bash theme={null}
> ssh -L 3080:127.0.0.1:3080 user@server
> ```
>
> 在同一个窗口里启动 dsh，不打开浏览器：
>
> ```bash theme={null}
> mkdir -p ~/dsh-test && cd ~/dsh-test && npx @deepseek-ai/dsh web --no-open
> ```
>
> 这个窗口保持打开，然后在自己电脑的浏览器里打开 dsh 打印的那条带 token 的地址。最好用普通用户而不是 `root` 运行 dsh，这样智能体在服务器上的权限更小。

> [!TIP]
>
> 如果 `npx` 一直下载不下来，可以换一个 npm 镜像，例如：
>
> ```bash theme={null}
> npm config set registry https://registry.npmmirror.com
> ```
>
> 改回默认源：`npm config set registry https://registry.npmjs.org`。

## 第 2 步：第一次打开

1. 先弹出「预览版说明」，点 **继续**。
2. 点输入框上方的 **选择工作区**，选你的文件夹（比如 `dsh-test`）→ **打开**。没选文件夹之前，顶部会提示「无法创建默认工作区」。
3. 界面语言默认跟浏览器语言。要改的话：左下角 **更多** → **设置** → **通用设置** → **语言**（英文界面是 **More** → **Settings** → **General** → **Language**），支持中文、英文、俄文等。

![dsh 设置：界面语言列表](https://mintcdn.com/no-d0cfaf14/WrUTbT3Z7Mkwzwdf/images/dsh/language-zh.webp?fit=max\&auto=format\&n=WrUTbT3Z7Mkwzwdf\&q=85\&s=b4f2b67cab3c22631fe5ef4a912b53da)

## 第 3 步：接入 RuAPI

**更多** → **设置** → **模型** → **添加模型提供商** → 切到 **自定义模型 API**。

| 字段 | 填什么 |
| - | - |
| Provider ID | `ruapi`（小写，以后不能改） |
| 显示名称 | `RuAPI` |
| API 地址 | `https://www.ruapi.ai/v1` |
| API 协议 | **OpenAI Chat Completions**（默认就是） |
| API 密钥 | 你的 `sk-...` 密钥 |

![dsh：自定义模型 API 表单](https://mintcdn.com/no-d0cfaf14/WrUTbT3Z7Mkwzwdf/images/dsh/add-provider-zh.webp?fit=max\&auto=format\&n=WrUTbT3Z7Mkwzwdf\&q=85\&s=3714933ca091f15eb4b4034865f3eb13)

点 **获取可用模型**，会列出 RuAPI 的全部模型。先取消全选，再用搜索框勾上要用的模型。入门勾三个就够：`deepseek-flash`、`claude-haiku-5-5`、`gpt-6-luna`。

![dsh：选择模型窗口，列出 RuAPI 的模型](https://mintcdn.com/no-d0cfaf14/WrUTbT3Z7Mkwzwdf/images/dsh/fetch-models-zh.webp?fit=max\&auto=format\&n=WrUTbT3Z7Mkwzwdf\&q=85\&s=7f41bc141cc46ba18504713a04ec8b29)

点 **更新列表**，再点底部的创建按钮。提供商列表里 RuAPI 后面出现绿点就说明接通了。

![dsh：RuAPI 提供商，地址 https://www.ruapi.ai/v1，三个模型](https://mintcdn.com/no-d0cfaf14/WrUTbT3Z7Mkwzwdf/images/dsh/provider-config-zh.webp?fit=max\&auto=format\&n=WrUTbT3Z7Mkwzwdf\&q=85\&s=8d55fbce5f13a596434f34814a2c4200)

全部模型名见 [价格页](https://www.ruapi.ai/pricing?utm_source=docs\&utm_campaign=zh-deepseek-harness)。以后要加模型：**模型** → RuAPI 的 **编辑** → **自定义设置** → **获取可用模型**。

## 第 4 步：第一个任务

1. 左上角 **新会话**。
2. 点输入框右下角的模型选择按钮，选比如 `deepseek-flash`。

![dsh：模型菜单里的 RuAPI 模型](https://mintcdn.com/no-d0cfaf14/WrUTbT3Z7Mkwzwdf/images/dsh/model-picker-zh.webp?fit=max\&auto=format\&n=WrUTbT3Z7Mkwzwdf\&q=85\&s=79eacb6d73d49518e0fc9e54f45f32b5)

3. 发一个任务，比如：

```
在当前文件夹里创建 hello.txt，写入“你好”，然后列出文件夹里的文件。
```

dsh 会建文件、执行命令、读取结果。我们实测 `deepseek-flash` 9 秒左右完成，`claude-haiku-5-5` 6 秒，`gpt-6-luna` 14 秒。

![dsh：通过 RuAPI 创建 hello.txt 并列出文件](https://mintcdn.com/no-d0cfaf14/WrUTbT3Z7Mkwzwdf/images/dsh/task-done-zh.webp?fit=max\&auto=format\&n=WrUTbT3Z7Mkwzwdf\&q=85\&s=11ff70c669e71bd3edc4afe3711a329b)

（这张截图那次用时 13 秒，耗时会有波动。）

> [!TIP]
>
> 中途想换模型，建议开一个 **新会话**：新模型从干净的上下文开始，不会接着别的模型的对话往下做。

## deepseek-flash 的推理等级

`deepseek-flash` 默认会先思考再回答。想在对话里切换等级：

1. **设置** → **模型** → RuAPI 的 **编辑** → **自定义设置**。
2. 点 `deepseek-flash` 右边的箭头 → 打开 **推理等级**（off / low / medium / high）→ 点设置窗口右下角的按钮保存。

![dsh：deepseek-flash 的推理等级设置](https://mintcdn.com/no-d0cfaf14/WrUTbT3Z7Mkwzwdf/images/dsh/reasoning-levels-zh.webp?fit=max\&auto=format\&n=WrUTbT3Z7Mkwzwdf\&q=85\&s=b2c0c03b9bf781483ad7981532458cba)

之后右下角的模型菜单会变成两层：一层选模型，一层选推理等级（Off、Low、Medium、High）。

> [!WARNING]
>
> **只选 Off 并不能关掉思考。** 选 Off 时 dsh 什么都不发，而 DeepSeek 不明确告诉它关掉就会照常思考。需要在配置文件里加一项设置，表单里没有这一项。

打开 `~/.dsh/profiles/web/cordis.patch.yml`（Windows 是 `%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml`），在 `name: deepseek-flash` 下面加两行 `compat`：

```yaml theme={null}
          - id: deepseek-flash
            name: deepseek-flash
            compat:
              thinkingFormat: deepseek
            reasoningEfforts:
```

缩进用空格，和上下行对齐。保存后停掉 dsh（`Ctrl+C`），在同一个窗口里再运行 `npx @deepseek-ai/dsh web`（如果是新开的终端，先 `cd dsh-test`）；重启后地址里的 token 会变。

我们实测改完后，Off 3 秒回答、不再思考（改之前 9 秒，其中思考 3 秒）；High 6 秒。

> [!TIP]
>
> 最简单的是点「设置」窗口右上角的 **打开配置文件**，它会在运行 dsh 的那台电脑上打开这个文件。Windows 上也可以按 `Win+R`，粘贴 `%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml`，选「记事本」打开。服务器上用 `nano ~/.dsh/profiles/web/cordis.patch.yml`（保存按 `Ctrl+O` 再按 `Enter`，退出按 `Ctrl+X`）。

## 用 Anthropic 原生格式接 Claude（可选）

上面的 `ruapi` 提供商已经能用 Claude。如果你经常用 Claude，可以再加一个用 Anthropic 原生协议的提供商，提示缓存能早一轮命中。

**添加模型提供商** → **自定义模型 API**：

| 字段 | 填什么 |
| - | - |
| Provider ID | `ruapi-claude` |
| 显示名称 | `RuAPI Claude` |
| API 地址 | `https://www.ruapi.ai`（**不带** `/v1`） |
| API 协议 | **Anthropic Messages** |
| API 密钥 | 同一个 `sk-...` 密钥 |

**获取可用模型** → 勾上要用的 Claude（比如 `claude-haiku-5-5`）→ **更新列表** → 创建。这些模型会出现在模型菜单的 **RuAPI Claude** 分组里。

![dsh：RuAPI Claude 提供商，协议 Anthropic Messages，地址 https://www.ruapi.ai](https://mintcdn.com/no-d0cfaf14/WrUTbT3Z7Mkwzwdf/images/dsh/anthropic-zh.webp?fit=max\&auto=format\&n=WrUTbT3Z7Mkwzwdf\&q=85\&s=42ddd16bb5cb4fe2be86aa3b396d87b3)

实测结果（同一个会话连问三个短问题，`claude-haiku-5-5`）：

| 轮次 | 走 `ruapi`（OpenAI 格式）缓存命中 | 走 `ruapi-claude`（Anthropic 格式）缓存命中 |
| - | - | - |
| 第 1 轮 | 0% | 0% |
| 第 2 轮 | 0% | 100% |
| 第 3 轮 | 100% | 100% |

差别只在每个会话的第 2 轮，所以大多数人只配 `ruapi` 一个提供商就够了。

## 费用

* dsh 每一步都会把系统提示词、工具说明和对话历史发给模型，我们实测每步输入 2.6–3.6 万 token。
* 其中大部分通常能命中缓存（实测 70–97%；Claude 走 OpenAI 格式要到第 3 轮才命中，见上表），缓存部分便宜很多。详见 [提示缓存](https://docs.ruapi.ai/zh/prompt-caching.md)。
* 用 dsh 最省钱的模型是 `deepseek-flash`。每次请求花了多少，可以在 RuAPI 控制台 → **使用日志** 里看。

## 常见问题

> [accordion] dsh web authentication required
>
> 打开网页时没带 token。请复制终端里整条 `http://127.0.0.1:3080/?token=...` 地址。

> [accordion] 提示「无法创建默认工作区」
>
> 手动选文件夹：输入框上方 **选择工作区** → 你的文件夹 → **打开**。

> [accordion] npx 提示 Node.js 版本不对
>
> 需要 Node.js 24.9 或更新。用 `node -v` 查看并升级。

> [accordion] 获取可用模型返回 401
>
> 密钥填错或已删除。到 RuAPI 控制台确认密钥后重新填：**模型** → **编辑** → **API 密钥**。

> [accordion] 模型菜单是空的
>
> 提供商里没有勾选模型。**编辑** → **自定义设置** → **获取可用模型** → 勾选 → **更新列表** → 点右下角的按钮保存。

> [accordion] deepseek-flash 选了 Off 还在思考
>
> 在配置文件里加 `compat: thinkingFormat: deepseek` 并重启 dsh，见上面「deepseek-flash 的推理等级」。

> [accordion] 换模型时提示「先用体验模型试一下……」
>
> 第一次充值前只能用体验模型（`deepseek-flash`、`claude-haiku-5-5`、`gpt-6-luna`）。[充值](https://www.ruapi.ai/console/topup?utm_source=docs\&utm_campaign=zh-deepseek-harness)后即可使用全部模型，支持 USDT，不需要境外银行卡。

## 安全

* dsh 把 RuAPI 密钥保存在你电脑的 `~/.dsh` 文件夹里，不要把这个文件夹发给别人。
* 建议给 dsh 单独建一个密钥，出问题时直接在控制台删掉即可。
* dsh 以你的系统用户身份执行命令。不要在放重要文件的目录里运行，也不要交给它你没准备检查结果的任务。

## 接下来

* [在 Claude Code 里跑 DeepSeek](https://docs.ruapi.ai/zh/integrations/claude-code-deepseek.md)：在 Claude Code 里用同一个 `deepseek-flash`。
* [Hermes Agent](https://docs.ruapi.ai/zh/integrations/hermes.md)：另一个支持 RuAPI 的智能体。
* [API 错误码](https://docs.ruapi.ai/zh/errors.md)：请求报错时查这里。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.