Jan Agent

运行一行 `jan config set --base-url https://api.kunavo.com/v1` 即可将 Kunavo 写入 ~/.jan/config.toml，Jan Agent 预览 CLI（不自带推理引擎）会使用该密钥运行。

# Jan Agent is a preview on a nightly channel — check your build first.
jan --version

jan config set \
  --provider kunavo \
  --api-key sk-kn-... \
  --base-url https://api.kunavo.com/v1 \
  --model claude-sonnet-5 \
  --model claude-haiku-4-5 \
  --api-type openai

jan config list   # configured providers as JSON, keys redacted

分步操作

1. 在 /app/keys 创建密钥并复制——它只会显示一次。
2. 先确认你正在配置的程序：jan --version。Jan Desktop 也附带通过 jan 调用的 CLI，但命令集不同，因此先确认 jan config set --help 会列出 --base-url，再输入其余内容。
3. 运行上面的 jan config set 命令。--provider 是你自行选择的 ID，而非固定列表中的名称——文档中的本地硬件示例使用 --provider local——且 --model 可重复使用；它会替换任何现有列表，而不是追加条目。
4. 使用 jan config list（密钥已隐藏）或 jan config path 检查文件，确认配置已写入；随后运行 jan cli models list 查看每个 provider 提供的内容。手动输入的模型 ID 即使端点不再列出它也会保留；而 jan cli models refresh --provider kunavo 会以端点返回的列表为准。
5. 切换到一个项目并运行 jan，然后用 /model 选择模型。首次运行建议使用 jan --plan：它是只读操作，因此协议不匹配会在任何内容写入磁盘之前显现。
6. 给它一个需要编辑文件的任务。Jan Agent 是代理，因此首次运行应检验工具调用和流式传输——如果端点仅部分兼容，这两项最先可能出问题，而问候语测试不了其中任何一项。

已于 2026年9月21日 对照 Jan Agent 的 Providers 页面 检查。第三方设置会发生变化；如果这里的字段名称不再与你看到的内容一致，应以该页面为准，而不是本页。

调试客户端前先验证

一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON，则相同的基础 URL 和密钥可以在 Jan Agent 中使用。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

字段中应填写哪个模型 ID

每个文本模型都可通过模型 ID 访问——实时列表见 GET /v1/models，包含价格的目录见模型页面。费率单位为每 1M token 的美元，格式为输入 / 输出。

两种不同的东西都叫作 Jan API 密钥

它们位于同一个文件中，含义却截然相反，因此如果你预期的是另一种含义，jan config list 看起来就可能不对。

Jan Desktop 不会签发上述任何一种密钥：它没有账户，因此无处生成密钥。其本地 API 服务器使用由你自行编造的密钥，这又是第三种含义，适用于另一台主机。

Jan Desktop 会传递哪些内容，以及传递到哪里为止

Jan Agent 会按优先级读取四个 provider 设置来源，后面的来源会覆盖前面的设置；其中第二个来源最容易让人意外。

1. ~/.jan/config.toml——基础配置，也是唯一会由 jan config set 写入的文件。
2. Jan Desktop 的 settings.json——仅继承。它会添加你尚未在 Agent 中配置的 provider，不会覆盖已有配置，也不会将设置写回。
3. 项目 agent.toml 中的 [provider] 块——这是明确的项目级选择，因此优先级高于前两者。该文件通常会提交到版本库，因此请勿将 api_key 放入其中。
4. 命令行中的 --provider / --api-key 或 JAN_API_KEY / <PROVIDER>_API_KEY——优先级最高，也最临时。

调试之前，有两个后果值得了解。jan config list 可能显示没有 provider，而 jan cli models list 却会返回很多结果——后者包含从 Desktop 继承的 provider，而这些配置并未存储在 ~/.jan/config.toml 中。继承的 provider 也不会更新，因为此处没有可供重写的条目：如果你希望 Kunavo 的模型列表保持最新，就必须创建独立的 jan config set 条目；上面的配置块正是这样做的。

两个 provider 提供相同模型 ID 时

Kunavo 提供 claude-sonnet-5 等 ID，直接指向模型供应商的 provider 条目也可能提供相同 ID。Jan Agent 必须择一使用，文档列出的顺序是：先匹配某个 provider 的 models 列表中的精确 ID，然后匹配指定已配置 provider 的 <provider>/<model> 前缀；如果多个 provider 都提供相同 ID，则优先选择配置了凭据的 provider，而非无密钥的同名条目。因此，使用 kunavo/claude-sonnet-5 即可指定你的选择。该限定符仅供 Jan 使用——发送请求之前会将其移除，因为上游服务不接受带 provider 限定符的 ID。

在控制台中使用相同条目

如果你不想输入标志：/settings > providers 可管理相同的 ~/.jan/config.toml 条目；a 会打开添加表单，其中包含 name、base url、api key 和以空格分隔的 models 字段。此表单还有两项命令行标志不具备的功能：基础 URL 必须是 https://（localhost 端点则必须是 http://），确保密钥不会通过明文远程连接发送——Kunavo 使用 https://，因此不受此限制；编辑时，API 密钥字段会显示 (unchanged)，除非你在其中输入内容，否则会保留已存储的密钥。清空该字段会删除密钥，而不是保留原值。