29.1 本地部署

生成模型：Claude Opus 4.6 (anthropic/claude-opus-4-6) Token 消耗：输入 ~195k tokens，输出 ~5k tokens（本节）

---

本地部署是 OpenClaw 最常见的使用方式——在个人电脑上运行 Gateway，通过控制台 UI 或原生客户端与之交互。

29.1.1 npm 全局安装

最简单的安装方式是通过 npm 全局安装：

npm install -g openclaw

安装完成后，可以直接运行：

openclaw gateway          # 启动 Gateway 服务器
openclaw chat             # 启动 CLI 聊天
openclaw doctor           # 运行健康检查

OpenClaw 的 npm 包包含预构建的 TypeScript 编译产物（dist/）和控制台 UI 资源（dist/control-ui/），不需要用户自行编译。

对于开发者，也可以通过源码安装：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
node openclaw.mjs gateway

29.1.2 守护进程管理（launchd / systemd）

在生产场景中，Gateway 应该作为守护进程运行，确保系统重启后自动启动。

macOS — launchd

macOS 使用 launchd 管理守护进程。OpenClaw 的 macOS 应用（OpenClaw.app）内置了 Launch Agent 管理器 GatewayLaunchAgentManager，它会自动创建一个 plist 文件：

<!-- ~/Library/LaunchAgents/ai.openclaw.gateway.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.openclaw.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>/usr/local/lib/node_modules/openclaw/openclaw.mjs</string>
        <string>gateway</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

衍生解释 — launchd

launchd 是 macOS 的进程管理系统，取代了传统 Unix 的 init/cron。它通过 XML 格式的 plist 配置文件来定义服务。RunAtLoad 表示系统启动时自动运行，KeepAlive 表示进程崩溃后自动重启。Launch Agents（~/Library/LaunchAgents/）以当前用户身份运行，Launch Daemons（/Library/LaunchDaemons/）以 root 身份运行。

Linux — systemd

Linux 系统使用 systemd 管理服务：

# /etc/systemd/system/openclaw-gateway.service
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=openclaw
Environment=NODE_ENV=production
ExecStart=/usr/bin/node /usr/local/lib/node_modules/openclaw/openclaw.mjs gateway
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable openclaw-gateway
sudo systemctl start openclaw-gateway

衍生解释 — systemd

systemd 是现代 Linux 发行版（Ubuntu、Debian、Fedora 等）的初始化系统和服务管理器。它使用 .service 文件定义服务，支持依赖管理（After=）、自动重启（Restart=always）、资源限制（LimitNOFILE=）等功能。systemctl enable 设置开机自启，systemctl start 立即启动。

29.1.3 openclaw doctor 健康检查

openclaw doctor 是一个内置的诊断命令，检查运行环境的完整性：

$ openclaw doctor
✔ Node.js v22.11.0 (>= 18 required)
✔ Configuration file exists (~/.openclaw/openclaw.json)
✔ Configuration is valid JSON
✔ API key configured (anthropic)
✔ Gateway port 18789 available
✔ UI assets present (dist/control-ui/)
✔ exec sandbox available
⚠ Tailscale not detected (optional)

doctor 命令注册在 CLI 的 maintenance 子命令组中：

// src/cli/program/register.maintenance.ts
program
  .command("doctor")
  .description("Check environment and repair common issues")
  .option("--fix", "Attempt to fix issues automatically")
  .option("--repair", "Alias for --fix")
  .option("--non-interactive", "Skip prompts")
  .action(async (opts) => {
    await doctorCommand(defaultRuntime, {
      fix: opts.fix || opts.repair,
      nonInteractive: opts.nonInteractive,
    });
  });

doctor 检查的项目包括：

检查项	说明
Node.js 版本	最低 18，推荐 22
配置文件	~/.openclaw/openclaw.json 是否存在且有效
API 密钥	至少配置了一个 LLM 提供商
UI 资源	dist/control-ui/ 是否存在
端口可用性	18789（Gateway）和 18790（Bridge）是否被占用
exec 沙箱	沙箱运行环境是否可用
可选依赖	Tailscale、ffmpeg 等

--fix 模式会尝试自动修复常见问题，如重建 UI 资源、修复配置文件格式等。openclaw update 命令在更新后也会自动运行 doctor 确保环境完整。

---

本节小结

1. npm 全局安装是最简单的部署方式，包含预构建产物，无需编译。

2. 守护进程管理：macOS 通过 launchd plist 实现自动启动和进程保活，Linux 通过 systemd service 实现同等功能。

3. openclaw doctor 提供全面的环境诊断，支持自动修复模式，是排查部署问题的首选工具。