1. 从 0.19 升到 RAGFlow 0.20.0：Agent 与 MCP 到底变了什么
RAGFlow 0.20.0 是一次把 Agent 编排和 MCP 工具调用真正打通的大版本。如果你之前用 0.19 搭过知识库问答，会发现旧版 Agent 有两个硬伤：一是没法挂载 MCP Server，外部工具接不进来；二是 Agent 跑起来之后看不到运行时日志，出错了只能靠猜。0.20.0 把这两块补齐了，同时把 Agent 和工作流的编排界面统一，支持多 Agent 配置、规划与反思，还能把 RAGFlow 自己当成 MCP Server 对外提供服务。
这篇面向的是已经部署过 RAGFlow、想升级到 0.20.0 并跑通一个带 MCP 的 Agent 示例的开发者。我会给出 docker-compose 与 .env 的可复制配置、升级前后的接口差异，以及通过 TaoToken 统一 Key 接入模型服务的完整验证步骤。适合谁：本地或内网已经跑着 RAGFlow 旧版本、手里有 Docker 环境、想快速验证 MCP 工具调用链路的人。
先说清楚 0.20.0 的几个关键变化，方便你判断升级收益：
Agent 全面重构，支持多 Agent 协作、规划和反思，可视化编排界面和工作流统一。MCP 功能完整落地，可以导入 MCP Server、让 Agent 作为 MCP Client 运行、也能让 RAGFlow 本身作为 MCP Server 暴露能力。Agent 运行时日志可访问，管理面板能看聊天历史。底层文档引擎换成新版 Infinity，自动打标能力更强。提供兼容 OpenAI 的 API，支持文件引用信息。新增 embedding 模型支持，包括 Kimi K2、Grok 4、Voyage，并引入 Gitee AI 作为模型提供商。
这些变化里，对开发者最直接的是 MCP 和 Agent 日志。前者决定了你的 Agent 能不能调用外部工具，后者决定了你调试时能不能定位问题。下面按升级路径一步步来。
2. 升级前的前置准备：TaoToken 统一 Key 与模型服务接入
升级本身不复杂，但升级后 Agent 要能跑起来，模型服务必须先接好。这里我用 TaoToken 做统一 Key 接入，原因是它把多家模型的调用收敛到一个 Base URL 和一把 Key 上，Agent 里配置模型时不用来回切换供应商。
TaoToken 是什么：一个兼容 OpenAI 接口规范的模型服务聚合入口，你拿到一把 Key 之后，把 Base URL 指向它，就能在 RAGFlow 的模型配置里统一调用。适合谁：需要在 RAGFlow 里同时用多个模型做对话、embedding、重排，又不想为每家单独维护 Key 和地址的开发者。
先拿 Key。打开控制台页面，登录后在 API Keys 里创建一个新 Key，复制出来备用。地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。注意这个 Key 只在创建时完整显示一次，先存到安全的地方。
拿到 Key 之后，RAGFlow 里配置模型服务需要三个东西：Base URL、API Key、Model ID。Base URL 填 https://taotoken.net/api ，注意这里不加任何 UTM 参数，就是纯 API 地址。API Key 填你刚复制的那串。Model ID 按你要用的模型填，比如对话模型填对应的模型名，embedding 模型填对应的 embedding 名。
这里有个容易踩的坑：RAGFlow 的模型配置分好几类，对话模型、embedding 模型、重排模型是分开配的。如果你只配了对话模型，Agent 跑起来在检索阶段会因为缺 embedding 模型报错。所以三类都要配，Base URL 和 Key 用同一套。
如果你还没部署过 RAGFlow，或者想先确认模型服务本身通不通，可以先用模型对话页面测一下 Key 是否有效： https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。在那边发一条消息，能正常返回就说明 Key 和 Base URL 没问题，再往 RAGFlow 里配就少一层排查。
前置准备清单：Docker 和 docker compose 可用；旧版 RAGFlow 项目目录还在；TaoToken 的 Key 已创建；确认当前 RAGFlow 版本（后面升级要用）。这些都齐了再往下走。
3. 可复制配置：docker-compose 与 .env 升级片段
升级的核心是拉新代码、切分支、改镜像版本、重启容器。先进入你的 RAGFlow 项目目录，执行拉取最新代码：
git pull然后切到 0.20.0 分支：
git checkout -f v0.20.0 git statusgit status用来确认当前确实在 v0.20.0 分支上，别切错了还在旧分支上改配置。
接着进 docker 目录，编辑 .env 文件：
cd ragflow/docker vim .env找到RAGFLOW_IMAGE这一行，改成 0.20.0 的镜像：
RAGFLOW_IMAGE=infiniflow/ragflow:v0.20.0如果你想改 RAGFlow 的启动端口，打开同目录下的 docker-compose.yml，找到端口映射那一段改。默认是 80 端口映射，改成你想要的宿主机端口即可。
改完镜像版本后，拉新镜像并重启：
docker compose -f docker-compose.yml pull docker compose -f docker-compose.yml up -d如果你要给项目指定名字，用-p参数：
docker compose -f docker-compose.yml -p ragflow up -d这里给一份 .env 里和模型接入相关的关键配置片段，方便你对照。RAGFlow 的模型配置主要在 Web 界面里做，但 .env 里有些基础项要确认：
# 镜像版本，升级核心 RAGFLOW_IMAGE=infiniflow/ragflow:v0.20.0 # 时区，日志时间对不上时改这里 TZ=Asia/Shanghai # 文档引擎相关，0.20.0 用新版 Infinity # 保持默认即可，除非你有自定义需求docker-compose.yml 里端口和卷的部分，升级时一般不用动，除非你要改端口：
services: ragflow: image: ${RAGFLOW_IMAGE} ports: - "80:80" volumes: - ./ragflow-logs:/ragflow/logs - ./nginx/ragflow.conf:/etc/nginx/conf.d/ragflow.conf注意：升级前建议先备份你的知识库数据卷和 .env 文件。虽然 0.20.0 的升级路径是平滑的，但备份是底线操作。数据卷一般在 docker 目录下的ragflow-logs和数据库相关目录里，具体看你部署时的挂载配置。
镜像拉取完成后，用docker compose ps看容器状态，确认 ragflow 容器是 Up 状态。如果容器起不来，先看日志：
docker compose -f docker-compose.yml logs -f ragflow日志里如果出现数据库迁移相关的信息，属于正常，等它跑完。0.20.0 换了新版 Infinity 文档引擎，首次启动可能会做一些初始化，耐心等几分钟。
4. 验证请求：跑通一个带 MCP 的 Agent 示例
容器起来后，打开浏览器进 RAGFlow 管理界面，先确认版本号显示的是 0.20.0。然后进模型配置，把 TaoToken 的对话模型、embedding 模型、重排模型都配上，Base URL 统一填 https://taotoken.net/api ，Key 填你创建的那把。
配好模型后，新建一个知识库，上传一份测试文档，等它完成解析和向量化。这一步是为了让 Agent 有检索的数据源。
接下来配 MCP。0.20.0 支持导入 MCP Server，在 Agent 编排界面里找到 MCP 配置入口，添加一个 MCP Server。你可以先用一个简单的本地 MCP Server 做测试，比如一个提供时间查询或计算能力的 Server。配置时需要填 MCP Server 的启动命令或地址，具体看你用的 Server 类型。
然后新建一个 Agent，在编排界面里把刚才配的对话模型选上，把知识库挂上，再把 MCP Server 作为工具挂到 Agent 上。0.20.0 的 Agent 支持多 Agent 配置和规划反思，你可以先建一个单 Agent 跑通链路，再考虑加多 Agent。
保存后，在 Agent 的对话界面发一条测试消息，比如问一个需要查知识库的问题，再问一个需要调用 MCP 工具的问题。观察返回结果，同时打开 Agent 运行时日志，看工具调用有没有被触发。
验证成功的标志：Agent 能正常返回知识库检索结果；调用 MCP 工具时日志里能看到工具调用记录；管理面板的聊天历史里能看到这次对话。
如果你想先用 API 方式验证模型服务通不通，可以用 curl 测一下 TaoToken 的接口：
curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer 你的Key" \ -H "Content-Type: application/json" \ -d '{ "model": "你的模型ID", "messages": [{"role": "user", "content": "你好"}] }'能返回正常 JSON 就说明 Key 和 Base URL 没问题。这一步和 RAGFlow 里的配置用的是同一套凭证，所以先测通再配 RAGFlow，能省不少排查时间。
如果你打算长期跑 Agent 和编码类任务，可以看下 Coding Plan 页面，了解下长期使用的方案： https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
升级和接入过程中，报错集中在几个地方。下面按真实报错对照排查。
401 Unauthorized。这个最常见，基本是 Key 或 Base URL 的问题。先确认 Key 有没有复制完整，有没有多余空格。再确认 Base URL 填的是 https://taotoken.net/api ，不要多加路径，也不要带 UTM 参数。如果 Key 是在别处创建的，确认它还有效、没被删除。RAGFlow 里模型配置的 Key 和你在 curl 里用的 Key 必须是同一把。
local proxy failed 或连接超时。这个通常是网络层的问题，不是 Key 的问题。先确认容器能访问外网，在容器里 curl 一下 TaoToken 的地址看通不通。如果容器网络是隔离的，检查 docker-compose 里的网络配置。另外确认没有在 .env 或环境变量里设置了错误的代理地址，RAGFlow 容器会读取这些变量。
reading choices 相关报错。这个一般出现在模型返回格式不符合预期时。RAGFlow 解析模型响应时如果拿不到 choices 字段，就会报这个。排查方向：确认你填的 Model ID 是对话模型，不是 embedding 或重排模型；确认 Base URL 指向的是兼容 OpenAI 的接口；用 curl 单独测一下这个 Model ID 能不能正常返回带 choices 的 JSON。
OAuth 相关报错。如果你在 MCP Server 配置里用了需要 OAuth 认证的 Server，报错通常出在 token 获取或刷新环节。先确认 OAuth 的 client id、client secret、回调地址填对了。如果 MCP Server 是本地启动的，确认它的 OAuth 流程能在当前网络环境下走通。实在不行，先用不需要 OAuth 的 MCP Server 跑通链路，再逐步加认证。
Agent 日志里看不到工具调用。先确认 MCP Server 真的挂到了 Agent 上，不是只配了没启用。再确认 Agent 的规划步骤里有没有走到工具调用那一步，有时候是模型没选择调用工具，而不是工具本身有问题。可以在 Agent 配置里调整提示词，明确要求它在需要时调用工具。
容器起不来或反复重启。先看日志，常见原因是镜像没拉全、端口被占用、数据卷权限不对。端口占用的话改 docker-compose.yml 里的端口映射。数据卷权限问题在 Linux 上比较常见，确认挂载目录的属主和容器内用户匹配。
升级后旧知识库数据看不到。先确认数据卷挂载路径和升级前一致，别换了目录。再确认数据库迁移有没有跑完，日志里如果有迁移报错，按报错处理。0.20.0 换了新版 Infinity，首次启动的初始化时间会比平时长，别急着判定失败。
6. 把 Key 和配置固定下来，后续少折腾
升级到 0.20.0 之后，Agent 和 MCP 的能力是实打实可用的，但前提是模型服务这一层要稳。我的做法是把 TaoToken 的 Base URL 和 Key 固定成一套配置，对话、embedding、重排都用它，这样在 RAGFlow 里配模型时不用记多套凭证，排查问题时也只需要验证一个入口。
如果你后面要接 Claude Code 或者做更复杂的 Agent 编排，接入文档里有更细的配置说明： https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。Claude Code 相关的接入可以看 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite 。
最后留一个实操建议：升级完成后，先别急着把生产知识库全量迁过来，用一个测试知识库加一个测试 Agent 跑通 MCP 调用链路，确认日志、检索、工具调用都正常，再逐步迁移。这样即使中间有配置问题，影响面也可控。
