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

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

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

本文原有聊天 Provider 与凭据配置说明固定审阅 0.1.1-rc.2；新增搜索小节单独审阅 0.1.5-alpha.1，不将旧配置示例视为新版通用设置。本站没有使用真实 API Key 发起请求。不同第三方网关的状态码和错误正文可能不同，应保留原始响应再判断。

0.2.0-rc.2：用 DeepSeek 账号登录时的网页搜索

2026-09-30 按 0.2.0-rc.2（639ed015397290b3745d163aafe02ffee4aa3f84）固定源码复核；本节只说明 DeepSeek 原生网页搜索的凭据选择，下方其他内容保留各自的版本范围。本站没有登录账号或发起真实搜索。

0.2.0 起，使用 DeepSeek 账号模型的会话，网页搜索可以直接用账号鉴权，不需要额外配置 API Key。凭据按下面的顺序选择：

报 WEB_PROVIDER_CREDENTIAL_MISSING 时，先确认当前会话选的是账号模型还是 API Key 模型：

• 想用账号搜索：确认已登录，并且没有用 DEEPSEEK_SEARCH_BASE_URL 或 baseURL 把搜索端点指向别的地址；
• 走 API Key：按下方步骤配置搜索用的 Key。

搜索端点默认 https://api.deepseek.com/anthropic/v1，与聊天使用的 DEEPSEEK_BASE_URL 相互独立。

依据：DeepSeek 网页搜索提供方说明 ↗（外部链接，在新标签页打开）、0.2.0-rc.1 发行说明 ↗（外部链接，在新标签页打开）。

快速判断表

先确认：是哪一种搜索实现返回错误

工具名、实际加载的插件与请求目标一起核对；聊天成功不能证明搜索凭据正确。不要把某个后端的 Key 或 Base URL 同时复制给所有搜索插件。

如果尚不确定实现，先记录工具名称、已加载插件及脱敏目标域名，再进入对应教程。不要公开请求头、Cookie 或完整配置。本节只补后端分流，未重新验证各插件的运行兼容性。

聊天能用，为什么只有 web_search 返回 401？

切换聊天 Provider 不代表搜索配置同步改变。以下仅对应 0.1.5-alpha.1 固定提交的第一方 web-search-deepseek；其他搜索实现需查看自己的设置，不能直接套用。

固定源码给出的入口为 Settings → Plugins → Plugin configuration → Web search（界面译名可能不同）。搜索使用 Anthropic-compatible Messages API，默认基地址为 https://api.deepseek.com/anthropic/v1，实现会追加 /messages，不会复用聊天的 DEEPSEEK_BASE_URL。

按这个顺序检查：

1. 确认 401 来自搜索请求，记录目标域名、状态码及脱敏错误，不公开认证头或完整请求正文。
2. 核对 web-search-deepseek.baseURL；未设置时依次使用 DEEPSEEK_SEARCH_BASE_URL 和上述默认地址。只配置你信任且支持该搜索能力的 Anthropic Messages 服务，不把聊天的 OpenAI-compatible 地址直接复制过来。
3. 核对搜索的 apiKeyEnv 凭据引用，默认名称为 DEEPSEEK_API_KEY。实现通过凭据服务解析；只有没有该服务时才回退到启动环境。不要因为聊天成功，就假设搜索引用解析到了同一把 Key。
4. 若已配置非空 apiKey 字面值，也需检查是否过期或指向其他服务；优先使用凭据引用，不将 Key 粘贴到聊天、问题报告或公开配置。确认目标服务的账号权限与搜索能力支持。
5. 在允许发起搜索的测试场景中分别验证普通聊天和搜索结果，并记录结果。若仍失败，保留脱敏响应交由对应服务排查，不反复更换正确的聊天配置。

401 优先检查认证匹配；403 检查服务权限或策略，429 检查限流或配额，超时检查连接与服务响应。最终以目标服务的错误正文为准，这些错误不能统一靠更换 Key 解决。

依据：固定搜索配置与凭据实现 ↗（外部链接，在新标签页打开）、固定搜索 Provider 与入口提示 ↗（外部链接，在新标签页打开）。#6023 ↗（外部链接，在新标签页打开）是用户需求线索，实际账号的失败原因仍需逐例判断。本站只完成源码审阅，未执行聊天或搜索调用；聊天配置详见Provider 指南。

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

先确认错误出现在：

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 环境错误。