1430 字
7 分钟
OpenClaw 部署指南
OpenClaw 部署指南
部署架构说明
OpenClaw 采用微服务架构设计,主要包含以下核心组件:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐│ Client Layer │────▶│ Gateway Layer │────▶│ Service Layer ││ (Web/CLI/IDE) │ │ (API Gateway) │ │ (Core Services) │└─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ │ Cache Layer │ │ Storage Layer │ │ (Redis) │ │ (PostgreSQL/S3) │ └─────────────────┘ └─────────────────┘核心组件:
- Gateway:API 网关,负责请求路由、认证、限流
- Core Service:核心业务服务,处理代码生成、理解等逻辑
- Model Engine:模型推理引擎,对接大模型服务
- Database:元数据存储(用户信息、会话记录等)
- Cache:会话缓存、上下文缓存
- Object Storage:存储大文件、训练数据等
前置依赖准备
硬件要求
| 部署规模 | CPU 核心 | 内存 | 存储 |
|---|---|---|---|
| 开发环境 | 4核 | 8GB | 50GB |
| 生产环境(100用户以内) | 8核 | 16GB | 200GB |
| 生产环境(1000用户以内) | 16核 | 32GB | 500GB |
| 企业级 | 32核+ | 64GB+ | 1TB+ |
软件依赖
- Docker 20.10+ 或 Containerd 1.5+
- Docker Compose 2.0+(Docker 部署用)
- Kubernetes 1.22+(K8s 部署用)
- PostgreSQL 13+ 或 MySQL 8.0+
- Redis 6.0+
- Nginx 1.20+(反向代理用)
一、Docker 部署(推荐快速体验)
1. 下载 Docker Compose 配置
mkdir openclaw && cd openclawwget https://github.com/openclaw/openclaw/releases/latest/download/docker-compose.yml2. 配置环境变量
创建 .env 文件:
# 基础配置OPENCLAW_VERSION=latestOPENCLAW_HOST=0.0.0.0OPENCLAW_PORT=8080
# 数据库配置DB_HOST=postgresDB_PORT=5432DB_USER=openclawDB_PASSWORD=your_passwordDB_NAME=openclaw
# Redis 配置REDIS_HOST=redisREDIS_PORT=6379REDIS_PASSWORD=your_redis_password
# 模型配置MODEL_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3MODEL_API_KEY=your_api_keyMODEL_NAME=openclaw-3.5
# 安全配置JWT_SECRET=your_jwt_secret_keyENCRYPTION_KEY=your_encryption_key3. 启动服务
docker-compose up -d4. 验证启动
docker-compose ps看到所有服务状态为 Up 则表示启动成功。
二、二进制部署
1. 下载二进制包
# 下载最新版本wget https://github.com/openclaw/openclaw/releases/latest/download/openclaw-linux-amd64.tar.gz# 或 ARM 版本wget https://github.com/openclaw/openclaw/releases/latest/download/openclaw-linux-arm64.tar.gz
# 解压tar -zxvf openclaw-linux-amd64.tar.gzcd openclaw2. 配置文件
复制配置模板并修改:
cp config.example.toml config.toml编辑 config.toml:
[server]host = "0.0.0.0"port = 8080debug = false
[database]type = "postgres"host = "localhost"port = 5432user = "openclaw"password = "your_password"name = "openclaw"
[redis]host = "localhost"port = 6379password = "your_redis_password"db = 0
[model]endpoint = "https://ark.cn-beijing.volces.com/api/v3"api_key = "your_api_key"model = "openclaw-3.5"
[security]jwt_secret = "your_jwt_secret_key"encryption_key = "your_encryption_key"3. 初始化数据库
./openclaw migrate4. 启动服务
# 直接启动./openclaw start
# 后台运行(使用 systemd)sudo cp openclaw.service /etc/systemd/system/sudo systemctl daemon-reloadsudo systemctl enable openclawsudo systemctl start openclaw5. 查看状态
systemctl status openclaw三、Kubernetes 部署(生产级推荐)
1. 添加 Helm 仓库
helm repo add openclaw https://helm.openclaw.aihelm repo update2. 自定义配置
创建 values.yaml:
# 全局配置global: imageRegistry: docker.io imageTag: latest storageClass: "standard"
# 网关配置gateway: replicas: 2 service: type: LoadBalancer port: 80
# 核心服务配置core: replicas: 3 resources: requests: cpu: "2" memory: "4Gi" limits: cpu: "4" memory: "8Gi"
# 数据库配置postgresql: enabled: true postgresqlUsername: openclaw postgresqlPassword: "your_password" postgresqlDatabase: openclaw persistence: size: 100Gi
# Redis 配置redis: enabled: true architecture: standalone auth: password: "your_redis_password" master: persistence: size: 20Gi
# 模型配置model: endpoint: "https://ark.cn-beijing.volces.com/api/v3" apiKey: "your_api_key" modelName: "openclaw-3.5"
# 安全配置security: jwtSecret: "your_jwt_secret_key" encryptionKey: "your_encryption_key"
# 入口配置ingress: enabled: true hostname: openclaw.yourdomain.com annotations: kubernetes.io/ingress.class: nginx cert-manager.io/cluster-issuer: letsencrypt-prod tls: true3. 部署
helm install openclaw openclaw/openclaw -f values.yaml -n openclaw --create-namespace4. 查看部署状态
kubectl get pods -n openclawkubectl get svc -n openclawkubectl get ingress -n openclaw配置说明
核心配置项
| 配置项 | 说明 | 默认值 |
|---|---|---|
server.host | 服务监听地址 | 0.0.0.0 |
server.port | 服务监听端口 | 8080 |
debug | 调试模式开关 | false |
rate_limit.enabled | 是否启用限流 | true |
rate_limit.requests_per_minute | 每分钟请求限制 | 100 |
context_cache.enabled | 是否启用上下文缓存 | true |
context_cache.ttl | 缓存过期时间(秒) | 3600 |
模型配置
支持对接多种大模型服务:
[model]# 火山引擎方舟provider = "volcengine"endpoint = "https://ark.cn-beijing.volces.com/api/v3"api_key = "your_api_key"model = "openclaw-3.5"
# OpenAI# provider = "openai"# endpoint = "https://api.openai.com/v1"# api_key = "your_openai_key"# model = "gpt-4"
# 本地部署模型# provider = "local"# endpoint = "http://localhost:8000/v1"# model = "qwen-7b-code"验证安装
1. 健康检查
curl http://localhost:8080/health预期响应:
{ "status": "ok", "version": "v1.0.0", "services": { "database": "connected", "redis": "connected", "model": "connected" }}2. 功能测试
curl -X POST http://localhost:8080/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your_api_key" \ -d '{ "messages": [{"role": "user", "content": "写一个Hello World程序"}], "stream": false }'3. Web 界面访问
打开浏览器访问 http://your-server-ip:8080,使用默认账号密码登录:
- 用户名:
admin@example.com - 密码:
admin123
首次登录后请立即修改默认密码!
常见问题排查
1. 服务启动失败
问题: 启动时提示数据库连接失败 排查步骤:
# 检查数据库服务状态systemctl status postgresql# 测试数据库连接psql -h localhost -U openclaw -d openclaw# 查看服务日志journalctl -u openclaw -f2. 模型调用失败
问题: 代码生成请求返回 500 错误 排查步骤:
# 检查模型服务连通性curl https://ark.cn-beijing.volces.com/api/v3/models -H "Authorization: Bearer your_api_key"# 查看模型调用日志grep "model_error" /var/log/openclaw/openclaw.log# 检查 API Key 是否正确3. 性能问题
问题: 响应速度慢 优化建议:
- 增加核心服务副本数
- 启用上下文缓存功能
- 调整模型参数,减少 max_tokens
- 检查网络延迟,建议模型服务和 OpenClaw 部署在同一区域
4. 内存占用过高
问题: 服务占用内存超过限制 解决方法:
- 调整 JVM 或 Go runtime 内存限制
- 减少并发请求数
- 启用连接池限制
- 定期清理过期会话数据
运维建议
- 数据备份:定期备份数据库和配置文件,建议每日备份
- 监控告警:配置 Prometheus + Grafana 监控,设置 CPU、内存、请求量、错误率告警
- 日志管理:集中管理日志,建议使用 ELK 栈或 Loki
- 版本升级:定期升级到最新版本,获取新功能和安全修复
- 安全加固:
- 启用 HTTPS
- 配置防火墙规则,限制管理端口访问
- 定期轮换 API Key 和密码
- 启用访问日志审计
升级指南
Docker 部署升级
docker-compose pulldocker-compose up -d二进制部署升级
# 下载新版本wget https://github.com/openclaw/openclaw/releases/latest/download/openclaw-linux-amd64.tar.gztar -zxvf openclaw-linux-amd64.tar.gz# 停止服务systemctl stop openclaw# 替换二进制文件cp openclaw /usr/local/bin/# 执行数据库迁移openclaw migrate# 启动服务systemctl start openclawKubernetes 部署升级
helm repo updatehelm upgrade openclaw openclaw/openclaw -f values.yaml -n openclaw更多详细信息请参考 官方文档