用自定义 LLM provider 把 Router One 模型接入 Zed Agent

在 Zed 1.21 里找到正确的设置入口

Zed 1.21 有两个设置入口。agent: open settings（即 agent::OpenSettings 操作，也可从 Agent Panel 右上角菜单进入）会打开图形化的设置编辑器并定位到 AI 页面，其中 LLM Providers → Add Provider 会让你填写 provider 名称、API URL、模型 ID 和上下文窗口，配置单个模型用这个表单就够了。要配置多个模型、能力开关和后台功能使用的模型，请直接编辑 JSON：zed: open settings file（zed::OpenSettingsFile）会打开 settings.json，在 macOS 和 Linux 上位于 ~/.config/zed/settings.json（除非 XDG_CONFIG_HOME 指向别处）。旧教程里的 zed: open settings 现在打开的是图形化编辑器，而不是这个文件。开始之前，先为 Zed 创建一把设了 maxSpend 消费上限的 Router One Key：Agent 会话每一轮模型调用都是一次请求，后台功能还会发出各自的请求。

把 Zed 配置到 Router One base URL

在 language_models 下添加 openai_compatible 配置。router-one 是 provider ID：选择器里的模型以它标注，Key 的环境变量名也由它得出。api_url 填带 /v1 的 base URL，因为 Zed 会自己拼上 /chat/completions。available_models 中的每一项就是选择器里的一个模型：name 是精确的目录 ID，会作为 model 字段发出；display_name 只是显示名称；max_tokens 是该模型的上下文窗口，写成整数。/models 上的模型详情页显示的是取整后的缩写（1.05M、200K），请换算成整数并往小取（1000000、200000）；Zed 也用这个值决定何时压缩会话，默认在窗口用到 90% 时触发。Zed 对自定义模型的能力默认值——tools 开、images 关、chat_completions 开、max_tokens_parameter 关——适合大多数纯文本工作，所以示例没有改动它们，何时需要调整见后面几节。reasoning_effort（none、minimal、low、medium、high、xhigh 或 max）会在 Agent Panel 中为该模型开启思考，并以 reasoning_effort 发出。对 Claude 系列 ID，Router One 不会把它转换为 thinking 设置；Claude Opus 5.5 例外，会映射到 output_config.effort（none 与 minimal 记为 low）。其他模型可能忽略它，或以 400 拒绝请求。除非你要自定输出上限，否则不要写 max_output_tokens；Key 永远不要写进 settings.json：

{
  "language_models": {
    "openai_compatible": {
      "router-one": {
        "api_url": "https://api.router.one/v1",
        "available_models": [
          {
            "name": "anthropic/claude-sonnet-5",
            "display_name": "Claude Sonnet 5 · Router One",
            "max_tokens": 1000000
          },
          {
            "name": "openai/gpt-5.5",
            "display_name": "GPT-5.5 · Router One",
            "max_tokens": 1000000,
            "reasoning_effort": "medium"
          }
        ]
      }
    }
  }
}

把 Key 交给 Zed：系统凭据存储或 ROUTER_ONE_API_KEY

Zed 不在 settings.json 里存放 provider 的 Key。在 Settings → AI → LLM Providers 页面、router-one provider 旁边粘贴 Key，Zed 会把它存进系统的凭据存储（keychain）。也可以在 Zed 启动时所在的环境里设置环境变量：变量名是 provider ID 转成大写下划线形式再加 _API_KEY，所以 router-one 读取的是 ROUTER_ONE_API_KEY。非空的环境变量优先于凭据存储中的值，这也是「新粘贴的 Key 好像没生效」最常见的原因；要停用它，请删除该变量并重启 Zed。对于 SSH、开发容器等远程项目，Zed 从本机的凭据存储和本机 Zed 进程的环境变量读取 Key，而不是从远程机器读取。无论哪种方式，Key 都保存在你的电脑上，所以用一把设了 maxSpend 上限的专用 Key，可以限制 Key 泄露时的损失。

设置 Agent 的默认模型和后台功能用的模型

agent.default_model 决定新建 Zed Agent 会话时使用的模型。Zed 的后台功能可以各自使用单独的模型：commit_message_model 写 Git 提交信息，thread_summary_model 生成会话摘要，inline_assistant_model 运行 Inline Assistant，subagent_model 运行子 Agent，compaction_model 压缩长会话。openai_compatible provider 自身没有声明快速模型，所以想让这些功能用更便宜的 ID，就要显式地以 provider 和 model 组合逐项指定；这里指定的每个模型也都必须列在 available_models 里。Zed 文档要求压缩模型的上下文窗口不小于会话所用模型的窗口，所以 1M 窗口模型的会话需要一个同样 1M 窗口的压缩模型，例如 deepseek-v4-flash，而不是只有 200K 窗口的 anthropic/claude-haiku-4.5。提交信息和会话摘要没有这项限制。自动压缩默认在窗口用到 90% 时触发，可以用 agent.auto_compact.threshold 调整，在消息编辑器里输入 /compact 则可以手动压缩。

{
  "agent": {
    "default_model": { "provider": "router-one", "model": "anthropic/claude-sonnet-5" },
    "commit_message_model": { "provider": "router-one", "model": "anthropic/claude-haiku-4.5" },
    "thread_summary_model": { "provider": "router-one", "model": "anthropic/claude-haiku-4.5" },
    "compaction_model": { "provider": "router-one", "model": "deepseek-v4-flash" }
  }
}

每个能力开关在网关侧改变了什么

能力开关决定 Zed 在每次请求里放什么内容，所以 Zed 接 Router One 时的大多数问题都从这里开始。要修改某个开关，请在 available_models 中该模型的条目里加一个 capabilities 对象。这个对象请从 Zed 文档的 OpenAI 兼容示例里整段复制，不要只写你想改的那一项：对象里的大多数开关没有默认值，只写一部分会导致配置无法加载。然后按下表修改相应开关，Zed 示例中的其他开关保持原样即可。

可选：通过 /v1/messages 调用 Claude 与 DeepSeek

Zed 还提供 anthropic_compatible provider，用于实现了 Anthropic Messages API 的服务；Router One 在 /v1/messages 上原生提供当前目录中的 Claude 系列 ID 与 DeepSeek ID。它的 api_url 填主机根地址 https://api.router.one，因为 Zed 会自己拼上 /v1/messages，并把 Key 放在 X-Api-Key 请求头中、同时发送 Anthropic-Version 2023-06-01。如果 api_url 以 /v1 结尾，实际路径会变成 /v1/v1/messages，Router One 会返回 404，并提示去掉末尾的 /v1。请给这个 provider 一个独立的 ID，例如 router-one-messages，这样它的 Key 变量就是 ROUTER_ONE_MESSAGES_API_KEY。这个 ID 必须与 openai_compatible 的配置不同：同一个名字在两处都配置时，Zed 保留 OpenAI 兼容的那一项，并在日志中把 Anthropic 那一项记为被覆盖。它的能力默认 tools 为 true、images 为 false；Claude 的 ID 在详情页标明支持图像输入，要把 images 设为 true，请像示例那样写全这个对象的三个开关。上面的 OpenAI 兼容 provider 已经能调用同样的模型，只有想让它们走原生 Messages API 时才需要加这一项；添加某个 ID 之前，先确认模型详情页列出了 POST /v1/messages。

{
  "language_models": {
    "anthropic_compatible": {
      "router-one-messages": {
        "api_url": "https://api.router.one",
        "available_models": [
          {
            "name": "anthropic/claude-sonnet-5",
            "display_name": "Claude Sonnet 5 · Messages",
            "max_tokens": 1000000,
            "capabilities": { "tools": true, "images": true, "prompt_caching": false }
          }
        ]
      }
    }
  }
}

这个 provider 管不到的部分：External Agents

你添加的 LLM provider 服务于 Zed Agent、Inline Assistant、提交信息和会话摘要。通过 Agent Client Protocol 运行的 External Agents 自己负责认证和计费：Zed 文档写明，为 Zed Agent 配置的 Anthropic API Key 不会自动配置 Claude Agent，OpenAI API Key 也不会配置 Codex。这些 Agent 使用各自的登录流程或配置，如何接入自定义端点取决于具体的 Agent；Claude Code 与 Codex 接入指南介绍了这两个工具各自的配置方式。在控制台 → 日志中，Zed Agent 的每一轮都记在你给 Zed 的那把 Key 下，每条请求显示模型、tokens、费用、状态、总耗时，以及产生过输出的流式请求的首字延迟（TTFT）。

Zed 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Zed 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个客户端或应用单独建 API Key，并设置 maxSpend 消费上限。

Zed 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在请求日志里核对 Zed 的调用

先在 Zed 发出一次简单文本请求，再到控制台 → 日志按时间、模型和 request_id 找到这条记录，核对 Token、花费、总耗时和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题