OpenClaw 部署与运维详细完整教程

OpenClaw 部署与运维详细完整教程

本教程提供从安装到生产环境运维的完整 OpenClaw 部署指南，涵盖多种部署场景和最佳实践。

📋 目录

  1. OpenClaw 简介
  2. 系统要求与环境准备
  3. 安装部署
  4. 基础配置
  5. Gateway 配置详解
  6. 通道配置
  7. 安全与认证
  8. 远程访问配置
  9. 运维与监控
  10. 故障排查
  11. 备份与恢复
  12. 升级维护

一、OpenClaw 简介

1.1 什么是 OpenClaw？

OpenClaw 是一个运行在本地设备的个人 AI 助手，具有以下特点：

  • 本地优先：数据和处理都在你的设备上
  • 多通道支持：WhatsApp、Telegram、Slack、Discord、飞书等 20+ 通讯平台
  • 统一控制平面：通过 Gateway WebSocket 管理所有会话和工具
  • 可扩展：支持 Skills 插件系统

1.2 核心架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
┌─────────────────────────────────────────────────────────────┐
│                         用户设备                              │
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────┐ │
│  │  WhatsApp   │    │   Telegram   │    │     Discord     │ │
│  └──────┬──────┘    └──────┬───────┘    └────────┬────────┘ │
│         │                  │                     │          │
│         └──────────────────┼─────────────────────┘          │
│                            ▼                                │
│                   ┌─────────────────┐                       │
│                   │     Gateway     │                       │
│                   │  (控制平面)      │                       │
│                   │  ws://localhost │                       │
│                   └────────┬────────┘                       │
│                            │                                │
│         ┌──────────────────┼──────────────────┐            │
│         ▼                  ▼                  ▼            │
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────┐ │
│  │  CLI 工具   │    │   WebChat    │    │   移动端 App    │ │
│  └─────────────┘    └──────────────┘    └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘

1.3 核心组件

组件 说明 用途
Gateway WebSocket 控制平面 会话管理、工具调度、事件分发
Agent AI 助手运行时 处理消息、调用工具
Channels 通讯通道 连接各种聊天平台
Skills 插件系统 扩展功能
Nodes 设备节点 移动端配对、设备控制

二、系统要求与环境准备

2.1 硬件要求

场景 CPU 内存 存储 网络
个人使用 2+ 核 4GB+ 10GB+ 宽带
小团队 4+ 核 8GB+ 20GB+ 稳定连接
生产环境 8+ 核 16GB+ 50GB+ 公网 IP/域名

2.2 软件要求

  • Node.js: 24 (推荐) 或 22.16+
  • npm: 10+ 或 pnpm/bun
  • 操作系统:
    • macOS 12+
    • Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
    • Windows 10/11 (WSL2 强烈推荐)

2.3 环境检查

1
2
3
4
5
6
7
8
9
10
11
# 检查 Node.js 版本
node --version  # 应 >= 22.16

# 检查 npm 版本
npm --version   # 应 >= 10

# 检查系统架构
uname -m        # x86_64 或 arm64

# 检查可用端口
netstat -tlnp | grep 18789  # 默认 Gateway 端口

2.4 网络要求

用途 端口 协议 说明
Gateway 18789 WebSocket 核心控制平面
WebChat 18789 HTTP/WebSocket 内置 Web 界面
通道 Webhook configurable HTTP 接收平台消息

三、安装部署

3.1 标准安装（推荐）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 使用 npm 全局安装
npm i -g openclaw

# 或使用 pnpm
pnpm add -g openclaw

# 验证安装
openclaw --version

# 官方一键安装
# macos/linux
curl -fsSL https://openclaw.ai/install.sh | bash

# windows powershell
powershell -c "irm https://openclaw.ai/install.ps1 | iex"

3.2 交互式初始化

1
2
# 启动引导向导（推荐）
openclaw onboard --install-daemon

这个命令会：

  1. 创建配置文件 ~/.openclaw/openclaw.json
  2. 初始化工作区 ~/.openclaw/workspace
  3. 安装 Gateway 守护进程（systemd/launchd）
  4. 引导配置模型和通道

3.3 开发环境安装

1
2
3
4
5
6
7
8
9
10
# 从源码安装
git clone https://github.com/openclaw/openclaw.git
cd openclaw

pnpm install
pnpm ui:build
pnpm build

# 运行开发版本
pnpm openclaw onboard --install-daemon

3.4 Docker 部署

1
2
3
4
5
6
7
8
9
10
11
12
13
# 使用官方 Docker 镜像
docker pull openclaw/openclaw:latest

# 运行容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e OPENAI_API_KEY=your_key \
  openclaw/openclaw:latest

# 查看日志
docker logs -f openclaw

3.5 Nix 部署

1
2
3
4
5
6
7
8
# 在 Nix 配置中添加
{
  inputs.openclaw.url = "github:openclaw/nix-openclaw";
  
  outputs = { self, nixpkgs, openclaw }: {
    # 使用 OpenClaw 模块
  };
}

四、基础配置

4.1 配置文件结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
~/.openclaw/
├── openclaw.json          # 主配置文件
├── openclaw.json.bak      # 自动备份
├── workspace/             # 工作区
│   ├── AGENTS.md         # 代理配置
│   ├── SOUL.md           # 个性定义
│   ├── TOOLS.md          # 工具配置
│   ├── USER.md           # 用户信息
│   ├── BOOTSTRAP.md      # 首次引导（可删除）
│   ├── HEARTBEAT.md      # 心跳任务
│   └── skills/           # 技能目录
├── credentials/          # 凭据存储
├── logs/                 # 日志文件
├── canvas/               # Canvas 数据
└── devices/              # 设备配对信息

4.2 最小配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "your-secure-token-here"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

4.3 使用 CLI 配置

1
2
3
4
5
6
7
8
9
10
11
12
# 交互式配置
openclaw configure

# 查看配置
openclaw config get

# 设置特定值
openclaw config set gateway.port 19001
openclaw config set agent.model "openai/gpt-4o"

# 验证配置
openclaw config validate

五、Gateway 配置详解

5.1 Gateway 核心配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "gateway": {
    "port": 18789,              // Gateway WebSocket 端口
    "mode": "local",            // local|remote|hybrid
    "bind": "loopback",         // loopback|lan|tailnet|auto|custom
    
    "auth": {
      "mode": "token",          // none|token|password|trusted-proxy
      "token": "secure-token",  // 共享令牌
      "allowTailscale": true    // 允许 Tailscale 身份
    },
    
    "controlUi": {
      "allowInsecureAuth": true // 允许不安全认证（仅本地）
    },
    
    "tailscale": {
      "mode": "off",            // off|serve|funnel
      "resetOnExit": false      // 退出时重置配置
    }
  }
}

5.2 启动 Gateway

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 前台运行（调试）
openclaw gateway run --verbose

# 后台服务
openclaw gateway start

# 查看状态
openclaw gateway status

# 查看健康
openclaw gateway health

# 停止服务
openclaw gateway stop

# 重启服务
openclaw gateway restart

5.3 绑定模式详解

模式 说明 适用场景
loopback 仅本地访问 (127.0.0.1) 单机使用
lan 局域网可访问 家庭/办公室网络
tailnet Tailscale 网络 远程安全访问
auto 自动检测 动态环境
custom 自定义绑定 高级配置

5.4 认证模式详解

模式 说明 安全级别
none 无认证 ⚠️ 仅开发
token 共享令牌 ✅ 推荐
password 密码认证 ✅ 高
trusted-proxy 信任代理 ⚠️ 需配合反向代理

六、通道配置

6.1 Telegram 配置

1
2
3
4
5
6
# 设置环境变量
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

# 或在配置文件中
openclaw config set channels.telegram.botToken "your-token"
openclaw config set channels.telegram.enabled true

配置选项：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "pairing",      // pairing|open
      "allowFrom": ["@username"], // 允许的用户
      "webhookUrl": "",           // 可选 Webhook
      "webhookSecret": ""         // Webhook 密钥
    }
  }
}

6.2 Discord 配置

1
export DISCORD_BOT_TOKEN="your-bot-token"
1
2
3
4
5
6
7
8
9
10
11
12
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "${DISCORD_BOT_TOKEN}",
      "dmPolicy": "pairing",
      "allowFrom": [],
      "guilds": [],               // 允许的 Discord 服务器
      "mediaMaxMb": 25          // 媒体大小限制
    }
  }
}

6.3 Slack 配置

1
2
export SLACK_BOT_TOKEN="xoxb-your-token"
export SLACK_APP_TOKEN="xapp-your-token"

6.4 飞书 (Feishu) 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "domain": "feishu",
      "connectionMode": "websocket",
      "groupPolicy": "open",
      "dmPolicy": "pairing"
    }
  }
}

6.5 WhatsApp 配置

1
2
3
4
# 登录 WhatsApp
openclaw channels login --channel whatsapp

# 扫描 QR 码完成配对

6.6 通道安全设置

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing",      // 配对模式：新用户需批准
      "allowFrom": ["@admin"],    // 白名单
      "groups": {                 // 群组配置
        "*": {
          "requireMention": true  // 需要 @提及才响应
        }
      }
    }
  }
}

七、安全与认证

7.1 DM 配对机制

默认情况下，未知发送者需要配对才能与助手交互：

1
2
3
4
5
6
7
8
# 查看待处理配对请求
openclaw pairing list

# 批准配对
openclaw pairing approve telegram ABC123

# 拒绝配对
openclaw pairing deny telegram ABC123

7.2 Gateway Token 管理

1
2
3
4
5
6
7
8
# 生成新 Token
openssl rand -hex 32

# 设置 Token
openclaw config set gateway.auth.token "your-new-token"

# 重启 Gateway 生效
openclaw gateway restart

7.3 沙箱配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",      // none|non-main|all
        "allowlist": [
          "bash", "process", "read", "write", "edit"
        ],
        "denylist": [
          "browser", "canvas", "nodes", "cron"
        ]
      }
    }
  }
}

7.4 安全检查

1
2
3
4
5
# 运行安全检查
openclaw doctor

# 查看安全报告
openclaw security audit

八、远程访问配置

8.1 Tailscale 集成

1
2
3
4
5
6
7
8
9
{
  "gateway": {
    "bind": "loopback",
    "tailscale": {
      "mode": "serve",      // serve|funnel
      "resetOnExit": false
    }
  }
}

启动：

1
2
3
4
5
# 自动配置 Tailscale
openclaw gateway run --tailscale serve

# 或使用 Funnel（公网访问）
openclaw gateway run --tailscale funnel --auth password

8.2 SSH 隧道

1
2
3
4
5
6
7
8
# 本地转发
ssh -L 18789:localhost:18789 user@remote-server

# 列如（也可指定本地端口）
ssh -L 18888:127.0.0.1:18789 [email protected]

# 远程转发（从服务器暴露到本地）
ssh -R 18789:localhost:18789 user@remote-server

8.3 反向代理配置

Nginx 配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;
    
    location / {
        proxy_pass http://localhost: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;
    }
}

Caddy 配置：

1
2
3
openclaw.yourdomain.com {
    reverse_proxy localhost:18789
}

九、运维与监控

9.1 健康检查

1
2
3
4
5
6
7
8
# Gateway 健康
openclaw health

# 完整探测
openclaw gateway probe

# 通道健康
openclaw status

9.2 日志管理

1
2
3
4
5
6
7
8
# 查看实时日志
openclaw logs

# 查看历史日志
openclaw logs --since 1h

# 设置日志级别
openclaw gateway run --log-level debug

9.3 监控指标

1
2
3
4
5
6
7
8
# 获取使用统计
openclaw gateway usage-cost

# 查看会话列表
openclaw sessions list

# 查看活跃连接
openclaw gateway call health

9.4 自动化任务

1
2
3
4
5
6
7
8
9
10
# 创建定时任务
openclaw cron add --name "daily-backup" \
  --schedule "0 2 * * *" \
  --command "openclaw backup create"

# 列出定时任务
openclaw cron list

# 删除定时任务
openclaw cron remove daily-backup

9.5 心跳检测

编辑 workspace/HEARTBEAT.md：

1
2
3
4
5
# 心跳任务清单

- [ ] 检查未读邮件
- [ ] 检查日历事件
- [ ] 检查系统健康

十、故障排查

10.1 常见问题

Gateway 无法启动

1
2
3
4
5
6
7
8
# 检查端口占用
lsof -i :18789

# 强制启动（杀死占用进程）
openclaw gateway run --force

# 查看详细错误
openclaw gateway run --verbose

通道连接失败

1
2
3
4
5
6
7
8
# 检查通道状态
openclaw channels status

# 重新登录通道
openclaw channels login --channel telegram

# 查看通道日志
openclaw logs --filter telegram

认证问题

1
2
3
4
5
6
7
8
9
10
11
# 验证 Token
openclaw config get gateway.auth.token

# 重新生成 Token
openssl rand -hex 32

# 查看 Token
openclaw dashboard --no-open

# 检查环境变量
echo $OPENCLAW_GATEWAY_TOKEN

10.2 诊断工具

1
2
3
4
5
6
7
8
9
10
11
# 全面诊断
openclaw doctor

# 检查配置
openclaw config validate

# 网络诊断
openclaw gateway discover

# 测试连接
openclaw gateway call health

10.3 调试模式

1
2
3
4
5
6
7
8
# 启用详细日志
openclaw gateway run --verbose --ws-log full

# 原始流日志
openclaw gateway run --raw-stream --raw-stream-path ./stream.jsonl

# 开发模式
openclaw --dev gateway run

十一、备份与恢复

11.1 创建备份

1
2
3
4
5
6
7
8
9
10
11
12
# 创建完整备份
openclaw backup create

# 指定备份路径
openclaw backup create --output ~/backups/openclaw-$(date +%Y%m%d).tar.gz

# 自动备份脚本
#!/bin/bash
BACKUP_DIR="$HOME/backups/openclaw"
mkdir -p "$BACKUP_DIR"
openclaw backup create --output "$BACKUP_DIR/backup-$(date +%Y%m%d-%H%M%S).tar.gz"
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +30 -delete

11.2 恢复备份

1
2
3
4
5
# 从备份恢复
openclaw backup restore --file ~/backups/openclaw-20240331.tar.gz

# 验证备份完整性
openclaw backup verify --file ~/backups/openclaw-20240331.tar.gz

11.3 备份内容

备份包含：

  • openclaw.json - 主配置
  • workspace/ - 工作区文件
  • credentials/ - 加密凭据
  • sessions/ - 会话历史
  • skills/ - 自定义技能

十二、升级维护

12.1 检查更新

1
2
3
4
5
# 检查新版本
openclaw update status

# 查看当前版本
openclaw --version

12.2 执行升级

1
2
3
4
5
6
7
8
# 升级到最新版
npm install -g openclaw@latest

# 或指定版本
npm install -g [email protected]

# 升级后重启
openclaw gateway restart

12.3 升级频道

1
2
3
4
5
6
7
8
# 切换到 Beta 频道
openclaw update --channel beta

# 切换到开发频道
openclaw update --channel dev

# 切换回稳定版
openclaw update --channel stable

12.4 升级前检查

1
2
3
4
5
6
7
8
# 运行升级前检查
openclaw doctor

# 创建升级前备份
openclaw backup create --output ~/pre-upgrade-backup.tar.gz

# 查看升级日志
openclaw update --dry-run

附录

A. 环境变量参考

变量 说明 示例
OPENCLAW_GATEWAY_TOKEN Gateway 认证令牌 abc123...
OPENAI_API_KEY OpenAI API 密钥 sk-...
ANTHROPIC_API_KEY Anthropic API 密钥 sk-ant-...
TELEGRAM_BOT_TOKEN Telegram Bot Token 123456:ABC...
DISCORD_BOT_TOKEN Discord Bot Token ...
SLACK_BOT_TOKEN Slack Bot Token xoxb-...
SLACK_APP_TOKEN Slack App Token xapp-...

B. CLI 命令速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# 基础
openclaw --version                    # 查看版本
openclaw onboard                      # 初始化向导
openclaw doctor                       # 健康检查

# Gateway
openclaw gateway run                  # 前台运行
openclaw gateway start                # 后台启动
openclaw gateway stop                 # 停止
openclaw gateway status               # 状态
openclaw gateway restart              # 重启

# 配置
openclaw config get                   # 查看配置
openclaw config set <path> <value>    # 设置配置
openclaw config validate              # 验证配置

# 通道
openclaw channels login               # 登录通道
openclaw channels status              # 通道状态

# 消息
openclaw message send                 # 发送消息
openclaw agent --message "..."        # 与助手对话

# 备份
openclaw backup create                # 创建备份
openclaw backup restore               # 恢复备份

C. 配置文件模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
  "meta": {
    "lastTouchedVersion": "2026.3.28",
    "lastTouchedAt": "2026-03-31T00:00:00.000Z"
  },
  "auth": {
    "profiles": {
      "openai:default": {
        "provider": "openai",
        "mode": "api_key"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "api": "openai-completions"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-4o"
      },
      "workspace": "~/.openclaw/workspace"
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  "channels": {},
  "tools": {
    "profile": "coding",
    "web": {
      "search": {
        "enabled": true,
        "provider": "duckduckgo"
      }
    }
  }
}

D. 参考链接

结语

OpenClaw 是一个功能强大且灵活的本地 AI 助手平台。通过本指南，你应该能够：

  1. 在各种环境中部署 OpenClaw
  2. 配置多个通讯通道
  3. 确保系统安全
  4. 进行日常运维和故障排查
  5. 保持系统更新