OpenClaw 完整安装指南从入门到精通

📖 导读：OpenClaw 是一个强大的 AI 代理框架，支持多模态交互、技能扩展和多渠道集成。本文将带你从零开始，完成 OpenClaw 的完整安装和配置。

🚀 一、快速开始

如果你已经熟悉技术环境，可以直接执行以下命令快速安装：

1下载安装包

Windows

# PowerShellInvoke-WebRequest -Uri "https://github.com/openclaw/openclaw/releases/latest/download/openclaw-windows.exe" -OutFile "openclaw.exe"

macOS

# Terminalcurl -L https://github.com/openclaw/openclaw/releases/latest/download/openclaw-macos -o openclawchmod +x openclawsudo mv openclaw /usr/local/bin/

Linux

# Terminalcurl -L https://github.com/openclaw/openclaw/releases/latest/download/openclaw-linux -o openclawchmod +x openclawsudo mv openclaw /usr/local/bin/

2安装并验证

# 安装openclaw install# 验证版本openclaw --version# 预期输出：# 🐉 OpenClaw 2026.3.2 (85377a2) | I don't sleep, I just enter low-power mode and dream of clean diffs.

💻 二、系统要求

检查你的系统配置

最低配置

项目	要求
操作系统	Windows 10/11, macOS 10.15+, Linux (Ubuntu 18.04+)
CPU	Intel Core i3 或同等性能
内存	4GB RAM
磁盘空间	2GB 可用空间
网络	稳定互联网连接

项目	要求
操作系统	Windows 11, macOS 12+, Ubuntu 22.04+
CPU	Intel Core i5 或更高
内存	16GB RAM
磁盘空间	10GB SSD
网络	10 Mbps 以上带宽

📦 三、安装 Node.js

OpenClaw 依赖 Node.js 18.x 或更高版本。

推荐使用 nvm（Node Version Manager）管理 Node.js 版本，可以在不同版本间轻松切换。

Windows 安装

方法一：官方安装程序（推荐新手）

访问 Node.js 官网
下载 LTS 版本（推荐 18.x 或 20.x）
双击运行 .msi 安装程序
按照向导完成安装，确保勾选 "Automatically install the necessary tools"

# 验证安装node --versionnpm --version

方法二：使用 nvm-windows（推荐开发者）

# 下载 nvm-windows: # https://github.com/coreybutler/nvm-windows/releases# 运行 nvm-setup.exe 安装# 安装 Node.jsnvm install 20nvm use 20# 验证node --version

macOS 安装

使用 Homebrew（推荐）

# 安装 Homebrew（如未安装）/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"# 安装 Node.jsbrew install node# 验证node --version

Linux 安装

Ubuntu/Debian

# 使用 NodeSource 仓库（推荐）curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -sudo apt-get install -y nodejs# 验证node --versionnpm --version

中国大陆用户提示：使用淘宝镜像加速 npm 下载

# 使用淘宝镜像npm config set registry https://registry.npmmirror.com# 验证npm config get registry

🔧 四、安装 OpenClaw

下载并安装 OpenClaw

从 GitHub Releases 获取最新版本

Windows 安装步骤

# 1. 创建目录New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.openclaw\bin"# 2. 移动文件Move-Item -Path openclaw.exe -Destination "$env:USERPROFILE\.openclaw\bin\openclaw.exe"# 3. 添加到 PATH（永久）[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.openclaw\bin", "User")# 4. 重启终端后，运行安装命令openclaw install

macOS/Linux 安装步骤

# 1. 移动到系统路径sudo mv openclaw /usr/local/bin/# 或移动到用户目录（无需 sudo）mkdir -p ~/.local/binmv openclaw ~/.local/bin/echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrcsource ~/.bashrc# 2. 运行安装命令openclaw install

验证安装

# 查看版本openclaw --version# 查看帮助openclaw --help# 检查系统状态openclaw health

⚙️ 五、初始化配置

运行配置向导

openclaw configure

配置向导会引导你完成以下设置：

认证配置
：选择模型提供商，输入 API 密钥或 OAuth 认证
模型选择
：选择要使用的 AI 模型
工作空间
：设置工作目录
工具权限
：选择工具使用范围（messaging 或 full）
渠道集成
（可选）：配置飞书、企业微信等

配置文件位置

Windows
: C:\Users\<用户名>\.openclaw\openclaw.json
macOS/Linux
: ~/.openclaw/openclaw.json

常用配置命令

# 查看配置文件位置openclaw config file# 获取配置值openclaw config get <配置路径># 设置配置值openclaw config set <配置路径> <值># 验证配置openclaw config validate

🤖 六、配置模型提供商

选择你的 AI 模型

支持多个主流大模型提供商

支持的模型提供商

提供商	Base URL	认证方式
Qwen Portal	https://portal.qwen.ai/v1	OAuth
通义千问	https://coding.dashscope.aliyuncs.com/v1	API Key
智谱 AI	https://open.bigmodel.cn/api/paas/v4/	API Key
Kimi	https://api.moonshot.cn/v1/	API Key

配置 Qwen Portal（推荐）

# 设置 Qwen Portal 提供商openclaw config set models.providers.qwen-portal.baseUrl "https://portal.qwen.ai/v1"openclaw config set models.providers.qwen-portal.apiKey "qwen-oauth"openclaw config set models.providers.qwen-portal.api "openai-completions"# 设置默认模型openclaw config set agents.defaults.model.primary "qwen-portal/coder-model"

配置通义千问

openclaw config set models.providers.dashscope.baseUrl "https://coding.dashscope.aliyuncs.com/v1"openclaw config set models.providers.dashscope.apiKey "<你的 API 密钥>"openclaw config set models.providers.dashscope.api "openai-completions"openclaw config set agents.defaults.model.primary "dashscope/qwen-turbo"

🔐 七、高级配置

环境变量

# 配置文件目录export OPENCLAW_CONFIG_DIR="/path/to/config"# 工作空间目录export OPENCLAW_WORKSPACE="/path/to/workspace"# 缓存目录export OPENCLAW_CACHE_DIR="/path/to/cache"# 日志级别export OPENCLAW_LOG_LEVEL="debug"# 网络超时（毫秒）export OPENCLAW_NETWORK_TIMEOUT="30000"

代理配置

# 设置 HTTP 代理openclaw config set network.proxy.http "http://proxy.example.com:8080"# 设置 HTTPS 代理openclaw config set network.proxy.https "http://proxy.example.com:8080"# 设置不使用代理的地址openclaw config set network.proxy.noProxy "localhost,127.0.0.1"

📝 八、常用命令

命令速查表

收藏这份命令清单，随时查阅

基础命令

# 查看版本openclaw --version# 查看帮助openclaw --help# 查看配置文件位置openclaw config file# 健康检查openclaw health

Gateway 管理

# 启动 Gatewayopenclaw gateway# 停止 Gatewayopenclaw gateway stop# 强制停止openclaw gateway --force# 查看状态openclaw gateway status# 查看日志openclaw logs# 实时查看日志openclaw logs --follow

技能管理

# 列出已安装技能openclaw skills list# 检查技能状态openclaw skills check# 查看技能信息openclaw skills info <技能名称># 使用 ClawHub 搜索技能npx clawhub search <关键词># 安装技能npx clawhub install <技能名称># 更新技能npx clawhub update <技能名称># 卸载技能npx clawhub uninstall <技能名称>

🔧 九、故障排除

1. Gateway 无法启动

症状：

Error: gateway already running (pid <PID>); lock timeout after 5000ms

解决方案：

# 停止现有 Gatewayopenclaw gateway stop# 重新启动openclaw gateway# 或强制重启openclaw gateway --force

2. API 请求限流

症状：

⚠️ API rate limit reached. Please try again later.