给所有 Dify 应用
Dify 是开源的 LLM 应用、Agent 与工作流搭建平台，每个上线的应用背后都要接一个模型供应商。通过 Dify 的 OpenAI-API-compatible 模型供应商插件把 Router One 注册一次，目录里的 GPT、Claude、Gemini、Grok 和 DeepSeek 对话模型就都在一份凭证后面，应用发出、经网关发往模型的每次调用都会成为控制台 → 日志里的一条请求，带模型、tokens、费用和状态（在输出任何内容之前就失败的流式请求可能没有记录）。不过这个插件的默认值是按「未知端点」设计的：上下文长度 4096、工具调用关闭。不改的话，聊天机器人会忘掉前面的对话，Agent 会退回用提示词模拟工具调用。本指南讲怎么安装插件、添加模型表单逐项怎么填、真实应用必须改的设置、哪些 Dify 功能 Router One 服务不了（Embedding 和 Rerank），以及怎么读懂 Dify 的第一条报错。按 Dify 1.17.1 与 OpenAI-API-compatible 插件 0.0.68 核对（2026-09-27 核对的是插件源码）；2026-10-09 复核时两者仍是最新版本。
安装 OpenAI-API-compatible 模型
Dify 的模型供应商以插件形式提供。打开 集成 → 模型供应商，在 Marketplace 列表中找到 langgenius 发布的 OpenAI-API-compatible 并安装；Marketplace 上的当前版本是 0.0.68（2026-10-09 核对）。表单里的地址字段在 2026-07-22 的 0.0.55 版改过名：0.0.53 及以前叫 API endpoint URL，之后叫 API Base URL，填的值完全一样。添加模型之前，先为这个 Dify 工作空间单独创建一把 Router One Key，并设置 maxSpend。工作空间里的所有应用、工作流和后台任务都会共用它；Key 触到上限后会收到 HTTP 402，不会继续花钱，你的其他 Key 照常可用。
把 Dify 配置到 Router One base URL
在 OpenAI-API-compatible 卡片上点击「添加模型」，模型类型选 LLM。「模型名称」填目录里的精确 ID，它会原样作为 model 字段发送，例如 anthropic/claude-sonnet-5、openai/gpt-5.6-sol、google/gemini-3.7-flash、deepseek-v4.1-flash 或 grok-4.7。「模型显示名称」可选，只影响 Dify 里显示的名字。「API endpoint中的模型名称」留空，这样发送的就是「模型名称」。「API Key」填你的 Router One Key（sk- 加 64 位十六进制字符）。「API Base URL」填 https://api.router.one/v1，恰好一个 /v1；插件会在后面拼上 /chat/completions，应用实际调用的是 POST /v1/chat/completions。「对话类型」保持「对话」。其余字段在下一节逐项说明。保存时，插件会用一个很小的请求验证凭据，这条请求会出现在控制台 → 日志里，看到对应记录，就说明 Key、地址和模型 ID 都没问题，不必等应用去用。每个要提供给应用的模型各加一条：
- API Base URL
- https://api.router.one/v1
# Dify → Integrations → Model Provider → OpenAI-API-compatible → Add Model Model type: LLM Model Name: anthropic/claude-sonnet-5 API Key: sk-your-router-one-key API Base URL: https://api.router.one/v1 Completion mode: Chat Model context size: 1048576 # context window from the model page Function Call Type: Tool Call Stream function calling: Support API Type: Chat Completions API (/chat/completions) Compatibility mode: OpenAI compatible (strict) # Plugin releases before 0.0.55 (2026-07-22) label the URL field API endpoint URL
决定 Dify 应用
添加模型表单里有十几项设置，默认值都是按未知端点选的。下表是接 Router One 时会影响行为的那些；其余几项（视频支持、音频支持、文档支持、用户标识支持、流模式授权）保持默认即可。
| 字段 | 默认值 | 接 Router One 时怎么设 | 原因 |
|---|---|---|---|
| 模型上下文长度 | 4096 | 模型详情页上的上下文窗口（整数）：anthropic/claude-sonnet-5 填 1048576，openai/gpt-5.6-sol 填 1050000，anthropic/claude-haiku-4.5 填 200000 | Dify 会把对话历史裁剪到「这个值减去最大 token 设置再减去提示词」以内，填 4096 时聊天机器人会忘掉较早的对话 |
| 最大 token 上限 | 4096 | 你希望应用里最大 token 滑块能拉到的上限 | 它只限制应用能请求多少，按你的用途定，不要照搬目录里的数字 |
| 函数调用类型 | 不支持 | 工具调用（模型详情页列出了工具调用的 ID） | 设为「不支持」时，Agent 应用会退回用提示词模拟的 ReAct 工具调用，可靠性不如原生工具调用 |
| 流式函数调用 | 不支持 | 支持（与「工具调用」一起开启） | 声明该模型能在流式回复中返回工具调用 |
| 视觉支持 | 不支持 | 支持（模型详情页列出了图片输入的 ID） | 声明该模型接受图片输入 |
| 结构化输出 | 不支持 | Claude 的 ID 保持「不支持」 | 在 /v1/chat/completions 上，response_format 不是让 Claude 系列 ID 稳定输出 JSON 的可靠方式 |
| API 类型 | Chat Completions API (/chat/completions) | 保持默认；只有 GPT 系列、DeepSeek 或 Grok 对话模型的 ID 才可以选 Responses API | Responses 会发往 {API Base URL}/responses，那个端点只服务这几个系列 |
| token 参数名 | 自动（按模型判断） | 保持「自动」 | 「自动」对以 o1、o3、gpt-5、gpt-6 开头的名称发送 max_completion_tokens；Router One 的 Chat Completions 把 max_completion_tokens 与 max_tokens 都当作输出上限 |
| 流式中包含用量 | 启用 | 保持启用 | Dify 才会记录流式回复的 token 用量 |
| 思考模式支持 | 仅支持非思考模式 | 没有测试过这个模型就保持默认 | 它决定 Dify 为该模型提供哪些思考相关的控制项 |
| 兼容模式 | 严格（OpenAI 兼容） | 保持严格 | 扩展模式会额外注入思考参数；Claude 或 -thinking 结尾的 ID 未经测试不要开启 |
默认模型、后台
在 集成 → 模型供应商 里，「默认模型设置」决定整个工作空间的默认值。按 Dify 自己的提示，「系统推理模型」在创建应用时使用，也会用于对话名称生成和下一步问题建议，所以每段对话都可能多出几次没人输入的小请求；把它设为速度快、单价低的对话模型，例如 anthropic/claude-haiku-4.5。每次保存或重新验证模型，也会多发一个小请求。Embedding 和 Rerank 则是另一回事：Router One 提供对话、图像和视频端点，没有 /v1/embeddings，也没有 rerank 端点，所以知识库要用的这两项默认模型得来自别的供应商。它们最好一次选定：Dify 会提示，之后再切换 Embedding 模型，已导入知识的向量就和新问题的向量不一致，检索会失败，直到重新建索引。你发布的应用在 Dify 里仍有自己的日志；按请求计的费用在控制台 → 日志，用工作空间那把 Key 筛选，就能看到整个工作空间的花费。
读懂 Dify 的第一条
保存失败时，Dify 显示 Credentials validation failed with status code <n> and response body <…>，其中的 body 就是 Router One 返回的 JSON 错误，通常已经写明了怎么改。404 且消息以 no route matched 开头，说明路径不对：POST /chat/completions 表示 API Base URL 少了 /v1，路径以 /v1/v1 开头表示 /v1 填了两次。401 且带 AUTH_INVALID_API_KEY，说明 Key 没被接受，检查有没有多余的空格、是不是以 sk- 开头。400 且提示 model '<id>' must be called via …，说明模型与 API 类型不匹配，常见的是 Claude 系列 ID 选了 Responses API。402 是计费问题：要么钱包余额不足，要么触到了这把 Key 的 maxSpend 上限，而充值并不会解除这个上限。其他情况，保留响应里的请求 ID，到控制台 → 日志里找到对应记录。
Dify 该填
从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Dify 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个客户端或应用单独建 API Key，并设置 maxSpend 消费上限。
Dify 用的是哪种 API 协议？
OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。
在请求日志里
先在 Dify 发出一次简单文本请求，再到控制台 → 日志按时间、模型和 request_id 找到这条记录，核对 Token、花费、总耗时和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，要么请求没到达网关（客户端配置或网络问题），要么网关在调用模型之前就拒绝了它——Key 问题的 401、余额不足或 Key 达到 maxSpend 上限的 402、Key 或账户自身限额触发的 429，或模型 ID、端点不对的 400 / 404；在输出任何内容之前就失败的流式请求也可能没有日志。看客户端收到的状态码和错误消息就能区分是哪一种；先确认这一点，再判断是不是网关或上游故障。
常见
在 Dify 里选哪种
在 集成 → 模型供应商 里安装并使用 langgenius 发布的 OpenAI-API-compatible。以单个厂商命名的供应商插件对应的是那家厂商自己的端点和 Key，而 OpenAI-API-compatible 插件可以填任意 base URL，接 Router One 需要的正是这一点。想提供给应用的每个模型各加一条，「模型名称」填 /models 页上的精确 ID；添加后，应用里就能按你起的显示名称选用。
API endpoint URL 和 API Base URL 有什么
没有区别，是同一个字段改了名。OpenAI-API-compatible 插件在 2026-07-22 发布的 0.0.55 版把 API endpoint URL 改叫 API Base URL，0.0.53 及更早版本仍显示旧名称。两个版本都填 https://api.router.one/v1，插件会自己拼上 /chat/completions。网上较早的教程截图里写的是旧名称，照填即可。
保存时报 Credentials validation failed with status code 404，哪里错了？
是 API Base URL。插件会在你填的地址后面拼上 /chat/completions，所以这里必须正好是 https://api.router.one/v1。少了 /v1，请求会发到 /chat/completions，Router One 返回 404，消息提示 OpenAI 兼容客户端的 base URL 要以 /v1 结尾；/v1 写了两次，请求会发到 /v1/v1/chat/completions，消息会提示去掉多余的 /v1。把完整端点地址贴进去，路径也会同样叠加。改好字段重新保存即可，404 不产生费用。
Dify 聊天
检查模型条目里的「模型上下文长度」。它默认是 4096，Dify 只保留能放进「这个值减去最大 token 设置再减去提示词」的对话历史，所以远没到模型真实上限，较早的轮次就被丢掉了。把它改成模型详情页上的上下文窗口，例如 anthropic/claude-sonnet-5 填 1048576，然后保存。历史越长，每次请求的输入 tokens 越多，控制台 → 日志里逐次可见。
Dify 的 Agent 不走
「函数调用类型」默认是「不支持」。这种设置下，Dify 的 Agent 应用会退回用提示词模拟的 ReAct 方式：让模型把工具调用写成文本，可靠性不如原生工具调用。把「函数调用类型」设为「工具调用」，「流式函数调用」设为「支持」，并选模型详情页列出了工具调用的 ID；其他 ID 先测试一次工具调用。
「API 类型」要不要选 Responses API？
只有 GPT 系列、DeepSeek ID 与 Grok 对话模型可以选，而且只在你需要 Responses 独有、Chat Completions 没有的功能时才有必要。选了之后插件会发往 {API Base URL}/responses。Claude 系列 ID 发过去会收到 HTTP 400 must be called via …，Gemini 的 ID 在 /v1/responses 上同样不提供，所以两者都留在服务全部对话模型的 Chat Completions 上。模型列表混用多个系列时，默认值最稳妥。
控制台 → 日志里
通常来自「系统推理模型」：Dify 用它生成对话名称和下一步问题建议；另外每次保存模型也会发一个小的验证请求。工作流节点和 Agent 的每一轮迭代也都是单独的调用。把系统推理模型换成低单价的 ID，不需要的应用关掉下一步问题建议。给工作空间单独一把 Key，这些请求用一个筛选条件就能全部看到。
Router One 能充当 Dify 的 Embedding 或 Rerank 模型吗？
不能。Router One 没有 /v1/embeddings，也没有 rerank 端点，所以用 Router One 的 base URL 添加 Embedding 或 Rerank 模型会失败。这两项工作空间默认值请留在别的供应商，Router One 负责 LLM 条目。搭知识库之前先定好 Embedding 模型，因为 Dify 提示之后再切换会让已导入知识的检索失效。
「模型
「模型名称」会作为 model 字段发给 Router One，必须与目录 ID 完全一致，包括厂商前缀和版本号。「模型显示名称」只是团队在 Dify 里看到的标签，所以条目可以叫 Claude Sonnet 5，而「模型名称」仍是 anthropic/claude-sonnet-5。「API endpoint中的模型名称」一旦填写，就会代替「模型名称」发送；留空，免得一个条目对应两个不同的 ID。
Dify 能通过
选用当前目录中同时支持 Dify 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只说明它从自身配置或 GET /v1/models 读到了这个 ID，仍需验证实际调用。
能列出
先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。
中国
能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。
报 401/402/403/429 怎么
先看客户端收到的响应：状态码、错误消息和 X-Request-ID 响应头。401（Key 缺失、不存在、已吊销或已过期）、402（钱包余额不足，或这把 Key 达到 maxSpend 上限）以及 Key 或账户自身限额触发的 429，都在调用任何模型之前被拒绝，不会出现在控制台 → 日志里；模型 ID 或端点写错导致的 400 / 404 也一样。401 查 Key 是否完整传入、在控制台 → API 密钥里是否仍有效；402 充值或调高这把 Key 的 maxSpend；403 请保留完整错误消息。429 请退避后重试；日志里能查到的 429 是网关重试之后上游仍返回的。保留 request_id，再按错误码速查页逐项排查。