Docker Compose + 飞书部署指南
本指南介绍如何使用 Docker Compose 部署 OpenClaw 网关，并配置飞书机器人通道。适用于需要容器化部署、对接飞书（或 Lark）的场景。
前置条件
- Docker & Docker Compose v2 已安装（Docker Desktop 或 Docker Engine）
- Node.js >= 22（如需本地运行 CLI 工具）
- 飞书/Lark 账号，可访问 飞书开放平台
- 飞书插件：飞书是 OpenClaw 的插件，需要单独安装（见下方第 1 步）
- AI 模型凭据：您的 API Token 和 Base URL（如 Anthropic、或兼容 Anthropic Messages API 的自定义端点）
快速开始
按照以下 7 步完成部署。每一步的详细说明请参阅对应的链接文档。
第 1 步：安装飞书插件
飞书通道以插件形式提供，必须先安装：
openclaw plugins install @openclaw/feishuDocker 用户：如果使用预构建镜像
ghcr.io/openclaw/openclaw:latest，该插件已预装，可跳过此步。如果使用自行构建的镜像，请确保插件已包含在镜像中。
第 2 步：创建项目目录
mkdir openclaw-feishu
cd openclaw-feishu创建 .env 文件存放敏感配置：
# .env
# 网关安全
OPENCLAW_GATEWAY_TOKEN=your-secure-gateway-token
# 飞书凭据（第 3 步获取后填入）
FEISHU_APP_ID=
FEISHU_APP_SECRET=
# 自定义模型提供商（按需修改）
ANTHROPIC_AUTH_TOKEN=your_api_token_here
ANTHROPIC_BASE_URL=https://api.anthropic.com安全提示：请将
.env加入.gitignore，切勿提交到版本控制。生成令牌：在 macOS 或 Linux 上，可使用以下命令生成安全的随机令牌：
bashopenssl rand -base64 32
第 3 步：创建飞书应用
在飞书开放平台创建企业自建应用，获取 App ID 和 App Secret，配置权限并启用机器人能力。
详细步骤请参阅 飞书应用配置详解。
第 4 步：编写 OpenClaw 配置
在 openclaw-data/ 目录下创建 openclaw.json 配置文件：
mkdir -p openclaw-data{
"agents": {
"defaults": {
"workspace": "/home/node/.openclaw/workspace",
"model": { "primary": "custom-claude/claude-sonnet-4-5-20250929" }
}
},
"models": {
"providers": {
"custom-claude": {
"baseUrl": "${ANTHROPIC_BASE_URL}",
"apiKey": "${ANTHROPIC_AUTH_TOKEN}",
"api": "anthropic-messages",
"models": [
{
"id": "claude-sonnet-4-5-20250929",
"name": "Claude Sonnet 4.5",
"contextWindow": 200000,
"maxTokens": 4096
}
]
}
}
},
"channels": {
"feishu": {
"enabled": true,
"domain": "feishu",
"accounts": {
"main": {
"appId": "${FEISHU_APP_ID}",
"appSecret": "${FEISHU_APP_SECRET}",
"botName": "OpenClaw"
}
},
"dmPolicy": "pairing",
"groupPolicy": "open"
}
},
"gateway": {
"mode": "local",
"port": 18789,
"auth": { "token": "${OPENCLAW_GATEWAY_TOKEN}" }
}
}模型 ID：自定义端点通常需要完整的带日期后缀的模型 ID（如
claude-sonnet-4-5-20250929），短别名（如claude-3-5-sonnet）可能会返回 422 错误。请根据您的端点支持的模型 ID 进行修改。Lark 国际版用户请将
"domain"改为"lark"。
完整配置说明请参阅 配置参考与故障排除。
第 5 步：编写 Docker Compose
创建 docker-compose.yml：
services:
openclaw:
image: ghcr.io/openclaw/openclaw:latest
container_name: openclaw_feishu
restart: unless-stopped
network_mode: host
env_file:
- .env
volumes:
# 整个 .openclaw 目录（配置文件 + 持久化数据）
- ./openclaw-data:/home/node/.openclaw为什么使用
network_mode: host？ OpenClaw 网关绑定到容器内的127.0.0.1。标准 Docker 端口映射通过桥接网络转发流量，网关会因来源 IP 不是 localhost 而拒绝连接。network_mode: host让容器直接共享宿主机网络栈，从而正常访问。macOS 用户：需要在 Docker Desktop 中启用 "Enable host networking"（设置 → 资源 → 网络）。
为什么挂载整个目录？ 网关运行时需要在
.openclaw目录下创建多个子目录（identity/、credentials/、canvas/等）。单独挂载文件会导致权限错误（EACCES、EBUSY），因为容器无法在挂载点旁创建临时文件。权限注意：Docker 镜像默认以
node用户（uid 1000）运行。如在 Linux 上遇到权限问题：bashsudo chown -R 1000:1000 ./openclaw-data
第 6 步：启动并配置事件订阅
docker compose up -d
docker compose logs -f等待日志中出现 [gateway] listening，表示网关已就绪。
⚠️ 重要：必须先确保容器已启动且网关正在运行，然后再去飞书开放平台配置事件订阅。如果网关未运行，长连接设置将无法保存。
[feishu] connected将在下方事件订阅配置完成并发布应用后出现。
回到飞书开放平台，配置事件订阅：
- 进入 事件订阅
- 选择 使用长连接接收事件（WebSocket）— 无需公网 webhook URL
- 添加事件：
im.message.receive_v1 - 创建版本并发布应用
详细步骤请参阅 飞书应用配置详解 — 事件订阅。
第 7 步：配对机器人
- 在飞书中找到您的机器人，发送一条消息（如 "你好"）
- 机器人会回复一个配对码（如
123-456） - 通过 CLI 批准配对：
docker compose exec openclaw openclaw pairing approve feishu <CODE>如果
openclaw命令未找到，请使用以下替代命令：bashdocker compose exec openclaw node dist/index.js pairing approve feishu <CODE>
- 配对完成后，机器人即可正常响应消息
常见操作
重启服务
docker compose restart更新镜像
docker compose pull && docker compose up -d查看配对列表
docker compose exec openclaw openclaw pairing list feishu
# 或：docker compose exec openclaw node dist/index.js pairing list feishu访问控制 UI
在浏览器中打开 http://127.0.0.1:18789/?token=<your-token>（将 <your-token> 替换为 .env 中的 OPENCLAW_GATEWAY_TOKEN 值）。
检查健康状态
docker compose exec openclaw node dist/index.js health --token "<your-gateway-token>"请将
<your-gateway-token>替换为您在.env中设置的OPENCLAW_GATEWAY_TOKEN值。$OPENCLAW_GATEWAY_TOKEN由主机 shell 解析，如果未在主机环境中导出该变量，需手动填入 token 值。