Skip to content

Latest commit

 

History

History
608 lines (439 loc) · 12.7 KB

OpenClaw-Deployment-Guide.md

File metadata and controls

608 lines (439 loc) · 12.7 KB

OpenClaw 部署指南

本文档详细介绍 OpenClaw 的环境要求、安装方法和配置步骤。 配套一键部署脚本：openclaw-deploy.sh、openclaw-deploy-macos-zsh.sh

目录

  1. 系统要求
  2. 环境依赖
  3. 安装方法
  4. 配置向导
  5. 服务管理
  6. 故障排除
  7. 进阶配置

系统要求

支持的平台

平台 支持状态 备注
macOS ✅ 完全支持 macOS 11+ 推荐
Linux ✅ 完全支持 Ubuntu 20.04+, Debian 11+, Fedora 35+
Windows ⚠️ 有限支持 强烈建议使用 WSL2

硬件要求

组件 最低配置 推荐配置
CPU 64位处理器 多核处理器
内存 4 GB RAM 8 GB RAM
磁盘 2 GB 可用空间 5 GB+ 可用空间
网络 互联网连接 稳定的宽带连接

环境依赖

必需依赖

1. Node.js

  • 版本要求: Node.js ≥ 22.12.0
  • 推荐版本: Node.js LTS (长期支持版)

检查 Node.js:

node --version
# 应显示 v22.x.x 或更高版本

安装 Node.js:

=== "macOS (Homebrew)" bash brew install node@22 brew link node@22 --force

=== "Ubuntu/Debian" bash # 使用 NodeSource curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs

=== "Fedora/RHEL/CentOS" bash curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - sudo dnf install -y nodejs

=== "Arch Linux" bash sudo pacman -S nodejs npm

=== "使用 NVM (推荐)" ```bash # 安装 NVM curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 加载 NVM
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 安装 Node.js
nvm install --lts
nvm use --lts
nvm alias default lts/*
```

2. npm / pnpm / Bun

  • npm: 随 Node.js 一起安装
  • pnpm: 高性能替代方案，节省磁盘空间
  • Bun: 超快 JavaScript 运行时和包管理器

安装 pnpm:

curl -fsSL https://get.pnpm.io/install.sh | sh -

安装 Bun:

curl -fsSL https://bun.sh/install | bash

3. Git (源码安装时需要)

# macOS
brew install git

# Ubuntu/Debian
sudo apt-get install git

# Fedora
sudo dnf install git

可选依赖

工具 用途 安装命令
Homebrew macOS 包管理器 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Tailscale 远程访问 https://tailscale.com/download
Docker 容器化部署 https://docs.docker.com/get-docker/

安装方法

方法一：macOS Zsh 专属脚本 (macOS 强烈推荐 ⭐)

专为 macOS Zsh 用户设计，自动处理 PATH 配置问题，无需手动编辑 ~/.zshrc。

一键运行（无需下载）：

# macOS 专属脚本 - 使用 Bun 安装（推荐）
bash <(curl -fsSL https://raw.githubusercontent.com/xiaoamo22333/OpenClaw_Guide/main/openclaw-deploy-macos-zsh.sh) --method bun

# 或使用 pnpm
bash <(curl -fsSL https://raw.githubusercontent.com/xiaoamo22333/OpenClaw_Guide/main/openclaw-deploy-macos-zsh.sh) --method pnpm

# 或使用 npm（默认）
bash <(curl -fsSL https://raw.githubusercontent.com/xiaoamo22333/OpenClaw_Guide/main/openclaw-deploy-macos-zsh.sh)

特点：

  • ✅ 自动检测并配置 ~/.zshrc
  • ✅ 自动添加 Bun/pnpm/npm 全局路径到 PATH
  • ✅ 自动重新加载配置
  • ✅ 解决 "command not found" 问题
  • ✅ 支持 Apple Silicon (M1/M2/M3) 和 Intel Mac

方法二：通用一键部署脚本

适合所有平台（macOS/Linux/WSL2）。

一键运行（无需下载）：

# 通用部署脚本 - 使用 npm 安装（默认）
bash <(curl -fsSL https://raw.githubusercontent.com/xiaoamo22333/OpenClaw_Guide/main/openclaw-deploy.sh)

# 使用 pnpm 安装
bash <(curl -fsSL https://raw.githubusercontent.com/xiaoamo22333/OpenClaw_Guide/main/openclaw-deploy.sh) --method pnpm

# 使用 Bun 安装
bash <(curl -fsSL https://raw.githubusercontent.com/xiaoamo22333/OpenClaw_Guide/main/openclaw-deploy.sh) --method bun

脚本选项：

# 查看帮助
bash <(curl -fsSL https://raw.githubusercontent.com/xiaoamo22333/OpenClaw_Guide/main/openclaw-deploy.sh) --help

# 使用 pnpm 安装
bash <(curl -fsSL https://raw.githubusercontent.com/xiaoamo22333/OpenClaw_Guide/main/openclaw-deploy.sh) --method pnpm

# 跳过配置向导
bash <(curl -fsSL https://raw.githubusercontent.com/xiaoamo22333/OpenClaw_Guide/main/openclaw-deploy.sh) --no-onboard

# 使用国内镜像加速
bash <(curl -fsSL https://raw.githubusercontent.com/xiaoamo22333/OpenClaw_Guide/main/openclaw-deploy.sh) --cn-mirror

# 详细输出
bash <(curl -fsSL https://raw.githubusercontent.com/xiaoamo22333/OpenClaw_Guide/main/openclaw-deploy.sh) --verbose

方法三：官方安装脚本

# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash
# Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

方法四：npm 安装

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

# 处理 sharp 编译错误 (macOS 用户)
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

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

方法五：pnpm 安装

# 全局安装
pnpm add -g openclaw@latest

# 批准构建脚本
pnpm approve-builds -g

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

方法六：从源码安装

适合开发者或需要最新功能的用户：

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

# 安装依赖
pnpm install

# 构建 UI
pnpm ui:build

# 构建项目
pnpm build

# 链接到全局
pnpm link --global

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

方法七：Bun 安装

Bun 是一个快速的 JavaScript 运行时和包管理器，比 npm 快 10-100 倍。

# 安装 Bun (如果尚未安装)
curl -fsSL https://bun.sh/install | bash

# 重新加载 shell
source ~/.bashrc  # 或 ~/.zshrc

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

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

Bun 的优势:

  • 🚀 超快的安装速度
  • 📦 自动管理依赖
  • 🔋 内置 TypeScript 支持

方法八：Docker 部署

# 拉取镜像
docker pull openclaw/openclaw:latest

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

配置向导

安装完成后，运行配置向导进行初始化：

openclaw onboard --install-daemon

向导将引导您完成：

  1. 身份验证设置

    • 配置 AI 模型提供商 (Anthropic, OpenAI 等)
    • 设置 API 密钥或 OAuth

  2. Gateway 配置

    • 设置端口号 (默认: 18789)
    • 配置工作目录
    • 安装系统服务

  3. 渠道配置 (可选)

    • WhatsApp
    • Telegram
    • Slack
    • Discord
    • 其他消息平台

  4. 技能配置 (可选)

    • 浏览器自动化
    • Canvas 可视化
    • 节点控制
    • 其他扩展功能

跳过向导

# 安装但不运行向导
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

# 稍后手动运行向导
openclaw onboard

服务管理

查看服务状态

# 查看 Gateway 状态
openclaw gateway status

# 运行诊断
openclaw doctor

启动/停止服务

# 启动 Gateway
openclaw gateway start

# 停止 Gateway
openclaw gateway stop

# 重启 Gateway
openclaw gateway restart

# 前台运行 (调试用)
openclaw gateway --port 18789 --verbose

系统服务说明

平台 服务类型 配置文件位置
macOS launchd ~/Library/LaunchAgents/ai.openclaw.gateway.plist
Linux systemd ~/.config/systemd/user/openclaw-gateway.service

故障排除

常见问题

1. "openclaw: command not found"

原因: npm 全局安装路径不在 PATH 中

解决:

# 添加 npm 全局路径到 shell 配置
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc  # 或 ~/.bashrc

# 重新加载配置
source ~/.zshrc  # 或 source ~/.bashrc

2. sharp 编译错误

原因: 本地 libvips 与 sharp 冲突

解决:

# 强制使用预构建二进制文件
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

3. Node.js 版本过低

解决:

# 使用 NVM 升级到最新 LTS
nvm install --lts
nvm use --lts
nvm alias default lts/*

4. Gateway 无法启动

检查:

# 检查端口占用
lsof -i :18789

# 检查日志
openclaw gateway --verbose

# 检查配置文件
openclaw doctor

5. 权限问题

解决:

# 修复 npm 权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# 或使用 npx 运行
npx openclaw@latest

6. macOS Zsh "command not found" 问题

原因: Bun/pnpm/npm 全局路径未添加到 ~/.zshrc

解决:

# 方案 1: 使用 macOS Zsh 专属脚本 (推荐)
# 自动处理所有 PATH 配置
bash <(curl -fsSL https://raw.githubusercontent.com/xiaoamo22333/OpenClaw_Guide/main/openclaw-deploy-macos-zsh.sh)

# 方案 2: 手动添加路径到 ~/.zshrc

# 如果是 Bun
echo 'export BUN_INSTALL="$HOME/.bun"' >> ~/.zshrc
echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> ~/.zshrc

# 如果是 pnpm
echo 'export PNPM_HOME="$HOME/Library/pnpm"' >> ~/.zshrc
echo 'export PATH="$PNPM_HOME:$PATH"' >> ~/.zshrc

# 如果是 npm 全局包
export PATH="$(npm prefix -g)/bin:$PATH"

# 重新加载配置
source ~/.zshrc

使用 macOS Zsh 专属脚本的优势：

  • 自动检测当前 shell 环境
  • 自动添加所需 PATH 到 ~/.zshrc
  • 安装后自动重新加载配置
  • 无需手动编辑配置文件

获取帮助

资源 链接
官方文档 https://docs.openclaw.ai
GitHub https://github.com/openclaw/openclaw
Discord 社区 https://discord.gg/clawd
问题反馈 https://github.com/openclaw/openclaw/issues

进阶配置

环境变量

变量 说明 示例
OPENCLAW_HOME 主目录 ~/.openclaw
OPENCLAW_STATE_DIR 状态目录 ~/.openclaw/state
OPENCLAW_CONFIG_PATH 配置文件路径 ~/.openclaw/config.json
OPENCLAW_PORT Gateway 端口 18789
OPENCLAW_LOG_LEVEL 日志级别 info, debug, error

配置文件示例

~/.openclaw/config.json:

{
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1"
  },
  "models": {
    "default": "anthropic/claude-opus-4-6",
    "fallback": "openai/gpt-4o"
  },
  "channels": {
    "webchat": {
      "enabled": true
    }
  }
}

更新 OpenClaw

# 检查更新
openclaw update --check

# 更新到最新版本
openclaw update

# 切换到测试频道
openclaw update --channel beta

卸载 OpenClaw

# 停止服务
openclaw gateway stop

# 卸载包 (根据安装方式选择)
npm uninstall -g openclaw
# 或
pnpm remove -g openclaw
# 或
bun uninstall -g openclaw

# 删除配置 (可选)
rm -rf ~/.openclaw

# 删除系统服务 (macOS)
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
rm ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# 删除系统服务 (Linux)
systemctl --user stop openclaw-gateway
rm ~/.config/systemd/user/openclaw-gateway.service

安全建议

  1. API 密钥管理

    • 不要将 API 密钥提交到版本控制
    • 使用环境变量或安全的密钥管理服务

  2. DM 安全

    • 默认启用配对模式，未知发送者需要批准
    • 使用 openclaw pairing approve <channel> <code> 批准新用户

  3. 网络安全

    • 使用 Tailscale 或 VPN 保护远程访问
    • 避免在公共网络暴露 Gateway 端口

  4. 定期更新

    • 保持 OpenClaw 和依赖项更新
    • 运行 openclaw doctor 检查安全问题

快速参考

# 核心命令
openclaw --help              # 显示帮助
openclaw dashboard           # 打开 Web 控制面板
openclaw gateway status      # 查看服务状态
openclaw agent               # 启动 AI 对话
openclaw doctor              # 运行诊断

# 消息发送
openclaw message send --target +1234567890 --message "Hello"

# 配对管理
openclaw pairing approve telegram ABC123
openclaw pairing reject telegram ABC123

# 配置管理
openclaw config get gateway.port
openclaw config set gateway.port 18888

最后更新: 2026-02-22 文档版本: 1.0.0