★ FEATURED ARTICLE 1. 从一次启动失败说起OpenClaw 源码工程到底怎么跑起来OpenClaw 是一个开源的 AI Agents 集成服务器端用 TypeScript 编写、跑在 Node 运行时里通过本地或远程的服务器网关把前端应用和后端大模型服务串起来。个人用户可以在 PC 上部署本地网关用 Web 控制台聊天企业用户则把网关放到云端让企业微信这类办公应用通过 API 对接。它适合谁适合想读懂 AI Agent 服务端运行机制、愿意翻源码、动手构建的开发者。我第一次拉下 OpenClaw 源码工程时以为npm install npm start就能跑结果卡在网关端口没起来。后来才发现OpenClaw 的运行实例不是普通前端项目它的入口是openclaw.mjs这个命令行可执行文件网关实例以 Http Server 的形式对外提供接口服务一台服务器跑单实例不同服务器之间的用户和 AI Agents 本地缓存数据不同步。这个设计决定了它的架构分层和普通 Web 工程不一样。所以这篇不打算泛泛讲概念而是带你从 TypeScript 模块拆解一路走到 Node 运行时验证先看清源码工程的目录与依赖关系再给出可复制的本地构建与启动配置最后用几个命令确认核心调度链路真的在工作。中间会穿插我踩过的坑比如端口占用、模块找不到、网关进程查不到这些真实报错。核心检索词先摆出来OpenClaw 技术架构、源码工程、TypeScript 模块组织、Node 运行时验证。你如果正在搜「OpenClaw 源码怎么构建」「OpenClaw gateway 启动失败」「OpenClaw TypeScript 模块依赖」这篇应该能对上。2. 前置准备TaoToken 接入与 Node 环境对齐在动源码之前先把两件事准备好Node 运行时版本对齐以及大模型服务的接入凭证。OpenClaw 的 AI Agents 通过工具、技能、通道去调用大模型提供商的远程接口你需要一个 API Key 来对接。我这边用的是 TaoToken 的接入方式官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时别把查询串抄进去。Node 环境这块OpenClaw 源码工程用 TypeScript 编码构建后跑在 Node 引擎中。建议 Node 18 LTS 以上我用的是 20.x。先确认版本node -v npm -v如果版本太低TypeScript 编译和 ESM 模块加载都可能出问题。装依赖前先看一眼package.json里面定义了构建脚本和依赖树。OpenClaw 的源码工程配置文件就是这个package.json它和源码一起构建成 Web 工程最终运行在 Node 引擎里。接入凭证建议单独放环境变量别硬编码进源码。你可以先建一个.env文件TAOTOKEN_API_KEY你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/apiKey 的获取入口在控制台的 API Keys 页面文档在接入文档里这两个地址后面 CTA 会再给一次。这里先记住三件套Base URL、Key、Model ID后面配置网关时都要用到。注意OpenClaw 网关实例是单实例运行的同一台服务器不要起多个网关抢同一个端口否则会出现端口占用报错。不同服务器的网关数据不同步这点在多机部署时要提前规划。环境对齐之后就可以进源码工程看模块组织了。3. 可复制配置TypeScript 模块拆解与本地构建启动OpenClaw 源码工程的模块组织核心可以分成几层入口层openclaw.mjs命令行可执行文件、网关层Http Server 实例、Agent 调度层工具/技能/通道、以及大模型对接层。openclaw.mjs提供运行实例的所有可执行命令是理解整个调度链路的起点。先克隆工程并安装依赖git clone https://github.com/openclaw/openclaw.git cd openclaw npm install安装完看构建脚本通常在package.json的scripts里。构建命令类似npm run build构建产物会输出到dist或类似目录具体以package.json为准。构建完成后用openclaw.mjs启动网关实例node openclaw.mjs gateway --port 18789如果你把它装成了全局命令也可以直接openclaw gateway --port 18789端口 18789 是示例你可以换成没被占用的端口。启动后网关以 Http Server 形式对外提供接口服务。接下来是模型接入配置。OpenClaw 的 Agent 调用大模型时需要 Base URL、Key、Model ID 三件套。如果你用配置文件方式可以写一个 JSON 片段路径按你工程实际结构调整这里以config/gateway.json为例{ gateway: { port: 18789, host: 127.0.0.1 }, model: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, modelId: 你的模型ID } }如果你更习惯 TOML也可以写成[gateway] port 18789 host 127.0.0.1 [model] baseUrl https://taotoken.net/api apiKey ${TAOTOKEN_API_KEY} modelId 你的模型ID注意baseUrl用https://taotoken.net/api不要带 UTM 查询串。apiKey用环境变量注入避免明文提交到仓库。模块依赖关系上入口层加载网关层网关层初始化 Agent 调度层调度层再按需调用模型对接层。你可以用下面的命令粗略看依赖树npm ls --depth1这一步能帮你定位核心调度链路从openclaw.mjs到网关实例再到 Agent 的工具/技能/通道注册。实测下来先把网关跑通再去接模型排障会清晰很多。4. 验证请求Node 运行时确认网关与调度链路配置写完别急着接前端先在 Node 运行时里验证网关是否真的起来了。启动网关后开另一个终端查进程ps -ef | grep openclaw-gateway如果能看到进程说明网关实例在跑。再查端口lsof -i:18789正常会显示监听状态。如果lsof没输出多半是端口没起来或者被别的进程占了。接着发一个本地请求验证 Http Server 是否响应curl -i http://127.0.0.1:18789/返回 200 或带 JSON 的响应说明网关层通了。如果返回连接拒绝回去看启动日志。再验证模型对接层。用三件套发一个最小请求这里以 curl 模拟 Agent 调用模型接口的思路curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [{role: user, content: ping}] }如果返回里有choices字段说明模型对接层通了。这一步很关键因为 OpenClaw 的 Agent 最终就是通过工具、技能、通道去调这个远程接口。验证成功后你可以回到 Web 管理控制台在聊天应用里发一条消息观察网关日志里 Agent 调度链路的输出。实测下来日志里能看到从请求进入、Agent 选择工具、到调用模型、再返回结果的完整路径。这条链路就是 OpenClaw 技术架构的核心。提示验证阶段建议把网关日志级别调高方便看调度细节。生产环境再降回去。5. 常见报错排查401、local proxy failed、reading choices、OAuth排障这块我踩过的坑不少挑几个高频的对照说。401 Unauthorized多半是 Key 没注入或写错。检查环境变量是否生效echo $TAOTOKEN_API_KEY如果为空说明.env没被加载或者你启动网关时没带上环境变量。另外确认baseUrl是https://taotoken.net/api别把 UTM 参数抄进去。local proxy failed这个报错通常出现在网关尝试转发请求但本地代理配置有问题时。检查你的网关 host 和 port 配置确认127.0.0.1:18789没有被防火墙拦。如果你在容器里跑注意端口映射。reading choices 报错一般是模型返回结构不符合预期或者 Model ID 写错。回去核对三件套里的 Model ID确认和平台上的模型标识一致。如果返回体里没有choices先单独用 curl 测模型接口排除是网关层还是模型层的问题。OAuth 相关报错如果你用的是需要 OAuth 的接入方式检查 token 是否过期、回调地址是否配置正确。OAuth 流程和 API Key 流程不要混用配置里选一种。排查顺序建议先确认网关进程和端口再确认模型接口单独可用最后看网关到模型的转发配置。这样能快速定位是入口层、网关层还是模型层的问题。如果你用 CC Switch、Cline MCP 或 Codex 的auth.json这类工具接入记得把三件套写全Base URL、Key、Model ID。缺一个都会报错。6. 继续深入从源码到长期编码与 Agent 调度把网关跑通、模型接通之后你就可以顺着openclaw.mjs往下读源码看 Agent 是怎么注册工具、技能和通道的。核心调度链路一般在网关初始化之后Agent 根据请求选择对应的工具去调模型。你可以用npm ls看模块依赖也可以直接在源码里搜关键类名。如果你打算长期用 OpenClaw 做编码或 Agent 调度建议把接入配置固化下来Key 走环境变量模型 ID 单独管理。需要长期编码或跑 Agent 的话可以看 Coding Plan 的接入方式想先验证模型对话效果用模型对话页面快速试排障和接入细节都在接入文档里。API Keys 在控制台的 API Keys 页面管理。我自己的习惯是每次改完配置先用 curl 测模型接口再重启网关最后看日志确认调度链路。这样出问题能第一时间定位到是哪一层。源码工程的价值就在于你能看清每一步而不是把它当黑盒。
阅读完成 · 觉得有帮助？
