openclaw-zero-token/ARCHITECTURE.md

OpenClaw / openclaw-zero-token CLI 架构流程

本文档描述本仓库中 命令行入口 到 子命令执行 的主路径，便于对照源码（openclaw.mjs、entry.ts、cli/）。与上游 OpenClaw 大架构说明见根目录 ARCHITECTURE.md。

图表说明

• 实线：主流程；虚线：按需加载（懒注册子命令）或异步分支。
• 退出码：0 成功；1 一般错误（校验失败、运行失败）；2 根级参数解析错误（如 --container / --profile 组合非法）；Node 版本过低时 openclaw.mjs 直接 exit(1)。
• Zero Token：onboard / configure 等流程可触发 src/zero-token/providers/* 与 Playwright/CDP，向各厂商 网页 API 发起请求；凭证落盘于状态目录下的 auth.json 等（勿提交版本库）。

flowchart TD
  subgraph Entry["入口"]
    A["openclaw.mjs<br/>校验 Node >= 22.12"] --> B{"dist/entry.(m)js 存在?"}
    B -->|否| E1["报错: missing dist/entry<br/>exit 1"]
    B -->|是| C["entry.js: normalize argv<br/>可选 respawn 子进程"]
  end

  C --> D{"容器模式<br/>--container?"}
  D -->|解析失败| X2["stderr 提示<br/>exit 2"]
  D -->|是| DC["Podman/Docker 内<br/>再执行 CLI"]
  D -->|否| P{"--profile / --dev?"}
  P -->|解析失败| X2
  P -->|是| PE["写入 profile 隔离<br/>STATE/CONFIG 环境变量"]
  P -->|否| V{"仅 --version / -V / -v ?"}
  V -->|是| VF["输出版本 + 可选 commit<br/>exit 0"]
  V -->|否| H{"仅 --help / -h ?"}
  H -->|是| HF["outputRootHelp<br/>exit 0"]
  H -->|否| R["runCli: Commander 程序"]

  subgraph Run["runCli / Commander"]
    R --> PL["插件发现与注册<br/>（extensions / plugins.allow）"]
    PL --> REG["registerProgramCommands<br/>核心命令占位 + 懒加载"]
    REG --> DISPATCH{"匹配子命令"}
  end

  DISPATCH -->|onboard / configure / setup| WZ["向导 + 配置写入<br/>openclaw.json / auth"]
  DISPATCH -->|gateway / daemon| GW["网关进程 / RPC<br/>WebSocket + HTTP"]
  DISPATCH -->|agent / tui| AG["经 Gateway 或 TUI<br/>调用模型与工具"]
  DISPATCH -->|models / channels / ...| SUB["各 cli/* 模块<br/>读配置 / 调服务"]
  DISPATCH -->|doctor| DOC["健康检查与修复建议<br/>可 exit 0 但含告警"]
  DISPATCH -->|未知或参数错误| ERR["Commander 错误信息<br/>通常 exit 1"]

  WZ --> BROWSER["Playwright / Chrome CDP<br/>（Zero Token 网页登录）"]
  WZ --> FS1["文件 I/O: 配置与 auth 存储"]
  GW --> NET["本机端口 / 对外 HTTP"]
  AG --> NET
  AG --> API["Provider: 网页 API 或<br/>OpenAI 兼容 / 本地 Ollama 等"]
  SUB --> FS2["读写配置与状态目录"]
  SUB --> NET

  style E1 fill:#f99
  style X2 fill:#f99
  style ERR fill:#f99
  style VF fill:#9f9
  style HF fill:#9f9

与源码的对应关系

阶段	主要文件
引导包装	openclaw.mjs
进程入口、版本/帮助快路径	entry.ts
CLI 主循环	cli/run-main.ts → cli/program/*
核心子命令注册	cli/program/command-registry.ts
扩展子命令	cli/program/register.subclis.ts、cli/program/subcli-descriptors.ts
Zero Token 网页侧	src/zero-token/providers/、src/zero-token/streams/