用CodeBuddy零代码部署OpenClaw：8102个源文件的AI网关，从架构到运行的完整实录

本文记录了用CodeBuddy AI编程助手在Windows上从零安装OpenClaw的全过程，包含架构分析、关键源码解读和踩坑记录。

---

1. OpenClaw是什么？为什么值得研究

OpenClaw是一个MIT协议的自托管AI网关。它能把你常用的聊天软件——微信、Telegram、Discord、Slack等20多个平台——接到大模型上。你从微信发条消息，它调DeepSeek处理，回复你。

技术上值得关注的点：8102个TypeScript源文件，128个workspace的monorepo，WebSocket网关架构，插件系统支持MCP协议，Agent框架支持多智能体路由和会话隔离。

项目规模让传统安装有一定门槛：需要Node.js 22+、pnpm、编译TypeScript、配置频道和模型。我用CodeBuddy试了全程不动手，只描述意图，以下是从架构到运行的完整过程。

---

2. 架构深度分析

2.1 整体分层

apps/           iOS(643.swift) + Android(151.kt) 移动端
ui/             358.ts React管理面板
──── Gateway ─────────────────────────────────────
src/gateway/    489文件 WebSocket控制平面
src/channels/   20+聊天平台适配器
src/agents/     Pi Agent多智能体框架
src/plugins/    477文件 插件加载/激活/注册
src/plugin-sdk/ 第三方插件SDK
──── Extensions ─────────────────────────────────
extensions/     58个官方插件(5867文件)
  ├── deepseek/        DeepSeek模型适配
  ├── telegram/        Telegram频道
  ├── whatsapp/        WhatsApp频道
  ├── browser/         浏览器自动化
  └── ...

2.2 进程入口: src/entry.ts

// 核心启动序列
if (!isMainModule({ currentFile: fileURLToPath(import.meta.url) })) {
  // 被import时不执行副作用
} else {
  process.title = "openclaw";
  installProcessWarningFilter();
  normalizeEnv();
  enableOpenClawCompileCache({ installRoot });

  if (!ensureCliRespawnReady()) {
    // 解析 --profile, --container 参数
    const parsed = parseCliProfileArgs(parsedContainer.argv);
    // 应用profile环境变量
    // 最终进入CLI路由
    await runMainOrRootHelp(process.argv);
  }
}

async function runMainOrRootHelp(argv: string[]) {
  if (await tryHandleRootHelpFastPath(argv)) return;
  const { runCli } = await import("./cli/run-main.js");
  await runCli(argv);
}

关键设计：entry.ts不包含任何业务逻辑，只是做环境标准化、编译缓存、参数解析，然后把控制权交给runCli。

2.3 WebSocket网关: src/gateway/

网关是整个系统的控制平面，基于WebSocket协议。启动时做的事情：

1. 加载配置 — 读取~/.openclaw/openclaw.json
2. 初始化频道 — 遍历extensions目录，加载已启用的频道插件
3. 激活插件 — 通过src/plugins/的loader系统，按manifest加载
4. 启动HTTP/WS服务器 — 绑定端口18789
5. BOOT.md机制 — 检查工作区是否有BOOT.md，有则作为初始prompt发给agent

// src/gateway/boot.ts — BOOT.md被执行时的prompt构建
function buildBootPrompt(content: string) {
  return [
    "You are running a boot check. Follow BOOT.md instructions exactly.",
    "BOOT.md:", content,
    "If BOOT.md asks you to send a message, use the message tool.",
    "If nothing needs attention, reply with ONLY: SILENT_REPLY_TOKEN.",
  ].join("\n");
}

2.4 Agent系统: src/agents/

OpenClaw内置Pi Agent，支持多agent路由。核心流程：

用户消息 → channel → agent router → agent session
                                        ↓
                               model provider (DeepSeek)
                                        ↓
                               tool execution → 回复

Agent system可以通过agentCommand() API被调用，支持thinking level控制、tool use、session管理。

2.5 频道系统: src/channels/

频道使用统一的消息生命周期模型：

inbound → normalize → route to agent → format → outbound

支持20+频道，每个频道是一个独立的adapter，核心统一处理消息的接收、格式化、发送。插件SDK通过src/plugin-sdk/提供标准接口给第三方频道开发者。

2.6 插件系统: src/plugins/ (477文件)

插件加载链路：

// 简化版——插件的发现→激活→注册流程
1. scan extensions/ directory
2. read manifest (openclaw.plugin.json)
3. validate dependencies & compatibility
4. load plugin code (dynamic import)
5. call lifecycle hooks (setup, activate)
6. register channels, tools, providers

---

3. 安装实录（CodeBuddy操作）

Step 1: 克隆仓库

我输入：

下载 https://github.com/openclaw/openclaw 到本地

CodeBuddy执行git clone。第一次GitHub超时，它自动切到codeload下载方式重试，并处理了Windows GBK编码问题。

Step 2: 安装依赖

安装项目依赖

执行pnpm install --no-frozen-lockfile。4分18秒，1232个包。

中途baileys包报EPERM: operation not permitted——Windows文件锁问题。CodeBuddy自己识别出原因，Remove-Item node_modules删除后重装，第二次成功。

Step 3: 编译

编译项目

pnpm build调用了scripts/build-all.mjs：

• 第一步：plugins:assets:build — 打包插件静态资源
• 第二步：tsdown — 编译8102个TS文件

核心编译通过，dist/entry.js和dist/index.js生成。最后一步write-cli-startup-metadata（生成浏览器帮助文本）因子进程超时失败——不影响核心功能。

# 验证编译结果
Test-Path dist/entry.js  # True
Test-Path dist/index.js  # True

Step 4: 配置API Key

初始化配置，deepseek api-key: sk-xxx

创建~/.openclaw/openclaw.json，需要的最小配置：

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "loopback"
  },
  "providers": {
    "deepseek": {
      "apiKey": "sk-xxx"
    }
  }
}

Step 5: 启动

node openclaw.mjs gateway --port 18789 --bind loopback

Web管理面板在http://127.0.0.1:18789/。

---

4. 与传统方式对比

维度	手动安装	CodeBuddy安装
前置知识	npm/pnpm/monorepo	无
耗时	30-60分钟	~15分钟
报错处理	Google→SO→试→再报错	AI读日志自修复
交互方式	逐条敲命令	描述意图

最关键的区别不在省时间，在于"排查报错"这个最消耗认知的环节被外包了。EPERM文件锁、子进程超时、GBK编码——这些在传统安装中每一个都够你Google半小时。

---

5. 下一步：接入频道

安装完成后，通过ClawHub安装频道插件：

node openclaw.mjs plugins install telegram
node openclaw.mjs plugins install wechat

每个频道需要单独配置API凭证（在~/.openclaw/credentials/下），配好后gateway会自动连接。

---

项目地址：github.com/openclaw/openclaw