OpenClaw 完整安装教程：Docker 部署与配置详解（2026最新版）
在准备好您的服务器（VPS）之后，现在我们将进入核心环节——安装与配置 OpenClaw。本教程将带您从零开始，完成 OpenClaw 的完整部署流程。
当前最主流、最稳定且不易踩坑的安装方式是使用 Docker 进行容器化部署。Docker 的优势在于：
- 📦 环境隔离：避免依赖冲突，保证系统清洁
- 🔄 易于更新：一行命令即可升级到最新版本
- 💾 数据持久化：配置文件和数据独立存储，重装不丢失
- 🚀 快速部署：从空白系统到运行只需 5 分钟
- 🌐 跨平台兼容：Linux、macOS、Windows 均可使用
⚠️ 前置条件：如果您还未配置好服务器，请先查阅：VPS 环境搭建与准备。
目录
1. 安装前的系统检查
在开始安装之前，我们需要确认系统满足基本要求。
1.1 最低系统要求
| 组件 | 最低要求 | 推荐配置 |
|---|---|---|
| CPU | 1 核 | 2 核及以上 |
| 内存 | 1 GB | 2 GB 及以上 |
| 存储空间 | 10 GB | 20 GB SSD |
| 操作系统 | Ubuntu 20.04+ / Debian 11+ | Ubuntu 22.04 LTS |
| 网络 | 稳定的互联网连接 | 带宽 ≥ 10 Mbps |
1.2 检查系统版本
登录到您的 VPS，执行以下命令查看系统信息：
bash
# 查看操作系统版本
cat /etc/os-release
# 查看内核版本
uname -r
# 查看系统架构（应为 x86_64 或 aarch64）
uname -m
# 查看可用内存
free -h
# 查看磁盘空间
df -h1.3 确认 Docker 安装状态
执行以下命令检查 Docker 和 Docker Compose 是否已安装：
bash
# 检查 Docker 版本
docker --version
# 期望输出：Docker version 24.x.x, build xxxxxxx
# 检查 Docker Compose 版本
docker compose version
# 期望输出：Docker Compose version v2.x.x
# 检查 Docker 服务状态
systemctl status docker
# 应该显示 active (running)如果未安装 Docker，请继续下一步。
2. Docker 环境准备
2.1 一键安装 Docker
我们推荐使用官方提供的便捷安装脚本：
bash
# 下载并执行 Docker 官方安装脚本
curl -fsSL https://get.docker.com | bash -s docker
# 或者使用国内镜像加速（适用于中国大陆用户）
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun2.2 配置 Docker 开机自启
bash
# 设置 Docker 开机自动启动
sudo systemctl enable docker
# 启动 Docker 服务
sudo systemctl start docker
# 验证 Docker 是否正常运行
sudo docker run hello-world如果看到 "Hello from Docker!" 的欢迎信息，说明 Docker 安装成功！
2.3 配置 Docker 镜像加速器（可选但强烈推荐）
对于中国大陆用户，配置镜像加速器可以显著提升拉取速度：
bash
# 创建或编辑 Docker 配置文件
sudo mkdir -p /etc/docker
sudo nano /etc/docker/daemon.json添加以下内容（选择适合您的镜像源）：
json
{
"registry-mirrors": [
"https://docker.m.daocloud.io",
"https://huecker.io",
"https://dockerhub.timeweb.cloud",
"https://noohub.ru"
]
}保存后重启 Docker：
bash
sudo systemctl daemon-reload
sudo systemctl restart docker2.4 将当前用户加入 docker 组（避免每次使用 sudo）
bash
# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER
# 使更改生效（需要重新登录 SSH）
exit
# 然后重新连接 SSH3. 使用 Docker Compose 部署 OpenClaw
3.1 创建项目目录
我们需要为 OpenClaw 创建一个专有的工作目录，便于数据持久化和后期维护管理。
bash
# 创建并进入目录
mkdir -p /opt/openclaw
cd /opt/openclaw
# 创建必要的子目录
mkdir -p data config logs
# 设置合适的权限
chmod -R 755 /opt/openclaw目录结构说明：
/opt/openclaw/
├── docker-compose.yml # Docker Compose 配置文件
├── .env # 环境变量文件（稍后创建）
├── data/ # 数据存储目录
│ ├── database/ # 数据库文件
│ └── uploads/ # 上传的文件
├── config/ # 配置文件目录
│ ├── settings.yaml # 主配置文件
│ └── plugins/ # 插件配置
└── logs/ # 日志目录
├── access.log # 访问日志
└── error.log # 错误日志3.2 创建环境变量文件
为了更好地管理敏感信息（如 API 密钥），我们使用 .env 文件：
bash
nano .env添加以下内容（请根据实际情况修改）：
bash
# OpenClaw 基础配置
TZ=Asia/Shanghai
CLAW_ENV=production
OPENCLAW_PORT=8080
# AI 模型 API 密钥（根据需要填写）
OPENAI_API_KEY=sk-your-openai-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here
GOOGLE_API_KEY=your-google-key-here
# 数据库配置（如果使用外部数据库）
# DB_HOST=localhost
# DB_PORT=5432
# DB_USER=openclaw
# DB_PASSWORD=your-strong-password
# 管理员账户（首次启动时设置）
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@example.com
# ADMIN_PASSWORD 将在首次启动时通过交互式设置⚠️ 安全提示：
- 永远不要将
.env文件提交到版本控制系统- 使用强密码并定期更换
- 考虑使用密钥管理服务（如 HashiCorp Vault）存储敏感信息
添加 .env 到 .gitignore（如果初始化了 git）：
bash
echo ".env" >> .gitignore3.3 编写 docker-compose.yml
使用 nano 或者 vim 编辑器，创建 docker-compose.yml 文件：
bash
nano docker-compose.yml将以下内容粘贴进去：
yaml
version: '3.8'
services:
openclaw:
image: openclaw/core:latest
container_name: openclaw
restart: unless-stopped
ports:
- '${OPENCLAW_PORT:-8080}:8080'
environment:
- TZ=${TZ:-Asia/Shanghai}
- CLAW_ENV=${CLAW_ENV:-production}
- OPENAI_API_KEY=${OPENAI_API_KEY:-}
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
- GOOGLE_API_KEY=${GOOGLE_API_KEY:-}
- MAX_CONCURRENT_TASKS=10
- MEMORY_LIMIT=2048M
- LOG_LEVEL=info
volumes:
- ./data:/app/data:rw
- ./config:/app/config:rw
- ./logs:/app/logs:rw
networks:
- openclaw-network
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
deploy:
resources:
limits:
cpus: '2.0'
memory: 2G
reservations:
cpus: '0.5'
memory: 512M
labels:
- "com.openclaw.description=OpenClaw AI Agent Platform"
- "com.openclaw.version=latest"
networks:
openclaw-network:
driver: bridge
name: openclaw-network配置详解：
| 配置项 | 说明 | 默认值 |
|---|---|---|
restart: unless-stopped | 容器退出时自动重启，除非手动停止 | - |
ports | 端口映射，格式：主机端口:容器端口 | 8080:8080 |
TZ | 时区设置 | Asia/Shanghai |
MAX_CONCURRENT_TASKS | 最大并发任务数 | 10 |
MEMORY_LIMIT | 内存限制 | 2048M |
volumes | 数据卷挂载，确保持久化 | - |
healthcheck | 健康检查配置 | 每 30 秒检查一次 |
deploy.resources | 资源限制和预留 | CPU 2核，内存 2G |
粘贴完成后，按下 Ctrl + O 保存，回车确认，然后按下 Ctrl + X 退出编辑器。
3.4 验证配置文件
在启动之前，验证配置文件语法是否正确：
bash
# 验证 docker-compose.yml 语法
docker compose config
# 如果没有错误，会输出完整的配置信息
# 如果有错误，会根据提示修复3.5 启动服务
在上一步创建的 /opt/openclaw 目录下，运行以下命令启动服务：
bash
# 后台启动服务
docker compose up -d
# 实时查看启动日志（按 Ctrl+C 退出日志查看）
docker compose logs -f首次启动过程：
- Docker 会从镜像仓库拉取 OpenClaw 镜像（约 200-500MB）
- 创建并配置容器
- 初始化数据库和配置文件
- 启动 Web 服务
整个过程通常需要 2-5 分钟，取决于网络速度。
3.6 验证服务状态
bash
# 查看容器运行状态
docker ps
# 期望输出类似：
# CONTAINER ID IMAGE STATUS PORTS NAMES
# abc123def456 openclaw/core:latest Up 2 minutes 0.0.0.0:8080->8080/tcp openclaw
# 检查容器日志
docker logs openclaw
# 查看资源使用情况
docker stats openclaw如果容器状态显示为 Up 且没有持续重启，说明启动成功！
3.7 常用 Docker 命令速查
bash
# 停止服务
docker compose down
# 重启服务
docker compose restart
# 查看实时日志
docker compose logs -f --tail=100
# 进入容器内部（调试用）
docker exec -it openclaw /bin/bash
# 更新到最新版本
docker compose pull
docker compose up -d
# 清理未使用的镜像和容器
docker system prune -a
# 备份数据卷
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz data/ config/4. 高级配置选项
4.1 使用反向代理（Nginx）
如果您计划通过域名访问，建议配置 Nginx 反向代理。详见进阶教程。
4.2 配置 HTTPS（SSL/TLS）
生产环境强烈建议启用 HTTPS。可以使用 Let's Encrypt 免费证书：
bash
# 安装 certbot
sudo apt install certbot python3-certbot-nginx -y
# 获取证书（需要先配置好 Nginx）
sudo certbot --nginx -d your-domain.com4.3 多实例部署
如果需要运行多个 OpenClaw 实例（例如开发环境和生产环境）：
bash
# 创建不同的目录
mkdir -p /opt/openclaw-dev
mkdir -p /opt/openclaw-prod
# 在每个目录中使用不同的端口
cd /opt/openclaw-dev
# 修改 .env 文件：OPENCLAW_PORT=8081
cd /opt/openclaw-prod
# 修改 .env 文件：OPENCLAW_PORT=80804.4 集成外部数据库
对于生产环境，建议使用外部数据库而非内置 SQLite：
yaml
services:
openclaw:
# ... 其他配置 ...
environment:
- DB_TYPE=postgresql
- DB_HOST=db
- DB_PORT=5432
- DB_NAME=openclaw
- DB_USER=openclaw
- DB_PASSWORD=${DB_PASSWORD}
depends_on:
db:
condition: service_healthy
db:
image: postgres:15-alpine
container_name: openclaw-db
restart: unless-stopped
environment:
- POSTGRES_DB=openclaw
- POSTGRES_USER=openclaw
- POSTGRES_PASSWORD=${DB_PASSWORD}
volumes:
- ./postgres-data:/var/lib/postgresql/data
networks:
- openclaw-network
healthcheck:
test: ["CMD-SHELL", "pg_isready -U openclaw"]
interval: 10s
timeout: 5s
retries: 55. 基础后台初始配置
如果一切正常运行，OpenClaw 默认会在本机的 8080 端口开放其 Web 管理面板。
5.1 访问 Web 界面
打开您的浏览器，访问：
http://您的VPS_IP:8080例如：http://123.45.67.89:8080
5.2 首次设置向导
根据向导提示，您需要完成以下步骤：
步骤 1：创建管理员账户
- 用户名：建议使用复杂用户名（不要使用 admin）
- 邮箱：用于接收通知和重置密码
- 密码：至少 12 位，包含大小写字母、数字和特殊字符
🔐 安全建议：
- 启用双因素认证（2FA）
- 使用密码管理器生成和存储密码
- 定期更换密码
步骤 2：配置 AI 模型 API
进入「设置中心」→「AI 模型配置」，填写您需要的 API 密钥：
OpenAI GPT：
- API Key:
sk-xxxxxxxxxxxxxxxxxxxx - 模型选择：gpt-4-turbo、gpt-3.5-turbo
- 温度参数：0.7（平衡创造性和准确性）
Anthropic Claude：
- API Key:
sk-ant-xxxxxxxxxxxxxxxxxxxx - 模型选择：claude-3-opus、claude-3-sonnet
Google Gemini：
- API Key:
xxxxxxxxxxxxxxxxxxxx - 模型选择：gemini-pro、gemini-ultra
国产模型：
- 通义千问、文心一言等（需配置对应的 API 端点）
💡 提示：您可以同时配置多个模型，OpenClaw 会根据任务类型自动选择最合适的模型。
步骤 3：连接通讯平台
根据您的使用需求，配置相应的集成：
- 微信：扫码绑定个人号或企业微信
- Telegram：输入 Bot Token
- Discord：配置 Bot 和应用权限
- 飞书/钉钉：配置企业应用凭证
步骤 4：测试连接
点击「测试连接」按钮，确保所有配置正确无误。
5.3 创建第一个自动化任务
配置完成后，让我们创建一个简单的测试任务：
- 进入「工作流」→「新建工作流」
- 触发器选择：定时任务（Cron）
- 设置时间：每天早上 8:00
- 动作：发送问候消息
- 保存并启用
6. 防火墙与安全设置
6.1 配置 UFW 防火墙
如果您无法访问网页配置界面，请检查服务器防火墙设置。
以 Ubuntu UFW 为例：
bash
# 安装 UFW（如果未安装）
sudo apt install ufw -y
# 放行 SSH 端口（重要！否则会被锁在外面）
sudo ufw allow 22/tcp
# 放行 OpenClaw 端口
sudo ufw allow 8080/tcp
# 如果配置了 HTTPS，放行 443 端口
sudo ufw allow 443/tcp
# 启用防火墙
sudo ufw enable
# 查看防火墙状态
sudo ufw status verbose6.2 云服务器安全组配置
如果使用的是阿里云、腾讯云、AWS 等云服务提供商，务必前往网页端控制台配置安全组：
阿里云 ECS：
- 登录阿里云控制台
- 进入「云服务器 ECS」→「实例」
- 找到您的实例，点击「更多」→「网络和安全组」→「安全组配置」
- 点击「配置规则」→「入方向」→「手动添加」
- 添加规则：
- 协议类型：TCP
- 端口范围：8080/8080
- 授权对象：0.0.0.0/0（或指定 IP）
- 优先级：1
- 策略：允许
腾讯云 CVM：
- 登录腾讯云控制台
- 进入「云服务器」→「安全组」
- 找到关联的安全组，点击「修改规则」
- 添加入站规则，放行 8080 端口
AWS EC2：
- 登录 AWS Console
- 进入「EC2」→「Security Groups」
- 编辑入站规则，添加自定义 TCP 规则，端口 8080
6.3 增强安全建议
bash
# 1. 禁用 root 远程登录
sudo nano /etc/ssh/sshd_config
# 修改：PermitRootLogin no
# 2. 使用密钥认证替代密码
ssh-keygen -t ed25519 -C "your_email@example.com"
ssh-copy-id user@your-server-ip
# 3. 安装 fail2ban 防止暴力破解
sudo apt install fail2ban -y
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
# 4. 定期更新系统
sudo apt update && sudo apt upgrade -y
# 5. 配置自动安全更新
sudo apt install unattended-upgrades -y
sudo dpkg-reconfigure -plow unattended-upgrades7. 常见问题与故障排查
问题 1：容器启动后立即退出
症状：docker ps 看不到容器，或状态为 Exited
解决方案：
bash
# 查看详细日志
docker logs openclaw
# 常见原因：
# 1. 端口被占用：lsof -i :8080
# 2. 配置文件错误：检查 docker-compose.yml 语法
# 3. 权限问题：chmod -R 755 data/ config/
# 4. 内存不足：free -h，考虑升级配置问题 2：无法访问 Web 界面
症状：浏览器显示 "无法连接" 或 "连接超时"
排查步骤：
bash
# 1. 检查容器是否运行
docker ps | grep openclaw
# 2. 检查端口监听
sudo netstat -tlnp | grep 8080
# 3. 检查防火墙
sudo ufw status
# 4. 测试本地连接
curl http://localhost:8080
# 5. 检查云服务器安全组（见上文 6.2 节）问题 3：API 密钥无效
症状：Web 界面提示 "API Key invalid" 或 "Authentication failed"
解决方案：
- 确认 API 密钥正确复制，没有多余空格
- 检查 API 账户余额是否充足
- 验证 API 密钥权限是否足够
- 尝试在容器中测试：bash
docker exec -it openclaw curl -H "Authorization: Bearer YOUR_KEY" https://api.openai.com/v1/models
问题 4：数据库连接失败
症状：日志中出现 "Database connection refused"
解决方案：
bash
# 检查数据库服务状态
docker ps | grep db
# 测试数据库连接
docker exec -it openclaw-db psql -U openclaw -d openclaw
# 检查网络连接
docker network inspect openclaw-network问题 5：性能缓慢
症状：响应时间长，任务执行慢
优化方案：
bash
# 1. 监控资源使用
docker stats openclaw
# 2. 增加资源限制（修改 docker-compose.yml）
deploy:
resources:
limits:
cpus: '4.0'
memory: 4G
# 3. 优化数据库
# 如果使用 SQLite，考虑迁移到 PostgreSQL
# 4. 启用缓存
# 在配置文件中启用 Redis 缓存
# 5. 减少并发任务数
# MAX_CONCURRENT_TASKS=5问题 6：如何备份和恢复
备份：
bash
# 停止服务
docker compose down
# 备份数据
tar -czf openclaw-backup-$(date +%Y%m%d-%H%M%S).tar.gz \
data/ config/ .env docker-compose.yml
# 启动服务
docker compose up -d恢复：
bash
# 停止服务
docker compose down
# 解压备份
tar -xzf openclaw-backup-YYYYMMDD-HHMMSS.tar.gz
# 启动服务
docker compose up -d问题 7：如何更新到最新版本
bash
# 方法一：Docker Compose
cd /opt/openclaw
docker compose pull
docker compose up -d
# 方法二：手动更新
docker stop openclaw
docker rm openclaw
docker pull openclaw/core:latest
docker compose up -d
# 验证更新
docker logs openclaw | grep version⚠️ 重要：更新前务必备份数据！
8. 性能优化建议
8.1 系统级优化
bash
# 1. 调整文件系统参数
sudo nano /etc/sysctl.conf
# 添加：
# fs.inotify.max_user_watches=524288
# fs.inotify.max_user_instances=512
# 2. 优化网络栈
sudo sysctl -w net.core.somaxconn=65535
sudo sysctl -w net.ipv4.tcp_max_syn_backlog=65535
# 3. 使用 SSD 存储
# 确保数据目录位于 SSD 上以获得更好的 I/O 性能8.2 Docker 优化
yaml
# 在 docker-compose.yml 中添加
deploy:
resources:
limits:
cpus: '2.0'
memory: 2G
reservations:
cpus: '0.5'
memory: 512M
# 使用构建缓存
docker build --cache-from openclaw/core:latest8.3 数据库优化
sql
-- 如果使用 PostgreSQL，执行以下优化
CREATE INDEX idx_tasks_status ON tasks(status);
CREATE INDEX idx_tasks_created_at ON tasks(created_at);
VACUUM ANALYZE;8.4 缓存策略
yaml
# 启用 Redis 缓存
services:
redis:
image: redis:7-alpine
container_name: openclaw-redis
command: redis-server --maxmemory 512mb --maxmemory-policy allkeys-lru
volumes:
- ./redis-data:/data总结与下一步
恭喜！您已经成功完成了 OpenClaw 的安装和基础配置。现在您的 AI 智能体平台已经就绪，可以开始探索强大的自动化功能了。
✅ 已完成的工作
🎯 接下来的步骤
探索高级功能 - 学习如何：
- 绑定域名并配置 HTTPS
- 使用 Nginx 反向代理
- 创建自定义工作流和快捷指令
- 优化并发性能和资源管理
阅读官方文档 - 深入了解：
- 完整的 API 参考
- 插件开发指南
- 最佳实践和案例研究
加入社区 - 与其他用户交流：
- 分享您的工作流
- 获取技术支持
- 了解最新动态
📚 相关资源
💬 获取帮助
遇到问题不要担心，有多种渠道可以获得帮助：
- 📖 文档：查阅官方文档
- 💬 社区论坛：在社区中提问
- 🐛 GitHub Issues：报告 Bug 或请求新功能
- 📧 邮件支持：发送问题至 support@openclaw.dev
🎉 祝贺您！ 现在您已经拥有自己的 AI 智能体平台。开始创建您的第一个自动化工作流，体验 OpenClaw 带来的效率提升吧！
💡 提示：收藏本页面以备将来参考。如果您觉得本教程有帮助，欢迎分享给更多朋友！