Dify 的 OpenAI-API-compatible 插件可以给兼容 OpenAI 接口的服务手动添加模型。真正容易出错的不是 Key而是界面 Model Name 与 API endpoint 中的模型名称 没有对齐保存或验证时就返回 model_not_found。适用环境Dify 官方 openai_api_compatible 插件 0.0.55 的可自定义聊天模型。先用这组最小配置与命令完成预检Model Name: 便于在 Dify 中识别的名称API Base URL: https://service.example/v1model name for API endpoint: /models 返回的精确 idCompletion mode: chatcurl -sS -H Authorization: Bearer YOUR_API_KEY \https://service.example/v1/models成功信号是模型目录 200再用精确 ID 发送最小 Chat Completions 请求也返回 200 和可读正文失败对照是错误模型的 404 model_not_found。先完成这三段信号再进入工作流排查。本文实际运行的是只监听 127.0.0.1 的脱敏协议夹具没有启动完整 Dify也没有请求线上模型。它验证的是当前官方插件字段对应的排错方法不是“任意第三方服务都已在 Dify 跑通”。先按这 5 步修正1. 记录插件版本和四个关键字段在 Dify 的模型供应商区域选择 OpenAI-API-compatible 并添加自定义模型。当前官方 schema 中与这次问题直接相关的完整字段是Model Name: Dify 界面中的模型名称API Key: 目标服务凭据API Base URL: 例如 https://service.example/v1model name for API endpoint: 目标端点真实识别的模型 ID可选Completion mode: 一般聊天模型选 chat先不要凭产品页展示名猜值。Model Name 可以是你在 Dify 里识别这条配置的名字但 endpoint model name 应与请求体中的 model 完全一致。当前官方实现会优先使用 endpoint_model_name只有它为空时才回退到界面 Model Name。2. 用 /models 确认 Base URL 和精确 ID如果目标服务提供 OpenAI 风格的模型目录先执行curl -sS \-H Authorization: Bearer YOUR_API_KEY \https://service.example/v1/models只记录脱敏后的 HTTP 状态、最终路径和 data[].id。成功结果应类似{object: list,data: [{id: your-exact-model-id, object: model}]}这里如果返回 401先处理 Key 或权限返回 404先检查 Base URL 是否少了或重复了 /v1返回 HTML 或登录页说明请求命中的不是 API 资源。不要在路径未确认时继续轮换模型名。并不是所有兼容服务都公开 /models。如果该接口未提供就从服务方当前控制台或官方 API 文档复制精确 ID但仍要把来源和观察时间记下来。3. 把精确 ID 填到 endpoint model name假设你希望在 Dify 中显示“团队代码模型”而 /models 返回的是 vendor-coder-2026-07可以这样区分Model Name: 团队代码模型model name for API endpoint: vendor-coder-2026-07不要把“团队代码模型”直接发给服务端也不要删除版本后缀、改大小写或把另一环境的模型名粘贴过来。model_not_found 只说明当前请求中的模型值不被当前端点接受它不等于 Key 失效也不等于 Base URL 一定正确。4. 用同一组值发送最小请求继续使用相同 Base URL、Key 和 endpoint model namecurl -sS \-H Authorization: Bearer YOUR_API_KEY \-H Content-Type: application/json \https://service.example/v1/chat/completions \-d {model: your-exact-model-id,messages: [{role: user, content: 只回复 DIFY_OK}],max_tokens: 16,stream: false}至少确认四项HTTP 是 200choices[0].message.content 可读取返回的 model 没有意外切到别的 ID响应不是 HTML、登录页或非 JSON 错误。如果 /models 是 200、错误模型是 404、正确模型是 200模型映射这一层才算闭合。5. 回到 Dify 保存并只测最小输入在 Dify 中保存自定义模型后先用最短提示验证不要直接运行包含知识库、工具调用和多节点的工作流。若最小验证仍失败保留以下脱敏信息插件版本API Base URL 的路径部分界面 Model Nameendpoint model nameHTTP 状态与错误 type服务端 request ID如有不要记录或截图完整 Key。确认模型层成功后再逐步加入流式、工具调用、图片和工作流节点否则新变量会掩盖原始问题。本地复现为什么只填界面模型名会失败我用标准库写了一个 loopback 服务目录中只开放 fixture-chat-model。第一次按“endpoint model name 为空时回退到界面 Model Name”的逻辑发送 dify-ui-alias服务返回 404第二次显式填写 fixture-chat-model返回 200 和 DIFY_PLUGIN_OK。执行命令python3 06-evidence/probe_dify_endpoint_model.py脱敏结果PLUGIN_VERSION0.0.55MODELS_HTTP200MODEL_IDSfixture-chat-modelWITHOUT_ENDPOINT_MODEL_HTTP404WITHOUT_ENDPOINT_MODEL_ERRORmodel_not_foundWITH_ENDPOINT_MODEL_HTTP200WITH_ENDPOINT_MODEL_TEXTDIFY_PLUGIN_OKONLINE_PROVIDER_REQUESTNOFULL_DIFY_RUNTIMENO这组结果证明排错顺序有效先确认目录再确认请求体里的模型值。它没有证明完整 Dify 界面、插件运行器或任何线上供应商已经执行成功因此不能把结果改写成“Dify 实测接入某服务成功”。三类常见失败不要混在一起Base URL 路径错误表现通常是 404、HTML 网关页或固定首页内容。检查最终请求是否落到 /v1/models 和 /v1/chat/completions尤其注意 Dify 中已填 /v1 后服务端文档是否又要求客户端拼一次。不要用增加斜杠的方式盲试一串地址。模型 ID 错误典型表现是 HTTP 404 或错误体中的 model_not_found。此时应对比当前端点的模型目录、endpoint model name 和请求日志里的 model而不是立刻更换 Key。响应协议不兼容模型请求可能返回 200但缺少 choices、message.content 或符合当前模式的字段。此时模型名已经不是首要问题应转向响应结构、Chat/Completion mode 和插件支持范围不要继续用 model_not_found 的办法处理协议错误。一张检查表收尾[ ] 插件版本已记录[ ] Base URL 来自同一服务环境[ ] /models 或官方目录给出精确模型 ID[ ] endpoint model name 与精确 ID 完全一致[ ] 错误模型能稳定复现 404/model_not_found[ ] 正确模型最小请求返回 200 和可读正文[ ] 完整 Key、账户信息和内部地址未进入日志或截图[ ] 完整 Dify 与线上服务未实测时正文已明确披露结论很简单Dify 里的显示名称和服务端真实模型 ID 可以不同。遇到 model_not_found 时先用当前 Base URL 查目录再把精确 ID 放进 endpoint model name并用同一组值发送最小请求。只有这条链路闭合后才值得继续排查工作流、流式和工具调用。