在上一篇文章中，我详细分析了 OpenClaw 如何接入模型，包括：

• Custom Provider 接入机制

• models.json 自动生成逻辑

• API Adapter（openai-completions 等）

那么我们回到最开始：

OpenClaw 到底是怎么启动的？

CLI 是怎么接管整个系统运行的？

于是我决定写这篇 源码级启动链路分析。

这篇文章将从 Node CLI 启动入口 出发，一步步追踪 OpenClaw 的启动流程，直到 CLI 命令真正被执行。

一、OpenClaw 启动架构总览

我们先看一张整体架构图

openclaw CLI
    │
    ▼
openclaw.mjs
    │
    ▼
src/entry.ts
    │
    ▼
src/cli/run-main.ts
    │
    ▼
buildProgram()
    │
    ▼
command registry
    │
    ▼
sub command dispatch
    │
 ┌───┴───────────┐
 │               │
gateway run    agent
 │               │
 ▼               ▼
Gateway Server   Agent Runtime

可以看到 OpenClaw 的启动分为几个阶段：

1️⃣ CLI 包装层

2️⃣ TypeScript 启动入口

3️⃣ CLI Runtime 初始化

4️⃣ Command Tree 构建

5️⃣ 子命令分发

理解这条链路，就等于理解了 OpenClaw 的启动机制。

二、Node CLI 入口：openclaw.mjs

OpenClaw CLI 的入口是：

openclaw.mjs

这个文件是 Node CLI 的包装层。

典型结构如下：

#!/usr/bin/env node

import('./dist/entry.js')

它的职责其实很简单：

• 作为 npm 发布的 CLI 入口

• 进入编译后的 dist 目录

• 启动真正的程序

为什么要这样设计？

因为 OpenClaw 使用 TypeScript 开发，发布时必须运行编译后的代码。

所以启动链第一步是：

openclaw.mjs
    ↓
dist/entry.js

三、源码级入口：src/entry.ts

接下来进入真正的源码入口：

src/entry.ts

这个文件是 OpenClaw 的 启动引导器（bootstrapper）。

核心逻辑非常简单：

import { runCli } from "./cli/run-main.js"

runCli()

这里还会做一些启动阶段的处理，例如：

• 设置 process.title

• 规范化环境变量

• 处理 --help / --version 快速路径

但真正的 CLI 初始化，是在 runCli() 中完成的。

四、CLI Runtime 初始化：run-main.ts

OpenClaw CLI 初始化的核心文件是：

src/cli/run-main.ts

这里负责：

• 解析 CLI 参数

• 加载环境变量

• 初始化 CLI Runtime

• 构建命令树

核心流程如下：

runCli(argv)
   │
   ├── normalize argv
   ├── apply CLI profile
   ├── load dotenv
   ├── normalize env
   ├── runtime compatibility check
   └── build CLI program

五、buildProgram()：命令树构建

OpenClaw 使用的是 Commander.js 作为 CLI 框架。

命令树是在这里构建的：

src/cli/program/build-program.ts

典型代码结构：

const program = new Command()

registerProgramCommands(program)

return program

六、CLI 命令注册机制

命令注册在这里：

src/cli/program/register.subclis.ts

OpenClaw 的 CLI 结构如下：

openclaw
├ gateway
├ agent
├ models
├ config
├ status
├ channels
└ plugins

也就是

CLI Framework
    ↓
command registry
    ↓
subcommand dispatch

七、命令分发：sub CLI 执行

当用户执行命令：

openclaw gateway run

CLI 会分发到：

src/cli/gateway-cli/run.ts

执行流程如下：

gateway CLI
   ↓
runGatewayLoop()
   ↓
startGatewayServer()

最终进入：

src/gateway/server.impl.ts

也就是说：

CLI
  ↓
Gateway CLI
  ↓
Gateway Server

八、Gateway Server 启动

Gateway 是 OpenClaw 的 核心控制层。

启动逻辑位于：

src/gateway/server.impl.ts

Gateway Server 负责：

• RPC 方法注册

• Agent 请求处理

• Session 管理

• Streaming 事件

• Channel 集成

Gateway 的 RPC 方法定义在：

src/gateway/server-methods.ts

其中最核心的是：

server-methods/agent.ts

九、配置加载：openclaw.json

很多人关心：

OpenClaw 的配置什么时候加载？

配置文件：

~/.openclaw/openclaw.json

源码位置：

src/config/load-config.ts

配置加载流程：

loadConfig()
   ↓
load user config
   ↓
merge defaults
   ↓
validate schema

Schema 使用：

zod

定义在：

src/config/zod-schema.core.ts

十、models.json 自动生成机制

模型 catalog 文件：

models.json

生成逻辑在：

src/agents/models-config.ts

核心函数：

ensureOpenClawModelsJson()

作用：

• 根据配置生成模型 catalog

• 合并 provider models

• 供 runtime discovery 使用

十一、OpenClaw 启动链路总结

完整启动链如下：

openclaw.mjs
   ↓
dist/entry.js
   ↓
src/entry.ts
   ↓
src/cli/run-main.ts
   ↓
buildProgram()
   ↓
register commands
   ↓
CLI command dispatch
   ↓
gateway / agent / models

十二、总结

从源码角度看，OpenClaw 的启动架构可以分为四层：

CLI Wrapper Layer
openclaw.mjs

Source Bootstrap Layer
src/entry.ts

CLI Runtime Layer
src/cli/run-main.ts

Command Dispatch Layer
buildProgram() + command registry

这套设计使得 OpenClaw：

• CLI 层保持轻量

• Runtime 与 CLI 解耦

• Gateway 统一控制 Agent 执行

换句话说：

OpenClaw 并不是一个简单的命令行工具，而是一个由 CLI 启动的 Agent Runtime 平台。

下一篇预告

在下一篇文章中，我会继续深入分析：

OpenClaw Agent Runtime 主执行链

包括：

• agent.ts

• runEmbeddedAttempt

• tool system

• prompt system

• streaming event

把 一次 Agent Run 的完整执行路径全部打通。