小龙虾openclaw Docker 生产环境详细部署教程

生产环境准备

服务器要求

资源 最低配置 推荐配置 生产环境
CPU 1核 2核 4核+
内存 1GB 2GB 4GB+
存储 10GB 20GB 50GB+
网络 1Mbps 10Mbps 100Mbps+

系统优化

1. 优化Docker配置

编辑 /etc/docker/daemon.json

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "storage-driver": "overlay2",
  "live-restore": true,
  "max-concurrent-downloads": 10,
  "max-concurrent-uploads": 10
}

重启Docker:

sudo systemctl restart docker

2. 优化系统参数

编辑 /etc/sysctl.conf

# 网络优化
net.core.somaxconn = 1024
net.ipv4.tcp_max_syn_backlog = 2048
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_fin_timeout = 30

# 文件描述符
fs.file-max = 65535

应用配置:

sudo sysctl -p

3. 增加文件描述符限制

编辑 /etc/security/limits.conf

* soft nofile 65536
* hard nofile 65536
* soft nproc 65536
* hard nproc 65536

🔒 安全配置

1. 使用只读配置文件

# 创建配置文件
cat > openclaw.json << 'EOF'
{
  "providers": {
    "bailian": {
      "apiKey": "YOUR_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen-turbo"
      }
    }
  }
}
EOF

# 设置权限
chmod 600 openclaw.json

2. 使用环境变量存储敏感信息

创建 .env 文件:

# API配置
OPENCLAW_API_KEY=YOUR_API_KEY

# 安全配置
OPENCLAW_ENABLE_TELEMETRY=false
OPENCLAW_LOG_LEVEL=warn

设置权限:

chmod 600 .env

3. 使用非root用户

# 创建非root用户
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -u 1000:1000 \
  -v $(pwd)/data:/home/openclaw/.openclaw \
  openclaw/openclaw:latest

4. 限制容器资源

# 启动容器(限制资源)
docker run -d \
  --name openclaw \
  --cpus="2" \
  --memory="2g" \
  --memory-swap="2g" \
  --pids-limit 100 \
  -p 18789:18789 \
  -v $(pwd)/data:/home/openclaw/.openclaw \
  openclaw/openclaw:latest

5. 使用Docker Compose生产配置

创建 docker-compose.prod.yml

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    volumes:
      - ./openclaw.json:/home/openclaw/.openclaw/openclaw.json:ro
      - ./data:/home/openclaw/.openclaw/data
    environment:
      - OPENCLAW_LOG_LEVEL=warn
      - OPENCLAW_ENABLE_TELEMETRY=false
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    networks:
      - openclaw-network

networks:
  openclaw-network:
    driver: bridge

启动:

# 启动生产环境
docker-compose -f docker-compose.prod.yml up -d

# 查看状态
docker-compose -f docker-compose.prod.yml ps

6. 使用HTTPS(Nginx反向代理)

获取SSL证书

使用Let’s Encrypt:

# 安装certbot
sudo apt install -y certbot python3-certbot-nginx

# 获取证书
sudo certbot certonly --standalone -d openclaw.example.com

配置Nginx

创建 nginx.conf

server {
    listen 80;
    server_name openclaw.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name openclaw.example.com;

    ssl_certificate /etc/letsencrypt/live/openclaw.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openclaw.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://openclaw:18789;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
    }

    # 限制请求大小
    client_max_body_size 10M;
}

启动Nginx

# 启动OpenClaw
docker run -d \
  --name openclaw \
  --network openclaw-network \
  -p 18789:18789 \
  -v $(pwd)/data:/home/openclaw/.openclaw \
  openclaw/openclaw:latest

# 启动Nginx
docker run -d \
  --name nginx \
  --network openclaw-network \
  -p 80:80 \
  -p 443:443 \
  -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro \
  -v /etc/letsencrypt:/etc/letsencrypt:ro \
  nginx:alpine

⚡ 性能优化

1. 使用多阶段构建

创建 Dockerfile

# 构建阶段
FROM node:22-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

# 运行阶段
FROM node:22-alpine AS runner

WORKDIR /app

# 复制构建产物
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

# 使用非root用户
RUN addgroup -g 1001 -S nodejs
RUN adduser -S openclaw -u 1001
USER openclaw

EXPOSE 18789

CMD ["node", "dist/index.js"]

2. 优化日志配置

# 启动容器(限制日志大小)
docker run -d \
  --name openclaw \
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  -p 18789:18789 \
  openclaw/openclaw:latest

3. 使用缓存优化

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    volumes:
      - ./data:/home/openclaw/.openclaw/data
      - ./cache:/home/openclaw/.cache
    environment:
      - NODE_ENV=production
      - CACHE_ENABLED=true

4. 使用Redis缓存(可选)

version: '3.8'

services:
  redis:
    image: redis:alpine
    container_name: redis
    command: redis-server --appendonly yes
    volumes:
      - ./redis-data:/data
    restart: unless-stopped

  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    depends_on:
      - redis
    ports:
      - "18789:18789"
    environment:
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    restart: unless-stopped

🔁 高可用部署

1. 使用负载均衡

version: '3.8'

services:
  nginx:
    image: nginx:alpine
    container_name: nginx
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - openclaw1
      - openclaw2

  openclaw1:
    image: openclaw/openclaw:latest
    container_name: openclaw1
    volumes:
      - ./data1:/home/openclaw/.openclaw
    restart: unless-stopped

  openclaw2:
    image: openclaw/openclaw:latest
    container_name: openclaw2
    volumes:
      - ./data2:/home/openclaw/.openclaw
    restart: unless-stopped

2. 使用Docker Swarm

# 初始化Swarm
docker swarm init

# 创建服务
docker service create \
  --name openclaw \
  --replicas 3 \
  --publish 18789:18789 \
  openclaw/openclaw:latest

# 查看服务
docker service ls

# 扩缩容
docker service scale openclaw=5

3. 使用Kubernetes

创建 deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: openclaw
spec:
  replicas: 3
  selector:
    matchLabels:
      app: openclaw
  template:
    metadata:
      labels:
        app: openclaw
    spec:
      containers:
      - name: openclaw
        image: openclaw/openclaw:latest
        ports:
        - containerPort: 18789
        resources:
          limits:
            memory: "2Gi"
            cpu: "1000m"
          requests:
            memory: "1Gi"
            cpu: "500m"
        volumeMounts:
        - name: data
          mountPath: /home/openclaw/.openclaw
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: openclaw-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: openclaw
spec:
  selector:
    app: openclaw
  ports:
  - port: 18789
    targetPort: 18789
  type: LoadBalancer

📊 监控和日志

1. 使用Docker健康检查

# 启动容器(启用健康检查)
docker run -d \
  --name openclaw \
  --health-cmd="curl -f http://localhost:18789/health || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  -p 18789:18789 \
  openclaw/openclaw:latest

# 查看健康状态
docker inspect --format='{{json .State.Health}}' openclaw

2. 使用Prometheus监控

创建 prometheus.yml

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'openclaw'
    static_configs:
      - targets: ['openclaw:18789']

启动Prometheus:

version: '3.8'

services:
  prometheus:
    image: prom/prometheus
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'

  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"

3. 使用Grafana可视化

version: '3.8'

services:
  grafana:
    image: grafana/grafana
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - ./grafana-data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

  prometheus:
    image: prom/prometheus
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"

4. 集中式日志收集(ELK Stack)

version: '3.8'

services:
  elasticsearch:
    image: elasticsearch:8.0.0
    container_name: elasticsearch
    environment:
      - discovery.type=single-node
    volumes:
      - ./es-data:/usr/share/elasticsearchasticsearch/data

  logstash:
    image: logstash:8.0.0
    container_name: logstash
    volumes:
      - ./logstash.conf:/usr/share/logstash/pipeline/logstash.conf
    depends_on:
      - elasticsearch

  kibana:
    image: kibana:8.0.0
    container_name: kibana
    ports:
      - "5601:5601"
    depends_on:
      - elasticsearch

  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

💾 备份和恢复

1. 自动备份脚本

创建 backup.sh

#!/bin/bash

BACKUP_DIR="./backups"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="openclaw-backup-${BACKUP_DIR}.tar.gz"

mkdir -p ${BACKUP_DIR}

# 备份数据
tar -czf ${BACKUP_DIR}/${BACKUP_FILE} ./data

# 删除30天前的备份
find ${BACKUP_DIR} -name "openclaw-backup-*.tar.gz" -mtime +30 -delete

echo "Backup created: ${BACKUP_DIR}/${BACKUP_FILE}"

设置权限:

chmod +x backup.sh

2. 定时备份

使用cron:

# 编辑crontab
crontab -e

添加定时任务:

# 每天凌晨2点备份
0 2 * * * /path/to/backup.sh >> /var/log/openclaw-backup.log 2>&1

3. 恢复数据

# 解压备份
tar -xzf backups/openclaw-backup-20260222_020000.tar.gz

# 启动容器(恢复数据)
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v $(pwd)/data:/home/openclaw/.openclaw \
  openclaw/openclaw:latest

🔄 自动更新

1. 使用Watchtower自动更新镜像

version: '3.8'

services:
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_SCHEDULE=0 0 * * *

  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

2. 手动更新脚本

创建 update.sh

#!/bin/bash

# 拉取最新镜像
docker pull openclaw/openclaw:latest

# 停止并删除旧容器
docker stop openclaw
docker rm openclaw

# 启动新容器
docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 18789:18789 \
  -v $(pwd)/data:/home/openclaw/.openclaw \
  openclaw/openclaw:latest

echo "OpenClaw updated successfully!"

⚠️ 常见问题

Q: 容器频繁重启?

A: 检查容器状态和日志:

# 查看容器状态
docker ps -a

# 查看容器日志
docker logs openclaw

# 查看退出代码
docker inspect openclaw | grep ExitCode

常见原因:

  • 内存不足 → 增加内存限制
  • 配置错误 → 检查 openclaw.json
  • 健康检查失败 → 检查健康检查配置

Q: 性能下降?

A: 优化措施:

  1. 增加资源限制

    docker update --cpus="2" --memory="2g" openclaw
  2. 优化日志配置

    docker run --log-opt max-size=10m --log-opt max-file=3
  3. 使用缓存

    environment:
      - CACHE_ENABLED=true

Q: 如何查看资源使用?

A:

# 实时查看资源使用
docker stats openclaw

# 查看详细信息
docker inspect openclaw

# 查看磁盘使用
docker system df

API 配置详解

OpenClaw 需要配置大模型 API 才能运行,本文详细介绍各平台的配置方法

快速开始(推荐)

新手推荐使用配置向导自动生成配置:

# 运行配置向导
openclaw onboard --install-daemon

向导会自动:

  1. 检测环境和依赖
  2. 引导选择 API 提供商
  3. 帮助获取 API Key
  4. 自动生成配置文件
  5. 验证配置正确性

使用配置模板

如果你需要手动配置,可以使用我们提供的配置模板:

# 1. 下载教程模板
templates

# 2. 查看模板目录
ls templates/

# 3. 查看模板使用指南
cat templates/README.md

模板文件说明:

文件 说明 使用方法
openclaw-template.json OpenClaw 主配置模板 复制到 ~/.openclaw/openclaw.json
env-template.txt 环境变量模板 复制到 ~/.openclaw/.env

快速使用模板:

# 复制主配置模板
cp templates/openclaw-template.json ~/.openclaw/openclaw.json

# 复制环境变量模板
cp templates/env-template.txt ~/.openclaw/.env

# 设置正确权限(重要!)
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/.env

# 编辑配置文件,填写你的 API Key
nano ~/.openclaw/openclaw.json
nano ~/.openclaw/.env

详细模板使用说明请查看:templates/README.md

配置技巧

多模型切换

OpenClaw 支持配置多个模型提供商,可以在不同场景使用不同模型:

{
  "providers": {
    "siliconflow": {
      "api_key": "sk-xxx",
      "base_url": "https://api.siliconflow.cn/v1",
      "models": {
        "default": "deepseek-ai/DeepSeek-V3",
        "coding": "Qwen/Qwen2.5-72B-Instruct"
      }
    },
    "zhipu": {
      "api_key": "xxx",
      "base_url": "https://open.bigmodel.cn/api/paas/v4",
      "models": {
        "default": "GLM-4-Plus"
      }
    }
  },
  "default_provider": "siliconflow"
}

成本优化建议

  1. 日常对话:使用 DeepSeek-V3 等高性价比模型
  2. 编程任务:使用专门的编程模型(如 Qwen-Code)
  3. 复杂推理:使用 GLM-4-Plus 或 Qwen-Max
  4. 批量处理:使用轻量模型降低成本

常见问题

Q: API Key 保存在哪里?

A: OpenClaw 的配置文件位于 ~/.openclaw/config.json,API Key 会安全存储在此文件中。

Q: 如何查看 API 使用量?

A: 登录各平台控制台查看,OpenClaw 也提供 openclaw usage 命令查看统计。

Q: 多个 API Key 如何管理?

A: 可以配置多个提供商,通过环境变量或配置文件切换。

TTS 语音配置

OpenClaw v2026.4.25 全面升级了 TTS 语音系统,支持多种语音提供商。

快速配置

# 启用 TTS
openclaw config set tts.enabled true

# 设置提供商 (推荐 Azure Speech)
openclaw config set tts.provider azure

# 设置语音角色
openclaw config set tts.voice zh-CN-XiaoxiaoNeural

# 测试 TTS
/tts latest

提供商选择建议

提供商 推荐场景 价格
Azure Speech 企业级应用 中等
Xiaomi 中文场景 便宜
Volcengine 中文场景 中等
ElevenLabs 高质量需求 较贵

详细配置指南

TTS 语音配置指南

OpenClaw v2026.4.25 全面升级了 TTS(Text-to-Speech)语音系统,支持多种语音提供商和高级功能。本指南将帮助你配置和使用 TTS 功能。

🎯 核心功能

主要特性

  • 多提供商支持: Azure Speech、Xiaomi、Volcengine、ElevenLabs 等
  • 语音角色: 支持个性化语音角色配置
  • 会话级控制: 每个聊天可以独立配置 TTS
  • 自动语音: 支持自动将消息转换为语音

新增命令

  • /tts latest – 语音朗读最新消息
  • /tts on – 开启自动 TTS
  • /tts off – 关闭自动 TTS
  • /tts voice <voice_name> – 切换语音角色

🔧 基础配置

1. 配置 TTS 提供商

在 ~/.openclaw/openclaw.json 中添加 TTS 配置:

{
  "tts": {
    "enabled": true,
    "provider": "azure",
    "voice": "zh-CN-XiaoxiaoNeural",
    "autoTts": false
  }
}

2. 使用命令行配置

# 启用 TTS
openclaw config set tts.enabled true

# 设置提供商
openclaw config set tts.provider azure

# 设置语音角色
openclaw config set tts.voice zh-CN-XiaoxiaoNeural

# 关闭自动 TTS
openclaw config set tts.autoTts false

3. 验证配置

# 查看 TTS 配置
openclaw config get tts

# 测试 TTS 功能
/tts latest

🎤 提供商配置

Azure Speech (推荐)

Azure Speech 是微软提供的高质量语音服务,支持多种语言和语音角色。

配置步骤

  1. 获取 API 密钥

    • 访问 Azure Portal
    • 创建 Speech 资源
    • 获取 API 密钥和区域
  2. 配置 OpenClaw

    # 设置 Azure Speech 配置
    openclaw config set tts.provider azure
    openclaw config set tts.azure.apiKey "your-api-key"
    openclaw config set tts.azure.region "eastasia"
  3. 选择语音角色

    # 中文女声
    openclaw config set tts.voice zh-CN-XiaoxiaoNeural
    
    # 中文男声
    openclaw config set tts.voice zh-CN-YunxiNeural
    
    # 英文女声
    openclaw config set tts.voice en-US-JennyNeural

支持的语音角色

语言 女声 男声
中文 zh-CN-XiaoxiaoNeural zh-CN-YunxiNeural
英文 en-US-JennyNeural en-US-GuyNeural
日文 ja-JP-NanamiNeural ja-JP-KeitaNeural
韩文 ko-KR-SunHiNeural ko-KR-InJoonNeural

Xiaomi (小米语音)

小米语音合成是小米提供的中文语音服务,适合中文场景。

配置步骤

  1. 获取 API 密钥

  2. 配置 OpenClaw

    # 设置 Xiaomi 配置
    openclaw config set tts.provider xiaomi
    openclaw config set tts.xiaomi.apiKey "your-api-key"
  3. 选择语音角色

    # 中文女声
    openclaw config set tts.voice xiaomi-female
    
    # 中文男声
    openclaw config set tts.voice xiaomi-male

Volcengine (火山引擎)

火山引擎是字节跳动提供的云服务,支持高质量中文语音合成。

配置步骤

  1. 获取 API 密钥

  2. 配置 OpenClaw

    # 设置 Volcengine 配置
    openclaw config set tts.provider volcengine
    openclaw config set tts.volcengine.apiKey "your-api-key"
    openclaw config set tts.volcengine.appId "your-app-id"
  3. 选择语音角色

    # 中文女声
    openclaw config set tts.voice volcengine-female
    
    # 中文男声
    openclaw config set tts.voice volcengine-male

ElevenLabs v3

ElevenLabs 提供高质量的语音合成,支持语音克隆和情感控制。

配置步骤

  1. 获取 API 密钥

    • 访问 ElevenLabs
    • 注册账号并获取 API 密钥
  2. 配置 OpenClaw

    # 设置 ElevenLabs 配置
    openclaw config set tts.provider elevenlabs
    openclaw config set tts.elevenlabs.apiKey "your-api-key"
  3. 选择语音角色

    # 使用预设语音
    openclaw config set tts.voice elevenlabs-rachel
    
    # 使用自定义语音(需要先克隆)
    openclaw config set tts.voice elevenlabs-custom-id

🎭 语音角色配置

使用预设角色

OpenClaw 提供多种预设语音角色:

# 查看可用语音角色
openclaw tts voices list

# 使用预设角色
openclaw config set tts.voice zh-CN-XiaoxiaoNeural

自定义语音角色

ElevenLabs 语音克隆

  1. 上传音频样本

    # 上传音频文件进行克隆
    openclaw tts clone --name "my-voice" --file "sample.wav"
  2. 使用克隆的语音

    # 使用自定义语音
    openclaw config set tts.voice "cloned:my-voice"

SSML 语音控制

使用 SSML(Speech Synthesis Markup Language)控制语音效果:

<speak>
  <prosody rate="slow" pitch="+10%">
    这是一个慢速高音的示例。
  </prosody>
  
  <break time="500ms"/>
  
  <prosody rate="fast" pitch="-10%">
    这是一个快速低音的示例。
  </prosody>
</speak>

🔄 自动 TTS 配置

会话级自动 TTS

在聊天中开启自动 TTS:

# 开启当前会话自动 TTS
/tts on

# 关闭当前会话自动 TTS
/tts off

# 查看当前会话 TTS 状态
/tts status

全局自动 TTS

配置全局自动 TTS:

# 开启全局自动 TTS
openclaw config set tts.autoTts true

# 关闭全局自动 TTS
openclaw config set tts.autoTts false

代理级自动 TTS

为特定代理配置自动 TTS:

{
  "agents": {
    "defaults": {
      "tts": {
        "autoTts": true,
        "voice": "zh-CN-XiaoxiaoNeural"
      }
    }
  }
}

💬 WhatsApp TTS 集成

语音朗读最新消息

在 WhatsApp 中使用 TTS:

# 朗读最新消息
/tts latest

# 朗读指定数量的消息
/tts latest 5

自动语音回复

配置 WhatsApp 自动语音回复:

{
  "channels": {
    "whatsapp": {
      "tts": {
        "autoReply": true,
        "voice": "zh-CN-XiaoxiaoNeural"
      }
    }
  }
}

🔍 故障排除

常见问题

1. TTS 不工作

症状: 使用 /tts 命令没有声音

解决方案:

# 检查 TTS 配置
openclaw config get tts

# 检查提供商配置
openclaw config get tts.azure  # 或其他提供商

# 测试提供商连接
openclaw tts test

2. 语音质量差

症状: 合成的语音不自然

解决方案:

  • 尝试不同的语音角色
  • 调整语速和音调参数
  • 升级到更高质量的提供商

3. 延迟高

症状: TTS 合成需要很长时间

解决方案:

  • 使用本地 CLI 提供商
  • 选择更快的语音角色
  • 检查网络连接

4. 语言支持问题

症状: 某些语言不支持

解决方案:

  • 检查提供商的语言支持列表
  • 使用支持目标语言的提供商
  • 考虑使用多语言提供商

调试命令

# 查看 TTS 详细日志
openclaw logs tts

# 测试 TTS 提供商
openclaw tts test --provider azure

# 查看可用语音
openclaw tts voices list --provider azure

# 重置 TTS 配置
openclaw config unset tts

📊 性能优化

选择合适的提供商

提供商 延迟 质量 价格 推荐场景
Azure Speech 企业级应用
Xiaomi 中文场景
Volcengine 中文场景
ElevenLabs 极高 高质量需求
Local CLI 极低 免费 本地部署

缓存优化

启用 TTS 缓存减少重复合成:

{
  "tts": {
    "cache": {
      "enabled": true,
      "maxSize": "100MB",
      "ttl": "7d"
    }
  }
}

并发控制

配置并发 TTS 请求:

{
  "tts": {
    "concurrency": {
      "max": 5,
      "queue": true
    }
  }
}

🔐 安全考虑

API 密钥安全

  • 使用环境变量存储 API 密钥
  • 定期轮换 API 密钥
  • 限制 API 密钥权限
# 使用环境变量
export TTS_API_KEY="your-api-key"
openclaw config set tts.azure.apiKey "$TTS_API_KEY"

访问控制

配置 TTS 访问控制:

{
  "tts": {
    "access": {
      "allowedUsers": ["user1", "user2"],
      "deniedUsers": ["user3"]
    }
  }
}

📚 参考资料

小龙虾openclaw Docker 详细部署教程

快速开始

根据你的平台选择对应教程:

💡 Windows用户特别提示:新手优先推荐使用 WSL(Windows子系统Linux) 安装,稳定性和兼容性更好,后续维护更方便,是Windows平台的首选安装方式。

直接Windows本地安装适合有经验的用户,新手请优先选择WSL安装。

平台 难度 推荐指数 适用人群 教程链接
WSL ⭐⭐ ⭐⭐⭐⭐⭐ 🔥 Windows新手首选 WSL 安装教程
Windows ⭐⭐ ⭐⭐⭐ Windows有经验用户 Windows 安装指南
macOS ⭐⭐ ⭐⭐⭐⭐⭐ macOS用户 macOS 安装指南
Linux ⭐⭐⭐⭐⭐ Linux用户 Linux 安装指南
Docker ⭐⭐⭐ ⭐⭐⭐⭐ 熟悉Docker的用户 Docker 部署教程
云服务器 ⭐⭐⭐ ⭐⭐⭐⭐⭐ 需要24小时在线的用户 云服务器部署指南
Android ⭐⭐⭐⭐ ⭐⭐⭐ 移动部署用户(实验性功能) Android 部署指南

 


✅ 前置条件

系统要求

要求 最低版本 推荐版本 检查命令
操作系统 Ubuntu 18.04+ Ubuntu 22.04 cat /etc/os-release
内存 2GB 4GB+ free -h
存储 10GB 20GB+ df -h
网络 稳定连接 稳定连接

Docker要求

要求 版本 检查命令
Docker 20.10+ docker --version
Docker Compose 2.0+ docker-compose --version

权限要求

✅ sudo权限: 安装和管理Docker需要管理员权限


🚀 快速开始

5分钟快速部署OpenClaw

最新推荐:ClawDock 官方容器方案 ✨

ClawDock是OpenClaw官方推出的容器运行时,内置优化配置,支持一键部署,无需手动编写配置文件:

# 一键安装ClawDock并部署
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/docker-setup.sh | bash

# 部署完成后访问Web控制台
open http://localhost:18789

部署进度

步骤 任务 预计时间 状态
1️⃣ 安装Docker 2分钟 ⏳ 进行中
2️⃣ 拉取镜像 1分钟 ⏸️ 待开始
3️⃣ 配置文件 1分钟 ⏸️ 待开始
4️⃣ 启动容器 30秒 ⏸️ 待开始
5️⃣ 验证部署 30秒 ⏸️ 待开始

手动部署(自定义配置)

# 1. 拉取OpenClaw官方镜像(托管在GitHub Container Registry)
docker pull ghcr.io/openclaw/openclaw:2026.2.22

# 也可以自行通过源码构建镜像
# git clone https://github.com/openclaw/openclaw && cd openclaw && docker build -t openclaw:local .

# 2. 创建配置文件(注意v2026.4.9已废弃旧配置别名,使用新的标准配置路径)
cat > openclaw.json << 'EOF'
{
  "providers": {
    "bailian": {
      "apiKey": "YOUR_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen-turbo"
      },
      "sandbox": {
        "perSession": true
      }
    }
  },
  "browser": {
    "ssrfPolicy": {
      "allowPrivateNetwork": false
    }
  }
}
EOF

# 3. 启动容器
docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 18789:18789 \
  -v $(pwd)/openclaw.json:/home/openclaw/.openclaw/openclaw.json:ro \
  -v $(pwd)/data:/home/openclaw/.openclaw/data \
  openclaw/openclaw:v2026.4.9

# 4. 查看日志
docker logs -f openclaw

✅ 成功标志: 看到 “Gateway running on http://0.0.0.0:18789


📦 Docker安装

方式1: 官方安装脚本(推荐)✨

适用场景: Ubuntu/Debian系统

# 下载安装脚本
curl -fsSL https://get.docker.com -o get-docker.sh

# 运行安装脚本
sudo sh get-docker.sh

# 将当前用户添加到docker组
sudo usermod -aG docker $USER

# 重新登录以生效
newgrp docker

# 验证安装
docker docker version
docker-compose version

✅ 成功输出: Docker version 24.x.x, Docker Compose version 2.x.x


方式2: 手动安装

适用场景: 需要精细控制版本

Ubuntu/Debian

# 更新包管理器
sudo apt update

# 安装依赖
sudo apt install -y \
  ca-certificates \
  curl \
  gnupg \
  lsb-release

# 添加Docker官方GPG密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 添加Docker仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 启动Docker服务
sudo systemctl start docker
sudo systemctl enable docker

# 验证安装
docker --version
docker-compose version

CentOS/RHEL

# 安装依赖
sudo yum install -y yum-utils

# 添加Docker仓库
sudo yum-config-manager \
  --add-repo \
  https://download.docker.com/linux/centos/docker-ce.repo

# 安装Docker
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 启动Docker服务
sudo systemctl start docker
sudo systemctl enable docker

# 验证安装
docker --version
docker-compose version

方式3: 使用Docker Desktop

适用场景: Windows/macOS系统

Windows

  1. 下载Docker Desktop: https://www.docker.com/products/docker-desktop
  2. 运行安装程序
  3. 启用WSL 2后端(推荐)
  4. 重启计算机
  5. 验证安装: docker --version

macOS

  1. 下载Docker Desktop: https://www.docker.com/products/docker-desktop/mac
  2. 拖拽到Applications文件夹
  3. 启动Docker Desktop
  4. 验证安装: docker --version

验证Docker安装

# 运行测试容器
docker run hello-world

# 查看Docker信息
docker info

# 查看Docker版本
docker --version
docker-compose version

✅ 成功输出: Hello from Docker!


🐳 OpenClaw Docker镜像

拉取镜像

# 拉取最新版本
docker pull openclaw/openclaw:latest

# 拉取指定版本
docker pull openclaw/openclaw:v2026.5.7

# 查看已拉取的镜像
docker images | grep openclaw

镜像版本

版本标签 说明 推荐场景
latest 最新稳定版本 生产环境
v2026.5.7 特定版本 稳定环境
dev 开发版本 测试环境
alpine Alpine Linux版本 轻量级部署

查看镜像信息

# 查看镜像详细信息
docker inspect openclaw/openclaw:latest

# 查看镜像大小
docker images openclaw/openclaw:latest

🚀 基本部署

最小化部署

# 启动容器(最小配置)
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  openclaw/openclaw:latest

使用配置文件部署

# 创建配置文件目录
mkdir -p openclaw-config

# 创建openclaw.json
cat > openclaw-config/openclaw.json << 'EOF'
{
  "providers": {
    "bailian": {
      "apiKey": "YOUR_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen-turbo"
      }
    }
  }
}
EOF

# 启动容器(挂载配置文件)
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v $(pwd)/openclaw-config/openclaw.json:/home/openclaw/.openclaw/openclaw.json \
  openclaw/openclaw:latest

使用环境变量部署

# 启动容器(使用环境变量)
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -e OPENCLAW_API_KEY="YOUR_API_KEY" \
  -e OPENCLAW_MODEL="bailian/qwen-turbo" \
  openclaw/openclaw:latest

完整部署

# 创建必要目录
mkdir -p openclaw-config/data

# 启动容器(完整配置)
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v $(pwd)/openclaw-config/openclaw.json:/home/openclaw/.openclaw/openclaw.json \
  -v $(pwd)/openclaw-config/data:/home/openclaw/.openclaw/data \
  -e OPENCLAW_LOG_LEVEL="info" \
  -e OPENCLAW_ENABLE_TELEMETRY="false" \
  --restart unless-stopped \
  openclaw/openclaw:latest

📄 配置文件

openclaw.json

创建 openclaw.json 配置文件:

{
  "providers": {
    "bailian": {
      "apiKey": "YOUR_API_KEY",
      "endpoint": "https://dashscope.aliyuncs.com/api/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen-turbo",
        "fallback": ["bailian/qwen-max"]
      }
    },
    "maxResponseTokens": 4096
  },
  "gateway": {
    "bind": "0.0.0.0",
    "port": 18789,
    "trustedProxies": ["*"]
  },
  "plugins": {
    "allow": [
      "feishu",
      "wecom",
      "dingtalk",
      "adp-openclaw"
    ]
  }
}

.env 文件

创建 .env 文件存储敏感信息:

# API配置
OPENCLAW_API_KEY=YOUR_API_KEY
OPENCLAW_MODEL=bailian/qwen-turbo

# 网关配置
GATEWAY_BIND=0.0.0.0
GATEWAY_PORT=18789

# 日志配置
LOG_LEVEL=info

# 其他配置
ENABLE_TELEMETRY=false

使用Docker Compose

创建 docker-compose.yml

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    volumes:
      - ./openclaw.json:/home/openclaw/.openclaw/openclaw.json
      - ./data:/home/openclaw/.openclaw/data
    environment:
      - OPENCLAW_LOG_LEVEL=info
      - OPENCLAW_ENABLE_TELEMETRY=false
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 10s
      retries: 3

启动服务:

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

💾 数据持久化

挂载目录

# 创建数据目录
mkdir -p openclaw-data

# 启动容器(挂载数据目录)
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v $(pwd)/openclaw-data:/home/openclaw/.openclaw \
  openclaw/openclaw:latest

数据目录结构

openclaw-data/
├── openclaw.json          # 配置文件
├── data/                  # 数据目录
│   ├── sessions/          # 会话数据
│   ├── memory/            # 记忆数据
│   └── workspace/         # 工作区
├── logs/                  # 日志文件
└── cache/                 # 缓存文件

备份数据

# 备份完整数据目录
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz openclaw-data/

# 仅备份关键数据
tar -czf openclaw-data-backup-$(date +%Y%m%d).tar.gz \
  openclaw-data/data/ \
  openclaw-data/openclaw.json

恢复数据

# 解压备份文件
tar -xzf openclaw-backup-20260222.tar.gz

# 启动容器(恢复数据)
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v $(pwd)/openclaw-data:/home/openclaw/.openclaw \
  openclaw/openclaw:latest

🌐 网络配置

端口映射

# 单端口映射
docker run -d --name openclaw -p 18789:18789 openclaw/openclaw:latest

# 多端口映射(如果需要)
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -p 8080:8080 \
  openclaw/openclaw:latest

使用自定义网络

# 创建网络
docker network create openclaw-network

# 启动容器(使用自定义网络)
docker run -d \
  --name openclaw \
  --network openclaw-network \
  --network-alias openclaw \
  -p 18789:18789 \
  openclaw/openclaw:latest

# 查看网络
docker network inspect openclaw-network

使用反向代理(Nginx)

创建 nginx.conf

server {
    listen 80;
    server_name openclaw.example.com;

    location / {
        proxy_pass http://openclaw:18789;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

启动Nginx和OpenClaw:

# 启动OpenClaw
docker run -d \
  --name openclaw \
  --network openclaw-network \
  -p 18789:18789 \
  openclaw/openclaw:latest

# 启动Nginx
docker run -d \
  --name nginx \
  --network openclaw-network \
  -p 80:80 \
  -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro \
  nginx:alpine

⚠️ 常见问题

Q: Docker安装失败?

A: 按照以下步骤排查:

  1. 检查系统版本

    cat /etc/os-release

    确保是Ubuntu 18.04+或CentOS 7+

  2. 清理旧版本

    sudo apt remove docker docker-engine docker.io containerd runc
  3. 重新安装

    curl -fsSL https://get.docker.com -o get-docker.sh
    sudo sh get-docker.sh

Q: 容器无法启动?

A: 常见原因和解决方案:

原因 解决方案
端口被占用 使用 -p 18790:18789 映射其他端口
配置文件错误 检查 openclaw.json 语法
权限不足 使用 sudo 或添加用户到docker组
内存不足 增加Docker内存限制

查看详细日志:

# 查看容器日志
docker logs openclaw

# 实时查看日志
docker logs -f openclaw

Q: 数据无法持久化?

A: 确保正确挂载目录:

# 正确挂载
docker run -d \
  --name openclaw \
  -v $(pwd)/data:/home/openclaw/.openclaw \
  openclaw/openclaw:latest

# 验证挂载
docker inspect openclaw | grep Mounts -A 10

Q: 如何更新镜像?

A:

# 拉取最新镜像
docker pull openclaw/openclaw:latest

# 停止并删除旧容器
docker stop openclaw
docker rm openclaw

# 启动新容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v $(pwd)/data:/home/openclaw/.openclaw \
  openclaw/openclaw:latest

Q: 如何查看容器资源使用?

A:

# 查看容器状态
docker stats openclaw

# 查看详细信息
docker inspect openclaw

# 查看进程
docker top openclaw

Docker方式 一键部署OpenClaw

  • Docker方式 一键部署OpenClaw 完全指南

    想拥有自己的AI助手,却被复杂的部署流程劝退?别担心!这篇博客将手把手教你用 Docker 方式,像搭积木一样快速把 OpenClaw 跑起来。不需要深究底层原理,几行命令就能搞定,让你专注在玩法上。

    第一章:为什么选 Docker?省心省力

    • 环境隔离,告别“依赖地狱”:Docker 会把 OpenClaw 和它的运行环境打包在一起,不会弄乱你本地的系统配置,删起来也干干净净。
    • 跨平台一致性:无论你用的是 macOS、Windows 还是 Linux 服务器,只要装了 Docker,运行效果一模一样,避免各种奇怪的兼容性问题。
    • 一键启动,快速迭代:利用官方镜像,不需要从源码编译,下载即运行,非常适合想快速尝鲜或者频繁更新的用户。

    第二章:准备工作,磨刀不误砍柴工

    • 安装 Docker 环境:确保你的机器上已经安装了 Docker Desktop(桌面用户)或者 Docker Engine(服务器用户)。这是基础门槛。
    • 准备配置文件:虽然是一键部署,但 OpenClaw 需要一些密钥(如 API Key)和网络配置。提前准备好你的 config.yaml 或者环境变量清单。
    • 检查端口占用:确认你打算使用的端口(通常是 3000 或其他自定义端口)没有被其他程序占用,避免启动失败。

    第三章:实战部署,复制粘贴搞定

    • 拉取最新镜像:使用 docker pull 命令获取最新的 OpenClaw 官方镜像,确保你用的是最稳定或最新的功能版本。
    • 编写启动命令:一条 docker run 命令搞定一切。通过 -v 挂载配置目录,通过 -p 映射端口,让容器里的服务能对外访问。
    • 使用 Docker Compose(进阶推荐):如果你觉得命令行参数太长,可以创建一个 docker-compose.yml 文件,以后只需要敲 docker-compose up -d 就能启动,管理起来更直观。

    第四章:启动验证与常见问题排查

    • 查看日志确认状态:部署后第一时间查看容器日志(docker logs),看看有没有红色的报错信息,确认服务是否真的在监听端口。
    • 访问 Web 界面:打开浏览器,输入 localhost:端口号(或你的服务器 IP),如果能看到 OpenClaw 的登录或控制界面,恭喜你成功了!
    • 权限与网络问题:如果发现连不上,检查防火墙是否放行了端口,或者 Docker 容器是否有足够的权限访问挂载的配置文件目录。

    结论:开启你的 AI 助手之旅

    通过 Docker 部署 OpenClaw,你不仅获得了一个强大的本地 AI 助手,还掌握了一种现代化的应用管理方式。现在,你可以尽情探索它的各种技能(Skills),比如管理文件、控制浏览器或者设置定时任务。如果在部署过程中遇到任何奇怪的问题,记得去官方 GitHub 或 Discord 社区逛逛,那里有大把的热心人帮你解答。祝你玩得开心!

    Docker 一键部署 OpenClaw:最简单、最快速的容器化部署指南

  • OpenClaw Docker 部署教程:一条命令搞定,新手也能轻松上手
  • 告别繁琐配置!用 Docker 一键部署 OpenClaw 全流程实战
  • 2026 最新:Docker 方式极速部署 OpenClaw 完整攻略
  • OpenClaw 快速入门:基于 Docker 的一键部署方案详解

项目简介

OpenClaw 是一个开源的自托管 AI Agent 网关平台,支持 Discord、飞书、Telegram、WhatsApp、Signal、Slack、iMessage 等 10+ 消息渠道,247,000+ GitHub Stars。

核心特性:

  • 🤖 真正的 AI Agent —— 不只是聊天,还能执行操作、操控浏览器、生成图片/视频
  • 🔒 安全沙箱 —— 新版本默认开启沙箱模式,限制文件系统访问,避免误操作风险
  • 🏠 自托管 —— 数据完全由你掌控,本地或云服务器部署
  • 🌐 多平台对接 —— 内置支持10+消息平台,飞书支持官方一键对接,5分钟完成配置
  • ⚡ 24小时在线 —— 云服务器部署全天候待命
  • 🛠️ 1500+ Skills —— 丰富的技能扩展库 (ClawHub)
  • 🎬 多媒体支持 —— 图片/视频/语音生成、语音转写、TTS
  • 📱 移动节点 —— iOS/Android 配对,随时随地对话

快速开始

 

根据你的平台选择对应教程:💡 Windows用户特别提示:新手优先推荐使用 WSL(Windows子系统Linux) 安装,稳定性和兼容性更好,后续维护更方便,是Windows平台的首选安装方式。

直接Windows本地安装适合有经验的用户,新手请优先选择WSL安装。

平台 难度 推荐指数 适用人群 教程链接
WSL ⭐⭐ ⭐⭐⭐⭐⭐ 🔥 Windows新手首选 WSL 安装教程
Windows ⭐⭐ ⭐⭐⭐ Windows有经验用户 Windows 安装指南
macOS ⭐⭐ ⭐⭐⭐⭐⭐ macOS用户 macOS 安装指南
Linux ⭐⭐⭐⭐⭐ Linux用户 Linux 安装指南
Docker ⭐⭐⭐ ⭐⭐⭐⭐ 熟悉Docker的用户 Docker 部署教程
云服务器 ⭐⭐⭐ ⭐⭐⭐⭐⭐ 需要24小时在线的用户 云服务器部署指南
Android ⭐⭐⭐⭐ ⭐⭐⭐ 移动部署用户(实验性功能) Android 部署指南

什么是 OpenClaw In Docker

OpenClaw In Docker 是 cncfstack 组织为 OpenClaw 提供的容器化部署方案,主要特点:

  • 类虚拟机隔离环境:基于 csvm 项目提供 systemd 系统服务
  • 用户登录认证:基于 OpenResty+Lua 提供安全的用户登录功能
  • HTTPS 强制访问:必须使用 HTTPS 访问,默认使用 OpenSSL 自签证书
  • 预装基础服务:openclaw、openresty、docker、cron、systemd、ssh 等
  • 预装开发工具:chromium、playwright 等浏览器自动化工具

二、核心特性

2.1 技术架构

OpenClaw In Docker 采用容器化技术,将 OpenClaw 及其依赖环境打包成完整的镜像。

组件 说明 作用
容器基础 基于 Debian 系统 集成 systemd 和 Docker in Docker 能力
Web 服务 OpenResty+Lua 提供 HTTP/HTTPS 服务和用户认证
反向代理 Nginx 配置 将外部 HTTPS 请求转发到内部 OpenClaw 服务
数据持久化 Docker Volume 通过挂载目录实现数据持久化

2.2 安全机制

多层安全防护:

  • 强制 HTTPS:所有 Web 访问必须使用 HTTPS,防止数据泄露
  • 用户认证:基于用户名密码的登录机制,未授权用户无法访问
  • 设备审批:新设备连接需要审批,防止未授权访问
  • 容器隔离:运行在隔离容器中,限制系统权限

三、环境准备

3.1 系统要求

项目 最低要求 推荐配置
操作系统 Linux (Ubuntu 20.04+) Ubuntu 22.04 LTS / Debian 11+
CPU 2 核心 4 核心+
内存 4GB 8GB+
磁盘 20GB 可用空间 50GB+ SSD
Docker 20.10+ 24.0+

3.2 安装 Docker

# Ubuntu/Debian 系统
curl -fsSL https://get.docker.com | bash

# 启动 Docker 服务
systemctl start docker
systemctl enable docker

# 验证安装
docker --version
docker info

⚠️ 注意事项:确保 Docker 服务正常运行,并且当前用户有权限执行 Docker 命令。如果需要,将用户添加到 docker 组:

sudo usermod -aG docker $USER
newgrp docker

3.3 安装Docker Compose

    • 确保已安装Docker。Docker Compose依赖于Docker引擎。
    • 安装Docker Compose:
    • Linux系统:
     sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
     sudo chmod +x /usr/local/bin/docker-compose
    • macOS和Windows系统:Docker Desktop已内置Docker Compose,无需单独安装
    • 验证安装:
   docker-compose --version

四、快速开始

4.1 拉取镜像

# 从 Docker Hub 拉取镜像
docker pull cncfstack/openclaw-in-docker:latest

# 或者从阿里云镜像仓库拉取(国内更快)
docker pull registry.cn-hangzhou.aliyuncs.com/cncfstack/openclaw-in-docker:latest

4.2 创建数据目录

# 创建数据持久化目录
mkdir -p /opt/openclaw/{data,logs,certs}
cd /opt/openclaw

# 设置权限
chmod -R 755 /opt/openclaw

4.3 启动容器

# 启动 OpenClaw 容器
docker run -d \\
  --name openclaw \\
  -p 8443:8443 \\
  -v /opt/openclaw/data:/data \\
  -v /opt/openclaw/logs:/var/log \\
  -v /opt/openclaw/certs:/certs \\
  -e OPENCLAW_ADMIN_PASSWORD=your_password \\
  --restart unless-stopped \\
  cncfstack/openclaw-in-docker:latest

✅ 启动成功:容器启动后,访问 https://你的服务器 IP:8443 即可看到 OpenClaw 登录页面。


五、详细配置

5.1 环境变量配置

变量名 说明 默认值 是否必填
OPENCLAW_ADMIN_PASSWORD 管理员密码 ✅ 必填
OPENCLAW_PORT 服务端口 8443 ❌ 可选
OPENCLAW_DEBUG 调试模式 false ❌ 可选
HTTP_PROXY HTTP 代理 ❌ 可选

5.2 Docker Compose 部署

version: '3.8'

services:
  openclaw:
    image: cncfstack/openclaw-in-docker:latest
    container_name: openclaw
    ports:
      - "8443:8443"
    volumes:
      - ./data:/data
      - ./logs:/var/log
      - ./certs:/certs
    environment:
      - OPENCLAW_ADMIN_PASSWORD=your_secure_password
      - OPENCLAW_DEBUG=false
    restart: unless-stopped
    networks:
      - openclaw_net

networks:
  openclaw_net:
    driver: bridge

使用 Docker Compose 启动:

docker compose up -d

六、证书配置

6.1 使用自签名证书(默认)

容器首次启动时会自动生成 OpenSSL 自签名证书,位于 /certs 目录。

6.2 使用 Let’s Encrypt 证书

# 安装 certbot
apt update && apt install -y certbot

# 获取证书
certbot certonly --standalone -d your-domain.com

# 复制证书到容器
cp /etc/letsencrypt/live/your-domain.com/fullchain.pem /opt/openclaw/certs/
cp /etc/letsencrypt/live/your-domain.com/privkey.pem /opt/openclaw/certs/

# 重启容器
docker restart openclaw

七、容器管理

7.1 查看容器状态

# 查看运行状态
docker ps -a | grep openclaw

# 查看容器日志
docker logs openclaw

# 实时查看日志
docker logs -f openclaw

7.2 停止和启动

# 停止容器
docker stop openclaw

# 启动容器
docker start openclaw

# 重启容器
docker restart openclaw

7.3 进入容器

# 进入容器 shell
docker exec -it openclaw /bin/bash

# 查看容器内资源使用
docker exec openclaw df -h
docker exec openclaw free -m

八、设备审批

新设备首次连接 OpenClaw 时需要管理员审批:

  1. 登录 OpenClaw 管理后台
  2. 进入「设置」→「设备管理」
  3. 查看待审批设备列表
  4. 点击「批准」或「拒绝」

九、版本升级

# 拉取最新镜像
docker pull cncfstack/openclaw-in-docker:latest

# 停止旧容器
docker stop openclaw
docker rm openclaw

# 启动新容器(使用相同的启动命令)
docker run -d \\
  --name openclaw \\
  -p 8443:8443 \\
  -v /opt/openclaw/data:/data \\
  -v /opt/openclaw/logs:/var/log \\
  -v /opt/openclaw/certs:/certs \\
  -e OPENCLAW_ADMIN_PASSWORD=your_password \\
  --restart unless-stopped \\
  cncfstack/openclaw-in-docker:latest

十、常见问题

10.1 无法访问 HTTPS 页面

原因:浏览器不信任自签名证书

解决:点击「高级」→「继续访问」或导入证书到信任列表

10.2 容器启动失败

检查:

  • 端口 8443 是否被占用
  • Docker 服务是否正常运行
  • 查看容器日志:docker logs openclaw

10.3 数据丢失问题

解决:确保正确挂载了 /data 目录,数据会持久化保存在宿主机

10.4 性能优化建议

  • 使用 SSD 存储提升 I/O 性能
  • 分配至少 8GB 内存
  • 使用 Docker Compose 管理更方便
  • 定期清理日志文件

总结

OpenClaw In Docker 提供了简单、安全的容器化部署方案,让你能够快速搭建自己的 AI Agent 服务。通过本文的教程,你应该已经掌握了从环境准备到生产部署的完整流程。

下一步建议:

  • 配置 IM 机器人接入(钉钉/飞书/Telegram)
  • 探索 OpenClaw 的 Skills 扩展能力
  • 学习编写自定义任务流程
  • 了解多 Agent 协作配置

🔗 相关链接

 

通过腾讯云轻量服务器模板部署OpenClaw后的详细配置教程

  1. 腾讯云轻量服务器部署OpenClaw教程:模板一键部署到完整配置
  2. OpenClaw + 腾讯云轻量服务器:手把手保姆级配置指南
  3. 用腾讯云轻量服务器搭建OpenClaw:从模板部署到调优全流程
  4. 腾讯云轻量服务器OpenClaw部署详解:新手也能上手的完整配置
  5. OpenClaw部署实战:腾讯云轻量服务器模板化配置最佳实践

购买服务器后,环境配置是使用 OpenClaw 的首要步骤。由于 OpenClaw 依赖 NodeJS、Swift、Kotlin 等多语言及相关依赖库,手动配置过程繁琐且易出现版本兼容问题,因此建议优先使用腾讯云轻量服务器中的应用模板——该模板已预置全套运行环境及 OpenClaw 核心程序,可直接跳过依赖安装环节,大幅提升配置效率。

需要注意的是,即便通过应用模板完成系统安装,也是无法直接使用 OpenClaw 的,所有后续配置需通过终端命令行完成,配置好了之后才能用上 OpenClaw。

所以请务必按照以下步骤逐步操作,避免因操作遗漏导致配置失败。
使用模板重装时,请使用 OpenClaw,Moltbot 不支持飞书。

1315495-20260131164606415-1681430355
服务器管理界面,找到登录按钮,进入命令终端,或者开放 22 端口后自行使用 shell 登录操作。

1315495-20260131164605313-420511351
接下来,执行命令启动配置向导,跟着提示一步一步配置。

openclaw onboard

提示:若配置过程中未保存设置,或需修改已配置项,可执行 openclaw configure 命令重新进入配置界面。

◆ I understand this is powerful and inherently risky. Continue?

操作说明:通过左右方向键切换 Yes/No 选项,选择 Yes 即表示已了解 OpenClaw 权限相关风险,同意继续配置。

1315495-20260131164605646-1819541500
◆ Onboarding mode

进入 Onboarding mode 选择界面时,对于首次配置的用户,建议优先选择 QuickStart 模式——该模式以「最小配置+最快部署」为目标,可跳过非必要配置项,快速完成 OpenClaw 基础部署。

1315495-20260131164605520-1006049119

1315495-20260131164605791-1366139041
◆Config handling

第一次配置使用 Use existing valuesUpdateReset 都行。

◆Model/auth provide

配置要使用的模型,可以在这里直接配置,也可以后续通过配置文件处理。

因为笔者使用 moonshot 国内模型,但是 OpenClaw 的配置是国际的会导致接口地址错误,所以笔者先选择 Skip for now 跳过大模型配置,后面再单独设置要使用的模型即可。

1315495-20260131164605522-1525839888

1315495-20260131164605264-1700792091
◆Default model

进入 Default model 选择界面时,可任意选择一个模型临时占位——该配置后续将通过修改配置文件覆盖,不影响最终使用效果。

1315495-20260131164606386-894241411
◆Select channel (QuickStart)

配置要使用的对话应用,如果用飞书,按要求填参数即可。这里可选 Skip for now ,先跳过选择,后面笔者会单独用一节内容讲解怎么配置。

1315495-20260131164605352-2069487184
◇ Skills status

配置技能,可以选 Yes,根据提示安装一些常用的工具。

1315495-20260131164605321-1711843445
到了 Install missing skill dependencies 环节,按下空格键选择要默认安装的 skill,可以多选。

1315495-20260131164606490-949425788
其它的配置用不到,先不管了。

1315495-20260131164605257-2067428666
确认重启服务。

1315495-20260131164605806-482383502

◆ How do you want to hatch your bot?

选择 Hatch in TUI,通过终端使用,后面也可以通过配置 Web UI 以便我们可以通过网页访问 OpenClaw。

1315495-20260131164605327-1990192637
最后查看界面输出的信息,将这些信息保存下来。

1315495-20260131164606145-1148979896

使用公网访问 OpenClaw

不用暴露访问到外网也可以,如果不需要接入 Telegram、WebUI 公开访问,可以跳过这一节内容。

如果有域名,建议使用域名绑定,而不是使用暴露端口的方式映射 OpenClaw 到公网。

WebSocket

WebSocket 方案需直接暴露 Gateway 端口,安全性较低,仅建议用于临时测试。

假如我们需要将社交 App 接入到服务器,就需要这样弄,如果只是配置飞书,不需要走这一步。

如果有域名可以做反向代理,也不建议使用端口暴露的方式公开 WebSocket。
其架构逻辑如下:

消息渠道 (WhatsApp/Telegram/Discord/iMessage)  
        │  
        ▼  
┌───────────────────────────┐  
│          Gateway          │  ws://127.0.0.1:18789  
│     (单一控制平面)        │  
└───────────┬───────────────┘  
              │  
              ├─ Pi agent (RPC)  
              ├─ CLI (clawdbot …)  
              ├─ Chat UI (SwiftUI)  
              └─ 其他客户端  

执行命令继续配置 OpenClaw。

openclaw configure

◆ Where will the Gateway run?

选择 ◆ Where will the Gateway run? 以便能够在外部访问服务器中你的 OpenClaw。

接着要注意 Gateway WebSocket URL 下面提示的地址是可以修改的,找到你的腾讯云服务器公网 IP,替换里面的 127.0.0.1

1315495-20260131164605567-1817231238
◆ Gateway auth

选择 Token,也就是要有凭证才能访问 OpenClaw。

1315495-20260131164605679-1338621944

◆ Gateway token

相当于输入密码,后续访问 OpenClaw 需要提供此密码,

停止并使用 --allow-unconfigured 启动不安全的模式。

openclaw gateway stop
openclaw gateway --allow-unconfigured

Web UI

~/.openclaw/openclaw.json 里面的 mode 改成 remotebind 改成 lan,然后重启 OpenClaw。

查看 token:

cat ~/.openclaw/openclaw.json

1315495-20260131164606097-370450759
使用公网访问时在地址后面附加 &token=xxx
1315495-20260131164606169-1876818599
访问公网会出现 pairing required 错误,说明需要给设备授权,执行命令查询授权终端列表:

openclaw devices list

1315495-20260131164605551-1523680332
找到 Pending 列表,把 Request 复制出来,配置授权。

openclaw devices approve b8eb70dd...

界面已正常访问。

1315495-20260131164605801-733793042

配置模型

这里以 moonshot 的模型为示例,跳过使用 CLI 的方式,怎么跳过配置文件配置自定义模型到 OpenClaw。

https://platform.moonshot.cn/console/api-keys 新建一个 key,到 https://platform.moonshot.cn/playground 查看支持的模型。

1315495-20260131164605934-2039061759
Kimi Code 模型也很强大,可以搞一个,以便挂后台写代码,到这里 https://www.kimi.com/code 购买编程模型。

1315495-20260131164606354-801022956
新建 key:https://www.kimi.com/code/console?from=kfc_overview_topbar

1315495-20260131164605905-1154285968
打开 ~/.openclaw/openclaw.json,替换或添加以下模型配置:

请替换 ${MOONSHOT_API_KEY} 、${KIMICODE_API_KEY}为你的 key。

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "moonshot/kimi-k2.5"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "workspace": "/root/.openclaw/workspace"
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.cn/v1",
        "apiKey": "${MOONSHOT_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "kimi-k2.5",
            "name": "Kimi K2.5"
          }
        ]
      },
      "kimi-code": {
        "baseUrl": "https://api.kimi.com/coding/v1",
        "apiKey": "${KIMICODE_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "kimi-for-coding",
            "name": "Kimi For Coding"
          }
        ]
      }
    }
  }
}

接入其它兼容 OpenAI 接口的模型,方式差不多。
重启:

openclaw gateway stop
openclaw gateway start

配置连接飞书

打开飞书应用管理后台,添加应用能力,选择机器人。

1315495-20260131164606867-1235744726
配置权限管理,把消息与群组的权限都开通。

1315495-20260131164606565-707707860
配置事件和回调,使用长连接,并且添加消息相关的事件。

1315495-20260131164607010-1852271788

1315495-20260131164605937-426452100
执行配置命令 OpenClaw:

openclaw configure

选择 Channels。

1315495-20260131164606150-528867752

1315495-20260131164606173-1504832911
按要求填入飞书的应用 id 和密钥,在飞书里面可以给机器人发送消息。

1315495-20260131164605317-1043045340

全是干货-通过学AI技术实现人生进阶教程 Youtube同步更新查看

欢迎 Star 收藏,持续关注 AI Agent 领域发展!🚀