> ## Documentation Index > Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt > Use this file to discover all available pages before exploring further. # DeepSeek Harness > 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](https://nodejs.org/)（建议使用 LTS 版本） * 支持 macOS / Linux / Windows，Web UI 通过浏览器访问 DeepSeek Harness 目前处于开发者预览（Developer Preview）阶段，迭代较快，可能存在不兼容变更，升级前请留意官方更新说明。 ## 三、前置条件 * 在你的机器上已安装 Node.js * 已在 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 创建 API Key（格式 `sk-xxxxxxxxxx`） ## 四、快速开始 ### 第一步：安装并启动 DeepSeek Harness 无需全局安装，直接通过 `npx` 启动 Web UI： ```bash theme={null} 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 1. 访问 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 2. 点击「新建令牌」，命名并保存 3. 复制以 `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 添加自定义提供方 ### 第四步：添加模型 在提供方表单的「模型目录」中点击 **获取可用模型**，DeepSeek Harness 会调用网关的 `GET /models` 接口列出可用模型，搜索并勾选想要的模型后点「添加所选」即可： DeepSeek Harness 获取可用模型 如果探测失败或列表为空，手动输入模型 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 模型广场](https://maas.gravitex.ai/#/api-models) 公布的为准。 ### 第五步：选择模型开始使用 保存提供方后，在会话的模型选择器中即可看到 GravitexAI 下的模型，选中即可开始任务。选择模型会同时将其设为新会话的默认值；**模型变更在下一次请求时生效，无需重启服务**： DeepSeek Harness 选择模型 ## 五、常用功能速查 | 功能 | 说明 | | ---------- | ------------------------------------------- | | 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` 表示密钥从环境变量读取，手写配置前请先在终端设置： ```bash macOS / Linux theme={null} export GRAVITEX_API_KEY="sk-xxxxxxxxxx" ``` ```powershell Windows PowerShell theme={null} $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` 示例，按需删减后复制使用： ```yaml theme={null} 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` 字段也可以写在**提供方层级**，对该提供方下所有模型统一生效： ```yaml theme={null} 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 ``` ## 七、常见问题 当前提供方没有解析到凭据。按配置方式分别检查：通过 Web UI 配置的，在模型页面重新保存 API Key；手写配置使用 `apiKeyEnv` 的，确认对应环境变量已设置（如 `export GRAVITEX_API_KEY="sk-..."`）且启动 `dsh` 的终端能读到它。不要在聊天里粘贴 Key 绕过。 模型 ID 未被当前提供方识别。核对该模型是否已添加到提供方的模型列表中，注意模型 ID 的大小写与拼写需与 [GravitexAI 模型广场](https://maas.gravitex.ai/#/api-models) 完全一致。 确认该模型所在提供方的协议为 `openai-responses`。GPT 系列模型不能放在 `openai-completions` 协议的提供方下，需要单独建一个 `openai-responses` 协议的提供方（如 `gravitex-openai`）后再添加模型。 401 说明密钥或地址不匹配，确认 Base URL 为 `https://api.gravitex.ai/v1` 且密钥以 `sk-` 开头、没有多余空格。列表为空或探测失败时直接手动输入模型 ID 即可，效果完全一样。 网关与 OpenAI 的请求形状存在差异。在 `settings.yaml` 的提供方层级设置 `compat.supportsDeveloperRole: false` 与 `compat.maxTokensField: max_tokens` 后重试（写法见第六节）。 留空的 `off` 不发送任何推理字段，默认思考的模型会继续思考。请为该模型设置 `compat.thinkingFormat: deepseek`（见第六节示例）。 手动录入的模型默认按纯文本对待。在 `settings.yaml` 中给该模型加上 `input: [text, image]`；反之如果提供方拒绝了带图片的请求，说明声明了模型实际不具备的图片能力，把 `image` 移除后开启新会话即可。 不能。Provider ID 是永久的（请求、已保存会话、凭据引用都引用它），如需修改请添加新提供方并删除旧提供方；显示名称、Base URL、协议、凭据和模型列表均可随时编辑。 ## 八、相关资源 * DeepSeek Harness GitHub：[deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) * 官方文档：[deepseek-harness.github.io/deepseek-harness](https://deepseek-harness.github.io/deepseek-harness/) * 模型配置官方指南：[providers 配置](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.zh.md) * 社区讨论：[GitHub Discussions](https://github.com/deepseek-ai/deepseek-harness/discussions) / [Discord](https://discord.gg/Ycq5dCaS4) * 密钥管理：[https://maas.gravitex.ai/#/api-keys](https://maas.gravitex.ai/#/api-keys) * 模型广场：[https://maas.gravitex.ai/#/api-models](https://maas.gravitex.ai/#/api-models)