openclaw 部署实践指南

# 更新包管理器
sudo apt update
sudo apt upgrade -y
# 安装基础编译工具
sudo apt install -y build-essential cmake git curl wget
# 安装 Python 相关
sudo apt install -y python3 python3-pip python3-venv python3-dev
# 安装其他依赖
sudo apt install -y libssl-dev libffi-dev libxml2-dev libxslt1-dev zlib1g-dev

# 安装基础工具
sudo yum install -y epel-release
sudo yum groupinstall -y "Development Tools"
sudo yum install -y cmake git curl wget
# 安装 Python
sudo yum install -y python3 python3-pip python3-devel
# 安装其他依赖
sudo yum install -y openssl-devel libffi-devel libxml2-devel libxslt-devel zlib-devel

# 安装 Homebrew（如果未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装依赖
brew install cmake git python3 openssl

# 克隆 openclaw 仓库
git clone https://github.com/your-org/openclaw.git
cd openclaw
# 或者使用 SSH 方式
# git clone git@github.com:your-org/openclaw.git

# 创建 Python 虚拟环境
python3 -m venv venv
# 激活虚拟环境
# Linux/macOS
source venv/bin/activate
# Windows
# venv\Scripts\activate

# 升级 pip
pip install --upgrade pip
# 安装项目依赖
pip install -r requirements.txt
# 如果项目有开发依赖
if [ -f requirements-dev.txt ]; then
    pip install -r requirements-dev.txt
fi

# 检查是否有额外的安装脚本
if [ -f scripts/install_deps.sh ]; then
    chmod +x scripts/install_deps.sh
    ./scripts/install_deps.sh
fi

# 复制环境变量配置文件
cp .env.example .env
# 复制应用配置文件
if [ -f config/config.example.yaml ]; then
    cp config/config.example.yaml config/config.yaml
fi

# 应用配置
APP_NAME=openclaw
APP_ENV=production
APP_DEBUG=false
APP_URL=http://localhost:8000
# 数据库配置（根据实际使用的数据库调整）
DB_CONNECTION=sqlite
DB_DATABASE=database/openclaw.db
# 或者使用 MySQL
# DB_CONNECTION=mysql
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=openclaw
# DB_USERNAME=root
# DB_PASSWORD=your_password
# Redis 配置（可选）
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
# 安全配置
APP_KEY=generate_a_secure_random_key_here

# 如果项目使用 Flask/Django 等框架，可能需要生成密钥
python -c "import secrets; print(secrets.token_hex(32))"
# 将生成的密钥填入 APP_KEY

# 创建数据库目录
mkdir -p database
# 初始化数据库
python manage.py migrate  # Django 项目
# 或
flask db upgrade  # Flask 项目
# 或根据项目的实际命令

# 登录 MySQL
mysql -u root -p
# 创建数据库
CREATE DATABASE openclaw CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
# 创建用户并授权
CREATE USER 'openclaw_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON openclaw.* TO 'openclaw_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

# 根据项目框架执行相应的迁移命令
python manage.py migrate  # Django
# 或
flask db upgrade  # Flask
# 或
alembic upgrade head  # SQLAlchemy

# 如果有种子数据
python manage.py loaddata initial_data.json  # Django
# 或
python scripts/seed_data.py  # 自定义脚本

# 启动开发服务器
python manage.py runserver 0.0.0.0:8000  # Django
# 或
flask run --host=0.0.0.0 --port=8000  # Flask
# 或
uvicorn main:app --host 0.0.0.0 --port 8000 --reload  # FastAPI

# 安装 Gunicorn
pip install gunicorn
# 启动服务
gunicorn --workers 4 --bind 0.0.0.0:8000 wsgi:app

# 创建 systemd 服务文件
sudo tee /etc/systemd/system/openclaw.service << EOF
[Unit]
Description=openclaw Web Service
After=network.target
[Service]
User=www-data
Group=www-data
WorkingDirectory=/path/to/openclaw
Environment="PATH=/path/to/openclaw/venv/bin"
ExecStart=/path/to/openclaw/venv/bin/gunicorn --workers 4 --bind unix:/tmp/openclaw.sock wsgi:app
Restart=always
[Install]
WantedBy=multi-user.target
EOF
# 重新加载 systemd
sudo systemctl daemon-reload
# 启动服务
sudo systemctl start openclaw
sudo systemctl enable openclaw

# 构建 Docker 镜像
docker build -t openclaw:latest .
# 运行容器
docker run -d \
  --name openclaw \
  -p 8000:8000 \
  -v $(pwd)/.env:/app/.env \
  openclaw:latest

# 检查服务是否运行
curl -I http://localhost:8000
# 或使用浏览器访问
# http://localhost:8000

# 如果项目有健康检查端点
curl http://localhost:8000/health
# 或
curl http://localhost:8000/api/health

# 查看应用日志
tail -f logs/app.log
# 或使用 systemd 查看
sudo journalctl -u openclaw -f

ERROR: Could not find a version that satisfies the requirement some-package
ERROR: No matching distribution found for some-package

# 升级 pip
pip install --upgrade pip
# 使用国内镜像源
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# 或指定 Python 版本
python3.8 -m pip install -r requirements.txt

OperationalError: (2003, "Can't connect to MySQL server on 'localhost' ([Errno 111] Connection refused)")

# 检查 MySQL 服务状态
sudo systemctl status mysql
# 启动 MySQL 服务
sudo systemctl start mysql
# 检查防火墙设置
sudo ufw allow 3306/tcp
# 验证数据库连接
mysql -u username -p -h localhost

OSError: [Errno 98] Address already in use

# 查找占用端口的进程
sudo lsof -i :8000
# 终止占用进程
sudo kill -9 <PID>
# 或使用其他端口
python manage.py runserver 0.0.0.0:8080

PermissionError: [Errno 13] Permission denied: '/path/to/file'

# 修改目录权限
sudo chown -R $USER:$USER /path/to/openclaw
# 或给特定目录添加写权限
chmod -R 755 database/
chmod -R 755 logs/

KeyError: 'APP_KEY'
或
ImproperlyConfigured: Set the APP_KEY environment variable

# 检查 .env 文件是否存在
ls -la .env
# 检查文件内容
cat .env
# 手动加载环境变量
export $(cat .env | xargs)
# 检查是否安装了 python-dotenv
pip install python-dotenv

openclaw/
├── app/                    # 应用主目录
│   ├── __init__.py
│   ├── models.py          # 数据模型
│   ├── views.py           # 视图函数
│   └── utils.py           # 工具函数
├── config/                # 配置文件
│   ├── config.yaml
│   └── config.example.yaml
├── database/              # 数据库文件
├── logs/                  # 日志目录
├── requirements.txt       # Python 依赖
├── .env.example          # 环境变量模板
├── manage.py             # 管理脚本（Django）
├── wsgi.py               # WSGI 入口
└── README.md             # 项目说明

# 更新代码
git pull origin main
# 更新依赖
pip install -r requirements.txt --upgrade
# 运行测试
pytest tests/
# 备份数据库
cp database/openclaw.db database/openclaw.db.backup.$(date +%Y%m%d)