通过 OpenAI 供应商把 MaxKB 接到 Router One
MaxKB 用于搭建知识库助手与智能体工作流。它的 OpenAI 供应商可以把兼容的聊天模型请求发给 Router One；知识库、检索、工具与工作流执行仍由 MaxKB 负责。本指南面向 MaxKB v2.10.6-lts 的模型表单与 OpenAI 适配器。
把 MaxKB 配置到 Router One base URL
打开「模型」，选择 OpenAI 供应商添加模型。「模型名称」是显示标签，「基础模型」才是发给 API 的 ID。在「基础模型」中输入 /models 里当前可用的完整聊天模型 ID，保留厂商前缀，即使预设下拉列表没有也可以手动输入。「模型类型」选「大语言模型」，API URL 填 https://api.router.one/v1；官方文档也把这个字段叫「API 域名」。API Key 填专用 Router One Key。这个供应商使用 Chat Completions 客户端，因此 API URL 后面不要再加 /chat/completions。有一个例外：v2.10.6-lts 自带的 langchain-openai 1.3.2 会把含 codex 的「基础模型」（例如 codex-auto-review）改发到 /v1/responses，所以只有模型详情页列出 /v1/responses 时才选这类 ID。保存成功后，在简易智能体的 AI 模型或 AI 对话节点中选用新建模型。
- API URL
- https://api.router.one/v1
# MaxKB → 模型 / Models → OpenAI → 添加模型 / Add model 模型名称 / Model name: Router One chat 模型类型 / Model type: 大语言模型 / LLM 基础模型 / Base model: <exact-model-id-from-/models> API URL: https://api.router.one/v1 API Key: sk-your-router-one-key # 保存后，在智能体中选用这个模型 / Select this model in your agent after saving # 向量模型另配 / Configure the knowledge-base embedding model separately
两个
模型名称方便你在 MaxKB 中区分资源，改名不会改变网关实际调用的模型。「基础模型」是可输入的下拉框，不是从 Router One 拉取的目录。v2.10.6-lts 适配器把它直接作为 model 参数发送，不去掉厂商前缀。供应商名称 OpenAI 选择的是兼容协议，不要求必须使用 OpenAI 系列模型；从 Router One 详情页选择支持 Chat Completions 的 ID 即可。
| MaxKB 字段 | 填写内容 | 实际作用 |
|---|---|---|
| 供应商 | OpenAI | 选择 OpenAI 兼容聊天适配器 |
| 模型名称 | Router One chat | 只在 MaxKB 内使用的显示标签 |
| 模型类型 | 大语言模型 / LLM | 聊天模型的位置 |
| 基础模型 | /models 中的精确 ID | 原样发给 API |
| API URL / API 域名 | https://api.router.one/v1 | 基础地址，不是完整的生成端点 |
| API Key | 专用 Router One Key | 验证与后续请求所用的凭据 |
保存时会
v2.10.6-lts 的凭据验证器会用一句问候调用所选模型，因此最终用户尚未聊天，保存测试就可能产生 token 用量。该版本 OpenAI 大语言模型的参数表单默认提供 temperature 0.7 和最大输出 8192 tokens；这是 MaxKB 默认值，不是 Router One 的推荐参数，也不是上下文窗口。若错误点名 temperature 或输出 token 参数，先在「高级设置」或「模型参数设置」中删除或调整不支持的参数，再重试。保留完整错误；换 Key 或修改 base URL 不能解决模型对某个参数的拒绝。
把知识
知识库需要单独选择向量模型。让它使用本地模型或其他供应商：Router One 不提供 embeddings 或 reranking 端点。大语言模型验证成功，不代表文档索引已通过验证。「问题优化」、知识库文档的「生成问题」和 AI 对话节点都可能在最终回答之外增加模型调用。使用设了 maxSpend 的专用 Key，先用一份小文档验证，再在控制台 → 日志按时间、模型和 request_id 核对请求。MaxKB 的对话历史和 token 估算不是网关结算记录。
MaxKB 该填
从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 MaxKB 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个客户端或应用单独建 API Key，并设置 maxSpend 消费上限。
MaxKB 用的是哪种 API 协议？
OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。
在请求日志里
先在 MaxKB 发出一次简单文本请求，再到控制台 → 日志按时间、模型和 request_id 找到这条记录，核对 Token、花费、总耗时和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，要么请求没到达网关（客户端配置或网络问题），要么网关在调用模型之前就拒绝了它——Key 问题的 401、余额不足或 Key 达到 maxSpend 上限的 402、Key 或账户自身限额触发的 429，或模型 ID、端点不对的 400 / 404；在输出任何内容之前就失败的流式请求也可能没有日志。看客户端收到的状态码和错误消息就能区分是哪一种；先确认这一点，再判断是不是网关或上游故障。
常见
基础模型
可以。官方 OpenAI 接入文档允许自定义输入，v2.10.6-lts 表单也为「基础模型」下拉框开启了 allow-create。把完整 ID 输在这里并确认新选项；只把它填进「模型名称」会修改显示标签，不会改变实际请求。本指南走 Chat Completions，即使目录 ID 以 anthropic/ 或 google/ 开头，供应商仍选 OpenAI。
添加模型
先看原始错误和 MaxKB 服务端日志。请求路径只有 /chat/completions、缺少 /v1，说明 API URL 没填完整；路径重复出现生成端点，说明把完整 endpoint 当成了 base URL。401 检查 Key，400 检查精确模型 ID 或错误点名的参数。请求由 MaxKB 服务器或容器发出，因此要检查它的出站 HTTPS 与 DNS。控制台 → 日志里查不到记录，本身不能证明网络失败：部分记录可能尚待定价，应优先依据实际响应或服务端日志判断。
聊天
不能。MaxKB 把大语言模型与向量模型作为不同资源管理。新建或选择提供 Embedding API 的模型，再到知识库设置中选用。OpenAI 供应商表单里有「向量模型」这个类型，不代表 Router One 实现了相应端点。语音等其他模型类型也不属于本篇聊天接入范围，需要另外核对端点兼容性。
MaxKB 能通过
选用当前目录中同时支持 MaxKB 所用端点和所需功能的模型。精确 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，再按错误码速查页逐项排查。