企业官网建设流程全解析

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 前置：把模型通道统一成一个 Key

OpenClaw 的 Gateway 在调试时会频繁发起模型请求，如果你每个 provider 配一套 Key，改配置、换模型、看日志都会很碎。TaoToken 在这里的作用是提供一个统一的 API 通道：你只需要一个 Key，就能在调试环境里切换不同模型，Gateway 侧的配置也只维护一份。

先做两件事。第一，注册并拿到 Key，入口在官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，登录后进控制台创建 API Key，控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。第二，确认你要用的模型名，可以在模型对话页先试一条，地址 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，确认通道可用再写进配置。

API 基地址统一用 https://taotoken.net/api ，注意这个地址不带任何查询参数，配置里直接写它就行。Key 的管理页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，建议给调试环境单独建一个 Key，方便后面排查时区分「是 Key 问题还是配置问题」。

如果你后面要长期做编码类调试、跑 Agent 任务，可以了解下 Coding Plan，地址 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合高频调用的场景。接入细节和字段说明看文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，Claude Code 相关的接入说明在 https://taotoken.net/claude-code?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite 。

注意：调试环境的 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 pnpm@latest --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 setup

pnpm 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 设置环境变量并启动 Gateway

export TAOTOKEN_API_KEY="你的Key" pnpm gateway:watch

gateway:watch会以 watch 模式运行 Gateway，源码、配置和 bundled-plugin metadata 变化时自动重载，适合调试。如果你已经构建过，也可以直接跑打包后的 CLI：

pnpm build node openclaw.mjs gateway --port 18789 --verbose

--port指定端口，--verbose输出详细日志。调试阶段建议一直带--verbose，你能看到配置加载、模型请求、插件注册的完整过程。

如果你改了ui/目录下的前端代码，注意gateway:watch不会重建dist/control-ui，需要单独执行：

pnpm ui:build # 或者开发 Control UI 时 pnpm ui:dev

4. 验证请求与成功结果

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 UI：

http://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 --verbose

app、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.json，skills 和 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_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，接入字段说明在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，对照检查即可。

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_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 和 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。想先验证模型通道是否可用，去模型对话页发一条：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。长期做编码和 Agent 调试，用 Coding Plan 更省心：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。

下一期进入仓库目录结构解析，重点看 apps、config、deploy、docs、extensions、packages、security、skills、src、test、ui 各自承担什么职责，建立后续源码阅读的目录地图。