DeepSeek Harness

一、产品简介

DeepSeek Harness（命令行工具 dsh）是 DeepSeek 官方开源的 Agent 运行框架，官方定位为「Model + Harness = Agent」——它本身不提供模型，而是为大模型装上操作文件、终端、网页和外部服务的「手脚」，让模型在你的工作区里自主拆解任务、读文件、改代码、执行命令并交付成果。它采用「一切皆插件」架构，模型只是其中一种可替换的能力，因此可以接入任意 OpenAI 兼容或 Anthropic 兼容的模型服务。 DeepSeek Harness 提供 Web UI（默认 http://127.0.0.1:3080）、命令行与 SDK 三种使用方式。通过对接 GravitexAI，您可以获得：

能力	说明
一把密钥全模型	无需分别注册各家账号，一个密钥即可在 DeepSeek Harness 中调用 GPT、Claude、Gemini、DeepSeek、Kimi、MiniMax 等全模型矩阵
密钥本地保存	API Key 仅保存在本机 `$DSH_HOME/.credentials.yaml`（macOS/Linux 默认 `~/.dsh/`，Windows 默认 `%USERPROFILE%\.dsh\`），设置文件中只存凭据引用，不含明文
图形化一键接入	设置 → 模型 → 添加自定义提供方，填入接口地址、协议、密钥、模型即可，无需手动改配置文件
多协议支持	同时支持 OpenAI Completions、OpenAI Responses 与 Anthropic 原生协议，可按模型类型各建一个提供方
按量自主付费	自定义提供方产生的费用由您直接向 GravitexAI 结算

二、环境要求

已安装 Node.js（建议使用 LTS 版本）
支持 macOS / Linux / Windows，Web UI 通过浏览器访问

DeepSeek Harness 目前处于开发者预览（Developer Preview）阶段，迭代较快，可能存在不兼容变更，升级前请留意官方更新说明。

三、前置条件

在你的机器上已安装 Node.js
已在 GravitexAI 控制台创建 API Key（格式 sk-xxxxxxxxxx）

四、快速开始

第一步：安装并启动 DeepSeek Harness

无需全局安装，直接通过 npx 启动 Web UI：

npx @deepseek-ai/dsh web

该命令默认在 http://127.0.0.1:3080 启动 Web UI 并自动打开浏览器；加 --no-open 可只启动服务不打开浏览器。配置和数据默认保存在 $DSH_HOME 目录（macOS/Linux 为 ~/.dsh/，Windows 为 %USERPROFILE%\.dsh\）。

第二步：获取 GravitexAI API Key

访问 GravitexAI 控制台
点击「新建令牌」，命名并保存
复制以 sk- 开头的密钥备用

第三步：添加自定义提供方

在 Web UI 中打开 设置 → 模型，选择「添加自定义提供方」，按下表填写：

字段	填写值	说明
Provider ID	`gravitex`	全小写，创建后不可改名（请求、会话、凭据引用都使用它），如需改名只能新建后删除旧的
Display name	`GravitexAI`	显示名称，可随时修改
Base URL	`https://api.gravitex.ai/v1`	OpenAI 兼容协议地址，必须带 `/v1`
API 协议	`openai-completions`	OpenAI 系列模型（如 `gpt-5.5`）需选 `openai-responses`，其余模型选 `openai-completions`
API Key	如 `sk-...`	粘贴上一步获取的 GravitexAI 令牌
模型	至少添加一个模型 ID	见下一步

一个提供方只能使用一种协议。OpenAI 系列模型（如 gpt-5.5）必须使用 openai-responses 协议，DeepSeek、Gemini、Kimi 等模型使用 openai-completions。Claude 系列模型推荐使用 Anthropic 原生协议（anthropic-messages）接入，Base URL 填 https://api.gravitex.ai（不带 /v1）。协议不同需各建一个提供方（如 gravitex、gravitex-openai、gravitex-anthropic，见第六节「进阶配置」）。

填写完成后的表单如下图所示：

第四步：添加模型

在提供方表单的「模型目录」中点击 获取可用模型，DeepSeek Harness 会调用网关的 GET /models 接口列出可用模型，搜索并勾选想要的模型后点「添加所选」即可：

如果探测失败或列表为空，手动输入模型 ID 效果完全一样。注意模型必须与所属提供方的协议匹配，例如：

模型 ID	说明	所属协议
`deepseek-v4-pro`	DeepSeek 旗舰模型	`openai-completions`
`claude-sonnet-5`	Claude 系列	`anthropic-messages`（推荐）/ `openai-completions`
`gpt-5.5`	GPT 系列	`openai-responses`
`gemini-3.6-flash`	Gemini 系列	`openai-completions`
`kimi-k3`	Kimi 系列	`openai-completions`

完整模型 ID 以 GravitexAI 模型广场公布的为准。

第五步：选择模型开始使用

保存提供方后，在会话的模型选择器中即可看到 GravitexAI 下的模型，选中即可开始任务。选择模型会同时将其设为新会话的默认值；模型变更在下一次请求时生效，无需重启服务：

五、常用功能速查

功能	说明
Agent 任务执行	模型在工作区内自主读写文件、执行终端命令、完成任务并交付
一切皆插件	模型、工具、运行时能力均为插件，可按需扩展和替换
多使用形态	Web UI（`dsh web`）、命令行、SDK 三种方式
多提供方切换	模型选择器中随时切换提供方/模型，下一次请求即生效
本地凭据存储	密钥存于 `$DSH_HOME/.credentials.yaml`，设置仅存凭据引用

六、进阶配置（可选）

通过 Web UI 完成上文配置后，一般无需阅读本节。模型页面只开放基础字段（密钥、地址、协议、模型 ID、上下文窗口等），其余能力——推理等级、图片输入、请求兼容性开关等——需直接编辑 $DSH_HOME/settings.yaml（macOS/Linux 默认 ~/.dsh/settings.yaml，Windows 默认 %USERPROFILE%\.dsh\settings.yaml；浏览器与服务器在同一台机器时，也可点击设置页顶部的「打开配置文件」直接打开）。保存后下一次请求即生效，无需重启服务。 关于密钥：本节示例中的 apiKeyEnv: GRAVITEX_API_KEY 表示密钥从环境变量读取，手写配置前请先在终端设置：

export GRAVITEX_API_KEY="sk-xxxxxxxxxx"

$env:GRAVITEX_API_KEY="sk-xxxxxxxxxx"

以上命令只在当前终端会话生效。Windows 下如需永久生效，可使用 setx GRAVITEX_API_KEY "sk-xxxxxxxxxx"（设置后需重新打开终端）；macOS/Linux 可将 export 命令写入 ~/.zshrc 或 ~/.bashrc。

如果你已在 Web UI 中保存过提供方的密钥，settings.yaml 中会自动写入一条凭据引用。在此基础上补充配置时保留该引用、不要替换成 apiKeyEnv 即可；apiKeyEnv 写法适用于完全手写配置、密钥由环境变量提供的场景。

完整参考配置

以下是一份包含三个提供方的完整 settings.yaml 示例，按需删减后复制使用：

llm-pi-ai:
  providers:
    # 提供方一：openai-completions 协议 —— DeepSeek / Gemini / Kimi 等模型
    gravitex:
      apiKeyEnv: GRAVITEX_API_KEY
      api: openai-completions
      baseURL: https://api.gravitex.ai/v1
      models:
        - id: deepseek-v4-pro
          compat:
            thinkingFormat: deepseek    # DeepSeek 模型正确开关思考必需
          reasoningEfforts:             # 声明后模型选择器出现推理等级菜单
            off:
            high: high
            max: max
        - id: gemini-3.6-flash
          input: [text, image]          # 视觉模型需声明图片输入，否则附图会在发送前被拒绝
        - id: kimi-k3

    # 提供方二：openai-responses 协议 —— GPT 系列模型
    gravitex-openai:
      apiKeyEnv: GRAVITEX_API_KEY
      api: openai-responses
      baseURL: https://api.gravitex.ai/v1
      models:
        - id: gpt-5.5

    # 提供方三：anthropic-messages 协议 —— Claude 系列模型（推荐方式）
    gravitex-anthropic:
      apiKeyEnv: GRAVITEX_API_KEY
      api: anthropic-messages
      baseURL: https://api.gravitex.ai  # 注意：Anthropic 协议不带 /v1
      models:
        - id: claude-sonnet-5

字段说明

字段	作用	何时需要
`apiKeyEnv`	密钥从指定环境变量读取	完全手写配置时；Web UI 保存过密钥则保留自动生成的凭据引用
`input`	声明模型支持的输入模态（`text` / `image`）	手动录入的视觉模型——默认按纯文本对待
`reasoningEfforts`	声明推理等级，模型选择器中会出现等级菜单	需要手动切换推理强度时；`off` 留空表示不发送推理参数
`compat.thinkingFormat: deepseek`	让 `off` 真正关闭思考，其余等级显式开启思考	OpenAI 兼容网关后的 DeepSeek 模型
`compat.supportsDeveloperRole: false`	系统提示词改用普通角色发送	密钥地址都正确但网关拒绝推理模型的请求时
`compat.maxTokensField: max_tokens`	输出上限改用 `max_tokens` 字段发送	网关不认 `max_completion_tokens` 字段时

后两个 compat 字段也可以写在提供方层级，对该提供方下所有模型统一生效：

    gravitex:
      apiKeyEnv: GRAVITEX_API_KEY
      api: openai-completions
      baseURL: https://api.gravitex.ai/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: deepseek-v4-pro

七、常见问题

报 MISSING_CREDENTIAL 怎么排查？

当前提供方没有解析到凭据。按配置方式分别检查：通过 Web UI 配置的，在模型页面重新保存 API Key；手写配置使用 apiKeyEnv 的，确认对应环境变量已设置（如 export GRAVITEX_API_KEY="sk-..."）且启动 dsh 的终端能读到它。不要在聊天里粘贴 Key 绕过。

报 UNKNOWN_MODEL 怎么排查？

模型 ID 未被当前提供方识别。核对该模型是否已添加到提供方的模型列表中，注意模型 ID 的大小写与拼写需与 GravitexAI 模型广场完全一致。

GPT 系列模型报错或无法正常调用？

确认该模型所在提供方的协议为 openai-responses。GPT 系列模型不能放在 openai-completions 协议的提供方下，需要单独建一个 openai-responses 协议的提供方（如 gravitex-openai）后再添加模型。

「获取可用模型」返回 401 或列表为空？

401 说明密钥或地址不匹配，确认 Base URL 为 https://api.gravitex.ai/v1 且密钥以 sk- 开头、没有多余空格。列表为空或探测失败时直接手动输入模型 ID 即可，效果完全一样。

密钥和地址都正确，但每个请求都被拒绝？

网关与 OpenAI 的请求形状存在差异。在 settings.yaml 的提供方层级设置 compat.supportsDeveloperRole: false 与 compat.maxTokensField: max_tokens 后重试（写法见第六节）。

DeepSeek 模型选 off 后仍在思考？

留空的 off 不发送任何推理字段，默认思考的模型会继续思考。请为该模型设置 compat.thinkingFormat: deepseek（见第六节示例）。

图片在发送前就被拒绝？

手动录入的模型默认按纯文本对待。在 settings.yaml 中给该模型加上 input: [text, image]；反之如果提供方拒绝了带图片的请求，说明声明了模型实际不具备的图片能力，把 image 移除后开启新会话即可。

Provider ID 填错了能改吗？

不能。Provider ID 是永久的（请求、已保存会话、凭据引用都引用它），如需修改请添加新提供方并删除旧提供方；显示名称、Base URL、协议、凭据和模型列表均可随时编辑。

八、相关资源

DeepSeek Harness GitHub：deepseek-ai/deepseek-harness
官方文档：deepseek-harness.github.io/deepseek-harness
模型配置官方指南：providers 配置
社区讨论：GitHub Discussions / Discord
密钥管理：https://maas.gravitex.ai/#/api-keys
模型广场：https://maas.gravitex.ai/#/api-models

对话型 AI

编程开发

AI Agent

技术工程

翻译场景

一、产品简介

二、环境要求

三、前置条件

四、快速开始

第一步：安装并启动 DeepSeek Harness

第二步：获取 GravitexAI API Key

第三步：添加自定义提供方

第四步：添加模型

第五步：选择模型开始使用

五、常用功能速查

六、进阶配置（可选）

完整参考配置

字段说明

七、常见问题

八、相关资源

​一、产品简介

​二、环境要求

​三、前置条件

​四、快速开始

​第一步：安装并启动 DeepSeek Harness

​第二步：获取 GravitexAI API Key

​第三步：添加自定义提供方

​第四步：添加模型

​第五步：选择模型开始使用

​五、常用功能速查

​六、进阶配置（可选）

​完整参考配置

​字段说明

​七、常见问题

​八、相关资源

一、产品简介

二、环境要求

三、前置条件

四、快速开始

第一步：安装并启动 DeepSeek Harness

第二步：获取 GravitexAI API Key

第三步：添加自定义提供方

第四步：添加模型

第五步：选择模型开始使用

五、常用功能速查

六、进阶配置（可选）

完整参考配置

字段说明

七、常见问题

八、相关资源