报错排查：DeepSeek Harness 的 API key 不生效 / 找不到 provider

harness 的凭证问题干净地分成两类，修法相反。动手之前先确定你在哪一类。

出问题的是哪种服务商？

目录内服务商——你在 Settings → Add provider 里选了 DeepSeek / Anthropic / OpenAI 之类，然后在 界面上粘了 key。key 存在 $DSH_HOME/.credentials.yaml。

自定义服务商——你自己填了 provider ID、base URL、API 协议和模型列表。自定义服务商不存 key，它 按名字引用一个环境变量。

大多数「我 key 不好使」的反馈其实是第二类，被当成第一类去修了。

apiKeyEnv 这个坑

自定义服务商长这样：

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: vision-preview
          input: [text, image]

apiKeyEnv: GATEWAY_API_KEY 的意思是*「从名为 GATEWAY_API_KEY 的环境变量里读 key」*。它不是 key 本身。把真密钥粘到这儿会同时干两件坏事：认证失败，以及把一份活凭证写进了一个本来设计成可共享的配置 文件。

正确做法是在启动 dsh 的 shell 里 export：

export GATEWAY_API_KEY="sk-..."
dsh --profile web

为什么你 export 了却「没用」

这是第二常见的成因，纯粹是进程语义问题。

一个运行中的进程持有的是它启动时那份环境快照。往 ~/.zshrc 里加一行，改变的是以后的 shell 会 继承什么。对下面这些毫无作用：

• 已经在跑的 dsh 进程
• 你保存文件之前就打开的终端标签
• 从图形界面启动、根本没 source 过登录 shell 的终端

在你实际要启动的那个 shell 里验：

printenv GATEWAY_API_KEY

没输出就是没有，不管你的配置文件里写了什么。然后重启 dsh——不是只刷新浏览器标签。

先独立验证端点

怪 harness 之前，先确认这套凭证和地址本身能不能用：

curl -sS https://gateway.example/v1/models \
  -H "Authorization: Bearer $GATEWAY_API_KEY" | head -20

401 是 key 不对。404 通常是 baseURL 写错了——很常见的错是 /v1 后缀加没加，和 api: openai-completions 的预期对不上。连接错误是网络或 DNS，跟认证无关。

这一条命令就能把「harness 配错了」和「这凭证压根没生效过」分开，值得放在所有排查之前跑。

provider not found

如果报的是找不到服务商而不是认证失败，说明引用和定义对不上了。查两件事。

provider ID 是永久的。 改不了名。如果你试过改，现在就有一个模型引用指向了一个不存在的 ID。新建 一个你要的 ID，删掉旧的。

启动的未必是你改的那份配置。 把组装结果打印出来：

dsh --profile web --dump-config

记住 patch 顺序——bundle、profile 的 cordis.patch.yml、home 级的 $DSH_HOME/cordis.patch.yml、 最后 --patch。home 级的 patch 会盖掉你在 profile 里的改动，「我明明配了」的服务商消失，这是常见原因。

一份能解决大部分情况的清单

1. 在启动用的 shell 里 printenv <变量名>——变量真的设了吗？
2. 用那个 key curl 一下端点——凭证本身有效吗？
3. dsh --profile web --dump-config——你的服务商在组装后还活着吗？
4. 改完环境变量，把 dsh 完整重启。
5. 确认你没把密钥粘进 apiKeyEnv。