第 9 章 启动流程：从 openclaw onboard 到守护进程跑起来

上一章我们从内部架构的角度理解了 Gateway 的骨架。本章换一个角度：从用户在终端敲下第一个命令开始，逐步跟踪 OpenClaw 是怎么一步步「活起来」的。

9.1 CLI 命令体系：openclaw 的全貌

openclaw 是一个多命令的 CLI，主要子命令如下：

命令	作用
openclaw onboard	交互式引导向导，完成初次配置和守护进程安装
openclaw gateway	启动 Gateway 进程（默认前台运行）
openclaw agent	通过 CLI 直接向 Gateway 发起 Agent 请求
openclaw message send	通过 Gateway 向某个聊天账号发送一条消息
openclaw pairing approve	批准某个未知发送者的配对请求
openclaw doctor	自检：检查配置、通道状态、服务健康
openclaw update	升级 OpenClaw 到最新版本
openclaw logs	查看 Gateway 的实时日志流

9.1.1 CLI 与 Gateway 的关系

在第 2 章我们已经提过：CLI 是一个薄薄的「前端」，绝大多数命令最终都转化为对 Gateway API 的调用。

唯一的例外是 openclaw onboard 可以在 Gateway 未启动时单独运行（需要完成配置文件的初始化），以及 openclaw gateway 本身就是启动 Gateway 的命令，不依赖 Gateway 已经在运行。

这意味着整个 CLI 代码库非常轻量。它只负责解析命令行参数、读取本地配置（主要是 Gateway 的地址和认证 token）、把操作意图通过 HTTP 或 WebSocket 转发给 Gateway、最后格式化并展示 Gateway 返回的结果。

9.1.2 CLI 入口代码逻辑（伪代码）

// openclaw.mjs 入口

import { parseArgs } from "./src/cli/args";
import { loadLocalConfig } from "./src/config";

async function main() {
  const args = parseArgs(process.argv.slice(2));
  const localConfig = await loadLocalConfig();

  // 非 gateway 类命令，都先连接到已运行的 Gateway
  if (args.command !== "gateway" && args.command !== "onboard") {
    const gw = getGatewayClient({
      url: localConfig.gateway.url,
      token: localConfig.gateway.authToken,
    });

    await gw.connect();
    await executeCommand(args, gw);
    await gw.disconnect();
    return;
  }

  // gateway 命令：在本进程内直接启动 Gateway
  if (args.command === "gateway") {
    const config = await loadFullConfig(args.options);
    await startGateway(config);
    return;
  }

  // onboard 命令：交互式向导
  if (args.command === "onboard") {
    await runOnboarding(args.options);
    return;
  }
}

main().catch((err) => {
  console.error(err.message);
  process.exit(1);
});

9.2 配置加载：从文件到内存，完整经过哪些步骤

9.2.1 配置文件的查找顺序

Gateway 在加载配置时，会按优先级依次合并以下来源：

1. 代码内的默认值（最低优先级）
2. ~/.openclaw/openclaw.json（用户级，最常用）
3. 环境变量（OPENCLAW_GATEWAY_PORT, ANTHROPIC_API_KEY, ...）
4. CLI 参数（最高优先级，只影响当次运行）

9.2.2 配置验证

配置加载后，会通过 schema 校验（通常使用 zod 或类似库）：

import { z } from "zod";

const GatewayConfigSchema = z.object({
  port: z.number().min(1024).max(65535).default(18789),
  host: z.string().default("127.0.0.1"),
  auth: z.object({
    token: z.string().optional(),
  }).optional(),
});

const OpenClawConfigSchema = z.object({
  gateway: GatewayConfigSchema,
  models: z.array(ModelConfigSchema).min(1),
  channels: ChannelsConfigSchema,
  agents: z.array(AgentConfigSchema),
  skills: SkillsConfigSchema,
  security: SecurityConfigSchema,
});

const config = OpenClawConfigSchema.parse(rawConfig);

如果验证失败（例如忘记设置 API Key、端口超出范围），Gateway 会在启动阶段就退出，并打印清晰的错误信息，而不是运行一段时间后才莫名崩溃。

9.2.3 敏感信息的处理

API Key、OAuth Token 等敏感信息通常不直接写进配置文件，而是通过环境变量引用。在配置文件中，可以用占位符写法（例如 "$ANTHROPIC_API_KEY"），加载时由配置模块替换。这样既方便管理，也避免把密钥提交到版本控制。

9.3 守护进程安装：launchd 与 systemd

9.3.1 为什么需要守护进程

如果只是前台运行 openclaw gateway，关掉终端 Gateway 就消失了——你的 Slack/Discord 就断线了，所有 Cron 任务也不会触发。

守护进程解决的是「让 Gateway 在你不用终端时也在后台持续运行」的问题，类似于 macOS 上 launchd 管理的系统服务，或 Linux 上 systemd 管理的用户服务。

9.3.2 macOS：launchd plist 安装

在 macOS 上，openclaw onboard --install-daemon 会生成并安装一个 launchd plist 文件：

<!-- ~/Library/LaunchAgents/ai.openclaw.gateway.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "...">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>ai.openclaw.gateway</string>

  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/openclaw</string>
    <string>gateway</string>
  </array>

  <key>RunAtLoad</key>
  <true/>

  <key>KeepAlive</key>
  <true/>

  <key>StandardOutPath</key>
  <string>/tmp/openclaw-gateway.log</string>

  <key>StandardErrorPath</key>
  <string>/tmp/openclaw-gateway-error.log</string>
</dict>
</plist>

安装后运行 launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist，Gateway 就会在用户登录时自动启动，崩溃后自动重启（KeepAlive: true）。

9.3.3 Linux：systemd user service

在 Linux 上，通常安装的是 user-level systemd 服务（不需要 root 权限）：

# ~/.config/systemd/user/openclaw-gateway.service

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/openclaw gateway
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

安装并启用：

systemctl --user enable openclaw-gateway
systemctl --user start openclaw-gateway

9.3.4 守护进程的管理

安装完成后，几个常用的管理操作：

# 查看状态
openclaw gateway status

# 重启（更新配置后）
openclaw gateway restart

# 查看日志
openclaw logs

# 停止
openclaw gateway stop

9.4 openclaw doctor：自检机制与故障提示

doctor 是一个「一键诊断」命令，会系统地检查 OpenClaw 的健康状态。

9.4.1 检查项

[✓] Node.js version >= 22
[✓] openclaw version: 2026.2.28
[✓] Gateway is running (port 18789)
[✓] Config file found: ~/.openclaw/openclaw.json
[✓] Config schema valid

Models:
[✓] Anthropic (claude-opus-4-6): connected, usage 43%
[!] OpenAI (gpt-4o): API key not set (optional)

Channels:
[✓] Slack: connected (@mybot)
[!] Discord: disconnected (token expired - run 'openclaw channel discord auth')
[✓] iMessage: connected

Security:
[!] Slack DM policy is 'open' - consider switching to 'pairing'
[✓] No unknown approved peers found

Skills:
[✓] weather (v1.2): enabled
[✓] github (v0.9): enabled, token valid
[!] himalaya (v0.5): enabled, no config found (run 'openclaw skill configure himalaya')

Sessions:
[✓] Active sessions: 3
[✓] Pending tasks: 0

9.4.2 常见问题与 doctor 的提示

doctor 不仅检查，还会给出具体的修复建议。通道断线时提示你运行对应的 openclaw channel <name> auth 重新授权；发现高风险 DM 策略时警告 open 配置，建议切换为 pairing；Skill 缺少配置时提示运行 openclaw skill configure <name> 完成配置；检测到旧版本时提示运行 openclaw update 升级。

doctor 应该成为你在遇到奇怪问题时的第一个排查命令。

9.5 源码走读导向：入口文件与主流程

在阅读源码时，启动流程的关键路径大致如下。

openclaw.mjs 是 npm 包入口，负责解析参数、分发到对应子命令处理器，代码非常轻量。

src/cli/ 目录下每个子命令（gateway.ts、onboard.ts、doctor.ts 等）各一个文件，每个文件只做参数验证、调用 Gateway SDK 或本地操作、格式化输出这几件事。

src/gateway/ 是 Gateway 主目录，包含 server.ts、boot.ts 等多个文件。真正的 startGateway 函数一般在 boot.ts 或 server.ts 中，按照上一章介绍的顺序依次初始化所有子系统。这里是整个 Gateway「站起来」的地方。

src/config/ 包含配置文件的查找、合并、schema 验证逻辑，值得关注的是如何处理多层配置合并以及如何在运行时支持热更新。

守护进程安装逻辑在 src/cli/onboard.ts 或 src/cli/daemon.ts 中，会生成 plist 或 systemd service 文件并调用系统命令安装和启用。这部分逻辑通常比较简单：生成一个文本文件加调用系统命令。

9.6 小结

本章追踪了 OpenClaw 的启动全流程。CLI 作为轻量前端把命令分发给 Gateway 或在本地处理，配置系统按优先级合并多层配置并在启动时做 schema 验证，守护进程（launchd/systemd）让 Gateway 在后台常驻并自动重启，openclaw doctor 是第一道故障诊断工具，从配置、通道、技能到安全策略做全面检查。

接下来我们进入本书技术密度最高的章节之一：第 10 章「一条消息的生命旅程」，把上面这些模块串成一条完整的调用链，用近源码的方式走一遍全程。