OpenClaw AI 助手 Docker Compose 一键部署文档（可下载）

一、文档说明

本文档为 OpenClaw AI 助手的 Docker Compose 一键部署完整手册，包含目录结构、核心配置文件、快速上手步骤、常用运维命令及问题排查，适配新手使用，所有配置文件可直接复制落地，部署完成后可实现多平台（Telegram/Web）聊天交互及基础 AI 技能调用。

适用环境：Docker 20.10+、Docker Compose v2+，支持 Linux（Ubuntu 22.04+ 推荐）/ macOS / Windows（WSL2）。

二、部署目录结构

先按以下目录结构创建文件夹（确保文件层级正确，避免部署失败）：

plain 复制代码

openclaw-deploy/          # 主部署目录（可自定义名称）
├── docker-compose.yml    # 核心部署配置文件（必选）
├── config.yaml           # OpenClaw 核心配置文件（必选）
├── gateway-config.yaml   # 网关配置文件（必选）
└── data/                 # 数据存储目录（自动生成，无需手动创建）

三、核心配置文件（可直接复制使用）

3.1 docker-compose.yml（核心部署文件）

作用：定义容器服务、网络、数据卷，实现核心服务与网关服务的隔离部署，自带资源限制和自动重启配置。

yaml 复制代码

# OpenClaw AI 助手 Docker Compose 配置
# 版本适配 Docker Compose v2+
version: '3.8'

# 定义网络（隔离容器通信，避免端口冲突）
networks:
  openclaw-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16  # 自定义子网，避免与其他容器网络冲突

# 定义数据卷（持久化存储日志、文件、缓存等数据，防止容器删除后数据丢失）
volumes:
  openclaw-data:  # 主数据存储卷
  openclaw-config:  # 配置文件备份卷

services:
  # OpenClaw 核心服务（负责 AI 推理、技能调度，核心中枢）
  openclaw-core:
    # 优先使用官方镜像，若无官方镜像则自动构建（兼容本地开发场景）
    image: openclaw/core:latest
    build:
      context: .
      dockerfile: Dockerfile.core  # 备用构建文件（可选，无需修改）
    container_name: openclaw-core  # 容器名称，便于后续运维
    restart: always  # 容器异常时自动重启，保证服务稳定性
    environment:
      - TZ=Asia/Shanghai  # 时区配置，避免日志时间错乱
      - PYTHONUNBUFFERED=1  # 实时输出日志，便于排查问题
    volumes:
      - ./config.yaml:/app/config.yaml:ro  # 只读挂载核心配置，防止误修改
      - openclaw-data:/app/data  # 持久化挂载数据目录
      - openclaw-config:/app/config-backup  # 配置文件自动备份
    networks:
      - openclaw-network
    # 资源限制（避免占用过多服务器资源，可根据服务器配置调整）
    deploy:
      resources:
        limits:
          cpus: '1'  # 限制使用 1 个 CPU 核心
          memory: 2G  # 限制使用 2G 内存

  # OpenClaw 网关服务（负责多平台聊天接口对接，消息收发）
  openclaw-gateway:
    image: openclaw/gateway:latest
    container_name: openclaw-gateway
    restart: always
    ports:
      - "8080:8080"  # Web 聊天界面端口（外部可访问）
      - "8081:8081"  # 网关与核心服务内部通信端口
    environment:
      - TZ=Asia/Shanghai
      - CORE_SERVICE_HOST=openclaw-core  # 指向核心服务容器，自动解析地址
    volumes:
      - ./gateway-config.yaml:/app/gateway-config.yaml:ro  # 只读挂载网关配置
      - openclaw-data:/app/data  # 共享数据目录，与核心服务同步
    networks:
      - openclaw-network
    # 依赖核心服务启动（避免网关先启动导致连接失败）
    depends_on:
      - openclaw-core
    deploy:
      resources:
        limits:
          cpus: '0.5'  # 限制使用 0.5 个 CPU 核心
          memory: 1G  # 限制使用 1G 内存

3.2 config.yaml（OpenClaw 核心配置）

作用：配置 AI 模型、技能开关，所有必填项已标注「必改」，新手只需替换密钥即可使用。

yaml 复制代码

# ==================== 核心 LLM 配置（必改）====================
llm:
  # 模型提供商：可选值（openai/qwen/claude/ernie/chatglm）
  provider: "openai"
  # 替换为你的大模型 API Key（必填，否则无法调用 AI 能力）
  api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  # 模型名称（根据提供商调整，示例为 OpenAI GPT-3.5）
  model: "gpt-3.5-turbo"
  # 国内模型需修改此地址（示例：通义千问地址 https://dashscope.aliyuncs.com/compatible-mode/v1）
  base_url: "https://api.openai.com/v1"
  # 单次回复最大令牌数（新手建议 1000-2000，平衡响应速度和回复长度）
  max_tokens: 1500
  # 随机性（0-1，越小越精准，越大越有创意，新手建议 0.6-0.8）
  temperature: 0.6

# ==================== 技能配置（按需开启）====================
skills:
  web_browser: true        # 网页浏览能力（开启后可让 AI 访问网页）
  file_system: true        # 文件操作能力（仅能访问 data 目录，安全隔离）
  search: false            # 搜索引擎能力（开启需配置下方 serpapi_key）
  automation: false        # 自动化脚本能力（新手建议先关闭，避免配置复杂）
  api_call: false          # 第三方 API 调用能力
  device_control: false    # 设备控制能力（需额外对接智能家居 API）
  # serpapi_key: "你的SerpAPI Key"  # 开启 search 技能时必填，替换为实际密钥

# ==================== 服务基础配置（无需修改）====================
service:
  host: "0.0.0.0"          # 监听所有网络地址，允许容器外部访问
  port: 8000               # 核心服务端口（与网关配置一致，无需修改）
  log_level: "INFO"        # 日志级别：DEBUG（详细）/INFO（正常）/WARN（警告）/ERROR（错误）
  log_file: "/app/data/openclaw-core.log"  # 日志存储路径，便于后续排查问题

3.3 gateway-config.yaml（网关配置）

作用：配置多平台聊天接口（Telegram/QQ/飞书/Web），新手优先配置 Telegram 和 Web 接口，快速完成测试。

yaml 复制代码

# ==================== 多平台网关配置（必改）====================
gateways:
  # Telegram 机器人（新手首选，配置最简单，易测试）
  telegram:
    enabled: true                          # 是否开启 Telegram 接口（建议开启）
    bot_token: "123456:ABC-DEF1234ghIkl"   # 替换为你的 Telegram Bot Token（必填）
    webhook: false                         # 本地测试用轮询模式，公网部署可改为 true
    webhook_url: ""                        # 公网地址（开启 webhook 时填写，本地测试留空）
  
  # QQ 机器人（需额外配置 go-cqhttp，新手建议先跳过）
  qq:
    enabled: false
    qq_account: 12345678                   # 你的 QQ 账号（开启后填写）
    ws_url: "ws://127.0.0.1:6700"          # go-cqhttp 服务地址（需提前部署）
  
  # 飞书机器人（需在飞书开放平台创建应用，新手可后续尝试）
  feishu:
    enabled: false
    app_id: "cli_xxxxxxxxxxxxxx"           # 飞书 App ID（开启后填写）
    app_secret: "xxxxxxxxxxxxxxxxxxxxxx"   # 飞书 App Secret（开启后填写）
  
  # Web 聊天界面（默认开启，无需额外配置，方便本地测试）
  webchat:
    enabled: true
    host: "0.0.0.0"
    port: 8080

# ==================== 网关与核心通信配置（无需修改）====================
core:
  host: "openclaw-core"    # Docker 内部容器名称，自动解析地址，无需修改
  port: 8000               # 核心服务端口，与核心配置一致
  timeout: 30              # 通信超时时间（秒），避免长时间等待

四、快速上手步骤（新手友好）

按照以下步骤操作，无需复杂命令，一键完成部署：

4.1 前置准备

安装 Docker 和 Docker Compose：确保已安装 Docker（20.10+）和 Docker Compose（v2+），可通过 docker -v 和 docker compose -v 命令验证是否安装成功。
准备密钥：提前获取 LLM API Key（如 OpenAI、通义千问）、Telegram Bot Token（创建方法见下文补充）。

4.2 部署操作

创建部署目录：新建 openclaw-deploy 文件夹（可自定义名称），将上述 3 个配置文件（docker-compose.yml、config.yaml、gateway-config.yaml）放入该文件夹。
填写密钥（必做）：
- 打开 config.yaml，替换 llm.api_key 为你的大模型 API Key；
- 打开 gateway-config.yaml，替换 telegram.bot_token为你的 Telegram Bot Token。
启动服务：

`# 进入部署目录（替换为你的实际目录路径）

cd openclaw-deploy

启动所有服务（后台运行，首次启动会自动拉取镜像，稍等3-5分钟）

docker-compose up -d

查看启动日志（确认服务无报错，出现 "OpenClaw AI Core started successfully" 即正常）

docker-compose logs -f`

4.3 验证部署结果

Telegram 测试：打开 Telegram，找到你的 Bot，发送 /start，若能收到 AI 回复，说明核心服务与 Telegram 网关正常。
Web 聊天测试：打开浏览器，访问 http://服务器IP:8080（本地测试可访问 http://localhost:8080），打开聊天界面发送消息，能收到回复即 Web 网关正常。
容器状态检查：执行 docker-compose ps，若两个容器（openclaw-core、openclaw-gateway）的状态均为 Up，说明部署成功。

五、常用运维命令

后续维护服务时，可使用以下命令（均在部署目录下执行）：

操作目的	命令	说明
启动所有服务	`docker-compose up -d`	后台启动，不占用终端
停止所有服务	`docker-compose down`	停止并删除容器，数据卷（data）保留
重启所有服务	`docker-compose restart`	修改配置后需执行，使配置生效
查看核心服务日志	`docker-compose logs -f openclaw-core`	排查 AI 核心相关报错
查看网关服务日志	`docker-compose logs -f openclaw-gateway`	排查聊天接口相关报错
查看容器状态	`docker-compose ps`	确认容器是否正常运行
删除容器+数据（谨慎）	`docker-compose down -v`	彻底删除容器和数据卷，适用于重新部署

六、补充说明

6.1 Telegram Bot Token 获取方法

打开 Telegram，搜索 @BotFather（官方机器人）；
发送 /newbot，按提示设置 Bot 名称（如 OpenClawBot）和用户名（需以 bot 结尾，如 OpenClaw_Ai_Bot）；
生成成功后，会收到包含 Bot Token 的消息，复制该 Token 填入 gateway-config.yaml 即可。

6.2 国内模型配置示例（通义千问）

若使用国内大模型（如通义千问），修改 config.yaml 中的 llm 部分：

yaml 复制代码

llm:
  provider: "qwen"
  api_key: "你的通义千问API Key"  # 从通义千问开放平台获取
  model: "qwen-turbo"
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"

6.3 常见问题排查

容器启动失败：检查密钥是否填写正确（尤其是 API Key、Bot Token），执行 docker-compose logs 查看具体报错，优先排查网络问题（如无法访问 LLM 服务器）。
Web 页面无法访问：确认端口 8080 未被占用，可修改 docker-compose.yml 中的端口映射（如 8082:8080），再重启服务。
AI 不回复：检查核心服务日志，确认 LLM API Key 有效，且模型地址（base_url）配置正确。
技能调用失败：确认对应技能在 config.yaml 中已开启（如 web_browser: true），若需 API 密钥（如 SerpAPI），需填写完整。

七、后续扩展

部署成功后，可参考以下方向扩展功能：

开启高级技能：在 config.yaml 中开启 search、automation 等技能，填写对应 API 密钥即可使用。
添加多平台接口：在 gateway-config.yaml 中开启 QQ、飞书接口，配置对应密钥和服务地址。
容器化优化：添加日志监控（Prometheus + Grafana）、数据备份策略，提升服务稳定性。
自定义技能：编写技能插件，接入专属业务能力（如本地数据库查询、自定义脚本执行）。

八、文档说明

本文档可直接复制保存为 .md 文件（Markdown 格式），下载后可离线查看、编辑；所有配置文件可直接复制到对应目录，替换占位符后即可使用，无需额外修改。

若部署过程中遇到任何问题，可查看日志排查，或提供报错信息寻求技术支持。