本文首发地址 https://h89.cn/archives/550.html
本文记录了一次完整的 OpenClaw 本地部署实践，涵盖 Docker 容器化、飞书对接、Nginx 反向代理、本地模型集成，以及几种常见部署路线的取舍。

什么是 OpenClaw

OpenClaw 是一个开源的个人 AI 助手框架，支持多平台接入（飞书、Telegram、Discord 等），可对接多种 AI 模型（Anthropic Claude、OpenAI、Ollama 本地模型等）。

核心特性：

  • 多通道接入（Chat Channels）
  • 多模型支持（Model Providers）
  • 设备配对认证（Device Pairing）
  • WebSocket 长连接
  • 插件生态系统

环境准备

硬件要求

  • CPU：2 核以上
  • 内存：4GB 以上
  • 存储：10GB 可用空间
  • 网络：可访问 ghcr.io（GitHub Container Registry）

软件要求

  • Docker 20.10+
  • Docker Compose v2+
  • Nginx（可选，用于反向代理）

几种部署路线怎么选

先说明一点：飞书秒搭更像替代路线，不是 OpenClaw 的另一种安装方式。如果只是想快速跑起来，优先看 Docker。

方案 优点 缺点 适用场景
Docker 部署 环境一致、迁移方便、回滚简单 需要理解 volume、network、反向代理 个人部署、家庭实验室、小团队正式运行
独立主机部署 性能开销低、调试直接、系统集成灵活 容易污染宿主机环境，升级回滚更麻烦 专用服务器、熟悉 Linux 运维的场景
独立用户隔离部署 权限边界清晰，适合多实例共存 端口、日志、证书、权限都要单独管理 一机多机器人、多团队共用一台服务器
飞书秒搭 上手快，几乎不用管运维 自定义能力受限，不是 OpenClaw 自托管替代 快速验证需求、轻量办公自动化场景

选型建议

  • 优先求稳：选 Docker。
  • 一机多实例：选独立用户隔离。
  • 追求原生可控：选独立主机部署。
  • 只想快速做飞书助手：先看飞书秒搭。

Docker 部署

以下命令默认在 Linux 服务器环境执行。

1. 创建项目目录

mkdir -p ~/openclaw/openclaw-data
cd ~/openclaw

2. 创建 docker-compose.yml

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    network_mode: host
    env_file:
      - .env
    volumes:
      - ./openclaw-data:/home/node/.openclaw

关键配置说明：

  • network_mode: host：网关绑定 localhost 必需
  • volumes：挂载完整数据目录，避免权限错误

3. 创建 .env 环境变量

# OpenClaw Gateway Security
OPENCLAW_GATEWAY_TOKEN=your-secure-gateway-token

# Feishu Credentials
FEISHU_APP_ID=
FEISHU_APP_SECRET=

# AI Model Provider
ANTHROPIC_AUTH_TOKEN=your_api_token_here
ANTHROPIC_BASE_URL=https://api.anthropic.com

提示：使用 openssl rand -base64 32 生成强随机 token。

4. 拉取镜像并启动

docker compose pull
docker compose up -d

国内网络加速方案：
如果 ghcr.io 拉取缓慢，可使用国内镜像源：

docker pull ghcr.nju.edu.cn/openclaw/openclaw:latest
docker tag ghcr.nju.edu.cn/openclaw/openclaw:latest ghcr.io/openclaw/openclaw:latest

5. 验证部署

docker compose ps
docker compose logs --tail 20

正常日志应包含：

[feishu] feishu[main]: WebSocket client started
[ws] ws client ready

飞书对接

1. 创建飞书应用

  1. 访问 飞书开放平台
  2. 创建企业自建应用
  3. 记录 App ID 和 App Secret

2. 配置应用权限

开通以下权限：

  • im:message（发送消息）
  • im:message.receive（接收消息）
  • contact:contact.base:readonly（获取用户信息）

3. 配置事件订阅

  • 订阅方式：使用长连接接收事件（WebSocket）
  • 事件：添加 im.message.receive_v1

4. 发布应用

在飞书开放平台完成应用发布和版本审核。

5. 设备配对

当用户首次给机器人发消息时，会收到配对码：

Your Feishu user id: ou_730746a90984f9fd6437d1685909e48c
Pairing code: UN97WP7N
Ask the bot owner to approve with:
openclaw pairing approve feishu UN97WP7N

在服务器执行：

docker compose exec openclaw openclaw pairing approve feishu UN97WP7N

Nginx 反向代理

为什么需要反向代理

OpenClaw Control UI 要求 HTTPS 或 localhost 安全上下文，直接通过 HTTP 访问会被拦截。

1. 添加独立 HTTPS 端口

在 Nginx 配置中添加独立 server 块（避免子路径代理问题）：

server {
    listen 6790 ssl;
    server_name f.h89.cn;

    ssl_certificate /etc/nginx/certs/fullchain.cer;
    ssl_certificate_key /etc/nginx/certs/f.h89.cn.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://192.168.31.165:18789;
        proxy_http_version 1.1;

        proxy_set_header Host $http_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 https;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Forwarded-Port 6790;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
        proxy_connect_timeout 75s;

        proxy_buffering off;
    }
}

2. 关键配置说明

  • 独立端口：避免子路径 /openclaw/ 导致的路由问题
  • WebSocket 支持：Upgrade 和 Connection 头必需
  • 完整 Host 传递：$http_host 保留端口信息

3. 重载 Nginx

nginx -t && nginx -s reload

4. 访问地址

https://f.h89.cn:6790/?token=YOUR_GATEWAY_TOKEN

本地模型集成

使用 Ollama 本地模型

如果不想依赖外部 API，可以使用 Ollama 运行本地模型。

1. 部署 Ollama

# docker-compose.yml
services:
  ollama:
    image: ollama/ollama
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    restart: unless-stopped
    environment:
      - OLLAMA_HOST=0.0.0.0

volumes:
  ollama_data:

2. 拉取模型

curl http://localhost:11434/api/pull -d '{"name": "qwen3.5:2b"}'

3. 配置 OpenClaw 使用 Ollama

在 openclaw-data/openclaw.json 中配置：

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://192.168.31.165:11434/v1",
        "apiKey": "ollama",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5:2b",
            "name": "Qwen 3.5 2B",
            "contextWindow": 32000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/qwen3.5:2b"
      }
    }
  }
}

常见问题排查

1. 镜像拉取失败

症状：dial tcp: lookup ghcr.io: no such host

解决：使用国内镜像源

docker pull ghcr.nju.edu.cn/openclaw/openclaw:latest
docker tag ghcr.nju.edu.cn/openclaw/openclaw:latest ghcr.io/openclaw/openclaw:latest

2. 配置解析错误

症状：JSON5 parse failed: SyntaxError

解决：检查 JSON 格式，确保没有多余逗号或括号不匹配。

3. "pairing required" 错误

症状：WebSocket 连接被拒绝，提示 pairing required

原因：浏览器通过代理访问时，设备身份未批准。

解决方案：

方案 A：批准设备

docker compose exec openclaw openclaw devices list
docker compose exec openclaw openclaw devices approve <deviceId>

方案 B：禁用设备认证（仅限可信网络）

{
  "gateway": {
    "controlUi": {
      "dangerouslyDisableDeviceAuth": true
    }
  }
}

4. "control ui requires device identity" 错误

症状：HTTP 访问被拦截

原因：OpenClaw 要求 HTTPS 或 localhost 安全上下文。

解决：通过 HTTPS 代理访问，不要直接访问 http://IP:18789。

5. "unauthorized: gateway token missing" 错误

症状：WebSocket 连接失败

解决：确保 URL 中包含 token 参数

https://f.h89.cn:6790/?token=YOUR_GATEWAY_TOKEN

6. 模型 API 返回 403

症状：飞书消息收到但回复 403 错误

原因：API 密钥错误或网络被拦截。

解决：

  • 检查 ANTHROPIC_AUTH_TOKEN 是否正确
  • 如果使用国内代理，确认 ANTHROPIC_BASE_URL 配置正确
  • 或切换到本地 Ollama 模型

7. 网关绑定问题

症状：只能从 localhost 访问，无法从局域网访问

解决：配置 bind: "lan"

{
  "gateway": {
    "bind": "lan"
  }
}

8. 子路径代理问题

症状：通过 /openclaw/ 子路径访问时静态资源 401

原因：OpenClaw 前端 JS 请求路径不包含子路径前缀。

解决：使用独立端口代理根路径，避免子路径重写。

完整配置示例

以下配置更偏调试或内网使用示例；如果要长期暴露到公网，建议恢复设备认证，并收紧 allowedOrigins、trustedProxies 等配置。

docker-compose.yml

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    network_mode: host
    env_file:
      - .env
    volumes:
      - ./openclaw-data:/home/node/.openclaw

.env

OPENCLAW_GATEWAY_TOKEN=P6wCs8bnrhDwSs2
FEISHU_APP_ID=cli_a942c53935b89bc6
FEISHU_APP_SECRET=your_app_secret_here

openclaw-data/openclaw.json

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://192.168.31.165:11434/v1",
        "apiKey": "ollama",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5:2b",
            "name": "Qwen 3.5 2B",
            "contextWindow": 32000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/qwen3.5:2b"
      },
      "workspace": "/home/node/.openclaw/workspace"
    }
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "feishu",
      "accounts": {
        "main": {
          "appId": "${FEISHU_APP_ID}",
          "appSecret": "${FEISHU_APP_SECRET}"
        }
      },
      "dmPolicy": "open",
      "groupPolicy": "open",
      "connectionMode": "websocket"
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    },
    "trustedProxies": ["172.19.0.0/16", "192.168.31.0/24"],
    "controlUi": {
      "allowedOrigins": ["https://f.h89.cn:6790"],
      "dangerouslyDisableDeviceAuth": true
    }
  },
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true,
        "config": {}
      }
    }
  }
}

总结

OpenClaw 的部署过程涉及多个关键环节：

  1. Docker 部署：注意网络模式和镜像源
  2. 飞书对接：WebSocket 长连接模式最简单
  3. Nginx 代理：独立端口避免子路径问题
  4. 模型配置：支持云端 API 和本地 Ollama
  5. 认证配对：理解 token 认证与设备配对的区别

核心经验：

  • 使用独立 HTTPS 端口代理，避免子路径重写
  • 配置 dangerouslyDisableDeviceAuth 简化调试（生产环境谨慎使用）
  • 优先使用 ?token=xxx 查询参数而非 #token=xxx hash
  • 本地模型是可靠的备选方案

希望这篇实战记录能帮助你顺利部署 OpenClaw！


本文链接：OpenClaw Docker 部署实战：从零基础到飞书机器人上线 - https://h89.cn/archives/550.html

版权声明：原创文章 遵循 CC 4.0 BY-SA 版权协议，转载请附上原文链接和本声明。

标签: docker, OpenClaw, 飞书, pairing required, gateway, dangerouslyDisableDeviceAuth, Nginx

添加新评论