模型与服务商

为当前对话选择模型#

输入区的模型选择器按已配置的连接提供模型候选。新会话在发送首条消息之前，可以同时选择连接与该连接下的模型；选择会保存到会话。

首条消息发出后，连接锁定。同一连接内可以换模型；要换服务商、凭据或另一条连接，需新建会话后再选择。换模型不会更改来源与技能。

1. 新建会话，打开输入区的模型选择器，先确认连接名称，再选择模型。
2. 如果所选模型提供推理强度选项，按任务需要调整。
3. 发送第一条消息前再次核对连接。已有消息时，要换连接请新建会话；只换模型时，从当前连接提供的模型中选择。

模型来自哪里#

模型来自你配置的模型连接。标准服务商使用运行时的服务商模型目录或你保存的模型选择；自定义端点使用 models 中明确列出的模型 ID。

桌面首次设置选择 ZeroWorks，可在浏览器完成登录与应用授权；成功后客户端保存该账号的模型连接与可用模型。只登录控制台不会触发这一步，需要从客户端发起授权。

1. 打开“设置 → AI”，查看已有模型连接、认证状态和模型列表。
2. 列表为空时，先确认已保存连接与正确的模型 ID；自定义端点不会仅凭 URL 自动补出完整能力信息。
3. 新建会话选择这条连接，发送一条简短文字请求，确认真实调用成功。

连接如何工作#

连接把请求地址、认证方式、后端与模型列表绑定在一起。当前 providerType 使用 anthropic、pi 或 pi_compat；自定义兼容端点使用 pi_compat，并通过 customEndpoint.api 选择协议。

连接在会话首条消息后锁定。即使另一条连接提供同名模型，也不能在已有会话中跨过去；请保留必要上下文，再新建会话选择目标连接。

来源连接与模型连接独立。已列出模型不等于端点、凭据、额度、流式返回和工具调用都经过验证。

• 同一连接内换模型：在当前会话的模型选择器中完成。
• 更换连接：新建会话，在首条消息之前选择。
• 中途发送行为保存在连接的 midStreamBehavior：queue 等待当前轮结束，steer 尝试把补充信息送入当前轮，后端不支持时可能退回中断后排队。
• 未配置 midStreamBehavior 时，anthropic 默认 queue；pi 与 pi_compat 默认 steer。可选决策层的 midTurnMessages 是额外功能，需要单独启用。

连接配置字段#

在“设置 → AI”添加或编辑连接。手工编辑 ~/.zero-works/config.json 时，把连接对象放入 llmConnections 数组，保留其他配置；API Key 在专用凭据表单保存。

配置自己的模型服务商#

自备服务商会按你填写的方式接入。保存前先确认接口地址、模型标识与凭据三项都来自服务商的官方说明，避免按印象填写。

同一个服务商可以保存多份配置，用不同接口地址区分不同环境。这样测试环境与生产环境的模型标识不会互相覆盖，切换时也更直观。

1. 打开“设置 → AI”，添加连接，按服务商选择认证方式与后端。
2. 自定义端点选择匹配的协议，填写服务基地址与模型 ID；有认证时在专用字段保存 Key。
3. 执行连接检查，再新建会话选择这条连接，发送短文字并检查流式返回。
4. 需要工具或图片时，分别验证对应调用；图片还需显式启用能力开关。实际验证成功前，不把“已保存”当作“已接通”。

自定义端点#

任意兼容端点使用 providerType: pi_compat。customEndpoint.api 为 openai-completions 时走 OpenAI Chat Completions；为 anthropic-messages 时走 Anthropic Messages。协议选择不能用 URL 或模型名称代替。

下面是 llmConnections 数组中一项的有效结构，以本机 Ollama 的 gpt-oss:20b 为例。先在运行 Agent 的主机安装并运行 Ollama、加载该模型，核对它实际配置的上下文大小；示例不表示已经替你运行或验收。

本地地址 http://localhost:11434/v1 与模型调用方式见 Ollama 官方兼容文档。远程 Agent 的 localhost 指向服务器，不能指向你的客户端。

1. 退出 ZeroWorks 并备份 config.json；把示例连接合并到 llmConnections，保留工作区列表等已有字段。
2. 本地无认证使用 none；需要 Key 的远程兼容服务改用 api_key_with_endpoint，填写真实 baseUrl 与模型 ID，重启后在连接表单保存 Key。
3. 若服务使用 Anthropic Messages，把 customEndpoint.api 设为 anthropic-messages，baseUrl 填服务文档要求的基地址，不填完整的 /v1/messages 请求路径。
4. 重启后新建会话选择该连接，先验证短文字，再验证工具调用；支持图片的模型须在模型设置启用图片，或明确写 models[].supportsImages: true。

• 图片能力优先级：models[].supportsImages > customEndpoint.supportsImages > false。某个模型显式 false 会覆盖连接级 true。
• contextWindow 与服务端真实窗口保持一致，避免压缩触发太晚；它不是单次输出长度。
• maxTokens 是单次输出上限，默认 8192。若长会话摘要因输出空间不足而压缩失败，在服务端允许范围内提高该值后重试，并检查真实窗口。
• 本机服务使用它实际监听的 http 或 https 协议；企业或远程服务不要机械改为 http。

{
  "slug": "ollama-local",
  "name": "Ollama local",
  "providerType": "pi_compat",
  "authType": "none",
  "baseUrl": "http://localhost:11434/v1",
  "models": [
    {
      "id": "gpt-oss:20b",
      "name": "gpt-oss:20b",
      "shortName": "gpt-oss:20b",
      "contextWindow": 131072,
      "supportsImages": false
    }
  ],
  "defaultModel": "gpt-oss:20b",
  "customEndpoint": {
    "api": "openai-completions",
    "supportsImages": false,
    "maxTokens": 8192
  },
  "midStreamBehavior": "steer",
  "createdAt": 1793059200000
}

配置完成后仍无法调用#

配置已保存、模型出现在列表中和请求成功是不同的状态。遇到失败时，根据页面提示逐项确认，不要跳过其中任何一步。

从最基础的一步开始排查：先用纯文字发一条短请求确认连接可用，再逐项排除额度、权限与输入类型的问题。

• 凭据失效：更新这条连接的访问凭据，刷新模型后再选择模型。
• 授权或额度不足：检查这条连接的使用权限、可用额度和服务商状态。
• 连接失败：检查服务地址、模型标识及凭据是否正确或已过期。
• 输入类型不支持：先用纯文字测试，再按模型实际能力添加其他材料。
• 没有返回内容：确认端点实现了所选连接方式要求的请求格式与流式返回。
• 连接锁定：已有消息的会话不能换连接。新建会话选择目标连接后再测试；同一连接内仍可换模型。
• 模型名不一致：模型标识必须与服务商要求的名字完全一致。
• 图片被拒：核对单模型和连接级 supportsImages，不能只看模型名称或资料标签。
• 长会话无法压缩：核对 models[].contextWindow，并在服务端允许范围内调整 customEndpoint.maxTokens。