Connect MaxKB to Router One through the OpenAI provider
MaxKB builds knowledge-base assistants and agent workflows. Its OpenAI provider can use Router One for compatible chat-model requests; MaxKB keeps the knowledge base, retrieval, tools and workflow execution. This guide covers the model form and OpenAI adapter in MaxKB v2.10.6-lts.
Configure MaxKB to use the Router One base URL
In Models, add a model under the OpenAI provider. Model name is your display label; Base model is the ID sent to the API. Type the exact current chat-model ID from /models into Base model, including any vendor prefix, even if it is absent from the preset dropdown. Choose the LLM model type and set API URL to https://api.router.one/v1; the documentation also calls this field API domain. Put a dedicated Router One key in API Key. This provider uses the Chat Completions client, so do not append /chat/completions to API URL. After saving successfully, select the new model as the AI model of your simple agent or the model of an AI chat node.
# 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
Two model names, one actual model ID
The editable label helps you find a model inside MaxKB; renaming it does not change what the gateway runs. Base model is an editable dropdown, not a list fetched from Router One. The v2.10.6-lts adapter passes that value as model without removing a vendor prefix. The provider name OpenAI selects the compatible protocol, so it does not require an OpenAI-family model. Pick an ID whose Router One detail page supports Chat Completions.
| MaxKB field | Value | Meaning |
|---|---|---|
| Provider | OpenAI | Selects the OpenAI-compatible chat adapter |
| Model name | Router One chat | A display label inside MaxKB |
| Model type | LLM / 大语言模型 | The chat-model slot |
| Base model | Exact ID from /models | Sent to the API unchanged |
| API URL / API domain | https://api.router.one/v1 | Base address; not the full completion URL |
| API Key | A dedicated Router One key | Credentials used for validation and later calls |
Saving validates the model with a real request
The v2.10.6-lts credential validator invokes the selected model with a greeting. A save-time check can therefore consume tokens before an end user starts chatting. Its OpenAI LLM parameter form starts with temperature 0.7 and a maximum output setting of 8192 tokens; these are MaxKB defaults, not Router One recommendations or a context-window declaration. If the error names temperature or an output-token parameter, inspect Advanced settings or Model parameter settings and remove or adjust the unsupported parameter before trying again. Keep the complete error; changing the key or base URL does not fix a model-specific parameter rejection.
Separate knowledge retrieval from billed model calls
A knowledge base selects its own embedding model. Leave that on a local model or another provider: Router One does not serve embeddings or reranking endpoints. A successful LLM validation does not validate document indexing. Question optimization, generating associated questions from documents and AI chat nodes can add model calls beyond the final answer. Use a dedicated key with maxSpend, test one small document first, and reconcile requests by time, model and request_id in Dashboard → Logs. MaxKB’s conversation history and token estimates are not the gateway’s settlement record.
Which model ID should MaxKB send?
Copy the exact model ID from /models, preserving case, hyphens, and version suffixes; do not substitute a display name. Open its detail page and match the supported API endpoints, context window, and capabilities such as tool calling to the provider and features selected in MaxKB. A catalog listing does not mean the client can use every feature of that model. Give each tool a dedicated API key with a maxSpend cap.
Which API protocol is MaxKB using?
OpenAI-compatible describes an interface format; it does not make Chat Completions (/v1/chat/completions), Responses (/v1/responses), and Anthropic Messages (/v1/messages) interchangeable. Check the installed client version, provider configuration, and actual request path against the model detail page and API compatibility fact sheet. A successful plain-text chat does not establish support for hosted tools, conversation state, or file-editing features.
Verify the MaxKB call in your request trace
Send a simple text request from MaxKB, then match its trace in Dashboard → Logs by time, model, and request_id: tokens, cost, latency, and status. Next, test streaming, tool calls, and multi-turn history separately. For failures, retain the actual request path, full error message, and request_id. If there is no matching log, check client configuration and connectivity before attributing the error to the gateway or upstream.
FAQ
The exact Router One ID is not in the Base model dropdown. Can I still use it?
Yes. The official OpenAI guide allows custom input, and the v2.10.6-lts form enables allow-create on the Base model dropdown. Enter the full ID there and confirm the new option. Putting it only in Model name changes the display label, not the request. Choose the OpenAI provider for this Chat Completions setup even when the catalog ID begins with anthropic/ or google/.
Why does adding a model fail with a connection or verification error?
Check the original error and the MaxKB server logs. A request to /chat/completions without /v1 points to an incomplete API URL; a duplicated completion path means the full endpoint was pasted as the base. Check the key for 401 and the exact model ID or named parameter for 400. The connection originates from the MaxKB server or container, so verify its outbound HTTPS and DNS. Missing Dashboard logs alone do not prove a network failure: some records can be pending pricing, and the response or server log is stronger evidence.
The chat model works, but document vectorization fails. Should I reuse the same connection?
No. MaxKB treats LLM and embedding models as separate resources. Create or select an embedding model from a provider that supports that API, then choose it in the knowledge-base settings. The OpenAI provider showing an Embedding model type does not mean Router One implements that endpoint. Keep speech and other model types outside this chat guide until their endpoint compatibility has been verified.
Which models can MaxKB use through the gateway?
Choose a current catalog model that supports both the endpoint and the features MaxKB uses. Check /models and the model detail page for the exact ID, current rates, and capabilities; a family name such as GPT or Claude is not a compatibility guarantee. Seeing a model in the picker confirms discovery, so verify an actual request too.
Models are listed, but requests fail with 400 or 404. What should I check?
Record the actual request path and error message, then check the exact model ID. A 400 can indicate invalid parameters, unsupported tools, or a model/endpoint mismatch; a 404 can indicate an incorrect path or missing resource, so it does not by itself establish that a model was retired. If the error says must be called via, use the named endpoint or select a model supported on the current endpoint. Do not add or remove /v1 or /chat/completions across all clients indiscriminately.
Does this work from Mainland China?
Yes. The gateway is reachable from Mainland China without a VPN, and the configuration is identical to the global setup.
How do I debug a 401/402/403/429?
Match the request and error message in Dashboard → Logs. For 401, check whether the key was sent and is valid; for 402, check wallet balance and maxSpend; for 403, check key permissions and access restrictions. For 429, distinguish request/token limits from upstream throttling using the error details. Keep the request_id and follow the error-codes reference.