1. 为什么源码解析前必须先把 OpenClaw 跑起来OpenClaw 不是那种 clone 下来读几个核心类就能搞懂的项目。它是一套本地优先、多渠道、可调用工具、可扩展技能、带安全隔离的个人 AI 助手系统模块之间靠运行时行为串联CLI 负责入口Gateway 负责常驻控制Agent Runtime 负责执行Channel 插件负责外部消息接入Control UI 负责可视化Sessions 负责上下文沉淀。你如果没跑过一次读代码时很容易把「配置加载」和「运行时注入」搞混把「Gateway 进程」和「CLI 命令」当成一回事。所以这一期的目标很明确用 pnpm 把 OpenClaw 源码在本地跑起来启动 Gateway打通一条最小调试链路并且把模型调用通道统一到 TaoToken 的 Key/API 上。这样后面分析 CLI、Gateway、Session、Tools、Skills、Channel 时你手里有一条真实可复现的链路可以对照而不是对着目录猜职责。适合谁看已经会 Node.js 基础命令、想读 OpenClaw 源码但卡在「跑不起来」这一步的开发者以及想把本地调试环境的模型通道统一管理、不想在多个 provider 之间来回切 Key 的人。我试过在 Node 22 LTS 和 Node 24 上各跑一遍下面给出的步骤在两者上都能走通差异点会单独标注。核心检索词先摆出来OpenClaw 源码解析、开发环境搭建、pnpm 依赖安装、Gateway 启动与调试、TaoToken 统一 Key。这几个词会贯穿全文你按这个顺序操作即可。2. TaoToken 前置把模型通道统一成一个 KeyOpenClaw 的 Gateway 在调试时会频繁发起模型请求如果你每个 provider 配一套 Key改配置、换模型、看日志都会很碎。TaoToken 在这里的作用是提供一个统一的 API 通道你只需要一个 Key就能在调试环境里切换不同模型Gateway 侧的配置也只维护一份。先做两件事。第一注册并拿到 Key入口在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 登录后进控制台创建 API Key控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。第二确认你要用的模型名可以在模型对话页先试一条地址 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 确认通道可用再写进配置。API 基地址统一用 https://taotoken.net/api 注意这个地址不带任何查询参数配置里直接写它就行。Key 的管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 建议给调试环境单独建一个 Key方便后面排查时区分「是 Key 问题还是配置问题」。如果你后面要长期做编码类调试、跑 Agent 任务可以了解下 Coding Plan地址 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合高频调用的场景。接入细节和字段说明看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Claude Code 相关的接入说明在 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。注意调试环境的 Key 不要提交进 Git 仓库。OpenClaw 的设计本身就把个人配置放在仓库外这一点后面会展开。3. 可复制配置pnpm 安装、Gateway 启动与 config.toml / settings.json 骨架3.1 基础环境与源码获取先确认版本。OpenClaw 推荐 Node 24兼容 Node 22 LTS源码构建主要用 pnpm。执行node -v pnpm -v git --version如果 pnpm 没装用 corepack 打开corepack enable corepack prepare pnpmlatest --activate然后克隆仓库并进目录git clone https://github.com/openclaw/openclaw.git cd openclaw进目录后先别急着看代码扫三个文件README.md看项目定位和安装方式package.json看脚本和 workspace 结构openclaw.mjs看 CLI 本地入口。这三个是源码阅读的入口也是你判断「命令到底调了什么」的第一手材料。3.2 安装依赖与初始化pnpm install pnpm openclaw setuppnpm install装的是整个工程的依赖不只是后端服务还包括 CLI、Control UI、Channel 插件、Skills/Tools 模块和构建脚本。pnpm openclaw setup是新鲜 checkout 的一次性初始化负责生成本地配置和 workspace 骨架。初始化后个人配置和工作区落在仓库外~/.openclaw/openclaw.json # 用户配置 ~/.openclaw/workspace # skills / prompts / memories ~/.openclaw/credentials/ # 渠道与认证状态 ~/.openclaw/agents/agentId/sessions/ # 会话记录 /tmp/openclaw/ # 运行日志这个边界要记牢源码仓库放程序代码~/.openclaw放你的东西。更新源码时git pull不会碰你的配置。3.3 config.toml 骨架OpenClaw 的配置以~/.openclaw/openclaw.json为主但很多开发者在调试时会用一份config.toml做本地覆盖方便版本管理和团队共享非敏感字段。下面是一份可直接复制的骨架把模型通道指向 TaoToken# ~/.openclaw/config.toml # 本地调试覆盖配置敏感字段不要写在这里 [gateway] host 127.0.0.1 port 18789 verbose true [model] # 统一走 TaoToken 通道 provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model gpt-4o-mini timeout_ms 60000 [workspace] path ~/.openclaw/workspace [logging] dir /tmp/openclaw level debug关键点base_url写https://taotoken.net/api不要带路径后缀api_key_env指向环境变量避免把 Key 写进文件。模型名按你在模型对话页确认过的填。3.4 settings.json 骨架如果你更习惯 JSON或者项目里已有settings.json约定可以用这份{ gateway: { host: 127.0.0.1, port: 18789, verbose: true }, model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, model: gpt-4o-mini, timeoutMs: 60000 }, workspace: { path: ~/.openclaw/workspace }, logging: { dir: /tmp/openclaw, level: debug } }两份配置字段语义一致选一份维护即可不要同时改两处否则排查时会分不清哪份生效。3.5 设置环境变量并启动 Gatewayexport TAOTOKEN_API_KEY你的Key pnpm gateway:watchgateway:watch会以 watch 模式运行 Gateway源码、配置和 bundled-plugin metadata 变化时自动重载适合调试。如果你已经构建过也可以直接跑打包后的 CLIpnpm build node openclaw.mjs gateway --port 18789 --verbose--port指定端口--verbose输出详细日志。调试阶段建议一直带--verbose你能看到配置加载、模型请求、插件注册的完整过程。如果你改了ui/目录下的前端代码注意gateway:watch不会重建dist/control-ui需要单独执行pnpm ui:build # 或者开发 Control UI 时 pnpm ui:dev4. 验证请求与成功结果Gateway 起来后开另一个终端验证。先看健康状态openclaw health返回正常说明 CLI 和 Gateway 通信通了。然后直接触发一次 Agent 调用不依赖任何外部渠道openclaw agent --message Hello OpenClaw --thinking high这条命令的链路是openclaw agent→openclaw.mjs→ CLI 命令解析 → Gateway / Agent 调用 → 模型请求走 TaoToken 通道→ 返回结果。如果模型配置正确你会看到 Agent 的回复如果 Key 或 base_url 有问题这里会直接报错比在 UI 里点半天更快定位。浏览器侧访问 Control UIhttp://127.0.0.1:18789/页面能打开说明 Gateway 已启动、Control UI 可访问、CLI 和浏览器都能连到本地 Gateway。三处都通最小链路就算跑通了。成功结果长这样终端里openclaw health返回健康状态openclaw agent返回模型回复浏览器打开 18789 端口看到 Control UI 界面。三者缺一就按下一节的排查顺序走。5. 本篇常见错排查5.1 端口不一致导致连不上Gateway WebSocket 默认是ws://127.0.0.1:18789。如果你手动用--port 18790启动但浏览器或 app 还在访问 18789就会连接失败。排查第一步永远是核对端口node openclaw.mjs gateway --port 18789 --verboseapp、CLI、浏览器三者的端口必须一致。改端口时三处一起改别只改一处。5.2 改了 UI 但页面没变化只跑了pnpm gateway:watch改ui/目录不会生效因为它不重建dist/control-ui。解决方式是补一条pnpm ui:build或者开发时用pnpm ui:dev。记住分工后端 Gateway 改动看gateway:watch前端 UI 改动看ui:build/ui:dev。5.3 把个人配置写进源码仓库这是最容易犯的错。把模型配置、渠道 token、prompt、skill 直接写进仓库目录会导致git pull冲突、误提交隐私配置、以及分不清「是源码问题还是配置问题」。正确做法是源码仓库只放程序代码个人配置放~/.openclaw/openclaw.jsonskills 和 prompts 放~/.openclaw/workspace。5.4 不看日志盲目改代码OpenClaw 是多模块系统问题可能来自 CLI、Gateway、模型配置、channel 认证、session 历史、workspace、skills、tools、Control UI 任意一环。出问题时先看三处当前终端输出、/tmp/openclaw/日志、~/.openclaw/openclaw.json配置。比盲目改代码有效得多。5.5 模型请求报错但不知道查哪如果openclaw agent报模型相关错误按这个顺序查环境变量TAOTOKEN_API_KEY是否导出成功echo $TAOTOKEN_API_KEY看有没有值base_url是否写成https://taotoken.net/api且没带多余路径模型名是否在模型对话页确认过可用。Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入字段说明在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照检查即可。6. 从运行流程反推源码阅读重点跑通之后你手里的命令就变成了源码地图pnpm openclaw setup → 配置初始化、workspace 初始化、默认文件生成 pnpm gateway:watch → Gateway 启动、watch 模式、服务监听、热重载 openclaw health → CLI 与 Gateway 通信、健康检查接口 openclaw agent → CLI 命令解析、Agent 调用链路、模型请求流程 http://127.0.0.1:18789/ → Control UI、Gateway Web 服务、前后端交互后续分析 CLI、Gateway、Session、Tools、Skills、Channel 时把代码放回这条链路里理解比孤立看目录高效得多。如果你在接入或排障时卡住优先看 API Keys 和接入文档https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 和 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先验证模型通道是否可用去模型对话页发一条https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。长期做编码和 Agent 调试用 Coding Plan 更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。下一期进入仓库目录结构解析重点看 apps、config、deploy、docs、extensions、packages、security、skills、src、test、ui 各自承担什么职责建立后续源码阅读的目录地图。