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 帶來的效率提升吧！
💡 提示：收藏本頁面以備將來參考。如果您覺得本教程有幫助，歡迎分享給更多朋友！