跳到主要内容
文档导航

模型与认证

Deskmate 本身提供桌面工作台、Agent 配置、工具系统和本地数据管理。真正的 AI 推理由你配置的模型 provider 完成。本页帮助你理解 provider 是什么、如何完成认证、不同模型的能力差异，以及遇到认证错误时如何排查。

模型 provider 是什么

Deskmate 本身提供桌面工作台、Agent 配置、工具系统和本地数据管理。AI 推理由你配置的模型 provider 完成。

需要理解几点：

  • Provider 可能是云端模型服务。
  • 可用模型以应用内列表为准，不以官网描述为准。
  • 不同 provider 的认证方式不同（OAuth 或 API key）。
  • 模型能力不同：工具调用、图片输入、reasoning、上下文长度等。

配置 provider

  1. 打开 Settings。
  2. 进入 Provider / Models 区域。
  3. 选择 provider。
  4. 按提示完成 OAuth 或填写 API key。
  5. 回到 Agent 配置，选择模型。
  6. 发送一条测试消息确认链路可用。

测试消息：

请用一句话回复：Deskmate provider 配置已可用。

如果模型按要求回复，说明 provider 认证与模型选择都已生效。

OAuth vs API key

不同 provider 提供不同的认证方式。两种方式的取舍如下：

方式 适合场景 优点 注意事项
OAuth provider 支持网页登录授权 不需要手动复制 key，可刷新 token 需要浏览器登录；token 可能过期
API key provider 提供 key 简单直接，易于服务端/本地配置 key 泄漏风险；需要用户自己管理

无论哪种方式，凭证都应只来自你信任的 provider，并保存在本地 profile 中。不要把 API key 写进 Agent knowledge 或聊天内容。

模型能力

不同模型适合不同任务

选择模型时可以关注以下能力维度：

  • Tool calling：能否稳定调用工具。
  • Reasoning：是否支持推理强度控制。
  • Vision：是否支持图片输入。
  • Context：上下文窗口大小。
  • Latency：响应速度。
  • Cost：调用成本。

实践建议：

  • 第一个 Agent 选择支持工具调用的通用模型。
  • 长文档和复杂代码任务选择上下文更大的模型。
  • 快速摘要选择低延迟模型。
  • 模型清单以应用内为准，不要依赖官网或文档里的硬编码列表。

Thinking / reasoning level

部分模型支持 reasoning level。Deskmate 会把 Agent 的 thinking level 透传给模型适配层，由 provider 以自己的方式执行。

不同 level 的大致取向：

  • Auto / default：适合大多数任务。
  • Low：快速、轻量任务。
  • Medium：一般分析。
  • High / xhigh：复杂推理、代码设计、排障。

需要注意：

  • 不同 provider 对同一 level 的语义可能不同。
  • 切换模型后，thinking level 可能需要重新选择。
  • 更高的 reasoning 可能更慢或更贵。

凭证存储

Provider 凭证保存在当前 profile 的本地数据目录中。未登录或未配置时，对应 auth 文件可能不存在。

注意事项：

  • 不要把凭证提交到代码仓库。
  • 不要把 key 放进 knowledge。
  • 共享 ~/.deskmate/ 备份时注意其中可能包含凭证。

常见错误

未认证 / token expired

原因：provider 凭证缺失或过期。

处理：回到 Provider 设置重新登录或更新 API key。

Unknown model

原因：模型不在当前 provider 的可用列表中，或配置已过期。

处理：刷新模型列表，选择应用内显示的模型。

Model does not support tools

原因：当前模型不支持工具调用。

处理：换用支持工具调用的模型。

Rate limit

原因：provider 限流。

处理：稍后重试，降低并发，或更换 provider / plan。

Network error

原因：网络、代理、provider 服务异常。

处理：检查网络，查看 provider 状态，查看 Deskmate 日志。

安全建议

  • API key 只保存在应用认证配置中。
  • 不把 key 发给 Agent。
  • 不在截图或 issue 中泄露 token。
  • 使用最小权限的 provider key。
  • 定期撤销不再使用的凭证。

下一步