---
title: "将 DeepSeek Harness 接入 XiuRouter"
description: "在 DeepSeek Harness 中添加 XiuRouter 自定义模型服务，并验证模型发现、文本请求和工具调用。"
image: "https://docs.xiu.ai/og.png"
---

> XiuAI 文档索引
> 完整文档索引：https://docs.xiu.ai/llms.txt
> 阅读前先通过索引确认当前可用页面。

# 将 DeepSeek Harness 接入 XiuRouter

DeepSeek Harness（DSH）可以把 XiuRouter 添加为自定义 provider。协议选择 OpenAI Chat Completions，Base URL 使用 `https://router-api.xiu.ai/v1`。

## 前置条件

- DSH Web UI 可以正常打开。
- 已创建一把 DSH 专用 XiuRouter API Key。
- 已从 XiuRouter 当前目录复制精确模型 ID。
- 已为 DSH 选择明确的工作区和最小必要权限。

## 在界面中添加 provider

1. 打开 **Settings → Models**。
2. 选择 **Add a custom provider**。
3. Provider ID 填 `xiurouter`。该 ID 会被会话和凭据引用，保存后不要直接改名。
4. Base URL 填 `https://router-api.xiu.ai/v1`。
5. API protocol 选择 `OpenAI Chat Completions`。
6. 保存 XiuRouter API Key。
7. 添加当前目录中的精确模型 ID，或使用 **Fetch available models** 读取这把 Key 可访问的模型。
8. 保存后，在模型选择器中选中 XiuRouter 模型并新建会话。

DSH 保存的 Key 是只写凭据，设置页不会再次返回明文。不要把 Key 写进工作区文件或插件配置。

## 使用环境变量配置

需要手动维护 `$DSH_HOME/settings.yaml` 时，先在启动 DSH 的同一环境设置：

```bash
export XIUROUTER_API_KEY="YOUR_XIUROUTER_API_KEY"
```

再把下面内容合并到配置中：

```yaml
llm-pi-ai:
  providers:
xiurouter:
  apiKeyEnv: XIUROUTER_API_KEY
  api: openai-completions
  baseURL: https://router-api.xiu.ai/v1
  models:
    - id: YOUR_MODEL_ID
```

优先使用设置界面。手动 YAML 只适合需要环境变量或排查组合配置的场景，不要同时维护两份互相冲突的 provider。

## 验证

1. 先发送一个短文本请求，确认会话使用 `xiurouter` 和预期模型。
2. 再让 DSH 只读取一个不含敏感信息的文件并总结，不允许修改。
3. 确认 XiuRouter“使用记录”出现对应模型、状态、Token 和费用。
4. 最后才扩大到文件修改、图片输入或更高工作区权限。

手动添加的模型默认按纯文本处理。只有目标模型和当前服务来源都已验证图片输入时，才在 DSH 中声明 `input: [text, image]`。

## 请求兼容问题

DSH 的 OpenAI 兼容适配器可能按模型发送 `developer` 角色或 `max_completion_tokens`。XiuRouter 当前请求转换层能识别这些字段，但具体上游模型仍可能拒绝某种组合。

如果 Key、Base URL 和模型都正确，但请求仍被上游拒绝，先记录原始错误，再按 DSH 官方指南为该 provider 添加最小兼容项；不要一开始就为所有模型关闭能力。

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

只有错误明确指向对应字段时才添加这段配置。不同模型可以需要不同设置。

## 常见失败

| 现象 | 处理 |
| --- | --- |
| Fetch available models 返回 `401` | 检查保存的 Key；也可以先手动添加精确模型 ID |
| `MISSING_CREDENTIAL` | 确认设置页已保存凭据，或启动 DSH 的进程能读取 `XIUROUTER_API_KEY` |
| `UNKNOWN_MODEL` | 在 `xiurouter` provider 中加入同一模型 ID，再新建会话 |
| 只在推理模型上报请求格式错误 | 记录错误后再尝试最小 `compat` 配置 |
| 普通回复成功但工具失败 | 换用已验证工具调用的模型，并保持工作区权限不变排查 |

## 回滚

在 **Settings → Models** 切回原 provider 和模型。确认新会话恢复原路由后，删除 `xiurouter` provider，并撤销 DSH 专用 XiuRouter API Key。

## 来源与核对日期

本文按 DeepSeek Harness 当前自定义 provider 配置、XiuRouter 路由与请求转换代码核对，日期为 2026-08-19。本轮未使用真实 Key 运行 DSH 计费任务，模型工具调用和上游兼容项需要在实际工作区验证。

源文件：https://docs.xiu.ai/router/integrations/dsh/index.mdx