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

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

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 路由中审慎配置：

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 配置；如果 CLI 本身还不能启动，先解决DSH Node 与 npx 环境错误。