企业官网建设流程全解析

1. 为什么要在 ONLYOFFICE 里接一个统一 Key

ONLYOFFICE 是一套开源协作办公套件，文档、表格、演示文稿、表单、PDF 编辑器都在同一个界面里完成，团队可以自托管，也可以直接用云端协作空间。它本身不带大模型能力，AI 功能全靠插件市场里的插件来补。问题就出在这里：插件一多，Key 就散。写文档的插件配一个 Key，PDF 摘要的插件配另一个 Key，表格公式助手再配一个，团队里每个人各自填一遍，换人、换项目、换模型都要重新折腾。

我试过把几个插件分别接不同厂商的 Key，结果就是版本一升级、Key 一过期，排查起来像破案。后来改成用 TaoToken 做统一入口：一个 Key、一个 API 通道，所有 ONLYOFFICE 插件都指向它。TaoToken 是一个大模型 API 聚合与分发平台，把多家模型的调用收敛到同一套接口和同一个 Key 上，适合需要给编辑器、插件、脚本统一供能的团队。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。

这篇面向的是这样一类人：团队已经在用 ONLYOFFICE 做文档协作，想给文档编辑器和 PDF 编辑器加上 AI 能力，但不想让每个插件各管各的 Key。下面会给可复制的 config.toml 与 settings.json 骨架、插件侧统一 Key 的配置步骤，以及连通性验证和排错。适合谁：自托管 ONLYOFFICE 的运维、给团队搭协作环境的开发者、以及要写 ONLYOFFICE 插件的同学。

2. 前置准备：TaoToken Key 与 ONLYOFFICE 环境

2.1 拿到统一 Key

先到 TaoToken 控制台创建一个 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。创建后复制那串以 sk- 开头的字符串，先存到本地密码管理器里，后面配置只引用环境变量，不硬编码进文件。

注意：Key 只显示一次，页面关掉就看不到了。团队场景建议按项目建 Key，方便单独吊销。

2.2 确认 ONLYOFFICE 版本与插件目录

ONLYOFFICE 的插件分两类：一类是官方插件市场里安装的，配置存在插件自己的存储里；另一类是你自己开发或改装的插件，代码放在插件目录下。自托管 Document Server 的插件目录通常在：

/var/www/onlyoffice/documentserver/sdkjs-plugins/

桌面版则在用户配置目录下，Linux 一般是：

~/.local/share/onlyoffice/desktopeditors/plugins/

先确认你的部署方式，再决定配置写在哪。下面给的 config.toml 适合自托管服务端统一注入，settings.json 适合插件侧读取。

2.3 网络与依赖

ONLYOFFICE 服务端要能访问 https://taotoken.net/api 。自托管环境如果是内网隔离的，需要放行这个域名。验证一下：

curl -sS -o /dev/null -w "%{http_code}\n" https://taotoken.net/api

返回 200 或 401 都说明网络通，401 只是没带 Key。如果超时，先查 DNS 和出口策略，别急着改插件代码。

3. 可复制配置：config.toml 与 settings.json 骨架

3.1 config.toml：服务端统一注入

自托管场景下，我习惯把 AI 通道写进服务端的 config.toml，让所有插件读同一份配置。文件放在 ONLYOFFICE 配置目录，比如：

/etc/onlyoffice/documentserver/ai-gateway.toml

内容骨架如下，字段按需改：

# ONLYOFFICE AI 插件统一通道配置 [gateway] provider = "taotoken" base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" timeout_seconds = 60 max_retries = 2 [models] default = "gpt-4o-mini" summarize = "gpt-4o-mini" translate = "gpt-4o-mini" code = "claude-3-5-sonnet" [plugins] enabled = ["ai-assistant", "pdf-ai", "sheet-helper"] config_path = "/etc/onlyoffice/documentserver/plugins/settings.json"

关键点：api_key_env 指向环境变量名，不写明文 Key。然后在服务启动脚本里导出：

export TAOTOKEN_API_KEY="sk-你的Key"

systemd 管理的服务，写进 unit 的 Environment 或 EnvironmentFile 更稳。

3.2 settings.json：插件侧读取

插件侧用 settings.json 承接 config.toml 的通道信息，放在插件目录下：

{ "ai": { "provider": "taotoken", "baseUrl": "https://taotoken.net/api", "apiKeyEnv": "TAOTOKEN_API_KEY", "defaultModel": "gpt-4o-mini", "models": { "summarize": "gpt-4o-mini", "translate": "gpt-4o-mini", "code": "claude-3-5-sonnet" }, "timeout": 60000, "retries": 2 }, "ui": { "showModelPicker": true, "defaultAction": "summarize" } }

两个文件的字段名保持一致，插件读 settings.json，服务端读 config.toml，改一处要同步另一处。团队里最好把这两个文件纳入版本管理，别让每个人本地各改一份。

3.3 参数对照表

提示：模型名按 TaoToken 文档里列出的可用模型填，别照搬别家平台的命名。

4. 插件侧统一 Key 配置与连通性验证

4.1 在插件里指向统一通道

以自研或改装的 AI 插件为例，插件入口 JS 里读取 settings.json，把请求发到统一 baseUrl。核心逻辑：

async function callAI(prompt, model) { const cfg = await loadSettings(); const apiKey = process.env[cfg.ai.apiKeyEnv]; const resp = await fetch(`${cfg.ai.baseUrl}/v1/chat/completions`, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` }, body: JSON.stringify({ model: model || cfg.ai.defaultModel, messages: [{ role: "user", content: prompt }] }) }); if (!resp.ok) throw new Error(`AI 请求失败: ${resp.status}`); return resp.json(); }

注意 baseUrl 后面拼的是 /v1/chat/completions，这是 OpenAI 兼容路径。如果你的插件用的是别的协议，按 TaoToken 文档调整路径。

4.2 连通性验证

先脱离 ONLYOFFICE，用 curl 直接打一次，确认 Key 和通道没问题：

curl -sS https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "用一句话说明什么是协作办公"}] }'

返回里能看到 choices[0].message.content 就说明通道通了。这一步过了，再回 ONLYOFFICE 里点插件按钮。如果 curl 通、插件不通，问题在插件配置或环境变量没传进去。

4.3 在编辑器里实测

打开一个文档，选中一段文字，调用插件的「总结」或「翻译」。成功的话结果会显示在侧边栏或选区下方。PDF 编辑器同理，选中文本后走同一个通道。表格里可以让插件生成公式说明，演示文稿里生成讲稿要点。验证模型是否可用，也可以直接到模型对话页试：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

5. 本篇常见错排查

5.1 401 Unauthorized

最常见。原因通常是环境变量没生效，或者 Key 复制时带了空格。检查：

echo "${TAOTOKEN_API_KEY:0:6}"

应该输出 sk- 开头的前几位。如果为空，说明服务进程没读到环境变量，检查 systemd 的 EnvironmentFile 路径和权限。

5.2 404 或路径错误

baseUrl 写成 https://taotoken.net 而漏了 /api，或者拼了错误的路径。统一用 https://taotoken.net/api 作为前缀，后面接 /v1/chat/completions。插件里如果写死了旧路径，改 settings.json 里的 baseUrl。

5.3 超时或连接被拒

自托管服务端出不去，或者 DNS 解析失败。先在服务器上跑 2.3 节的 curl。如果是容器部署，确认容器网络能访问外网，别只在宿主机测。

5.4 插件读不到 settings.json

路径不对，或者 JSON 格式有误。用 jq 校验：

jq . /etc/onlyoffice/documentserver/plugins/settings.json

报错就说明 JSON 语法有问题，常见是多了逗号或少了引号。路径要和 config.toml 里的 config_path 一致。

5.5 模型名不识别

返回 model not found，说明填的模型名不在 TaoToken 可用列表里。到文档页核对：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。改 settings.json 里的 defaultModel 和 models 映射。

5.6 多人协作时 Key 冲突

团队里有人本地覆盖了环境变量，导致部分请求走错通道。统一从服务端注入，禁止个人在插件里手填 Key。需要长期跑编码类或 Agent 类任务的，可以单独用 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，和文档插件的 Key 分开管理。

6. 把统一通道用起来

配置跑通之后，日常维护其实就三件事：Key 轮换时只改环境变量、模型升级时只改 settings.json 的映射、插件新增时复用同一份 config.toml。团队里新同学入职，给他配好环境变量和两个配置文件，十分钟就能在 ONLYOFFICE 里用上 AI，不用挨个插件教。

如果你还在选型阶段，建议先用模型对话页试几个模型，确认哪个适合你们的文档场景，再写进配置。接入文档和可用模型列表在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，Key 在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 创建。踩过的坑基本都在第 5 节，遇到报错先按那几条对一遍，比翻日志快。