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) │
└─────────────────┘ └─────────────────┘

核心组件:

  1. Gateway:API 网关,负责请求路由、认证、限流
  2. Core Service:核心业务服务,处理代码生成、理解等逻辑
  3. Model Engine:模型推理引擎,对接大模型服务
  4. Database:元数据存储(用户信息、会话记录等)
  5. Cache:会话缓存、上下文缓存
  6. Object Storage:存储大文件、训练数据等

前置依赖准备#

硬件要求#

部署规模CPU 核心内存存储
开发环境4核8GB50GB
生产环境(100用户以内)8核16GB200GB
生产环境(1000用户以内)16核32GB500GB
企业级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 配置#

Terminal window
mkdir openclaw && cd openclaw
wget https://github.com/openclaw/openclaw/releases/latest/download/docker-compose.yml

2. 配置环境变量#

创建 .env 文件:

# 基础配置
OPENCLAW_VERSION=latest
OPENCLAW_HOST=0.0.0.0
OPENCLAW_PORT=8080
# 数据库配置
DB_HOST=postgres
DB_PORT=5432
DB_USER=openclaw
DB_PASSWORD=your_password
DB_NAME=openclaw
# Redis 配置
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
# 模型配置
MODEL_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3
MODEL_API_KEY=your_api_key
MODEL_NAME=openclaw-3.5
# 安全配置
JWT_SECRET=your_jwt_secret_key
ENCRYPTION_KEY=your_encryption_key

3. 启动服务#

Terminal window
docker-compose up -d

4. 验证启动#

Terminal window
docker-compose ps

看到所有服务状态为 Up 则表示启动成功。

二、二进制部署#

1. 下载二进制包#

Terminal window
# 下载最新版本
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.gz
cd openclaw

2. 配置文件#

复制配置模板并修改:

Terminal window
cp config.example.toml config.toml

编辑 config.toml

[server]
host = "0.0.0.0"
port = 8080
debug = false
[database]
type = "postgres"
host = "localhost"
port = 5432
user = "openclaw"
password = "your_password"
name = "openclaw"
[redis]
host = "localhost"
port = 6379
password = "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. 初始化数据库#

Terminal window
./openclaw migrate

4. 启动服务#

Terminal window
# 直接启动
./openclaw start
# 后台运行(使用 systemd)
sudo cp openclaw.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

5. 查看状态#

Terminal window
systemctl status openclaw

三、Kubernetes 部署(生产级推荐)#

1. 添加 Helm 仓库#

Terminal window
helm repo add openclaw https://helm.openclaw.ai
helm repo update

2. 自定义配置#

创建 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: true

3. 部署#

Terminal window
helm install openclaw openclaw/openclaw -f values.yaml -n openclaw --create-namespace

4. 查看部署状态#

Terminal window
kubectl get pods -n openclaw
kubectl get svc -n openclaw
kubectl 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. 健康检查#

Terminal window
curl http://localhost:8080/health

预期响应:

{
"status": "ok",
"version": "v1.0.0",
"services": {
"database": "connected",
"redis": "connected",
"model": "connected"
}
}

2. 功能测试#

Terminal window
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. 服务启动失败#

问题: 启动时提示数据库连接失败 排查步骤:

Terminal window
# 检查数据库服务状态
systemctl status postgresql
# 测试数据库连接
psql -h localhost -U openclaw -d openclaw
# 查看服务日志
journalctl -u openclaw -f

2. 模型调用失败#

问题: 代码生成请求返回 500 错误 排查步骤:

Terminal window
# 检查模型服务连通性
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. 性能问题#

问题: 响应速度慢 优化建议:

  1. 增加核心服务副本数
  2. 启用上下文缓存功能
  3. 调整模型参数,减少 max_tokens
  4. 检查网络延迟,建议模型服务和 OpenClaw 部署在同一区域

4. 内存占用过高#

问题: 服务占用内存超过限制 解决方法:

  1. 调整 JVM 或 Go runtime 内存限制
  2. 减少并发请求数
  3. 启用连接池限制
  4. 定期清理过期会话数据

运维建议#

  1. 数据备份:定期备份数据库和配置文件,建议每日备份
  2. 监控告警:配置 Prometheus + Grafana 监控,设置 CPU、内存、请求量、错误率告警
  3. 日志管理:集中管理日志,建议使用 ELK 栈或 Loki
  4. 版本升级:定期升级到最新版本,获取新功能和安全修复
  5. 安全加固
    • 启用 HTTPS
    • 配置防火墙规则,限制管理端口访问
    • 定期轮换 API Key 和密码
    • 启用访问日志审计

升级指南#

Docker 部署升级#

Terminal window
docker-compose pull
docker-compose up -d

二进制部署升级#

Terminal window
# 下载新版本
wget https://github.com/openclaw/openclaw/releases/latest/download/openclaw-linux-amd64.tar.gz
tar -zxvf openclaw-linux-amd64.tar.gz
# 停止服务
systemctl stop openclaw
# 替换二进制文件
cp openclaw /usr/local/bin/
# 执行数据库迁移
openclaw migrate
# 启动服务
systemctl start openclaw

Kubernetes 部署升级#

Terminal window
helm repo update
helm upgrade openclaw openclaw/openclaw -f values.yaml -n openclaw

更多详细信息请参考 官方文档

OpenClaw 部署指南
https://blog.debugmy.com/posts/openclaw-deployment-guide/
作者
Junnan Ying
发布于
2026-03-09
许可协议
CC BY-NC-SA 4.0