1. 为什么我决定用 100 篇死磕 OpenClaw 源码OpenClaw 是一个用 TypeScript 写的 Agent 运行时框架核心模块包括 Gateway网关层负责消息路由与协议适配和 Agent智能体执行层负责 LLM 调用与工具编排。它适合谁适合那些不满足于“调个 API 就完事”、想搞清楚 Agent 框架内部到底怎么跑起来的技术人。我试过直接上手读 OpenClaw 的src/目录第一次打开的时候满屏的 TypeScript 类型定义和依赖注入说实话有点懵。后来我换了个思路先跑起来再打断点最后顺着调用链一行行看。这个系列就是把我踩过的坑和总结的方法论拆成 100 篇可跟做的文章。你可能会问现在 Agent 框架这么多为什么偏偏选 OpenClaw我的判断是它的架构分层足够清晰——Transport → Gateway → Orchestration → Application 四层各司其职代码组织方式在很多 Agent 项目里都有影子。读透它你再去看别的框架会快很多。这篇是系列的第 1 篇目标很明确帮你把本地源码阅读环境搭好把 Gateway 和 Agent 的关键调用链断点设好再用 TaoToken 的统一 API 通道验证一次完整的 Gateway 请求转发。做完这三件事你就有了一套可复用的源码调试工作流后面 99 篇都能在这个环境里跑。2. 本地源码阅读环境搭建与 Gateway 断点调试配置2.1 克隆仓库与依赖安装先把代码拉到本地。OpenClaw 用 pnpm 做包管理Node 版本建议 20 LTS 以上。git clone https://github.com/openclaw/openclaw.git cd openclaw corepack enable pnpm install安装完成后先别急着跑。我建议你先做一件事在项目根目录建一个.vscode/launch.json把调试配置写好。这样后面设断点的时候可以直接 F5 启动不用每次手动拼命令。{ version: 0.2.0, configurations: [ { name: Debug Gateway, type: node, request: launch, runtimeExecutable: pnpm, runtimeArgs: [tsx, src/entry.ts], cwd: ${workspaceFolder}, env: { NODE_ENV: development, OPENCLAW_LOG_LEVEL: debug }, console: integratedTerminal, skipFiles: [node_internals/**] } ] }这里有几个关键点。runtimeExecutable用 pnpm 而不是 node是因为 OpenClaw 的入口依赖 workspace 内的包解析。OPENCLAW_LOG_LEVELdebug打开详细日志后面追踪 Gateway 消息路由的时候会省很多事。skipFiles把 Node 内部模块跳过断点只会停在你的业务代码里。2.2 关键断点位置环境搭好之后在下面这几个文件里设断点。我按调用顺序列出来第一个断点设在src/entry.ts的 main 函数入口。这是程序的第一行代码你能看到 Gateway 是怎么从命令行参数初始化出来的。第二个断点设在src/gateway/server.ts的消息路由函数里。具体位置是处理 incoming message 的那个 switch 或 if-else 分支。消息进来之后怎么判断该走哪个 Agent、该调哪个 Skill全在这里。第三个断点设在src/agent/agent-run-dispatch.ts的 dispatch 方法。这是 Agent 执行链路的起点从这里开始请求会经过agent-run-handler.ts的 Pipeline 生命周期最终进入run-orchestrator.ts的编排循环。第四个断点设在src/agent/run-orchestrator.ts里调用 LLM 的那一行。你会看到请求体是怎么拼出来的Tool 定义是怎么注入的以及响应回来之后怎么解析。设好这四个断点按 F5 启动调试。如果一切正常终端会输出 Gateway 监听的端口号通常是 3000 或 8080具体看配置文件。2.3 用 TaoToken 统一 API 通道OpenClaw 的 Agent 模块需要调用 LLM。为了不把时间浪费在配多个厂商的 Key 上我用 TaoToken 做统一入口。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的接口格式OpenClaw 的 Provider 配置里直接填这个 Base URL 就行。你需要在 TaoToken 控制台创建一个 API Key然后拿到一个 Model ID。这两个东西加上 Base URL就是 OpenClaw 接入 LLM 的三件套。具体配置我放在下一节这里先记住Base URL 填https://taotoken.net/apiKey 填你创建的那串Model ID 填你选定的模型标识。3. 可复制的 OpenClaw Gateway 与 Agent 配置片段3.1 环境变量与 settings 配置OpenClaw 的配置体系支持环境变量和配置文件两种方式。我建议开发阶段用.env文件方便切换。在项目根目录创建.env.localOPENCLAW_GATEWAY_PORT3000 OPENCLAW_LOG_LEVELdebug OPENCLAW_PROVIDER_BASE_URLhttps://taotoken.net/api OPENCLAW_PROVIDER_API_KEYsk-your-taotoken-key OPENCLAW_DEFAULT_MODELyour-model-id注意OPENCLAW_PROVIDER_BASE_URL后面不要加/v1OpenClaw 的 Provider 层会自动拼接路径。如果你填了/v1请求会变成/v1/v1/chat/completions直接 404。如果你更喜欢用 JSON 配置文件OpenClaw 支持在config/gateway.json里写{ gateway: { port: 3000, logLevel: debug }, provider: { baseUrl: https://taotoken.net/api, apiKey: ${OPENCLAW_PROVIDER_API_KEY}, defaultModel: your-model-id, timeout: 30000 }, agent: { maxToolRounds: 5, contextWindow: 128000 } }这个 JSON 里的${OPENCLAW_PROVIDER_API_KEY}是变量引用语法OpenClaw 启动时会从环境变量里读。这样你可以把 Key 放在.env.local里JSON 文件提交到 Git 也不会泄露。3.2 Agent 与 Gateway 的对接配置Gateway 负责接收外部请求Agent 负责执行。两者之间的对接在config/agent.json里定义{ agents: [ { id: default, name: Default Agent, provider: taotoken, model: your-model-id, systemPrompt: You are a helpful assistant., tools: [shell, file-read, file-write], maxRounds: 5 } ], routing: { defaultAgent: default, rules: [ { match: { channel: http }, agent: default } ] } }这里的provider字段填taotoken对应你在gateway.json里定义的 provider 名称。routing.rules决定了一条消息进来之后Gateway 把它分发给哪个 Agent。你现在看到的是最简单的单 Agent 配置后面第 14 篇讲多 Agent 协同的时候会扩展这个结构。3.3 启动与验证配置写完之后启动 Gatewaypnpm tsx src/entry.ts --config config/gateway.json如果终端输出类似Gateway listening on port 3000的日志说明启动成功。这时候你可以用 curl 发一条测试消息curl -X POST http://localhost:3000/v1/chat \ -H Content-Type: application/json \ -d { agentId: default, message: Hello, what can you do? }如果返回的 JSON 里有choices字段说明 Gateway 成功把请求转发给了 AgentAgent 又通过 TaoToken 调用了 LLM。整条链路跑通了。4. 验证 Gateway 请求转发与 Agent 调用链4.1 用断点追踪一条消息的完整旅程上一节你用 curl 发了请求现在回到 VS Code 的调试模式重新发一次。这次断点会依次命中。第一个命中在entry.ts程序启动时的初始化流程。继续按 F5第二个断点命中在gateway/server.ts的消息路由函数。你能看到req.body里的agentId和message以及路由规则是怎么匹配到defaultAgent 的。继续往下第三个断点命中在agent-run-dispatch.ts。这里你会看到 Agent 的上下文是怎么构建的system prompt、历史消息、工具定义全部在这里组装成一个请求对象。第四个断点在run-orchestrator.ts的 LLM 调用处。按 F10 单步跳过这一行观察response对象的结构。如果一切正常response.choices[0].message.content就是 LLM 返回的文本。4.2 验证 TaoToken 通道是否生效怎么确认请求真的走了 TaoToken 而不是别的通道两个方法。第一个方法在run-orchestrator.ts调用 LLM 之前打印provider.baseUrl。如果输出是https://taotoken.net/api说明配置生效了。第二个方法打开 TaoToken 控制台的请求日志页面发一条消息刷新日志。你应该能看到一条对应的请求记录包含 Model ID、Token 消耗量和响应时间。这是最直接的验证方式。如果你在断点里看到provider.baseUrl是空的或者默认值检查.env.local里的OPENCLAW_PROVIDER_BASE_URL有没有被正确加载。OpenClaw 用 dotenv 加载环境变量.env.local的优先级高于.env。4.3 观察 Tool 调用循环OpenClaw 的 Agent 支持多轮 Tool 调用。你可以在run-orchestrator.ts的循环入口设一个断点然后发一条会触发 Tool 的消息比如“列出当前目录下的文件”。断点会命中多次。第一次是 LLM 返回 Tool 调用请求第二次是 Tool 执行完毕把结果回传给 LLM第三次是 LLM 生成最终回复。这个循环最多执行maxToolRounds次超过之后会强制结束并返回当前结果。观察每一轮循环里messages数组的变化你能清楚地看到 Tool 调用结果是怎么追加到上下文里的。这个机制是 Agent 框架的核心后面第 8 到 13 篇会逐行拆解。5. 常见报错与排查401、local proxy failed、reading choices5.1 401 Unauthorized这是最常见的错误。终端输出401 Unauthorized或者Invalid API key说明 TaoToken 的 Key 没配对。排查步骤第一检查.env.local里的OPENCLAW_PROVIDER_API_KEY是否以sk-开头有没有多余的空格或换行。第二确认这个 Key 在 TaoToken 控制台里是启用状态。第三如果你用的是 JSON 配置检查${OPENCLAW_PROVIDER_API_KEY}的变量名是否和.env.local里的一致大小写敏感。修复之后重启 Gateway再发一次请求。如果还是 401把 Key 复制到 curl 命令里直接测 TaoToken 的接口排除是 OpenClaw 配置问题还是 Key 本身的问题。5.2 local proxy failed这个报错通常出现在 Gateway 启动阶段日志里会写local proxy failed to connect或者ECONNREFUSED。原因是 Gateway 尝试连接的 Provider 地址不通。检查OPENCLAW_PROVIDER_BASE_URL是否写成了https://taotoken.net/api注意是https不是http末尾不要加/v1。如果你在本地开了其他网络工具先关掉再试。OpenClaw 的 Provider 层用的是标准 fetch不依赖系统代理设置。还有一个容易忽略的点如果你的 Node 版本低于 18fetch 可能不可用。用node -v确认版本低于 18 的话升级到 20 LTS。5.3 reading choices 报错完整报错通常是Cannot read properties of undefined (reading choices)。这说明 LLM 返回的响应结构不符合预期代码在访问response.choices的时候拿到了undefined。三个可能的原因。第一TaoToken 返回的是错误响应比如{error: {message: ...}}没有choices字段。你需要在run-orchestrator.ts里加一行日志打印完整的response对象看看实际返回了什么。第二Model ID 填错了TaoToken 找不到对应的模型返回了错误信息。第三请求体格式不对比如messages数组为空某些模型会直接返回错误。排查方法在断点里展开response对象看error字段有没有内容。如果有根据错误信息调整配置。如果没有error也没有choices检查请求体的model字段是否和 TaoToken 控制台里的 Model ID 完全一致。5.4 OAuth 相关报错如果你在启动时看到OAuth token expired或refresh token failed说明 OpenClaw 的某个插件或 Skill 尝试用 OAuth 认证。开发阶段可以先把相关插件禁用在config/agent.json的tools数组里去掉对应的工具名。如果你确实需要 OAuth 认证的 Skill检查config/auth.json里的 token 是否过期。OpenClaw 的 Auth 模块支持自动刷新但需要refreshToken和clientId都配置正确。这部分内容在第 16 到 60 篇的周边基建部分会详细展开。6. 用 TaoToken 打通 OpenClaw 全链路调试源码阅读最怕的就是环境跑不起来或者跑起来了但不知道请求到底发到了哪里。这篇给你的是一套可复用的工作流本地克隆 → VS Code 断点 → TaoToken 统一通道 → curl 验证 → 日志排查。你现在应该已经能做到在entry.ts看到 Gateway 启动在server.ts看到消息路由在agent-run-dispatch.ts看到 Agent 调度在run-orchestrator.ts看到 LLM 调用和 Tool 循环。这四个断点覆盖了 OpenClaw 最核心的调用链后面 99 篇的源码解读都会在这个基础上展开。TaoToken 在这个工作流里扮演的是“统一出口”的角色。你不需要为每个模型厂商单独配 Key也不需要改 OpenClaw 的 Provider 代码。Base URL 填https://taotoken.net/apiKey 和 Model ID 从控制台拿三件套配好就能跑。如果你想先验证模型对话效果可以直接用模型对话功能测一下通道是否通畅如果你打算长期跟这个系列做编码和 Agent 调试Coding Plan 会更划算接入过程中遇到报错先去接入文档里对照错误码大部分问题都有现成的解决方案。下一篇我会拆 OpenClaw 的项目定位与设计哲学讲清楚它为什么把 Gateway 和 Agent 分成两层、TypeScript 的类型系统在 Agent 框架里到底解决了什么问题。你可以先把这篇的环境搭好断点设上下一篇文章的代码你就能直接跟读了。