DeepSeek Harness 接入指南

DeepSeek Harness（dsh）是 DeepSeek 开源的 Agent Harness。本文介绍如何通过自定义 Provider 接入 Step 5 Preview，包括 Web UI 配置、配置文件、验证与常见问题。

dsh 目前处于开发者预览阶段，界面和配置可能随版本变化。本文按当前官方模型配置文档整理；运行前请阅读项目的安全说明，只在可信工作目录中使用，并谨慎授权文件操作和命令执行。

配置速查

配置项	值
Provider ID	`stepfun`
API protocol	`openai-completions`
Step Plan Base URL	`https://api.stepfun.com/step_plan/v1`
按量付费 API Base URL	`https://api.stepfun.com/v1`
模型 ID	`step-5-preview`
上下文窗口	1,000,000 tokens
API Key	控制台密钥管理

前置条件

安装并启动 dsh

准备 Node.js 22.19+（22.x）或 24+ 和 npm，建议使用当前 LTS，并以 dsh 官方要求为准。然后在可信工作目录中运行：

npx -y @deepseek-ai/dsh web

首次运行会下载所需包。本机启动时默认打开 http://127.0.0.1:3080；通过 SSH 启动时可能只打印地址。具体启动选项见 dsh 官方仓库。

准备 API Key

在控制台创建 API Key。使用 Step Plan 前请确认订阅和模型权限；使用按量付费 API 时请确认账户余额及权限。不要将真实密钥提交到代码仓库或分享在截图中。

方式一：通过 Web UI 配置

使用 Step Plan 订阅额度时，必须选择 /step_plan/v1，并确认订阅有效、具备对应模型权限。普通 /v1 是按量付费 API，不会因为已有 Step Plan 订阅而自动使用订阅额度。下文示例默认使用 Step Plan；按量付费用户请统一替换 Base URL。

打开模型设置

在 dsh Web UI 中进入 Settings → Models，选择 Add a custom provider。

填写 Provider

字段	填写内容
Provider ID	`stepfun`，这是提供方标识，不是模型名
Display name	`StepFun`
Base URL	`https://api.stepfun.com/step_plan/v1`
API protocol	`openai-completions`
API key	您的 StepFun API Key

Provider ID 保存后不能直接重命名；要使用新标识，请创建新的 Provider。

添加模型

在模型列表中点击 Add model，将模型 ID 和显示名称都填为 step-5-preview。在 Model options 中将上下文窗口设为 1000000（1,000,000 tokens，输入时不加逗号）；需要图片输入时，在 Input types 中保留 Text 并选中 Image。可选添加 step-3.7-flash，上下文窗口为 256,000 tokens（填写 256000）。模型规格分别见 Step 5 Preview 和 Step 3.7 Flash，可用模型以当前账户权限为准。

模型 ID 不能为空。仅点击 Add model 而不填写 ID 会导致保存失败；Provider ID 应为 stepfun，模型 ID 是 step-5-preview。

保存并选择模型

点击 Create provider，新建会话，在模型选择器中选择 StepFun 下的 step-5-preview，发送一条简单消息验证。已有会话可能保留之前使用的模型。

Web UI 保存的密钥存储在运行 dsh 的机器上的 $DSH_HOME/.credentials.yaml 中，配置只保留凭据引用；如果 dsh 部署在远程服务器上，密钥也保存在服务器上。调用模型时仍会将密钥作为认证信息发送给配置的 API 服务，请核对 Base URL。

方式二：通过配置文件

编辑 ~/.dsh/settings.yaml。如果设置了 DSH_HOME，请使用该目录下的 settings.yaml。将以下配置合并到现有 llm-pi-ai.providers 中，不要覆盖其他 Provider 或重复创建同名 YAML 键。

llm-pi-ai:
  providers:
    stepfun:
      apiKeyEnv: STEPFUN_API_KEY
      api: openai-completions
      baseURL: https://api.stepfun.com/step_plan/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: step-5-preview
          name: step-5-preview
          contextWindow: 1000000
          input: [text, image]
        - id: step-3.7-flash
          name: step-3.7-flash
          contextWindow: 256000
          input: [text, image]

compat 将系统指令按兼容的角色发送，并使用 max_tokens 指定输出限制；这些选项见 dsh 请求兼容性文档。input 声明 dsh 可发送的输入类型，不代表模型的全部模态能力。

设置凭据

选择以下一种方式：

Web UI（推荐）：启动 dsh，进入 Settings → Models，编辑 stepfun，填入 API Key 并保存。
环境变量：将 YOUR_STEP_API_KEY 替换为您的 API Key，在启动 dsh 的同一个终端中设置变量，再启动进程。以下命令适用于 macOS / Linux / WSL 的 Bash 或 Zsh：

export STEPFUN_API_KEY="YOUR_STEP_API_KEY"
npx -y @deepseek-ai/dsh web

settings.yaml 和通过 Web UI 保存的凭据通常在下一次请求生效，无需重启。终端中的新环境变量不会自动传入已经运行的进程；使用环境变量方式时，需要从已设置变量的终端重新启动 dsh。

验证配置

先确认 dsh 新会话选中了 stepfun 下的 step-5-preview，发送简单消息并检查返回。如需单独排查 API 连通性，在终端设置 STEPFUN_API_KEY 后运行以下命令。仅在 Web UI 中保存密钥不会自动设置终端变量。

curl --silent --show-error --fail-with-body \
  --write-out '\nHTTP %{http_code}\n' \
  https://api.stepfun.com/step_plan/v1/chat/completions \
  -H "Authorization: Bearer $STEPFUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "step-5-preview",
    "messages": [{"role": "user", "content": "Say hello briefly."}],
    "max_tokens": 1024
  }'

返回 HTTP 200 且 JSON 中包含正常的 choices 表示这次 API 请求成功；它不能单独证明 dsh 的 Provider、凭据或会话选择正确。若输出被截断，可提高 max_tokens 后重试。测试调用会使用对应账户的额度。

常见问题

现象	排查方式
`MISSING_CREDENTIAL`	确认 `apiKeyEnv` 与 `STEPFUN_API_KEY` 一致，变量已传入 dsh 进程；或在 Web UI 中补填密钥。若旧环境变量仍存在，更新或移除它后重启，避免遮蔽 UI 保存的新密钥。
模型 ID 不能为空	模型 ID 是 API 调用时使用的模型标识：Step 5 Preview 填写 `step-5-preview`，Step 3.7 Flash 填写 `step-3.7-flash`。为每个新增模型填写对应 ID，或删除多余的空模型行。Provider ID 填写 `stepfun`，不要与模型 ID 混淆。
`401 Unauthorized`	检查密钥是否正确、有效，且属于当前 API 地址对应的平台账户。
`404` / model not found	检查 Base URL、`step-5-preview` 拼写以及账户模型权限；不要把完整 `/chat/completions` 路径填入 Base URL。
密钥和地址正确，但请求字段被拒绝	检查 YAML 的 `compat.supportsDeveloperRole: false` 和 `compat.maxTokensField: max_tokens`，然后新建会话重试。
新配置没有生效	检查 `DSH_HOME`、YAML 缩进及重复键；重新选择模型并新建会话。使用新环境变量时重启 dsh。
模型列表获取失败	模型发现依赖服务端列表接口；可以直接手动添加模型 ID，不必等待自动发现。

开始了解

接入指南

配置速查

前置条件

安装并启动 dsh

准备 API Key

方式一：通过 Web UI 配置

方式二：通过配置文件

设置凭据

验证配置

常见问题

相关文档

​配置速查

​前置条件

​安装并启动 dsh

​准备 API Key

​方式一：通过 Web UI 配置

​方式二：通过配置文件

​设置凭据

​验证配置

​常见问题

​相关文档

配置速查

前置条件

安装并启动 dsh

准备 API Key

方式一：通过 Web UI 配置

方式二：通过配置文件

设置凭据

验证配置

常见问题

相关文档