📝 前言

在本地开发环境中部署属于自己的 AI 助理，能够极大地提升研发效率。本文将详细记录在 WSL (Ubuntu) + Docker 环境下，通过 OpenClaw 网关将 Qwen (通义千问) 大模型无缝接入飞书机器人的全过程。

整个部署过程主要解决四个核心痛点：

1. Docker 挂载目录权限导致的无限重启。

2. 飞书开放平台“长连接与事件订阅”的死循环陷阱。

3. OpenClaw 本地网关的 Web UI 跨域安全拦截。

4. 容器化应用的日常生命周期管理。

---

🛠️ 第一部分：飞书开放平台“打地基”

⚠️ 踩坑警告：飞书的接口有极严格的版本校验逻辑。如果不在配置前发布一个基础版本，后续本地程序请求建立 WebSocket 长连接时会直接报 400 Bad Request 被踢出。

1. 创建应用与开启机器人

   • 登录 飞书开发者后台，创建企业自建应用。

   • 在左侧菜单找到 添加应用能力，开启 机器人。

2. 配置核心权限

   • 进入 开发配置 -> 权限管理，搜索并开通以下 4 个基础权限：

     • im:message:receive (接收消息)

     • im:message.p2p_msg:readonly (读取单聊)

     • im:message.group_msg:readonly (读取群聊)

     • im:message:send (发送消息)

3. 获取应用凭证

   • 进入 凭证与基础信息，保存你的 App ID (cli_开头) 和 App Secret。

4. 关键动作：发布初始版本

   • 不要急着去配置事件订阅！

   • 直接前往左侧菜单的 版本管理与发布 -> 创建版本 -> 申请发布。

   • 必须确保应用状态变为 “已上线”，否则本地服务无法成功握手。

---

💻 第二部分：本地环境初始化与权限修复

⚠️ 踩坑警告：OpenClaw 容器默认以非 root 的 node 用户运行。如果宿主机的配置目录权限不足，容器会因为无法写入 openclaw.json 而进入 Restarting 无限重启死循环。

1. 拉取项目代码

Bash

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

1. 打通挂载目录权限 强行赋予本地配置目录最高读写权限，为容器运行扫清障碍：

Bash

mkdir -p ~/.openclaw/logs
chmod -R 777 ~/.openclaw

---

⚙️ 第三部分：核心配置与大模型授权

不要直接使用 docker compose up 启动空配置的容器（会报 Gateway start blocked）。我们需要通过临时容器呼出交互式配置菜单。

1. 启动交互式向导

Bash

docker compose run -it --rm openclaw-gateway node openclaw.mjs configure

1. 配置关键节点

   • 部署模式：务必选择 Local gateway (this machine)。

   • 大模型接入：在 Model 列表中选择 Qwen，系统会弹出 OAuth 授权链接，在浏览器打开并输入终端提供的 Pairing Code，完成大模型大脑的绑定。

   • 通信渠道 (Channels)：

     • 选择 Feishu / Lark。

     • 依次填入之前保存的 App ID 和 App Secret。

     • 当询问 Verification Token 和 Encrypt Key 时，直接按回车留空跳过。

     • 群聊策略选择 Open（被@回复），私聊策略选择 No（稍后通过配对码手动认证）。

   • 一路回车保存，直到终端提示 Saved 并退出向导。

---

🔓 第四部分：突破跨域安全锁

⚠️ 踩坑警告：在 Docker 环境下，网关的 Web UI 绑定在 0.0.0.0。OpenClaw 的安全机制会拦截非本地环回地址的访问，报出 non-loopback Control UI requires allowedOrigins 错误并拒绝启动服务。

我们需要向配置文件中强行注入解除限制的参数。直接在终端执行以下 Node.js 单行脚本打补丁：

Bash

docker compose run -it --rm openclaw-gateway node -e "const fs=require('fs');const p='/home/node/.openclaw/openclaw.json';const c=JSON.parse(fs.readFileSync(p));c.gateway=c.gateway||{};c.gateway.controlUi=c.gateway.controlUi||{};c.gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true;fs.writeFileSync(p,JSON.stringify(c,null,2));console.log('✅ 安全限制已解除！');"

---

🚀 第五部分：建立长连接与飞书闭环

1. 正式启动后台服务 此时配置文件已完美就绪，执行启动命令：

Bash

docker compose up -d --force-recreate

启动后，本地网关会主动向飞书发起 WebSocket 长连接。

1. 飞书后台完成事件闭环

   • 回到飞书开发者后台，进入 事件与回调。刷新页面，此时上方应显示绿色的 已连接。

   • 点击 添加事件，搜索并勾选 接收消息 (im.message.receive_v1)。

   • 最后一步：前往 版本管理与发布，再次创建一个新版本并 申请发布。

   • 注：只有发布新版本，刚刚添加的接收消息事件才会生效，机器人才能监听到你的消息。

---

🔑 第六部分：终端配对认主仪式

OpenClaw 内置了极佳的防蹭网机制，首次私聊必须经过控制台授权。

1. 触发配懂码 打开飞书客户端，搜索并向你的机器人发送第一条消息（如 hello）。它会回复一段英文拒绝信，并附带一个 8 位配对码：

Pairing code: 6MAM6LJJ

1. 终端授权验证 复制该配对码，在 Linux 终端执行以下命令进行认证（替换为你自己的配对码）：

Bash

docker exec -it openclaw-openclaw-gateway-1 node openclaw.mjs pairing approve feishu 6MAM6LJJ

验证通过后，再次在飞书向机器人发消息，它就会调用 Qwen 大模型为你解答问题了！🎉

---

🛑 第七部分：日常运维与服务管理

部署完成后，你可以像控制家用电器一样，通过 Docker 指令轻松管理机器人的生命周期。

注意：执行以下命令前，请确保终端已 cd 进入你的 openclaw 部署目录。

1. 开启机器人（上班） 让机器人在后台静默运行并保持待命状态：

Bash

docker compose up -d

2. 停止机器人（下班/关机） 如果你想让它停止工作释放系统资源，执行该命令（配置和数据均会安全保留）：

Bash

docker compose down

3. 重启机器人（排障） 如果遇到网络波动导致飞书断连，或 API 响应卡顿，无需先关再开，直接执行一键重启恢复最佳状态：

Bash

docker compose restart

---

💡 总结

通过 WSL 和 Docker 实现了轻量化的本地部署，整个架构无需公网 IP 即可通过 WebSocket 完美穿透内网响应飞书消息。借助容器化管理，服务的启动、停止与更新都变得异常简单。现在，你的专属 AI 研发助理已经完全就位，尽情享受自动化带来的效率飞跃吧！