通过
FastGPT 是开源的知识库与 Agent 应用平台：应用以工作流搭建，AI 对话、工具调用、问题分类、内容提取等节点都要挂一个语言模型。FastGPT 通过内置的 AI Proxy 连接模型服务商——从 V4.17.0 起它是必需依赖——所以 Router One 是在那里加成一个 OpenAI 协议渠道：一把 Key 覆盖 GPT、Claude、Gemini、Grok 和 DeepSeek 系列，每次请求在控制台 → 日志都有成本 Trace。本指南讲清渠道表单该填什么、如何在模型配置里登记精确模型 ID 并做渠道测试，以及索引、重排和语音模型为什么要另找供应商。
确认部署走
本指南以官方 Docker Compose 模板自部署的 FastGPT 为前提，模板里 AI Proxy 是必需服务。FastGPT 容器带两个变量：AIPROXY_API_ENDPOINT 是 AI Proxy 服务根地址，不要附加 /v1，FastGPT 会按接口补充路径；AIPROXY_API_TOKEN 必须与 AI Proxy 服务端的 ADMIN_KEY 一致。V4.17.0 升级说明把两者列为必填，并写明旧的 OPENAI_BASE_URL 和 CHAT_API_KEY 已弃用并移除，配置后不再生效。下面的片段就是官方模板里的这几行——token 是模板生成的 YAML 引用别名，不是 Router One 的值。然后为这套部署单独创建一把设了 maxSpend 的 Router One Key：它只填进渠道表单，不进这些环境变量。
# 节选自 FastGPT 官方 docker-compose 模板
x-aiproxy-token: &x-aiproxy-token 'token'
services:
fastgpt-app:
environment:
# AI Proxy 的地址，如果配了该地址，优先使用
AIPROXY_API_ENDPOINT: http://fastgpt-aiproxy:3000
# AI Proxy 的 Admin Token，与 AI Proxy 中的环境变量 ADMIN_KEY
AIPROXY_API_TOKEN: *x-aiproxy-token
fastgpt-aiproxy:
environment:
ADMIN_KEY: *x-aiproxy-token
# 最大重试次数
RETRY_TIMES: 3把 FastGPT 配置到 Router One base URL
打开 管理员 → 模型提供商，切到「模型渠道」标签页，点右上角「新增渠道」，表单与下方代码块一一对应。协议类型选 OpenAI：AI Proxy 会把这个渠道的每次请求发到「代理地址 + /chat/completions」，所以代理地址要填带 /v1 的 https://api.router.one/v1——表单占位符给出的 OpenAI 默认地址本身也以 /v1 结尾。API 密钥填 Router One Key。「模型」是这个渠道要分发的目录 ID；下拉框只列「模型配置」里已有的模型，目录 ID 没有内置时，先到「模型配置」标签页点「新增模型」，把精确的目录 ID 填进「模型ID」——它就是 FastGPT 请求体里 model 字段的值，渠道转发时也用同一个值。两边 ID 完全一致时「模型映射」留空，只有想用本地别名时才把它映射到精确目录 ID。保存后点这个渠道的「模型测试」按钮，再点「批量测试 N 个模型」：它会对每个模型真实发一次请求并显示结果与耗时，这些测试请求同样会出现在控制台 → 日志。最后启用模型，在应用的 AI 配置或工作流的「AI 对话」节点里选它：
- 代理地址（Base url）
- https://api.router.one/v1
# FastGPT → 管理员 → 模型提供商 → 模型渠道 → 新增渠道 # FastGPT → Admin → Model provider → Model provider tab → Added channels 名称（Name）: Router One 协议类型（Protocol Type）: OpenAI 代理地址（Base url）: https://api.router.one/v1 API 密钥（API key）: sk-your-router-one-key 模型（Model）: <exact-model-id-from-/models> 模型映射（Model Mapping）: 留空 / leave empty（模型 ID 与目录 ID 完全一致时） # 模型配置 → 新增模型（Model configuration → Add new model） 模型ID（Model ID）: <exact-model-id-from-/models> 别名（Alias）: 任意展示名 / any display name 最大上下文 / 支持工具调用 / 支持图片识别: 按 /models 模型详情页填写 # 保存后：模型测试 → 批量测试 N 个模型（Model testing → Batch test N models）
每个
Router One 需要的东西都在一个渠道加一条对应的模型配置里。首次登录时系统要求的其他模型类型在同一个管理页配置，但必须指向别的供应商：
| FastGPT 字段 | 填什么 | 怎么验证 |
|---|---|---|
| 模型渠道 → 协议类型 | OpenAI | AI Proxy 在代理地址后拼 /chat/completions，目录里所有聊天模型都在这个端点上提供服务 |
| 模型渠道 → 代理地址 | https://api.router.one/v1 | 模型测试通过；测试报 404 not_found 说明少了 /v1 |
| 模型渠道 → API 密钥 | 为这套部署单独创建、设了 maxSpend 的 Router One Key | 测试请求出现在控制台 → 日志里这把 Key 名下 |
| 模型渠道 → 模型 / 模型映射 | 精确目录 ID；映射只用于把本地别名指向精确 ID | 日志里每条 Trace 的模型与 /models 逐字一致 |
| 模型配置 → 模型ID | 同一个精确 ID；上下文、工具调用、图片输入按模型详情页填 | 只有模型详情页列出工具调用时才打开「支持工具调用」：它让工具调用节点从在提示词里描述工具改为发送原生 tools；V4.17.0 的问题分类和内容提取无论开关与否都只发普通提示词 |
| 模型配置 → 自定义请求地址 / Key | 已标记即将弃用；若使用，填完整路径 https://api.router.one/v1/chat/completions | 绕过渠道和它的调用日志；官方文档要求改成渠道管理 |
| 索引、重排、语音合成、语音识别模型 | 另一家供应商的渠道 | Router One 没有 embeddings 和 rerank 端点；FastGPT 至少要有一个索引模型才能建知识库 |
给一套部署定
一次工作流运行会散成多次模型请求：AI 对话节点、回到模型的工具调用、问题分类、内容提取各算一次，AI Proxy 还会自行重试失败的请求（官方 Compose 模板把 RETRY_TIMES 设为 3），客户端每一次经网关发往模型的尝试都是独立请求，有各自的 Trace。给每套 FastGPT 部署单独一把设了 maxSpend 的 Router One Key，失控的工作流会停在你设的上限。按 FastGPT v4.17.1 的模型配置文档（2026-10-06 核对），在「系统模型 → 模型探测」里可选开启的自动探测，会按 5～60 分钟的间隔测试每个已启用的模型，失败时最多再重试 3 次；经 Router One 到达模型的每次探测都和普通请求一样计费，所以不需要时保持关闭，或把间隔调长。这里有三本账，只有一本是你要付的钱：控制台 → 日志是逐请求的费用，带模型、tokens、成本、延迟、状态和 request_id；AI Proxy 的「调用日志」页按次显示输入输出 tokens、耗时和请求地址——看实际打到哪个路径最快——错误详情默认只保留 1 小时（LOG_DETAIL_STORAGE_HOURS）；FastGPT 自己的积分（模型表单里的价格字段）用来给你的用户计量，与网关费率无关。按时间、模型和 token 数对账，报障时保留网关的 request_id。如果同一个模型 ID 还配在别的渠道里，AI Proxy 会按优先级在渠道间负载均衡，Router One 日志里少的那一条可能只是被别的渠道接走了。
FastGPT 该填
从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 FastGPT 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个客户端或应用单独建 API Key，并设置 maxSpend 消费上限。
FastGPT 用的是哪种 API 协议？
OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。
在请求日志里
先在 FastGPT 发出一次简单文本请求，再到控制台 → 日志按时间、模型和 request_id 找到这条记录，核对 Token、花费、总耗时和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，要么请求没到达网关（客户端配置或网络问题），要么网关在调用模型之前就拒绝了它——Key 问题的 401、余额不足或 Key 达到 maxSpend 上限的 402、Key 或账户自身限额触发的 429，或模型 ID、端点不对的 400 / 404；在输出任何内容之前就失败的流式请求也可能没有日志。看客户端收到的状态码和错误消息就能区分是哪一种；先确认这一点，再判断是不是网关或上游故障。
常见
渠道
两个 ID 必须一致：「模型配置」里的模型ID 就是 FastGPT 请求体里 model 字段的值，渠道原样转发，除非「模型映射」改写了它——所以模型启用时的拼写和目录 ID 不同，或映射指向了已下架的 ID，只会在真实调用时才报错。先看 AI Proxy「调用日志」里的请求地址和这次调用返回的错误消息：模型 ID 或端点不对导致的 400 / 404 在调用任何模型之前就被拒绝，控制台 → 日志里没有记录。协议类型为 OpenAI 时路径是 /v1/chat/completions，目录里所有聊天模型都在这个端点上；400 且消息含 must be called via，说明请求走到了别的端点——比如用 Anthropic 协议类型建的渠道会往代理地址下的 /messages 发请求，而网关只为它列出的 Claude 系列和 DeepSeek ID 提供该端点——所以即使是 Claude 系列 ID，Router One 渠道也保持 OpenAI 协议类型。400 里点名某个参数，则是模型拒绝了它：FastGPT 模型表单注明最大温度留空表示模型不支持 temperature，Body 额外字段会合并进每次请求。
代理
在 FastGPT 里要带。渠道存在 AI Proxy 里，它的 OpenAI 协议类型会在你填的地址后面拼 /chat/completions；表单占位符是以 /v1 结尾的 OpenAI 默认地址，FastGPT 文档也提醒「注意是否需要增加 /v1」。不带的话请求会发到 https://api.router.one/chat/completions，网关返回 404 not_found，消息里直接说明 OpenAI 兼容客户端需要以 /v1 结尾的 base URL。中转站页面上相反的口径没有错，但那是 one-api 和 new-api 的「OpenAI」渠道类型，它们自己拼完整的 /v1/chat/completions。测试失败时，先到 AI Proxy「调用日志」看请求地址，再决定增删 /v1；连接排查页有这一步的完整走法。
知识库的
不能。FastGPT 把五类模型分开配置——语言、索引、重排、语音合成、语音识别——系统至少要有一个语言模型和一个索引模型才能正常使用。Router One 在 /v1/chat/completions 上提供聊天模型，没有 embeddings、rerank 和音频端点，所以这三类模型要从另一家供应商的渠道来，Router One 渠道里只放语言模型。一把 Router One Key 仍然覆盖所有对话和 Agent 节点——GPT、Claude、Gemini、Grok 和 DeepSeek 系列——知识库索引的费用则留在另一家的账单上。
FastGPT 能通过
选用当前目录中同时支持 FastGPT 所用端点和所需功能的模型。精确 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，再按错误码速查页逐项排查。