DeepSeek Harness 模型配置：provider 与 API 凭据管理

模型配置的主入口是 Web UI 的 设置 → 模型，也可以在 $DSH_HOME/settings.yaml 里直接改。一个关键认知先行：模型变更在下一次请求生效，不需要重启服务器——你随时可以在会话中切换模型做对比实验。

密钥的三个落点，各司其职

理解凭据如何流动，排错就简单一半：

落点	存什么
`$DSH_HOME/.credentials.yaml`	明文密钥（唯一存放处）
`settings.yaml` / 模型页	只存凭据引用（描述符），不含明文
环境变量	密钥也可以来自环境变量（如`GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN` 的写法）

模型页保存密钥时，界面只会收到脱敏描述符——这是刻意设计，防止密钥出现在截图、日志、浏览器扩展眼里。所以"保存后密钥不见了"是正常现象。

三类提供方，按需选择

1. 默认：DeepSeek

模型页的 DeepSeek 卡片，输入 API 密钥保存即用。

2. 目录提供方（Anthropic、OpenAI 等）

点 添加提供方，选 Anthropic 或 OpenAI 等，输入各自 API 密钥。已安装的目录会自带端点、协议和模型列表，省去手填。

例外：Bedrock、Vertex、Azure、Codex 这类原生认证的提供方不吃普通 API 密钥——分别要 AWS 凭据+区域、ADC 项目、api-version、OAuth。只填密钥字段配不成。

3. 自定义提供方（公司网关 / 自建服务 / OpenAI 兼容端点）

点 添加自定义提供方，手填：

Provider ID（小写）：路由身份，永久不可改——请求、历史会话、默认模型、凭据引用都靠它。想改名只能"新增 + 删旧"
基础 URL + API 协议 + 凭据 + 至少一个模型

配完可用"获取可用模型"探测（走 OpenAI 兼容的 GET /models）；不提供该端点的服务手动输入模型名即可。

模型选择与切换的规则

已配置的提供方会出现在模型选择器里
选中即设为新会话的默认模型
每个会话的模型记录在自己的日志里，已发过请求的会话不随默认值变化——换个默认模型，老会话还是老模型
若默认值指向已删除的提供方，输入框会显示"选择模型"并阻止输入，直到重选

常见报错速查

报错	处理
`MISSING_CREDENTIAL`	模型页存密钥，或保证被引用的环境变量存在
`UNKNOWN_MODEL`	选一个已配置模型，或给自定义提供方补上该模型
获取模型返回 401	密钥错了。查`GET /models` 用的凭据
图片请求被拒	见下节——该模型没声明图片模态

进阶：给自定义模型声明图片输入

自定义提供方手输的模型默认一律按纯文本对待，传图片会在发送前被拒。要在 settings.yaml 里给模型声明：

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]      # 声明此模型接受图片