作者注：分清 Zed 的三条 Agent 路径，再用 OpenAI-compatible 和 Anthropic-compatible 两种自定义 Provider 把 API易 接进 Zed，并说明 Base URL、模型 ID、价格和排错要点。
你在 Zed 里用 Agent 面板或 Inline Assistant 写代码，想换成别的模型，却发现设置页里有 LLM Providers、External Agents、终端线程好几个入口，不确定 Key 该填在哪。更常见的情况是填了一个第三方网关，结果一直报 404 或鉴权失败。本文介绍 用 Zed 自定义 Provider（OpenAI-compatible / Anthropic-compatible）接入第三方模型网关 的完整做法，以 API易 为例走通配置流程。
这不是又一篇“复制粘贴配置就完事”的速查。文章先讲清 Zed 三条 AI 路径各自的模型接入边界，再给出两条可以照做的路线。Base URL 什么时候加 /v1、什么时候不加，这个最容易出错的细节会单独讲。
核心价值：读完本文，你能判断自己要改的是哪一层配置，并在 5 分钟内让 Zed Agent 用上 claude-opus-5-5、claude-sonnet-5-5 这类模型。出了问题，也知道该先查哪一项。
Zed 换模型核心要点：先分清三条 Agent 路径
Zed 是 Atom / Tree-sitter 原班人马打造的高性能多人协作编辑器。截至 2026-11-13，GitHub 仓库 zed-industries/zed 约有 94,884 star（GitHub API 观察）。官方 releases 页显示，2026-11-11 的稳定版为 1.28.1，同日 Preview 为 1.29.1。macOS、Linux、Windows 都可以直接下载，Web 版尚未正式可用。
在 Zed 里换模型之前，要先明白一点：官方文档把 AI 能力分成三条路径，每条路径的模型接入方式和鉴权方式都不一样。如果填错了地方，配置不会生效，Key 也不会被另一条路径读取。
| 路径 | 模型从哪来 | 鉴权由谁管 | 典型用途 |
|---|---|---|---|
| Zed Agent | LLM Providers（Zed 托管、厂商 Key、订阅、网关、本地模型） | Zed 本身，Key 存系统钥匙串 | Agent 面板、Inline Assistant、内置工具 / profiles / skills / MCP |
| External Agents（ACP） | 外部 Agent 自己选模型 | 外部 Agent 自己管 | 在 Zed 线程里运行 Claude Agent、Codex、OpenCode、Copilot、Cursor 等 |
| Terminal Threads | 由你运行的 CLI / TUI 决定 | CLI 自己的配置 | 在终端线程里直接跑各类 Agent CLI |
Zed Agent 与 External Agent 的接入边界
“给 Zed Agent 换模型”指的是配置 LLM Providers，也就是 API Access 这一层，这是本文的主线。官方支持的一等厂商有 Anthropic、OpenAI、Google AI、Mistral、DeepSeek、xAI、OpenCode，另外还提供 Anthropic-compatible 和 OpenAI-compatible 两种自定义端点。第三方网关就是从这两种自定义端点接进来的。
如果你只是想在面板里用 Claude Agent 或 OpenCode，那属于 External Agent，走的是 Agent Client Protocol（ACP）。这种情况下线程由 Zed 托管，运行时、鉴权和模型选择通常由外部 Agent 自己负责。你在 LLM Providers 里填的 Key 不会自动共用给它，Claude Agent 需要在自己的线程里执行 /login。外部 Agent 可以通过命令面板 zed: acp registry 打开注册表安装。按官方文档的说法，Zed 不为 External Agents 单独收费，账单在 Agent 提供方。
Zed 自定义 Provider 核心配置要点
两种自定义端点的差别主要在请求格式上。OpenAI-compatible 走 Chat Completions，Anthropic-compatible 走 Messages API（/v1/messages）。这个差别直接决定了 Base URL 的写法，也决定了能不能用上 Prompt Cache 计费。
| 配置项 | OpenAI-compatible | Anthropic-compatible |
|---|---|---|
| 请求格式 | /v1/chat/completions |
/v1/messages |
| API易 api_url | https://api.apiyi.com/v1 |
https://api.apiyi.com（不加 /v1） |
| 模型字段 | available_models[].name + max_tokens |
available_models |
| 能力开关 | 默认 tools=true、images=false、chat_completions=true | 可配 capabilities.prompt_caching |
| 缓存计费 | API易 文档说明不生效 | 原生 Messages 格式下生效 |
| 适合场景 | 想用一个 Provider 挂多家模型 | 主力用 Claude、长上下文、需要缓存 |
Base URL 为什么一个加 /v1、一个不加
根据 API易 Base URL FAQ（文档核对 2026-11-13），OpenAI 兼容客户端会在 api_url 后面直接拼接 /chat/completions，所以 api_url 要写到 /v1 这一级。Anthropic 一侧的客户端会自己拼接 /v1/messages，只能填根域名。如果写成 https://api.apiyi.com/v1，最终请求就会变成 /v1/v1/messages，直接返回 404。
还有两点需要注意。Zed 的 API Key 存在系统钥匙串里，不会写进 settings.json；如果对应的环境变量非空，环境变量会优先于钥匙串生效。另外，只支持 Responses 接口的模型要把 capabilities.chat_completions 设为 false，否则 Zed 会按 Chat Completions 去调用。
Zed 接入 API易 快速上手
下面两条路线可以只选一条，也可以都配上，在模型选择器里切换。动手前先准备好 Key。
🚀 快速开始：登录后在 API易 令牌页
api.apiyi.com/token创建一个令牌，建议为 Zed 单独建一个，便于查看用量和随时吊销。快速开始文档 docs.apiyi.com/getting-started 还提供 skill.md / llms.txt，方便让 Agent 读取平台说明。
路线 A：OpenAI-compatible 端点接入 Zed
- 打开 Agent 设置：在命令面板执行
agent: open settings。不同版本的界面入口名可能略有差异，以 AI / Agent 设置页里的 LLM Providers 区块为准。 - 在 LLM Providers 区块点击 Add Provider，类型选择 OpenAI-compatible。
- Provider 名称自己起一个，比如
apiyi，对应 settings.json 中的language_models.openai_compatible.apiyi。 - API URL 填
https://api.apiyi.com/v1。这里必须带/v1，这也是 API易 OpenAI 兼容页给出的写法。 - API Key 粘贴刚创建的令牌，Zed 会把它存进系统钥匙串。
- 添加模型：name 填 API易 型号总表里的真实 ID，例如
claude-opus-5-5、claude-sonnet-5-5，也可以加claude-fable-5-2。max_tokens按型号文档填写；不确定时先取保守值，跑通后再调大。 - 能力开关保持默认即可（tools=true）。需要发图片时再手动打开 images。
- 回到 Agent 面板，在模型选择器里搜
apiyi或模型名。近期版本的模型选择器已经支持模糊搜索，选中后发一条消息验证。
这条路线的好处是一个 Provider 能挂多家模型。API易 文档说明，OpenAI 兼容端点 /v1/chat/completions 只需要改一处模型字符串就能换模型。
路线 B：Anthropic-compatible 端点接入 Zed
- 同样进入 LLM Providers → Add Provider，类型选择 Anthropic-compatible。
- API URL 填
https://api.apiyi.com，只写根域名，不加 /v1。实际请求会落到 API易 的 Anthropic 原生端点https://api.apiyi.com/v1/messages。 - 粘贴同一个令牌，或者另建一个专用令牌。
- 在 available_models 里添加
claude-opus-5-5、claude-sonnet-5-5等 ID。 - 如果希望长上下文对话能命中缓存，打开
capabilities.prompt_caching。按 API易 Claude 能力页的说明，缓存计费只在原生 Messages 格式下生效。 - 在模型选择器中选中该模型，发一条消息测试。
💡 选择建议：日常以 Claude 为主、会话长、经常反复读同一批文件，选路线 B 更划算。需要在多家模型之间频繁切换，选路线 A 更省事。两条路线可以用同一个 API易 令牌，在 Zed 模型选择器里按任务切换。
Claude 模型价格参考（数据日期 2026-11-13）
以下数据来自 API易 型号总表，于 2026-11-13 文档核对，单位为美元 / 每 1M tokens，按量计费。
| 模型 ID | 输入 | 输出 | 缓存读 | 支持端点 | 可用平台 |
|---|---|---|---|---|---|
claude-opus-5-5 |
$4 | $20 | $0.2 | chat + messages | API易 apiyi.com |
claude-opus-5-5-thinking |
同 opus-5-5 | 同 opus-5-5 | 同 opus-5-5 | 以总表为准 | API易 apiyi.com |
claude-sonnet-5-5 |
$2 | $10 | $0.1 | 以总表为准 | API易 apiyi.com |
claude-fable-5-2 |
$8 | $40 | $0.2 | 以总表为准 | API易 apiyi.com |
型号与价格以平台型号列表为准。配置前可以打开 docs.apiyi.com/models 核对当天的数字和分组（总表中 claude-opus-5-5 列有 ClaudeCode、Claude_Reverse、Claude_Enterprise、Default、SVIP 等分组）。
关于 claude-opus-5-5 的使用限制，API易 上线动态（2026-09-23）提到三点：思考无法设为 disabled；tool_choice 设为 any / tool 会返回 400；effort 默认 medium。如果 Zed Agent 调用工具时出现 400，先排查这几项。
Zed 自定义端点常见报错排查
自定义 Provider 出错时，大多数问题出在 URL、Key 和模型名这三处。下表按出现频率排序，可以逐项检查。
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 404 Not Found | Anthropic-compatible 填了 /v1，路径变成 /v1/v1/messages |
改回根域名 https://api.apiyi.com |
| 404 / 路径不对 | OpenAI-compatible 漏了 /v1 |
改为 https://api.apiyi.com/v1 |
| 401 / 鉴权失败 | 令牌错误、已删除，或环境变量覆盖了钥匙串 | 到 api.apiyi.com/token 重新核对，清空冲突的环境变量 |
| 模型不存在 | ID 拼写错误或使用了别名 | 照 docs.apiyi.com/models 复制原始 ID |
| 400（工具调用） | tool_choice 为 any / tool，或尝试关闭思考 |
按上线动态说明调整 |
| 图片无效 | OpenAI-compatible 默认 images=false | 在 capabilities 中打开 images |
| 只支持 Responses 的模型报错 | 仍按 Chat Completions 调用 | 将 capabilities.chat_completions 设为 false |
🎯 排错建议：遇到 404，先把 Zed 设置里的 api_url 和 API易 Base URL FAQ（docs.apiyi.com/faq/base-url-config）逐字对照。大部分问题都是
/v1多写或少写了一次。
使用 Zed 自定义 Provider 的风险提示
- 非官方托管：OpenAI-compatible / Anthropic-compatible 自定义 Provider 是 Zed 提供的通用接入能力，第三方网关不属于 Zed 官方托管服务。出现服务问题时，需要找网关方处理。
- Key 与账单由你负责：令牌和用量计费都在你自己的账户下。建议为 Zed 单独建令牌，定期查看用量，不要把 Key 写进 settings.json 后提交到仓库。Zed 默认使用钥匙串存储，本身就降低了这个风险。
- External Agent 的条款在提供方：Claude Agent、Codex 等外部 Agent 的订阅、配额和使用条款由各自提供方决定，与 Zed Agent 的 Provider 配置相互独立。
- 版本差异：本文界面描述基于 1.28.x / 1.29.x 的官方文档与 releases 信息（观察日期 2026-11-13），后续版本的入口名称可能会调整。
常见问题 FAQ
Q1：Zed 的 OpenAI 兼容端点是什么？
它是 LLM Providers 里的一种自定义 Provider 类型。只要服务端实现了 Chat Completions 接口，就可以通过 api_url 和模型列表接入 Zed Agent，不需要等 Zed 官方适配。
Q2：在 LLM Providers 里填的 Key，Claude Agent 能直接用吗？
不能。Claude Agent 属于 External Agent，鉴权由它自己管理，需要在它的线程里执行 `/login`。LLM Providers 里的 Key 只给 Zed Agent 使用。
Q3：OpenAI-compatible 和 Anthropic-compatible 该选哪个？
主力用 Claude、需要缓存计费时选 Anthropic-compatible；想用一个 Provider 挂多家模型时选 OpenAI-compatible。按 API易 文档说明，缓存计费只在原生 Messages 格式下生效。
Q4：模型 ID 应该填什么？
填平台型号总表里的原始 ID，例如 `claude-opus-5-5`、`claude-sonnet-5-5`、`claude-fable-5-2`。建议直接从 docs.apiyi.com/models 复制，避免手打拼错导致“模型不存在”。
Q5：配置完一直 404，怎么排查？
先看 `/v1`：OpenAI-compatible 要带，Anthropic-compatible 不能带。如果路径没问题，再检查模型 ID 是否和 API易 型号列表一致。
Q6：API Key 存在哪里？会被同步到仓库吗？
Zed 把 Key 存在系统钥匙串，不写进 settings.json，所以分享设置文件时不会带出 Key。需要注意的是，同名环境变量非空时会优先于钥匙串，排查 401 时别忘了检查环境变量。
Q7：这套配置有哪些已知限制？
OpenAI-compatible 默认不开图片能力；`claude-opus-5-5` 的思考不能关闭，`tool_choice` 设为 any / tool 会返回 400。另外，自定义 Provider 不是 Zed 官方托管服务，稳定性取决于网关方。
Zed 接入 API易 核心要点 Key Takeaways
- 先分路径：Zed Agent 走 LLM Providers，External Agent 自己管鉴权。
- 两种端点：OpenAI-compatible 走 chat，Anthropic-compatible 走 messages。
- URL 规则：OpenAI 兼容填
/v1，Claude 原生只填根域名。 - 模型 ID：照 API易 型号总表复制
claude-opus-5-5等原始 ID。 - 缓存计费：需要缓存时用 Anthropic-compatible 并开启 prompt_caching。
- 排错顺序：依次检查
/v1、令牌、模型 ID、工具参数。 - 上手方式：在 api.apiyi.com/token 建专用令牌，5 分钟即可配完。
总结
在 Zed 里换模型，关键是确认要改的是哪一层：
- Zed Agent 换模型：在 LLM Providers 中用 Add Provider 添加 OpenAI-compatible 或 Anthropic-compatible 端点。
- External Agent：Claude Agent、OpenCode 等自行鉴权，Key 不与 Zed Agent 共用。
- Base URL：OpenAI 兼容填
https://api.apiyi.com/v1，Anthropic 兼容填https://api.apiyi.com，/v1多写或少写都会 404。
配置之前，建议先在 docs.apiyi.com/models 核对当天的型号与价格，再从令牌页创建 Zed 专用 Key。先用 claude-sonnet-5-5 跑通，再按任务切换到 claude-opus-5-5。可以通过 API易 apiyi.com 用同一个令牌在两种 Provider 下对比效果。
📚 参考资料
- Zed GitHub 仓库：源码与 star 数观察（2026-11-13）
- 链接：
github.com/zed-industries/zed -
说明：许可证以 GPL-3.0-or-later 为主，含 Apache-2.0 组件
-
Zed AI Overview：三条 AI 路径的官方说明
- 链接：
zed.dev/docs/ai/overview -
说明：Zed Agent、External Agents、Terminal Threads 的边界
-
Zed Use API Access：自定义 Provider 配置
- 链接：
zed.dev/docs/ai/use-api-access -
说明：OpenAI-compatible / Anthropic-compatible 字段与钥匙串存储
-
Zed External Agents：ACP 外部 Agent
- 链接：
zed.dev/docs/ai/external-agents -
说明：Claude Agent、Codex、OpenCode 等的接入方式
-
Zed Releases：版本更新记录
- 链接：
zed.dev/releases/stable -
说明：1.28.1 稳定版与 Preview 更新内容
-
API易 型号总表：模型 ID 与价格
- 链接：
docs.apiyi.com/models.md -
说明：输入 / 输出 / 缓存读价格，以当天列表为准
-
API易 Base URL 配置 FAQ：/v1 规则
- 链接：
docs.apiyi.com/faq/base-url-config.md -
说明：OpenAI 兼容与 Claude 原生 Base URL 写法差异
-
API易 Claude 能力页：原生与兼容端点
- 链接：
docs.apiyi.com/api-capabilities/claude.md -
说明：缓存计费仅在 Messages 格式下生效
-
API易 claude-opus-5-5 上线动态：使用限制
- 链接：
docs.apiyi.com/live/2026-09/claude-opus-5-5.md - 说明：思考、tool_choice、effort 默认值说明
作者：API易 技术团队
技术交流：配置遇到问题，可查阅 docs.apiyi.com 文档中心，或通过 API易 官网首页联系我们
