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

石工记2026-03-12 11:52

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 前置准备

  1. 安装 Docker 和 Docker Compose：确保已安装 Docker（20.10+）和 Docker Compose（v2+），可通过 docker -v 和 docker compose -v 命令验证是否安装成功。

  2. 准备密钥：提前获取 LLM API Key（如 OpenAI、通义千问）、Telegram Bot Token（创建方法见下文补充）。

4.2 部署操作

  1. 创建部署目录：新建 openclaw-deploy 文件夹（可自定义名称），将上述 3 个配置文件（docker-compose.yml、config.yaml、gateway-config.yaml）放入该文件夹。

  2. 填写密钥（必做）：

    • 打开 config.yaml，替换 llm.api_key 为你的大模型 API Key；

    • 打开 gateway-config.yaml，替换 telegram.bot_token为你的 Telegram Bot Token。

  3. 启动服务：

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

    cd openclaw-deploy

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

docker-compose up -d

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

docker-compose logs -f`

4.3 验证部署结果

  1. Telegram 测试：打开 Telegram，找到你的 Bot，发送 /start，若能收到 AI 回复，说明核心服务与 Telegram 网关正常。

  2. Web 聊天测试：打开浏览器，访问 http://服务器IP:8080（本地测试可访问 http://localhost:8080），打开聊天界面发送消息，能收到回复即 Web 网关正常。

  3. 容器状态检查：执行 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 获取方法

  1. 打开 Telegram，搜索 @BotFather（官方机器人）；

  2. 发送 /newbot，按提示设置 Bot 名称（如 OpenClawBot）和用户名（需以 bot 结尾，如 OpenClaw_Ai_Bot）；

  3. 生成成功后，会收到包含 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），需填写完整。

七、后续扩展

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

  1. 开启高级技能：在 config.yaml 中开启 search、automation 等技能，填写对应 API 密钥即可使用。

  2. 添加多平台接口：在 gateway-config.yaml 中开启 QQ、飞书接口，配置对应密钥和服务地址。

  3. 容器化优化：添加日志监控（Prometheus + Grafana）、数据备份策略，提升服务稳定性。

  4. 自定义技能：编写技能插件，接入专属业务能力（如本地数据库查询、自定义脚本执行）。

八、文档说明

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

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

相关推荐
格林威2 小时前
Halcon vs OpenCV 速度对比（表格）
人工智能·数码相机·opencv·机器学习·计算机视觉·视觉检测·halcon
WwW.-.2 小时前
OpenClaw 技术解析：多渠道 AI Gateway 如何连接消息、Agent 与远程节点
网络·人工智能·gateway
不如语冰2 小时前
openclaw安装使用教程，飞书配置，skills简介
人工智能·飞书·skills·openclaw
maotou5262 小时前
Centos7安装docker+redis+pgsql
redis·docker·容器
雷焰财经2 小时前
智能合约赋能与全球实践：宇信科技绘制银行数字人民币能力建设新蓝图
人工智能·科技·金融·智能合约
飞Link2 小时前
终结序列建模：Transformer 架构深度解析与实战指南
人工智能·python·深度学习·算法·transformer
青瓷程序设计2 小时前
基于深度学习的【动物识别】系统实现~Python+人工智能+图像识别+算法模型
人工智能·python·深度学习
AC赳赳老秦2 小时前
2026 AI原生工具链升级：DeepSeek与AI原生IDE深度联动，重塑开发效率新高度
大数据·ide·人工智能·web3·去中心化·ai-native·deepseek
大傻^2 小时前
【OpenClaw -01】OpenClaw 安装部署指南：npm、Docker 与源码三种模式详解
前端·docker·npm
热门推荐
01GitHub 镜像站点02OpenClaw 使用和管理 MCP 完全指南03本地部署 OpenClaw + DeepSeek-R1 完全指南04得物前端部门，没了05OpenClaw 连接飞书完整指南：插件安装、配置与踩坑记录06OpenClaw 飞书机器人不回复消息？3 小时踩坑总结07Window 10部署openclaw报错node.exe : npm error code 12808OpenClaw macOS 完整安装与本地模型配置教程（实战版）09npm-error code 128问题解决方法10OpenClaw 接入 QQ Bot 完整实践指南