# 37.1 本地部署

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

***

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

## 37.1.1 npm 全局安装

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

```bash
npm install -g openclaw
```

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

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

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

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

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

## 37.1.2 守护进程管理（launchd / systemd）

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

### macOS — launchd

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

```xml
<!-- ~/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` 管理服务：

```ini
# /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
```

```bash
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` 立即启动。

## 37.1.3 `openclaw doctor` 健康检查

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

```bash
$ 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 子命令组中：

```typescript
// 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`** 提供全面的环境诊断，支持自动修复模式，是排查部署问题的首选工具。