Zed 编辑器自定义模型配置

先说结论:settings.json 里一个块

Zed 原生支持自定义 OpenAI 兼容 provider。在 settings.json 的 language_models.openai_compatible 下加一个 provider 条目,api_url 设成 https://api.kkaiapi.com/v1,在 available_models 下声明每个想用的模型,带上名字和上下文大小。这些模型会立刻出现在 Agent 面板的模型下拉里。 API Key 刻意不放在 settings.json 里。通过 provider 设置界面输入时,Zed 会把它存进系统密钥链;或者从一个由你的 provider key 派生出来的环境变量里读取:一个叫 kkaiapi 的 provider 会读 KKAIAPI_API_KEY。环境变量的优先级高于密钥链里存的值。

{
  "language_models": {
    "openai_compatible": {
      "kkaiapi": {
        "api_url": "https://api.kkaiapi.com/v1",
        "available_models": [
          {
            "name": "claude-sonnet-4-6",
            "display_name": "Claude Sonnet 4.6",
            "max_tokens": 200000
          }
        ]
      }
    }
  }
}

Zed 怎么解析自定义 provider 和模型

Zed(GitHub 上的 zed-industries,约 87K 星标)是一个高性能编辑器,自带能做规划、改文件、跑工具的 Agent 面板。它的 openai_compatible provider 类型说的就是标准 /v1/chat/completions 协议,正是一个多厂商网关提供的协议,编辑器和端点之间不需要插件或扩展。 你起的 provider key(上面是 "kkaiapi")身兼两职。它在 Agent 面板设置里给 provider 命名,也生成 Zed 会去检查的环境变量名,规则是转成大写下划线格式再加 _API_KEY 后缀。这条命名规则值得在排查之前先记住:改了 provider 名字,对应期待的变量名也会跟着变。 available_models 是一份白名单。Zed 没法自动枚举一个自定义端点,所以只有你声明过的 ID 才能被选中,每一个都是精确字符串,包括版本后缀。当 api_url 背后的端点同时提供 Claude、GPT、Gemini、Kimi 的 ID 时,一个 provider 块就能把 Agent 面板的选择器变成一个跨厂商切换台。有一点范围说明:Zed 的 edit predictions 功能用的是自己专用的模型,单独配置;自定义 provider 驱动的是 Agent 面板和行内助手,不是 edit predictions。

完整配置:模型、上下文大小、能力声明

每个 available_models 条目要填的不止一个名字。max_tokens 声明模型的上下文窗口,max_output_tokens 限制生成长度;Zed 用这两个数字管理长的 Agent 会话,所以给一个长上下文模型填小的 max_tokens 会白白浪费它的余量。capabilities 对象告诉 Zed 这个模型支持什么:打算用 Agent 面板驱动的都把 tools 设成 true,只有真的接受图片输入的模型才开 images。 Key 这一侧,桌面编辑器上更稳妥的路径是走 provider 设置界面,值会存进系统密钥链。环境变量路径也可以用,但有一个排查环节要留意:从 Dock 启动的图形界面应用不会继承你的 shell 配置文件。

{
  "language_models": {
    "openai_compatible": {
      "kkaiapi": {
        "api_url": "https://api.kkaiapi.com/v1",
        "available_models": [
          {
            "name": "claude-sonnet-4-6",
            "display_name": "Claude Sonnet 4.6",
            "max_tokens": 200000,
            "max_output_tokens": 64000,
            "capabilities": { "tools": true, "images": false }
          },
          {
            "name": "claude-opus-4-7",
            "display_name": "Claude Opus 4.7",
            "max_tokens": 200000,
            "capabilities": { "tools": true }
          },
          { "name": "gpt-5.5", "display_name": "GPT-5.5", "max_tokens": 200000 },
          { "name": "kimi-k2.7-code", "display_name": "Kimi K2.7 Code", "max_tokens": 256000 }
        ]
      }
    }
  }
}

给 Agent 面板选模型

因为每个声明过的模型都在同一个选择器里,实际的工作方式是对着真实工作做比较,而不是看跑分:同一类任务在不同天用两个候选各跑一次,让按 Key 的用量日志给每个定价。在 Zed 里换模型是下拉框选一下,做这个实验的成本几乎为零。

• Agent 面板承载真正的工程活:读文件、规划多步改动、在长会话里跑工具。旗舰编码模型(claude-sonnet-4-6、claude-opus-4-7、gpt-5.5)属于这个槽位
• kimi-k2.7-code 这类代码专精 ID,哪怕不是默认值也值得声明;为一个重构密集的会话切过去只是选择器里点一下,不是改配置
• 长上下文模型比如 gemini-3.1-pro-preview,在会话经常要拉进大文件或整模块上下文时值回票价
• 行内助手比 Agent 会话短命得多,一个快速的中端 ID 能让单次变换保持轻快,不为一行改写烧掉旗舰 token

主力模型价格

价格按 kkaiapi 中文区实时价格计算,单位 ¥/1M tokens(输入/输出)。

Zed 自定义 provider 专属的翻车点

Key 填在 settings.json 里却什么都不生效。Zed 按设计不从 settings.json 读取 API Key。要么在 provider 设置界面输入,要么导出派生出来的环境变量;粘进 JSON 里的 Key 会被忽略。 环境变量设了,Zed 还是要 Key。变量名是从 provider key 派生的,转大写下划线再加 _API_KEY,一个叫 kkaiapi 的 provider 需要的是 KKAIAPI_API_KEY,不是 OPENAI_API_KEY。而且在 macOS 上,从 Dock 启动的应用永远不会加载你的 shell 配置文件,配置文件里的 export 对它不可见。用终端里的 zed 命令启动,或者干脆走密钥链路径绕开这个问题。 选择器里缺个模型。available_models 是白名单;一个你以为有、其实没声明的 ID 根本不存在。ID 是精确字符串,包括版本后缀,网关的 /v1/models 列表是权威拼写来源。 Agent 用不了工具。如果某个模型的 capabilities 里 tools 是 false,Zed 不会给它提供工具调用。按模型实际支持的能力声明。 api_url 漏了 /v1。客户端会在你给的 base 后面拼接 /chat/completions 这类路由路径,所以 https://api.kkaiapi.com/v1 是对的,裸域名不行。一个看起来都对的块出现 404 形状的失败,几乎都是这个原因。

哪些人会把 Zed 接到一个网关上

• 常年活在编辑器里的开发者,想在一个 Agent 面板选择器里用上 Claude、GPT、Kimi,而不是给每家厂商维护单独的凭证
• 在真实改动上比较编码模型的工程师,每个候选只是一条声明加一次下拉选择,不需要为每次实验开新账号
• 想统一一个密钥的团队,一个 KKAIAPI_API_KEY 写进入职文档,取代按厂商的密钥清单,按 Key 用量能看出每个座位花了多少
• 想给旗舰 Agent 模型搭配一个不同厂商的快速行内助手模型的用户,单一厂商配置做不到这一点
• 手头没有某家厂商官方支付渠道的开发者,充值即用不需要海外卡

验证接入与排查首个会话

开始一个 Agent 会话之前先列出网关提供了什么;/v1/models 返回的 ID 就是 available_models 条目必须用的精确字符串。 首个会话的失败很有规律。401 意味着 Zed 解析到的 Key 是错的或者根本没解析到:检查 provider 设置里的密钥链条目,或者确认派生出的环境变量对 Zed 进程可见,而不只是对你的终端可见。网关返回模型不存在,说明声明的名字和提供的 ID 不匹配,版本后缀也算。如果 provider 块在设置里根本不出现,先校验 JSON;settings.json 允许注释,但不允许结构性错误。 请求跑通之后,kkaiapi 控制台会显示每次请求的模型、token 数和花费。Agent 会话是长上下文、多轮次的负载,看清楚哪些会话、哪些模型在消耗 token,才知道你的默认模型到底值不值这个槽位。

curl -s https://api.kkaiapi.com/v1/models \
  -H "Authorization: Bearer $KKAIAPI_KEY" | head -50

常见问题