乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > 【OpenClaw 架构设计】6-OpenClaw 部署

【OpenClaw 架构设计】6-OpenClaw 部署

当前时间： 2026-05-27 17:39:16 更新时间： 2026-05-27 分类：软件教程 评论(0)

【OpenClaw 架构设计】6-OpenClaw 部署

1. 概述

OpenClaw 提供多种部署选项，包括 NPM 全局安装、Docker 部署和源码构建。根据您的使用场景和技术需求，可以选择最适合的部署方式。本文档详细介绍了各种部署选项、先决条件、部署工作流和技术栈。

2. 部署选项

2.1 NPM 全局安装（推荐）

NPM 全局安装是最简单、最推荐的部署方式，适用于 macOS、Linux 和 Windows（通过 WSL2）。

2.1.1 安装步骤

# 1. 安装 OpenClawnpm install -g openclaw@latest# 2. 运行向导配置openclaw onboard --install-daemon# 3. 验证安装openclaw doctor# 4. 检查 Gateway 状态openclaw statusopenclaw health

2.1.2 使用 pnpm 安装

如果您使用 pnpm 作为包管理器：

# 1. 安装 OpenClawpnpm add -g openclaw@latest# 2. 批准构建脚本pnpm approve-builds -g# 3. 重新运行安装以执行 postinstall 脚本pnpm add -g openclaw@latest# 4. 运行向导配置openclaw onboard --install-daemon

2.1.3 优点

  • 简单快速
    一条命令即可完成安装
  • 自动更新
    通过 npm 轻松更新到最新版本
  • 系统集成
    自动配置系统服务（launchd/systemd）
  • 跨平台
    支持 macOS、Linux、Windows（WSL2）

2.1.4 适用场景

  • 个人开发和测试
  • 本地运行 AI 助手
  • 快速体验 OpenClaw 功能
  • 开发者日常使用

2.2 Docker 部署

Docker 部署适合容器化环境、服务器部署和隔离运行。

2.2.1 快速开始

# 1. 克隆仓库git clone https://github.com/openclaw/openclaw.gitcd openclaw# 2. 运行 Docker 设置脚本./docker-setup.sh

docker-setup.sh 脚本会自动完成以下操作：

  • 构建 Gateway Docker 镜像
  • 运行配置向导
  • 生成 Gateway Token
  • 启动 Gateway 服务

2.2.2 手动 Docker 部署

如果您需要更多控制，可以手动配置：

# 1. 构建镜像docker build -t openclaw:local .# 2. 创建数据目录mkdir -p ~/.openclawmkdir -p ~/.openclaw/workspace# 3. 生成 Gateway Tokenexport OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)# 4. 运行容器docker run -d \  --name openclaw-gateway \  -v ~/.openclaw:/root/.openclaw \  -p 18789:18789 \  -e OPENCLAW_GATEWAY_TOKEN=$OPENCLAW_GATEWAY_TOKEN \  openclaw:local

2.2.3 Docker Compose 配置

使用 Docker Compose 可以更方便地管理服务：

# docker-compose.ymlversion: '3.8'services:  openclaw-gateway:    image: openclaw:local    container_name: openclaw-gateway    restart: unless-stopped    ports:      - "18789:18789"    volumes:      - ~/.openclaw:/root/.openclaw    environment:      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}      - OPENCLAW_GATEWAY_BIND=0.0.0.0      - OPENCLAW_GATEWAY_PORT=18789

启动服务：

# 启动docker compose up -d# 查看日志docker compose logs -f openclaw-gateway# 健康检查docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

2.2.4 渠道配置

在 Docker 容器中配置渠道：

# WhatsApp（QR 登录）docker compose run --rm openclaw-cli channels login# Telegram（Bot Token）docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"# Discord（Bot Token）docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

2.2.5 优点

  • 环境隔离
    完全隔离的运行环境
  • 易于部署
    一次构建，到处运行
  • 可移植性
    轻松迁移到不同服务器
  • 资源限制
    可以限制容器的资源使用

2.2.6 适用场景

  • 服务器部署
  • 生产环境
  • 多环境隔离
  • CI/CD 流水线
  • 云平台部署（Hetzner、Railway、Render 等）

2.3 源码构建

源码构建适合开发者和需要自定义部署的场景。

2.3.1 克隆仓库

# 克隆仓库git clone https://github.com/openclaw/openclaw.gitcd openclaw

2.3.2 安装依赖

# 使用 pnpm 安装依赖pnpm install# 构建 UI（首次运行会自动安装 UI 依赖）pnpm ui:build# 构建项目pnpm build

2.3.3 运行配置

# 运行向导配置pnpm openclaw onboard --install-daemon# 或者使用 Node.js 运行node dist/index.js onboard --install-daemon

2.3.4 开发模式

如果您想参与开发或调试：

# 开发模式运行 Gateway（自动重载）pnpm gateway:watch# 运行测试pnpm test# 代码检查pnpm lint# 格式化代码pnpm format

2.3.5 优点

  • 完全控制
    可以修改和定制任何部分
  • 最新功能
    可以体验最新的开发功能
  • 调试方便
    可以直接调试源码
  • 贡献代码
    方便提交 PR 贡献代码

2.3.6 适用场景

  • 开发者贡献代码
  • 自定义功能开发
  • 调试和问题排查
  • 学习和研究架构

2.4 其他部署选项

2.4.1 Nix

使用 Nix 进行声明式配置：

# 使用 Nix 安装nix profile install github:openclaw/nix-clawdbot

详细文档：Nix 安装指南

2.4.2 Ansible

使用 Ansible 自动化部署：

# 使用 Ansible playbookansible-playbook openclaw.yml

详细文档：Ansible 安装指南

2.4.3 Bun

使用 Bun 运行时（仅 CLI）：

# 使用 Bun 安装bun install -g openclaw@latest# 运行bun openclaw onboard --install-daemon

详细文档：Bun 安装指南

3. 先决条件

3.1 运行时环境

3.1.1 Node.js

OpenClaw 需要 Node.js 22+ 版本：

# 检查 Node.js 版本node --version# 推荐版本：22.12.0+

安装 Node.js：

# macOS (使用 Homebrew)brew install node@22# Linux (使用 nvm)curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bashnvm install 22nvm use 22# Windows (使用 Chocolatey)choco install nodejs-lts

3.1.2 包管理器

推荐使用 pnpm 作为包管理器：

# 安装 pnpmnpm install -g pnpm# 检查版本pnpm --version# 推荐版本：10.23.0+

3.1.3 Bun（可选）

Bun 是一个可选的运行时，可以直接运行 TypeScript：

# 安装 Buncurl -fsSL https://bun.sh/install | bash# 检查版本bun --version

3.2 系统要求

3.2.1 macOS

  • 版本
    macOS 10.15+ (Catalina 及以上)
  • 架构
    支持 Intel (x64) 和 Apple Silicon (ARM64)
  • 工具
    Xcode Command Line Tools
# 安装 Xcode Command Line Toolsxcode-select --install

3.2.2 Linux

  • 发行版
    Ubuntu、Debian、Fedora、CentOS 等主流发行版
  • 内核
    Linux kernel 4.0+
  • 工具
    build-essential、python3
# Ubuntu/Debiansudo apt-get updatesudo apt-get install -y build-essential python3# Fedorasudo dnf install -y gcc-c++ make python3

3.2.3 Windows

  • 版本
    Windows 10+ (通过 WSL2)
  • WSL2
    必须启用 WSL2
# 启用 WSL2wsl --install# 安装 Ubuntuwsl --install -d Ubuntu-22.04

3.3 AI 模型

OpenClaw 支持多种 AI 模型，推荐使用 Anthropic Claude。

3.3.1 Anthropic Claude（推荐）

# 配置 Anthropic API Keyopenclaw config set agents.defaults.auth.anthropic.apiKey YOUR_API_KEY# 或使用 OAuth 登录openclaw login --provider anthropic

推荐模型：

  • Claude Opus 4.5
    最强大的模型，适合复杂任务
  • Claude Sonnet 4.5
  • 平衡性能和成本
  • Claude 3.5 Sonnet
    稳定可靠的模型

3.3.2 OpenAI GPT

# 配置 OpenAI API Keyopenclaw config set agents.defaults.auth.openai.apiKey YOUR_API_KEY# 或使用 OAuth 登录openclaw login --provider openai

支持模型：

  • GPT-4o
    最新的多模态模型
  • GPT-4 Turbo
    高性能模型
  • O1/O3
    推理增强模型

3.3.3 其他模型

OpenClaw 还支持：

  • Google Gemini
  • OpenRouter
  • 本地模型
    （通过 Ollama）

3.4 可选依赖

3.4.1 Chrome/Chromium

浏览器工具需要 Chrome 或 Chromium：

# macOSbrew install --cask google-chrome# Linuxsudo apt-get install -y chromium-browser# Windowschoco install googlechrome

3.4.2 ElevenLabs API

语音合成需要 ElevenLabs API：

# 配置 ElevenLabs API Keyopenclaw config set tts.elevenlabs.apiKey YOUR_API_KEY

3.4.3 Docker

容器化部署和沙箱隔离需要 Docker：

# macOSbrew install --cask docker# Linuxcurl -fsSL https://get.docker.com | sh# Windows# 安装 Docker Desktop

4. 部署工作流

4.1 标准部署流程

1. 环境准备• 安装 Node.js 22+• 配置 pnpm• 选择部署方式2. 安装 OpenClaw• NPM: npm install -g openclaw@latest• Docker: ./docker-setup.sh• 源码: pnpm install && pnpm build3. 运行向导• openclaw onboard –install-daemon• 配置 Gateway• 配置工作区 • 选择渠道 • 安装技能4. 启动服务• 安装 daemon 服务• 启动 Gateway • 验证连接 • 检查健康状态5. 配置渠道• 连接消息渠道 • 配置 AI 模型 • 测试功能

4.2 详细步骤

4.2.1 环境准备

# 1. 检查 Node.js 版本node --version  # 应该 >= 22.12.0# 2. 安装 pnpmnpm install -g pnpm# 3. 检查 pnpm 版本pnpm --version  # 应该 >= 10.23.0# 4. （可选）安装 Buncurl -fsSL https://bun.sh/install | bash

4.2.2 安装 OpenClaw

# NPM 安装（推荐）npm install -g openclaw@latest# 或使用 pnpmpnpm add -g openclaw@latestpnpm approve-builds -gpnpm add -g openclaw@latest

4.2.3 运行向导

# 运行配置向导openclaw onboard --install-daemon

向导会引导您完成以下配置：

  1. Gateway 配置
    • 绑定地址：loopback（本地）或 lan（局域网）
    • 端口：默认 18789
    • 认证方式：token 或 none
    • Tailscale 暴露：On 或 Off
  2. 工作区配置
    • 工作区路径：默认 ~/openclaw
    • 代理 ID：默认 main
    • 代理名称：自定义名称
  3. 渠道配置
    • 选择要连接的渠道
    • 配置渠道凭证
  4. 技能安装
    • 选择要安装的技能
    • 配置技能参数

4.2.4 启动服务

# 1. 验证安装openclaw doctor# 2. 检查 Gateway 状态openclaw status# 3. 检查健康状态openclaw health# 4. 打开控制面板openclaw dashboard

4.2.5 配置渠道

# WhatsApp（QR 登录）openclaw channels login --channel whatsapp# Telegram（Bot Token）openclaw channels add --channel telegram --token YOUR_BOT_TOKEN# Discord（Bot Token）openclaw channels add --channel discord --token YOUR_BOT_TOKEN# Slack（OAuth）openclaw channels login --channel slack

4.3 验证部署

# 1. 检查 Gateway 运行状态openclaw status# 2. 检查 Gateway 健康openclaw health# 3. 检查渠道状态openclaw channels status# 4. 发送测试消息openclaw message send --to YOUR_PHONE_NUMBER --message "Hello from OpenClaw"# 5. 测试 AI 代理openclaw agent --message "Hello, how are you?"

5. 技术栈

5.1 核心技术

技术
版本
用途
TypeScript
ESM
主要开发语言
Node.js
22+
运行时环境
pnpm
10.23.0+
包管理器
WebSocket
–
实时通信
Express
5.x
HTTP 服务器
Hono
4.x
Web 框架
SQLite
–
数据存储
Vitest
4.x
测试框架

5.2 渠道技术

渠道
库
用途
WhatsApp
Baileys
WhatsApp Web API
Telegram
grammY
Telegram Bot API
Slack
Bolt
Slack App API
Discord
discord.js
Discord Bot API
Signal
signal-cli
Signal CLI

5.3 AI 模型技术

提供商
SDK
用途
Anthropic
@anthropic-ai/sdk
Claude API
OpenAI
openai
GPT API
Google
@google/generative-ai
Gemini API

5.4 浏览器技术

技术
用途
Playwright
浏览器自动化
Chrome DevTools Protocol
浏览器控制

5.5 移动端技术

平台
语言
框架
iOS
Swift
SwiftUI
Android
Kotlin
Jetpack Compose
macOS
Swift
SwiftUI

5.6 其他技术

技术
用途
Sharp
图像处理
node-llama-cpp
本地模型推理
sqlite-vec
向量搜索
Croner
定时任务
AJV
JSON Schema 验证
TypeBox
运行时类型检查

6. 部署最佳实践

6.1 生产环境部署

6.1.1 使用 Docker

# docker-compose.prod.ymlversion: '3.8'services:  openclaw-gateway:    image: openclaw:latest    container_name: openclaw-gateway    restart: always    ports:      - "18789:18789"    volumes:      - /data/openclaw:/root/.openclaw      - /data/openclaw/workspace:/root/.openclaw/workspace    environment:      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}      - OPENCLAW_GATEWAY_BIND=0.0.0.0      - NODE_ENV=production    healthcheck:      test: ["CMD", "node", "dist/index.js", "health", "--token", "${OPENCLAW_GATEWAY_TOKEN}"]      interval: 30s      timeout: 10s      retries: 3    logging:      driver: "json-file"      options:        max-size: "10m"        max-file: "3"

6.1.2 使用 systemd

# /etc/systemd/system/openclaw.service[Unit]Description=OpenClaw GatewayAfter=network.target[Service]Type=simpleUser=openclawGroup=openclawWorkingDirectory=/home/openclawExecStart=/usr/bin/node /usr/lib/node_modules/openclaw/dist/index.js gateway --port 18789Restart=alwaysRestartSec=10Environment=NODE_ENV=productionEnvironment=OPENCLAW_GATEWAY_TOKEN=YOUR_TOKEN[Install]WantedBy=multi-user.target

启用服务：

# 创建用户sudo useradd -r -s /bin/false openclaw# 安装 OpenClawsudo npm install -g openclaw@latest# 复制服务文件sudo cp openclaw.service /etc/systemd/system/# 启用服务sudo systemctl daemon-reloadsudo systemctl enable openclawsudo systemctl start openclaw# 检查状态sudo systemctl status openclaw

6.2 安全配置

6.2.1 使用 Token 认证

# 生成强 Tokenexport OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)# 配置 Gateway 使用 Tokenopenclaw config set gateway.auth.token $OPENCLAW_GATEWAY_TOKEN

6.2.2 配置防火墙

# UFW (Ubuntu)sudo ufw allow 18789/tcpsudo ufw enable# iptablessudo iptables -A INPUT -p tcp --dport 18789 -j ACCEPTsudo iptables-save

6.2.3 使用 TLS

使用 Nginx 反向代理配置 TLS：

# /etc/nginx/sites-available/openclawserver {    listen 443 ssl http2;    server_name openclaw.yourdomain.com;    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;    location / {        proxy_pass http://127.0.0.1:18789;        proxy_http_version 1.1;        proxy_set_header Upgrade $http_upgrade;        proxy_set_header Connection "upgrade";        proxy_set_header Host $host;        proxy_set_header X-Real-IP $remote_addr;        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;        proxy_set_header X-Forwarded-Proto $scheme;    }}

6.3 监控和日志

6.3.1 日志管理

# 查看日志openclaw logs# 实时查看日志openclaw logs --follow# 查看最近 100 行日志openclaw logs --lines 100

6.3.2 健康监控

# 定期健康检查*/5 * * * * /usr/bin/openclaw health --token $OPENCLAW_GATEWAY_TOKEN || /usr/bin/systemctl restart openclaw

6.4 备份和恢复

6.4.1 备份数据

# 备份配置和数据tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw# 备份到云存储aws s3 cp openclaw-backup-$(date +%Y%m%d).tar.gz s3://your-bucket/backups/

6.4.2 恢复数据

# 恢复备份tar -xzf openclaw-backup-20260228.tar.gz -C ~/# 重启服务sudo systemctl restart openclaw

7. 故障排查

7.1 常见问题

7.1.1 Gateway 无法启动

# 检查端口占用lsof -i :18789# 检查日志openclaw logs# 运行诊断openclaw doctor

7.1.2 渠道连接失败

# 检查渠道状态openclaw channels status# 重新登录渠道openclaw channels login --channel whatsapp# 查看渠道日志openclaw logs --channel whatsapp

7.1.3 AI 模型调用失败

# 检查模型配置openclaw config get agents.defaults.auth# 测试模型连接openclaw agent --message "test" --verbose# 查看错误日志openclaw logs --level error

7.2 获取帮助

  • 文档
    https://docs.openclaw.ai
  • GitHub Issues
    https://github.com/openclaw/openclaw/issues
  • Discord
    https://discord.gg/clawd
  • 诊断工具
    openclaw doctor

8. 总结

OpenClaw 提供了灵活多样的部署选项：

  1. NPM 全局安装
    最简单快速，适合个人使用和开发
  2. Docker 部署
    环境隔离，适合生产环境和服务器部署
  3. 源码构建
    完全控制，适合开发者贡献代码和自定义开发

根据您的具体需求选择合适的部署方式，并参考本文档中的最佳实践进行配置和优化。