OpenClaw
全网最详细安装部署教程

OpenClaw 是一个 开源、自托管的个人 AI 助手网关（MIT 协议），运行在你自己的机器或服务器上，通过你已在使用的聊天工具（WhatsApp、Telegram、Discord、Slack、iMessage 等）与 AI 模型交互。

与 ChatGPT 等"会话即止"的 AI 工具不同，OpenClaw 作为持久化后台守护进程运行，可以主动发送消息、执行 Shell 命令、管理文件、自动化浏览器操作、发送定时任务提醒，是真正的"AI 数字员工"。

支持的消息平台

WhatsApp · Telegram · Discord · Slack · Google Chat · Signal · iMessage / BlueBubbles · IRC · Microsoft Teams · Matrix · Feishu（飞书）· LINE · Mattermost · Nostr · Synology Chat · Twitch · Zalo · WebChat · iOS/Android 节点

最低硬件要求

软件依赖

# 安装前检查命令
node --version     # 必须 v22.x.x 以上
npm --version      # 必须 8.x 以上
git --version
df -h              # 确认磁盘至少有 10GB 可用
free -h            # 确认 RAM ≥ 2GB

macOS（尤其是 Apple Silicon M 系列）是运行 OpenClaw 体验最好的平台，原生支持 iMessage、Reminders、Notes 等系统集成。

方法一：官方一键安装脚本（推荐）

curl -fsSL https://openclaw.ai/install.sh | bash

openclaw onboard

openclaw doctor      # 检查配置问题
openclaw status      # 查看 gateway 状态
openclaw dashboard   # 在浏览器中打开控制面板

方法二：npm 全局安装

# 先用 Homebrew 安装 Node.js 22
brew install node

# 验证版本
node --version  # 确认 ≥ v22

# 全局安装 OpenClaw
npm install -g openclaw@latest

# 或使用 pnpm
pnpm add -g openclaw@latest

方法三：macOS Companion App（Beta）

macOS 用户还可下载菜单栏 Companion App（需 macOS 14+），与 CLI 配合使用，提供更便捷的图形化管理界面。下载地址见官方文档。

# 方式 A：使用 NodeSource 官方源（推荐）
sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 方式 B：使用 nvm（多版本管理，推荐给开发者）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22

# 验证
node --version  # 必须 ≥ v22
npm --version

curl -fsSL https://openclaw.ai/install.sh | bash
# 或
npm install -g openclaw@latest

which openclaw        # 确认命令可找到
openclaw --version
openclaw onboard      # 运行初始化向导

注册为 systemd 服务（开机自启）

# 安装时带 --install-daemon 参数可自动注册服务
openclaw onboard --install-daemon

# 或手动管理
sudo cp scripts/openclaw.service /etc/systemd/system/
sudo systemctl enable openclaw
sudo systemctl start openclaw
systemctl status openclaw

# 查看日志
journalctl -u openclaw -f

# 需要 Windows 10 v2004+ 或 Windows 11
wsl --install
# 安装完成后重启，设置用户名密码

# 编辑 WSL 配置文件
sudo nano /etc/wsl.conf

# 添加以下内容
[boot]
systemd=true

# 重启 WSL2（PowerShell 中执行）
wsl --shutdown
wsl

sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 注意！在 WSL2 中，必须在 Linux 目录操作
# 不要在 /mnt/c/ 下操作（权限问题多）
cd ~/projects  # 使用 WSL 原生目录

npm install -g openclaw@latest
openclaw onboard

http://localhost:18789/

WSL2 开机自启配置

# WSL2 重启后 systemd 服务不会自动启动，手动启动：
systemctl --user start openclaw-gateway

# 或配置 Windows 任务计划程序在开机时自动启动 WSL
# 详见 Windows Task Scheduler 相关文档

Docker 方式提供最强的隔离性、可复现性和安全性，是 VPS 或需要多服务共存环境的首选方案。

git clone https://github.com/openclaw/openclaw.git
cd openclaw
bash docker-setup.sh

# docker-compose.yml 关键挂载
volumes:
  - ~/.openclaw:/workspace/.openclaw       # 配置、密钥
  - ~/openclaw/workspace:/workspace/files  # Agent 工作区

docker compose up -d          # 后台启动
docker compose ps             # 查看运行状态
docker compose logs -f        # 实时日志

# 运行 CLI 命令
docker compose run --rm openclaw-cli openclaw doctor
docker compose run --rm openclaw-cli openclaw status --all

# Telegram 配对
docker compose run --rm openclaw-cli pairing approve telegram <CODE>

WhatsApp Docker 持久化配置

# 正确持久化 WhatsApp 凭证（防断线后重新扫码）
services:
  openclaw:
    image: openclaw/openclaw:2026.1.29
    volumes:
      - /srv/openclaw/credentials/whatsapp:/workspace/.openclaw/credentials/whatsapp
      - /srv/openclaw/sessions:/workspace/.openclaw/sessions
    environment:
      - OPENCLAW_WA_SESSION_PERSISTENCE=true
      - OPENCLAW_WA_AUTO_RECONNECT=true
      - OPENCLAW_WA_RECONNECT_DELAY_MS=5000
      - OPENCLAW_WA_MAX_RECONNECT_ATTEMPTS=10

资源限制（低配 VPS）

# 限制容器资源，防止与其他服务竞争
deploy:
  resources:
    limits:
      memory: 512m
      cpus: '1.0'

VPS 是推荐的 24/7 永久在线部署方案，消除了本地断电、网络波动等问题。

推荐 VPS 配置

支持的 VPS 服务商：DigitalOcean（有 1-Click Deploy）、Contabo、Linode / Akamai、AWS EC2/Lightsail、Hetzner

DigitalOcean 1-Click 快速部署

DigitalOcean 提供预装 OpenClaw 的一键模板，包含 v2026.1.24-1 及所有依赖。登录后在控制台选择 Provider 和 API Key 即可，两种访问方式：GUI（浏览器）和 TUI（终端）。

手动 VPS 部署流程

# 1. SSH 到服务器
ssh root@your-vps-ip

# 2. 创建非 root 用户（重要！）
useradd -r -m -d /home/openclaw -s /bin/bash openclaw
passwd openclaw

# 3. 配置 SSH 公钥认证，禁用密码登录
mkdir -p /home/openclaw/.ssh && chmod 700 /home/openclaw/.ssh
nano /home/openclaw/.ssh/authorized_keys  # 粘贴你的公钥
chmod 600 /home/openclaw/.ssh/authorized_keys
chown -R openclaw:openclaw /home/openclaw/.ssh

# 4. 切换到 openclaw 用户安装
su - openclaw
curl -fsSL https://openclaw.ai/install.sh | bash

# 5. 防火墙配置
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow in on tailscale0  # 如使用 Tailscale
sudo ufw enable

低 RAM VPS 的 Swap 配置

# 1GB RAM 的 VPS 必须配置 Swap，否则 npm install 会 OOM
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

硬件选型建议

# Pi 上安装 OpenClaw（与 Linux 相同）
sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g openclaw@latest
openclaw onboard --install-daemon

Pi 的功耗仅约 5-10W，与 VPS 月租相比，设备成本可在数月内回本。推荐"混合部署"方案：Pi 作为 24/7 网关，笔记本/台式机作为节点，需要时连接使用本地摄像头、屏幕录制等能力。

NixOS 模块提供完全声明式、可审计、可复现的 OpenClaw 部署，并内置完整的安全加固配置。

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    openclaw.url = "github:Scout-DJ/openclaw-nix";
  };
}

# configuration.nix
{ config, pkgs, ... }: {
  services.openclaw = {
    enable = true;
    domain = "agents.example.com";
    modelProvider = "anthropic";
    modelApiKeyFile = "/run/secrets/anthropic-api-key";
    telegram = {
      enable = true;
      tokenFile = "/run/secrets/telegram-bot-token";
    };
    toolSecurity = "allowlist";
    toolAllowlist = [ "read" "write" "edit" "web_search" "web_fetch" "message" "tts" ];
  };
}

NixOS 模块自动配置：NoNewPrivileges=yes · PrivateTmp=yes · ProtectSystem=strict · ProtectHome=yes 等 systemd 安全指令。

安装完成后，运行 openclaw onboard 进行交互式配置。向导依次询问：

支持的 AI 提供商

多模型与故障转移配置

{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "thinkingLevel": "high"
  },
  "modelFallback": [
    "openai/gpt-4o",
    "openai/gpt-4o-mini"
  ]
}

切换为 Setup Token 方式（更稳定）

# 避免 OAuth 定期刷新失效，改用长期 API Token
openclaw models auth setup-token --provider anthropic
# 或粘贴 Token
openclaw models auth paste-token --provider anthropic

# OpenClaw 会通过 Bot 向你发送配对码
# 在终端执行：
openclaw pairing approve telegram <CODE>
# Docker 环境：
docker compose run --rm openclaw-cli pairing approve telegram <CODE>

Telegram 安全配置（allowlist）

{
  "channels": {
    "telegram": {
      "allowFrom": ["你的TelegramUserID"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

如何获取自己的 Telegram User ID：向 @userinfobot 发送任意消息即可获取数字 ID。

{
  "channels": {
    "slack": {
      "dm": { "policy": "pairing" }
    }
  }
}

Slack 接入需要创建 Slack App，获取 Bot Token（xoxb-...）和 Signing Secret，在向导中按提示配置。

安全核心原则

• 绝不以 root 用户运行 OpenClaw
• Gateway 默认绑定 127.0.0.1（loopback），绝不直接暴露到公网
• 远程访问通过 SSH 隧道或 Tailscale，而非开放端口
• 所有连接账号应是你可以承受丢失的备用账号
• 定期运行 openclaw doctor 检查配置漏洞
• 在配置文件中启用 exec.ask: "on"，写入/执行命令前需人工确认

绑定配置（仅本地访问 vs 网络访问）

# ✅ 安全：仅本地访问
openclaw config set gateway.bind loopback
# 等同于绑定 127.0.0.1，只有本机能访问

# ⚠️ 需要认证：通过 Tailscale 局域网访问
# 先安装 Tailscale
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# 配置 Tailscale Serve（需密码）
openclaw config set gateway.tailscale.mode serve

工具权限白名单（重要！）

{
  "allowedTools": [
    "read",       
    "write",      
    "edit",       
    "web_search", 
    "web_fetch",  
    "message",
    "tts"
  ],
  "elevatedTools": {
    "enabled": false
  }
}
// ⚠️ exec（Shell 命令）和 browser 权限要谨慎开启！
// 开启前务必配置 sandbox 隔离

Sandbox 隔离

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}
// 非主会话（群组聊天等）在隔离的 Docker 容器中运行

February 2026 重要安全更新：auth:none 被移除

# 2026年2月更新移除了 auth:none 模式，这是一个破坏性变更
# 所有旧版教程生成的配置可能产生漏洞
# 检查和修复安全配置：
openclaw doctor --security-audit

# 生成新的安全 Token
openclaw gateway restart
# 如果 doctor 未自动生成，手动生成
openssl rand -base64 48

安装为系统服务

# 安装时加参数（推荐）
openclaw onboard --install-daemon
# Linux: 注册 systemd 服务
# macOS: 注册 launchd 服务
# 确保服务存活，开机自动启动

# 查看服务状态
systemctl status openclaw     # Linux
launchctl list | grep openclaw  # macOS

使用 pm2 管理（替代方案）

npm install -g pm2
pm2 start openclaw -- gateway start
pm2 save
pm2 startup  # 生成开机启动脚本

# 更新到最新版本
npm install -g openclaw@latest

# ⚠️ 注意：版本更新后必须完全重启 Gateway
# 软重启 (SIGUSR1) 不会加载新模块 hash
openclaw gateway restart  # 必须完全重启
# 或使用 doctor 自动修复
openclaw doctor --fix

# Docker 更新
docker compose pull
docker compose up -d

# 订阅更新通知（推荐）
# 访问 github.com/openclaw/openclaw/releases 开启 Watch

每条消息都会调用 LLM API，活跃的 Telegram 群组或 Discord 频道可能快速消耗 API 额度。以 Claude 或 GPT-4 级别模型为例，单个活跃用户每天发 100 条消息，每天可能消耗 $3-5。

配置限速

# 在 .env 或配置文件中设置
RATE_LIMIT_PER_USER=30       # 每用户每小时最多 30 条消息
DAILY_COST_LIMIT=5.00        # 每天最高花费 $5

使用 ChatGPT OAuth 控制开销

如选择 OpenAI Codex + ChatGPT OAuth 认证方式，OpenClaw 的 API 调用会消耗 ChatGPT 订阅的额度（而非单独计费），自然设置了一个每月上限。

模型路由策略（省钱关键）

{
  "agent": {
    "model": "openai/gpt-4o-mini"  
  },
  "modelRouting": {
    "complex": "anthropic/claude-opus-4-6",
    "simple": "openai/gpt-4o-mini"
  }
}
// 简单对话用经济模型，复杂任务才用高端模型
// 此策略可降低 50%+ 的 API 成本

完整重装流程

# 当一切方法都失败时，完全清理重装
openclaw gateway stop
docker compose down -v    # 如果用 Docker
npm uninstall -g openclaw
docker system prune -a    # 清理 Docker 缓存（Docker 用户）
# 可选：备份并清理配置
cp -r ~/.openclaw ~/.openclaw-backup
rm -rf ~/.openclaw
# 重新安装
npm install -g openclaw@latest
openclaw onboard

获取社区帮助

• 官方文档：docs.openclaw.ai
• GitHub Discussions：github.com/openclaw/openclaw/discussions
• 官方 Discord：通过 README 中的链接加入
• 提 Issue 时附带：openclaw doctor 完整输出、OS 版本、Node 版本、Docker 版本