# OpenClaw 完整安装教程：全平台部署指南
　　OpenClaw 是一款功能强大的开源AI助手工具，支持多种部署方式和平台环境。下面将详细介绍在不同操作系统上的安装方法、配置步骤以及常见问题解决方案。
　　 环境准备与前置要求
　　在开始安装OpenClaw 之前，需要确保系统满足以下基本要求：
　　| 组件 | 最低要求 | 推荐版本 |
　　|------|----------|----------|
　　| 操作系统 | Windows 10 / macOS 10.15+ / Ubuntu 18.04+ | 最新稳定版 |
　　| Node.js | 18.x | 22.22.0 [ref_6] |
　　| 内存 | 4GB | 8GB+ |
　　| 存储空间 | 2GB | 5GB+ |
　　 Node.js 环境配置
　　Windows 系统推荐使用 nvm 管理 Node.js 版本：
　　bash
　　# 使用 nvm 安装指定版本的 Node.js
　　nvm install 22.22.0
　　nvm use 22.22.0
　　# 验证安装
　　node --version
　　npm --version
　　
　　macOS/Linux 系统：
　　bash
　　# 使用 Homebrew (macOS)
　　brew install node@22
　　# 或使用官方安装脚本
　　curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
　　sudo apt-get install -y nodejs
　　
　　 安装方法详解
　　OpenClaw 提供多种安装方式，用户可根据自身需求选择合适的方法。
　　 方法一：一键安装（推荐新手）
　　这是最简单快捷的安装方式，适用于所有主流平台：
　　bash
　　# 使用官方安装脚本
　　npm install -g @openclaw/cli
　　# 或使用 curl 方式
　　curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/install.sh | bash
　　
　　安装完成后，运行初始化命令：
　　bash
　　# 初始化 OpenClaw 配置
　　openclaw init
　　
　　此方法会自动检测系统环境并完成所有依赖项的安装 [ref_5]。
　　 方法二：npm 手动安装
　　适合需要更多控制权的用户：
　　bash
　　# 创建项目目录
　　mkdir openclaw-project && cd openclaw-project
　　# 初始化 npm 项目
　　npm init -y
　　# 安装OpenClaw CLI
　　npm install @openclaw/cli --save-dev
　　# 安装核心包
　　npm install @openclaw/core --save
　　
　　 方法三：Docker 部署
　　适合需要环境隔离或快速部署的场景：
　　dockerfile
　　# 使用官方 Docker 镜像
　　docker pull openclaw/openclaw:latest
　　# 运行容器
　　docker run -it -p 3000:3000 
　　 -v $(pwd)/config:/app/config 
　　 openclaw/openclaw:latest
　　
　　或者使用 docker-compose：
　　yaml
　　version: '3.8'
　　services:openclaw:
　　 image:openclaw/openclaw:latest
　　 ports:
　　 - "3000:3000"
　　 volumes:
　　 - ./data:/app/data
　　 environment:
　　 - NODE_ENV=production
　　
　　 方法四：源码编译安装
　　适合开发者或需要定制功能的用户：
　　bash
　　# 克隆源码
　　git clone https://github.com/openclaw/openclaw.git
　　cd openclaw
　　# 安装依赖
　　npm install
　　# 构建项目
　　npm run build
　　# 链接到全局
　　npm link
　　
　　 平台特定安装指南
　　 Windows 系统安装
　　标准安装流程：
　　1. 安装 Node.js 环境
　　 powershell
　　 # 以管理员身份运行 PowerShell
　　 # 安装 Chocolatey (包管理器)
　　 Set-ExecutionPolicy Bypass -Scope Process -Force
　　 [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
　　 iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
　　 # 使用 Chocolatey 安装 Node.js
　　 choco install nodejs -y
　　 
　　2. 安装OpenClaw
　　 powershell
　　 npm install -g @openclaw/cli
　　 openclaw --version
　　 
　　WSL2 安装方案：
　　如果遇到兼容性问题，建议使用 WSL2 环境 [ref_1]：
　　bash
　　# 在 WSL2 Ubuntu 中执行
　　sudo apt update && sudo apt upgrade -y
　　# 启用 systemd
　　sudo nano /etc/wsl.conf
　　# 添加以下内容：
　　# [boot]
　　# systemd=true
　　# 重启 WSL，然后安装OpenClaw
　　wsl --shutdown
　　wsl
　　npm install -g @openclaw/cli
　　
　　 macOS 系统安装
　　Intel 和 Apple Silicon 芯片通用安装：
　　bash
　　# 使用 Homebrew 安装依赖
　　brew install node git
　　# 安装OpenClaw
　　npm install -g @openclaw/cli
　　# 解决可能的权限问题
　　sudo npm install -g @openclaw/cli --unsafe-perm=true --allow-root
　　
　　对于自定义模型配置，需要额外设置 [ref_3]：
　　bash
　　# 配置自定义模型提供商
　　openclaw config set provider.custom.url "https://api.example.com/v1"
　　openclaw config set provider.custom.apiKey "your-api-key-here"
　　
　　 Linux 系统安装
　　Ubuntu/Debian 系统：
　　bash
　　# 更新系统并安装依赖
　　sudo apt update
　　sudo apt install -y curl git build-essential
　　# 安装 Node.js
　　curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
　　sudo apt-get install -y nodejs
　　# 安装OpenClaw
　　sudo npm install -g @openclaw/cli
　　
　　CentOS/RHEL 系统：
　　bash
　　# 安装 EPEL 仓库和依赖
　　sudo yum install -y epel-release
　　sudo yum install -y curl git
　　# 安装 Node.js
　　curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
　　sudo yum install -y nodejs
　　# 安装OpenClaw
　　sudo npm install -g @openclaw/cli
　　
　　 服务配置与启动
　　 Gateway 服务配置
　　OpenClaw 的核心是 Gateway 服务，负责处理所有 AI 请求：
　　bash
　　# 启动 Gateway 服务
　　openclaw gateway start
　　# 或使用开发模式
　　openclaw gateway dev
　　
　　配置服务参数：
　　bash
　　# 设置服务端口（默认 3000）
　　openclaw config set gateway.port 8080
　　# 设置主机绑定
　　openclaw config set gateway.host 0.0.0.0
　　# 启用 HTTPS
　　openclaw config set gateway.https true
　　
　　 模型配置
　　配置 AI 模型是 OpenClaw 的核心功能，以下以 GLM-4.6 为例 [ref_5]：
　　bash
　　# 配置智谱 AI 模型
　　openclaw config set models.default.provider "zhipu"
　　openclaw config set models.default.apiKey "your-zhipu-api-key"
　　openclaw config set models.default.model "glm-4-6"
　　openclaw config set models.default.baseUrl "https://open.bigmodel.cn/api/paas/v4"
　　
　　验证模型配置：
　　bash
　　# 测试模型连接
　　openclaw test model
　　# 查看配置信息
　　openclaw config list
　　
　　 飞书机器人集成
　　OpenClaw 可以轻松集成到飞书平台，实现企业级 AI 助手功能 [ref_2][ref_4]。
　　 飞书应用创建步骤
　　1. 登录飞书开放平台，创建企业自建应用
　　2. 启用机器人能力，获取 App ID 和 App Secret
　　3. 配置权限：消息接收、发送等必要权限
　　4. 设置事件回调 URL：`https://your-domain.com/webhook/feishu`
　　 OpenClaw 飞书插件安装
　　bash
　　# 安装飞书插件
　　openclaw plugin install @openclaw/feishu
　　# 配置飞书凭据
　　openclaw config set feishu.appId "your-app-id"
　　openclaw config set feishu.appSecret "your-app-secret"
　　openclaw config set feishu.encryptKey "your-encrypt-key" # 可选
　　openclaw config set feishu.verificationToken "your-verification-token"
　　
　　 事件回调配置
　　在飞书开放平台配置事件订阅：
　　yaml
　　# OpenClaw 飞书配置示例
　　feishu:
　　 appId: "cli_xxxxxx"
　　 appSecret: "xxxxxx"
　　 encryptKey: "xxxxxx"
　　 verificationToken: "xxxxxx"
　　 eventUrl: "/webhook/feishu"
　　
　　启动飞书服务：
　　bash
　　openclaw feishu start
　　
　　 常见问题与解决方案
　　 安装阶段问题
　　1. sharp 依赖安装失败
　　bash
　　# 清理缓存重新安装
　　npm cache clean --force
　　npm uninstall sharp
　　npm install --ignore-scripts=false sharp
　　
　　2. 权限错误（EACCES）
　　bash
　　# 使用 node version manager 或修改 npm 全局目录
　　mkdir ~/.npm-global
　　npm config set prefix '~/.npm-global'
　　export PATH=~/.npm-global/bin:$PATH
　　
　　3. 端口冲突
　　bash
　　# 检查端口占用
　　netstat -an | findstr :3000 # Windows
　　lsof -i :3000 # macOS/Linux
　　# 修改端口配置
　　openclaw config set gateway.port 3001
　　
　　 运行阶段问题
　　1. Gateway 启动失败
　　bash
　　# 检查日志
　　openclaw gateway logs
　　# 重置配置
　　openclaw config reset
　　openclaw init
　　
　　2. 模型认证错误（409/703）
　　bash
　　# 验证 API Key 和 Base URL
　　openclaw config get models.default
　　# 重新配置正确的凭据
　　openclaw config set models.default.apiKey "new-correct-api-key"
　　
　　3. 网络连接问题
　　bash
　　# 测试网络连通性
　　curl -v https://open.bigmodel.cn/api/paas/v4
　　# 配置代理（如需要）
　　openclaw config set network.proxy "http://proxy-server:port"
　　
　　 验证安装结果
　　完成安装后，通过以下步骤验证 OpenClaw 是否正常工作：
　　bash
　　# 检查版本信息
　　openclaw --version
　　# 测试基础功能
　　openclaw status
　　# 运行健康检查
　　openclaw health
　　# 测试 AI 交互
　　openclaw chat "你好，请介绍一下你自己"
　　
　　如果一切正常，应该能看到类似以下的输出：
　　
　　✓ OpenClaw CLI v1.2.0
　　✓ Gateway service: running on port 3000
　　✓ Default model: glm-4-6 (connected)
　　✓ Plugins: feishu, webui (loaded)
　　
　　 进阶配置与优化
　　 性能调优
　　bash
　　# 调整模型上下文窗口
　　openclaw config set models.default.maxTokens 8192
　　# 配置缓存策略
　　openclaw config set cache.enabled true
　　openclaw config set cache.ttl 3600
　　# 启用请求批处理
　　openclaw config set gateway.batchProcessing true
　　
　　 安全配置
　　bash
　　# 设置访问令牌
　　openclaw config set security.apiKeys "your-secure-token"
　　# 启用 CORS
　　openclaw config set security.cors.origin "https://your-domain.com"
　　# 配置速率限制
　　openclaw config set security.rateLimit.enabled true
　　openclaw config set security.rateLimit.windowMs 
　　openclaw config set security.rateLimit.max 100
　　
　　通过以上完整的安装和配置流程，您应该能够在各种平台上成功部署OpenClaw，并根据实际需求进行个性化定制。如果在安装过程中遇到特殊问题，建议查阅官方文档或社区支持资源。