---
title: "DSH 出现 MISSING_CREDENTIAL 或模型 401 怎么修复"
seo_title: "DeepSeek Harness MISSING_CREDENTIAL 与 401：DSH API Key 排查"
description: "区分 DeepSeek Harness 的 MISSING_CREDENTIAL、UNKNOWN_MODEL、模型目录 401 和网关请求兼容性问题，安全检查 API Key、Provider 与模型。"
canonical: https://52dsh.com/errors/dsh-missing-credential-401/
authors: ["52DSH 编辑部"]
published_at: 2026-08-25
updated_at: 2026-08-25
verified_on: 2026-08-25
maintenance_status: community
verification_level: source_reviewed
risk_level: high
dsh_version: 0.1.1-rc.2
plugin_id: null
tutorial_kind: null
related_plugin_url: null
---

# DSH 出现 MISSING_CREDENTIAL 或模型 401 怎么修复

区分 DeepSeek Harness 的 MISSING_CREDENTIAL、UNKNOWN_MODEL、模型目录 401 和网关请求兼容性问题，安全检查 API Key、Provider 与模型。

## 先区分两个完全不同的问题

`MISSING_CREDENTIAL` 表示 DSH 没有解析到当前 Provider 所引用的凭据；401 则通常表示请求已经到达模型服务或模型发现端点，但对方拒绝认证。前者优先检查“凭据是否存在、引用是否正确”，后者优先检查“Key、Base URL 和目标服务是否匹配”。两者不应通过把 API Key 粘贴进聊天消息来绕过。

本文固定审阅 DeepSeek Harness `0.1.1-rc.2` 的官方 Provider 指南和凭据实现，没有使用真实 API Key 发起请求。不同第三方网关的状态码和错误正文可能不同，应保留原始响应再判断。

## 快速判断表

| 现象 | 主要含义 | 第一检查点 |
|---|---|---|
| `MISSING_CREDENTIAL` | Provider 引用的凭据没有被解析 | 设置 → 模型中的凭据与环境变量 |
| `UNKNOWN_MODEL` | 当前 Provider 不认识所选模型 ID | Provider、模型 ID 与默认模型 |
| 获取可用模型返回 401 | `GET /models` 被服务拒绝 | 当前表单中的 Key 与 Base URL |
| 保存成功但实际请求 401 | 推理请求被服务拒绝 | Key 权限、端点、账号和请求路由 |
| Key 与地址正确但所有请求仍被拒绝 | 可能是 OpenAI 兼容请求形状不同 | Provider 的 `compat` 配置 |

## 第一步：记录错误发生阶段

先确认错误出现在：

1. 保存 Provider 时；
2. 点击“获取可用模型”时；
3. 选择模型并发送第一条消息时；
4. 只有某个旧会话或推理模型失败时。

不要只记录“模型不能用”。保留 Provider ID、模型 ID、Base URL 的域名、DSH 版本、错误 code 和经过脱敏的响应。不得记录完整 Key、Authorization Header、Cookie 或 `.credentials.yaml` 内容。

## 修复 MISSING_CREDENTIAL

在 Web UI 打开 `设置 → 模型`，进入当前会话所选的 Provider，重新确认凭据已保存。官方实现将密钥作为只写数据：保存后浏览器只收到脱敏描述符，明文保存在 `$DSH_HOME/.credentials.yaml`，settings 只保存凭据引用。

如果 Provider 使用环境变量，检查被引用的变量名是否存在于启动 DSH 的同一个进程环境。官方基础配置还会从继承环境、`$DSH_HOME/.credentials.yaml`、调用目录 `.env` 和 `$DSH_HOME/.env` 解析凭据来源。不要因为浏览器里看不到明文就反复创建多个同名 Key；先确认当前 Provider 实际引用哪一个来源。

检查完成后，新建一个会话，重新选择该 Provider 的模型，再发送不调用工具的最小请求。旧会话会保留自己日志中记录的模型，改变默认模型不会自动重写已经发送过请求的会话。

## 修复 UNKNOWN_MODEL

`UNKNOWN_MODEL` 与 Key 是否正确不是同一个问题。确认：

- 当前会话选择的模型属于哪个 Provider；
- 自定义 Provider 中确实保存了该模型 ID；
- 模型 ID 的大小写、前缀和拼写与服务要求一致；
- 默认模型没有继续指向已删除的 Provider。

官方 UI 在默认值指向已删除 Provider 时会要求重新选择模型，并在选择前阻止输入。对自定义 Provider，Provider ID 是持久标识；需要改名时应新建 Provider、迁移选择，再删除旧项。

## 修复“获取可用模型”返回 401

官方 Provider 指南说明，自定义 Provider 的模型发现会调用 OpenAI 兼容的 `GET /models`。出现 401 时先检查当前表单中的 Key 和 Base URL 是否属于同一个服务，Key 是否仍有效、未被撤销且具备所需权限。

有些服务根本不提供 `GET /models`。这种情况下，模型发现失败不等于推理端点一定不可用；按照服务的第一方文档手动填写模型 ID，再用最小请求单独验证。不要为了让列表加载而把 Key 发送到未经核验的代理地址。

## 保存成功但发送消息返回 401

这表示凭据记录存在，但远端推理请求没有通过认证。按以下顺序检查：

1. Key 是否属于当前 Base URL 对应的服务和账号；
2. Base URL 是否指向正确环境，而不是测试、旧网关或另一个供应商；
3. Key 是否过期、撤销、受 IP/组织/项目范围限制；
4. 企业代理是否改变了目标地址或认证 Header；
5. 服务第一方状态页和账户侧日志是否有明确拒绝原因。

这些属于服务端认证事实，DSH 不能通过重试自动修复。若 Key 曾出现在聊天、截图、终端历史或 Git 中，应先在服务端轮换，再清理本地暴露面。

## Key 正确但网关仍拒绝请求

OpenAI 兼容网关不一定接受完全相同的请求形状。官方指南给出的两个常见兼容点是：推理模型的系统提示词可能使用 `developer` 角色，输出上限可能使用 `max_completion_tokens`。只接受旧形状的网关可在对应 Provider 路由中审慎配置：

```yaml
llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: my-model
```

这段配置只适用于服务确实要求这些兼容项的情况，不是所有 401 的通用修复。401 首先是认证问题；请求形状不兼容更常见于 400 类或网关自定义错误。不要在没有服务端证据时盲目复制全部兼容开关。

## 安全验证和清理

修复后用新会话发送一句不调用工具的测试消息，确认模型回答，再逐步恢复文件或命令工具。最后检查：

- 浏览器仍只显示脱敏凭据；
- `.credentials.yaml` 和 `.env` 没有进入 Git；
- 日志和截图没有完整 Key；
- 测试 Key 可以轮换，并已删除不再使用的旧凭据；
- 记录 Provider、模型、DSH 版本和验证日期，但不记录秘密值。

不要通过放宽 DSH 文件权限来解决模型认证。Provider 凭据风险与 Agent workspace 权限是两个不同的安全边界。

## 本文的验证范围

本文完成了固定版本 Provider 页面、凭据存储说明、模型选择和官方排错条目的源码审阅。没有调用 DeepSeek 或第三方网关，也没有验证任意 Key、代理、账号权限或服务可用性。

需要从头配置模型时阅读[DeepSeek Harness 模型、API Key 与 Provider 配置](/tutorials/deepseek-harness-model-provider/)；如果 CLI 本身还不能启动，先解决[DSH Node 与 npx 环境错误](/errors/dsh-node-version-error/)。

## 原始来源

- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.1-rc.2
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/docs/user/guide/providers.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/packages/credentials/credentials-local/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/packages/llm/llm-pi-ai/README.md