1. 为什么要在 ONLYOFFICE 里接一个统一 KeyONLYOFFICE 是一套开源协作办公套件文档、表格、演示文稿、表单、PDF 编辑器都在同一个界面里完成团队可以自托管也可以直接用云端协作空间。它本身不带大模型能力AI 功能全靠插件市场里的插件来补。问题就出在这里插件一多Key 就散。写文档的插件配一个 KeyPDF 摘要的插件配另一个 Key表格公式助手再配一个团队里每个人各自填一遍换人、换项目、换模型都要重新折腾。我试过把几个插件分别接不同厂商的 Key结果就是版本一升级、Key 一过期排查起来像破案。后来改成用 TaoToken 做统一入口一个 Key、一个 API 通道所有 ONLYOFFICE 插件都指向它。TaoToken 是一个大模型 API 聚合与分发平台把多家模型的调用收敛到同一套接口和同一个 Key 上适合需要给编辑器、插件、脚本统一供能的团队。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_KEYsk-你的Keysystemd 管理的服务写进 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 参数对照表字段作用建议值base_url / baseUrlAPI 入口https://taotoken.net/apiapi_key_env / apiKeyEnvKey 环境变量名TAOTOKEN_API_KEYdefault_model默认模型gpt-4o-minitimeout单次请求超时60000 msmax_retries失败重试次数2提示模型名按 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。改 settings.json 里的 defaultModel 和 models 映射。5.6 多人协作时 Key 冲突团队里有人本地覆盖了环境变量导致部分请求走错通道。统一从服务端注入禁止个人在插件里手填 Key。需要长期跑编码类或 Agent 类任务的可以单独用 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 和文档插件的 Key 分开管理。6. 把统一通道用起来配置跑通之后日常维护其实就三件事Key 轮换时只改环境变量、模型升级时只改 settings.json 的映射、插件新增时复用同一份 config.toml。团队里新同学入职给他配好环境变量和两个配置文件十分钟就能在 ONLYOFFICE 里用上 AI不用挨个插件教。如果你还在选型阶段建议先用模型对话页试几个模型确认哪个适合你们的文档场景再写进配置。接入文档和可用模型列表在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建。踩过的坑基本都在第 5 节遇到报错先按那几条对一遍比翻日志快。
协作办公利器再升级：ONLYOFFICE 配 TaoToken 统一 Key 接入 AI 插件入门指南
1. 为什么要在 ONLYOFFICE 里接一个统一 KeyONLYOFFICE 是一套开源协作办公套件文档、表格、演示文稿、表单、PDF 编辑器都在同一个界面里完成团队可以自托管也可以直接用云端协作空间。它本身不带大模型能力AI 功能全靠插件市场里的插件来补。问题就出在这里插件一多Key 就散。写文档的插件配一个 KeyPDF 摘要的插件配另一个 Key表格公式助手再配一个团队里每个人各自填一遍换人、换项目、换模型都要重新折腾。我试过把几个插件分别接不同厂商的 Key结果就是版本一升级、Key 一过期排查起来像破案。后来改成用 TaoToken 做统一入口一个 Key、一个 API 通道所有 ONLYOFFICE 插件都指向它。TaoToken 是一个大模型 API 聚合与分发平台把多家模型的调用收敛到同一套接口和同一个 Key 上适合需要给编辑器、插件、脚本统一供能的团队。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_KEYsk-你的Keysystemd 管理的服务写进 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 参数对照表字段作用建议值base_url / baseUrlAPI 入口https://taotoken.net/apiapi_key_env / apiKeyEnvKey 环境变量名TAOTOKEN_API_KEYdefault_model默认模型gpt-4o-minitimeout单次请求超时60000 msmax_retries失败重试次数2提示模型名按 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。改 settings.json 里的 defaultModel 和 models 映射。5.6 多人协作时 Key 冲突团队里有人本地覆盖了环境变量导致部分请求走错通道。统一从服务端注入禁止个人在插件里手填 Key。需要长期跑编码类或 Agent 类任务的可以单独用 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 和文档插件的 Key 分开管理。6. 把统一通道用起来配置跑通之后日常维护其实就三件事Key 轮换时只改环境变量、模型升级时只改 settings.json 的映射、插件新增时复用同一份 config.toml。团队里新同学入职给他配好环境变量和两个配置文件十分钟就能在 ONLYOFFICE 里用上 AI不用挨个插件教。如果你还在选型阶段建议先用模型对话页试几个模型确认哪个适合你们的文档场景再写进配置。接入文档和可用模型列表在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建。踩过的坑基本都在第 5 节遇到报错先按那几条对一遍比翻日志快。
