OpenClaw 本地部署详解：从环境准备到服务启动
本教程属于《OpenClaw 从入门到精通》系列
在上一篇文章中，我们已经介绍了 OpenClaw 的快速上手方法。本文将深入讲解本地部署的完整流程，帮助你在自己的服务器或电脑上稳定运行 OpenClaw。
📋 系统要求
在开始部署之前，请确保你的系统满足以下要求：
| 组件 | 最低版本 | 推荐版本 |
|---|---|---|
| Node.js | 18.x | 22.x |
| pnpm | 7.x | 8.x |
| 内存 | 2GB | 4GB+ |
| 磁盘空间 | 1GB | 5GB+ |
支持的操作系统
- ✅ Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
- ✅ macOS 12+
- ✅ Windows (推荐 WSL2)
🚀 安装方式
OpenClaw 支持多种本地安装方式，下面详细介绍每种方式的特点和适用场景。
方式一：Installer 脚本（推荐）
这是最简单的方式，脚本会自动检测并安装所有依赖：
# Linux/macOS/WSL2
curl -fsSL https://openclaw.ai/install.sh | bash
Windows PowerShell 用户：
iwr -useb https://openclaw.ai/install.ps1 | iex
安装过程说明：
- 自动检测 Node.js，如未安装则提示安装
- 下载并安装 OpenClaw CLI
- 初始化配置目录
~/.openclaw - 启动 Gateway 服务
如需跳过交互式引导：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
方式二：npm/pnpm 安装
如果你已经安装了 Node.js 22+，可以使用包管理器：
# 使用 pnpm（推荐）
pnpm add -g openclaw@latest
pnpm approve-builds -g # 批准构建脚本
# 或使用 npm
npm install -g openclaw@latest
安装完成后初始化：
openclaw onboard --install-daemon
常见问题处理：
如果遇到 sharp 构建错误：
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
方式三：从源码安装
适合开发者或需要定制化安装的场景：
# 1. 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw
# 2. 安装依赖
pnpm install
pnpm ui:build
pnpm build
# 3. 链接 CLI
pnpm link --global
# 4. 启动服务
openclaw onboard --install-daemon
⚙️ 目录结构说明
安装完成后，OpenClaw 会在用户主目录下创建以下结构：
~/.openclaw/
├── config.yaml # 主配置文件
├── memory/ # 记忆存储
│ └── *.md
├── nodes/ # 配对的设备节点
├── skills/ # 已安装的技能
├── workspace/ # 工作区文件
│ ├── AGENTS.md
│ ├── MEMORY.md
│ ├── SOUL.md
│ ├── TOOLS.md
│ └── USER.md
└── state.json # 运行状态
🔧 核心配置
配置文件位置
主配置文件位于 ~/.openclaw/config.yaml：
# AI 提供商配置
ai:
provider: "anthropic" # 可选: openai, anthropic, google
model: "claude-sonnet-4-20250514"
apiKey: "${ANTHROPIC_API_KEY}" # 建议使用环境变量
# Gateway 服务配置
gateway:
host: "0.0.0.0"
port: 18789
auth:
enabled: true
username: "admin"
password: "${GATEWAY_PASSWORD}"
# 消息渠道配置
channels:
telegram:
enabled: false
discord:
enabled: false
# 心跳任务配置
heartbeat:
enabled: true
interval: 3600 # 秒
# 记忆系统配置
memory:
enabled: true
type: "file" # 或 "sqlite"
环境变量
推荐使用环境变量存储敏感信息：
# 在 ~/.bashrc 或 ~/.zshrc 中添加
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GATEWAY_PASSWORD="your-secure-password"
🎯 服务管理
启动服务
# 启动 Gateway
openclaw gateway start
# 指定端口
openclaw gateway start --port 8080
# 后台运行
openclaw gateway start --daemon
查看状态
# 查看服务状态
openclaw status
# 运行健康检查
openclaw doctor
停止服务
# 停止 Gateway
openclaw gateway stop
🔐 安全建议
1. 配置防火墙
# Ubuntu/Debian
sudo ufw allow 18789/tcp
sudo ufw enable
# CentOS
sudo firewall-cmd --permanent --add-port=18789/tcp
sudo firewall-cmd --reload
2. 使用 Nginx 反向代理（可选）
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://127.0.0.1:18789;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
3. 启用 HTTPS（推荐）
使用 Certbot 配置 Let’s Encrypt 免费证书：
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
📊 性能优化
1. 内存优化
# config.yaml
gateway:
maxMemory: "2gb"
ai:
# 降低上下文长度可减少内存使用
maxTokens: 4096
2. 磁盘清理
定期清理日志和缓存：
# 清理旧日志
openclaw gateway logs --clean
# 清理缓存
rm -rf ~/.openclaw/cache/*
3. 自动更新
配置自动更新（谨慎使用）：
# 设置每周自动检查更新
openclaw update --auto --schedule "0 2 * * 0"
🩺 故障排查
常见问题
Q1: 端口被占用
# 查找占用端口的进程
lsof -i :18789
# 或修改端口
openclaw gateway start --port 3001
Q2: Node.js 版本过低
# 使用 nvm 管理 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22
Q3: AI API 调用失败
- 检查 API Key 配置是否正确
- 确认 API 余额充足
- 验证网络能访问 AI 服务
Q4: 服务启动后无法访问
- 检查防火墙设置
- 确认绑定地址为
0.0.0.0而非127.0.0.1 - 查看日志：
openclaw gateway logs
✅ 验证清单
部署完成后，请确认：
- OpenClaw CLI 已正确安装
- Gateway 服务正常运行
-
openclaw status显示健康状态 -
openclaw doctor无错误警告 - 配置文件已正确设置
- 防火墙已正确配置（如果需要外网访问）
📞 下一步
本地部署完成后，你可以继续学习：
📚 参考资料
本教程由 AI 自动生成并发布