1. 为什么要在本地跑一套 Codex Docs还要接上统一 KeyCodex Docs 是一个基于 Editor.js 的轻量文档应用说白了就是给你一个干净的块编辑器用来写技术文档、接口说明、团队知识库。它不像那些重型 Wiki 那样一上来就要你配一堆中间件核心就是一个 Node 后端加一个本地数据库文件Docker 一拉就能跑。适合谁我觉着三类人最合适一是想给自己项目搭个内部文档站的后端同学二是需要把文档能力嵌进自己工具链的独立开发者三是想拿它当 Editor.js 落地案例来研究的前端。它本身不复杂复杂的是「本地跑起来之后怎么让外面的人也能访问」以及「怎么让文档应用里的 AI 能力走一个统一的 Key 出口」。先说清楚这篇要解决的两件事。第一件是部署链路用 Docker 把 Codex Docs 跑在本地 3313 端口再用内网穿透工具把端口映射到公网实现外部访问。第二件是 Key 治理Codex Docs 本身是个文档编辑器但你在实际用的时候往往会挂一些 AI 辅助能力比如让模型帮你润色段落、生成摘要、补全接口说明。这些调用如果每个工具都单独配一套 Key管理起来就是灾难。TaoToken 在这里的角色是提供一个统一的 API 出口你只需要在配置文件里写一份 Base URL、一个 Key、一个 Model ID所有走 OpenAI 兼容协议的工具都能复用。我试过把文档应用和编码工具混在一起管 Key结果就是每次换模型都要翻五六个配置文件。后来统一到一个出口之后settings.json 和 config.toml 里只留一份凭证清爽很多。下面从 Docker 部署开始一步步把本地到公网的链路打通再把 TaoToken 的配置骨架塞进去。2. TaoToken 前置准备统一 Key 与接入信息在动 Docker 之前先把 Key 这块理清楚不然后面配置写到一半又要回头找。TaoToken 的定位是一个模型调用聚合入口你拿到一个 Key 之后可以用它去调对话模型、编码模型走的是 OpenAI 兼容的接口格式。这意味着任何支持自定义 Base URL 的工具都能把请求指过来。你需要准备三样东西Base URL、API Key、Model ID。Base URL 是https://taotoken.net/api注意这个地址不带任何查询参数直接作为接口根路径用。API Key 在控制台的 API Keys 页面创建创建完复制出来只显示一次丢了就重新建。Model ID 取决于你要调哪个模型比如做文档润色可以用对话类模型做代码补全可以用编码类模型具体 ID 在模型列表里查。这里有个容易踩的坑很多人把 Base URL 写成带/v1或者带斜杠结尾的形式结果请求 404。正确做法是只写到/api至于/v1/chat/completions这部分路径由你用的 SDK 或者工具自己拼。如果你用的是 OpenAI 官方 SDK它默认会拼/chat/completions那 Base URL 就得包含到/v1那一层但 TaoToken 的接入文档里写得很清楚根路径就是/api具体拼接规则看文档里的示例。创建 Key 的入口在控制台接入文档里有完整的请求示例和参数说明。我建议你先把 Key 创建好放在一个临时的地方等会儿写配置文件的时候直接粘。另外如果你后面要长期跑编码类任务或者 Agent可以考虑 Coding Plan它更适合高频调用场景如果只是偶尔验证一下模型通不通用模型对话页面直接测就行。注意Key 不要写进会提交到 Git 的配置文件里。生产环境用环境变量注入本地测试可以用.env文件配合.gitignore。3. 可复制配置Docker Compose 与 settings.json/config.toml 骨架这一节是核心所有配置都给你可复制的片段。先建目录结构再写 compose 文件最后把 TaoToken 的 Key 配置塞进 settings.json 和 config.toml 两个骨架里。第一步创建项目目录。我习惯把数据、数据库、上传文件分开挂载这样备份和迁移都方便mkdir -p /volume2/docker/codex.docs/{data,db,uploads} cd /volume2/docker/codex.docs第二步写docker-compose.yml。注意端口映射是3313:3000容器内部跑 3000宿主机暴露 3313后面内网穿透映射的就是 3313version: 3.2 services: docs: image: ghcr.io/codex-team/codex.docs:v2.1 container_name: codex-docs ports: - 3313:3000 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 restart: unless-stopped第三步写docs-config.yaml。这里我保留了原版的结构但把认证密码改掉数据库用本地驱动避免额外依赖 MongoDBport: 3000 host: 0.0.0.0 uploads: driver: local local: path: ./uploads frontend: title: CodeX Docs description: Docs powered by Editor.js startPage: auth: password: your-strong-password secret: your-random-secret database: driver: local local: path: ./db注意host我改成了0.0.0.0原版是localhost如果保持 localhost容器外部访问会连不上。这是个很隐蔽的坑后面排障章节会细说。第四步TaoToken 统一 Key 的配置骨架。Codex Docs 本身不直接读这两个文件但你的 AI 辅助工具链会读。settings.json是很多编辑器类工具用的格式config.toml是 Codex 系工具用的格式。两个都给你按需取用。settings.json骨架{ api: { baseUrl: https://taotoken.net/api, apiKey: sk-your-taotoken-key, model: your-model-id }, docs: { endpoint: http://localhost:3313, authPassword: your-strong-password } }config.toml骨架[api] base_url https://taotoken.net/api api_key sk-your-taotoken-key model your-model-id [docs] endpoint http://localhost:3313 auth_password your-strong-password如果你用的是 Claude Code 这类工具配置路径通常在~/.claude/settings.json或者项目级的.claude/settings.json把上面的api段塞进去就行。如果是 Codex 系工具auth.json里需要写 Base URL、Key、Model ID 三件套格式参考接入文档。Cline MCP 的场景下配置写在 MCP server 的启动参数里同样是这三个值。第五步启动容器docker-compose up -d启动后用docker ps确认容器状态是 Up然后浏览器打开http://localhost:3313输入你在docs-config.yaml里设的密码就能看到 Editor.js 的编辑界面了。4. 验证请求与外部访问连通性本地跑通只是第一步真正要验证的是两件事TaoToken 的 Key 能不能正常调通模型以及内网穿透之后外部能不能访问到 Codex Docs。先验证 TaoToken。用 curl 直接打一个对话请求确认 Key 和 Base URL 都对curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-your-taotoken-key \ -H Content-Type: application/json \ -d { model: your-model-id, messages: [{role: user, content: ping}], max_tokens: 10 }如果返回里有choices字段说明 Key 通了。如果返回 401检查 Key 有没有复制完整如果返回 404检查 Base URL 是不是多写了或者少写了路径段。再验证 Codex Docs 本地访问。用 curl 打本地端口确认服务在监听curl -I http://localhost:3313返回 200 或者 302 都算正常。如果连接被拒绝说明容器没起来或者端口没映射对。接下来是外部访问。内网穿透工具我用的是路由侠它的逻辑是在本地跑一个客户端把本地端口注册到它的服务端然后给你一个公网地址。先在任意一台 Windows 机器上装路由侠客户端进入设备中心点添加设备拿到安装码。然后在 Linux 这边用 Docker 跑路由侠的客户端容器wget https://dl.luyouxia.com:8443/v2/lyx-docker-x86_64.tar docker load -i lyx-docker-x86_64.tar docker run --name lyx -it --restartalways --nethost -e code你的安装码 luyouxia/lyx注意--nethost这个参数它让容器直接用宿主机网络这样路由侠才能访问到宿主机的 3313 端口。跑起来之后按 CtrlC 会退出用docker start lyx让它后台持续运行。回到 Windows 客户端的设备列表刷新一下就能看到这台设备。点内网映射右上角选中刚添加的设备点添加映射选原生端口内网端口填 3313创建。等大约 30 秒映射生效后会生成一个公网地址。复制这个地址在任意外网机器的浏览器里打开如果能看到 Codex Docs 的登录界面说明整条链路通了。这里有个验证技巧不要只在自己电脑上测用手机流量或者让同事帮忙访问一下排除本地 DNS 缓存或者防火墙的干扰。如果外网打不开但本地能开八成是映射没生效或者端口填错了。5. 本篇常见错误排查这一节列几个真实会撞上的报错对照着查。第一个401 Unauthorized。这个基本是 Key 的问题。检查三处Key 有没有复制完整有时候复制会漏掉末尾字符、请求头里Authorization的格式是不是Bearer sk-xxx、Key 有没有被禁用或者过期。如果 Key 是对的但还是 401看看是不是把 Base URL 写成了别的域名。第二个local proxy failed或者连接超时。这个通常出现在内网穿透环节。路由侠客户端容器如果没用--nethost它就没法访问宿主机的 3313 端口映射自然失败。另外检查宿主机的防火墙有没有放行 3313有些系统默认只开 80 和 443。第三个reading choices报错。这个一般是你调模型接口时返回体结构不对。常见原因是 Base URL 写错了请求打到了错误的路径返回了一个 HTML 错误页而不是 JSON。确认 Base URL 是https://taotoken.net/api并且你的 SDK 拼接路径正确。如果用的是 OpenAI SDK注意它会在 Base URL 后面拼/chat/completions所以 Base URL 要写到/v1那一层但 TaoToken 的文档里根路径是/api具体看文档示例。第四个OAuth 相关报错。如果你用的是 Claude Code 或者 Codex 系工具它们可能默认走 OAuth 登录流程。你要做的是在配置里显式指定 API Key 模式把auth.json或者settings.json里的认证方式改成 Key而不是让它去走浏览器授权。三件套写全Base URL、Key、Model ID缺一个都可能触发 OAuth 回退。第五个Codex Docs 页面打开是空白。检查docs-config.yaml里的host是不是0.0.0.0如果是localhost容器外部访问会拿到空响应。另外检查uploads和db目录的权限容器内的用户需要有写权限否则启动时会静默失败。第六个路由侠映射生效慢。官方说大约 30 秒但实际有时候要等一两分钟。如果超过五分钟还没生效删掉映射重新创建一次比干等快。6. 把 Key 和访问链路固定下来走到这一步你手上应该有一套能跑的 Codex Docs一个能用的公网地址以及一份统一的 TaoToken Key 配置。接下来要做的是把临时验证变成稳定运行。第一把docs-config.yaml里的密码和 secret 换成强随机值不要用示例里的secretpassword。第二把 TaoToken 的 Key 从配置文件里挪到环境变量用env注入避免误提交。第三路由侠容器设成--restartalways宿主机重启后自动恢复映射。第四定期备份db和uploads目录文档数据丢了比服务挂了更麻烦。如果你后面要在这个文档站上挂更多 AI 能力比如自动生成目录、段落润色、接口文档补全统一走 TaoToken 的出口就行。换模型的时候只改一个 Model ID不用动其他配置。需要长期跑编码类任务的话Coding Plan 比按次调用更划算只是偶尔验证模型通不通用模型对话页面直接测最快。Key 的管理入口在控制台的 API Keys 页面接入细节看接入文档里面有完整的请求示例和参数说明。