1. server-http.ts 到底在做什么从入口到协议分支的完整拆解server-http.ts 是一个 TypeScript 编写的服务端核心文件它把 HTTP、HTTPS、WebSocket 三类协议能力收拢在同一个模块里对外暴露两个关键函数createGatewayHttpServer和attachGatewayUpgradeHandler。前者负责创建并配置 HTTP 或 HTTPS 服务器后者负责接管upgrade事件把 WebSocket 握手从普通请求流里分流出去。如果你正在读一个网关类项目或者需要改造一个已经跑起来的 Node 服务端这个文件就是理解整个请求生命周期的起点。它适合谁适合已经能写 TypeScript、但对 Node 原生http/https模块的协作方式还不够熟的开发者也适合接手了一个“能跑但看不懂”的服务端文件、需要快速定位入口和协议分支的人。我试过把一个类似结构的文件从零拆到能本地启动最大的感受是它的复杂度不在语法而在“请求阶段”的组织方式——每个功能模块都是一个返回boolean的异步阶段谁先返回true谁就终止后续处理。这个文件的核心检索词可以概括为TypeScript 服务端 HTTP/HTTPS/WebSocket 统一实现、请求阶段流水线、升级事件分流。下面我会按“模块划分清单 → 关键类型定义 → 可复制配置 → 本地验证 → 报错排查”的顺序逐层拆开每一步都给出能直接粘贴运行的片段。先看整体结构。文件大致分成五块导入区、常量与类型定义区、工具函数区、请求处理器工厂区、服务器创建与升级附加区。导入区里既有 Node 原生模块node:crypto、node:http、node:https、node:tls也有项目内部的认证、钩子、插件、Canvas、控制 UI 等子模块。这种“原生 业务”混排的导入方式说明它承担的是聚合层角色而不是纯工具库。请求处理的主线在handleRequest里。它先设置安全头然后判断upgrade头是否为websocket如果是就直接return把控制权交给upgrade事件监听器。这一步很关键很多人第一次读会疑惑“为什么 WebSocket 请求没进业务逻辑”答案就是它被主动让渡出去了。接着它加载配置快照、解析可信代理、规范化 Canvas 作用域 URL再按顺序构建一个requestStages数组。这个数组就是整个文件的灵魂。每个阶段是一个对象形如{ name: string; run: () Promiseboolean | boolean }。runGatewayHttpRequestStages会依次执行遇到第一个返回true的阶段就停止。阶段的顺序大致是hooks → tools-invoke → slack → openresponses可选→ openai可选→ canvas-auth → a2ui → canvas-http → plugin-auth → plugin-http → control-ui-avatar → control-ui-http → gateway-probes。最后如果没有任何阶段命中返回 404。理解了这个流水线你就能回答“一个请求进来后到底走了哪条路”。比如/health会一路走到gateway-probes阶段被处理/api/channels/mattermost/command会在插件阶段被特殊放行认证而/canvas/...会先过canvas-auth再做实际处理。这种设计的好处是新增功能只需往数组里插一个阶段不用改动主流程。2. 前置准备用 TaoToken 拿到可用的模型与 Key在本地把这个服务端跑起来之前你需要一个能提供模型调用的后端。TaoToken 提供统一的 API 入口兼容常见的 OpenAI 风格请求格式适合用来验证服务端里的openai和openresponses阶段是否工作正常。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 。第一步打开模型对话页面确认账号可用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。在这里你可以先发一条测试消息确认返回正常避免后面把服务端问题和账号问题混在一起排查。第二步进入控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建后复制那串以sk-开头的密钥注意它只显示一次。如果你打算长期跑编码类任务可以顺便看一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合持续性的 Agent 调用场景。第三步如果你用的是 Claude Code 这类工具需要单独配置 Anthropic 兼容入口参考文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 可以随时吊销或新建。拿到 Key 之后先别急着改服务端代码。用一条 curl 验证连通性确认 Base URL、Key、Model ID 三件套都对curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的密钥 \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }如果返回里能看到choices数组说明后端链路是通的。这一步的意义在于后面服务端里的handleOpenAiHttpRequest阶段如果报错你可以确定问题出在服务端配置而不是账号本身。把 Key 写进环境变量别硬编码进源码export TAOTOKEN_API_KEYsk-你的密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/api3. 可复制配置模块划分清单与关键类型定义这一节给出可以直接落地的配置片段。先看模块划分清单你可以按这个结构去对照自己的文件server-http.ts ├── imports 原生模块 内部子模块 ├── constants 失败上限、时间窗口、路径映射 ├── types HookClientIpConfig / HookReplayEntry / GatewayHttpRequestStage ├── utils sendJson / writeUpgradeAuthFailure / runGatewayHttpRequestStages ├── hooks-handler createHooksRequestHandler ├── plugin-stages buildPluginRequestStages ├── server-factory createGatewayHttpServer └── upgrade-handler attachGatewayUpgradeHandler关键类型定义里最值得记住的是请求阶段类型和钩子客户端 IP 配置type GatewayHttpRequestStage { name: string; run: () Promiseboolean | boolean; }; export type HookClientIpConfig Readonly{ trustedProxies?: string[]; allowRealIpFallback?: boolean; };GatewayHttpRequestStage决定了整个流水线的扩展方式HookClientIpConfig则影响客户端 IP 的解析结果进而影响速率限制的粒度。如果你要新增一个自定义阶段照着这个类型写就行。接下来是服务端启动配置。假设你用 tsx 或 ts-node 直接跑可以写一个最小的启动脚本import { createGatewayHttpServer, attachGatewayUpgradeHandler } from ./server-http.js; import { WebSocketServer } from ws; const clients new Set(); const wss new WebSocketServer({ noServer: true }); const httpServer createGatewayHttpServer({ canvasHost: null, clients, controlUiEnabled: false, controlUiBasePath: /ui, openAiChatCompletionsEnabled: true, openAiChatCompletionsConfig: { baseUrl: process.env.TAOTOKEN_BASE_URL, apiKey: process.env.TAOTOKEN_API_KEY, model: gpt-4o-mini, }, openResponsesEnabled: false, handleHooksRequest: async () false, resolvedAuth: { mode: none }, }); attachGatewayUpgradeHandler({ httpServer, wss, canvasHost: null, clients, resolvedAuth: { mode: none }, }); httpServer.listen(8787, 127.0.0.1, () { console.log(gateway listening on http://127.0.0.1:8787); });如果你需要 HTTPS把tlsOptions传进去即可服务器会自动切换到createHttpsServerimport { readFileSync } from node:fs; const httpServer createGatewayHttpServer({ // ...其余字段同上 tlsOptions: { key: readFileSync(./certs/localhost-key.pem), cert: readFileSync(./certs/localhost-cert.pem), }, });注意tlsOptions存在与否是 HTTP 和 HTTPS 的唯一分支点源码里就是靠opts.tlsOptions ? createHttpsServer(...) : createHttpServer(...)这一行完成的。所以你在排查“为什么没走 HTTPS”时第一件事就是确认这个字段有没有被传进去。4. 验证请求本地启动与成功结果对照配置写好后启动服务npx tsx ./src/server-http.ts看到gateway listening on http://127.0.0.1:8787就说明服务器起来了。接下来分三条链路验证。第一条健康检查。请求/health和/readycurl -i http://127.0.0.1:8787/health curl -i http://127.0.0.1:8787/ready/health命中GATEWAY_PROBE_STATUS_BY_PATH里的live返回 200 和{ok:true,status:live}。/ready如果没有传getReadiness同样返回 200如果传了就绪检查器且未就绪会返回 503。注意这两个端点只允许 GET 和 HEAD用 POST 会拿到 405 和Allow: GET, HEAD头。第二条OpenAI 兼容链路。因为上面配置里openAiChatCompletionsEnabled为 true请求会进入openai阶段curl -s http://127.0.0.1:8787/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:hello}]}成功时你会看到标准的choices结构。如果这一步返回 401说明resolvedAuth或 Key 有问题如果返回 404说明路径没匹配上任何阶段检查一下请求路径是否在handleOpenAiHttpRequest的识别范围内。第三条WebSocket 升级。用wscat或浏览器控制台连npx wscat -c ws://127.0.0.1:8787/ws连接建立后服务端会走attachGatewayUpgradeHandler里的wss.handleUpgrade然后emit(connection)。如果你在upgrade事件里看到malformedScopedPath为 true会直接收到 401 并断开这是 Canvas 作用域 URL 规范化失败的保护逻辑。三条链路都通之后再回头读requestStages数组你会发现每个阶段对应一个可观测的端点。这种“一个阶段一个验证点”的方式比通读源码再猜行为要高效得多。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth第一个高频错误是 401 Unauthorized。在钩子链路里它来自safeEqualSecret(token, hooksConfig.token)返回 false。此时会先检查速率限制器如果同一客户端键在 60 秒内失败超过 20 次返回 429 并带Retry-After头。排查顺序先确认 token 是通过Authorization: Bearer或X-OpenClaw-Token头传的而不是查询参数——源码里明确对url.searchParams.has(token)返回 400。再确认hooksConfig.token和请求里的 token 完全一致包括大小写。第二个是local proxy failed。这类报错通常出现在你通过本地代理转发请求时服务端解析客户端 IP 失败。resolveRequestClientIp依赖trustedProxies和allowRealIpFallback两个配置。如果trustedProxies为空且allowRealIpFallback为 false代理头里的真实 IP 不会被采纳速率限制会把所有请求算到同一个键上触发误封。解决方式是显式配置可信代理列表或者本地调试时把allowRealIpFallback设为 true。第三个是reading choices相关报错。这通常发生在 OpenAI 阶段服务端拿到了上游响应但结构不符合预期。先确认openAiChatCompletionsConfig里的baseUrl指向 https://taotoken.net/api 并且model字段是有效模型 ID。如果上游返回的是错误对象而不是choices服务端在解析时就会抛错。用第 2 节的 curl 单独验证上游能快速区分是服务端问题还是上游问题。第四个是 OAuth 相关失败。如果项目里集成了 OAuth 回调注意resolveMattermostSlashCallbackPaths会从配置里收集回调路径默认包含/api/channels/mattermost/command。如果回调 URL 配置成了别的路径且没被正确规范化认证阶段会跳过该路径的放行逻辑导致 401。检查配置里的callbackPath和callbackUrl确保它们以/开头且能被isMattermostCommandCallbackPath识别。如果你用的是 Claude Code 或 Cline 这类工具接入配置里必须同时写全三件套Base URL、API Key、Model ID。缺任何一个都会在握手阶段失败。Cline 的 MCP 配置里Base URL 填 https://taotoken.net/api Key 填sk-开头的密钥Model ID 填你验证过的模型名。Codex 的auth.json同理三个字段一个都不能少。6. 把服务端接进你的工作流从验证到长期运行服务端跑通之后下一步是把它接进日常开发流。如果你只是偶尔验证模型返回用模型对话页面就够了https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。但如果你要让这个网关长期处理编码任务或 Agent 调度建议走 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它在持续调用场景下更稳。接入文档里有完整的协议说明和示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。API Keys 页面可以随时轮换密钥https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。控制台里能看到调用量https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。最后给一个实用技巧在handleRequest里临时加一行日志打印requestPath和命中的阶段名能极大缩短排查时间。因为整个流水线是顺序执行的你只要看到哪个阶段返回了 true就知道请求最终去了哪里。这个文件的设计价值也正在于此——它把“一个请求该走哪条路”变成了一个可读、可插、可测的数组而不是散落在各处的 if-else。