企业官网建设流程全解析

1. 为什么要在自托管协作空间里接入 AI 智能体

ONLYOFFICE 协作空间 3.6 的 AI 智能体模块，简单说就是给自托管文档平台装了一个能读写房间、检索知识库、调用外部模型的“数字同事”。它和普通聊天机器人的区别在于：智能体通过 MCP（Model Context Protocol）协议与协作空间内部元素交互，能创建房间、整理文档、邀请成员，而不只是返回一段文本。适合谁？适合已经把 ONLYOFFICE 协作空间部署在自有服务器、又希望文档流程里嵌入自动化分析或内容生成的技术团队。

我试过在本地 Docker 环境里从零走一遍配置，发现真正卡人的不是“点哪个按钮”，而是 MCP 服务器地址填什么、API Key 怎么和模型 ID 对应、以及验证时返回reading choices这类报错怎么定位。这篇就按“原问题 → 前置准备 → 可复制配置 → 验证请求 → 错排查 → 下一步”的顺序拆开讲，每一步都给出可粘贴的片段和预期结果。

先明确一个边界：协作空间 3.6 的 AI 智能体本身不训练模型，它只负责编排。模型能力来自你接入的提供商，MCP 负责让智能体“看见”协作空间里的房间、文档和用户。所以配置分两层——模型层（API Key + Base URL + Model ID）和平台层（MCP 服务器启用 + 知识库索引）。两层都通，智能体才能既回答问题又执行操作。

如果你只是想让智能体做文档摘要，模型层通了就够；如果要它自动建房间、加成员，MCP 必须启用并正确指向协作空间内部服务。下面从环境确认开始。

2. 接入前的环境确认与 TaoToken 配置准备

在动协作空间后台之前，先把模型侧的三个参数拿到手：Base URL、API Key、Model ID。协作空间 3.6 的 AI 设置里添加提供商时，OpenAI 兼容接口需要填这三项。很多自托管团队卡在第一步，是因为只拿了 Key 却没确认 Base URL 是否支持流式返回。

TaoToken 在这里的角色是提供 OpenAI 兼容的模型调用入口，Base URL 填https://taotoken.net/api，API Key 在控制台生成，Model ID 按你实际要用的模型填。注意 API 地址不带任何查询参数，直接写根路径即可。控制台入口在 https://taotoken.net/console ，API Keys 管理页在 https://taotoken.net/api-keys ，生成后复制一次，页面刷新就不再完整显示。

环境侧需要确认三件事。第一，协作空间版本确实是 3.6，旧版没有 AI 设置板块。第二，服务器能出站访问你填的 Base URL，自托管环境常因内网 DNS 或防火墙导致local proxy failed。第三，如果要用知识库检索，文档存储目录要有可写权限，索引进程需要读取上传文件。

我建议先在服务器上用 curl 验证模型侧连通，再进协作空间后台配置。这样出错时能快速判断是模型侧还是平台侧的问题。验证命令如下，把$TAOTOKEN_KEY换成你的实际 Key：

curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 16 }'

返回 JSON 里choices[0].message.content有内容，说明 Base URL、Key、Model ID 三者匹配。如果返回 401，先查 Key 是否复制完整；如果返回model not found，换一个控制台里列出的 Model ID。这一步通了再进协作空间，能省掉大量来回试错。

另外提醒一点：协作空间的 AI 设置里“添加提供商”支持的列表包含 OpenAI、Anthropic、TogetherAI、OpenRouter 等，选 OpenAI 兼容类型即可对接 TaoToken 的 API 地址。不要选成需要 OAuth 跳转的类型，自托管环境没有回调域名会直接失败。

3. 可复制的智能体与 MCP 配置片段

这一节给可直接粘贴的配置。协作空间 3.6 的 AI 设置板块分三块：提供商、MCP 服务器、知识库与网络搜索。先配提供商，字段对应关系如下表。

MCP 服务器部分，协作空间内置一个默认 MCP 服务器，启用后智能体才能操作房间和文档。如果你要接外部 MCP，地址填法遵循 JSON 结构。下面是一个可复制的 MCP 配置片段，路径对应协作空间后台“AI 设置 → MCP 服务器”：

{ "mcpServers": { "onlyoffice-workspace": { "command": "npx", "args": ["-y", "@onlyoffice/mcp-server"], "env": { "ONLYOFFICE_BASE_URL": "https://your-workspace.example.com", "ONLYOFFICE_API_KEY": "your_workspace_api_key" } } } }

注意ONLYOFFICE_BASE_URL是你自托管协作空间的访问地址，ONLYOFFICE_API_KEY是协作空间里生成的集成 Key，不是模型 Key。两者别混。如果你用 Cline 或 Claude Code 这类客户端接 MCP，配置结构类似，但要把 Base URL、Key、Model ID 三件套写全，缺一个都会在初始化时报错。

知识库和网络搜索按需开。知识库开启后系统会对房间内文档做索引，索引完成前智能体检索会返回空。网络搜索用于实时信息，自托管环境如果出站受限，开了也拿不到结果，建议先只开知识库验证。

创建智能体时，名称、封面、标签随意，关键是“指令”字段。指令决定它的行为边界，比如“本对话空间专用于合同条款比对，只基于知识库回答，不编造条款”。存储配额在“设置 → 存储空间管理”里调，配额太小会导致长对话被截断。

4. 验证请求与成功结果判定

配置保存后，进入“AI 智能体”板块新建对话，发一条能同时触发模型和 MCP 的指令，比如“列出当前房间内的文档数量，并总结第一个文档的前三行”。这条指令既需要模型理解，又需要 MCP 读取房间数据，能一次性验证两层是否都通。

预期成功结果分三部分。第一，对话界面返回文本，说明模型层通。第二，返回内容里包含真实文档数量，说明 MCP 读取成功。第三，如果开了知识库，追问“根据知识库回答某文档的核心结论”，能返回文档内实际内容而非泛泛而谈。

如果只想验证模型层，用下面这条最小请求，在协作空间对话里发：

请只回复：模型连通正常

返回完全一致的内容，说明 Base URL、Key、Model ID 无误。如果返回空或报错，看下一节的错排查。

验证 MCP 层时，发“创建一个名为 test-room 的协作空间”。成功的话，房间列表里会出现新房间。这一步能过，说明 MCP 服务器地址和协作空间 API Key 都正确。注意创建操作会真实写入，测试完记得删掉。

我实测下来，最容易出问题的是知识库索引。上传文档后索引不是即时完成，大文件可能几分钟。索引未完成时问知识库问题，智能体会回答“未找到相关内容”，这不是配置错，等索引跑完再试即可。索引状态可以在 AI 设置的知识库板块看进度。

5. 常见报错与排查对照

这一节按真实报错逐条排查。第一个高频错误是 401 Unauthorized。出现在模型侧，说明 API Key 无效或复制时带了空格。解决：重新在 https://taotoken.net/api-keys 生成，粘贴时确认首尾无空格。出现在 MCP 侧，说明协作空间集成 Key 错，去协作空间后台重新生成。

第二个是local proxy failed。自托管环境常见，原因是服务器无法出站访问 Base URL。排查：在服务器上执行curl -v https://taotoken.net/api/v1/models，看是否卡在 DNS 或 TLS。如果是内网 DNS 问题，给服务器配可解析的 DNS；如果是防火墙，放行出站 443。

第三个是reading choices相关报错，通常表现为返回体里choices字段为空或解析失败。原因多是 Model ID 填错，或该模型不支持当前请求格式。解决：换控制台里明确列出的 Model ID，并确认请求体里messages结构正确。协作空间内部调用时如果报这个，检查提供商配置里的 Model ID 是否和 curl 验证时用的一致。

第四个是 OAuth 相关报错。如果你在添加提供商时选了需要 OAuth 的类型，自托管环境没有回调地址会直接失败。解决：改选 OpenAI 兼容类型，用 API Key 方式对接，不要走 OAuth 流程。

第五个是 MCP 初始化超时。表现为智能体对话一直转圈或提示 MCP 不可用。排查：确认 MCP 服务器进程在跑，npx命令能正常执行；确认ONLYOFFICE_BASE_URL从 MCP 所在机器能访问。如果 MCP 和协作空间不在同一台机器，地址不能填 localhost。

第六个是知识库检索返回空。先确认索引完成，再确认文档在智能体可访问的房间内。权限不对的房间，智能体读不到。检查智能体成员权限，至少要有内容创作者级别才能读知识库。

6. 从验证到长期使用的下一步

配置通了之后，下一步是把智能体接到实际工作流。如果你主要做文档分析和内容生成，直接在协作空间对话里用即可，模型对话入口在 https://taotoken.net/chat 。如果要把智能体嵌入编码或 Agent 流程，长期跑自动化任务，可以看 Coding Plan，入口在 https://taotoken.net/coding-plan ，它更适合持续调用而非单次对话。

接入文档在 https://taotoken.net/doc ，里面有各语言 SDK 的调用示例，自托管集成时可以直接参考。API Keys 管理还是 https://taotoken.net/api-keys ，建议给协作空间单独生成一个 Key，方便按用途排查和轮换。

最后给一个实用技巧：把智能体的指令写成“先检索知识库，再回答，回答末尾标注引用的文档名”。这样每次输出都可追溯，团队审阅时能快速定位来源。MCP 操作类指令建议加确认步骤，比如“创建房间前先列出将要创建的名称”，避免误操作。配置片段建议存到版本控制里，协作空间升级到 3.7 时对比字段变化会省事很多。