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_LEVEL=debug打开详细日志，后面追踪 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/api，Key 填你创建的那串，Model ID 填你选定的模型标识。

3. 可复制的 OpenClaw Gateway 与 Agent 配置片段

3.1 环境变量与 settings 配置

OpenClaw 的配置体系支持环境变量和配置文件两种方式。我建议开发阶段用.env文件，方便切换。在项目根目录创建.env.local：

OPENCLAW_GATEWAY_PORT=3000 OPENCLAW_LOG_LEVEL=debug OPENCLAW_PROVIDER_BASE_URL=https://taotoken.net/api OPENCLAW_PROVIDER_API_KEY=sk-your-taotoken-key OPENCLAW_DEFAULT_MODEL=your-model-id

注意OPENCLAW_PROVIDER_BASE_URL后面不要加/v1，OpenClaw 的 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 启动与验证

配置写完之后，启动 Gateway：

pnpm 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 成功把请求转发给了 Agent，Agent 又通过 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 choices

5.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 版本低于 18，fetch 可能不可用。用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/api，Key 和 Model ID 从控制台拿，三件套配好就能跑。如果你想先验证模型对话效果，可以直接用模型对话功能测一下通道是否通畅；如果你打算长期跟这个系列做编码和 Agent 调试，Coding Plan 会更划算；接入过程中遇到报错，先去接入文档里对照错误码，大部分问题都有现成的解决方案。

下一篇我会拆 OpenClaw 的项目定位与设计哲学，讲清楚它为什么把 Gateway 和 Agent 分成两层、TypeScript 的类型系统在 Agent 框架里到底解决了什么问题。你可以先把这篇的环境搭好，断点设上，下一篇文章的代码你就能直接跟读了。