1. Codex Docs 接入 AI 时到底卡在哪Codex Docs 是一个基于 Editor.js 的文档应用适合搭内部知识库、产品手册或者个人笔记站。它的内容结构很有意思每个段落、标题、图片、引用都是一个独立的 block数据以 JSON 形式存下来。这种块式结构对 AI 其实很友好因为你可以按 block 粒度做摘要、改写、翻译而不是把整篇文档当成一坨纯文本硬塞给模型。但真正动手接 AI 的时候问题就来了。Codex Docs 本身没有内置任何大模型调用能力你得自己在后端加一层。而这一层要处理的事情比想象中多Key 放哪、用哪个 SDK、请求格式怎么统一、Editor.js 的 block 数组怎么转成模型能吃的 prompt、返回结果又怎么塞回 block。更麻烦的是如果你同时想用几个不同厂商的模型做对比每个厂商的 endpoint、鉴权头、参数命名都不一样代码里很快就会堆满 if-else。我试过直接在 Codex Docs 的 backend 里硬编码某家厂商的调用结果换模型时改了七八个文件。后来改成走统一 Key/API 通道把模型差异收敛到一个配置层情况就好很多。这篇就按这个思路给出settings.json和config.toml两份可复制骨架再演示一次从 Editor.js block 到模型返回的完整请求验证。适合谁看已经在跑 Codex Docs、想给它加 AI 摘要/改写/翻译能力的开发者或者正在用 Editor.js 做编辑器、需要一套统一模型接入层的同学。前置条件是你已经能用 docker-compose 把 Codex Docs 跑起来对 Node.js 和配置文件不陌生。2. 前置准备TaoToken 统一通道与 Key 获取统一通道的价值在于你不需要在 Codex Docs 里为每个模型厂商写一套适配代码。所有请求都发到同一个 base URL用同一个 Key模型名作为参数传进去。这样配置层只需要维护一份 Key 和一份模型清单换模型就是改一个字符串。TaoToken 的 API 入口是https://taotoken.net/api兼容 OpenAI 风格的请求格式所以你可以直接用现成的 OpenAI SDK把baseURL指过去就行。这对 Codex Docs 这种 Node 后端特别省事不用引入额外的厂商 SDK。拿 Key 的步骤打开https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite登录后在控制台创建 API Key。建议给 Codex Docs 单独建一个 Key命名成codex-docs-prod之类方便后面按项目排查用量。创建后立刻复制保存页面刷新后就不再完整显示。模型名怎么填在模型对话页面https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite可以看到当前可用的模型列表把你要用的模型 ID 记下来后面写进配置文件。如果你打算长期跑编码类或 Agent 类任务可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite它更适合高频调用场景。注意Key 只放在服务端配置文件或环境变量里绝对不要写进前端代码或提交到 Git 仓库。Codex Docs 的前端是 Editor.js 渲染层任何打进 bundle 的 Key 都等于公开。3. 可复制配置骨架settings.json 与 config.tomlCodex Docs 的配置入口是docs-config.yaml但 AI 相关的配置我建议单独拆出来不要和文档应用本身的配置混在一起。原因很简单文档配置改动频率低AI 配置你可能天天调模型、调温度、调超时。拆开后互不影响也方便做多环境。下面这份settings.json放在 Codex Docs 项目根目录由后端启动时读取。它描述的是「用哪个通道、哪个模型、什么参数」。{ ai: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, defaultModel: gpt-4o-mini, models: { summary: gpt-4o-mini, rewrite: claude-3-5-sonnet, translate: gpt-4o-mini }, request: { timeoutMs: 30000, maxRetries: 2, temperature: 0.3 }, features: { blockSummary: true, blockRewrite: true, docTranslate: false } } }几个字段说明。apiKeyEnv指向环境变量名而不是直接写 Key这样容器里通过-e TAOTOKEN_API_KEYxxx注入就行。models按用途分摘要用便宜快的改写用质量高的互不干扰。timeoutMs给 30 秒Editor.js 的 block 多的时候请求体不小太短容易断。再来看config.toml。这份文件我用来描述 Editor.js block 到 prompt 的映射规则因为不同 block 类型处理方式不一样段落直接拼文本标题要加层级标记代码块要保留语言标识图片块只取 caption。[editorjs] version 2.28 [editorjs.block_map] paragraph text header heading code code quote quote list list image caption [editorjs.prompt] system 你是一个文档助手基于用户提供的 Editor.js block 内容完成任务。 summary_template 请用三句话总结以下文档内容\n\n{{content}} rewrite_template 请在不改变原意的前提下改写以下段落使其更简洁\n\n{{content}} translate_template 请将以下内容翻译为英文保留原有结构\n\n{{content}} [editorjs.limits] max_blocks_per_request 50 max_chars_per_request 12000block_map决定了遍历 Editor.js 的blocks数组时每种type取哪个字段。比如paragraph取data.textheader取data.text同时读data.levelcode取data.code和data.language。limits是保护措施block 太多或字符太长就分批避免单次请求超限。把这两份文件和 Codex Docs 的docs-config.yaml放同一目录docker-compose 里挂载进去version: 3.2 services: docs: image: ghcr.io/codex-team/codex.docs:v2.1 container_name: codex-docs ports: - 3313:3000 environment: - TAOTOKEN_API_KEY${TAOTOKEN_API_KEY} - AI_SETTINGS_PATH/usr/src/app/settings.json - AI_CONFIG_PATH/usr/src/app/config.toml command: - node - dist/backend/app.js - -c - docs-config.yaml volumes: - ./uploads:/usr/src/app/uploads - ./db:/usr/src/app/db - ./docs-config.yaml:/usr/src/app/docs-config.yaml - ./settings.json:/usr/src/app/settings.json - ./config.toml:/usr/src/app/config.toml启动前在.env文件里写TAOTOKEN_API_KEY你的Keydocker-compose 会自动注入。这样 Key 不进镜像、不进代码仓库换 Key 只改.env。4. 验证请求从 Editor.js block 到模型返回配置写完必须验证一次否则你不知道是配置错了还是模型没通。我写了一个最小验证脚本直接读settings.json和config.toml构造一个假的 Editor.js 文档走完整链路。先看 Editor.js 的典型数据结构{ time: 1700000000000, blocks: [ { type: header, data: { text: 部署说明, level: 2 } }, { type: paragraph, data: { text: 本文档介绍 Codex Docs 的安装流程。 } }, { type: code, data: { code: docker-compose up -d, language: bash } } ], version: 2.28 }验证脚本verify-ai.jsconst fs require(fs); const TOML require(iarna/toml); const settings JSON.parse(fs.readFileSync(./settings.json, utf8)); const config TOML.parse(fs.readFileSync(./config.toml, utf8)); const doc { blocks: [ { type: header, data: { text: 部署说明, level: 2 } }, { type: paragraph, data: { text: 本文档介绍 Codex Docs 的安装流程。 } }, { type: code, data: { code: docker-compose up -d, language: bash } } ] }; function blocksToText(blocks) { return blocks.map(b { const field config.editorjs.block_map[b.type]; if (!field) return ; if (b.type header) return ${#.repeat(b.data.level)} ${b.data.text}; if (b.type code) return \\\${b.data.language}\n${b.data.code}\n\\\; return b.data[field] || ; }).filter(Boolean).join(\n\n); } async function main() { const content blocksToText(doc.blocks); const prompt config.editorjs.prompt.summary_template.replace({{content}}, content); const res await fetch(${settings.ai.baseUrl}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${process.env.TAOTOKEN_API_KEY} }, body: JSON.stringify({ model: settings.ai.models.summary, messages: [ { role: system, content: config.editorjs.prompt.system }, { role: user, content: prompt } ], temperature: settings.ai.request.temperature }) }); if (!res.ok) { console.error(请求失败, res.status, await res.text()); process.exit(1); } const data await res.json(); console.log(模型返回, data.choices[0].message.content); } main();运行TAOTOKEN_API_KEY你的Key node verify-ai.js如果配置正确你会看到类似这样的输出模型返回 本文档介绍了 Codex Docs 的安装流程核心步骤是通过 docker-compose 启动服务并给出了对应的启动命令。这一步跑通说明三件事都对了Key 有效、base URL 可达、Editor.js block 到 prompt 的转换逻辑没问题。接下来你只需要把这个blocksToText函数和请求逻辑封装成后端接口在 Codex Docs 的编辑器里加个按钮调用就行。5. 本篇常见错排查配置和验证过程中最容易踩的坑集中在几个地方我按出现频率排一下。401 或 403 鉴权失败。先确认环境变量有没有真正注入容器docker exec codex-docs env | grep TAOTOKEN看一眼。如果变量在但还报错检查 Key 有没有多余空格或者是不是复制时漏了尾部字符。还有一种情况是 Key 被禁用或额度用尽去控制台确认状态。404 路径错误。base URL 必须是https://taotoken.net/api请求路径拼/v1/chat/completions。如果你在 base URL 末尾多加了斜杠或者少写了/v1都会 404。建议把完整 URL 打印出来核对一次。模型名不存在。settings.json里的模型 ID 必须和模型对话页面列出的完全一致大小写敏感。填错会返回 model not found 之类的错误。换模型时只改models字段不要动baseUrl。请求超时。Editor.js 文档 block 多的时候拼出来的 prompt 可能上万字符。timeoutMs给 30 秒是底线如果文档特别大要么调大超时要么按max_blocks_per_request分批。分批逻辑就是在blocksToText外面套一层切片每 50 个 block 发一次请求结果再合并。返回内容塞不回 block。模型返回的是纯文本而 Editor.js 要的是 block 结构。简单做法是把返回文本按换行拆成多个paragraphblock复杂做法是让模型直接返回 JSON 格式的 block 数组。后者需要在 prompt 里明确要求输出结构并在解析时做容错。容器内访问不到外网。如果 Codex Docs 跑在受限网络环境容器可能无法直连 API。确认容器的 DNS 和出站规则docker exec codex-docs curl -I https://taotoken.net/api测一下连通性。提示排查时把settings.ai.request.maxRetries临时设为 0避免重试掩盖真实错误信息。定位到问题后再调回来。6. 把 AI 能力接进 Codex Docs 的下一步配置骨架跑通之后真正要做的集成工作是在 Codex Docs 后端加一个路由接收前端传来的 block 数组和操作类型summary/rewrite/translate调用上面验证过的逻辑把结果返回给编辑器。前端在 Editor.js 的工具栏加个自定义按钮选中 block 后触发请求拿到结果后调用 Editor.js 的 API 插入新 block 或替换原 block。如果你还想让 AI 直接操作文档结构比如「把这段改成列表」「给这篇文档生成目录」那就需要模型返回结构化的 block 数据而不是纯文本。这时候 prompt 工程和 JSON 解析的健壮性就变得很关键建议加一层 schema 校验解析失败时降级成纯文本插入。长期跑编码类或 Agent 类任务的话Coding Plan 在调用频率和成本上会更合适具体可以在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite了解。接入过程中遇到鉴权或路径问题直接查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有针对不同语言和框架的示例。需要管理多个项目的 Key 时控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite可以按项目拆分和查看用量。
