跳过主要内容
全部文章
教程

如何在 DeepSeek Harness 中配置 DeepSeek API Key 与模型

通过 Settings → Models 或 settings.yaml 配置 DeepSeek Harness 的 API key，理解 .credentials.yaml 的作用，并修复 MISSING_CREDENTIAL 报错。

要使用 DeepSeek Harness（dsh），打开 Web UI，进入 Settings → Models，把你的 DeepSeek API key 粘贴进 DeepSeek 卡片的 key 输入框——不需要重启。在底层，这个 key 会被写入 $DSH_HOME/.credentials.yaml，与非敏感的 settings.yaml 分开存放；如果你想用环境变量来设置它，dsh 会按一套明确定义的优先级顺序来解析凭据。本文讲清楚凭据存在哪里、解析顺序如何工作，以及两个最常见的鉴权错误。

模型配置存在哪里

dsh 把模型配置拆成两个文件，都存放在 $DSH_HOME（默认 ~/.dsh）下，并且跨所有 profile 共享——这一点和某个 profile 自己的 cordis.patch.yml（只作用于单个 profile）不同：

文件内容
$DSH_HOME/settings.yaml非敏感配置：模型路由、自定义 provider 的 base URL、协议、模型列表
$DSH_HOME/.credentials.yamlAPI key 等敏感凭据

Web UI 的 Settings 页面会自动同时写入这两个文件。如果你通过 Settings → Models 保存了一个 key，界面上只会回显一个脱敏的引用描述符——保存之后明文 key 不会再被回显。

配置 DeepSeek 官方 provider

最简单的路径，也是大多数人会用的方式：

  1. 打开 Web UI（npx @deepseek-ai/dsh web，默认 http://127.0.0.1:3080）。
  2. 进入 Settings → Models。
  3. 找到 DeepSeek 卡片——它只有一个字段，API key。
  4. 粘贴你的 key，保存。

就这样。改动会在你下一次请求时生效；不需要重启 dsh 进程。

凭据解析顺序

如果你完全不想通过 UI 存储 key——比如在 CI 任务或容器里——dsh 会按以下顺序依次解析凭据，共四个来源：

1. 继承的进程环境
2. $DSH_HOME/.credentials.yaml
3. 调用目录下的 .env
4. $DSH_HOME/.env

有个细节值得了解：通过 .credentials.yaml 托管的凭据永远不会被写入 process.env——这个文件是一个独立的、专门的凭据存储，不只是又一层环境变量。相比之下，两个 .env 文件是普通的启动环境层，优先级低于已经被应用解析出来的凭据。

一个具体例子：如果你想完全跳过 UI，改用环境变量为一次 headless/CI 运行设置 key，在调用 dsh 之前导出它即可：

export DEEPSEEK_API_KEY=your-key-here
dsh --profile headless "summarize the open pull requests"

需要注意的是，DEEPSEEK_API_KEY 具体被文档记录为 base bundle 里 web_search 工具（DeepSeek 原生搜索）所用的凭据，同时也是 Python SDK 示例脚本默认读取的模型鉴权变量名——它不一定是 dsh 模型路由层为每个 provider 都读取的同一个变量，所以如果你用这种方式接入非默认 provider，请检查 settings.yaml 里实际引用的变量名。

添加非 DeepSeek 的 provider

如果你想用 Anthropic、OpenAI，或者 dsh 内置目录里已有的其他 provider，在 Settings → Models 里选 Add provider 而不是用 DeepSeek 卡片。填入 API key 通常就够了——目录内置 provider 的 endpoint、协议、模型列表都已经写死。

有几个 provider 需要的不只是一个 API key，因为它们用的是原生鉴权方式而不是 bearer token：

Provider实际需要什么
BedrockAWS 凭据
VertexGoogle Application Default Credentials + 项目
Azure除了 key 之外还需要一个 api-version
CodexOAuth，不是静态 API key

如果你要接的东西不在 dsh 内置目录里——自建的模型网关、公司内部代理，或任意 OpenAI 兼容端点——完整的自定义 provider 配置流程见 在 DeepSeek Harness 中使用 OpenAI、Anthropic 或任意 OpenAI 兼容 API，包括如何为视觉模型声明图片输入支持。

凭据是所有 profile 共享的

有一点值得明说：模型 provider 配置存在 $DSH_HOME 下，不属于任何单个 profile 目录。也就是说，如果你同时跑多个 profile——比如一个用于交互式工作的 web profile，和一个用于脚本化运行的独立 ci-headless profile——它们读的是同一份 settings.yaml 和 .credentials.yaml。你只需要配置一次 provider，之后启动的每一个 profile 都能用它；不需要为每个 profile 单独维护一份重复的凭据。profile 作用域的配置（哪些插件生效、工具默认值、沙箱微调）是完全独立的一层，写在该 profile 自己的 cordis.patch.yml 里。

这也意味着，一个泄露或权限过宽的凭据不会被限制在单个 profile 内——如果你在跑多个信任级别明显不同的 profile，请把这个共享作用域的事实记在心里。

验证配置是否生效

保存 key 之后，最快的验证方式是跑一次简单的 headless 调用，因为它会直接把结果打印到终端，完全不需要打开 Web UI：

dsh --profile headless "reply with the word 'ok' and nothing else"

如果它返回 ok 并以退出码 0 结束，说明你的模型 provider 和凭据已经端到端配置正确。如果失败了，错误文本会指向 MISSING_CREDENTIAL 或 UNKNOWN_MODEL 其中之一——下面的表格讲清楚每一个分别是什么意思、怎么修复。

常见错误与修复

错误原因 / 修复
MISSING_CREDENTIAL所选模型/provider 没有解析出任何 key——通过 Settings → Models 设置，或者通过上面任意一个凭据解析来源提供
UNKNOWN_MODEL你选择的模型 ID 没有在任何地方注册——换一个已配置的模型，或者把缺失的模型 ID 加到你的自定义 provider 模型列表里
Fetch available models 返回 401你的 API key 对该端点无效。这个按钮具体调用的是 OpenAI 兼容的 GET /models 端点——如果你的 provider 没实现这个端点，就需要手动填写模型 ID
附带的图片在发送前被拒绝你用的模型没有声明 input: [text, image]——具体 YAML 写法见自定义 provider 指南

FAQ

DeepSeek Harness 到底把我的 API key 存在哪里？

存在 $DSH_HOME/.credentials.yaml（默认 $DSH_HOME 是 ~/.dsh）里，这个文件和非敏感的 settings.yaml 是分开的。Web UI 保存之后不会再把明文 key 显示给你——只会显示一个脱敏的引用。

改完 API key 之后需要重启 dsh 吗？

不需要。通过 Settings → Models 保存的 key，在你下一次请求时就会生效。

我能用环境变量而不是 Web UI 来设置 API key 吗？

可以——dsh 的凭据解析顺序里，继承的进程环境是第一个被检查的来源，优先级高于 .credentials.yaml 和两个 .env 位置。这也是 CI 和 headless 自动化的典型路径。

DEEPSEEK_API_KEY 具体控制什么？

它被文档记录为 base bundle 里原生 web_search 工具所用的凭据，也是 Python SDK 示例脚本默认读取的模型鉴权变量名。对于其他 provider 或自定义端点，请检查你 settings.yaml 条目里实际引用的变量名是什么。

我配置了一个 provider，但还是报 UNKNOWN_MODEL，哪里出了问题？

你选择的模型 ID 没有在任何已配置 provider 的 settings.yaml 里注册。要么换一个已配置的模型，要么把缺失的模型 ID 加到该 provider 的 models 列表里——具体 YAML 格式见 在 DeepSeek Harness 中使用 OpenAI、Anthropic 或任意 OpenAI 兼容 API。

Next steps