OpenClaw 完整安装指南从入门到精通
·
📖 导读：OpenClaw 是一个强大的 AI 代理框架，支持多模态交互、技能扩展和多渠道集成。本文将带你从零开始，完成 OpenClaw 的完整安装和配置。
目录
🚀 一、快速开始
如果你已经熟悉技术环境，可以直接执行以下命令快速安装：
1.下载安装包
Windows
# PowerShell
Invoke-WebRequest -Uri "https://github.com/openclaw/openclaw/releases/latest/download/openclaw-windows.exe" -OutFile "openclaw.exe"macOS
# Terminal
curl -L https://github.com/openclaw/openclaw/releases/latest/download/openclaw-macos -o openclaw
chmod +x openclaw
sudo mv openclaw /usr/local/bin/Linux
# Terminal
curl -L https://github.com/openclaw/openclaw/releases/latest/download/openclaw-linux -o openclaw
chmod +x openclaw
sudo 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 --version
npm --version方法二：使用 nvm-windows（推荐开发者）
# 下载 nvm-windows:
# https://github.com/coreybutler/nvm-windows/releases
# 运行 nvm-setup.exe 安装
# 安装 Node.js
nvm install 20
nvm use 20
# 验证
node --versionmacOS 安装
使用 Homebrew（推荐）
# 安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装 Node.js
brew install node
# 验证
node --versionLinux 安装
Ubuntu/Debian
# 使用 NodeSource 仓库（推荐）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# 验证
node --version
npm --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 installmacOS/Linux 安装步骤
# 1. 移动到系统路径
sudo mv openclaw /usr/local/bin/
# 或移动到用户目录（无需 sudo）
mkdir -p ~/.local/bin
mv openclaw ~/.local/bin/
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.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 healthGateway 管理
# 启动 Gateway
openclaw gateway
# 停止 Gateway
openclaw 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解决方案：
# 停止现有 Gateway
openclaw gateway stop
# 重新启动
openclaw gateway
# 或强制重启
openclaw gateway --force2. API 请求限流
症状：
⚠️ API rate limit reached. Please try again later.解决方案：
- 等待几分钟后重试
- 降低请求频率
- 升级 API 套餐
- 使用多个 API 密钥轮换
3. 权限错误
症状：
Error: EPERM: operation not permittedWindows 解决方案：
# 以管理员身份运行 PowerShell
icacls "C:\Users\<用户名>\.openclaw" /grant Administrators:FmacOS/Linux 解决方案：
# 修改权限
chmod -R 755 ~/.openclaw4. Node.js 版本过低
# 检查当前版本
node --version
# 使用 nvm 升级
nvm install 20
nvm use 20
nvm alias default 20🌟 十、最佳实践
✨最佳实践建议
让你的 OpenClaw 运行更安全、更高效
安全建议
- API 密钥保护：不要在代码中硬编码 API 密钥，使用环境变量存储
- 权限控制：遵循最小权限原则，开发环境使用 messaging 权限
- 网络安全：使用 HTTPS 加密通信，配置防火墙规则
- 定期轮换：定期更换 API 密钥
性能优化
- 模型选择：根据任务复杂度选择合适的模型
- 缓存策略：启用响应缓存，设置合理的缓存过期时间
- 资源管理：控制并发请求数量，使用连接池
开发建议
- 版本控制：使用 Git 管理配置文件
- 环境隔离：为不同环境创建独立配置文件
- 测试验证：定期测试配置，验证 API 连接
监控建议
- 日志管理：定期检查日志，配置日志轮转
- 性能监控：监控 API 使用量，跟踪响应时间
- 告警设置：配置错误告警，设置用量告警
📖 资源链接
官方文档：docs.openclaw.ai
GitHub 仓库：github.com/openclaw/openclaw
技能市场：clawhub.com
社区支持：discord.gg/openclaw
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
8
0- 0
已为社区贡献1条内容
所有评论(0)