OpenClaw源码解读系列:CLI 框架与进程模型

process.title = "openclaw";installProcessWarningFilter();normalizeEnv();if (process.argv.includes("--no-color")) {  process.env.NO_COLOR = "1";  process.env.FORCE_COLOR = "0";}

functionensureExperimentalWarningSuppressed(): boolean{  if (isTruthyEnvValue(process.env.OPENCLAW_NO_RESPAWN)) {    return false;  }  if (isTruthyEnvValue(process.env.OPENCLAW_NODE_OPTIONS_READY)) {    return false;  }  if (hasExperimentalWarningSuppressed()) {    return false;  }  // Respawn guard (and keep recursion bounded if something goes wrong).  process.env.OPENCLAW_NODE_OPTIONS_READY = "1";  // Pass flag as a Node CLI option, not via NODE_OPTIONS  const child = spawn(    process.execPath,    [EXPERIMENTAL_WARNING_FLAG, ...process.execArgv, ...process.argv.slice(1)],    {      stdio: "inherit",      env: process.env,    },  );  attachChildProcessBridge(child);  // ... exit/error handling ...  return true;}

if (!ensureExperimentalWarningSuppressed()) {  const parsed = parseCliProfileArgs(process.argv);  if (!parsed.ok) {    console.error(`[openclaw] ${parsed.error}`);    process.exit(2);  }  if (parsed.profile) {    applyCliProfileEnv({ profile: parsed.profile });    process.argv = parsed.argv;  }  import("./cli/run-main.js")    .then(({ runCli }) => runCli(process.argv))    .catch((error) => {      console.error(        "[openclaw] Failed to start CLI:",        error instanceof Error ? (error.stack ?? error.message) : error,      );      process.exitCode = 1;    });}

export async function runCli(argv: string[] = process.argv) {  const normalizedArgv = stripWindowsNodeExec(argv);  loadDotEnv({ quiet: true });  normalizeEnv();  ensureOpenClawCliOnPath();  assertSupportedRuntime();  if (await tryRouteCli(normalizedArgv)) {    return;  }  enableConsoleCapture();  const { buildProgram } = await import("./program.js");  const program = buildProgram();  installUnhandledRejectionHandler();  // ... uncaughtException handler ...  const parseArgv = rewriteUpdateFlagArgv(normalizedArgv);  const primary = getPrimaryCommand(parseArgv);  if (primary) {    const { registerSubCliByName } = await import("./program/register.subclis.js");    await registerSubCliByName(program, primary);  }  const shouldSkipPluginRegistration = !primary && hasHelpOrVersion(parseArgv);  if (!shouldSkipPluginRegistration) {    const { registerPluginCliCommands } = await import("../plugins/cli.js");    const { loadConfig } = await import("../config/config.js");    registerPluginCliCommands(program, loadConfig());  }  await program.parseAsync(parseArgv);}

export async function tryRouteCli(argv: string[]): Promise<boolean> {  if (isTruthyEnvValue(process.env.OPENCLAW_DISABLE_ROUTE_FIRST)) {    return false;  }  if (hasHelpOrVersion(argv)) {    return false;  }  const path = getCommandPath(argv, 2);  if (!path[0]) {    return false;  }  const route = findRoutedCommand(path);  if (!route) {    return false;  }  await prepareRoutedCommand({ argv, commandPath: path, loadPlugins: route.loadPlugins });  return route.run(argv);}

export function buildProgram() {  const program = new Command();  const ctx = createProgramContext();  const argv = process.argv;  configureProgramHelp(program, ctx);  registerPreActionHooks(program, ctx.programVersion);  registerProgramCommands(program, ctx, argv);  return program;}

export function registerPreActionHooks(program: Command, programVersion: string) {  program.hook("preAction", async (_thisCommand, actionCommand) => {    setProcessTitleForCommand(actionCommand);    const argv = process.argv;    if (hasHelpOrVersion(argv)) {      return;    }    // ... banner, verbose ...    await ensureConfigReady({ runtime: defaultRuntime, commandPath });    if (PLUGIN_REQUIRED_COMMANDS.has(commandPath[0])) {      ensurePluginRegistryLoaded();    }  });}

  const primary = getPrimaryCommand(parseArgv);  if (primary) {    const { registerSubCliByName } = await import("./program/register.subclis.js");    await registerSubCliByName(program, primary);  }

export async function registerSubCliByName(program: Command, name: string): Promise<boolean> {  const entry = entries.find((candidate) => candidate.name === name);  if (!entry) {    return false;  }  const existing = program.commands.find((cmd) => cmd.name() === entry.name);  if (existing) {    removeCommand(program, existing);  }  await entry.register(program);  return true;}

  {    name: "gateway",    description: "Gateway control",    register: async (program) => {      const mod = await import("../gateway-cli.js");      mod.registerGatewayCli(program);    },  },

function registerLazyCommand(program: Command, entry: SubCliEntry) {  const placeholder = program.command(entry.name).description(entry.description);  placeholder.allowUnknownOption(true);  placeholder.allowExcessArguments(true);  placeholder.action(async (...actionArgs) => {    removeCommand(program, placeholder);    await entry.register(program);    // ... 重建 argv ...    const parseArgv = buildParseArgv({      programName: program.name(),      rawArgs,      fallbackArgv,    });    await program.parseAsync(parseArgv);  });}

export function registerSubCliCommands(program: Command, argv: string[] = process.argv) {  if (shouldEagerRegisterSubcommands(argv)) {    for (const entry of entries) {      void entry.register(program);    }    return;  }  const primary = getPrimaryCommand(argv);  if (primary && shouldRegisterPrimaryOnly(argv)) {    const entry = entries.find((candidate) => candidate.name === primary);    if (entry) {      registerLazyCommand(program, entry);      return;    }  }  for (const candidate of entries) {    registerLazyCommand(program, candidate);  }}

export type CliDeps = {  sendMessageWhatsApp: typeof sendMessageWhatsApp;  sendMessageTelegram: typeof sendMessageTelegram;  sendMessageDiscord: typeof sendMessageDiscord;  sendMessageSlack: typeof sendMessageSlack;  sendMessageSignal: typeof sendMessageSignal;  sendMessageIMessage: typeof sendMessageIMessage;};export function createDefaultDeps(): CliDeps {  return {    sendMessageWhatsApp,    sendMessageTelegram,    sendMessageDiscord,    sendMessageSlack,    sendMessageSignal,    sendMessageIMessage,  };}

用户输入: openclaw gateway run --port 18789    │    ▼[openclaw.mjs] → import("dist/entry.js")    │    ▼[entry.ts] 第 10-12 行: process.title / warningFilter / normalizeEnv    │    ▼[entry.ts] 第 148 行: ensureExperimentalWarningSuppressed()    │                        │    │        (需要 respawn)   ├──→ spawn(node, [--disable-warning, ...args])    │                        │       └→ 子进程重新执行 entry.ts    │                        │          └→ 这次 OPENCLAW_NODE_OPTIONS_READY=1，不 respawn    │   (不需要 respawn)     │    ▼                        ▼[entry.ts] 第 149 行: parseCliProfileArgs → 无 profile    │    ▼[entry.ts] 第 162 行: import("./cli/run-main.js") → runCli(argv)    │    ▼[run-main.ts] 第 29-34 行: dotenv / normalizeEnv / assertRuntime    │    ▼[run-main.ts] 第 36 行: tryRouteCli(argv)    │   path = ["gateway", "run"] → findRoutedCommand → 没有匹配 → 返回 false    │    ▼[run-main.ts] 第 43-44 行: import("./program.js") → buildProgram()    │   ├─ createProgramContext() → { version, channelOptions }    │   ├─ registerPreActionHooks() → 注册 preAction 钩子    │   └─ registerProgramCommands() → 遍历 commandRegistry，    │       其中 subclis 组调用 registerSubCliCommands()    │       → getPrimaryCommand = "gateway"    │       → registerLazyCommand(program, gatewayEntry) ← 只注册 gateway 占位符    │    ▼[run-main.ts] 第 57-60 行: primary = "gateway"    │   → registerSubCliByName(program, "gateway")    │   → 移除占位符 → import("gateway-cli.js") → registerGatewayCli(program)    │     → 注册完整的 gateway 子命令树 (run, status, probe, discover...)    │    ▼[run-main.ts] 第 64-68 行: registerPluginCliCommands(program, loadConfig())    │   → 把插件提供的 CLI 命令挂到 program    │    ▼[run-main.ts] 第 71 行: program.parseAsync(argv)    │   → Commander 匹配 "gateway run --port 18789"    │   → 触发 preAction 钩子:    │       ├─ process.title = "openclaw-gateway"    │       ├─ emitCliBanner("2026.2.13")    │       ├─ ensureConfigReady() → 校验配置    │       └─ (不在 PLUGIN_REQUIRED_COMMANDS 里，跳过插件加载)    │   → 执行 gateway run 的 action    │       → startGatewayServer(18789)