郑工长

AI沙盒：OpenClaw Docker 安装与飞书配置指南

发布于 2026年2月12日 | 分类: AI随心分享

AI沙盒：OpenClaw Docker 安装与飞书配置指南

OpenClaw Docker 安装与飞书配置指南

本文档详细介绍如何通过 Docker 安装 OpenClaw，并配置飞书机器人进行对话。

目录

  1. 环境要求
  2. 安装 OpenClaw
  3. 配置控制面板
  4. 安装飞书插件
  5. 配置飞书渠道
  6. 测试验证
  7. 常见问题

环境要求

  • Docker Desktop 或 Docker Engine + Docker Compose v2
  • 充足的磁盘空间
  • 飞书账号（用于配置机器人）

安装 OpenClaw

1. 克隆项目

git clone https://github.com/openclaw/openclaw.git
cd openclaw

2. 运行安装脚本

./docker-setup.sh

脚本会自动完成：

  • 构建 Gateway 网关镜像
  • 运行交互式新手引导向导
  • 生成网关令牌并写入 .env
  • 通过 Docker Compose 启动网关

3. 配置向导选项

在向导中选择：

  • 理解风险提示：选择 Yes
  • Onboarding 模式：选择 QuickStart
  • Install Feishu plugin：选择跳过（后续手动安装）
  • 配置技能：选择 Skip for now
  • 配置 API Key：选择 No（使用默认配置）
  • 启用 Hooks：选择 Skip for now

4. 解决配对问题

如果在控制面板中看到 disconnected (1008): pairing required，需要修改配置：

编辑 ~/.openclaw/openclaw.json，添加 allowInsecureAuth：

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "你的令牌"
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}

重启网关：

docker compose restart openclaw-gateway

配置控制面板

1. 访问控制面板

在浏览器中打开：

http://127.0.0.1:18789/#token=你的令牌

2. 配置 Gateway 连接

在控制面板的 Overview 页面：

  • WebSocket URL: ws://127.0.0.1:18789
  • Gateway Token: 填入 .env 文件中的 OPENCLAW_GATEWAY_TOKEN
  • 点击 Connect 按钮

如果 Health 显示 OK，表示连接成功。

3. 开始对话

点击左侧 Chat，发送消息测试：

  • 输入：你好
  • 或输入：/status 查看状态

安装飞书插件

1. 从本地安装插件

由于 npm 安装可能遇到依赖问题，建议从本地源码安装：

docker run --rm \
  -v "$PWD/extensions/feishu:/plugin" \
  -v "$HOME/.openclaw/extensions:/output" \
  -w /plugin \
  node:22-alpine \
  sh -c 'cp -r /plugin /output/feishu && cd /output/feishu && npm install --omit=dev'

2. 启用插件

编辑 ~/.openclaw/openclaw.json，在 plugins.entries 中添加：

{
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
    }
  }
}

3. 重启网关

docker compose restart openclaw-gateway

验证插件是否加载：

docker compose logs --tail 20 openclaw-gateway | grep feishu

应该看到 feishu[main]: WebSocket client started。

配置飞书渠道

1. 创建飞书应用

  1. 访问 飞书开放平台
  2. 点击 创建企业自建应用
  3. 填写应用名称（如 "OpenClaw助手"）
  4. 在 凭证与基础信息 页面获取：
    • App ID（格式如 cli_xxx）
    • App Secret

2. 配置应用权限

在 权限管理 页面，添加以下权限：

  • im:message:send_as_bot（以机器人身份发送消息）
  • im:message:readonly（读取消息）
  • im:chat:readonly（读取群组信息）
  • contact:contact.base:readonly（读取联系人基础信息）
  • contact:contact:access_as_app（以应用身份访问通讯录）

3. 启用机器人能力

  1. 在 应用能力 > 机器人 页面开启机器人能力
  2. 配置机器人名称

4. 配置事件订阅

在 事件订阅 页面：

  1. 选择 使用长连接接收事件（WebSocket 模式）
  2. 添加事件：im.message.receive_v1（接收消息）

5. 发布应用

在 版本管理与发布 页面：

  1. 创建版本
  2. 提交审核并发布
  3. 等待管理员审批（企业自建应用通常自动通过）

6. 配置 OpenClaw

编辑 ~/.openclaw/openclaw.json，添加飞书渠道配置：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "botName": "OpenClaw助手"
        }
      }
    }
  }
}

注意：如果是 Lark（国际版），需添加 domain: "lark"。

7. 重启网关

docker compose restart openclaw-gateway

测试验证

1. 发送测试消息

在飞书中搜索你的机器人名称，发送一条消息：

你好

2. 检查日志

查看是否收到消息：

docker compose logs -f openclaw-gateway 2>&1 | grep -E "(feishu|received|dispatch)"

应该看到类似：

feishu[main]: received message from ou_xxx in oc_xxx (p2p)
feishu[main]: dispatching to agent

3. 设定机器人身份

机器人第一次会询问身份设定，你可以回复：

你就叫"郑小猪"，性格：友好/专业/耐心，主要语言：中文

4. 功能测试

试试以下功能：

  • 基础对话："你好"、"今天天气怎么样"
  • 系统命令："执行命令：date"、"查看系统信息"
  • 文件操作："列出当前目录的文件"
  • 状态查看：发送 /status、发送 /usage tokens

常见问题

1. 配对错误 (1008)

问题：控制面板显示 disconnected (1008): pairing required

解决：在 openclaw.json 中添加：

{
  "gateway": {
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}

2. 飞书插件加载失败

问题：日志显示 Cannot find module '@sinclair/typebox'

解决：从本地源码安装插件（见第4节），而非 npm 安装。

3. 飞书权限错误

问题：日志显示 Access denied. One of the following scopes is required

解决：在飞书开放平台添加缺少的权限，特别是联系人相关权限。

4. 无法接收消息

问题：发送消息没有回复

检查清单：

  1. 检查网关是否运行：docker compose ps
  2. 检查日志是否有错误：docker compose logs openclaw-gateway
  3. 检查事件订阅是否配置正确
  4. 检查应用是否已发布并审批通过

5. 获取新的仪表板链接

如果忘记令牌，可以获取新的链接：

docker compose run --rm openclaw-cli dashboard --no-open

常用命令

# 查看日志
docker compose logs -f openclaw-gateway

# 重启网关
docker compose restart openclaw-gateway

# 停止服务
docker compose down

# 查看飞书配对列表
docker compose exec openclaw-gateway node dist/index.js pairing list feishu

# 批准飞书配对
docker compose exec openclaw-gateway node dist/index.js pairing approve feishu <配对码>

# 查看状态
docker compose exec openclaw-gateway node dist/index.js status

配置文件详解

重要提示：~/.openclaw/openclaw.json 是 OpenClaw 的核心配置文件，不在 Git 版本控制中。该文件位于用户主目录下，包含所有运行时配置。

文件位置

~/.openclaw/openclaw.json

主要配置项说明

1. 网关配置 (gateway)

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "你的令牌"
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}
配置项 说明 默认值
port 网关监听端口 18789
mode 运行模式 (local/remote) local
bind 绑定地址 (lan/loopback/0.0.0.0) lan
auth.mode 认证模式 (token/password) token
auth.token 访问令牌 自动生成
controlUi.allowInsecureAuth 允许无配对访问控制面板 false

2. 模型配置 (models.providers)

支持多个模型提供商：

Qwen (通义千问)

"qwen-portal": {
  "baseUrl": "https://portal.qwen.ai/v1",
  "apiKey": "qwen-oauth",
  "models": ["coder-model", "vision-model"]
}

DeepSeek

"deepseek": {
  "baseUrl": "https://api.deepseek.com/v1",
  "apiKey": "${DEEPSEEK_API_KEY}",
  "models": ["deepseek-chat"]
}

Ollama (本地模型)

"ollama": {
  "baseUrl": "http://host.docker.internal:11434/v1",
  "apiKey": "ollama",
  "models": ["qwen3:1.7b"]
}

3. 默认模型配置 (agents.defaults)

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      },
      "models": {
        "deepseek/deepseek-chat": {
          "alias": "deepseek"
        },
        "qwen-portal/coder-model": {
          "alias": "qwen"
        }
      }
    }
  }
}

切换模型命令：

  • /model deepseek - 切换到 DeepSeek
  • /model qwen - 切换到 Qwen

4. 飞书渠道配置 (channels.feishu)

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "botName": "OpenClaw助手"
        }
      }
    }
  }
}
配置项 说明
enabled 是否启用飞书渠道
dmPolicy 私聊策略 (pairing/allowlist/open)
accounts 飞书应用账号配置

5. 插件配置 (plugins)

{
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      },
      "qwen-portal-auth": {
        "enabled": true
      }
    }
  }
}

配置文件备份

由于该文件不在 Git 中，建议定期备份：

# 备份配置文件
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)

# 或使用提供的备份脚本
./backup.sh

完整配置示例

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "你的令牌"
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "botName": "OpenClaw助手"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      }
    }
  },
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
    }
  }
}

总结

通过以上步骤，你已经成功：

  1. ✅ 使用 Docker 安装并运行 OpenClaw
  2. ✅ 配置控制面板连接
  3. ✅ 安装飞书插件
  4. ✅ 配置飞书机器人渠道
  5. ✅ 通过飞书与 OpenClaw 进行对话

现在你可以随时随地通过飞书使用 OpenClaw AI 助手了！

适用系统：macOS / Linux / Windows (Docker Desktop)

相关内容

别再让 OpenClaw 失忆了！其实你缺的只是这套配置方案！

别再让 OpenClaw 失忆了！其实你缺的只是这套配置方案！

OpenClaw 平替大战：为什么大厂都在做'Claw'产品？

OpenClaw 平替大战：为什么大厂都在做'Claw'产品？

掌控未来AI：AI Agent 智能体开发框架全景指南

掌控未来AI：AI Agent 智能体开发框架全景指南

提升开发效率！在 Gemini CLI 中集成 MySQL MCP 的最佳实践

提升开发效率！在 Gemini CLI 中集成 MySQL MCP 的最佳实践

OpenClaw 实战指南：找个"临时工"处理耗时任务

OpenClaw 实战指南：找个"临时工"处理耗时任务

告别提示词工程师，你好AI“工头”：Clawdbot个人使用指南

告别提示词工程师，你好AI“工头”：Clawdbot个人使用指南